mapteksdk.operations module

General operations which work with multiple applications.

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.

exception PickCancelledError(pick_type)

Bases: PickFailedError

Error raised when a pick operation is cancelled.

When connected to an application with an API version lower than 1.8, the SDK cannot tell the difference between a pick failing and a pick being cancelled and a PickFailedError is raised in either case.

Parameters:

pick_type (SelectablePrimitiveType | str) – The SelectablePrimitiveType for the pick which was cancelled, or a string representing the type of the pick operation.

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 OperationCancelledError

Bases: Exception

Error raised when an operation is cancelled.

This indicates the user closed the panel associated with the operation or pressed “Cancel”.

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 OperationFailedError

Bases: Exception

Error raised when an operation fails.

This error typically shouldn’t be caught. It typically indicates the application is incompatible with the current 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 Severity(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enum of severity of messages.

INFORMATION = 0

The message is an information message.

The message will display with a blue circle with a white “i” icon. This severity indicates that though the message is important, but it is less severe than an error or a warning.

WARNING = 1

The message is a warning.

The message will be displayed with an orange exclamation mark icon. This severity indicates that the message is a warning - something potentially bad has happened or is about to happen, but not something bad enough that the script will stop.

ERROR = 2

The message is an error.

The message will display with a red cross icon and the Workbench will play a warning sound. This severity indicates that something bad has happened, or is about to happen, and the script cannot continue.

class Primitive(path, 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:

  • path (str) – The path to the object containing the primitive.

  • primitive_type (SelectablePrimitiveType) – The type of primitive selected.

  • index (int) – Index of the selected primitive in the object.

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.

open_new_view(objects: list[mapteksdk.data.objectid.ObjectID[mapteksdk.data.base.DataObject]] | None = None, wait: Literal[True] = True) → ViewController
open_new_view(objects: list[mapteksdk.data.objectid.ObjectID[mapteksdk.data.base.DataObject]] | None = None, wait: Literal[False] = False) → None

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 – The list of objects to include in the new view.

  • wait – 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.

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)
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.")
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()
coordinate_pick(*, label=None, 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}")
object_pick(*, object_types: None = None, label: str = '', support_label: str = '', help_text: str = '') → ObjectID[DataObject]
object_pick(*, object_types: type[ObjectT] | tuple[type[ObjectT], ...], label: str = '', support_label: str = '', help_text: str = '') → ObjectID[ObjectT]

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

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
primitive_pick(primitive_type=SelectablePrimitiveType.POINT, *, 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}")
write_report(label, 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')
show_message(title, message, severity=Severity.INFORMATION)

Display a popup message box in the application.

Note that message boxes can be disruptive to the user and should be used sparingly. Consider using write_report() or display_toast_notification() instead.

Supported by PointStudio 2021.1, Vulcan GeologyCore 2021 and higher.

Parameters:

  • title (str) – The title which will be displayed in the title bar of the message box. This should be no more than 255 characters long.

  • message (str) – The message which will be displayed in the main area of the message box.

  • severity (Severity) – The severity of the message. See the documentation on the enum for more information.

Raises:

ValueError – If title is longer than 255 characters.

show_toast_notification(title, message, severity=Severity.INFORMATION)

Display a toast notification in the application.

The toast notification will appear at the bottom of the application and fade away after a few seconds. This is useful for transient messages. If the message may need to be kept, use write_report() instead.

Parameters:

  • title (str) – The title which will be displayed at the top of the toast notification in bold text. This should be no more than 255 characters long.

  • message (str) – The message which will be displayed in the main area of the toast notification.

  • severity (Severity) – The severity of the message. See the documentation on the enum for more information.

Raises:

ValueError – If title is longer than 255 characters.

project_points_onto_surface(surface_points, facets, points_to_project, discard_unprojected_points=False)

Project points onto a Surface.

This projects points by moving the point the minimum possible distance in the z direction for the point to lie on the surface. Points which cannot be projected onto the surface this way will not have their z coordinate adjusted.

Parameters:

  • surface_points (PointArrayLike) – The points used to define the surface to project points onto. This can be populated with the points of a surface (i.e. Surface.points) or by providing the points directly.

  • facets (FacetArrayLike) – The facets used to define the surface to project points onto. This can be populated with the facets of a Surface (i.e. Surface.facets) or by providing the facets directly.

  • points_to_project (PointArrayLike) – Points to project onto the surface.

  • discard_unprojected_points (bool) – If True, any points which cannot be projected onto the surface are discarded from the output. If False (default), points which cannot be projected onto the surface will not have their z coordinate changed in the output and the corresponding element in the returned facet_indices array will be an invalid index into facets.

Returns:

  • projected_points – A copy of points_to_project with the z values adjusted to place the points onto the surface. If discard_projected_points if False, if a point could not be projected onto the surface, its z value will be unchanged. If discard_unprojected_points is True, this will not contain any points in points_to_project which could not be projected onto the surface.

  • facet_indices – An array which indicates which facet each point was projected onto. The point at projected_points[i] is projected onto the facet at facets[facet_indices[i]]. If discard_unprojected_points is False, if a point could not be projected onto the surface, then facet_indices will be an unspecified index greater than the length of facets (thus using it to index into facets will raise an IndexError). If discard_unprojected_points is True, if a point could not be projected onto the surface, it will be removed from the facet_indices array.

Raises:

  • ValueError – If surface_points or points_to_project contains a NaN.

  • ValueError – If surface_points, facets or points_to_project are empty.

  • TypeError – If surface_points, facets or points_to_project contain a value which cannot be converted to the correct type.

Return type:

tuple[npt.NDArray, npt.NDArray]

Notes

If a point could be projected onto multiple facets, this will choose the facet with the highest z coordinate (even if there are facets which are closer to the point’s current position).

request_string(label, *, title='Python', initial_value=None, choices=None)

Request a string.

By default, this creates a window in the connected application into which the user can type. When they press “OK” in the application, whatever value the user typed in is returned by this function.

If the choices parameter is specified, this instead creates a window in the connected application which contains a drop down box. When the user presses “OK” the selected item in the drop down box is returned.

Parameters:

  • label (str) – The label to display next to the text box.

  • title (str) – The title of the window. This is “Python” by default.

  • initial_value (str | None) – The initial value in the panel. If choices is not specified, this value will be in the text box when the panel is opened. If choices is specified, this must be one of the items in choices. This item will be selected in the drop down box when the panel opens. By default, this is the empty string or the first item in choices if it is specified.

  • choices (Iterable[str] | None) – Iterable of possible choices. If this is specified, the user is required to choose one of these choice values. They will be presented in a drop down box.

Returns:

The string the user entered into the text box or selected in the drop down box.

Return type:

str

Raises:
request_float(label, *, initial_value=0.0)

Request a float.

This creates a window in the connected application into which the user can type a number. When they press Okay, this function will return the number they typed in.

Parameters:

  • label (str) – The label to display next to the text box.

  • initial_value (float) – The initial value to place in the text box. This is 0.0 by default.

Returns:

The float the user typed into the text box.

Return type:

float

Raises:
request_integer(label, *, initial_value=0)

Request an integer.

This creates a window in the connected application into which the user can type an integer. When they press Okay, this function will return the number they typed in.

Unlike request_float(), this only allows the user to enter a whole number.

Parameters:

  • label (str) – The label to display next to the text box.

  • initial_value (int) – The initial value to place in the text box. This is 0 by default.

Returns:

The integer the user typed into the panel.

Return type:

int

Raises:
ask_question(question, *, title='Python')

Ask a yes/no question.

This creates a window with a “Yes” and a “No” button.

Parameters:

  • question (str) – The content of the question. This appears above the Yes/No buttons.

  • title (str) – The title of the window. This is “Python” by default.

Returns:

True if the user clicked “Yes”; False if they clicked “No”.

Return type:

bool

Raises:

OperationFailedError – If the operation failed to complete.

request_file(*, title=None, save=False, extensions=None, exclude_all_files_filter=False)

Creates an open file dialog in the connected application.

By default, this will be an open file dialog and it will return the path to a file which exists.

If the save parameter is set to True, this will instead be a save file dialog and it may return a path to a file which doesn’t exist. This does not open the file, though the return value can be used to open the file.

Parameters:

  • title (str | None) – Title to display in the open file dialog. If None, the operating system default will be used.

  • save (bool) – If False (default), the file dialog will be for opening a file and it will require that the file exists. If True, the file dialog will be for saving a file. In this case, the path returned by this function may not be to an existent file.

  • extensions (dict[str, Union[str, Sequence[str]]] | None) – Dictionary where the keys are the description and the values are file extensions or list of file extensions. The file extensions must not include the dot (i.e. “txt” instead of “.txt”). This requires Project.version to be (1, 9) or higher.

  • exclude_all_files_filter (bool) – If True, removes the all files filter, restricting the user to only selecting file types specified in extensions. Defaults to False. Has no effect if extensions is not specified.

Returns:

Path to the file the user picked.

Return type:

pathlib.Path

Raises:

  • OperationCancelledError – If the file request was cancelled by the user.

  • TooOldForOperations – If Project.version is < (1, 8) or If Project.version is < (1, 10) and the extensions argument is specified.

Warning

Even when save=False, the file path returned by this function may not exist (e.g. The file could be deleted between the user selecting it and this function returning it). The user also may not have privileges to open the file.

Examples

The simplest usage of this function is with no arguments. This allows for the selection of any file. For example: >> path = request_file()

To ensure that the selected file has a specific extension, use the extensions parameter. For example, to ensure that the user must select a pdf file:

>>> path = request_file(
...     extensions={
...         "Portable document format" : "pdf"
...     },
...     excludes_all_files_filter=True
>>> )

If there are multiple acceptable file extensions, the dictionary value passed to the extensions argument can be a list of file extensions. For example, to support files with both the “jpeg” and “jpg” extensions:

>>> path = request_file(
...     extensions={
...         "Joint Photographic experts group" : ["jpg", "jpeg"]
...     },
...     excludes_all_files_filter=True
>>> )

Adding multiple keys to the extensions dictionary allows for grouping the files into similar groups. For example, placing JPEG and PNG files in different groups:

>>> path = request_file(
...     extensions={
...         "Joint Photographic experts group" : ["jpg", "jpeg"],
...         "Portable Network Graphics" : "png"
...     },
...     excludes_all_files_filter=True
>>> )

The return value of this function is a pathlib Path object, which can be used to open the file and read its contents:

>>> path = request_file()
>>> with path.open() as file:
...     # The file can be read here.
...     pass

By default, this function selects a file to read. To instead select the file to save, set the save parameter to True.

>>> save_path = request_file(save=True)
>>> with save_path.open(mode="w") as save_file:
...     # Save the file here.
...     pass
request_directory(*, title=None)

Creates an open directory dialog in the connected application.

This does not read the contents of the directory. It only returns the path to the directory.

Parameters:

title (str | None) – The title to display at the top of the open directory dialog. This has no effect for applications with Project.version (1, 8) or lower.

Returns:

The path to the selected directory.

Return type:

pathlib.Path