mapteksdk.data.points module

Point data types.

This module contains data types where the most complicated primitive they use is points. Though many other objects use points, the types defined here only use points.

Currently there is only one such data type (PointSet).

class PointSet(object_id=None, lock_type=LockType.READWRITE)

Bases: PointProperties, PointDeletionProperties, Topology

A pointset is a set of three dimensional points.

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_point_attribute(attribute_name)

Delete a point attribute by name.

This is equivalent to: point_attributes.delete_attribute(attribute_name)

Parameters:: attribute_name (str | AttributeKey) – The name or key of the attribute.

dissociate_raster(raster)

Removes the raster from the object.

If an error occurs after dissociating a raster resulting in save() not being called, the dissociation of the raster can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Dissociating a raster 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 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 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 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 point_attributes: PrimitiveAttributes

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: ColourArray

The colour of each point in RGBA.

This is a numpy array of shape (N, 4) where N is the point count.

Examples

To get the colour of the ith point:

>>> point_i_colour = point_set.point_colours[i]

To get the red, green, blue and alpha components of the ith point:

>>> red, green, blue, alpha = point_set.point_colours[i]

property point_count: int: The number of points in this object.

property point_selection: BooleanArray

An array which indicates which points have been selected.

This is an array of booleans of shape (N,) where N is the point count. If the ith element in this array is True, then the ith point is selected. If the ith element in this array is False, then the ith point is not selected.

Examples

To get if the ith point is selected:

>>> point_i_selected = point_set.point_selection[i]

The point selection can be used to filter the arrays of other per-point properties down to only include the values of selected points. The following snippet demonstrates getting the colours of only the selected points in an object:

>>> selected_colours = point_set.point_colours[point_set.point_selection]

property point_visibility: BooleanArray

An array which indicates which points are visible.

This is an array of booleans of shape (N,) where N is the point count. If the ith element in this array is True, then the ith point is visible. If the ith element in this array is False, then the ith point is invisible.

Examples

To get if the ith point is visible:

>>> point_i_visible = point_set.point_visibility[i]

The point visibility can be used to filter the arrays of other per-point properties down to only include the values of visible points. The following snippet demonstrates getting the colours of only the visible points in an object:

>>> visible_colours = point_set.point_colours[point_set.point_visibility]

property point_z: FloatArray

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: PointArray

The three dimensional points in the object.

This is a numpy array of shape (N, 3) where N is the point count. This is of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]]

To get the ith point:

>>> point_i = point_set.points[i]

Similarly, to get the x, y and z coordinates of the ith point:

>>> x, y, z = point_set.points[i]

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.]]

To add a new point to a PointSet, the numpy row_stack function can be used. This is demonstrated by the following example which creates a point set and then opens it for editing and adds an extra point. The original points are coloured blue and the new point is coloured red.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> import numpy as np
>>> if __name__ == "__main__":
...   with Project() as project:
...     with project.new("cad/append_single_example", PointSet
...         ) as point_set:
...       point_set.points = [
...         [-1, -1, 0], [1, -1, 0], [-1, 1, 0], [1, 1, 0]
...       ]
...       point_set.point_colours = [0, 0, 255, 255]
...     with project.edit(point_set.id) as edit_set:
...       edit_set.points = np.row_stack((edit_set.points, [0, 0, 1]))
...       edit_set.point_colours[-1] = [255, 0, 0, 255]

The row stack function can also be used to add multiple points to an object at once, as demonstrated in the following example:

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> import numpy as np
>>> if __name__ == "__main__":
...   original_points = [[-1, -1, 1], [1, -1, 1], [-1, 1, 1], [1, 1, 1]]
...   new_points = [[-1, -1, 2], [1, -1, 2], [-1, 1, 2], [1, 1, 2]]
...       with Project() as project:
...     with project.new("cad/append_multiple_example", PointSet
...         ) as point_set:
...       point_set.points = original_points
...       point_set.point_colours = [0, 0, 255, 255]
...     with project.edit(point_set.id) as edit_set:
...       original_point_count = edit_set.point_count
...       edit_set.points = np.row_stack((edit_set.points, new_points))
...       new_point_count = edit_set.point_count
...       edit_set.point_colours[
...         original_point_count:new_point_count] = [255, 0, 0, 255]

The row stack function can combine more than two point arrays if required by adding additional arrays to the tuple passed to the function. This is demonstrated by the following example, which creates a new point set containing the points from the point sets in the previous two examples plus a third set of points defined in the script. Make sure to run the previous two examples before running this one.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> import numpy as np
>>> if __name__ == "__main__":
...   extra_points = [[-2, -2, 3], [2, -2, 3], [-2, 2, 3], [2, 2, 3]]
...   with Project() as project:
...     with project.new("cad/triple_point_stack", PointSet) as new_set, \
...         project.read("cad/append_single_example") as single_set, \
...         project.read("cad/append_multiple_example") as multiple_set:
...       new_set.points = np.row_stack((
...         extra_points,
...         single_set.points,
...         multiple_set.points
...       ))

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]

remove_coordinate_system()

Remove the coordinate system from the object.

This does not change the geometry of the object. It only clears the label which states what coordinate system the object is in.

This has no effect if the object does not have a coordinate system.

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 (int | Sequence[int]) – The index of the point to remove or a list of indices of points to remove. Indices should only contain 32-bit unsigned integer (They should be greater than or equal to 0 and less than 2**32). Any index greater than or equal to the point count is ignored. Passing an index less than zero is not supported. It 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().

Returns:: The change reasons for the operation. This depends on what changes to the object were saved. If the api_version is less than 1.9, this always returns ChangeReasons.NO_CHANGE.
Return type:: ChangeReasons

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.

Saving a point attribute using an AttributeKey allows for additional metadata to be specified.

Parameters:

attribute_name (str | AttributeKey) – The name or key of the attribute.
data (npt.ArrayLike) – An array_like of length point_count containing the values for attribute_name.

Raises:

ValueError – If the type of the attribute is not supported.
AmbiguousNameError – If there is already an attribute with the same name, but with different metadata.

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, bool, int, float, str]] | 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.

Notes

If an error occurs after adding a new object attribute or editing an existing object attribute resulting in save() not being called, the changes to the object attributes can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Adding new object attributes, or editing the values of object attributes, will not be undone if an error occurs.

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 point set as stored in a Project.

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

property id: ObjectID[PointSet]

Object ID that uniquely references this object in the project.

Returns:: The unique id of this object.
Return type:: ObjectID

dataframe(save_changes=True, attributes=None, include_colours=True, include_visibility=True, include_selection=True)

Context managed representation of the PointSet as a Pandas Dataframe.

Parameters:

save_changes (bool) – If save_changes = False then any changes to the data frame will not be propagated to the point set. If save_changes = True (default) and the point set is opened for editing, all changes made to the dataframe will be propagated to the point set when the with block finishes. This is ignored if the point set is opened in read mode - in that case changes to the dataframe will never be made to the point set.
attributes (iterable) – List of names of point attributes to include as extra columns in the DataFrame. If None (default) all existing point properties are included in the dataframe. For better performance, only include the point attributes you want in the DataFrame.
include_colours (bool) – If True (default), the point colours will be included in the dataframe as the “R”, “G”, “B” and “A” columns. If False, the point colours will not be included in the dataframe (And thus the dataframe will not have the “R”, “G”, “B”, “A” columns). Setting this to False is more efficient than dropping these columns from the dataframe.
include_visibility (bool) – If True (default), the point visibility will be included in the dataframe as the “Visible” column. If False, the point visibility will not be included and the dataframe will not have a “Visible” column. Setting this to False is more efficient than dropping this column from the dataframe.
include_selection (bool) – If True (default), the point selection will be included in the dataframe as the “Selected” column. If False, the point selection will not be included and the dataframe will not have a “Selected” column. Setting this to False is more efficient than dropping this column from the dataframe.

Yields:

pandas.DataFrame – DataFrame representing the PointSet. Columns include: [‘X’, ‘Y’, ‘Z’, ‘R’, ‘G’, ‘B’, ‘A’, ‘Visible’, ‘Selected’] Any point attributes included in the DataFrame are inserted after Selected.

Raises:

KeyError – If attributes contains an attribute name which doesn’t exist.
KeyError – If the X, Y or Z columns of the data frame are dropped.

Notes

If save_changes is True, dropping the R, G or B column will cause the red, green or blue component of the colour to be set to 0. Dropping the A column will cause the alpha of all points to be set to 255. Dropping the Visible column will cause all points to be set to be visible. Dropping the Selected column will cause all points to be set to be not selected. Dropping a primitive attribute column will cause that primitive attribute to be deleted.

Examples

Use pandas to hide all points with Z less than 15.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.new("cad/my_points", PointSet) as new_set:
...     new_set.points = [[1, 2, 3], [5, 5, 16], [-1, -6, -16]]
...     with new_set.dataframe() as frame:
...         frame.loc[frame.Z < 15, "Visible"] = False
>>>     print(new_set.point_visibility)
[False True False]

Calculate and print the mean ‘redness’ of points using pandas.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.new("cad/my_other_points", PointSet) as new_set:
...     new_set.points = [[1, 2, 3], [5, 5, 16], [-1, -6, -16]]
...     new_set.point_colours = [[100, 0, 0], [150, 0, 0], [200, 50, 50]]
>>> with project.read("cad/my_other_points") as read_set:
...     with read_set.dataframe() as frame:
...         print(frame.loc[:, 'R'].mean())
150.0

Populate a point property with if the x value of the point is negative or positive.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.new("cad/positive_points", PointSet) as new_set:
...     new_set.points = [[-1, 3, 9], [1, 4, -5], [-5, 2, 3]]
...     new_set.point_attributes['negative_x'] = [False] * 3
...     with new_set.dataframe() as frame:
...         frame.loc[frame.X < 0, 'negative_x'] = True
...         frame.loc[frame.X >= 0, 'negative_x'] = False
...     print(new_set.point_attributes['negative_x'])
[True False True]

When extracting the values of points as a pandas dataframe, you can set it to not save changes. This way you can make changes to the Dataframe without changing the original point set. In the below example, all points with red greater than or equal to 200 have their red set to zero in the dataframe and prints them. However when the with statement ends, the points are left unchanged - when the points colours are printed, they are the same as before the dataframe. Use this to work with a temporary copy of your data.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import PointSet
>>> project = Project()
>>> with project.new("cad/my_nice_points", PointSet) as new_set:
...     new_set.points = [[1, 2, 3], [5, 5, 16], [-1, -6, -16]]
...     new_set.point_colours = [[100, 0, 0], [150, 0, 0], [200, 50, 50]]
...     with new_set.dataframe(save_changes=False) as frame:
...         frame.loc[frame.R >= 200, 'R'] = 0
...         print(frame.loc[:, 'R'])
...     print(new_set.point_colours)
0    100
1    150
2      0
Name: R, dtype: uint8
[[100   0   0 255]
 [150   0   0 255]
 [200  50  50 255]]