mapteksdk.data.blocks module

Block model data types.

Block models are objects constructed entirely from block primitives. There are different kinds of block models, however only DenseBlockModels and SubblockedBlockModels are currently supported.

exception InvalidBlockCentroidError

Bases: ValueError

Error raised for block centroids which lie outside of the block model.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception InvalidBlockSizeError

Bases: ValueError

Error raised for invalid block sizes.

add_note()

Exception.add_note(note) – add a note to the exception

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class DenseBlockModel(object_id=None, lock_type=LockType.READWRITE, x_res=None, y_res=None, z_res=None, x_count=None, y_count=None, z_count=None, *, col_count=None, row_count=None, slice_count=None, col_res=None, row_res=None, slice_res=None)

Bases: Topology, BlockProperties, RotationMixin

A block model with equally sized blocks arranged in a regular 3D grid.

A dense block model consists of blocks which are the same size arranged in a three dimensional grid structure. The block model is dense because it does not allow ‘holes’ in the model - every region in the grid must contain a block.

For example, a dense block model with an col_res of 1, a row_res of 2 and a slice_res of 3 means all of the blocks in the model are 1 by 2 by 3 metres in size. If the dense block model’s col_count was 10, the row_count was 15 and the slice_count was 5 then the model would consist of 10 * 15 * 5 = 750 blocks each of which is 1x2x3 meters. These blocks would be arranged in a grid with 10 columns, 15 rows and 5 slices with no gaps.

The blocks of a dense block model are defined at creation and cannot be changed.

Parameters:

• col_count (int) – The number of columns of blocks in the block model. In the block model coordinate system, this is the number of blocks in the X direction. Must be greater than zero.

• row_count (int) – The number of rows of blocks in the block model. In the block model coordinate system, this is the number of blocks in the Y direction. Must be greater than zero.

• slice_count (int) – The number of slices of blocks in the block model. In the block model coordinate system, this is the number of blocks in the Z direction. Must be greater than zero.

• col_res (float) – The size of each block in the direction of the columns of the model. In the block model coordinate system, this is the size of the blocks in the X direction. Must be greater than zero.

• row_res (float) – The size each of block in the direction of the rows of the model. In the block model coordinate system, this is the size of the blocks in the Y direction. Must be greater than zero.

• slice_res (float) – The size of each block in the direction of the slices of the model. In the block model coordinate system, this is the size of the blocks in the Z direction. Must be greater than zero.

• x_res (float) – A deprecated alias for col_res. Kept for backwards compatibility.

• y_res (float) – A deprecated alias for row_res. Kept for backwards compatibility.

• z_res (float) – A deprecated alias for slice_res. Kept for backwards compatibility.

• x_count (int) – A deprecated alias for col_count. Kept for backwards compatibility.

• y_count (int) – A deprecated alias for row_count. Kept for backwards compatibility.

• z_count (int) – A deprecated alias for slice_count. Kept for backwards compatibility.

Raises:

• ValueError – If col_res, row_res, slice_res, col_count, row_count or slice_count are less than or equal to zero.

• TypeError – If col_res, row_res, slice_res, col_count, row_count or slice_count is not numeric.

• TypeError – If col_count, row_count or slice_count are numeric but not integers.

See also

dense-block-model

Help page for dense block model.

Notes

Parameters should only be passed for new block models.

Examples

Create a block model as described above and make every second block invisible.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.new("blockmodels/model", DenseBlockModel(
...         col_res=1, row_res=2, slice_res=3,
...         col_count=10, row_count=15, slice_count=5) as new_model:
>>>     new_model.block_visibility[0::2] = True
>>>     new_model.block_visibility[1::2] = False

Note that the with statement can be made less verbose through the use of dictionary unpacking, as shown below.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> parameters = {
...     "col_res" : 1, "row_res" : 2, "slice_res" : 3,
...     "col_count" : 10, "row_count" : 15, "slice_count" : 5,
... }
>>> with project.new("blockmodels/model", DenseBlockModel(**parameters)
...         ) as new_model:
>>>     new_model.block_visibility[0::2] = True
>>>     new_model.block_visibility[1::2] = False

classmethod static_type()

Return the type of dense block model as stored in a Project.

This can be used for determining if the type of an object is a dense block model.

property id: ObjectID[DenseBlockModel]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

property block_count

The count of blocks in the model.

property block_centroids_3d

Access block centroids by slice, row, column instead of index.

This is a view on the block_centroids array reshaped into three dimensions such that block_centroids_3d[slice, row, column] is the centroid of the block in the specified specified slice, row and column.

property block_visibility_3d

Access block visibility by slice, row, column instead of index.

This is a view of the block visibility reshaped into three dimensions such that block_visibility_3d[slice, row, column] gives the visibility for the block in the specified slice, row and column.

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.

Examples

Make a 10x10x10 block model and make every block in the 4th row invisible, excluding blocks in the 0th slice.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.new("blockmodels/visibility_3d", DenseBlockModel(
...         col_count=10, row_count=10, slice_count=10,
...         col_res=1, row_res=1, slice_res=0.5)) as new_blocks:
...     new_blocks.block_visibility_3d[:, 5, :] = False
...     new_blocks.block_visibility_3d[0, :, :] = True

property block_selection_3d

Access block selection by slice, row, column instead of index.

This is a view of the block selection reshaped into three dimensions such that block_selection_3d[slice, row, column] is the visibility for the block in the specified slice, row and column.

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.

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 block_attributes: PrimitiveAttributes

Access block attributes.

block_model.block_attributes[“Blocktastic”] will return the block attribute called “Blocktastic”.

Returns:

Access to the block attributes.

Return type:

PrimitiveAttributes

property block_centroids: PointArray

An array of the centre points of each block in the model.

This is an ndarray of shape (block_count, 3) of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] where N is the block_count.

property block_colours: ColourArray

An array of the colours of each block in the model.

This is represented as a ndarray of shape (block_count, 4) where each row i represents the colour of the ith block in the model in the form [Red, Green, Blue, Alpha].

When setting block colours, you may omit the Alpha component.

property block_resolution: BlockSize

The resolution of the block model.

The array [col_res, row_res and slice_res]. These are the same values as used to create the block model. Once the block model has been created, these values cannot be changed.

property block_selection: BooleanArray

An array which indicates which blocks are selected.

This is represented as an ndarray of bools with shape: (block_count,). True indicates the block is selected; False indicates it is not selected.

Notes

In mapteksdk version 1.0, block_selection returned a 3D ndarray. To get the same functionality, see block_selection_3d property of dense block models.

property block_sizes: BlockSizeArray

An array of the sizes of each block in the model

This is represented as an ndarray of shape (block_count, 3). Each row represents the size of one block in the form [column_size, row_size, slice_size] where column_size, row_size and slice_size are positive numbers.

This means that the extent for the block with index i is calculated as: (block_centroids[i] - block_sizes[i] / 2, block_centroids[i] + block_sizes[i] / 2)

Notes

For DenseBlockModels, all block_sizes are the same.

property block_to_grid_index: IndexArray

A mapping of the blocks to the primary blocks.

This is an ndarray with the int dtype containing the mapping of the blocks to the row, column and slice their centroid lies within. This has shape (N, 3) where N is the block_count and each item is of the form [column, row, slice].

This means that the column, row and slice of the block centred at block_centroids[i] is block_to_grid_index[i].

Notes

For DenseBlockModels, there is only one block per grid cell and thus each item of the array will be unique.

property block_visibility: BooleanArray

An array which indicates which blocks are visible.

This is represented as an ndarray of bools with shape: (block_count,). True indicates the block is visible, False indicates it is not visible.

Notes

In mapteksdk version 1.0 block_visibility returned a 3D ndarray. To get the same functionality, see block_visibility_3d property of dense block models.

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.

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

Alias for column count.

This exists so that the property can be referred to by the same name as the argument in the constructor.

property col_res: int

The number of columns of blocks in the model.

This is the col_res parameter passed into the constructor.

property column_count: int

The number of columns in the underlying block model.

This is the number of blocks in the X direction of the block model’s coordinate system. Note that it only corresponds with the direction of the X-axis if the block model is not rotated. This is the column_count value passed to the constructor.

convert_to_block_coordinates(world_coordinates)

Converts points in world coordinates to points in block coordinates.

The block coordinate system for a particular model is defined such that [0, 0, 0] is the centre of the block in row 0, column 0 and slice 0. The X axis is aligned with the columns, the Y axis is aligned with the rows and the Z axis is aligned with the slices of the model. This makes the centre of the primary block in column i, row j and slice k to be: [column_res * i, row_res * j, slice_res * k].

This function performs no error checking that the points lies within the model.

Parameters:

world_coordinates (array_like) – Points in world coordinates to convert to block coordinates.

Returns:

Numpy array containing world_coordinates converted to be in block_coordinates.

Return type:

numpy.ndarray

Raises:

ValueError – If world_coordinates has an invalid shape.

Notes

If a block model has origin = [0, 0, 0] and has not been rotated, then the block and world coordinate systems are identical.

Block models of differing size, origin or rotation will have different block coordinate systems.

convert_to_world_coordinates(block_coordinates)

Converts points in block coordinates to points in world coordinates.

This is the inverse of the transformation performed by convert_to_block_coordinates.

Parameters:

block_coordinates (npt.ArrayLike) – Points in block coordinates to convert to world coordinates.

Returns:

Numpy array containing block_coordinates converted to world_coordinates.

Return type:

numpy.ndarray

Raises:

ValueError – If block_coordinates has an invalid shape.

Notes

Block models of differing size, origin or rotation will have different block coordinate systems.

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_block_attribute(attribute_name)

Delete a block attribute.

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

grid_index(start, stop=None)

Index block properties via row, slice and column instead of index.

Generates a boolean index for accessing block properties by row, column and slice instead of by block. The boolean index will include all subblocks between primary block start (inclusive) and primary block stop (exclusive), or all subblocks within primary block start if stop is not specified.

Parameters:

• start (npt.ArrayLike | int) – An array_like containing three elements - [column, row, slice]. The returned boolean index will include all blocks in a greater column, row and slice. If this is an integer, that integer is interpreted as the column, row and slice.

• end – An array_like containing three elements - [column, row, slice]. If None (Default) this is start + 1 (The resulting index will contain all blocks within primary block start). If not None, the boolean index will include all blocks between start (inclusive) and end (exclusive). If this is an integer, that integer is interpreted as the column, row and slice index.

• stop (npt.ArrayLike | int | None) –

Returns:

A boolean index into the block property arrays. This is an array of booleans of shape (block_count,). If element i is True then subblock i is within the range specified by start and stop. If False it is not within that range.

Return type:

ndarray

Raises:

• TypeError – If start or stop are invalid types.

• ValueError – If start or stop are incorrect shapes.

Examples

These examples require a block model to be at “blockmodels/target”

This example selects all subblocks within the primary block in column 0, row 0 and slice 0:

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("blockmodels/target") as edit_model:
...     index = edit_model.grid_index([0, 0, 0])
...     edit_model.block_selection[index] = True

By passing two values to grid index, it is possible to operate on all subblocks within a range of subblocks. This example passes [0, 2, 2] and [4, 5, 6] meaning all subblocks which have 0 <= column < 4 and 2 <= row < 5 and 2 <= slice < 6 will be selected by grid_index. By passing this index to block visibility, all subblocks within those primary blocks are made invisible.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("blockmodels/target") as edit_model:
...     index = edit_model.grid_index([0, 2, 2], [4, 5, 6])
...     edit_model.block_visibility[index] = False

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_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 origin: Point

The origin of the block model represented as a point.

Setting the origin will translate the entire block model to be centred around the new origin.

Warning

The origin is located in the centre of the block in the 0th row, 0th column and 0th slice. Thus the origin is offset by half a block relative to the bottom corner of the block model.

Notes

For DenseBlockModels the resulting changes to the block_centroids will not occur until save is called. For SubblockedBlockModels the resulting changes to the block_centroids are immediately available, however changing the origin of such a model is slower.

Examples

Changing the origin will change the block model centroids, in this case by translating them by 1 unit in the X direction, 2 units in the Y direction and 3 units in the Z direction. Note that as this is a DenseBlockModel, the model needs to be saved (in this case via closing ending the with block) before the changes to the centroids will occur.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.new("blockmodels/model", DenseBlockModel(
...         col_res=2, row_res=3, slice_res=4,
...         col_count=2, row_count=2, slice_count=2)) as new_model:
...     new_model.origin = [1, 2, 3]
>>> with project.edit("blockmodels/model") as edit_model:
...     print(edit_model.block_centroids)
[[1, 2, 3], [3, 2, 3], [1, 5, 3], [3, 5, 3], [1, 2, 7], [3, 2, 7],
[1, 5, 7], [3, 5, 7]]

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.

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.

property row_count: int

The number of rows in the block model.

This is the number of blocks in the Y direction of the block model’s coordinate system. Note that it only corresponds with the direction of the Y-axis if the block model is not rotated. This is the row_count value passed to the constructor.

property row_res: int

The number of rows of blocks in the model.

This is the row resolution (row_res) passed into the constructor.

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

Create a new block attribute with the specified name and data.

Saving a block 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) – Data for the associated attribute. This should be a ndarray of shape (block_count,). The ith entry in this array is the value of this primitive attribute for the ith block.

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

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

The number of slices in the block model.

This is the number of blocks in the Z direction of the block model’s coordinate system. Note that it only corresponds with the direction of the Z-axis if the block model is not rotated. This is the slice_count value passed to the constructor.

property slice_res: int

The number of slices of blocks in the model.

This is the slice resolution (slice_res) passed into the constructor.

class SubblockedBlockModel(object_id=None, lock_type=LockType.READWRITE, x_res=None, y_res=None, z_res=None, x_count=None, y_count=None, z_count=None, *, row_count=None, col_count=None, slice_count=None, row_res=None, col_res=None, slice_res=None)

Bases: Topology, BlockDeletionProperties, RotationMixin

A dense subblocked block model.

Each primary block can contain subblocks allowing for the model to hold greater detail in areas of greater interest and less detail in areas of less interest.

Block attributes, such as block_visibility and block_colour, have one value per subblock. A subblocked block model is empty when created and contains no blocks. Use the add_subblocks function to add additional subblocks to the model.

Note that it is possible for a subblocked block model to include invalid subblocks. For example, subblocks which are outside of the extents of the block model. These blocks will not be displayed in the viewer.

If interoperability with Vulcan is desired, the subblock sizes should always be a multiple of the primary block sizes (the resolution defined on construction) and you should be careful to ensure subblocks do not intersect each other.

Parameters:

• col_count (int) – The number of columns of blocks in the block model. In the block model coordinate system, this is the number of blocks in the X direction. Must be greater than zero.

• row_count (int) – The number of rows of blocks in the block model. In the block model coordinate system, this is the number of blocks in the Y direction. Must be greater than zero.

• slice_count (int) – The number of slices of blocks in the block model. In the block model coordinate system, this is the number of blocks in the Z direction. Must be greater than zero.

• col_res (float) – The size of each block in the direction of the columns of the model. In the block model coordinate system, this is the size of the blocks in the X direction. Must be greater than zero.

• row_res (float) – The size each of block in the direction of the rows of the model. In the block model coordinate system, this is the size of the blocks in the Y direction. Must be greater than zero.

• slice_res (float) – The size of each block in the direction of the slices of the model. In the block model coordinate system, this is the size of the blocks in the Z direction. Must be greater than zero.

• x_res (float) – A deprecated alias for col_res. Kept for backwards compatibility.

• y_res (float) – A deprecated alias for row_res. Kept for backwards compatibility.

• z_res (float) – A deprecated alias for slice_res. Kept for backwards compatibility.

• x_count (int) – A deprecated alias for col_count. Kept for backwards compatibility.

• y_count (int) – A deprecated alias for row_count. Kept for backwards compatibility.

• z_count (int) – A deprecated alias for slice_count. Kept for backwards compatibility.

Raises:

• ValueError – If col_res, row_res, slice_res, col_count, row_count or slice_count are less than or equal to zero.

• TypeError – If col_res, row_res, slice_res, col_count, row_count or slice_count is not numeric.

• TypeError – If col_count, row_count or slice_count are numeric but not integers.

See also

subblocked-block-model

Help page for subblocked models.

Notes

Parameters should only be passed for new block models.

Examples

Creating a subblocked block model with two parent blocks, one of which is completely filled by a single subblock and another which is split into three subblocks. Each subblock is made invisible individually. Though the block model has two primary blocks, it has four subblocks so four values are required for the visibility.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import SubblockedBlockModel
>>> centroids = [[0, 0, 0], [-1, 3, 0], [1, 3, 0], [0, 5, 0]]
>>> sizes = [[4, 4, 4], [2, 2, 4], [2, 2, 4], [4, 2, 4]]
>>> visibility = [True, True, False, False]
>>> project = Project()
>>> with project.new("blockmodels/subblocked_model", SubblockedBlockModel(
...         col_count=1, row_count=2, slice_count=1,
...         col_res=4, row_res=4, slice_res=4)) as new_blocks:
...     new_blocks.add_subblocks(centroids, sizes)
...     new_blocks.block_visibility = visibility

classmethod static_type()

Return the type of subblocked block model as stored in a Project.

This can be used for determining if the type of an object is a subblocked block model.

property id: ObjectID[SubblockedBlockModel]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

add_subblocks(block_centroids, block_sizes, use_block_coordinates=True)

Adds an array of subblocks to the subblocked block model.

By default the block_centroids should be in block model coordinates rather than world coordinates. See convert_to_world_coordinates() for more information.

Parameters:

• block_centroid (array_like) – An array of block centroids of the new blocks. This is of the form: [x, y, z].

• block_sizes (array_like) – An array of block sizes of the new blocks, each containing three floats. This is of the form: [x_size, y_size, z_size].

• use_block_coordinates (bool) – If True (default) then the coordinates of the block centroids will be interpreted as block model coordinates (They will be passed through convert_to_world_coordinates()). If False, then the coordinates of the block centroids will be interpreted as world coordinates.

Raises:

• InvalidBlockSizeError – If any block_size is less than zero or greater than the primary block size.

• InvalidBlockCentroidError – If any block_centroid is not within the block model.

• ReadOnlyError – If called when in read-only mode.

Warning

By default this function assumes the input is in the “block model coordinate system” (see convert_to_world_coordinates()). The [0, 0, 0] in this coordinate system is located in the centre of the primary block in the 0th row, column and slice. This “half-block offset” means that the block centroids are offset by half a block relative to the bottom corner of the block model.

Notes

Calling this function in a loop is very slow. You should calculate all of the subblocks and pass them to this function in a single call.

Examples

The block centroids are specified in block model coordinates relative to the bottom left hand corner of the block model. In the below example, the block model is rotated around all three axes and translated away from the origin. By specifying the centroids in block model coordinates, the centroids remain simple. The output shows the resulting block centroids of the model. To get the same model with use_block_coordinates=False these are the centroids which would be required. As you can see they are significantly more complicated.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import SubblockedBlockModel, Axis
>>> centroids = [[-1.5, -1, -1], [-0.5, -1, -1], [-1, 1, -1],
...              [-1.5, -1, 1], [-0.5, -1, 1], [-1, 1, 1],
...              [-1.5, -1, 3], [-0.5, -1, 3], [-1, 1, 3]]
>>> sizes = [[1, 2, 2], [1, 2, 2], [2, 2, 2],
...          [1, 2, 2], [1, 2, 2], [2, 2, 2],
...          [1, 2, 2], [1, 2, 2], [2, 2, 2]]
>>> project = Project()
>>> with project.new("blockmodels/transformed", SubblockedBlockModel(
...         col_count=1, row_count=2, slice_count=3,
...         col_res=4, row_res=4, slice_res=4)) as new_blocks:
...     new_blocks.origin = [94, -16, 12]
...     new_blocks.rotate(math.pi / 3, Axis.X)
...     new_blocks.rotate(-math.pi / 4, Axis.Y)
...     new_blocks.rotate(math.pi * 0.75, Axis.Z)
...     new_blocks.add_subblocks(centroids, sizes)
...     print(new_blocks.block_centroids)
[[ 95.95710678 -16.64693601  11.96526039]
 [ 95.45710678 -15.86036992  12.32763283]
 [ 94.70710678 -16.09473435  10.42170174]
 [ 94.54289322 -17.87168089  12.67236717]
 [ 94.04289322 -17.08511479  13.03473961]
 [ 93.29289322 -17.31947922  11.12880852]
 [ 93.12867966 -19.09642576  13.37947395]
 [ 92.62867966 -18.30985966  13.74184639]
 [ 91.87867966 -18.54422409  11.8359153 ]]

Specifying the block centroids in world coordinates is useful when the centroids are already available in world coordinates. This example shows copying the blocks from the model created in the previous example into a new model. Notice that the origin and rotations are the same for the copy. If this were not the case the centroids would likely lie outside of the block model and would not appear in the viewer.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import SubblockedBlockModel, Axis
>>> project = Project()
>>> with project.new("blockmodels/transformed_copy", SubblockedBlockModel(
...         col_count=1, row_count=2, slice_count=3,
...         col_res=4, row_res=4, slice_res=4)) as new_blocks:
...     new_blocks.origin = [94, -16, 12]
...     new_blocks.rotate(math.pi / 3, Axis.X)
...     new_blocks.rotate(-math.pi / 4, Axis.Y)
...     new_blocks.rotate(math.pi * 0.75, Axis.Z)
...     with project.read("blockmodels/transformed") as read_blocks:
...         new_blocks.add_subblocks(read_blocks.block_centroids,
...                                  read_blocks.block_sizes,
...                                  use_block_coordinates=False)

rotate(angle, axis)

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

Parameters:

• angle – The angle to rotate by in radians. Positive is clockwise, negative is anticlockwise (When looking in the direction of 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)

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 – Angle to set the rotation to in radians. Positive is clockwise, negative is anticlockwise.

• axis – Axis to rotate around.

Raises:

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

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 – Relative rotation of the Y axis around the X axis in radians. This should be between -pi and pi (inclusive).

• plunge – Relative rotation of the X axis around the Y axis in radians. This should be between -pi / 2 and pi / 2 (exclusive).

• bearing – 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)

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 block_attributes: PrimitiveAttributes

Access block attributes.

block_model.block_attributes[“Blocktastic”] will return the block attribute called “Blocktastic”.

Returns:

Access to the block attributes.

Return type:

PrimitiveAttributes

property block_centroids: PointArray

An array of the centre points of each block in the model.

This is an ndarray of shape (block_count, 3) of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] where N is the block_count.

property block_colours: ColourArray

An array of the colours of each block in the model.

This is represented as a ndarray of shape (block_count, 4) where each row i represents the colour of the ith block in the model in the form [Red, Green, Blue, Alpha].

When setting block colours, you may omit the Alpha component.

property block_count: int

The count of blocks in the model.

property block_resolution: BlockSize

The resolution of the block model.

The array [col_res, row_res and slice_res]. These are the same values as used to create the block model. Once the block model has been created, these values cannot be changed.

property block_selection: BooleanArray

An array which indicates which blocks are selected.

This is represented as an ndarray of bools with shape: (block_count,). True indicates the block is selected; False indicates it is not selected.

Notes

In mapteksdk version 1.0, block_selection returned a 3D ndarray. To get the same functionality, see block_selection_3d property of dense block models.

property block_sizes: BlockSizeArray

An array of the sizes of each block in the model

This is represented as an ndarray of shape (block_count, 3). Each row represents the size of one block in the form [column_size, row_size, slice_size] where column_size, row_size and slice_size are positive numbers.

This means that the extent for the block with index i is calculated as: (block_centroids[i] - block_sizes[i] / 2, block_centroids[i] + block_sizes[i] / 2)

Notes

For DenseBlockModels, all block_sizes are the same.

property block_to_grid_index: IndexArray

A mapping of the blocks to the primary blocks.

This is an ndarray with the int dtype containing the mapping of the blocks to the row, column and slice their centroid lies within. This has shape (N, 3) where N is the block_count and each item is of the form [column, row, slice].

This means that the column, row and slice of the block centred at block_centroids[i] is block_to_grid_index[i].

Notes

For DenseBlockModels, there is only one block per grid cell and thus each item of the array will be unique.

property block_visibility: BooleanArray

An array which indicates which blocks are visible.

This is represented as an ndarray of bools with shape: (block_count,). True indicates the block is visible, False indicates it is not visible.

Notes

In mapteksdk version 1.0 block_visibility returned a 3D ndarray. To get the same functionality, see block_visibility_3d property of dense block models.

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.

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

Alias for column count.

This exists so that the property can be referred to by the same name as the argument in the constructor.

property col_res: int

The number of columns of blocks in the model.

This is the col_res parameter passed into the constructor.

property column_count: int

The number of columns in the underlying block model.

This is the number of blocks in the X direction of the block model’s coordinate system. Note that it only corresponds with the direction of the X-axis if the block model is not rotated. This is the column_count value passed to the constructor.

convert_to_block_coordinates(world_coordinates)

Converts points in world coordinates to points in block coordinates.

The block coordinate system for a particular model is defined such that [0, 0, 0] is the centre of the block in row 0, column 0 and slice 0. The X axis is aligned with the columns, the Y axis is aligned with the rows and the Z axis is aligned with the slices of the model. This makes the centre of the primary block in column i, row j and slice k to be: [column_res * i, row_res * j, slice_res * k].

This function performs no error checking that the points lies within the model.

Parameters:

world_coordinates (array_like) – Points in world coordinates to convert to block coordinates.

Returns:

Numpy array containing world_coordinates converted to be in block_coordinates.

Return type:

numpy.ndarray

Raises:

ValueError – If world_coordinates has an invalid shape.

Notes

If a block model has origin = [0, 0, 0] and has not been rotated, then the block and world coordinate systems are identical.

Block models of differing size, origin or rotation will have different block coordinate systems.

convert_to_world_coordinates(block_coordinates)

Converts points in block coordinates to points in world coordinates.

This is the inverse of the transformation performed by convert_to_block_coordinates.

Parameters:

block_coordinates (npt.ArrayLike) – Points in block coordinates to convert to world coordinates.

Returns:

Numpy array containing block_coordinates converted to world_coordinates.

Return type:

numpy.ndarray

Raises:

ValueError – If block_coordinates has an invalid shape.

Notes

Block models of differing size, origin or rotation will have different block coordinate systems.

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_block_attribute(attribute_name)

Delete a block attribute.

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

grid_index(start, stop=None)

Index block properties via row, slice and column instead of index.

Generates a boolean index for accessing block properties by row, column and slice instead of by block. The boolean index will include all subblocks between primary block start (inclusive) and primary block stop (exclusive), or all subblocks within primary block start if stop is not specified.

Parameters:

• start (npt.ArrayLike | int) – An array_like containing three elements - [column, row, slice]. The returned boolean index will include all blocks in a greater column, row and slice. If this is an integer, that integer is interpreted as the column, row and slice.

• end – An array_like containing three elements - [column, row, slice]. If None (Default) this is start + 1 (The resulting index will contain all blocks within primary block start). If not None, the boolean index will include all blocks between start (inclusive) and end (exclusive). If this is an integer, that integer is interpreted as the column, row and slice index.

• stop (npt.ArrayLike | int | None) –

Returns:

A boolean index into the block property arrays. This is an array of booleans of shape (block_count,). If element i is True then subblock i is within the range specified by start and stop. If False it is not within that range.

Return type:

ndarray

Raises:

• TypeError – If start or stop are invalid types.

• ValueError – If start or stop are incorrect shapes.

Examples

These examples require a block model to be at “blockmodels/target”

This example selects all subblocks within the primary block in column 0, row 0 and slice 0:

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("blockmodels/target") as edit_model:
...     index = edit_model.grid_index([0, 0, 0])
...     edit_model.block_selection[index] = True

By passing two values to grid index, it is possible to operate on all subblocks within a range of subblocks. This example passes [0, 2, 2] and [4, 5, 6] meaning all subblocks which have 0 <= column < 4 and 2 <= row < 5 and 2 <= slice < 6 will be selected by grid_index. By passing this index to block visibility, all subblocks within those primary blocks are made invisible.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("blockmodels/target") as edit_model:
...     index = edit_model.grid_index([0, 2, 2], [4, 5, 6])
...     edit_model.block_visibility[index] = False

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_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 origin: Point

The origin of the block model represented as a point.

Setting the origin will translate the entire block model to be centred around the new origin.

Warning

The origin is located in the centre of the block in the 0th row, 0th column and 0th slice. Thus the origin is offset by half a block relative to the bottom corner of the block model.

Notes

For DenseBlockModels the resulting changes to the block_centroids will not occur until save is called. For SubblockedBlockModels the resulting changes to the block_centroids are immediately available, however changing the origin of such a model is slower.

Examples

Changing the origin will change the block model centroids, in this case by translating them by 1 unit in the X direction, 2 units in the Y direction and 3 units in the Z direction. Note that as this is a DenseBlockModel, the model needs to be saved (in this case via closing ending the with block) before the changes to the centroids will occur.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.new("blockmodels/model", DenseBlockModel(
...         col_res=2, row_res=3, slice_res=4,
...         col_count=2, row_count=2, slice_count=2)) as new_model:
...     new_model.origin = [1, 2, 3]
>>> with project.edit("blockmodels/model") as edit_model:
...     print(edit_model.block_centroids)
[[1, 2, 3], [3, 2, 3], [1, 5, 3], [3, 5, 3], [1, 2, 7], [3, 2, 7],
[1, 5, 7], [3, 5, 7]]

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_block(index)

Deletes the block at the specified index.

This operation is performed directly on the project to ensure that all properties (such as block_visibility and block_attributes) for the deleted block are deleted as well.

Does nothing if requested to delete a non-existent block.

Parameters:

index (int) – Index of the block to the delete. This index should be greater than or equal to 0 and less than block_count.

Raises:

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

Warning

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

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.

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.

property row_count: int

The number of rows in the block model.

This is the number of blocks in the Y direction of the block model’s coordinate system. Note that it only corresponds with the direction of the Y-axis if the block model is not rotated. This is the row_count value passed to the constructor.

property row_res: int

The number of rows of blocks in the model.

This is the row resolution (row_res) passed into the constructor.

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

Create a new block attribute with the specified name and data.

Saving a block 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) – Data for the associated attribute. This should be a ndarray of shape (block_count,). The ith entry in this array is the value of this primitive attribute for the ith block.

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

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

The number of slices in the block model.

This is the number of blocks in the Z direction of the block model’s coordinate system. Note that it only corresponds with the direction of the Z-axis if the block model is not rotated. This is the slice_count value passed to the constructor.

property slice_res: int

The number of slices of blocks in the model.

This is the slice resolution (slice_res) passed into the constructor.

class SparseBlockModel(object_id=None, lock_type=LockType.READWRITE, *, row_count=None, col_count=None, slice_count=None, row_res=None, col_res=None, slice_res=None)

Bases: Topology, BlockDeletionProperties, RotationMixin

A sparse regular block model.

Similar to a dense block model, all blocks are the same size. The primary difference is a sparse block model allows for areas in the model extent to be empty (i.e. They do not contain any blocks).

This allows for more compact storage for block models where a large proportion of the blocks do not contain data because blocks which do not contain data do not need to be stored. For block models in which most blocks contain data, a dense block model will provide more efficient storage.

Parameters:

• col_count (int) – The number of columns of blocks in the block model. In the block model coordinate system, this is the number of blocks in the X direction. Must be greater than zero.

• row_count (int) – The number of rows of blocks in the block model. In the block model coordinate system, this is the number of blocks in the Y direction. Must be greater than zero.

• slice_count (int) – The number of slices of blocks in the block model. In the block model coordinate system, this is the number of blocks in the Z direction. Must be greater than zero.

• col_res (float) – The size of each block in the direction of the columns of the model. In the block model coordinate system, this is the size of the blocks in the X direction. Must be greater than zero.

• row_res (float) – The size each of block in the direction of the rows of the model. In the block model coordinate system, this is the size of the blocks in the Y direction. Must be greater than zero.

• slice_res (float) – The size of each block in the direction of the slices of the model. In the block model coordinate system, this is the size of the blocks in the Z direction. Must be greater than zero.

Examples

The following example demonstrates creating a simple sparse block model and adding it to a new view.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import SparseBlockModel, ObjectID
>>> from mapteksdk.operations import open_new_view
>>> def create_simple_model(project: Project, path: str
...     ) -> ObjectID[SparseBlockModel]:
...   '''Create a simple sparse block model.
...
...   The created sparse block model has three rows, slices and columns
...   however only the corner and centre blocks exist.
...
...   The central block is coloured red and the corner blocks are coloured
...   orange.
...
...   Parameters
...   ----------
...   project
...     The Project to use to create the sparse block model.
...   path
...     The path to create the sparse block model at.
...
...   Returns
...   -------
...   ObjectID
...     ObjectID of the newly created sparse block model.
...   '''
...   with project.new(path, SparseBlockModel(
...       row_count=3, slice_count=3, col_count=3,
...       row_res=1.5, col_res=1.25, slice_res=1.75
...       )) as model:
...     model.block_indices = [
...       [0, 0, 0], [2, 0, 0], [0, 2, 0], [0, 0, 2],
...       [2, 2, 0], [0, 2, 2], [2, 0, 2], [2, 2, 2],
...       [1, 1, 1]
...     ]
...     # Nine block indices means there are nine blocks in the model,
...     # so only nine colours need to be provided.
...     model.block_colours = [
...       [255, 165, 0, 255], [255, 165, 0, 255], [255, 165, 0, 255],
...       [255, 165, 0, 255], [255, 165, 0, 255], [255, 165, 0, 255],
...       [255, 165, 0, 255], [255, 165, 0, 255], [255, 0, 0, 255]
...     ]
...   return model.id
...
>>> if __name__ == "__main__":
...   with Project() as main_project:
...     oid = create_simple_model(main_project, "block models/simple")
...     open_new_view(oid)

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.

property id: ObjectID[SparseBlockModel]

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

property block_indices: numpy.ndarray

Maps block indices to the row, column and slice containing the block.

This is an array of shape (block_count, 3) where the ith row contains the [slice, row, column] of the ith block in the model.

Changing the block_indices will change the block centroids. The changes will not be propagated to the centroids until save() is called.

Warning

If any block is outside of the model (i.e. The slice is greater than the slice_count, the row is greater than the row count or the column is greater than the column count), the block will be silently removed when save() is called.

Block indices can contain duplicate indices resulting in the model containing duplicate blocks (i.e. Two blocks with the same centroid and size).

Notes

This array is the same as the block_to_grid_index, except the 0th and 2nd columns have been swapped.

• The block_indices stores the mapping as [slice, row, column].

• The block_to_grid_index stores the mapping as [column, row, slice].

property block_count

The count of blocks in the model.

property block_centroids

An array of the centre points of each block in the model.

This is an ndarray of shape (block_count, 3) of the form: [[x1, y1, z1], [x2, y2, z2], …, [xN, yN, zN]] where N is the block_count.

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 block_attributes: PrimitiveAttributes

Access block attributes.

block_model.block_attributes[“Blocktastic”] will return the block attribute called “Blocktastic”.

Returns:

Access to the block attributes.

Return type:

PrimitiveAttributes

property block_colours: ColourArray

An array of the colours of each block in the model.

This is represented as a ndarray of shape (block_count, 4) where each row i represents the colour of the ith block in the model in the form [Red, Green, Blue, Alpha].

When setting block colours, you may omit the Alpha component.

property block_resolution: BlockSize

The resolution of the block model.

The array [col_res, row_res and slice_res]. These are the same values as used to create the block model. Once the block model has been created, these values cannot be changed.

property block_selection: BooleanArray

An array which indicates which blocks are selected.

This is represented as an ndarray of bools with shape: (block_count,). True indicates the block is selected; False indicates it is not selected.

Notes

In mapteksdk version 1.0, block_selection returned a 3D ndarray. To get the same functionality, see block_selection_3d property of dense block models.

property block_sizes

An array of the sizes of each block in the model

This is represented as an ndarray of shape (block_count, 3). Each row represents the size of one block in the form [column_size, row_size, slice_size] where column_size, row_size and slice_size are positive numbers.

This means that the extent for the block with index i is calculated as: (block_centroids[i] - block_sizes[i] / 2, block_centroids[i] + block_sizes[i] / 2)

Notes

For DenseBlockModels, all block_sizes are the same.

property block_to_grid_index: IndexArray

A mapping of the blocks to the primary blocks.

This is an ndarray with the int dtype containing the mapping of the blocks to the row, column and slice their centroid lies within. This has shape (N, 3) where N is the block_count and each item is of the form [column, row, slice].

This means that the column, row and slice of the block centred at block_centroids[i] is block_to_grid_index[i].

Notes

For DenseBlockModels, there is only one block per grid cell and thus each item of the array will be unique.

property block_visibility: BooleanArray

An array which indicates which blocks are visible.

This is represented as an ndarray of bools with shape: (block_count,). True indicates the block is visible, False indicates it is not visible.

Notes

In mapteksdk version 1.0 block_visibility returned a 3D ndarray. To get the same functionality, see block_visibility_3d property of dense block models.

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.

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

Alias for column count.

This exists so that the property can be referred to by the same name as the argument in the constructor.

property col_res: int

The number of columns of blocks in the model.

This is the col_res parameter passed into the constructor.

property column_count: int

The number of columns in the underlying block model.

This is the number of blocks in the X direction of the block model’s coordinate system. Note that it only corresponds with the direction of the X-axis if the block model is not rotated. This is the column_count value passed to the constructor.

convert_to_block_coordinates(world_coordinates)

Converts points in world coordinates to points in block coordinates.

The block coordinate system for a particular model is defined such that [0, 0, 0] is the centre of the block in row 0, column 0 and slice 0. The X axis is aligned with the columns, the Y axis is aligned with the rows and the Z axis is aligned with the slices of the model. This makes the centre of the primary block in column i, row j and slice k to be: [column_res * i, row_res * j, slice_res * k].

This function performs no error checking that the points lies within the model.

Parameters:

world_coordinates (array_like) – Points in world coordinates to convert to block coordinates.

Returns:

Numpy array containing world_coordinates converted to be in block_coordinates.

Return type:

numpy.ndarray

Raises:

ValueError – If world_coordinates has an invalid shape.

Notes

If a block model has origin = [0, 0, 0] and has not been rotated, then the block and world coordinate systems are identical.

Block models of differing size, origin or rotation will have different block coordinate systems.

convert_to_world_coordinates(block_coordinates)

Converts points in block coordinates to points in world coordinates.

This is the inverse of the transformation performed by convert_to_block_coordinates.

Parameters:

block_coordinates (npt.ArrayLike) – Points in block coordinates to convert to world coordinates.

Returns:

Numpy array containing block_coordinates converted to world_coordinates.

Return type:

numpy.ndarray

Raises:

ValueError – If block_coordinates has an invalid shape.

Notes

Block models of differing size, origin or rotation will have different block coordinate systems.

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_block_attribute(attribute_name)

Delete a block attribute.

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

grid_index(start, stop=None)

Index block properties via row, slice and column instead of index.

Generates a boolean index for accessing block properties by row, column and slice instead of by block. The boolean index will include all subblocks between primary block start (inclusive) and primary block stop (exclusive), or all subblocks within primary block start if stop is not specified.

Parameters:

• start (npt.ArrayLike | int) – An array_like containing three elements - [column, row, slice]. The returned boolean index will include all blocks in a greater column, row and slice. If this is an integer, that integer is interpreted as the column, row and slice.

• end – An array_like containing three elements - [column, row, slice]. If None (Default) this is start + 1 (The resulting index will contain all blocks within primary block start). If not None, the boolean index will include all blocks between start (inclusive) and end (exclusive). If this is an integer, that integer is interpreted as the column, row and slice index.

• stop (npt.ArrayLike | int | None) –

Returns:

A boolean index into the block property arrays. This is an array of booleans of shape (block_count,). If element i is True then subblock i is within the range specified by start and stop. If False it is not within that range.

Return type:

ndarray

Raises:

• TypeError – If start or stop are invalid types.

• ValueError – If start or stop are incorrect shapes.

Examples

These examples require a block model to be at “blockmodels/target”

This example selects all subblocks within the primary block in column 0, row 0 and slice 0:

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("blockmodels/target") as edit_model:
...     index = edit_model.grid_index([0, 0, 0])
...     edit_model.block_selection[index] = True

By passing two values to grid index, it is possible to operate on all subblocks within a range of subblocks. This example passes [0, 2, 2] and [4, 5, 6] meaning all subblocks which have 0 <= column < 4 and 2 <= row < 5 and 2 <= slice < 6 will be selected by grid_index. By passing this index to block visibility, all subblocks within those primary blocks are made invisible.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("blockmodels/target") as edit_model:
...     index = edit_model.grid_index([0, 2, 2], [4, 5, 6])
...     edit_model.block_visibility[index] = False

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_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 origin: Point

The origin of the block model represented as a point.

Setting the origin will translate the entire block model to be centred around the new origin.

Warning

The origin is located in the centre of the block in the 0th row, 0th column and 0th slice. Thus the origin is offset by half a block relative to the bottom corner of the block model.

Notes

For DenseBlockModels the resulting changes to the block_centroids will not occur until save is called. For SubblockedBlockModels the resulting changes to the block_centroids are immediately available, however changing the origin of such a model is slower.

Examples

Changing the origin will change the block model centroids, in this case by translating them by 1 unit in the X direction, 2 units in the Y direction and 3 units in the Z direction. Note that as this is a DenseBlockModel, the model needs to be saved (in this case via closing ending the with block) before the changes to the centroids will occur.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import DenseBlockModel
>>> project = Project()
>>> with project.new("blockmodels/model", DenseBlockModel(
...         col_res=2, row_res=3, slice_res=4,
...         col_count=2, row_count=2, slice_count=2)) as new_model:
...     new_model.origin = [1, 2, 3]
>>> with project.edit("blockmodels/model") as edit_model:
...     print(edit_model.block_centroids)
[[1, 2, 3], [3, 2, 3], [1, 5, 3], [3, 5, 3], [1, 2, 7], [3, 2, 7],
[1, 5, 7], [3, 5, 7]]

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_block(index)

Deletes the block at the specified index.

This operation is performed directly on the project to ensure that all properties (such as block_visibility and block_attributes) for the deleted block are deleted as well.

Does nothing if requested to delete a non-existent block.

Parameters:

index (int) – Index of the block to the delete. This index should be greater than or equal to 0 and less than block_count.

Raises:

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

Warning

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

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.

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.

property row_count: int

The number of rows in the block model.

This is the number of blocks in the Y direction of the block model’s coordinate system. Note that it only corresponds with the direction of the Y-axis if the block model is not rotated. This is the row_count value passed to the constructor.

property row_res: int

The number of rows of blocks in the model.

This is the row resolution (row_res) passed into the constructor.

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

Create a new block attribute with the specified name and data.

Saving a block 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) – Data for the associated attribute. This should be a ndarray of shape (block_count,). The ith entry in this array is the value of this primitive attribute for the ith block.

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

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

The number of slices in the block model.

This is the number of blocks in the Z direction of the block model’s coordinate system. Note that it only corresponds with the direction of the Z-axis if the block model is not rotated. This is the slice_count value passed to the constructor.

property slice_res: int

The number of slices of blocks in the model.

This is the slice resolution (slice_res) passed into the constructor.