mapteksdk.data.primitives.attribute_key module

Keys for accessing primitive attributes consistently.

class AttributeKey(name)

Bases: object

A key for accessing attributes.

Primitive attributes can be read, edited and created using their name (a string) or using an AttributeKey object. The primary advantage of using an AttributeKey is it allows for any metadata (e.g. The unit) of the primitive attribute to be read via the properties on the AttributeKey object.

Examples

If an AttributeKey is constructed through the constructor, then it will contain no metadata and attempting to access the metadata will return None. For example:

>>> from mapteksdk.data import AttributeKey
>>> no_meta_data_key = AttributeKey("distance from object")
>>> print("Name: ", no_metadata_key.name)
>>> print("Data type: ", no_metadata_key.data_type)
>>> print("Unit: ", no_metadata_key.unit)
>>> print("Null values: ", no_metadata_key.null_values)
Name:  distance from object
Data type:  None
Unit:  None
Null values:  None

Alternatively, the metadata of an AttributeKey can be specified when it is created. This allows for creating primitive attributes with additional metadata.

>>> import ctypes
>>> import math
>>> from mapteksdk.data import AttributeKey, DistanceUnit
>>> metadata_key = AttributeKey.create_with_metadata(
...     "distance from origin",
...     # The values of the attribute must be 64 bit floating point numbers.
...     data_type=ctypes.c_double,
...     # The values are in metres.
...     unit=DistanceUnit.METRE,
...     # NaN (Not a Number) is used to represent invalid values.
...     null_values=(math.nan,)
>>> )
>>> print("Name: ", metadata_key.name)
>>> print("Data type: ", metadata_key.data_type)
>>> print("Unit: ", metadata_key.unit)
>>> print("Null values: ", metadata_key.null_values)
Name:  distance from origin
Data type:  <class 'ctypes.c_double'>
Unit:  DistanceUnit.METRE
Null values:  ('nan',)

Once an AttributeKey is created, it can be used to create a primitive attribute the same as a string. For example:

>>> point_set: PointSet
>>> point_set.point_attributes[no_metadata_key] = np.zeros(
...     (point_set.point_count,))
>>> point_set.point_attributes[metadata_key] = np.zeros(
...     (point_set.point_count,))

To read the primitive attribute, you can either use the attribute key or the name given to the attribute.

>>> point_set: PointSet
>>> # These will both read the same point attribute.
>>> _ = point_set.point_attributes[no_metadata_key]
>>> _ = point_set.point_attributes["distance from object"]

Parameters:: name (str) –

SUPPORTED_DATA_TYPES: ClassVar[set[type]] = {<class 'ctypes.c_char_p'>, <class 'ctypes.c_ubyte'>, <class 'ctypes.c_longlong'>, <class 'ctypes.c_double'>, <class 'ctypes.c_ulonglong'>, <class 'ctypes.c_byte'>, <class 'ctypes.c_short'>, <class 'ctypes.c_long'>, <class 'ctypes.c_float'>, <class 'ctypes.c_ushort'>, <class 'ctypes.c_ulong'>, <class 'ctypes.c_bool'>}: The set of supported data types for AttributeKeys.

property name: str

The name of the attribute.

This should uniquely identify the primitive attribute.

property data_type: type | None

The type of data stored by this attribute.

Attempting to assign values which cannot be converted to this type to a primitive attribute with this key will raise a ValueError.

If this is None, then values of any type can be associated with this primitive attribute.

property semantic: str | None

The semantic of the data stored by this attribute.

If this is None, the semantic is undefined.

property unit: UnsupportedUnit | DistanceUnit | AngleUnit | None

The unit this data is stored in.

If this attribute stores distances, this will be a DistanceUnit. If this attribute stores angles, this will be an AngleUnit. If this attribute stores any other data, this will be an UnsupportedUnit. If this is None, the unit is unspecified.

property null_values: tuple[str, ...] | None

Values which should be considered to mean null.

These are always stored as strings rather than the value type. They may not correspond to valid values for the primitive attribute.

If this is None, then the null values are unspecified.

to_json()

Convert the AttributeKey to JSON.

Returns:: The json string used to access this attribute.
Return type:: str

classmethod create_with_metadata(name, data_type, *, unit=None, null_values=None, semantic=None)

Create an AttributeKey with metadata.

Parameters:

name (str) – Name of the primitive attribute.
data_type (type) – Ctypes type of data stored by the attribute or int, float, bool or str. See Notes for how Python types are mapped to ctypes types. This will restrict the values in the array for this attribute to have the specified type.
unit (UnsupportedUnit | DistanceUnit | AngleUnit | None) – The unit of the data. If not specified, the unit will be unknown. Typically, if this is specified, it should be a member of the DistanceUnit or AngleUnit enums. Though other units can be represented by passing UnsupportedUnit, this is not recommended.
null_values (tuple[str, ...] | None) – Tuple of values the data should treat as null.
semantic (str | None) – By default, this will be set appropriately based on the data_type. Typically, this should be left to the default. If this is set to a semantic not recognised by the application, the application may fail to read the values.

Return type:

Self

Notes

The below table defines how Python types passed as the data_type are mapped to ctypes types:

Python type	Ctypes type
int	c_int32
float	c_double
bool	c_bool
str	c_char_p

classmethod from_json(json_string)

Create an AttributeKey from a JSON string containing the name.

Parameters:: json_string (str) – The JSON string containing the name.
Returns:: An instance of this class loaded from the string.
Return type:: Self