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) –
See also
- drillholes
Help page for this class.
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.
- Raises
CannotSaveInReadOnlyModeError – If the object was open for read only (i.e not for editing). It not necessary to call this for a read only object as there will be no pending changes to save.
- property id: ObjectID[DrillholeDatabase]
Object ID that uniquely references this object in the project.
- Returns
The unique id of this object.
- Return type
- 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.
- property desurvey_method: DesurveyMethod
The desurvey method used to generate the visualisation of the drillhole.
The default desurvey method for a new database is DesurveyMethod.TANGENT.
Notes
Setting the desurvey method to DesurveyMethod.TANGENT_WITH_LENGTH will set the tangent length to 1.0.
Example
The following example demonstrates setting the desurvey method of the drillholes in a picked database to the tangent desurvey method. In particular, note that after setting the desurvey method on an existing drillhole database you must call refresh_drillholes() to update the visualisation of the existing drillholes to use the new desurvey method.
>>> from mapteksdk.project import Project >>> from mapteksdk.geologycore import DrillholeDatabase, DesurveyMethod >>> from mapteksdk.operations import object_pick >>> if __name__ == "__main__": ... with Project() as project: ... drillhole_id = object_pick( ... label="Pick a drillhole in the database to set to use the " ... "tangent desurvey method") ... database_id = drillhole_id.parent ... with project.edit(database_id) as database: ... database: DrillholeDatabase ... database.desurvey_method = DesurveyMethod.TANGENT ... # Refresh the visualisation of existing holes so that they know to ... # use the new desurvey method. ... database.refresh_holes()
- property tangent_length: float
The tangent length used for the tangent with length desurvey method.
If the desurvey method is not TANGENT_WITH_LENGTH, this will be NaN.
- 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
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[mapteksdk.geologycore.tables.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
- Raises
TableNotFoundError – If there is no table with the specified name.
Allow the SDK to list and create objects considered hidden.
The names of hidden objects start with a full stop (e.g. “.hidden”).
Warning
This should be configured prior to reading the children of the container.
Setting allow_hidden_objects to True and deleting hidden containers that you didn’t create may cause tools in the application to fail and can cause the application to crash.
- allow_standard_containers: bool = False
Allow the SDK to handle standard containers like any other containers.
This disables the handling of standard containers as they appear to users.
If False (default), standard containers cannot be added or removed. If True, standard containers are treated as normal containers.
Warning
This should be configured prior to modifying the children of the container.
Setting allow_standard_containers to True and deleting standard containers can cause the application to crash.
- append(child)
Append a child to the end of the container.
Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.
If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.
- Parameters
child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.
- Raises
ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).
ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).
ReadOnlyError – If the object was open for read only (i.e not for editing).
- 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.
- 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.
- clear()
Remove all children from the container.
Any child objects that are not in another container will be deleted.
It is fine to call this function if there are no children in the container. This does not clear any object attributes.
The post condition of this function will be len(self) == 0.
- Raises
ReadOnlyError – If the object was open for read only (i.e not for editing).
- 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 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()
Return the object ID for the given name in the container.
If there is no such child, the null object ID will be returned or default
- 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.
- ids()
Returns the object IDs of the children.
- Returns
List of ObjectIDs of the children.
- Return type
list
- insert(index, child)
Insert child before index in the container.
Any leading or trailing whitespace will be stripped, such whitespace is avoided as it is hard for users to tell two objects apart if the only difference in their name is whitespace.
- Parameters
index (int) – The position of where the child should be inserted.
child (tuple[str, mapteksdk.data.objectid.ObjectID]) – The name to give the object and the ID of the object.
- Raises
ValueError – If the name is None, the empty string or name contains a new line or slashes (forward and back).
ValueError – If there is another object in the container with the given name (after leading and trailing whitespace has been removed).
ReadOnlyError – If the object was open for read only (i.e not for editing).
- 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.
- items()
Return the (name, object ID) pair for each child.
- Returns
List of tuples in the form (name, object ID).
- Return type
list
- 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
- name_of_object(object_id)
Return the name of the given object in the container.
Only the name of the first occurrence of the object will be provided.
- Parameters
object_id (mapteksdk.data.objectid.ObjectID | mapteksdk.data.base.DataObject) – The ID of the object to find the name of.
- Returns
The name of the object in this container if found.
- Return type
str
- Raises
ValueError – If there is no child with the given object ID in the container. This will be raised if the object is hidden and allow_hidden_objects is False (default) as it will be as if the object ID didn’t appear.
- names()
Returns the names of the children.
- Returns
List of names of children.
- Return type
list
- remove(name)
Remove the child with the given name or object ID from the container.
The name itself won’t be validated to reject names that aren’t possible for a child.
- Returns
The ID of the removed object.
- Return type
- Raises
ReadOnlyError – If the object was open for read only (i.e not for editing).
KeyError – If there is no child with the given name in the container.
ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).
ValueError – If the given name is a standard container allow_standard_containers is False (default).
- Parameters
name (str) –
- remove_object(object_to_remove)
Remove the first child with object ID from the container.
Only the first occurrence of the object will be removed.
- Raises
ReadOnlyError – If the object was open for read only (i.e not for editing).
ValueError – If there is no child with the given object ID in the container.
ValueError – If the given object is considered hidden and allow_hidden_objects is False (default).
ValueError – If the given object is a standard container allow_standard_containers is False (default).
- Parameters
object_to_remove (mapteksdk.data.objectid.ObjectID | mapteksdk.data.base.DataObject) –
- rename(old_name, new_name)
Rename an object within this container.
Renaming an object to its own name has no effect.
Renaming a standard container will create a container with the new name and move the children into the new container unless allow_standard_containers is True. This matches the behaviour of if a user renames the container from the explorer.
Care should be taken when renaming standard containers when allow_standard_containers is True. Avoid renaming standard containers that you did not create (i.e avoid renaming standard containers that are created by the applications themselves).
Warning
If a standard container is renamed when allow_standard_containers is False then you must ensure the changes are saved (no error is raised before it is saved). Failing to do so will result in the objects in the standard container being lost.
- Parameters
old_name (str) – The current name of the object to rename. This is not the path to the object, only its name. For example, to rename the pointset at the path “cad/pointset”, the old name of the object would be “pointset”.
new_name (str) – The new name for the object.
- Raises
KeyError – If there is no child by old_name (the key) in the container.
ValueError – If the new_name is not a valid name to change to.
ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).
ReadOnlyError – If the object was open for read only (i.e not for editing).
- replace(name, new_object)
Replace the object with the given name with a different object.
This is similar to removing the object with the given name and then inserting the new object at its old position/index.
This can be used for overwriting an existing object in a container with another.
If the object referred to by the given ObjectID is deleted, the child will not be added to the container on save.
- Parameters
name (str) – The name of the object in the container to replace. This is not the path to the object, only its name. For example, to replace the pointset at the path “cad/pointset”, the name of the object to replace is “pointset”, where as “cad” is the name of the container.
new_object (mapteksdk.data.objectid.ObjectID | mapteksdk.data.base.DataObject) – The object to replace with.
- Returns
The ID of the object that was replaced.
- Return type
- Raises
KeyError – If there is no child called name (the key) in the container.
ValueError – If new_object is not a valid object (it is null).
ValueError – If the given name is for a hidden object and allow_hidden_objects is False (default).
ValueError – If the given object is a standard container and allow_standard_containers is False (default).
ReadOnlyError – If the object was open for read only (i.e not for editing).
- 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]] | 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.
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.