mapteksdk.data.scans module

Scan data types.

This contains data types designed for representing data from LiDAR scanners. Currently, this only includes the generic Scan class, but may be expanded in the future to support other types of scans.

class Scan(object_id=None, lock_type=LockType.READWRITE, *, dimensions=None, point_validity=None)

Bases: Topology, PointProperties, CellProperties, RotationMixin

Class optimised for storing scans made by 3D laser scanners.

The Cartesian points of a scan are derived from the point_ranges, vertical_angles and the horizontal_angles.

When a scan is created you can populate the points instead of the point_ranges, vertical_angles and horizontal_angles. If you populate both then the point_ranges, vertical_angles and horizontal_angles will be ignored in favour of the points.

When a scan is created if the dimensions parameter is not specified, then it is considered to have one row with point_count columns and all points within the scan are considered valid. This is the simplest method of creating a scan; however, such scans have no cells.

If the dimensions parameter is specified to be (major_dimension_count, minor_dimension_count) but the point_validity parameter is not specified, then the points of the scan are expected to be arranged in a grid with the specified number of major and minor dimensions and all points in the grid should be finite. Scans created by the SDK are always row-major. The major dimension count should always correspond to the row count and the minor dimension count should always correspond to the column count.

If the dimensions parameter is specified to be (major_dimension_count, minor_dimension_count) and the point_validity parameter is specified and contains a non-true value, then some of the points in the underlying cell network are considered invalid.

Scans possess three types of properties:

Point properties.
Cell properties.
Cell point properties.

Point properties are associated with the valid points. They start with ‘point’ and have point_count values - one value for each valid point.

Cell properties start with ‘cell’ and should have cell_count values - one value for each cell in the scan. All cell property arrays will return a zero-length array before save() has been called.

Cell point properties are a special type of cell and point properties. They start with ‘cell_point’ (with the exclusion of horizontal_angles and vertical_angles) and have cell_point_count values - one value for each point in the underlying cell network, including invalid points.

Parameters

dimensions (Iterable) – Iterable containing two integers representing the major and minor dimension counts of the cell network. If specified, the points of the scan are expected to be organised in a grid with the specified number of major and minor dimensions. If this is not specified, then the scan is considered to have one row with an unspecified number of columns. In this case, the column count is determined as soon as either the points, ranges, horizontal angles or vertical angles is set.
point_validity (numpy.ndarray) – Array of length major_dimension_count * minor_dimension_count of booleans. True indicates the point is valid, False indicates the point is invalid. If None (default), all points are considered valid.

Raises

DegenerateTopologyError – If a value in dimensions is lower than 1.
ValueError – If a value in dimensions cannot be converted to an integer.
ValueError – If a value in point_validity cannot be converted to a bool.
ValueError – If point_validity does not have one value for each point.
TypeError – If dimensions is not iterable.
RuntimeError – If point_validity is specified but dimensions is not.

Warning

Creating a scan using Cartesian points will result in a loss of precision. The final points of the scan will not be exactly equal to the points used to create the scan.

See also

mapteksdk.data.points.PointSet: Accurate storage for Cartesian points.
scan: Help page for this class.

Notes

Editing the points property of a scan is only possible on new scans. Attempting to edit this array on a non-new scan will raise an error. Because scans have different behaviour when opened with project.new() versus project.edit(), you should never open a scan with project.new_or_edit().

Rotating a scan does not change the horizontal_angles, vertical_angles or point ranges. Once save() is called the rotation will be applied to the cartesian points of the scan.

Examples

Create a scan using Cartesian coordinates. Note that when the points are read from the scan, they will not be exactly equal to the points used to create the scan.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> with project.new("scans/cartesian_scan", Scan) as new_scan:
>>>     new_scan.points = [[1, 2, 4], [3, 5, 7], [6, 8, 9]]

Create a scan using spherical coordinates.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> with project.new("scans/spherical_scan", Scan) as new_scan:
>>>     new_scan.point_ranges = [2, 16, 34, 12]
>>>     new_scan.horizontal_angles = [3 * math.pi / 4, math.pi / 4,
>>>                                   -math.pi / 4, - 3 * math.pi / 4]
>>>     new_scan.vertical_angles = [math.pi / 4] * 4
>>>     new_scan.max_range = 50
>>>     new_scan.intensity = [256, 10000, 570, 12]
>>>     new_scan.origin = [-16, 16, -16]

Create a scan with the dimensions of the scan specified. This example creates a scan with four rows and five columns of points which form three rows and four columns of cells. Unlike the above two examples, this scan has cells and after save() has been called, its cell properties can be accessed.

>>> import numpy as np
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> dimensions = (4, 5)
>>> # Each line represents one row of points in the scan.
>>> ranges = [10.8, 11.2, 10.7, 10.6, 10.8,
...           9.3, 10.3, 10.8, 10.6, 11.1,
...           9.2, 10.9, 10.7, 10.7, 10.9,
...           9.5, 11.2, 10.6, 10.6, 11.0]
>>> horizontal_angles = [-20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20]
>>> vertical_angles = [-20, -20, -20, -20, -20,
...                    -10, -10, -10, -10, -10,
...                    0, 0, 0, 0, 0,
...                    10, 10, 10, 10, 10]
>>> with project.new("scans/example", Scan(dimensions=dimensions),
...         overwrite=True) as example_scan:
...     example_scan.point_ranges = ranges
...     example_scan.horizontal_angles = np.deg2rad(horizontal_angles)
...     example_scan.vertical_angles = np.deg2rad(vertical_angles)
...     example_scan.origin = [0, 0, 0]
>>> # Make all cells visible.
>>> with project.edit(example_scan.id) as edit_scan:
>>>     edit_scan.cell_visibility[:] = True

If the dimensions of a scan are specified, the point_validity can also be specified. For any value where the point_validity is false, values for point properties (such as point_range) are not stored.

>>> import numpy as np
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> dimensions = (5, 5)
>>> # Each line represents one row of points in the scan.
>>> # Note that rows containing invalid points have fewer values.
>>> ranges = [10.7, 10.6, 10.8,
...           10.3, 10.8, 10.6,
...           9.2, 10.9, 10.7, 10.7, 10.9,
...           9.5, 11.2, 10.6, 10.6,
...           9.1, 9.4, 9.2]
>>> horizontal_angles = [-20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,]
>>> vertical_angles = [-20, -20, -20, -20, -20,
...                    -10, -10, -10, -10, -10,
...                    0, 0, 0, 0, 0,
...                    10, 10, 10, 10, 10,
...                    20, 20, 20, 20, 20,]
>>> point_validity = [False, False, True, True, True,
...                   False, True, True, True, False,
...                   True, True, True, True, True,
...                   True, True, True, True, False,
...                   True, True, True, False, False]
>>> with project.new("scans/example_with_invalid", Scan(
...         dimensions=dimensions, point_validity=point_validity
...         ), overwrite=True) as example_scan:
...     example_scan.point_ranges = ranges
...     example_scan.horizontal_angles = np.deg2rad(horizontal_angles)
...     example_scan.vertical_angles = np.deg2rad(vertical_angles)
...     example_scan.origin = [0, 0, 0]
>>> # Make all cells visible.
>>> with project.edit(example_scan.id) as edit_scan:
...     edit_scan.cell_visibility[:] = True

classmethod static_type()

Return the type of scan as stored in a Project.

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

property id: ObjectID[Scan]

Object ID that uniquely references this object in the project.

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

property cells

This property maps the cells to the points which define them.

Use this to refer to the points which define the four corners of a cell.

This is a numpy array of shape (n, 4) where n is the cell count. If cells[i] is [a, b, c, d] then the four corner points of the ith cell are points[a], points[b], points[c] and points[d].

Notes

Sparse cell objects (such as Scans) may contain cells with point indices of -1. These represent invalid points. In the future, this may be changed to be a masked array instead.

Examples

This example creates a GridSurface object with 3 rows and 3 columns of points and prints the cells. Then it prints the four points which define the first cell (index 0).

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/small_square", GridSurface(
...         major_dimension_count=3, minor_dimension_count=3,
...         x_step=0.1, y_step=0.1)) as small_square:
...     print("Cells:")
...     print(small_square.cells)
...     print("The points which define the first cell are:")
...     for index in small_square.cells[0]:
...         print(f"Point {index}:", small_square.points[index])
Cells:
[[0 3 4 1]
 [1 4 5 2]
 [3 6 7 4]
 [4 7 8 5]]
The points which define the first cell are:
Point 0: [0. 0. 0.]
Point 3: [0.3 0.  0. ]
Point 4: [0.  0.1 0. ]
Point 1: [0.1 0.  0. ]

property point_count

Returns the number of points.

For scans, point_count returns the number of valid points in the scan. If the scan contains invalid points then this will be less than cell_point_count.

property point_ranges

The distance of the points from the scan origin.

This has one value per valid point.

Any range value greater than max_range() will be set to max_range() when save() is called.

Raises

ReadOnlyError – If attempting to edit while they are read-only.
ValueError – If new value cannot be converted to a np.array of 32-bit floats.
ValueError – If dimensions was passed to the constructor and the number of ranges is set to be not equal to the point_count.

Warning

When creating a new scan, you should either set the points or the ranges, vertical angles and horizontal angles. If you set both, the points will be saved and the ranges ignored.

property horizontal_angles

The horizontal angles of the points from the scan origin.

This is the azimuth of each point (including invalid points) measured clockwise from the Y axis.

The horizontal angles can only be set when the scan is first created. Once save() has been called they become read-only.

Raises

ReadOnlyError – If attempting to edit while they are read-only.
ValueError – If new value cannot be converted to a np.array of 32 bit floats.
ValueError – If dimensions was passed to the constructor and this is set to a value with less than cell_point_count values.

Warning

When creating a new scan, you should either set the points or set the ranges, vertical angles and horizontal angles. If you set both, the points will be saved and the ranges ignored.

Notes

Technically this should be cell_point_horizontal_angles, however it has been shortened to horizontal_angles. This should have cell_point_count values.

This array contains values for invalid points, however the value for an invalid point is unspecified and may be NAN (Not A Number). It is not recommended to use invalid angles in algorithms.

property vertical_angles

The vertical angles of the points from the scan origin.

This is the elevation angle in the spherical coordinate system.

The vertical_angles can only be set when the scan is first created. Once save() has been called they become read-only.

Raises

ReadOnlyError – If attempting to edit when the vertical angles are read-only.
ValueError – If new value cannot be converted to a np.array of 32 bit floats.
ValueError – If dimensions was passed to the constructor and this is set to a value with less than cell_point_count values.

Warning

When creating a new scan, you should either set the points or set the ranges, vertical angles and horizontal angles. If you set both, the points will be saved and the vertical angles ignored.

Notes

Technically this should be cell_point_vertical_angles, however it has been shortened to vertical_angles. This should have cell_point_count values.

This array contains values for invalid points, however the value for an invalid point is unspecified and may be NAN (Not A Number). It is not recommended to use invalid angles in algorithms.

property major_dimension_count

The major dimension count of the Cell Network.

If the inheriting object is stored in row major order, then this will correspond to the row count. If stored in column major order then this will correspond to the column count.

property minor_dimension_count

The major dimension count of the Cell Network.

If the inheriting object is stored in row major order, then this will correspond to the column count. If stored in column major order then this will correspond to the row count.

property row_count

The number of rows in the underlying cell network.

Note that this is the logical count of the rows. This will only correspond to the major dimension for the underlying array if is_column_major() returns false.

property column_count

The number of columns in the underlying cell network.

Note that this is the logical count of the columns. This will only correspond to the minor dimension for the underlying array if is_column_major() returns false.

property origin

The origin of the scan represented as a point.

This should be set to the location of the scanner when the scan was taken (if known).

When creating a scan using Cartesian coordinates, if the origin is not set it will default to the centroid of the points. Changing the origin in this case will not change the points.

When creating a scan using point_range, horizontal_angles and vertical_angles the origin will default to [0, 0, 0]. Changing the origin in this case will cause the points to be centred around the new origin.

Editing the origin will translate the scan by the difference between the new origin and the old origin.

Notes

Points which are far away from the origin may suffer precision issues.

Examples

Set the origin of a scan creating using ranges and angles and print the points. The origin is set to [1, 1, 1] so the final points are translated by [1, 1, 1].

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> with project.new("scans/angle_scan", Scan) as new_scan:
...     new_scan.point_ranges = [1, 1, 1, 1]
...     new_scan.horizontal_angles = [math.pi / 4, math.pi * 0.75,
...                                   -math.pi / 4, -math.pi * 0.75]
...     new_scan.vertical_angles = [0, 0, 0, 0]
...     new_scan.origin = [1, 1, 1]
>>> with project.read("scans/angle_scan") as read_scan:
...     print(read_scan.points)
[[1.70710668 1.70710688 1.00000019]
 [1.70710681 0.29289325 1.00000019]
 [0.29289332 1.70710688 1.00000019]
 [0.29289319 0.29289325 1.00000019]]

Unlike for spherical coordinates, Cartesian coordinates are round tripped. This means that setting the origin in new() will not translate the points.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> with project.new("scans/point_scan", Scan) as new_scan:
...     new_scan.points = [[1, 1, 1], [-1, 1, 2], [1, -1, 3], [-1, -1, 4]]
...     new_scan.origin = [2, 2, 2]
>>> with project.read("scans/point_scan") as read_scan:
...     print(read_scan.points)
[[ 0.99999997  1.00000006  1.00000008]
 [-1.00000002  1.0000001   2.00000059]
 [ 0.99999975 -1.00000013  2.99999981]
 [-1.00000004 -0.99999976  4.00000031]]

However changing the origin in edit will always translate the points. By changing the origin from [2, 2, 2] to [-2, -2, -2] the x, y and z coordinates of the scan are each reduced by four.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("scans/point_scan") as edit_scan:
...     edit_scan.origin = [-2, -2, -2]
>>> with project.read("scans/point_scan") as read_scan:
...     print(read_scan.points)
[[-3.00000003 -2.99999994 -2.99999992]
 [-5.00000002 -2.9999999  -1.99999941]
 [-3.00000025 -5.00000013 -1.00000019]
 [-5.00000004 -4.99999976  0.00000031]]

property max_range

The maximum range of the generating scanner.

This is used to normalise the ranges to allow for more compact storage. Any point further away from the origin will have its range set to this value when save() is called.

If this is not set when creating a new scan, it will default to the maximum distance of any point from the origin.

This can only be set for new scans.

Raises: ReadOnlyError – If user attempts to set when this value is read-only.

property cell_point_validity

Which points in the underlying cell network are valid.

A value of True indicates the point is valid and will appear in the points array. A value of False indicates the point is invalid and it will not appear in the points array.

Invalid points are not stored and thus do not require point properties, such as colour to be stored for them.

Examples

If this is set in the constructor, point properties such as ranges and point_colours should have one value for each True in this array. This is shown in the below example:

>>> import numpy as np
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Scan
>>> project = Project()
>>> dimensions = (5, 5)
>>> # Each line represents one row of points in the scan.
>>> # Note that rows containing invalid points have fewer values.
>>> ranges = [10.7, 10.6, 10.8,
...           10.3, 10.8, 10.6,
...           9.2, 10.9, 10.7, 10.7, 10.9,
...           9.5, 11.2, 10.6, 10.6,
...           9.1, 9.4, 9.2]
>>> horizontal_angles = [-20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,
...                      -20, -10, 0, 10, 20,]
>>> vertical_angles = [-20, -20, -20, -20, -20,
...                    -10, -10, -10, -10, -10,
...                    0, 0, 0, 0, 0,
...                    10, 10, 10, 10, 10,
...                    20, 20, 20, 20, 20,]
>>> red = [255, 0, 0, 255]
>>> green = [0, 255, 0, 255]
>>> blue = [0, 0, 255, 255]
>>> point_colours = [red, green, blue,
...                  red, green, blue,
...                  red, green, blue, red, green,
...                  red, green, blue, red,
...                  red, green, blue]
>>> point_validity = [False, False, True, True, True,
...                   False, True, True, True, False,
...                   True, True, True, True, True,
...                   True, True, True, True, False,
...                   True, True, True, False, False]
>>> with project.new("scans/example_with_invalid_and_colours", Scan(
...         dimensions=dimensions, point_validity=point_validity
...         ), overwrite=True) as example_scan:
...     # Even though no points have been set, because point_validity was
...     # specified in the constructor point_count will return
...     # the required number of valid points.
...     print(f"Point count: {example_scan.point_count}")
...     # The scan contains invalid points, so cell_point_count
...     # will be lower than the point count.
...     print(f"Cell point count: {example_scan.cell_point_count}")
...     example_scan.point_ranges = ranges
...     example_scan.horizontal_angles = np.deg2rad(horizontal_angles)
...     example_scan.vertical_angles = np.deg2rad(vertical_angles)
...     example_scan.origin = [0, 0, 0]
...     example_scan.point_colours = point_colours
Point count: 18
Cell point count: 25

This property can also be used to filter out angles from invalid points so that they are not used in algorithms. This example calculates the average vertical and horizontal angles for valid points for the scan created in the previous example. Make sure to run the previous example first.

>>> import math
>>> import numpy as np
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("scans/example_with_invalid_and_colours") as scan:
...     validity = scan.cell_point_validity
...     valid_vertical_angles = scan.vertical_angles[validity]
...     mean_vertical_angles = math.degrees(np.mean(valid_vertical_angles))
...     valid_horizontal_angles = scan.horizontal_angles[validity]
...     mean_horizontal_angles = math.degrees(np.mean(
...         valid_horizontal_angles))
...     print(f"Average vertical angle: {mean_vertical_angles}")
...     print(f"Average horizontal angle: {mean_horizontal_angles}")
Average vertical angle: 0.5555580888570226
Average horizontal angle: -1.1111082803078174

property point_intensity

A list containing the intensity of the points.

This contains one value for each valid point.

Each intensity value is represented as a 16 bit unsigned integer and should be between 0 and 65535 (inclusive). If the value is outside of this range, integer overflow will occur.

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

property cell_attributes: PrimitiveAttributes

Access custom cell attributes.

These are arrays of values of the same type, with one value for each cell.

Use Object.cell_attributes[attribute_name] to access a cell attribute called attribute_name. See PrimitiveAttributes for valid operations on cell attributes.

Returns: Access to the cell attributes.
Return type: PrimitiveAttributes
Raises: ValueError – If the type of the attribute is not supported.

property cell_count: int

The number of cells in the cell network.

By default this is equal to the (major_dimension_count - 1) x (minor_dimension_count - 1), however subclasses may override this function to return different values.

property cell_point_count: int

The number of points in the cell network, including invalid points.

The point_count of a cell network only counts the valid points. However, sparse cell networks (such as Scans) may also contain invalid points for which point properties are not stored. This is equal to: major_dimension_count * minor_dimension_count.

If the object contains invalid points, then cell_point_count > point_count.

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

Delete a cell attribute by name.

This is equivalent to: cell_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.

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.
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 heading_pitch_roll: tuple[float, float, float]

The heading, pitch and roll angles for this rotation.

The heading is defined as the angle of the rotation about the -z axis. The pitch is defined as the angle of the rotation about the x axis. The roll is defined as the rotation about the y axis.

property is_column_major

True if the scan is stored in a column major cell network.

All scans created via the SDK will be in row-major order.

property is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

property lock_type: LockType

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

Use the is_read_only property instead for checking if an object is open for reading or editing.

Returns: The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.
Return type: LockType

property modified_date: datetime

The date and time (in UTC) of when this object was last modified.

Returns: The date and time this object was last modified. 0:0:0 1/1/1970 if the operation failed.
Return type: datetime.datetime

property orientation: tuple[float, float, float]

The rotation represented as Vulcan-style dip, plunge and bearing.

This is the tuple: (dip, plunge, bearing) where each value is in radians.

This is defined differently for ellipsoids to ensure consistency with the dip, plunge and bearing displayed in applications.

Notes

This is a derived property. It is recalculated each time this is called.

property 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_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]

rotate(angle, axis)

Rotates the object by the specified angle around the specified axis.

Parameters

angle (float) – The angle to rotate by in radians. Positive is clockwise, negative is anticlockwise (When looking in the direction of axis).
axis (Axis) – The axis to rotate by.

Raises

ReadOnlyError – If this object is open for read-only.

Examples

Create a 2x2x2 dense block model which is rotated by pi / 4 radians (45 degrees) around the X axis.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel, Axis
>>> project = Project()
>>> with project.new("blockmodels/dense_rotated", DenseBlockModel(
...         x_res=1, y_res=1, z_res=1,
...         x_count=2, y_count=2, z_count=3)) as new_model:
...     new_model.rotate(math.pi / 4, Axis.X)

If you want to specify the angle in degrees instead of radians, use the math.radians function. Additionally rotate can be called multiple times to rotate the block model in multiple axes. Both of these are shown in the below example. The resulting block model is rotated 32 degrees around the Y axis and 97 degrees around the Z axis.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel, Axis
>>> project = Project()
>>> with project.new("blockmodels/dense_rotated_degrees", DenseBlockModel(
...         x_res=1, y_res=1, z_res=1,
...         x_count=2, y_count=2, z_count=3)) as new_model:
...     new_model.rotate(math.radians(32), Axis.Y)
...     new_model.rotate(math.radians(97), Axis.Z)

rotate_2d(angle)

Rotates the object in two dimensions. This is equivalent to rotate with axis=Axis.Z

Parameters: angle (float) – The angle to rotate by in radians. Positive is clockwise, negative is anticlockwise.
Raises: ReadOnlyError – If this object is open for read-only.

property rotation: float

Returns the magnitude of the rotation of the object in radians.

This value is the total rotation of the object relative to its original position.

Notes

If the object has been rotated in multiple axes, this will not be the sum of the rotations performed. For example, a rotation of 90 degrees around the X axis, followed by a rotation of 90 degrees around the Y axis corresponds to a single rotation of 120 degrees so this function would return (2 * pi) / 3 radians.

save()

Save the changes made to the object.

Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().

save_cell_attribute(attribute_name, data)

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

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

Parameters

attribute_name (str) – The name of attribute
data (array_like) – An array_like of length cell_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.

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 (npt.ArrayLike) – 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 (str) – The name of the object attribute for which the value should be set.
dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.
data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises

ValueError – If dtype is an unsupported type.
TypeError – If value is an inappropriate type for object attribute name.
ValueError – If name starts or ends with whitespace or is empty.
RuntimeError – If a different error occurs.

Warning

Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
0

set_heading_pitch_roll(heading, pitch, roll)

Replace the existing rotation with specified heading, pitch and roll.

Parameters

heading (float) – Angle in radians of the rotation about the -z axis. This should be between 0 and 2 * pi radians (inclusive).
pitch (float) – Angle in radians of the rotation about the x axis. This should be between -pi / 2 and pi / 2 radians (inclusive).
roll (float) – Angle in radians of the rotation about the y axis. This should be between -pi / 2 and pi / 2 radians (inclusive).

Raises

ValueError – If heading < 0 or heading > 2 * pi. If pitch < -pi / 2 or pitch > pi / 2. If roll < -pi / 2 or roll > pi / 2.

set_orientation(dip, plunge, bearing)

Overwrite the existing rotation with dip, plunge and bearing.

For block models, an orientation of (dip, plunge, bearing) radians is equivalent to rotating the model -dip radians around the X axis, -plunge radians around the Y axis and -(bearing - pi / 2) radians around the Z axis.

For ellipsoids, set_orientation(dip, plunge, bearing) is equivalent to set_heading_pitch_roll(bearing, plunge, -dip)

Parameters

dip (float) – Relative rotation of the Y axis around the X axis in radians. This should be between -pi and pi (inclusive).
plunge (float) – Relative rotation of the X axis around the Y axis in radians. This should be between -pi / 2 and pi / 2 (exclusive).
bearing (float) – Absolute bearing of the X axis around the Z axis in radians. For block models, this should be between -pi and pi (inclusive) For ellipsoids, this should be between -pi / 2 and pi / 2 (exclusive).

Raises

TypeError – If dip, plunge or bearing are not numbers.
ReadOnlyError – If this object is not open for editing.

Examples

Set orientation of a new 3x3x3 block model to be plunge = 45 degrees, dip = 30 degrees and bearing = -50 degrees

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.new("blockmodels/model_1", DenseBlockModel(
...         x_res=1, y_res=1, z_res=1,
...         x_count=3, y_count=3, z_count=3)) as new_model:
>>>     new_model.set_orientation(math.radians(45),
...                               math.radians(30),
...                               math.radians(-50))

Copy the rotation from one block model to another. Requires two block models.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.edit("blockmodels/model_1") as model_1:
...     with project.edit("blockmodels/model_2") as model_2:
...         model_2.set_orientation(*model_1.orientation)

set_rotation(angle, axis)

Overwrites the existing rotation with a rotation around the specified axis by the specified angle.

This is useful for resetting the rotation to a known point.

Parameters

angle (float) – Angle to set the rotation to in radians. Positive is clockwise, negative is anticlockwise.
axis (Axis) – Axis to rotate around.

Raises

ReadOnlyError – If this object is open for read-only.

set_rotation_2d(angle)

Overwrite the existing rotation with a simple 2d rotation.

Parameters: angle (float) – Angle to set the rotation to in radians.
Raises: ReadOnlyError – If this object is not open for editing.

property point_to_grid_index

An array which maps a point index to its row and column in the grid.

This is a numpy array of shape (point_count, 2) where each row of the array is of the form (scan_row, scan_column) where scan_row is the index of the row in the scan which contains the point and scan_column is the index of the column in the scan which contains the point.

Examples

Get the row and column of the point at index seven in the scan.

>>> row, column = scan.point_to_grid_index[7]

Set all points in the third row (index 2) of a scan to cyan.

>>> index = scan.point_to_grid_index[:, 0] == 2
>>> scan.point_colours[index] = [0, 255, 255, 255]

Set all points in the second column (index 1) of a scan to yellow.

>>> index = scan.point_to_grid_index[:, 1] == 1
>>> scan.point_colours[index] = [255, 255, 0, 255]

property grid_to_point_index

An array which maps the row and column of a point to its index.

This is a numpy masked array of shape (row_count, column count) where the value in row i and column j is the index of the point in row i and column j. If the point is invalid, the value will be np.ma.masked and attempting to index into a point property array with it will raise an IndexError.

Examples

Get the index of the point in the row index 5 and column index 7

>>> index = scan.grid_to_point_index[5, 7]

Set all points in the second column (index 1) of a scan to be yellow.

>>> index = scan.grid_to_point_index[:, 1]
>>> # Filter out invalid indices.
>>> index = index[index != np.ma.masked]
>>> scan.point_colours[index] = [255, 255, 0, 255]

Set all points in the third row (index 2) of a scan to cyan.

>>> index = scan.grid_to_point_index[2]
>>> # Filter out invalid indices.
>>> index = index[index != np.ma.masked]
>>> scan.point_colours[index] = [0, 255, 255, 255]