mapteksdk.geologycore.operations module

Operations available in GeologyCore.

Operations exposes functionality from within an application that can be invoked from Python functions. These typically correspond to menu items that are available in the application, but their inputs can be populated from Python without requiring the user to fill them out.

topographic_triangulation(scans, trim_edges_to_maximum_length=None, output_option=TriangulationOutput.SINGLE_SURFACE, relimit_to_polygon=None, edge_constraints=None, destination='')

Create triangulations (surfaces) of a group of scans.

This works in the XY plane, that is, it triangulates straight down. This means that if there are areas of undercut walls, these will not be modelled accurately.

This option is typically used once scans have been registered and filtered.

Parameters:

scans (list) – The list of scan objects to triangulate.
trim_edges_to_maximum_length (float or None) – If not None, then long, incorrectly generated boundary triangles will be eliminated. A maximum length is specified, which prevents triangles greater than this being created. This option is only applicable to boundary triangles; large voids in the centre of the data will still be modelled.
output_option (TriangulationOutput) – If SINGLE_SURFACE, then this creates a single surface from the selected objects/scans. If SURFACE_PER_OBJECT, then this creates a single surface for each selected object/scan. If SPLIT_ALONG_EDGE_CONSTRAINTS, then splits the triangulation into separate objects based on any lines or polygons provided by edge_constraints.
relimit_to_polygon (ObjectID or None) – Constrains the model to a polygon, for example a pit boundary. The output_option must be RELIMIT_TO_POLYGON to use this.
edge_constraints (list or None) – The lines and polygons to use when splitting the triangulation into separate objects. The output_option must be SPLIT_ALONG_EDGE_CONSTRAINTS to use this.
destination (str) – An optional path to the container to store the resulting triangulations. The empty string will use a default path.

boundary_edges(selection, merge_boundaries=False)

Finds boundary edges for objects in the selection.

This creates either a single edge network or multiple polylines which represent the edges of the objects in the selection.

Parameters:

selection (list) – List of paths or object ids of the objects to find the boundary edges for.
merge_boundaries (bool) – If True, all boundary edges are combined into a single edge network. If False, each boundary edge is a polygon. They are coloured green for edges around the perimeter of the object and red if they are edges around holes in the object.

Returns:

Selection containing the created objects. If merge_boundaries is True, this will contain between zero and len(selection) objects. if merge_boundaries is False, this can contain any number of objects.

Return type:

WorkflowSelection

Raises:

TransactionFailed – If no object in selection is a Surface or Discontinuity.

Warning

This operation will enter an infinite loop if all objects in the selection are surfaces which do not contain boundary edges.

contour_surface(surfaces, lower_limit, upper_limit, major_contour_intervals=15.0, major_contour_colour=(0, 255, 255, 255), minor_contour_intervals=None, minor_contour_colour=(255, 0, 127, 255), destination_path=None)

Create contours from surfaces (triangulations), which are then saved into an edge network object.

Parameters:

surfaces (list) – The list of surfaces to contour.
lower_limit (float) – The minimum value of the contours (the lowest elevation).
upper_limit (float) – The maximum value of the contours (the highest elevation).
major_contour_intervals (float) – The difference in elevation between major contour lines.
major_contour_colour (sequence) – The colour of the major contour lines. This may be a RGB colour [red, green, blue] or a RGBA colour [red, green, blue, alpha].
minor_contour_intervals (float or None) – If None then no minor contours lines will be included. The difference in elevation between minor contour lines between the major contour lines.
minor_contour_colour (sequence) – The colour of the minor contour lines. This may be a RGB colour [red, green, blue] or a RGBA colour [red, green, blue, alpha]. This is only relevant if minor_contour_intervals is not None.
destination_path (str) – The path to where the contours should be written. If None then the default path will be used.

Returns:

The list of edge networks created that contain the resulting the contour lines if there are no minor contour lines. Otherwise a list of containers each containing the set of major and minor contour lines will be provided.

Return type:

list

Raises:

ValueError – If a colour cannot be converted to a valid RGBA colour.
ValueError – If lower_limit is greater than upper_limit. You may have simply passed the arguments in the wrong way around.

loop_surface_straight(selection, destination=None)

Create a Surface from a series of loops using “straight loop ordering”.

This creates a single Surface with the loops connected based on their orientation.

Parameters:

selection (list) – List of Surfaces or Polygons to use to generate the loop surface. Each must contain loops.
destination (str) – Path to place the destination object. If not specified, this will use the default destination of the menu item.

Returns:

Selection containing the created Surface.

Return type:

WorkflowSelection

loop_surface_iterative(selection, destination=None)

Creates Surfaces from a series of loops using “iterative loop ordering”.

This joins nearby loops with similar orientations. This can create multiple surfaces and may wrap around corners if needed.

Unlike loop_surface_straight, this may ignore loops if they are not sufficiently close to another loop.

Parameters:

selection (list) – List of Surfaces or Polygons to use to generate the loop surfaces. Each must contain loops.
destination (str) – Path to place the destination object. If not specified, this will use the default destination of the menu item.

Returns:

Selection containing the created Surface(s).

Return type:

WorkflowSelection

fix_surface(surfaces)

Automates the fixing of common issues with surfaces (triangulation).

The fixes it performs are: - Self intersections - Fixes cases where the surface intersects itself

Trifurcations - Fixes cases where the surface meets itself, creating a T-junction.
Facet normals - Orient facet normals to point in the same direction. This will be up for surfaces/topography and out for solids.
Vertical facets - Remove vertical facets and close the hole this produces by moving the points along the top down, adding points as necessary to neighbouring non-vertical facets to maintain a consistent surface.

Parameters:: surfaces (list) – The list of surfaces to fix.
Returns:: The same list of surfaces.
Return type:: list

General Operations

These operations can be imported from this module, however they are actually defined in mapteksdk.operations.

exception TooOldForOperation(minimum_version, current_version)

Bases: Exception

Error raised when the application is too old to support an operation.

Parameters:

minimum_version (tuple[int, int]) – Minimum version required to support the operation. This is of the form (major, minor).
current_version (tuple[int, int]) – Current version required to support the operation. This is of the form (major, minor).

Notes

This does not check that current_version is older than new_version.

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception PickFailedError(pick_type, reason='cancelled or failed')

Bases: ValueError

Error raised when a pick operation fails.

This is also raised when a pick operation is cancelled.

Parameters:

pick_type (SelectablePrimitiveType | str) – The SelectablePrimitiveType for the pick which failed, or a string representing the type of the pick operation.
reason (str) – The reason the pick operation failed. This is “cancelled or failed” by default.

Notes

This inherits from ValueError instead of OperationCancelledError because it predates OperationCancelledError. Scripts should always catch this error as a PickFailedError. It may be changed to inherit from OperationCancelledError in a future version of the SDK.

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

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

Bases: Enum

Enum representing the selectable primitive types.

Warning

Block selections are impossible in PointStudio even when block objects are loaded into the view.

POINT = 1

EDGE = 2

FACET = 3

CELL = 5

BLOCK = 6

class Primitive(oid, primitive_type, index)

Bases: object

Class which can uniquely identify a selected primitive.

Includes the object the primitive exists in, the type of the primitive and the index of that primitive in the object.

Parameters:

oid (ObjectID) – The object ID of the object which the primitive is a part of.
primitive_type (SelectablePrimitiveType) – The type of primitive selected.
index (int) – Index of the selected primitive in the object.

property oid: ObjectID: The Object ID of the object with the primitive.

property path: str: Path to the object containing the selected primitive.

property primitive_type: SelectablePrimitiveType: The type of primitive which was selected.

property index: int: The index of the selected primitive in the primitive array.

operations.open_new_view(wait=True)

Open a new view window in the current application.

This is only suitable for use by the Python SDK When connecting to an existing Maptek application.

Using the Python SDK to develop an application which creates an Maptek Viewer within it requires special handling to set-up that isn’t provided by this function.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Parameters:

objects (list[mapteksdk.data.objectid.ObjectID[mapteksdk.data.base.DataObject]] | None) – The list of objects to include in the new view.
wait (bool) – If True then the function waits until the view has been opened and is considered complete before returning and will return the ObjectID of the newly created view. Otherwise it won’t wait and it will return immediately with no result.

Returns:

ViewController – The view controller for the newly created view if wait is True.
None – If wait is False.

Raises:

TooOldForOperation – If the application does not have the necessary support for this operation.

Return type:

ViewController | None

operations.opened_views()

Return the list of opened views in the current application.

This does not include embedded views in panels.

This is only suitable for use by the Python SDK when connecting to an existing Maptek application.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Returns:: A list containing the ViewController for each of the opened views. If there are no opened views this list will be empty.
Return type:: list
Raises:: TooOldForOperation – If the application does not have the necessary support for this operation.

Example

Print out the list of active views.

>>> from mapteksdk.project import Project
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> print('Open views:')
>>> for view in operations.opened_views():
>>>     print(view.server_name, view.window_title)

operations.active_view()

Return the active view of the current application otherwise None if there is no active view

This is only suitable for use by the Python SDK when connecting to an existing Maptek application.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Returns:

ViewController – The view controller for the active view
None – If there was no active view.

Raises:

TooOldForOperation – If the application does not have the necessary support for this operation.

Return type:

ViewController | None

Example

Query the active view

>>> from mapteksdk.project import Project
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> view = operations.active_view()
>>> if view:
>>>    print(f"The active view is: {view}")
>>> else:
>>>     print("There is no active view.")

operations.active_view_or_new_view()

Return the active view of the current application or opens a new view if there is none.

This is only suitable for use by the Python SDK when connecting to an existing Maptek application.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Returns:

ViewController – The view controller for the active view or new view.
None – If it was unable to determine the active view or create a new view.

Raises:

TooOldForOperation – If the application does not have the necessary support for this operation.

Return type:

ViewController | None

Example

Query the active view or create a new view if there is no active view.

>>> from mapteksdk.project import Project
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> view = operations.active_view_or_new_view()

operations.coordinate_pick(*, support_label=None, help_text=None)

Requests for the user to select a coordinate in the software.

This will wait for the user to select a coordinate and then returns the point.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Parameters:

label (str | None) – The label to show for the coordinate pick. This is shown in the status bar to the left of the X, Y and Z coordinates of the selected point. Default is “Select a coordinate”. The default may be translated to the user’s selected language within the application.
support_label (str | None) – The support label to display in a yellow box at the top of the view. Default is “Select a coordinate”. The default may be translated to the user’s selected language within the application. If label is specified and this is not, this will default to label.
help_text (str | None) – Text to display when the mouse hovers over the status bar during the coordinate pick option. Default is: “Select a coordinate for the running Python Script”. The default may be translated to the user’s selected language within the application.

Returns:

A ndarray with shape (3,) representing the selected coordinate.

Return type:

ndarray

Raises:

TooOldForOperation – If the application does not have the necessary support for this operation.
PickFailedError – If the pick operation fails. This is also raised if the pick operation is cancelled and the API version is 1.7 or lower.
PickCancelledError – If the pick operation is cancelled and the API version is 1.8 or greater.

Notes

A coordinate pick allows the user to pick any coordinate and thus the coordinate may not be a part of any object. If the selected coordinate must be a coordinate on an object, use primitive pick instead.

Examples

Request for the user to select two points in the running application and then calculates the distance between those two points. The selected points and the distance is displayed in the report window. When picking the first point, the message in the bottom corner of the screen will be: “Pick the first point”. For the second point it will be: “Pick the second point”.

>>> import numpy as np
>>> from mapteksdk.operations import (coordinate_pick, write_report)
>>> from mapteksdk.project import Project
>>> project = Project()
>>> start = coordinate_pick(label="Pick the first point.")
>>> end = coordinate_pick(label="Pick the second point.")
>>> difference = start - end
>>> distance = np.linalg.norm(difference)
>>> write_report(f"Distance between points",
...              f"The distance between {start} and {end} is {distance}")

operations.object_pick(*, label='', support_label='', help_text='')

Requests for the user to select an object in the software.

This will wait for the user to select an object and then returns it.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Parameters:

object_type – DataObject subclass or a tuple of DataObject subclasses to restrict the object pick to. Only objects of the specified types will be accepted as valid picks by the operation.
label (str) – The label to show for the object pick. This is shown in the status bar. Default is “Select a object”. The default may be translated to the user’s selected language within the application.
support_label (str) – The support label to display in a yellow box at the top of the view. Default is “Select a object”. The default may be translated to the user’s selected language within the application. If label is specified and this is not, this will default to label.
help_text (str) – Text to display when the mouse hovers over the status bar during the object pick option. Default is: “Select a object for the running Python Script”. The default may be translated to the user’s selected language within the application.
object_types (type[ObjectT] | tuple[type[ObjectT], ...] | None) –

Returns:

Object ID of the selected object. This may be a null object id.

Return type:

ObjectID

Raises:

TooOldForOperation – If the application does not have the necessary support for this operation.
PickFailedError – If the pick operation is cancelled or fails.
TypeError – If object_types contains an object which is not a DataObject subclass.

Examples

Ask for the user to select an object in the running application. A report is added to the report window containing the type of the selected object.

>>> from mapteksdk.operations import object_pick, write_report
>>> from mapteksdk.project import Project
>>> project = Project()
>>> oid = object_pick(label="Query object type",
...                   support_label="Select an object to query its type")
>>> write_report("Query type", f"{oid.path} is a {oid.type_name}")

Specifying the object type allows for restricting the operation to specific types. For example, setting the object type to Surface will cause the pick to only accept surfaces, as shown in the following script:

>>> from mapteksdk.data import Surface
>>> from mapteksdk.operations import object_pick
>>> from mapteksdk.project import Project
>>> project = Project()
>>> oid = object_pick(object_types=Surface
...                   label="Pick a surface")
>>> with Project.edit(oid) as surface:
...   # The surface variable is guaranteed to be a Surface.
...   pass

Alternatively, a tuple of types can be passed to specify a group of types to restrict the pick to. For example, the following script restricts the pick to Polygon and Polyline:

>>> from mapteksdk.data import Polyline, Polygon
>>> from mapteksdk.operations import object_pick
>>> from mapteksdk.project import Project
>>> project = Project()
>>> oid = object_pick(object_types=(Polyline, Polygon)
...                   label="Pick a polyline or polygon")
>>> with Project.edit(oid) as line:
...   # The line variable is guaranteed to be a Polyline or Polygon.
...   pass

operations.primitive_pick(*, label=None, support_label=None, help_text=None, locate_on=None)

Requests for the user to select a primitive of the specified type in the software.

This will wait for the user to select a primitive and returns it.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Parameters:

primitive_type (SelectablePrimitiveType) – The type of Primitive the user will be asked to select.
label (str | None) – The label to show for the primitive pick. This is shown in the status bar. Default is “Select a primitive”. The default may be translated to the user’s selected language within the application.
support_label (str | None) – The support label to display in a yellow box at the top of the view. Default is “Select a primitive”. The default may be translated to the user’s selected language within the application. If label is specified and this is not, this will default to label.
help_text (str | None) – Text to display when the mouse hovers over the status bar during the primitive pick option. Default is: “Select a primitive for the running Python Script”. The default may be translated to the user’s selected language within the application.
locate_on (Iterable[ObjectID] | None) – An iterable of ObjectID to restrict the pick to. If specified, only the pick can only be populated by picking on an object in the iterable. This does not check if these objects have the required primitive (e.g. No error will be raised if locate_on only contains block models, but primitive_type is SelectablePrimitiveType.FACET).

Returns:

Object representing the selected primitive.

Return type:

Primitive

Raises:

TooOldForOperation – If the application does not have the necessary support for this operation.
PickFailedError – If the pick operation fails. This is also raised if the pick operation is cancelled and the API version is 1.7 or lower.
PickCancelledError – If the pick operation is cancelled and the API version is 1.8 or greater.

Examples

Request for the user to pick a point and then displays a report containing the coordinate of the selected point.

>>> from mapteksdk.operations import (primitive_pick,
...                                   SelectablePrimitiveType,
...                                   write_report)
>>> from mapteksdk.project import Project
>>> project = Project()
>>> primitive = primitive_pick(SelectablePrimitiveType.POINT)
>>> with project.read(primitive.path) as read_object:
... write_report("Selected point", str(read_object.points[primitive.index]))

Request for the user to pick an edge then displays a report containing the points the selected edge connects.

>>> from mapteksdk.operations import (primitive_pick,
...                                   SelectablePrimitiveType,
...                                   write_report)
>>> from mapteksdk.project import Project
>>> project = Project()
>>> primitive = primitive_pick(SelectablePrimitiveType.EDGE)
>>> with project.read(primitive.path) as read_object:
...     edge = read_object.edges[primitive.index]
...     start = read_object.points[edge[0]]
...     end = read_object.points[edge[1]]
...     write_report("Selected Edge", f"{start} to {end}")

operations.write_report(message)

Write a report to the report window of the application.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Parameters:

label (str) – The label to show on the report.
message (str) – The message to include in the report. This is essentially the body of the report itself.

Example

Write out a simple report

>>> from mapteksdk.project import Project
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> operations.write_report(
...     'My Script', 'Completed filtering in 1.5 seconds')