mapteksdk.geologycore.database module

Drillhole database data types.

class DrillholeDatabase(object_id=None, lock_type=LockType.READ)

Bases: VisualContainer, TablesMixin

A container which contains Drillhole objects.

A DrillholeDatabase object is backed by a database. This database may be a Vulcan Isis database, a set of CSV files or an internal database.

New databases created through this interface are always backed by an internal database. Upon creation, the new database contains a single table (A collar table containing a northing field and an easting field) and no drillholes.

Raises

EmptyTableError – If any table in the database contains no fields.
DuplicateFieldTypeError – If any table contains multiple fields of a type which does not support duplicates.
MissingRequiredFieldsError – If any table does not contain all of its required fields.

Parameters

object_id (ObjectID | None) –
lock_type (LockType) –

Examples

Creating a new drillhole database containing a single drillhole. This is a simple example which only uses two tables (A collar table and a geology table).

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import StringColourMap
>>> from mapteksdk.geologycore import (
...   DrillholeDatabase, DrillholeTableType, DrillholeFieldType)
>>> with Project() as project:
...   # The colour map to use to colour the drillhole.
...   with project.new("drillholes/geology_rock_type", StringColourMap
...       ) as colour_map:
...     colour_map.legend = ["DIRT", "ROCK", "UNOBTAINIUM"]
...     colour_map.colours = [
...       [165, 42, 42, 255],
...       [100, 100, 100, 255],
...       [255, 215, 0, 255]
...     ]
...   with project.new("drillholes/new_database", DrillholeDatabase
...       ) as database:
...     # The newly created database automatically contains a collar table,
...     # so the creator does not need to create one.
...     # The collar table only initially contains a northing and an easting
...     # field. To be able to more accurately place the drillhole, add an
...     # elevation field.
...     collar_table = database.collar_table
...     collar_table.add_field(
...       "ELEVATION",
...       float,
...       "Elevation of the drillhole",
...       field_type=DrillholeFieldType.ELEVATION
...     )
...     database.add_table("GEOLOGY", DrillholeTableType.GEOLOGY)
...     geology_table = database.geology_table
...     # The newly created geology table automatically contains to depth
...     # and from depth fields so the creator does not need to create them.
...     geology_table.add_field(
...       "ROCK_TYPE",
...       str,
...       "The type of rock in the interval",
...       field_type=DrillholeFieldType.ROCK_TYPE)
...     # Add a new drillhole to the database.
...     drillhole_id= database.new_drillhole("D-1")
...   with project.edit(drillhole_id) as drillhole:
...     # Set the collar point.
...     drillhole.raw_collar = (-0.7, 1.6, -15.6)
...     # Populate the geology table.
...     geology_table = drillhole.geology_table
...     geology_table.add_rows(3)
...     geology_table.from_depth.values = [0, 12.3, 25.1]
...     geology_table.to_depth.values = [12.3, 25.1, 34.4]
...     geology_table.rock_type.values = [
...       "DIRT",
...       "ROCK",
...       "UNOBTAINIUM"]
...     drillhole.set_visualisation(geology_table.rock_type,
...                                 colour_map)

save(): Saves the object to the Project.

property id: ObjectID[DrillholeDatabase]

Object ID that uniquely references this object in the project.

Returns: The unique id of this object.
Return type: ObjectID

classmethod static_type()

Return the type of visual container as stored in a Project.

This can be used for determining if the type of an object is a visual container.

close()

Closes the object.

This should be called as soon as you are finished working with an object. To avoid needing to remember to call this function, open the object using a with block and project.read(), project.new() or project.edit(). Those functions automatically call this function at the end of the with block.

A closed object cannot be used for further reading or writing. The ID of a closed object may be queried and this can then be used to re-open the object.

new_drillhole(drillhole_id)

Create a new drillhole and add it to the database.

The drillhole should be opened using the ObjectID returned by this function. The drillhole is inserted into the drillhole database container with drillhole_id as its name.

Opening the new drillhole for reading or editing before closing the drillhole database will raise an OrphanDrillholeError.

Parameters

drillhole_id (str) – Unique id for the new drillhole.

Raises

ValueError – If there is already a drillhole with the specified ID or if the drillhole could not be created.
TypeError – If drillhole_id is not a str.
ReadOnlyError – If this object is open for read-only.

Return type

ObjectID[Drillhole]

Notes

If there is an object at the path where the drillhole will be inserted, that object will be silently orphaned and the path will now refer to the new drillhole.

add_table(table_name, table_type=DrillholeTableType.OTHER)

Add a new table to the database.

The newly created table will contain any fields required by the specified table type (For example, to and from depth fields for assay tables).

Parameters

table_name (str) – The name for the new table.
table_type (DrillholeTableType) – The type of the new table. This is DrillholeTableType.OTHER by default.

Raises

ValueError – If table_type is DrillholeTableType.UNKNOWN.
TypeError – If table_type is not part of the DrillholeTableType enum.
DuplicateTableTypeError – If attempting to add a second collar or survey table to a database.

Notes

When creating a table which supports TO_DEPTH or FROM_DEPTH fields, this function will automatically add both TO_DEPTH and FROM_DEPTH fields to the table. Though it is valid for a table to contain only a TO_DEPTH field or only a FROM_DEPTH field, it is not possible to create such a table through this function.

refresh_holes()

Forces the visualisation of the drillholes to be refreshed.

The refresh occurs when the database is saved. This should be called when an edit to the database design will change how existing drillholes are visualised, typically due to field types being changed.

Warning

This operation can be quite slow on databases with a large number of drillholes.

property assay_table: AssayTableInformation

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: CollarTableInformation

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

TableNotFoundError – If there is no collar table.
TooManyTablesError – If there are multiple collar tables in the database. This should not be possible.

property survey_table: SurveyTableInformation

Returns the survey table if it exists.

A database can only contain one survey table.

Raises

TableNotFoundError – If there is no survey table.
TooManyTablesError – If there are multiple survey tables in the database. This should not be possible.

property geology_table: GeologyTableInformation

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: DownholeTableInformation

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: QualityTableInformation

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[BaseTableInformation]

The tables representing the drillhole.

Returns: List of BaseDrillholeTable for the drillhole.
Return type: list

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

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.

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 lock_type: LockType

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

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

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 – The name of the object attribute for which the value should be set.
dtype – 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 – 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.
RuntimeError – If a different error occurs.

Warning

Object attributes are saved separately from the object itself - any changes made by this function (assuming it does not raise an error) will be saved even if save() is not called (for example, due to an error being raised by another function).

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.