mapteksdk.data.annotations module
Annotation data types.
These data types are useful for marking areas of interest.
Currently this includes:
Text2D: Represents 2D text which always faces the view.
Text3D: Represents 3D text.
Marker: 3D object which can be used to represent a place, route, sign, etc.
- class HorizontalAlignment(value)
Bases:
Enum
Enum used to represent the horizontal alignment options for 2D and 3D Text.
- LEFT = 0
- CENTRED = 1
- RIGHT = 2
- class VerticalAlignment(value)
Bases:
Enum
Enum used to represent the vertical alignment options for 2D and 3D text.
- TOP = 3
- CENTRED = 6
- BOTTOM = 4
- class FontStyle(value)
Bases:
Flag
Enum representing the possible font styles.
This is a flag enum so the values can be combined via bitwise operators.
- REGULAR = 0
The Regular font style.
- BOLD = 1
The Bold font style.
- ITALIC = 2
The Italic font style.
- class Text(object_id=None, lock_type=LockType.READWRITE)
Bases:
Topology
The abstract base class representing text at a fixed location in space.
This class cannot be instantiated directly - use Text2D or Text3D instead.
- Parameters
object_id (ObjectID | None) –
lock_type (LockType) –
- property text: str
The text displayed by this object.
- Raises
TypeError – If you attempt to set the text to a non-string value.
- property size: float
The size of the text. The default size is 16.
- property location: Point
Location of the text as point ([x,y,z]).
- property colour: Colour
The colour of the text represented as an RGBA colour.
- property vertical_alignment: VerticalAlignment
The vertical alignment of the text.
See the VerticalAlignment enum for valid values.
- Raises
TypeError – If attempting to set to a value which is not from the VerticalAlignment enum.
ValueError – If an unsupported vertical alignment is read from the Project.
Examples
Setting 3D text to be center aligned.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, VerticalAlignment >>> project = Project() >>> with project.new("cad/centre", Text3D) as new_text_3d: ... new_text_3d.text = "Centre" ... new_text_3d.vertical_alignment = VerticalAlignment.CENTRED
- property horizontal_alignment: HorizontalAlignment
The horizontal alignment of the text.
See the HorizontalAlignment enum for valid values.
- Raises
TypeError – If attempting to set to a value which is not from the HorizontalAlignment enum.
ValueError – If an unsupported horizontal alignment is read from the Project.
Examples
Setting 3D text to be left aligned.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, HorizontalAlignment >>> project = Project() >>> with project.new("cad/left", Text3D) as new_text_3d: ... new_text_3d.text = "Left" ... new_text_3d.horizontal_alignment = HorizontalAlignment.LEFT
- property font_style: FontStyle
The font style of the text.
See FontStyles enum for the possible values. Note that this is a flag enum and flags can be combined using the | operator.
- Raises
TypeError – If set to a value which is not a part of FontStyles.
Examples
Set text to be italic.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.new("cad/italic", Text3D) as new_text: ... new_text.text = "This text is italic" ... new_text.font_style = FontStyle.ITALIC
Set text to be bold and italic.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.new("cad/bolditalic", Text3D) as new_text: ... new_text.text = "This text is bold and italic" ... new_text.font_style = FontStyle.BOLD | FontStyle.ITALIC
Print if the text created in the above example is bold.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.read("cad/bolditalic") as read_text: ... if read_text.font_style & FontStyle.BOLD: ... print("This text is bold.") This text is bold.
- attribute_names()
Returns a list containing the names of all object-level attributes.
Use this to iterate over the object attributes.
- Returns
List containing the attribute names.
- Return type
list
Examples
Iterate over all object attributes of the object stared at “target” and print their values.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for name in read_object.attribute_names(): ... print(name, ":", read_object.get_attribute(name))
- close()
Closes the object and saves the changes to the Project.
Attempting to read or edit properties of an object after closing it will raise a ReadOnlyError.
- property closed: bool
If this object has been closed.
Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.
Examples
If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.
>>> with self.project.new("cad/point_set", PointSet) as point_set: >>> point_set.points = [[1, 2, 3], [4, 5, 6]] >>> print("closed?", point_set.closed) >>> print("closed?", point_set.closed) closed? False closed? True
- property coordinate_system: mapteksdk.data.coordinate_systems.CoordinateSystem | None
The coordinate system the points of this object are in.
- Raises
ReadOnlyError – If set on an object open for read-only.
Warning
Setting this property does not change the points. This is only a label stating the coordinate system the points are in.
Notes
If the object has no coordinate system, this will be None.
Changes are done directly in the project and will not be undone if an error occurs.
Examples
Creating an edge network and setting the coordinate system to be WGS84. Note that setting the coordinate system does not change the points. It is only stating which coordinate system the points are in.
>>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon >>> project = Project() >>> with project.new("cad/rectangle", Polygon) as new_edges: ... # Coordinates are in the form [longitude, latitude] ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = CRS.from_epsg(4326)
Often a standard map projection is not convenient or accurate for a given application. In such cases a local transform can be provided to allow coordinates to be specified in a more convenient system. The below example defines a local transform where the origin is translated 1.2 degrees north and 2.1 degree east, points are scaled to be twice as far from the horizontal origin and the coordinates are rotated 45 degrees clockwise about the horizontal_origin. Note that the points of the polygon are specified in the coordinate system after the local transform has been applied.
>>> import math >>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon, CoordinateSystem, LocalTransform >>> project = Project() >>> transform = LocalTransform( ... horizontal_origin = [1.2, 2.1], ... horizontal_scale_factor = 2, ... horizontal_rotation = math.pi / 4) >>> system = CoordinateSystem(CRS.from_epsg(20249), transform) >>> with project.new("cad/rectangle_transform", Polygon) as new_edges: ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = system
See also
mapteksdk.data.coordinate_systems.CoordinateSystem
Allows for a coordinate system to be defined with an optional local transform.
- property created_date: datetime
The date and time (in UTC) of when this object was created.
- Returns
The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- delete_all_attributes()
Delete all object attributes attached to an object.
This only deletes object attributes and has no effect on PrimitiveAttributes.
- Raises
RuntimeError – If all attributes cannot be deleted.
- delete_attribute(attribute)
Deletes a single object-level attribute.
Deleting a non-existent object attribute will not raise an error.
- Parameters
attribute (str) – Name of attribute to delete.
- Returns
True if the object attribute existed and was deleted; False if the object attribute did not exist.
- Return type
bool
- Raises
RuntimeError – If the attribute cannot be deleted.
- dissociate_raster(raster)
Removes the raster from the object.
This is done directly on the Project and will not be undone if an error occurs.
- Parameters
raster (Raster | ObjectID[Raster]) – The raster to dissociate.
- Returns
True if the raster was successfully dissociated from the object, False if the raster was not associated with the object.
- Return type
bool
- Raises
TypeError – If raster is not a Raster.
ReadOnlyError – If this object is open for read-only.
Notes
This only removes the association between the Raster and the object, it does not clear the registration information from the Raster.
Examples
Dissociate the first raster found on a picked object.
>>> from mapteksdk.project import Project >>> from mapteksdk import operations >>> project = Project() >>> oid = operations.object_pick( ... support_label="Pick an object to remove a raster from.") ... with project.edit(oid) as data_object: ... report = f"There were no raster to remove from {oid.path}" ... for index in data_object.rasters: ... data_object.dissociate_raster(data_object.rasters[index]) ... report = f"Removed raster {index} from {oid.path}" ... break ... # Now that the raster is dissociated and the object is closed, ... # the raster can be associated with a different object. ... operations.write_report("Remove Raster", report)
- get_attribute(name)
Returns the value for the attribute with the specified name.
- Parameters
name (str) – The name of the object attribute to get the value for.
- Returns
The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).
- Return type
ObjectAttributeTypes
- Raises
KeyError – If there is no object attribute called name.
Warning
In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.
- get_attribute_type(name)
Returns the type of the attribute with the specified name.
- Parameters
name (str) – Name of the attribute whose type should be returned.
- Returns
The type of the object attribute name.
- Return type
ObjectAttributeDataTypes
- Raises
KeyError – If there is no object attribute called name.
- get_colour_map()
Return the ID of the colour map object associated with this object.
- Returns
The ID of the colour map object or null object ID if there is no colour map.
- Return type
- property id: ObjectID[DataObject]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- property is_read_only: bool
If this object is read-only.
This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.
- property lock_type: LockType
Indicates whether operating in read-only or read-write mode.
Use the is_read_only property instead for checking if an object is open for reading or editing.
- Returns
The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.
- Return type
LockType
- property modified_date: datetime
The date and time (in UTC) of when this object was last modified.
- Returns
The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- property rasters: dict[int, ObjectID[Raster]]
The raster associated with this object.
This is a dictionary of raster indices and Object IDs of the raster images currently associated with this object.
The keys are the raster ids and the values are the Object IDs of the associated rasters. Note that all raster ids are integers however they may not be consecutive - for example, an object may have raster ids 0, 1, 5 and 200.
Notes
Rasters with higher indices appear on top of rasters with lower indices. The maximum possible raster id is 255.
Removing a raster from this dictionary will not remove the raster association from the object. Use dissociate_raster to do this.
Examples
Iterate over all rasters on an object and invert the colours. Note that this will fail if there is no object at the path “target” and it will do nothing if no rasters are associated with the target.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for raster in read_object.rasters.values(): ... with project.edit(raster) as edit_raster: ... edit_raster.pixels[:, :3] = 255 - edit_raster.pixels[:, :3]
- save()
Save the changes made to the object.
Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().
- set_attribute(name, dtype, data)
Sets the value for the object attribute with the specified name.
This will overwrite any existing attribute with the specified name.
- Parameters
name (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.
data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).
- Raises
ValueError – If dtype is an unsupported type.
TypeError – If value is an inappropriate type for object attribute name.
ValueError – If name starts or ends with whitespace or is empty.
RuntimeError – If a different error occurs.
Warning
Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).
Examples
Create an object attribute on an object at “target” and then read its value.
>>> import ctypes >>> from mapteksdk.project import Project >>> project = Project() >>> with project.edit("target") as edit_object: ... edit_object.set_attribute("count", ctypes.c_int16, 0) ... with project.read("target") as read_object: ... print(read_object.get_attribute("count")) 0
- classmethod static_type()
Return the type of a topology as stored in a Project.
This can be used for determining if the type of an object is topology.
- class Text2D(object_id=None, lock_type=LockType.READWRITE)
Bases:
Text
Allows creation of text at a fixed location in space.
Examples
Creating a new 2D text object at the origin.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text2D >>> project = Project() >>> with project.new("cad/text", Text2D) as new_text: >>> new_text.location = [0, 0, 0] >>> new_text.text = "Hello World"
Editing an existing 2D text object to be size 16 and magenta.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.edit("cad/text") as text: >>> text.colour = [255, 0, 255] >>> text.size = 16
See also
- text-2d
Help page for this class.
- Parameters
object_id (ObjectID | None) –
lock_type (LockType) –
- classmethod static_type()
Return the type of 2D text as stored in a Project.
This can be used for determining if the type of an object is a 2D text.
- Return type
int
- property id: ObjectID[Text2D]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- attribute_names()
Returns a list containing the names of all object-level attributes.
Use this to iterate over the object attributes.
- Returns
List containing the attribute names.
- Return type
list
Examples
Iterate over all object attributes of the object stared at “target” and print their values.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for name in read_object.attribute_names(): ... print(name, ":", read_object.get_attribute(name))
- close()
Closes the object and saves the changes to the Project.
Attempting to read or edit properties of an object after closing it will raise a ReadOnlyError.
- property closed: bool
If this object has been closed.
Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.
Examples
If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.
>>> with self.project.new("cad/point_set", PointSet) as point_set: >>> point_set.points = [[1, 2, 3], [4, 5, 6]] >>> print("closed?", point_set.closed) >>> print("closed?", point_set.closed) closed? False closed? True
- property colour: Colour
The colour of the text represented as an RGBA colour.
- property coordinate_system: mapteksdk.data.coordinate_systems.CoordinateSystem | None
The coordinate system the points of this object are in.
- Raises
ReadOnlyError – If set on an object open for read-only.
Warning
Setting this property does not change the points. This is only a label stating the coordinate system the points are in.
Notes
If the object has no coordinate system, this will be None.
Changes are done directly in the project and will not be undone if an error occurs.
Examples
Creating an edge network and setting the coordinate system to be WGS84. Note that setting the coordinate system does not change the points. It is only stating which coordinate system the points are in.
>>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon >>> project = Project() >>> with project.new("cad/rectangle", Polygon) as new_edges: ... # Coordinates are in the form [longitude, latitude] ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = CRS.from_epsg(4326)
Often a standard map projection is not convenient or accurate for a given application. In such cases a local transform can be provided to allow coordinates to be specified in a more convenient system. The below example defines a local transform where the origin is translated 1.2 degrees north and 2.1 degree east, points are scaled to be twice as far from the horizontal origin and the coordinates are rotated 45 degrees clockwise about the horizontal_origin. Note that the points of the polygon are specified in the coordinate system after the local transform has been applied.
>>> import math >>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon, CoordinateSystem, LocalTransform >>> project = Project() >>> transform = LocalTransform( ... horizontal_origin = [1.2, 2.1], ... horizontal_scale_factor = 2, ... horizontal_rotation = math.pi / 4) >>> system = CoordinateSystem(CRS.from_epsg(20249), transform) >>> with project.new("cad/rectangle_transform", Polygon) as new_edges: ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = system
See also
mapteksdk.data.coordinate_systems.CoordinateSystem
Allows for a coordinate system to be defined with an optional local transform.
- property created_date: datetime
The date and time (in UTC) of when this object was created.
- Returns
The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- delete_all_attributes()
Delete all object attributes attached to an object.
This only deletes object attributes and has no effect on PrimitiveAttributes.
- Raises
RuntimeError – If all attributes cannot be deleted.
- delete_attribute(attribute)
Deletes a single object-level attribute.
Deleting a non-existent object attribute will not raise an error.
- Parameters
attribute (str) – Name of attribute to delete.
- Returns
True if the object attribute existed and was deleted; False if the object attribute did not exist.
- Return type
bool
- Raises
RuntimeError – If the attribute cannot be deleted.
- dissociate_raster(raster)
Removes the raster from the object.
This is done directly on the Project and will not be undone if an error occurs.
- Parameters
raster (Raster | ObjectID[Raster]) – The raster to dissociate.
- Returns
True if the raster was successfully dissociated from the object, False if the raster was not associated with the object.
- Return type
bool
- Raises
TypeError – If raster is not a Raster.
ReadOnlyError – If this object is open for read-only.
Notes
This only removes the association between the Raster and the object, it does not clear the registration information from the Raster.
Examples
Dissociate the first raster found on a picked object.
>>> from mapteksdk.project import Project >>> from mapteksdk import operations >>> project = Project() >>> oid = operations.object_pick( ... support_label="Pick an object to remove a raster from.") ... with project.edit(oid) as data_object: ... report = f"There were no raster to remove from {oid.path}" ... for index in data_object.rasters: ... data_object.dissociate_raster(data_object.rasters[index]) ... report = f"Removed raster {index} from {oid.path}" ... break ... # Now that the raster is dissociated and the object is closed, ... # the raster can be associated with a different object. ... operations.write_report("Remove Raster", report)
- property font_style: FontStyle
The font style of the text.
See FontStyles enum for the possible values. Note that this is a flag enum and flags can be combined using the | operator.
- Raises
TypeError – If set to a value which is not a part of FontStyles.
Examples
Set text to be italic.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.new("cad/italic", Text3D) as new_text: ... new_text.text = "This text is italic" ... new_text.font_style = FontStyle.ITALIC
Set text to be bold and italic.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.new("cad/bolditalic", Text3D) as new_text: ... new_text.text = "This text is bold and italic" ... new_text.font_style = FontStyle.BOLD | FontStyle.ITALIC
Print if the text created in the above example is bold.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.read("cad/bolditalic") as read_text: ... if read_text.font_style & FontStyle.BOLD: ... print("This text is bold.") This text is bold.
- get_attribute(name)
Returns the value for the attribute with the specified name.
- Parameters
name (str) – The name of the object attribute to get the value for.
- Returns
The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).
- Return type
ObjectAttributeTypes
- Raises
KeyError – If there is no object attribute called name.
Warning
In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.
- get_attribute_type(name)
Returns the type of the attribute with the specified name.
- Parameters
name (str) – Name of the attribute whose type should be returned.
- Returns
The type of the object attribute name.
- Return type
ObjectAttributeDataTypes
- Raises
KeyError – If there is no object attribute called name.
- get_colour_map()
Return the ID of the colour map object associated with this object.
- Returns
The ID of the colour map object or null object ID if there is no colour map.
- Return type
- property horizontal_alignment: HorizontalAlignment
The horizontal alignment of the text.
See the HorizontalAlignment enum for valid values.
- Raises
TypeError – If attempting to set to a value which is not from the HorizontalAlignment enum.
ValueError – If an unsupported horizontal alignment is read from the Project.
Examples
Setting 3D text to be left aligned.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, HorizontalAlignment >>> project = Project() >>> with project.new("cad/left", Text3D) as new_text_3d: ... new_text_3d.text = "Left" ... new_text_3d.horizontal_alignment = HorizontalAlignment.LEFT
- property is_read_only: bool
If this object is read-only.
This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.
- property location: Point
Location of the text as point ([x,y,z]).
- property lock_type: LockType
Indicates whether operating in read-only or read-write mode.
Use the is_read_only property instead for checking if an object is open for reading or editing.
- Returns
The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.
- Return type
LockType
- property modified_date: datetime
The date and time (in UTC) of when this object was last modified.
- Returns
The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- property rasters: dict[int, ObjectID[Raster]]
The raster associated with this object.
This is a dictionary of raster indices and Object IDs of the raster images currently associated with this object.
The keys are the raster ids and the values are the Object IDs of the associated rasters. Note that all raster ids are integers however they may not be consecutive - for example, an object may have raster ids 0, 1, 5 and 200.
Notes
Rasters with higher indices appear on top of rasters with lower indices. The maximum possible raster id is 255.
Removing a raster from this dictionary will not remove the raster association from the object. Use dissociate_raster to do this.
Examples
Iterate over all rasters on an object and invert the colours. Note that this will fail if there is no object at the path “target” and it will do nothing if no rasters are associated with the target.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for raster in read_object.rasters.values(): ... with project.edit(raster) as edit_raster: ... edit_raster.pixels[:, :3] = 255 - edit_raster.pixels[:, :3]
- save()
Save the changes made to the object.
Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().
- set_attribute(name, dtype, data)
Sets the value for the object attribute with the specified name.
This will overwrite any existing attribute with the specified name.
- Parameters
name (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.
data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).
- Raises
ValueError – If dtype is an unsupported type.
TypeError – If value is an inappropriate type for object attribute name.
ValueError – If name starts or ends with whitespace or is empty.
RuntimeError – If a different error occurs.
Warning
Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).
Examples
Create an object attribute on an object at “target” and then read its value.
>>> import ctypes >>> from mapteksdk.project import Project >>> project = Project() >>> with project.edit("target") as edit_object: ... edit_object.set_attribute("count", ctypes.c_int16, 0) ... with project.read("target") as read_object: ... print(read_object.get_attribute("count")) 0
- property size: float
The size of the text. The default size is 16.
- property text: str
The text displayed by this object.
- Raises
TypeError – If you attempt to set the text to a non-string value.
- property vertical_alignment: VerticalAlignment
The vertical alignment of the text.
See the VerticalAlignment enum for valid values.
- Raises
TypeError – If attempting to set to a value which is not from the VerticalAlignment enum.
ValueError – If an unsupported vertical alignment is read from the Project.
Examples
Setting 3D text to be center aligned.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, VerticalAlignment >>> project = Project() >>> with project.new("cad/centre", Text3D) as new_text_3d: ... new_text_3d.text = "Centre" ... new_text_3d.vertical_alignment = VerticalAlignment.CENTRED
- class Text3D(object_id=None, lock_type=LockType.READWRITE)
Bases:
Text
Allows creation of three dimensional text at a fixed location and size.
See also
- text-3d
Help page for this class.
- Parameters
object_id (ObjectID | None) –
lock_type (LockType) –
- class Facing(value)
Bases:
Enum
Enum representing the possible facing values for 3D text.
- NO_FACING = 0
The text will not be camera or viewer facing.
Depending on the angle it is viewed from, the text may be upside down, back-to-front or both.
- CAMERA_FACING = 1
The text will rotate to always face towards the camera.
Regardless of the angle it is viewed at, the text will never be upside down or back-to-front.
This causes direction and up direction of the text to be ignored.
- VIEWER_FACING = 2
The text will automatically flip so that it never appears upside down.
Viewer facing text can still be back-to-front.
- classmethod static_type()
Return the type of 3D text as stored in a Project.
This can be used for determining if the type of an object is a 3D text.
- property id: ObjectID[Text3D]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- property direction: Vector3D
The 3D direction vector of the text.
This is the direction vector from the start of the first character to the end of the last character.
- property up_direction: Vector3D
The 3D direction vector of the text.
This is the direction vector from the bottom of the text to the top.
- property always_visible: bool
If the text will be visible through other objects.
If set to true, the 3D text will be visible with a faded out appearance when there are objects between the text and the view. This is False by default.
- Raises
TypeError – If set to a value which is not a bool.
- property facing: Facing
Where the text will face.
By default this is Text3D.Facing.VIEWER_FACING which causes the text to never appear upside down, even when viewed from the back.
See the values of the Text3D.Facing enum for possible options.
- Raises
TypeError – If set to a value which is not Text3D.Facing.
Examples
Set text containing a smiley face to be always camera facing so that it will always be smiling even when viewed from the back.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D >>> project = Project() >>> with project.new("cad/smile", Text3D) as new_text: ... new_text.text = ":)" ... new_text.facing = Text3D.Facing.CAMERA_FACING
- attribute_names()
Returns a list containing the names of all object-level attributes.
Use this to iterate over the object attributes.
- Returns
List containing the attribute names.
- Return type
list
Examples
Iterate over all object attributes of the object stared at “target” and print their values.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for name in read_object.attribute_names(): ... print(name, ":", read_object.get_attribute(name))
- close()
Closes the object and saves the changes to the Project.
Attempting to read or edit properties of an object after closing it will raise a ReadOnlyError.
- property closed: bool
If this object has been closed.
Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.
Examples
If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.
>>> with self.project.new("cad/point_set", PointSet) as point_set: >>> point_set.points = [[1, 2, 3], [4, 5, 6]] >>> print("closed?", point_set.closed) >>> print("closed?", point_set.closed) closed? False closed? True
- property colour: Colour
The colour of the text represented as an RGBA colour.
- property coordinate_system: mapteksdk.data.coordinate_systems.CoordinateSystem | None
The coordinate system the points of this object are in.
- Raises
ReadOnlyError – If set on an object open for read-only.
Warning
Setting this property does not change the points. This is only a label stating the coordinate system the points are in.
Notes
If the object has no coordinate system, this will be None.
Changes are done directly in the project and will not be undone if an error occurs.
Examples
Creating an edge network and setting the coordinate system to be WGS84. Note that setting the coordinate system does not change the points. It is only stating which coordinate system the points are in.
>>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon >>> project = Project() >>> with project.new("cad/rectangle", Polygon) as new_edges: ... # Coordinates are in the form [longitude, latitude] ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = CRS.from_epsg(4326)
Often a standard map projection is not convenient or accurate for a given application. In such cases a local transform can be provided to allow coordinates to be specified in a more convenient system. The below example defines a local transform where the origin is translated 1.2 degrees north and 2.1 degree east, points are scaled to be twice as far from the horizontal origin and the coordinates are rotated 45 degrees clockwise about the horizontal_origin. Note that the points of the polygon are specified in the coordinate system after the local transform has been applied.
>>> import math >>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon, CoordinateSystem, LocalTransform >>> project = Project() >>> transform = LocalTransform( ... horizontal_origin = [1.2, 2.1], ... horizontal_scale_factor = 2, ... horizontal_rotation = math.pi / 4) >>> system = CoordinateSystem(CRS.from_epsg(20249), transform) >>> with project.new("cad/rectangle_transform", Polygon) as new_edges: ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = system
See also
mapteksdk.data.coordinate_systems.CoordinateSystem
Allows for a coordinate system to be defined with an optional local transform.
- property created_date: datetime
The date and time (in UTC) of when this object was created.
- Returns
The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- delete_all_attributes()
Delete all object attributes attached to an object.
This only deletes object attributes and has no effect on PrimitiveAttributes.
- Raises
RuntimeError – If all attributes cannot be deleted.
- delete_attribute(attribute)
Deletes a single object-level attribute.
Deleting a non-existent object attribute will not raise an error.
- Parameters
attribute (str) – Name of attribute to delete.
- Returns
True if the object attribute existed and was deleted; False if the object attribute did not exist.
- Return type
bool
- Raises
RuntimeError – If the attribute cannot be deleted.
- dissociate_raster(raster)
Removes the raster from the object.
This is done directly on the Project and will not be undone if an error occurs.
- Parameters
raster (Raster | ObjectID[Raster]) – The raster to dissociate.
- Returns
True if the raster was successfully dissociated from the object, False if the raster was not associated with the object.
- Return type
bool
- Raises
TypeError – If raster is not a Raster.
ReadOnlyError – If this object is open for read-only.
Notes
This only removes the association between the Raster and the object, it does not clear the registration information from the Raster.
Examples
Dissociate the first raster found on a picked object.
>>> from mapteksdk.project import Project >>> from mapteksdk import operations >>> project = Project() >>> oid = operations.object_pick( ... support_label="Pick an object to remove a raster from.") ... with project.edit(oid) as data_object: ... report = f"There were no raster to remove from {oid.path}" ... for index in data_object.rasters: ... data_object.dissociate_raster(data_object.rasters[index]) ... report = f"Removed raster {index} from {oid.path}" ... break ... # Now that the raster is dissociated and the object is closed, ... # the raster can be associated with a different object. ... operations.write_report("Remove Raster", report)
- property font_style: FontStyle
The font style of the text.
See FontStyles enum for the possible values. Note that this is a flag enum and flags can be combined using the | operator.
- Raises
TypeError – If set to a value which is not a part of FontStyles.
Examples
Set text to be italic.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.new("cad/italic", Text3D) as new_text: ... new_text.text = "This text is italic" ... new_text.font_style = FontStyle.ITALIC
Set text to be bold and italic.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.new("cad/bolditalic", Text3D) as new_text: ... new_text.text = "This text is bold and italic" ... new_text.font_style = FontStyle.BOLD | FontStyle.ITALIC
Print if the text created in the above example is bold.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, FontStyle >>> project = Project() >>> with project.read("cad/bolditalic") as read_text: ... if read_text.font_style & FontStyle.BOLD: ... print("This text is bold.") This text is bold.
- get_attribute(name)
Returns the value for the attribute with the specified name.
- Parameters
name (str) – The name of the object attribute to get the value for.
- Returns
The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).
- Return type
ObjectAttributeTypes
- Raises
KeyError – If there is no object attribute called name.
Warning
In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.
- get_attribute_type(name)
Returns the type of the attribute with the specified name.
- Parameters
name (str) – Name of the attribute whose type should be returned.
- Returns
The type of the object attribute name.
- Return type
ObjectAttributeDataTypes
- Raises
KeyError – If there is no object attribute called name.
- get_colour_map()
Return the ID of the colour map object associated with this object.
- Returns
The ID of the colour map object or null object ID if there is no colour map.
- Return type
- property horizontal_alignment: HorizontalAlignment
The horizontal alignment of the text.
See the HorizontalAlignment enum for valid values.
- Raises
TypeError – If attempting to set to a value which is not from the HorizontalAlignment enum.
ValueError – If an unsupported horizontal alignment is read from the Project.
Examples
Setting 3D text to be left aligned.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, HorizontalAlignment >>> project = Project() >>> with project.new("cad/left", Text3D) as new_text_3d: ... new_text_3d.text = "Left" ... new_text_3d.horizontal_alignment = HorizontalAlignment.LEFT
- property is_read_only: bool
If this object is read-only.
This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.
- property location: Point
Location of the text as point ([x,y,z]).
- property lock_type: LockType
Indicates whether operating in read-only or read-write mode.
Use the is_read_only property instead for checking if an object is open for reading or editing.
- Returns
The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.
- Return type
LockType
- property modified_date: datetime
The date and time (in UTC) of when this object was last modified.
- Returns
The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- property rasters: dict[int, ObjectID[Raster]]
The raster associated with this object.
This is a dictionary of raster indices and Object IDs of the raster images currently associated with this object.
The keys are the raster ids and the values are the Object IDs of the associated rasters. Note that all raster ids are integers however they may not be consecutive - for example, an object may have raster ids 0, 1, 5 and 200.
Notes
Rasters with higher indices appear on top of rasters with lower indices. The maximum possible raster id is 255.
Removing a raster from this dictionary will not remove the raster association from the object. Use dissociate_raster to do this.
Examples
Iterate over all rasters on an object and invert the colours. Note that this will fail if there is no object at the path “target” and it will do nothing if no rasters are associated with the target.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for raster in read_object.rasters.values(): ... with project.edit(raster) as edit_raster: ... edit_raster.pixels[:, :3] = 255 - edit_raster.pixels[:, :3]
- save()
Save the changes made to the object.
Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().
- set_attribute(name, dtype, data)
Sets the value for the object attribute with the specified name.
This will overwrite any existing attribute with the specified name.
- Parameters
name (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.
data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).
- Raises
ValueError – If dtype is an unsupported type.
TypeError – If value is an inappropriate type for object attribute name.
ValueError – If name starts or ends with whitespace or is empty.
RuntimeError – If a different error occurs.
Warning
Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).
Examples
Create an object attribute on an object at “target” and then read its value.
>>> import ctypes >>> from mapteksdk.project import Project >>> project = Project() >>> with project.edit("target") as edit_object: ... edit_object.set_attribute("count", ctypes.c_int16, 0) ... with project.read("target") as read_object: ... print(read_object.get_attribute("count")) 0
- property size: float
The size of the text. The default size is 16.
- property text: str
The text displayed by this object.
- Raises
TypeError – If you attempt to set the text to a non-string value.
- property vertical_alignment: VerticalAlignment
The vertical alignment of the text.
See the VerticalAlignment enum for valid values.
- Raises
TypeError – If attempting to set to a value which is not from the VerticalAlignment enum.
ValueError – If an unsupported vertical alignment is read from the Project.
Examples
Setting 3D text to be center aligned.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Text3D, VerticalAlignment >>> project = Project() >>> with project.new("cad/centre", Text3D) as new_text_3d: ... new_text_3d.text = "Centre" ... new_text_3d.vertical_alignment = VerticalAlignment.CENTRED
- class Marker(object_id=None, lock_type=LockType.READWRITE)
Bases:
Topology
,RotationMixin
Provides a visual representation for a sign.
This can be used to mark locations.
See also
- marker
Help page for this class.
Examples
Create a red diamond-shaped Marker with white text at [1, 2, 3].
>>> from mapteksdk.project import Project >>> from mapteksdk.data import Marker >>> project = Project() >>> with project.new("cad/diamond", Marker) as new_marker: >>> new_marker.text = "White" >>> new_marker.marker_colour = [255, 0, 0] >>> new_marker.text_colour = [255, 255, 255] >>> new_marker.shape = Marker.Shape.DIAMOND >>> new_marker.location = [1, 2, 3]
Rotate an existing marker by 45 degrees.
>>> import math >>> from mapteksdk.project import Project >>> project = Project() >>> with project.edit("cad/diamond") as marker: >>> marker.rotate_2d(math.radians(45))
- class Shape(value)
Bases:
IntEnum
Different shapes or styles that a marker can be.
A marker can have a custom shape where a Surface provides the shape.
- A_FRAME_OPEN = 0
The marker is shaped like an A-frame.
This shape is similar to a crime scene evidence marker or a cleaning in progress sign with the name of the marker on both surfaces.
- DIAMOND = 1
An 8 facet diamond with the name appearing on all surfaces.
- CUBE = 2
A cube with name on all the sides excluding top and bottom.
- VERTICAL_SIGN = 3
A simple vertical billboard.
- A_FRAME_SIGN = 4
A triangular prism billboard.
This is similar to A_FRAME_OPEN but solid and placed on a pole.
- THREE_SIDED_SIGN = 5
A triangular prism billboard with the triangle in the XY plane
- HORIZONTAL_SIGN = 6
A billboard aligned with the XY plane.
- ZEBRA_SCALE = 7
A striped scale bar.
- CHECKERED_SCALE = 8
A scale bar in checkerboard pattern.
- U_SCALE = 9
A U-Shaped scale bar in uniform colour.
- PRONE_HUMAN = 10
A prone human shaped marker.
- UPRIGHT_HUMAN = 11
An upright human shaped marker with a pedestal.
- COMPASS_ROSE = 12
A 3D compass rose marker.
- CUSTOM = 255
The marker uses a custom shape.
The custom shape is set by assigning a Surface to the custom_shape_object property.
- attribute_names()
Returns a list containing the names of all object-level attributes.
Use this to iterate over the object attributes.
- Returns
List containing the attribute names.
- Return type
list
Examples
Iterate over all object attributes of the object stared at “target” and print their values.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for name in read_object.attribute_names(): ... print(name, ":", read_object.get_attribute(name))
- close()
Closes the object and saves the changes to the Project.
Attempting to read or edit properties of an object after closing it will raise a ReadOnlyError.
- property closed: bool
If this object has been closed.
Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.
Examples
If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.
>>> with self.project.new("cad/point_set", PointSet) as point_set: >>> point_set.points = [[1, 2, 3], [4, 5, 6]] >>> print("closed?", point_set.closed) >>> print("closed?", point_set.closed) closed? False closed? True
- property coordinate_system: mapteksdk.data.coordinate_systems.CoordinateSystem | None
The coordinate system the points of this object are in.
- Raises
ReadOnlyError – If set on an object open for read-only.
Warning
Setting this property does not change the points. This is only a label stating the coordinate system the points are in.
Notes
If the object has no coordinate system, this will be None.
Changes are done directly in the project and will not be undone if an error occurs.
Examples
Creating an edge network and setting the coordinate system to be WGS84. Note that setting the coordinate system does not change the points. It is only stating which coordinate system the points are in.
>>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon >>> project = Project() >>> with project.new("cad/rectangle", Polygon) as new_edges: ... # Coordinates are in the form [longitude, latitude] ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = CRS.from_epsg(4326)
Often a standard map projection is not convenient or accurate for a given application. In such cases a local transform can be provided to allow coordinates to be specified in a more convenient system. The below example defines a local transform where the origin is translated 1.2 degrees north and 2.1 degree east, points are scaled to be twice as far from the horizontal origin and the coordinates are rotated 45 degrees clockwise about the horizontal_origin. Note that the points of the polygon are specified in the coordinate system after the local transform has been applied.
>>> import math >>> from pyproj import CRS >>> from mapteksdk.project import Project >>> from mapteksdk.data import Polygon, CoordinateSystem, LocalTransform >>> project = Project() >>> transform = LocalTransform( ... horizontal_origin = [1.2, 2.1], ... horizontal_scale_factor = 2, ... horizontal_rotation = math.pi / 4) >>> system = CoordinateSystem(CRS.from_epsg(20249), transform) >>> with project.new("cad/rectangle_transform", Polygon) as new_edges: ... new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]] ... new_edges.coordinate_system = system
See also
mapteksdk.data.coordinate_systems.CoordinateSystem
Allows for a coordinate system to be defined with an optional local transform.
- property created_date: datetime
The date and time (in UTC) of when this object was created.
- Returns
The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- delete_all_attributes()
Delete all object attributes attached to an object.
This only deletes object attributes and has no effect on PrimitiveAttributes.
- Raises
RuntimeError – If all attributes cannot be deleted.
- delete_attribute(attribute)
Deletes a single object-level attribute.
Deleting a non-existent object attribute will not raise an error.
- Parameters
attribute (str) – Name of attribute to delete.
- Returns
True if the object attribute existed and was deleted; False if the object attribute did not exist.
- Return type
bool
- Raises
RuntimeError – If the attribute cannot be deleted.
- dissociate_raster(raster)
Removes the raster from the object.
This is done directly on the Project and will not be undone if an error occurs.
- Parameters
raster (Raster | ObjectID[Raster]) – The raster to dissociate.
- Returns
True if the raster was successfully dissociated from the object, False if the raster was not associated with the object.
- Return type
bool
- Raises
TypeError – If raster is not a Raster.
ReadOnlyError – If this object is open for read-only.
Notes
This only removes the association between the Raster and the object, it does not clear the registration information from the Raster.
Examples
Dissociate the first raster found on a picked object.
>>> from mapteksdk.project import Project >>> from mapteksdk import operations >>> project = Project() >>> oid = operations.object_pick( ... support_label="Pick an object to remove a raster from.") ... with project.edit(oid) as data_object: ... report = f"There were no raster to remove from {oid.path}" ... for index in data_object.rasters: ... data_object.dissociate_raster(data_object.rasters[index]) ... report = f"Removed raster {index} from {oid.path}" ... break ... # Now that the raster is dissociated and the object is closed, ... # the raster can be associated with a different object. ... operations.write_report("Remove Raster", report)
- get_attribute(name)
Returns the value for the attribute with the specified name.
- Parameters
name (str) – The name of the object attribute to get the value for.
- Returns
The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).
- Return type
ObjectAttributeTypes
- Raises
KeyError – If there is no object attribute called name.
Warning
In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.
- get_attribute_type(name)
Returns the type of the attribute with the specified name.
- Parameters
name (str) – Name of the attribute whose type should be returned.
- Returns
The type of the object attribute name.
- Return type
ObjectAttributeDataTypes
- Raises
KeyError – If there is no object attribute called name.
- get_colour_map()
Return the ID of the colour map object associated with this object.
- Returns
The ID of the colour map object or null object ID if there is no colour map.
- Return type
- property heading_pitch_roll: tuple[float, float, float]
The heading, pitch and roll angles for this rotation.
The heading is defined as the angle of the rotation about the -z axis. The pitch is defined as the angle of the rotation about the x axis. The roll is defined as the rotation about the y axis.
- property is_read_only: bool
If this object is read-only.
This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.
- property lock_type: LockType
Indicates whether operating in read-only or read-write mode.
Use the is_read_only property instead for checking if an object is open for reading or editing.
- Returns
The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.
- Return type
LockType
- property modified_date: datetime
The date and time (in UTC) of when this object was last modified.
- Returns
The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.
- Return type
datetime.datetime
- property orientation: tuple[float, float, float]
The rotation represented as Vulcan-style dip, plunge and bearing.
This is the tuple: (dip, plunge, bearing) where each value is in radians.
This is defined differently for ellipsoids to ensure consistency with the dip, plunge and bearing displayed in applications.
Notes
This is a derived property. It is recalculated each time this is called.
- property rasters: dict[int, ObjectID[Raster]]
The raster associated with this object.
This is a dictionary of raster indices and Object IDs of the raster images currently associated with this object.
The keys are the raster ids and the values are the Object IDs of the associated rasters. Note that all raster ids are integers however they may not be consecutive - for example, an object may have raster ids 0, 1, 5 and 200.
Notes
Rasters with higher indices appear on top of rasters with lower indices. The maximum possible raster id is 255.
Removing a raster from this dictionary will not remove the raster association from the object. Use dissociate_raster to do this.
Examples
Iterate over all rasters on an object and invert the colours. Note that this will fail if there is no object at the path “target” and it will do nothing if no rasters are associated with the target.
>>> from mapteksdk.project import Project >>> project = Project() >>> with project.read("target") as read_object: ... for raster in read_object.rasters.values(): ... with project.edit(raster) as edit_raster: ... edit_raster.pixels[:, :3] = 255 - edit_raster.pixels[:, :3]
- rotate(angle, axis)
Rotates the object by the specified angle around the specified axis.
- Parameters
angle (float) – The angle to rotate by in radians. Positive is clockwise, negative is anticlockwise (When looking in the direction of axis).
axis (Axis) – The axis to rotate by.
- Raises
ReadOnlyError – If this object is open for read-only.
Examples
Create a 2x2x2 dense block model which is rotated by pi / 4 radians (45 degrees) around the X axis.
>>> import math >>> from mapteksdk.project import Project >>> from mapteksdk.data import DenseBlockModel, Axis >>> project = Project() >>> with project.new("blockmodels/dense_rotated", DenseBlockModel( ... x_res=1, y_res=1, z_res=1, ... x_count=2, y_count=2, z_count=3)) as new_model: ... new_model.rotate(math.pi / 4, Axis.X)
If you want to specify the angle in degrees instead of radians, use the math.radians function. Additionally rotate can be called multiple times to rotate the block model in multiple axes. Both of these are shown in the below example. The resulting block model is rotated 32 degrees around the Y axis and 97 degrees around the Z axis.
>>> import math >>> from mapteksdk.project import Project >>> from mapteksdk.data import DenseBlockModel, Axis >>> project = Project() >>> with project.new("blockmodels/dense_rotated_degrees", DenseBlockModel( ... x_res=1, y_res=1, z_res=1, ... x_count=2, y_count=2, z_count=3)) as new_model: ... new_model.rotate(math.radians(32), Axis.Y) ... new_model.rotate(math.radians(97), Axis.Z)
- rotate_2d(angle)
Rotates the object in two dimensions. This is equivalent to rotate with axis=Axis.Z
- Parameters
angle (float) – The angle to rotate by in radians. Positive is clockwise, negative is anticlockwise.
- Raises
ReadOnlyError – If this object is open for read-only.
- property rotation: float
Returns the magnitude of the rotation of the object in radians.
This value is the total rotation of the object relative to its original position.
Notes
If the object has been rotated in multiple axes, this will not be the sum of the rotations performed. For example, a rotation of 90 degrees around the X axis, followed by a rotation of 90 degrees around the Y axis corresponds to a single rotation of 120 degrees so this function would return (2 * pi) / 3 radians.
- save()
Save the changes made to the object.
Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().
- set_attribute(name, dtype, data)
Sets the value for the object attribute with the specified name.
This will overwrite any existing attribute with the specified name.
- Parameters
name (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.
data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).
- Raises
ValueError – If dtype is an unsupported type.
TypeError – If value is an inappropriate type for object attribute name.
ValueError – If name starts or ends with whitespace or is empty.
RuntimeError – If a different error occurs.
Warning
Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).
Examples
Create an object attribute on an object at “target” and then read its value.
>>> import ctypes >>> from mapteksdk.project import Project >>> project = Project() >>> with project.edit("target") as edit_object: ... edit_object.set_attribute("count", ctypes.c_int16, 0) ... with project.read("target") as read_object: ... print(read_object.get_attribute("count")) 0
- set_heading_pitch_roll(heading, pitch, roll)
Replace the existing rotation with specified heading, pitch and roll.
- Parameters
heading (float) – Angle in radians of the rotation about the -z axis. This should be between 0 and 2 * pi radians (inclusive).
pitch (float) – Angle in radians of the rotation about the x axis. This should be between -pi / 2 and pi / 2 radians (inclusive).
roll (float) – Angle in radians of the rotation about the y axis. This should be between -pi / 2 and pi / 2 radians (inclusive).
- Raises
ValueError – If heading < 0 or heading > 2 * pi. If pitch < -pi / 2 or pitch > pi / 2. If roll < -pi / 2 or roll > pi / 2.
- set_orientation(dip, plunge, bearing)
Overwrite the existing rotation with dip, plunge and bearing.
For block models, an orientation of (dip, plunge, bearing) radians is equivalent to rotating the model -dip radians around the X axis, -plunge radians around the Y axis and -(bearing - pi / 2) radians around the Z axis.
For ellipsoids, set_orientation(dip, plunge, bearing) is equivalent to set_heading_pitch_roll(bearing, plunge, -dip)
- Parameters
dip (float) – Relative rotation of the Y axis around the X axis in radians. This should be between -pi and pi (inclusive).
plunge (float) – Relative rotation of the X axis around the Y axis in radians. This should be between -pi / 2 and pi / 2 (exclusive).
bearing (float) – Absolute bearing of the X axis around the Z axis in radians. For block models, this should be between -pi and pi (inclusive) For ellipsoids, this should be between -pi / 2 and pi / 2 (exclusive).
- Raises
TypeError – If dip, plunge or bearing are not numbers.
ReadOnlyError – If this object is not open for editing.
Examples
Set orientation of a new 3x3x3 block model to be plunge = 45 degrees, dip = 30 degrees and bearing = -50 degrees
>>> import math >>> from mapteksdk.project import Project >>> from mapteksdk.data import DenseBlockModel >>> project = Project() >>> with project.new("blockmodels/model_1", DenseBlockModel( ... x_res=1, y_res=1, z_res=1, ... x_count=3, y_count=3, z_count=3)) as new_model: >>> new_model.set_orientation(math.radians(45), ... math.radians(30), ... math.radians(-50))
Copy the rotation from one block model to another. Requires two block models.
>>> from mapteksdk.project import Project >>> from mapteksdk.data import DenseBlockModel >>> project = Project() >>> with project.edit("blockmodels/model_1") as model_1: ... with project.edit("blockmodels/model_2") as model_2: ... model_2.set_orientation(*model_1.orientation)
- set_rotation(angle, axis)
Overwrites the existing rotation with a rotation around the specified axis by the specified angle.
This is useful for resetting the rotation to a known point.
- Parameters
angle (float) – Angle to set the rotation to in radians. Positive is clockwise, negative is anticlockwise.
axis (Axis) – Axis to rotate around.
- Raises
ReadOnlyError – If this object is open for read-only.
- set_rotation_2d(angle)
Overwrite the existing rotation with a simple 2d rotation.
- Parameters
angle (float) – Angle to set the rotation to in radians.
- Raises
ReadOnlyError – If this object is not open for editing.
- classmethod static_type()
Return the type of marker as stored in a Project.
This can be used for determining if the type of an object is a marker.
- Return type
int
- property id: ObjectID[Marker]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- property text: str
The text displayed on the marker.
- property shape: Shape
What shape the marker takes in a view.
This must be from the Marker.Shape enum.
- property custom_shape_object: ObjectID[Surface]
The ObjectID of the surface used for the custom marker shape.
For best results the surface should be centred at [0, 0, 0] and should fit within a unit sphere centred at the origin.
- Raises
TypeError – If set to a value which cannot be converted to an ObjectID.
ValueError – If set to an ObjectID which is not for a Surface.
Notes
Set this to None to remove the custom shape of the marker.
Examples
Creating a tetrahedron shaped marker at [10, 10, 10] using a custom surface.
>>> import math >>> from mapteksdk.project import Project >>> from mapteksdk.data import Marker, Surface >>> x = 1 / math.sqrt(2) >>> points = [[1, 0, -x], [-1, 0, -x], [0, 1, x], [0, -1, x]] >>> facets = [[2, 0, 1], [0, 3, 1], [2, 1, 3], [0, 2, 3]] >>> project = Project() >>> with project.new("surfaces/tetra_base", Surface) as new_tetrahedron: ... new_tetrahedron.points = points ... new_tetrahedron.facets = facets >>> with project.new("cad/tetra_marker", Marker) as new_marker: ... new_marker.text = "tetrahedron" ... new_marker.custom_shape_object = new_tetrahedron ... new_marker.location = [10, 10, 10]
- property location: Point
Position of the marker as a point ([x,y,z]).
- property size: float
The size of the marker in meters. The default is 1.0.
For a marker with a custom shape, the actual size of the marker is the size of the custom shape object multiplied by this property.
- Raises
ValueError – If set to a value which cannot be converted to a float.
TypeError – If set to a type which cannot be converted to a float.
- property height: float
The height the marker will appear above the location.
This can be used to make the marker appear a suitable distance above the marked location. This can be useful if having the marker exactly at the marked location causes it to obscure the location it is marking.
Notes
Requires api_version 1.4 or higher.
See also
mapteksdk.project.Project.api_version
Includes a table of applications to api_versions.
- property text_colour: Colour
The colour of the text on the marker, represented as an RGBA colour.
See also
marker_colour
The colour of the marker itself.
- property marker_colour: Colour
The colour of the marker, represented as an RGBA colour.
See also
text_colour
The colour of the text on the marker.
Notes
Marker colour is currently ignored by markers with custom shapes, however it is intended to be implemented in the future.
The alpha value of the marker colour is currently ignored, though may be supported in the future. It is recommended to set the alpha value to 255.