mapteksdk.data.cells module

Cell network data types.

Cell networks are objects which are defined by quadrilateral cell primitives. This module only contains the GridSurface class which represents a dense irregular cell network.

See also

mapteksdk.data.scans.Scan

Scans are also cell networks, however they are not included in this module due to their specialised nature.

class GridSurface(object_id=None, lock_type=LockType.READWRITE, major_dimension_count=None, minor_dimension_count=None, x_step=None, y_step=None, start=None, column_major=False)

Bases: Topology, PointProperties, CellProperties

A dense surface formed by quadrilaterals called ‘cells’.

A GridSurface is more compact than a Surface and calculations can be performed faster on them, however they are less versatile. They cannot represent surfaces with disconnected parts or holes in the surface (unless the grid surface self-intersects).

The object will contain major_dimension_count * minor_dimension_count points which are used to define the cells. The structure contains (major_dimension_count - 1) * (minor_dimension_count - 1) cells - due to the gridded nature of the object adjacent cells share points. To make working with the gridded data structure easier, this object provides two dimensional versions of the point and cell properties. This allows for these properties to be indexed based on the row and column of the cell in the grid.

The cell in the ith row and the jth column is defined as the quadrilateral between cell_points[i][j], cell_points[i + 1][j], cell_points[i + 1][j + 1] and cell_points[i][j + 1] For example, the zeroth cell is between the points cell_points[0][0], cell_points[0][1], cell_points[1][1] and cell_points[1][0]. Cell selection and cell visibility map the selection and visibility to the cells in the same way.

The constructor for grid surfaces can generate a regular grid (via the x_step and y_step parameters) in the X and Y direction. If this form of the constructor is used then only setting the Z values will create a consistent grid with no self-intersections. Use the start parameter to specify the start position of the grid.

Parameters:

• major_dimension_count (int) – The number of rows used to store the grid surface. Note that this will only correspond to the number of rows in the grid surface if the points are stored in row major order. This is ignored if opening an existing irregular grid surface.

• minor_dimension_count (int) – The number of columns used to store the grid surface. Note that this will only correspond to the number of columns in the grid surface if the points are stored in row major order. This is ignored if opening an existing grid surface.

• x_step (int) – If x_step, y_step or start are specified, the constructor will set the points to a regular grid using this as the size of each grid square in the X direction. If y_step is specified this should also be specified. Ignored when opening an existing grid surface. To make scripts run faster, only specify this argument if you intend to use the generated regular grid.

• y_step (int) – If x_step, y_step or start are specified, the constructor will set the points to a regular grid using this as the size of each grid square in the Y direction. If x_step is specified this should also be specified. Ignored when opening an existing grid surface. To make scripts run faster, only specify this argument if you intend to use the generated regular grid.

• start (array_like) – If x_step, y_step or start are specified, the constructor will set the points to a regular grid using this as the start point of the generated grid. The default is [0, 0, 0]. This should only be specified if x_step and y_step are specified. Ignored when opening an existing grid surface. To make scripts run faster, only specify this argument if you intend to use the generated regular grid.

• column_major (bool) – If False (default) then the generated grid will be in row major order (X values change in rows, Y values in columns). If True the generated grid will be in column major order (Y values change in rows, X values in columns). This has no effect if x_step, y_step and start are not specified. Ignored when opening an existing grid surface.

Warning

GridSurfaces have no protection against self-intersecting cells or cells intersecting each other. This can cause unintuitive index to spatial relationships and holes in the surface.

Raises:

• ValueError – If major_dimension_count or minor_dimension_count are less than zero.

• TypeError – If major_dimension_count or minor_dimension_count are not integers.

See also

grid-surface

Help page for this class.

Examples

Creates a new grid surface using the grid constructor then sets the Z coordinates to be the sine of the X coordinate plus the Y coordinate. By using the grid constructor then setting only the Z coordinates, this ensures the resulting surface has no self-intersections and an intuitive index to spatial relationship.

>>> import math
>>> import numpy as np
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/sin_x+y", GridSurface(
...         major_dimension_count=8, minor_dimension_count=8,
...         x_step=math.pi/4, y_step=math.pi/4)) as new_grid:
...     np.sin(new_grid.points[:, 1] + new_grid.points[:, 2],
...            out=new_grid.point_z)

If the X and Y information is already available or does not neatly conform to a grid, construction of the object will be faster if the X and Y step parameters are not specified. In the below example the X and Y coordinates are not regularly spaced (as is often the case for real world data) so it is more efficient to not specify the x_step and y_step parameters.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> points = [[1.1, 1.15, 1.11], [1.98, 1.17, 1.08], [3.02, 1.13, 1.07],
...           [1.08, 1.99, 1.07], [2.01, 2.03, 1.37], [3.00, 2.11, 1.33],
...           [1.13, 3.08, 1.08], [2.00, 3.01, 0.99], [3.18, 3.07, 1.34]]
>>> with project.new("surfaces/noisy", GridSurface(
...         major_dimension_count=3, minor_dimension_count=3
...         )) as new_grid:
...     new_grid.points = points

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 id: ObjectID[GridSurface]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

property point_count

The number of points in this object.

property cells_2d

The cells rearranged into rows and columns.

GridSurface.cells_2d[i][j] will return the cell in the ith row and jth column.

property cell_visibility_2d

The visibility of the cells rearranged into rows and columns.

This is a view of the cell_visibility reshaped to be a grid of size major_dimension_count - 1 by minor_dimension_count - 1.

Raises:

• ValueError – If assigned a value which is not major_dimension_count - 1 by minor_dimension_count - 1.

• ValueError – If set using a value which cannot be converted to a bool.

Examples

Set all cells along the diagonal of the grid surface to be invisible, then print the cell visibility. The loop is bounded by the lower of the major and minor dimension counts, so it will work even for grid surfaces which are not squares.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/cell_visibility", GridSurface(
...         major_dimension_count=5, minor_dimension_count=5,
...         x_step=1, y_step=1)) as new_cells:
...     for i in range(min(new_cells.cell_visibility_2d.shape)):
...         new_cells.cell_visibility_2d[i][i] = False
...     print(new_cells.cell_visibility_2d)
[[False, True, True, True]
 [True, False, True, True]
 [True, True, False, True]
 [True, True, True, False]]

Note that when the object created in the previous example is viewed from above, the resulting cell visibility will be mirrored on the Y axis to what was printed. This is because ascending y will go up the screen, whereas the ascending rows are printed down the screen. i.e. The grid surface will have the following visibility:

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("surfaces/cell_visibility") as read_cells:
...     print(read_cells.cell_visibility_2d[:, ::-1])
[[ True  True  True False]
 [ True  True False  True]
 [ True False  True  True]
 [False  True  True  True]]

Set a 2x2 area of cells to be invisible then print the resulting cell visibility.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import GridSurface
>>> project = Project()
>>> with project.new("surfaces/cell_visibility_2", GridSurface(
...         major_dimension_count=5, minor_dimension_count=5,
...         x_step=1, y_step=1)) as new_cells:
...     new_cells.cell_visibility_2d[1:3, 1:3] = [[False, False],
...                                               [False, False]]
[[True, True, True, True]
 [True, False, False, True]
 [True, False, False, True]
 [True, True, True, True]]

property cell_selection_2d

The cell selection rearranged into rows and columns.

This is the cell_selection reshaped into a grid of size: major_dimension_count - 1 by minor_dimension_count - 1

Raises:

• ValueError – If set to a value which is not major_dimension_count - 1 by minor_dimension_count - 1.

• ValueError – If set using a value which cannot be converted to a bool.

property cell_points

The points rearranged into rows and columns.

This is a view of points reshaped to follow the underlying grid structure of the surface. This means that for the cell in row i and column j, the points which define the four corners of the cell are: cell_points[i][j], cell_points[i + 1][j], cell_points[i + 1, j + 1] and cell_points[i][j + 1].

As this is a view of the points, any changes made to points will be reflected in cell_points and vice versa.

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.

See also

mapteksdk.data.primitives.PointProperties.points

Flat array access to points.

property cell_point_colours

The point colours rearranged into rows and columns.

This is a view of the point_colours reshaped to be major_dimension_count by minor_dimension_count.

Raises:

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

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

• TypeError – If set to a value which cannot be converted to an integer.

See also

mapteksdk.data.primitives.PointProperties.point_colours

Flat array access to point colours.

append_points(*points)

Append points to the object.

Using this function is preferable to assigning to the points array directly because it allows points to be added to the object without any risk of changing existing points by accident. The return value can also be used to assign point properties for the new points.

Parameters:

points (Point) – Points to append to the object.

Returns:

Boolean array which can be used to assign properties for the newly added points.

Return type:

BooleanArray

Raises:

AppendPointsNotSupportedError – If the object does not support appending points. This is raised for GridSurfaces, and non-new Scans.

Examples

This function can be used to add a single point to an object:

>>> point_set: PointSet
>>> point_set.append_points([1.5, -1.5, 2.25])

Passing multiple points can be used to append multiple points at once:

>>> point_set: PointSet
>>> point_set.append_points([3.1, 1.1, 4.1], [2.2, 7.2, 1.2])

This function also accepts iterables of points, so the following is functionally identical to the previous example:

>>> point_set: PointSet
>>> point_set.append_points([[3.1, 1.1, 4.1], [2.2, 7.2, 1.2]])

The return value of this function can be used to assign point properties to the newly added points:

>>> point_set: PointSet
>>> new_point_indices = point_set.append_points(
...     [3.1, 1.1, 4.1], [2.2, 7.2, 1.2])
>>> # Colour the two new points blue and magenta.
>>> point_set.point_colours[new_point_indices] = [
...     [0, 0, 255, 255], [255, 0, 255, 255]]

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

cancel()

Cancel any pending changes to the object.

This undoes all changes made to the object since it was opened (including any changes saved by save()) and then closes the object.

After this is called, attempting to read or edit any of the properties on this object (other than the id) will raise an ObjectClosedError.

Raises:

• ReadOnlyError – If the object was open for read only (i.e not for editing). It is not necessary to call this for a read only object as there will be no pending changes.

• ObjectClosedError – If called on a closed object.

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.primitives.PointProperties.point_count

The count of valid points in the object.

property cell_point_visibility

The point visibility rearranged into rows and columns.

A view of the point_visibility reshaped to be major_dimension_count by minor_dimension_count.

Raises:

• ValueError – If set using a value which cannot be converted to a bool.

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

See also

mapteksdk.data.primitives.PointProperties.point_visibility

Flat array access to point visibility.

property cell_selection: BooleanArray

The selection of the cells as a flat array.

This array will contain cell_count booleans - one for each cell. True indicates the cell is selected and False indicates the cell is not selected.

property cell_visibility: BooleanArray

The visibility of the cells as a flat array.

This array will contain cell_count booleans - one for each cell. True indicates the cell is visible and False indicates the cell is invisible.

property cells: CellArray

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

close()

Closes the object and saves the changes to the Project.

Attempting to read or edit properties of an object after closing it will raise a ReadOnlyError.

property closed: bool

If this object has been closed.

Attempting to read or edit a closed object will raise an ObjectClosedError. Such an error typically indicates an error in the script and should not be caught.

Examples

If the object was opened with the Project.new(), Project.edit() or Project.read() in a “with” block, this will be True until the with block is closed and False afterwards.

>>> with self.project.new("cad/point_set", PointSet) as point_set:
>>>     point_set.points = [[1, 2, 3], [4, 5, 6]]
>>>     print("closed?", point_set.closed)
>>> print("closed?", point_set.closed)
closed? False
closed? True

property coordinate_system: CoordinateSystem | None

The coordinate system the points of this object are in.

If the object has no coordinate system, this will be None.

Raises:

ReadOnlyError – If set on an object open for read-only.

Warning

Setting this property does not change the points. This is only a label stating the coordinate system the points are in.

Examples

Creating an edge network and setting the coordinate system to be WGS84. Note that setting the coordinate system does not change the points. It is only stating which coordinate system the points are in.

>>> from pyproj import CRS
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polygon
>>> project = Project()
>>> with project.new("cad/rectangle", Polygon) as new_edges:
...     # Coordinates are in the form [longitude, latitude]
...     new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]]
...     new_edges.coordinate_system = CRS.from_epsg(4326)

Often a standard map projection is not convenient or accurate for a given application. In such cases a local transform can be provided to allow coordinates to be specified in a more convenient system. The below example defines a local transform where the origin is translated 1.2 degrees north and 2.1 degree east, points are scaled to be twice as far from the horizontal origin and the coordinates are rotated 45 degrees clockwise about the horizontal_origin. Note that the points of the polygon are specified in the coordinate system after the local transform has been applied.

>>> import math
>>> from pyproj import CRS
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Polygon, CoordinateSystem, LocalTransform
>>> project = Project()
>>> transform = LocalTransform(
...     horizontal_origin = [1.2, 2.1],
...     horizontal_scale_factor = 2,
...     horizontal_rotation = math.pi / 4)
>>> system = CoordinateSystem(CRS.from_epsg(20249), transform)
>>> with project.new("cad/rectangle_transform", Polygon) as new_edges:
...     new_edges.points = [[112, 9], [112, 44], [154, 44], [154, 9]]
...     new_edges.coordinate_system = system

See also

mapteksdk.data.coordinate_systems.CoordinateSystem

Allows for a coordinate system to be defined with an optional local transform.

property created_date: datetime

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

Returns:

The date and time the object was created. 0:0:0 1/1/1970 if the operation failed.

Return type:

datetime.datetime

delete_all_attributes()

Delete all object attributes attached to an object.

This only deletes object attributes and has no effect on PrimitiveAttributes.

Raises:

RuntimeError – If all attributes cannot be deleted.

delete_attribute(attribute)

Deletes a single object-level attribute.

Deleting a non-existent object attribute will not raise an error.

Parameters:

attribute (str) – Name of attribute to delete.

Returns:

True if the object attribute existed and was deleted; False if the object attribute did not exist.

Return type:

bool

Raises:

RuntimeError – If the attribute cannot be deleted.

delete_cell_attribute(attribute_name)

Delete a cell attribute.

This is equivalent to: cell_attributes.delete_attribute(attribute_name)

Parameters:

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

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 major_dimension_count: int

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: int

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

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

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

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

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

Parameters:

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

• data (array_like) – An array_like of length cell_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.

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

property cell_point_selection

The point selection rearranged into rows and columns.

A view of the point_selection reshaped to be major_dimension_count by minor_dimension_count.

Raises:

• ValueError – If set using a value which cannot be converted to a bool.

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

See also

mapteksdk.data.primitives.PointProperties.point_selection

Flat array access to point selection.

classmethod static_type()

Return the type of a topology as stored in a Project.

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