mapteksdk.data.primitives.block_properties module

Support for block primitives.

Block primitives are three dimensional cubes or rectangular prisms defined by a centroid and a block size. Given a block with centroid [0, 0, 0] and size [2, 4, 8] then the block will be the rectangular prism centred at [0, 0, 0] and 2 metres by 4 metres by 8 metres in size.

class BlockProperties

Bases: RotationMixin

Mixin class which provides spatial object support for block primitives.

Functions and properties defined on this class are available on all classes which support blocks.

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

The number of columns of blocks in the model.

This is the col_res parameter passed into 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.

property slice_res: int

The number of slices of blocks in the model.

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

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

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

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

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

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.

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.

delete_block_attribute(attribute_name)

Delete a block attribute.

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

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

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.

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.

class BlockDeletionProperties

Bases: BlockProperties

BlockProperties with an extra functions for deleting blocks.

Classes which inherit from BlockDeletionProperties instead of BlockProperties support everything BlockProperties supports and the removal of blocks.

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.

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.

delete_block_attribute(attribute_name)

Delete a block attribute.

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

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

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

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.