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 upon save() to be equal to the point_count.
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.

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.

Notes

The points of a scan can only be set on new scans. Setting the points on non-new scans will be ignored. 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 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.

Warning

For new scans, if the points are not set but the ranges, horizontal_angles and vertical angles are, then this will not correspond to the number of points in the points property.

property point_ranges

List of floats representing the distance of the points from the scan origin with one value per valid point. Any range value greater than max_range() will be set to max_range() when save() is called.

The ranges array can only be assigned when the scan is first created. After creation, values within the range array can be only changed via assignment and operations which work in-place on the array.

If the dimensions were specified in the constructor, then this must have one value per valid point.

When save() is called, if there are less point_ranges than vertical_angles or horizontal_angles the ranges will be padded with zeroes. If there are more ranges than angles, the ranges will be truncated to be the same length as the angles arrays.

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.
DegenerateTopologyError – 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

List of horizontal angles of the points. This is the azimuth of the point 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. When save() is called, if there are more horizontal angles than vertical angles this will be padded with zeroes to be the same length.

If the dimensions were specified in the constructor, then this must have cell_point_count values.

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.
DegenerateTopologyError – 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

List of vertical angles of the points. 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. When save() is called, if there are more vertical angles than horizontal angles this will be padded with zeroes to be the same length.

If the dimensions were specified in the constructor, then this must have cell_point_count values.

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.
DegenerateTopologyError – 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.

Notes

Scans appear ‘flattened’ when read in the Python SDK - a scan with ten rows and ten columns of points will appear as a flat array containing one hundred points.

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 the generating scanner is capable of. 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

A list of booleans specifying which items in the underlying cell network are valid. 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 - 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.

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

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

property cell_attributes

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

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

The number of points in the cell network, including 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.

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 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 orientation

The rotation of the object represented as Vulcan-style dip, plunge and bearing. This will return the tuple: (dip, plunge, bearing)

The returned values are in radians.

Notes

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

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

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.

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.

property rotation

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_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 (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

set_orientation(dip, plunge, bearing)

Overwrite the existing rotation with a rotation defined by the specified dip, plunge and bearing.

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.

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. This should be between -pi and pi (inclusive).

Raises

TypeError – If dip, plunge or bearing are not numbers.

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.

set_rotation_2d(angle)

Overwrite the existing rotation with a simple 2d rotation.

Parameters: angle (float) – Angle to set the rotation to in radians.