mapteksdk.data.edges module

Edge data types.

Data types which are based on edge primitives. This includes:

• EdgeNetwork which has discontinuous lines/polylines in single object.

• Polyline which represents an open polygon.

• Polygon which represents a closed polygon.

class Edge(object_id, lock_type=LockType.READWRITE)

Bases: EdgeProperties, PointProperties, PointDeletionProperties, Topology

Base class for EdgeNetwork, Polygon and Polyline.

Parameters

• object_id (ObjectID) – The ID of the object to open. If None make a new Edge.

• lock_type (LockType) – The type of lock to place on the object. Default is Read.

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().

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, preventing any further changes.

property coordinate_system: CoordinateSystem | None

The coordinate system the points of this object are in.

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.

delete_edge_attribute(attribute_name)

Delete a edge attribute by name.

Parameters

attribute_name (str) – The name of attribute

Raises

Exception – If the object is opened in read-only mode.

delete_point_attribute(attribute_name)

Delete a point attribute by name.

This is equivalent to: point_attributes.delete_attribute(attribute_name)

Parameters

attribute_name (str) – The name of attribute

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the primitive type is not supported.

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.

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 edge_attributes

Access to custom edge attributes. These are arrays of values of the same type with one value for each edge.

Use Object.edge_attributes[attribute_name] to access the edge attribute called attribute_name. See PrimitiveAttributes for valid operations on edge attributes.

Returns

Access to the edge attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

Warning

For Surfaces if you have changed the points or facets in the object, you must call save() before accessing the edge attributes.

property edge_colours

The colours of the edges, represented as a numpy array of RGBA colours, with one colour for each edge. When setting the colour you may use RGB or greyscale colours instead.

If there are more edge colours than edges, the excess colours are silently ignored. If there are fewer colours than edges, the uncoloured edges are coloured green. If only a single colour is passed, instead of padding with green all of the edges are coloured with that colour. ie: object.edge_colours = [[Red, Green, Blue]] will set all edge colours to be the colour [Red, Green, Blue].

property edge_count

The count of edges in the object.

property edge_selection

A 1D ndarray representing which edges are selected.

edge_selection[i] = True indicates edge i is selected.

property edges

A 2D Numpy array of edges of the form: [[i0, j0], [i1, j1], …, [iN, jN]] where N is the number of edges and all iK and jK are valid indices in Object.points.

Warning

For Surfaces the edges are derived from the points and facets. If any changes are made to the points or facets, the corresponding changes to the edges will not be made until save() has been called.

Notes

Invalid edges are removed during save().

property extent: Extent

The axes aligned bounding extent of the object.

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 currently associated with this object.

Returns

The ID of the colour map object or null object ID if there is no colour map.

Return type

ObjectID

property id: ObjectID[DataObject]

Object ID that uniquely references this object in the project.

Returns

The unique id of this object.

Return type

ObjectID

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

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 point_attributes

Access the custom point attributes. These are arrays of values of the same type with one value for each point.

Use Object.point_attributes[attribute_name] to access the point attribute called attribute_name. See PrimitiveAttributes for valid operations on point attributes.

Returns

Access to the point attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

property point_colours

The colours of the points, represented as a 2d ndarray of RGBA colours. When setting the colour you may use RGB or greyscale colours instead of RGBA colours. The array has one colour for each point. Object.point_colours[i] returns the colour of Object.points[i].

Notes

When the point colours are set, if there are more colours than points then the excess colours are silently ignored. If there are fewer colours than points then uncoloured points are coloured green. If only a single colour is specified, instead of padding with green all of the points are coloured with that colour. i.e.: object.point_colours = [[Red, Green, Blue]] will set all points to be the colour [Red, Green, Blue].

property point_count

The number of points in the object.

property point_selection

A 1D ndarray representing the point selection.

If Object.point_selection[i] = True then Object.point[i] is selected. Object.point_selection[i] = False then Object.point[i] is not selected.

property point_visibility

A 1D ndarray representing the visibility of points.

Object.point_visibility[i] is true if Object.point[i] is visible. It will be False if the point is invisible.

Object.point_visibility[i] = False will make Object.point[i] invisible.

property point_z

The Z coordinates of the points.

Raises

• ValueError – If set using a string which cannot be converted to a float.

• ValueError – If set to a value which cannot be broadcast to the right shape.

• TypeError – If set using a value which cannot be converted to a float.

property points

A 2D ndarray of points of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] Where N is the number of points.

Raises

AttributeError – If attempting to set the points on an object which does not support setting points.

Examples

Create a new point set and set the points:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
... with project.new("cad/test_points", PointSet) as new_points:
...     new_points.points = [[0, 0, 0], [1, 0, 0], [1, 1, 0],
...                          [0, 1, 0], [0, 2, 2], [0, -1, 3]]

Print the second point from the point set defined above.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     print(read_points.points[2])
[1., 1., 0.]

Then set the 2nd point to [1, 2, 3]:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.edit("cad/test_points") as edit_points:
...     edit_points.points[2] = [1, 2, 3]

Iterate over all of the points and print them.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
>>>     for point in read_points.points:
>>>         print(point)
[0., 0., 0.]
[1., 0., 0.]
[1., 2., 3.]
[0., 1., 0.]
[0., 2., 2.]
[0., -1., 3.]

Print all points with y > 0 using numpy. Note that index has one element for each point which will be true if that point has y > 0 and false otherwise. This is then used to retrieve the points with y > 0.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     index = read_points.points[:, 1] > 0
...     print(read_points.points[index])
[[1. 2. 3.]
 [0. 1. 0.]
 [0. 2. 2.]]

property rasters: dict[int, ObjectID[Raster]]

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]

remove_points(point_indices)

Remove one or more points from the object.

Calling this function is preferable to altering the points array because this function also removes the point properties associated with the removed points (e.g. point colours, point visibility, etc).

This operation is performed directly on the Project and will not be undone if an error occurs.

Parameters

point_indices (array_like or int) – The index of the point to remove or a list of indices of points to remove. Any index which is lower than zero or greater than or equal to the point count is ignored (i.e. Passing -1 will not delete the last point).

Returns

If passed a single point index, True if the point was removed and False if it was not removed. If passed an iterable of point indices, True if the object supports removing points and False otherwise.

Return type

bool

Raises

ReadOnlyError – If called on an object not open for editing. This error indicates an issue with the script and should not be caught.

Warning

Any unsaved changes to the object when this function is called are discarded before any points are deleted. If you wish to keep these changes, call save() before calling this function.

Examples

Deleting a point through this function is preferable over removing the point from the points array because this function also deletes the properties associated with the deleted points. For example, all points will remain the same colour after the deletion operation, which points are visible will remain the same, etc. This is shown in the following script:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> red = [255, 0, 0, 255]
>>> blue = [0, 0, 255, 255]
>>> with project.new("cad/deletion_example", PointSet) as point_set:
...     point_set.points = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]
...     point_set.point_colours = [red, red, blue, blue]
...     point_set.point_attributes["attribute"] = [0, 1, 2, 3]
>>> with project.edit(point_set.id) as edit_set:
...     edit_set.remove_points((1, 2))
...     print("points\n", edit_set.points)
...     print("colours\n", edit_set.point_colours)
...     print("attribute\n", edit_set.point_attributes["attribute"])
points
 [[0. 0. 0.]
 [1. 1. 0.]]
colours
 [[255   0   0 255]
 [  0   0 255 255]]
attribute
 [0 3]

save_edge_attribute(attribute_name, data)

Create and/or edit the values of the edge attribute attribute_name.

This is equivalent to Object.edge_attributes[attribute_name] = data

Parameters

• attribute_name (str) – The name of attribute.

• data (array_like) – An array_like of a base type data to store for the attribute per-primitive.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

save_point_attribute(attribute_name, data)

Create and/or edit the values of the point attribute attribute_name.

This is equivalent to Object.point_attributes[attribute_name] = data.

Parameters

• attribute_name (str) – The name of attribute

• data (array_like) – An array_like of length point_count containing the values for attribute_name.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

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 – The name of the object attribute for which the value should be set.

• dtype – 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 – 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.

• 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 EdgeNetwork(object_id=None, lock_type=LockType.READWRITE)

Bases: Edge

An edge network can contain multiple discontinuous lines/polylines in single object. Unlike Polyline and Polygon, the user must explicitly set the edges in the EdgeNetwork.

Examples

Creating an edge network with an edge between points 0 and point 1 and a second edge edge between points 2 and 3.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import EdgeNetwork
>>> project = Project()
>>> with project.new("cad/edges", EdgeNetwork) as new_network:
>>>     new_network.points = [[0, 0, 0], [1, 2, 3], [0, 0, 1], [0, 0, 2]]
>>>     new_network.edges = [[0, 1], [2, 3]]

property id: ObjectID[EdgeNetwork]

Object ID that uniquely references this object in the project.

Returns

The unique id of this object.

Return type

ObjectID

property edges

A 2D Numpy array of edges of the form: [[i0, j0], [i1, j1], …, [iN, jN]] where N is the number of edges and all iK and jK are valid indices in Object.points.

Warning

For Surfaces the edges are derived from the points and facets. If any changes are made to the points or facets, the corresponding changes to the edges will not be made until save() has been called.

Notes

Invalid edges are removed during save().

remove_edges(edge_indices)

Remove one or more edges from the object.

Calling this function is preferable to altering the edges array because this function also removes the edge properties associated with the removed edges (e.g. edge colours, edge visibility, etc). Additionally, if after the removal of edges if any point is not part of any edge it will be removed as well.

This operation is performed directly on the Project and will not be undone if an error occurs.

Parameters

edge_indices (array_like or int) – The index of the edge to remove or a list of indices of edges to remove. Any index which is lower than zero or greater than or equal to the edge count is ignored (i.e. Passing -1 will not delete the last edge).

Returns

If passed a single edge index, True if the edge was removed and False if it was not removed. If passed an iterable of edge indices, True if the object supports removing edges and False otherwise.

Return type

bool

Raises

ReadOnlyError – If called on an object not open for editing. This error indicates an issue with the script and should not be caught.

Warning

Any unsaved changes to the object when this function is called are discarded before any edges are deleted. If you wish to keep these changes, call save() before calling this function.

classmethod static_type()

Return the type of edge network as stored in a Project.

This can be used for determining if the type of an object is an edge network.

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, preventing any further changes.

property coordinate_system: CoordinateSystem | None

The coordinate system the points of this object are in.

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.

delete_edge_attribute(attribute_name)

Delete a edge attribute by name.

Parameters

attribute_name (str) – The name of attribute

Raises

Exception – If the object is opened in read-only mode.

delete_point_attribute(attribute_name)

Delete a point attribute by name.

This is equivalent to: point_attributes.delete_attribute(attribute_name)

Parameters

attribute_name (str) – The name of attribute

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the primitive type is not supported.

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.

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 edge_attributes

Access to custom edge attributes. These are arrays of values of the same type with one value for each edge.

Use Object.edge_attributes[attribute_name] to access the edge attribute called attribute_name. See PrimitiveAttributes for valid operations on edge attributes.

Returns

Access to the edge attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

Warning

For Surfaces if you have changed the points or facets in the object, you must call save() before accessing the edge attributes.

property edge_colours

The colours of the edges, represented as a numpy array of RGBA colours, with one colour for each edge. When setting the colour you may use RGB or greyscale colours instead.

If there are more edge colours than edges, the excess colours are silently ignored. If there are fewer colours than edges, the uncoloured edges are coloured green. If only a single colour is passed, instead of padding with green all of the edges are coloured with that colour. ie: object.edge_colours = [[Red, Green, Blue]] will set all edge colours to be the colour [Red, Green, Blue].

property edge_count

The count of edges in the object.

property edge_selection

A 1D ndarray representing which edges are selected.

edge_selection[i] = True indicates edge i is selected.

property extent: Extent

The axes aligned bounding extent of the object.

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 currently associated with this object.

Returns

The ID of the colour map object or null object ID if there is no colour map.

Return type

ObjectID

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

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 point_attributes

Access the custom point attributes. These are arrays of values of the same type with one value for each point.

Use Object.point_attributes[attribute_name] to access the point attribute called attribute_name. See PrimitiveAttributes for valid operations on point attributes.

Returns

Access to the point attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

property point_colours

The colours of the points, represented as a 2d ndarray of RGBA colours. When setting the colour you may use RGB or greyscale colours instead of RGBA colours. The array has one colour for each point. Object.point_colours[i] returns the colour of Object.points[i].

Notes

When the point colours are set, if there are more colours than points then the excess colours are silently ignored. If there are fewer colours than points then uncoloured points are coloured green. If only a single colour is specified, instead of padding with green all of the points are coloured with that colour. i.e.: object.point_colours = [[Red, Green, Blue]] will set all points to be the colour [Red, Green, Blue].

property point_count

The number of points in the object.

property point_selection

A 1D ndarray representing the point selection.

If Object.point_selection[i] = True then Object.point[i] is selected. Object.point_selection[i] = False then Object.point[i] is not selected.

property point_visibility

A 1D ndarray representing the visibility of points.

Object.point_visibility[i] is true if Object.point[i] is visible. It will be False if the point is invisible.

Object.point_visibility[i] = False will make Object.point[i] invisible.

property point_z

The Z coordinates of the points.

Raises

• ValueError – If set using a string which cannot be converted to a float.

• ValueError – If set to a value which cannot be broadcast to the right shape.

• TypeError – If set using a value which cannot be converted to a float.

property points

A 2D ndarray of points of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] Where N is the number of points.

Raises

AttributeError – If attempting to set the points on an object which does not support setting points.

Examples

Create a new point set and set the points:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
... with project.new("cad/test_points", PointSet) as new_points:
...     new_points.points = [[0, 0, 0], [1, 0, 0], [1, 1, 0],
...                          [0, 1, 0], [0, 2, 2], [0, -1, 3]]

Print the second point from the point set defined above.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     print(read_points.points[2])
[1., 1., 0.]

Then set the 2nd point to [1, 2, 3]:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.edit("cad/test_points") as edit_points:
...     edit_points.points[2] = [1, 2, 3]

Iterate over all of the points and print them.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
>>>     for point in read_points.points:
>>>         print(point)
[0., 0., 0.]
[1., 0., 0.]
[1., 2., 3.]
[0., 1., 0.]
[0., 2., 2.]
[0., -1., 3.]

Print all points with y > 0 using numpy. Note that index has one element for each point which will be true if that point has y > 0 and false otherwise. This is then used to retrieve the points with y > 0.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     index = read_points.points[:, 1] > 0
...     print(read_points.points[index])
[[1. 2. 3.]
 [0. 1. 0.]
 [0. 2. 2.]]

property rasters: dict[int, ObjectID[Raster]]

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]

remove_points(point_indices)

Remove one or more points from the object.

Calling this function is preferable to altering the points array because this function also removes the point properties associated with the removed points (e.g. point colours, point visibility, etc).

This operation is performed directly on the Project and will not be undone if an error occurs.

Parameters

point_indices (array_like or int) – The index of the point to remove or a list of indices of points to remove. Any index which is lower than zero or greater than or equal to the point count is ignored (i.e. Passing -1 will not delete the last point).

Returns

If passed a single point index, True if the point was removed and False if it was not removed. If passed an iterable of point indices, True if the object supports removing points and False otherwise.

Return type

bool

Raises

ReadOnlyError – If called on an object not open for editing. This error indicates an issue with the script and should not be caught.

Warning

Any unsaved changes to the object when this function is called are discarded before any points are deleted. If you wish to keep these changes, call save() before calling this function.

Examples

Deleting a point through this function is preferable over removing the point from the points array because this function also deletes the properties associated with the deleted points. For example, all points will remain the same colour after the deletion operation, which points are visible will remain the same, etc. This is shown in the following script:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> red = [255, 0, 0, 255]
>>> blue = [0, 0, 255, 255]
>>> with project.new("cad/deletion_example", PointSet) as point_set:
...     point_set.points = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]
...     point_set.point_colours = [red, red, blue, blue]
...     point_set.point_attributes["attribute"] = [0, 1, 2, 3]
>>> with project.edit(point_set.id) as edit_set:
...     edit_set.remove_points((1, 2))
...     print("points\n", edit_set.points)
...     print("colours\n", edit_set.point_colours)
...     print("attribute\n", edit_set.point_attributes["attribute"])
points
 [[0. 0. 0.]
 [1. 1. 0.]]
colours
 [[255   0   0 255]
 [  0   0 255 255]]
attribute
 [0 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().

save_edge_attribute(attribute_name, data)

Create and/or edit the values of the edge attribute attribute_name.

This is equivalent to Object.edge_attributes[attribute_name] = data

Parameters

• attribute_name (str) – The name of attribute.

• data (array_like) – An array_like of a base type data to store for the attribute per-primitive.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

save_point_attribute(attribute_name, data)

Create and/or edit the values of the point attribute attribute_name.

This is equivalent to Object.point_attributes[attribute_name] = data.

Parameters

• attribute_name (str) – The name of attribute

• data (array_like) – An array_like of length point_count containing the values for attribute_name.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

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 – The name of the object attribute for which the value should be set.

• dtype – 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 – 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.

• 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

class Polyline(object_id=None, lock_type=LockType.READWRITE)

Bases: Edge

A polyline is formed from an ordered sequence of points, where edges are between consecutive points. For example, the first edge is from point 0 to point 1. The second edge is from point 1 to point 2 and so on.

This type is also known as a continuous unclosed line, edge chain or string.

Raises

DegenerateTopologyError – If the Polyline contains fewer than two points when save() is called.

Notes

The edges of a polyline object are implicitly defined by the points. The first edge is between point 0 and point 1, the second edge is between point 1 and point 2 and so on. Because the edges are derived in this way, editing the edges of a polyline is ambiguous and not supported. To change the edges, edit the points instead. If you need to edit or remove edges from a polyline, consider using an EdgeNetwork instead.

Examples

Create a c shape.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polyline
>>> project = Project()
>>> with project.new("cad/c_shape", Polyline) as new_line:
>>>     new_line.points = [[1, 1, 0], [0, 1, 0], [0, 0, 0], [1, 0, 0]]

Create a square. Note that a Polygon would be more appropriate for creating a square as it would not require the last point.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polyline
>>> project = Project()
>>> with project.new("cad/square", Polyline) as new_line:
>>>     new_line.points = [[0, 0, 0], [1, 0, 0], [1, 1, 0],
>>>                        [0, 1, 0], [0, 0, 0]]

property id: ObjectID[Polyline]

Object ID that uniquely references this object in the project.

Returns

The unique id of this object.

Return type

ObjectID

property edges

A 2D Numpy array of edges of the form: [[i0, j0], [i1, j1], …, [iN, jN]] where N is the number of edges and all iK and jK are valid indices in Object.points.

Warning

For Surfaces the edges are derived from the points and facets. If any changes are made to the points or facets, the corresponding changes to the edges will not be made until save() has been called.

Notes

Invalid edges are removed during save().

property edge_count

The count of edges in the object.

classmethod static_type()

Return the type of polyline as stored in a Project.

This can be used for determining if the type of an object is a polyline.

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().

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, preventing any further changes.

property coordinate_system: CoordinateSystem | None

The coordinate system the points of this object are in.

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.

delete_edge_attribute(attribute_name)

Delete a edge attribute by name.

Parameters

attribute_name (str) – The name of attribute

Raises

Exception – If the object is opened in read-only mode.

delete_point_attribute(attribute_name)

Delete a point attribute by name.

This is equivalent to: point_attributes.delete_attribute(attribute_name)

Parameters

attribute_name (str) – The name of attribute

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the primitive type is not supported.

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.

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 edge_attributes

Access to custom edge attributes. These are arrays of values of the same type with one value for each edge.

Use Object.edge_attributes[attribute_name] to access the edge attribute called attribute_name. See PrimitiveAttributes for valid operations on edge attributes.

Returns

Access to the edge attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

Warning

For Surfaces if you have changed the points or facets in the object, you must call save() before accessing the edge attributes.

property edge_colours

The colours of the edges, represented as a numpy array of RGBA colours, with one colour for each edge. When setting the colour you may use RGB or greyscale colours instead.

If there are more edge colours than edges, the excess colours are silently ignored. If there are fewer colours than edges, the uncoloured edges are coloured green. If only a single colour is passed, instead of padding with green all of the edges are coloured with that colour. ie: object.edge_colours = [[Red, Green, Blue]] will set all edge colours to be the colour [Red, Green, Blue].

property edge_selection

A 1D ndarray representing which edges are selected.

edge_selection[i] = True indicates edge i is selected.

property extent: Extent

The axes aligned bounding extent of the object.

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 currently associated with this object.

Returns

The ID of the colour map object or null object ID if there is no colour map.

Return type

ObjectID

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

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 point_attributes

Access the custom point attributes. These are arrays of values of the same type with one value for each point.

Use Object.point_attributes[attribute_name] to access the point attribute called attribute_name. See PrimitiveAttributes for valid operations on point attributes.

Returns

Access to the point attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

property point_colours

The colours of the points, represented as a 2d ndarray of RGBA colours. When setting the colour you may use RGB or greyscale colours instead of RGBA colours. The array has one colour for each point. Object.point_colours[i] returns the colour of Object.points[i].

Notes

When the point colours are set, if there are more colours than points then the excess colours are silently ignored. If there are fewer colours than points then uncoloured points are coloured green. If only a single colour is specified, instead of padding with green all of the points are coloured with that colour. i.e.: object.point_colours = [[Red, Green, Blue]] will set all points to be the colour [Red, Green, Blue].

property point_count

The number of points in the object.

property point_selection

A 1D ndarray representing the point selection.

If Object.point_selection[i] = True then Object.point[i] is selected. Object.point_selection[i] = False then Object.point[i] is not selected.

property point_visibility

A 1D ndarray representing the visibility of points.

Object.point_visibility[i] is true if Object.point[i] is visible. It will be False if the point is invisible.

Object.point_visibility[i] = False will make Object.point[i] invisible.

property point_z

The Z coordinates of the points.

Raises

• ValueError – If set using a string which cannot be converted to a float.

• ValueError – If set to a value which cannot be broadcast to the right shape.

• TypeError – If set using a value which cannot be converted to a float.

property points

A 2D ndarray of points of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] Where N is the number of points.

Raises

AttributeError – If attempting to set the points on an object which does not support setting points.

Examples

Create a new point set and set the points:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
... with project.new("cad/test_points", PointSet) as new_points:
...     new_points.points = [[0, 0, 0], [1, 0, 0], [1, 1, 0],
...                          [0, 1, 0], [0, 2, 2], [0, -1, 3]]

Print the second point from the point set defined above.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     print(read_points.points[2])
[1., 1., 0.]

Then set the 2nd point to [1, 2, 3]:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.edit("cad/test_points") as edit_points:
...     edit_points.points[2] = [1, 2, 3]

Iterate over all of the points and print them.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
>>>     for point in read_points.points:
>>>         print(point)
[0., 0., 0.]
[1., 0., 0.]
[1., 2., 3.]
[0., 1., 0.]
[0., 2., 2.]
[0., -1., 3.]

Print all points with y > 0 using numpy. Note that index has one element for each point which will be true if that point has y > 0 and false otherwise. This is then used to retrieve the points with y > 0.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     index = read_points.points[:, 1] > 0
...     print(read_points.points[index])
[[1. 2. 3.]
 [0. 1. 0.]
 [0. 2. 2.]]

property rasters: dict[int, ObjectID[Raster]]

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]

remove_points(point_indices)

Remove one or more points from the object.

Calling this function is preferable to altering the points array because this function also removes the point properties associated with the removed points (e.g. point colours, point visibility, etc).

This operation is performed directly on the Project and will not be undone if an error occurs.

Parameters

point_indices (array_like or int) – The index of the point to remove or a list of indices of points to remove. Any index which is lower than zero or greater than or equal to the point count is ignored (i.e. Passing -1 will not delete the last point).

Returns

If passed a single point index, True if the point was removed and False if it was not removed. If passed an iterable of point indices, True if the object supports removing points and False otherwise.

Return type

bool

Raises

ReadOnlyError – If called on an object not open for editing. This error indicates an issue with the script and should not be caught.

Warning

Any unsaved changes to the object when this function is called are discarded before any points are deleted. If you wish to keep these changes, call save() before calling this function.

Examples

Deleting a point through this function is preferable over removing the point from the points array because this function also deletes the properties associated with the deleted points. For example, all points will remain the same colour after the deletion operation, which points are visible will remain the same, etc. This is shown in the following script:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> red = [255, 0, 0, 255]
>>> blue = [0, 0, 255, 255]
>>> with project.new("cad/deletion_example", PointSet) as point_set:
...     point_set.points = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]
...     point_set.point_colours = [red, red, blue, blue]
...     point_set.point_attributes["attribute"] = [0, 1, 2, 3]
>>> with project.edit(point_set.id) as edit_set:
...     edit_set.remove_points((1, 2))
...     print("points\n", edit_set.points)
...     print("colours\n", edit_set.point_colours)
...     print("attribute\n", edit_set.point_attributes["attribute"])
points
 [[0. 0. 0.]
 [1. 1. 0.]]
colours
 [[255   0   0 255]
 [  0   0 255 255]]
attribute
 [0 3]

save_edge_attribute(attribute_name, data)

Create and/or edit the values of the edge attribute attribute_name.

This is equivalent to Object.edge_attributes[attribute_name] = data

Parameters

• attribute_name (str) – The name of attribute.

• data (array_like) – An array_like of a base type data to store for the attribute per-primitive.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

save_point_attribute(attribute_name, data)

Create and/or edit the values of the point attribute attribute_name.

This is equivalent to Object.point_attributes[attribute_name] = data.

Parameters

• attribute_name (str) – The name of attribute

• data (array_like) – An array_like of length point_count containing the values for attribute_name.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

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 – The name of the object attribute for which the value should be set.

• dtype – 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 – 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.

• 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

class Polygon(object_id=None, lock_type=LockType.READWRITE)

Bases: Edge

A polygon is formed from an ordered sequence of points, with edges between consecutive points. For example, the first edge is between point 0 and point 1, the second edge is between point 1 and point 2 and the final edge is between point n - 1 and point 0 (where n is the number of points). Unlike an Polyline, a Polygon is a closed loop of edges.

Also known as a closed line or edge loop.

See also

Edge

Parent class of Polygon

EdgeNetwork

Class which supports editing edges.

Notes

The edges of a polygon are implicitly defined by the points. For a polygon with n edges, the first edge is between points 0 and 1, the second edge is between points 1 and 2, and the final edge is between points n - 1 and 0. Because the edges are derived from the points, editing the edges is not supported - you should edit the points instead. If you need to edit or remove edges without changing points consider using an EdgeNetwork instead.

Raises

DegenerateTopologyError – If the Polygon contains fewer than three points when save() is called.

Examples

Create a diamond

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polygon
>>> project = Project()
>>> with project.new("cad/polygon_diamond", Polygon) as new_diamond:
>>>     new_diamond.points = [[1, 0, 0], [0, 1, 0], [1, 2, 0], [2, 1, 0]]

property id: ObjectID[Polygon]

Object ID that uniquely references this object in the project.

Returns

The unique id of this object.

Return type

ObjectID

property edges

A 2D Numpy array of edges of the form: [[i0, j0], [i1, j1], …, [iN, jN]] where N is the number of edges and all iK and jK are valid indices in Object.points.

Warning

For Surfaces the edges are derived from the points and facets. If any changes are made to the points or facets, the corresponding changes to the edges will not be made until save() has been called.

Notes

Invalid edges are removed during save().

property edge_count

The count of edges in the object.

classmethod static_type()

Return the type of polygon as stored in a Project.

This can be used for determining if the type of an object is a polygon.

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().

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, preventing any further changes.

property coordinate_system: CoordinateSystem | None

The coordinate system the points of this object are in.

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.

delete_edge_attribute(attribute_name)

Delete a edge attribute by name.

Parameters

attribute_name (str) – The name of attribute

Raises

Exception – If the object is opened in read-only mode.

delete_point_attribute(attribute_name)

Delete a point attribute by name.

This is equivalent to: point_attributes.delete_attribute(attribute_name)

Parameters

attribute_name (str) – The name of attribute

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the primitive type is not supported.

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.

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 edge_attributes

Access to custom edge attributes. These are arrays of values of the same type with one value for each edge.

Use Object.edge_attributes[attribute_name] to access the edge attribute called attribute_name. See PrimitiveAttributes for valid operations on edge attributes.

Returns

Access to the edge attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

Warning

For Surfaces if you have changed the points or facets in the object, you must call save() before accessing the edge attributes.

property edge_colours

The colours of the edges, represented as a numpy array of RGBA colours, with one colour for each edge. When setting the colour you may use RGB or greyscale colours instead.

If there are more edge colours than edges, the excess colours are silently ignored. If there are fewer colours than edges, the uncoloured edges are coloured green. If only a single colour is passed, instead of padding with green all of the edges are coloured with that colour. ie: object.edge_colours = [[Red, Green, Blue]] will set all edge colours to be the colour [Red, Green, Blue].

property edge_selection

A 1D ndarray representing which edges are selected.

edge_selection[i] = True indicates edge i is selected.

property extent: Extent

The axes aligned bounding extent of the object.

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 currently associated with this object.

Returns

The ID of the colour map object or null object ID if there is no colour map.

Return type

ObjectID

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

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 point_attributes

Access the custom point attributes. These are arrays of values of the same type with one value for each point.

Use Object.point_attributes[attribute_name] to access the point attribute called attribute_name. See PrimitiveAttributes for valid operations on point attributes.

Returns

Access to the point attributes.

Return type

PrimitiveAttributes

Raises

ValueError – If the type of the attribute is not supported.

property point_colours

The colours of the points, represented as a 2d ndarray of RGBA colours. When setting the colour you may use RGB or greyscale colours instead of RGBA colours. The array has one colour for each point. Object.point_colours[i] returns the colour of Object.points[i].

Notes

When the point colours are set, if there are more colours than points then the excess colours are silently ignored. If there are fewer colours than points then uncoloured points are coloured green. If only a single colour is specified, instead of padding with green all of the points are coloured with that colour. i.e.: object.point_colours = [[Red, Green, Blue]] will set all points to be the colour [Red, Green, Blue].

property point_count

The number of points in the object.

property point_selection

A 1D ndarray representing the point selection.

If Object.point_selection[i] = True then Object.point[i] is selected. Object.point_selection[i] = False then Object.point[i] is not selected.

property point_visibility

A 1D ndarray representing the visibility of points.

Object.point_visibility[i] is true if Object.point[i] is visible. It will be False if the point is invisible.

Object.point_visibility[i] = False will make Object.point[i] invisible.

property point_z

The Z coordinates of the points.

Raises

• ValueError – If set using a string which cannot be converted to a float.

• ValueError – If set to a value which cannot be broadcast to the right shape.

• TypeError – If set using a value which cannot be converted to a float.

property points

A 2D ndarray of points of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] Where N is the number of points.

Raises

AttributeError – If attempting to set the points on an object which does not support setting points.

Examples

Create a new point set and set the points:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
... with project.new("cad/test_points", PointSet) as new_points:
...     new_points.points = [[0, 0, 0], [1, 0, 0], [1, 1, 0],
...                          [0, 1, 0], [0, 2, 2], [0, -1, 3]]

Print the second point from the point set defined above.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     print(read_points.points[2])
[1., 1., 0.]

Then set the 2nd point to [1, 2, 3]:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.edit("cad/test_points") as edit_points:
...     edit_points.points[2] = [1, 2, 3]

Iterate over all of the points and print them.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
>>>     for point in read_points.points:
>>>         print(point)
[0., 0., 0.]
[1., 0., 0.]
[1., 2., 3.]
[0., 1., 0.]
[0., 2., 2.]
[0., -1., 3.]

Print all points with y > 0 using numpy. Note that index has one element for each point which will be true if that point has y > 0 and false otherwise. This is then used to retrieve the points with y > 0.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.read("cad/test_points") as read_points:
...     index = read_points.points[:, 1] > 0
...     print(read_points.points[index])
[[1. 2. 3.]
 [0. 1. 0.]
 [0. 2. 2.]]

property rasters: dict[int, ObjectID[Raster]]

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]

remove_points(point_indices)

Remove one or more points from the object.

Calling this function is preferable to altering the points array because this function also removes the point properties associated with the removed points (e.g. point colours, point visibility, etc).

This operation is performed directly on the Project and will not be undone if an error occurs.

Parameters

point_indices (array_like or int) – The index of the point to remove or a list of indices of points to remove. Any index which is lower than zero or greater than or equal to the point count is ignored (i.e. Passing -1 will not delete the last point).

Returns

If passed a single point index, True if the point was removed and False if it was not removed. If passed an iterable of point indices, True if the object supports removing points and False otherwise.

Return type

bool

Raises

ReadOnlyError – If called on an object not open for editing. This error indicates an issue with the script and should not be caught.

Warning

Any unsaved changes to the object when this function is called are discarded before any points are deleted. If you wish to keep these changes, call save() before calling this function.

Examples

Deleting a point through this function is preferable over removing the point from the points array because this function also deletes the properties associated with the deleted points. For example, all points will remain the same colour after the deletion operation, which points are visible will remain the same, etc. This is shown in the following script:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> red = [255, 0, 0, 255]
>>> blue = [0, 0, 255, 255]
>>> with project.new("cad/deletion_example", PointSet) as point_set:
...     point_set.points = [[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]
...     point_set.point_colours = [red, red, blue, blue]
...     point_set.point_attributes["attribute"] = [0, 1, 2, 3]
>>> with project.edit(point_set.id) as edit_set:
...     edit_set.remove_points((1, 2))
...     print("points\n", edit_set.points)
...     print("colours\n", edit_set.point_colours)
...     print("attribute\n", edit_set.point_attributes["attribute"])
points
 [[0. 0. 0.]
 [1. 1. 0.]]
colours
 [[255   0   0 255]
 [  0   0 255 255]]
attribute
 [0 3]

save_edge_attribute(attribute_name, data)

Create and/or edit the values of the edge attribute attribute_name.

This is equivalent to Object.edge_attributes[attribute_name] = data

Parameters

• attribute_name (str) – The name of attribute.

• data (array_like) – An array_like of a base type data to store for the attribute per-primitive.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

save_point_attribute(attribute_name, data)

Create and/or edit the values of the point attribute attribute_name.

This is equivalent to Object.point_attributes[attribute_name] = data.

Parameters

• attribute_name (str) – The name of attribute

• data (array_like) – An array_like of length point_count containing the values for attribute_name.

Raises

• Exception – If the object is opened in read-only mode.

• ValueError – If the type of the attribute is not supported.

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 – The name of the object attribute for which the value should be set.

• dtype – 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 – 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.

• 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