mapteksdk.data.rotation module

Rotation support.

This module contains a mixin class which adds rotation functions to inheriting objects. It is up to the inheriting object to apply the rotation to the primitives and save the rotation.

class RotationMixin

Bases: object

Mixin class designed to add rotation to a Topology object.

Inheriting classes must implement _get_rotation which gets the rotation from the Project and they must provide their own code for saving the rotation to the Project.

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

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.

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