mapteksdk.data.geotechnical module

Geotechnical data types.

Currently this only includes discontinuities, however in the future it may be expanded to contain other geotechnical objects such as stereonets.

class Polarity(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum representing the polarity of a Discontinuity.

UNKNOWN = 0

The polarity of the discontinuity is unknown.

This is the default polarity for newly created discontinuities.

UPRIGHT = 1

The discontinuity is upright.

This indicates that the discontinuity is upright relative to the orientation the rocks were originally deposited in.

OVERTURNED = -1

The discontinuity is overturned.

This indicates that the discontinuity is overturned relative to the orientation the rocks were originally deposited in.

flip()

Flip the polarity value.

This returns the opposite polarity.

Returns:

The opposite polarity. If called on Polarity.OVERTURNED, this is Polarity.UPRIGHT. If called on Polarity.UPRIGHT, this is Polarity.OVERTURNED. If called on Polarity.UNKNOWN, this is Polarity.UNKNOWN.

Return type:

Polarity

class Discontinuity(object_id=None, lock_type=LockType.READWRITE)

Bases: Topology, TwoSidedColouringMixin

A discontinuity (Also known as a tangent plane).

These are generally used to mark a change in the physical or chemical characteristics in soil or rock mass.

Discontinuities with similar properties are often placed in special containers known as discontinuity sets.

Raises:

DegenerateTopologyError – If on save, there are fewer than three points in the object.

See also

discontinuity

Help page for this class.

Examples

The simplest way to define a discontinuity is to define the planar points. This example defines a discontinuity using points in the plane with the equation 3x - y + 2z + 4 = 0. The other properties are automatically derived from the points used to define the discontinuity.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Discontinuity
>>> points = [[1, 1, -3], [-1, 2, 0.5], [-2, -2, 0],
...           [0, -2, -3], [-4, 0, 4], [2, 2, -4]]
>>> project = Project()
>>> with project.new("geotechnical/3x-y+2z+4", Discontinuity) as plane:
...     plane.planar_points = points
>>> with project.read(plane.id) as read_plane:
...     print("Dip: ", read_plane.dip)
...     print("Dip direction: ", read_plane.dip_direction)
...     print("Location: ", read_plane.location)
...     print("Area: ", read_plane.area)
...     print("Length: ", read_plane.length)
Dip:  1.0068536854342678
Dip direction:  1.8925468811915387
Location:  [-0.66666667  0.16666667 -0.91666667]
Area:  28.062430400804566
Length:  10.198039027185569

A discontinuity can also be defined by setting the dip, dip direction and location. This is less preferable than the other methods because the discontinuity will not have a length or area.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Discontinuity
>>> project = Project()
>>> with project.new("geotechnical/simple", Discontinuity) as plane:
...     plane.dip = math.pi / 4
...     plane.dip_direction = math.pi / 2
...     plane.location = [4, 2, 1]
>>> with project.read(plane.id) as read_plane:
...     print("Points", read_plane.planar_points)
...     print("Area: ", read_plane.area)
...     print("Length: ", read_plane.length)
Points [[3.29289322 2.         1.70710678]
[4.35355339 1.1339746  0.64644661]
[4.35355339 2.8660254  0.64644661]]
Area:  nan
Length:  nan

when creating a new discontinuity, it possible to define the planar points and the dip, dip direction and location. This causes the points to be projected onto the plane defined by the dip and dip direction and to be translated to be centred at the specified location. In the below example, though the points are originally centred around the origin and in the XY plane they are translated to be centred around the new centre and to be in the new plane.

>>> import math
>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Discontinuity
>>> points = [[-1, -1, 0], [1, -1, 0], [-1, 1, 0], [1, 1, 0]]
>>> project = Project()
>>> with project.new("geotechnical/both", Discontinuity) as plane:
...     plane.planar_points = points
...     plane.dip = math.pi / 4
...     plane.dip_direction = math.pi / 2
...     plane.location = [4, 2, 1]
>>> with project.read(plane.id) as read_plane:
...     print("Points", read_plane.planar_points)
...     print("Dip: ", read_plane.dip)
...     print("Dip direction: ", read_plane.dip_direction)
...     print("Location: ", read_plane.location)
...     print("Area: ", read_plane.area)
...     print("Length: ", read_plane.length)
Points [[3.29289322 3.         1.70710678]
 [3.29289322 1.         1.70710678]
 [4.70710678 3.         0.29289322]
 [4.70710678 1.         0.29289322]]
Dip:  0.7853981633974482
Dip direction:  1.5707963267948966
Location:  [4. 2. 1.]
Area:  4.0
Length:  2.8284271247461907

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

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

property planar_points

The points used to define the discontinuity.

This is an array of floats of shape (n, 3) where n is the planar_point_count. These points are coplanar.

When set the first three of these points are used to define the dip and dip direction. If the first three points are collinear, the resulting discontinuity object will be empty.

property planar_point_count

The number of points used to visualize the discontinuity.

property planar_facets

The facets used to visualise the discontinuity.

These are derived from the points and do not support direct assignment.

If you change planar_points, the corresponding changes to the planar_facets will not occur until save() is called.

property planar_facet_count

The count of facets used to visualise the discontinuity.

property planar_colour

The colour of the facets. This is a single value used for all facets.

The alpha value has no effect. This is provided as an RGBA colour for consistency.

property has_two_sided_colouring: bool

True if this surface has two sided colouring.

If this is True, the point, edge and facet colours are used to colour the “front” of the surface, and the back colour is used to colour the “back” of the surface.

If this is False, the point, edge and facet colours are used to colour both the back and the front of the surface.

Examples

This property can be used to check if an object uses two sided colouring. The following example uses this property to write a report on the picked object stating whether it has two sided colouring:

>>> from mapteksdk.project import Project
>>> from mapteksdk.operations import object_pick, write_report
>>> if __name__ == "__main__":
...   with Project() as project:
...     oid = object_pick(
...       label="Pick an object to query two sided colouring.")
...     title = f"Does '{oid.path}' use two sided colouring?"
...     with project.read(oid) as read_object:
...       try:
...         write_report(title, str(read_object.has_two_sided_colouring))
...       except AttributeError:
...         write_report(title, "Unknown")

property dip

The dip of the discontinuity.

This is the angle in radians the discontinuity is rotated by in the dip direction.

The dip and dip direction, taken together, define the plane the discontinuity lies in. If they are changed, upon save() the planar_points will be projected to lie on the new plane.

Raises:

ValueError – If set to an value which cannot be converted to a float, or is below zero or greater than pi / 2.

Warning

Dip values close to zero cause issues with calculating the dip direction which can result in unintuitive behaviour.

property dip_direction

The dip direction of the discontinuity.

This is the angle in radians around the z axis which the plane is rotated by dip radians.

The dip and dip direction, taken together, define the plane the discontinuity lies in. If they are changed, upon save() the planar_points will be projected to lie on the new plane.

Raises:

ValueError – If set to a value which cannot be converted to a float, or is below zero or greater than or equal to 2 * pi.

Notes

For completely horizontal discontinuities, this may be NaN.

property strike

The strike of the discontinuity.

This is the angle in radians to the y axis of the line of intersection between the discontinuity plane and the horizontal plane (XY plane).

This is derived from the dip direction. Changing the dip direction will change the strike and vice versa.

Raises:

ValueError – If set to a value which cannot be converted to a float, or is below zero or greater than or equal to 2 * pi.

Notes

For completely horizontal discontinuities, this may be NaN.

property plunge

The plunge angle of the discontinuity.

This is derived from the dip - changing the dip will change the plunge and vice versa.

Raises:

ValueError – If set to a value which cannot be converted to a float, or is below zero or greater than pi / 2.

Notes

The dip and plunge for a discontinuity always add up to pi / 2.

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 back_colour: numpy.ndarray

The colour used to colour the back of the object.

The back colour is represented by an RGB colour instead of a RGBA colour. The back colour cannot be transparent, so it does not have an alpha component.

Setting the back colour will set has_two_sided_colouring to True.

Notes

The default back colour is red (220, 0, 0).

The back colour can still be read if has_two_sided_colouring is False, however it will not be used to visualise the object.

Examples

Setting the back colour sets the object to use two sided colouring (if it is not using it already). The following example demonstrates this by creating a square with one facet coloured yellow, one facet coloured cyan and the back of both facets coloured grey.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Surface
>>> if __name__ == "__main__":
...   with Project() as project:
...     with project.new("surfaces/two_sided", Surface) as surface:
...       surface.points = [
...         [-5, -5, 0], [5, -5, 0], [5, 5, 0], [-5, 5, 0]
...       ]
...       surface.facets = [[0, 1, 2], [0, 2, 3]]
...       surface.facet_colours = [
...         [255, 255, 0, 255], [0, 255, 255, 255]
...       ]
...       surface.back_colour = [127, 127, 127]

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

dissociate_raster(raster)

Removes the raster from the object.

If an error occurs after dissociating a raster resulting in save() not being called, the dissociation of the raster can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Dissociating a raster will not be undone if an error occurs.

Parameters:

raster (Raster | ObjectID[Raster]) – The raster to dissociate.

Returns:

True if the raster was successfully dissociated from the object, False if the raster was not associated with the object.

Return type:

bool

Raises:

• TypeError – If raster is not a Raster.

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

Notes

This only removes the association between the Raster and the object, it does not clear the registration information from the Raster.

Examples

Dissociate the first raster found on a picked object.

>>> from mapteksdk.project import Project
>>> from mapteksdk import operations
>>> project = Project()
>>> oid = operations.object_pick(
...     support_label="Pick an object to remove a raster from.")
... with project.edit(oid) as data_object:
...     report = f"There were no raster to remove from {oid.path}"
...     for index in data_object.rasters:
...         data_object.dissociate_raster(data_object.rasters[index])
...         report = f"Removed raster {index} from {oid.path}"
...         break
... # Now that the raster is dissociated and the object is closed,
... # the raster can be associated with a different object.
... operations.write_report("Remove Raster", report)

property extent: Extent

The axes aligned bounding extent of the object.

get_attribute(name)

Returns the value for the attribute with the specified name.

Parameters:

name (str) – The name of the object attribute to get the value for.

Returns:

The value of the object attribute name. For dtype = datetime.datetime this is an integer representing the number of milliseconds since 1st Jan 1970. For dtype = datetime.date this is a tuple of the form: (year, month, day).

Return type:

ObjectAttributeTypes

Raises:

KeyError – If there is no object attribute called name.

Warning

In the future this function may be changed to return datetime.datetime and datetime.date objects instead of the current representation for object attributes of type datetime.datetime or datetime.date.

get_attribute_type(name)

Returns the type of the attribute with the specified name.

Parameters:

name (str) – Name of the attribute whose type should be returned.

Returns:

The type of the object attribute name.

Return type:

ObjectAttributeDataTypes

Raises:

KeyError – If there is no object attribute called name.

get_colour_map()

Return the ID of the colour map object associated with this object.

Returns:

The ID of the colour map object or null object ID if there is no colour map.

Return type:

ObjectID

property is_read_only: bool

If this object is read-only.

This will return True if the object was open with Project.read() and False if it was open with Project.edit() or Project.new(). Attempting to edit a read-only object will raise an error.

property lock_type: LockType

Indicates whether operating in read-only or read-write mode.

Use the is_read_only property instead for checking if an object is open for reading or editing.

Returns:

The type of lock on this object. This will be LockType.ReadWrite if the object is open for editing and LockType.Read if the object is open for reading.

Return type:

LockType

property 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 rasters: dict[int, ObjectID[Raster]]

The raster associated with this object.

This is a dictionary of raster indices and Object IDs of the raster images currently associated with this object.

The keys are the raster ids and the values are the Object IDs of the associated rasters. Note that all raster ids are integers however they may not be consecutive - for example, an object may have raster ids 0, 1, 5 and 200.

Notes

Rasters with higher indices appear on top of rasters with lower indices. The maximum possible raster id is 255.

Removing a raster from this dictionary will not remove the raster association from the object. Use dissociate_raster to do this.

Examples

Iterate over all rasters on an object and invert the colours. Note that this will fail if there is no object at the path “target” and it will do nothing if no rasters are associated with the target.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for raster in read_object.rasters.values():
...         with project.edit(raster) as edit_raster:
...             edit_raster.pixels[:, :3] = 255 - edit_raster.pixels[:, :3]

remove_coordinate_system()

Remove the coordinate system from the object.

This does not change the geometry of the object. It only clears the label which states what coordinate system the object is in.

This has no effect if the object does not have a coordinate system.

save()

Save the changes made to the object.

Generally a user does not need to call this function, because it is called automatically at the end of a with block using Project.new() or Project.edit().

Returns:

The change reasons for the operation. This depends on what changes to the object were saved. If the api_version is less than 1.9, this always returns ChangeReasons.NO_CHANGE.

Return type:

ChangeReasons

set_attribute(name, dtype, data)

Sets the value for the object attribute with the specified name.

This will overwrite any existing attribute with the specified name.

Parameters:

• name (str) – The name of the object attribute for which the value should be set.

• dtype (type[Union[NoneType, Type[NoneType], ctypes.c_bool, ctypes.c_byte, ctypes.c_ubyte, ctypes.c_short, ctypes.c_ushort, ctypes.c_long, ctypes.c_ulong, ctypes.c_longlong, ctypes.c_ulonglong, ctypes.c_float, ctypes.c_double, ctypes.c_char_p, datetime.datetime, datetime.date, bool, int, float, str]] | None) – The type of data to assign to the attribute. This should be a type from the ctypes module or datetime.datetime or datetime.date. Passing bool is equivalent to passing ctypes.c_bool. Passing str is equivalent to passing ctypes.c_char_p. Passing int is equivalent to passing ctypes.c_int16. Passing float is equivalent to passing ctypes.c_double.

• data (Any) – The value to assign to object attribute name. For dtype = datetime.datetime this can either be a datetime object or timestamp which will be passed directly to datetime.utcfromtimestamp(). For dtype = datetime.date this can either be a date object or a tuple of the form: (year, month, day).

Raises:

• ValueError – If dtype is an unsupported type.

• TypeError – If value is an inappropriate type for object attribute name.

• ValueError – If name starts or ends with whitespace or is empty.

• RuntimeError – If a different error occurs.

Notes

If an error occurs after adding a new object attribute or editing an existing object attribute resulting in save() not being called, the changes to the object attributes can only be undone if the application’s API version is 1.6 or greater.

Prior to mapteksdk 1.6: Adding new object attributes, or editing the values of object attributes, will not be undone if an error occurs.

Examples

Create an object attribute on an object at “target” and then read its value.

>>> import ctypes
>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.edit("target") as edit_object:
...     edit_object.set_attribute("count", ctypes.c_int16, 0)
... with project.read("target") as read_object:
...     print(read_object.get_attribute("count"))
0

property trend

The trend of the discontinuity in radians.

This is derived from the dip direction. Changing the dip direction will change the trend and vice versa.

Raises:

ValueError – If set to a value which cannot be converted to a float, or is below zero or greater than or equal to pi * 2.

property polarity: Polarity

The polarity of the Discontinuity.

See the enum for more details on the meaning of each polarity value.

If the discontinuity’s polarity is known and it is displayed using the “Simple” display type, the front of the discontinuity will be coloured planar_colour and the back will be coloured back_colour.

Examples

Create a discontinuity with “upright” polarity. When viewed in “simple” mode, the discontinuity will appear as a disk at [0, 0, 0]. The front of the disk will be coloured dark green and the back of the disk will be coloured grey (The planar colour determines the front colour and the back colour determines the back colour).

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Discontinuity, Polarity
>>> if __name__ == "__main__":
...   project = Project()
...   path = "geotechnical/upright"
...   with project.new(path, Discontinuity) as new_plane:
...     new_plane.planar_points = [[0, 0, 0], [1, 0, 0], [0, 1, 0]]
...     new_plane.polarity = Polarity.UPRIGHT
...     new_plane.planar_colour = [0, 165, 15, 255]
...     new_plane.back_colour = [67, 67, 67]
...   with project.read(new_plane.id) as read_plane:
...     print(read_plane.planar_points)
...     print(read_plane.planar_facets)
...     print(read_plane.polarity)
...     print(read_plane.planar_colour)

property length

The length of the discontinuity.

This is the diameter of the smallest sphere capable of containing all of the points.

Notes

For empty discontinuities, the length will be NaN.

property location

The location of the discontinuity in the form [X, Y, Z].

By default, this is the mean of the points used to construct the discontinuity.

Notes

For empty discontinuities, this will be NaN.

property area

The scaled area of the discontinuity.

Changes to the area will not occur until save() is called. This may not be exactly equal to the area of the planar facets.

flip_polarity()

Flips the polarity of the discontinuity.

See the documentation on the Polarity enum for the effect of flipping the polarity of an enum.