mapteksdk.geologycore.drillholes module

Drillhole data types.

class Drillhole(object_id=None, lock_type=LockType.READ)

Bases: Topology, TablesMixin

Class representing a single drillhole.

Drillholes cannot be created with Project.new() like other objects. Instead they are created through DrillholeDatabase.new_drillhole(). An error will be raised if you open the new drillhole before closing the drillhole database.

Notes

Though the values representing a Drillhole are accessed through this object, they are actually stored in the DrillholeDatabase which the Drillhole is inside.

Drillholes in the same database will have the same tables and fields.

Raises:

  • TypeError – If passed to Project.new().

  • OrphanDrillholeError – If the drillhole is not inside of a drillhole database container. This error will also be raised if a new drillhole is opened before the drillhole database is closed.

Parameters:

  • object_id (ObjectID) –

  • lock_type (LockType) –

See also

mapteksdk.geologycore.database.DrillholeDatabase.new_drillhole

Create new drillholes.

drillholes

Help page for this class.

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

Object ID that uniquely references this object in the project.

Returns:

The unique id of this object.

Return type:

ObjectID

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 name: str

The name of the drillhole.

property converted_collar: numpy.ndarray

The collar point of the drillhole adjusted for the coordinate system.

This is the collar point adjusted for the drillhole’s coordinate system and thus where the collar point appears when the drillhole is viewed in the application.

This will not match the ordinates read from the collar table (and thus the raw_collar property) if the drillhole has a coordinate system.

Raises:

Warning

If the collar table or the raw_collar property is edited, changes will only be reflected in this property after save() is called.

Notes

If there is no elevation field in the collar table, the Z ordinate will always be zero.

property raw_collar: numpy.ndarray

The collar point as it appears in the collar table.

This does not take into account the drillhole’s coordinate system.

This will not match the converted_collar property if the drillhole has a coordinate system.

Warns:

RuntimeWarning – If the table contains no elevation field and the collar is set to a point containing a non-zero Z ordinate.

Notes

If there is no elevation field in the collar table, the Z ordinate will always be zero.

Examples

If the table has an elevation field, when assigning to this property the caller should provide a northing, easting and elevation value:

>>> drillhole.raw_collar = [1.1, 2.2, 3.3]

If the table does not have an elevation field, when assigning to this property the elevation may be omitted:

>>> drillhole.raw_collar = [1.1, 2.2]
property displayed_table: BaseDrillholeTable

Returns the displayed table for the drillhole.

This is the table which contains the displayed field used to colour the intervals of the drillhole in views.

Returns:

The displayed table.

Return type:

BaseDrillholeTable

Raises:

TableNotFoundError – If the displayed table cannot be found.

property displayed_field: DrillholeDatabaseField

Returns the displayed field for the drillhole.

When the drillhole is displayed in the application, this is the field which is used to determine the intervals used to colour the drillhole. This is also the field used to determine the points and edges returned by the drillhole’s point and edge properties.

Returns:

The displayed field.

Return type:

DrillholeDatabaseField

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

set_visualisation(field, colour_map)

Set the field and colour map used to display the Drillhole.

Parameters:
Raises:

  • ReadOnlyError – If the drillhole is open for read-only.

  • TypeError – If colour_map is not an ObjectID.

  • TypeError – If field is not a DrillholeDatabaseField.

  • TypeError – If field contains numeric values and colour_map is a StringColourMap.

  • TypeError – If field contains string values and colour_map is a NumericColourMap.

  • ValueError – If field stores boolean values.

  • ValueError – If field is not a field read from this drillhole.

property points: numpy.ndarray

The points used to visualise the drillhole.

These points mark the boundaries of intervals for the displayed field in the displayed table. Thus these are a property of the visualisation of the drillhole and not the drillhole itself. This array cannot be edited directly, however edits to the displayed field will propagate to this property when the drillhole is saved.

Notes

The points of a drillhole are derived from the displayed table and cannot be edited directly from Python.

property point_selection: numpy.ndarray

Point selection array for the drillhole.

If point_selection[i] is True then the point located at points[i] is selected.

Notes

The point selection of a drillhole cannot be edited from Python.

property edges: numpy.ndarray

The edges used to visualise the drillhole.

The edges which represent the intervals of the displayed field in the displayed table. Thus these are a property of the visualisation of the drillhole and not the drillhole itself. This array cannot be edited directly, however edits to the displayed field will propagate to this property when the drillhole is saved.

Notes

The edges of a drillhole are derived from the displayed table and cannot be edited directly from Python.

property edge_selection: numpy.ndarray

Edge selection array for the drillhole.

If edge_selection[i] is True then the edge located at edges[i] is selected.

Notes

The edge selection of a drillhole cannot be edited from Python.

property assay_table: AssayTable

Returns the assay table if it exists.

This property should only be used if the caller is certain that the database only contains one assay table.

Raises:

TableNotFoundError – If there is no assay table.

Warns:

TooManyTablesWarning – If the database contains multiple assay tables. The first table was returned.

property collar_table: CollarTable

Returns the collar table if it exists.

The collar table represents the location on the surface which the drillhole was taken from.

A database can only have one collar table.

Raises:
property survey_table: SurveyTable

Returns the survey table if it exists.

A database can only contain one survey table.

Raises:
property geology_table: GeologyTable

Returns the geology table if it exists.

A database may contain multiple geology tables. This property should only be used if the caller is certain that the database only contains one geology table.

Raises:

TableNotFoundError – If there is no geology table.

Warns:

TooManyTablesWarning – If the database contains multiple geology tables. The first table was returned.

property downhole_table: DownholeTable

Returns the downhole table if it exists.

A database may contain multiple downhole tables. This property should only be used if the caller is certain that the database only contains one downhole table.

Raises:

TableNotFoundError – If there is no geology table.

Warns:

TooManyTablesWarning – If the database contains multiple geology tables. The first table was returned.

property quality_table: QualityTable

Returns the quality table if it exists.

A database may contain multiple quality tables. This property should only be used if the caller is certain that the database only contains one quality table.

Raises:

TableNotFoundError – If there is no geology table.

Warns:

TooManyTablesWarning – If the database contains multiple geology tables. The first table was returned.

property tables: list[mapteksdk.geologycore.tables.BaseDrillholeTable]

The tables representing the drillhole.

Returns:

List of BaseDrillholeTable for the drillhole.

Return type:

list

point_at_depth(depth)

Get the point in the drillhole at the specified depth.

The returned point is relative to the collar point. To get the point at the specified depth in world coordinates, you must add the collar point to this point.

This takes into account the desurvey method assigned to the drillhole database and any values in the survey table.

Parameters:

depth (float) – The depth down the hole for which the point should be returned.

Returns:

Numpy array of shape (3,) containing the X, Y and Z coordinate of the point at the specified depth down the hole. This may not correspond to any point in the points array.

Return type:

np.ndarray

Raises:

SurveyTableLoadedError – If the drillhole is open for editing and may have unsaved changes.

tables_by_type(table_type)

Returns a list of tables with the specified type.

Parameters:

table_type (DrillholeTableType) – The type of table to include in the list.

Returns:

List of BaseDrillholeTable objects with the specified table type.

Return type:

list

Raises:

KeyError – If table_type is not a DrillholeTableType.

table_by_name(name)

Returns the table with the specified name.

Parameters:

name (str) – The name of the table to return.

Returns:

The table with the specified name.

Return type:

BaseDrillholeTable

Raises:

TableNotFoundError – If there is no table with the specified name.

attribute_names()

Returns a list containing the names of all object-level attributes.

Use this to iterate over the object attributes.

Returns:

List containing the attribute names.

Return type:

list

Examples

Iterate over all object attributes of the object stared at “target” and print their values.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("target") as read_object:
...     for name in read_object.attribute_names():
...         print(name, ":", read_object.get_attribute(name))
cancel()

Cancel any pending changes to the object.

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

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

Raises:

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

  • ObjectClosedError – If called on a closed object.

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

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

The number of tables in the database.