mapteksdk.data.objectid module

The ObjectID class.

An ObjectID uniquely references an object within a Project. Note that an ObjectID is only unique within one Project - an ObjectID of an object in one project may be the ID of a different object in a different project. Attempting to use an ObjectID once the project has been closed (or before it has been opened) will raise an error.

class ObjectID(handle=None)

Bases: Generic[T]

ObjectID used to identify and represent an object.

There is a special value an Object ID can represent called the null object ID. The null object ID is considered False and other values are considered True.

This object is generic for the purposes of typing hinting but not during run-time. It is possible for the type of the object an ObjectID represents to change or for the type hint to be incorrect. e.g. Type hinting an object id as ObjectID[Surface] only tells your code editor to provide autocomplete suggestions as if it were the ObjectID of a Surface. When the code is run, it does not check that it is the ObjectID of a Surface. To check the actual type of an ObjectID, use ObjectID.is_a() instead.

Examples

Test if an object ID is the null object ID or not.

>>> def test_object_id(object_id: ObjectID):
...     if object_id:
...         print("Object ID is not the null object ID.")
...     else:
...         print("The given object ID is null")

storage_type: alias of T_ObjectHandle

classmethod convert_from(storage_value)

Convert from the underlying value (of storage type) to this type.

This is used by the communication system.

classmethod convert_to(value)

Convert to the underlying value.

This is used by the communication system.

classmethod from_path(object_path)

Constructs an ObjectID instance from a valid object path string.

This method relies on a valid object existing in the Project at the path passed into this method.

Parameters:

object_path (str) – Path to the object to get the ID of.

Returns:

An ObjectID instance if the string was valid.

Return type:

ObjectID

Raises:

TypeError – If the object_path parameter is not a string.
ValueError – If object_path failed to convert to an ObjectID.

property handle

T_ObjectHandle representation of the Object ID.

Returns:: This handle represents the Object ID.
Return type:: T_ObjectHandle

property native_handle

Native Integer (uint64) representation of the Object ID.

Returns:: uint64 representation of the Object ID.
Return type:: int

property icon_name

The name of the icon that represents the object.

Returns:: Icon name for the object type.
Return type:: str
Raises:: TypeError – If the ObjectID refers to the null object ID.

property type_name

The type name of this object.

This name is for diagnostics purposes only. Do not use it to alter the behaviour of your code. If you wish to check if an object is of a given type, use is_a() instead.

Returns:: The name of the type of the given object.
Return type:: str
Raises:: TypeError – If the ObjectID refers to the null object ID.

See also

is_a: Check if the type of an object is the expected type.

property exists

Returns true if the object associated with this object id exists. This can be used to check if a previously existing object has been deleted or if the parameters used to create the ObjectID instance are valid and refer to an existing object.

Returns:: True if it exists; False if it no longer exists. False is also returned if ObjectID never existed.
Return type:: bool

property name

The name of the object (if one exists).

If the object is not inside a container then it won’t have a name. The name comes from its parent. If the object is inside more than one container (has multiple paths) then this is the name in the primary container. Each container that this object is in can assign it a different name.

Returns:: The name of the object.
Return type:: str
Raises:: TypeError – If the ObjectID is the null object ID.

property path

The path to the object (if one exists) in the project. If an object has multiple paths, the primary path will be returned.

Returns:: Path to the object if one exists (e.g. ‘/cad/my_object’).
Return type:: str
Raises:: TypeError – If the ObjectID is the null object ID.

property hidden

If the object is a hidden object.

Returns:: True if hidden, False if not hidden.
Return type:: bool
Raises:: TypeError – If the ObjectID is the null object ID. An object that doesn’t exist is not hidden but it is also not hidden.

property parent

The ObjectID of the primary parent of this object.

Returns:: ObjectID instance representing the parent of this object.
Return type:: ObjectID
Raises:: TypeError – If the ObjectID handle is None.

Notes

If this object is already the root, the same object will be returned. If this object has multiple parents, the primary parent will be returned.

property is_orphan

Check if object is an orphan (no parents, or all of its ancestors are either orphans or are descendants of objects that are themselves orphans).

Returns:: True if the object is an orphan or False if it is not.
Return type:: bool
Raises:: TypeError – If the ObjectID handle is None.

is_a(object_type)

Check if this object ID represents an object of the given type.

This allows for checking the type of an object without opening it.

This takes into account inheritance. For example, for a Polygon object this function will return True if object type is Polygon or Topology because Polygon is a child class of Topology.

Parameters:: object_type – The Python class to check if this object ID represents an object of this type (or any subclass of this type) or a tuple of classes to check.
Returns:: True if the object referenced by this object ID is of the type (or any subclass of) object_type otherwise False. If object_type is a tuple of types, then True if the object referenced by this object ID is any of the types in the tuple otherwise False.
Return type:: bool
Raises:: TypeError – If the argument is not a type of object or a tuple of object types.

Examples

The following example demonstrates is_a() for the object id of a Polygon object.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polygon, Topology, Surface
>>> with Project() as project:
...     with project.new("cad/test_polygon", Polygon) as polygon:
...         polygon.points = [[0, 0, 0], [0, 1, 0], [0, 1, -1], [0, 0, -1]]
...     polygon_id = polygon.id
...     print("Polygon is a Polygon?", polygon_id.is_a(Polygon))
...     print("Polygon is a Topology?", polygon_id.is_a(Topology))
...     print("Polygon is a Surface?", polygon_id.is_a(Surface))
...     # Specifying a tuple of types allows for checking if the object
...     # is any of those types.
...     print(
...         "Polygon is a Polygon or Surface?",
...          polygon_id.is_a((Polygon, Surface)))
Polygon is a Polygon? True
Polygon is a Topology? True
Polygon is a Surface? False
Polygon is a Polygon or Surface? True