mapteksdk.project package

Module contents

Core class for setting up a connection to an instance of an MDF application to start operations and initialise internal dependencies. Provides methods for interacting with user facing objects and data within the applications.

class mapteksdk.project.Project(options=None, existing_mcpd=None)

Bases: object

Main class to connect to an instance of an MDF application. Project() establishes the communication protocol and provides base functionality into the dataengine, such as object naming, locating, copying and deleting.

Parameters

  • options (ProjectOptions) – Optional specification of project, dataengine and mcp connection settings. Used for unit testing to start a new database and processes without an MDF host application already running.

  • existing_mcpd (ExistingMcpdInstance or McpdConnection or None) –

    If None (default) then the latest relevant application that was launched will be connected to. This is equivalent to passing in Project.find_running_applications()[0].

    Otherwise it may be ExistingMcpdInstance which refers to the host application to connect to otherwise a McpdConnection which is an existing connection to a host application (its mcpd).

Raises

ProjectConnectionFailureError – If the script fails to connect to the project. Generally this is because there is no application running, or the specified application is no longer running.

unload_project()

Call the mcp class to unload a spawned mcp instance (i.e. when not using a host application like Eureka or PointStudio). Use this when finished operating on a project that has ProjectOptions that requested an mcpd_mode of CREATE_NEW.

Also unloads dataengine created with same methods.

Failure to call this un-loader may leave orphan mcpd.exe processes running on the machine.

property api_version

Returns the API version reported by the application.

Returns

The API version of the application in the form: (major, minor).

Return type

tuple

Notes

PointStudio 2020 / Eureka 2020 / Blastlogic 2020.1 have api_version (1, 1). PointStudio 2020.1 has api_version (1, 2). Earlier applications will have api_version (0, 0). It is not recommended to connect to applications with api versions less than (1, 1).

raise_if_version_below(version)

Raises an error if the script has connected to an application whose version is lower than the specified version.

This allows for scripts to exit early when attaching to an application which does not support the required data types.

Raises

ApplicationTooOldError – If the API version is lower than the specified version.

Examples

Exit if the application does not support GridSurface (api_version is less than (1, 2)).

>>> from mapteksdk.project import Project
>>> project = Project()
>>> project.raise_if_version_below((1, 2))

It is also possible to catch this error and add extra information.

>>> from mapteksdk.project import Project, ApplicationTooOldError
>>> project = Project()
>>> try:
...     project.raise_if_version_below((1, 2))
>>> except ApplicationTooOldError as error:
...     raise SystemExit("The attached application does not support "
...                      "irregular grids") from error
find_object(path)

Find the ObjectID of the object at the given path.

Parameters

path (str) – Path to the object.

Returns

  • ObjectID – The ID of the object at the given path.

  • None – If there was no object at path.

read(path_or_id)

Open an existing object in read-only mode. In read-only mode the values in the object can be read, but no changes can be saved. Use this function instead of edit() if you do not intend to make any changes to the object.

If this is called using a with statement, close() is called automatically at the end of the with block.

Parameters

path_or_id (str or ObjectID) – The path or the ID of the object to open.

Raises

  • ObjectDoesNotExistError – If path_or_id is not an existent object.

  • TypeError – If path_or_id is an unsupported object.

Examples

Read an object at path/to/object/to/read and then print out the point, edge and facet counts of the object.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> path = "path/to/object/to/read"
>>> with project.read(path) as read_object:
...     if hasattr(read_object, "point_count"):
...         print(f"{path} contains {read_object.point_count} points")
...     if hasattr(read_object, "edge_count"):
...         print(f"{path} contains {read_object.edge_count} edges")
...     if hasattr(read_object, "facet_count"):
...         print(f"{path} contains {read_object.facet_count} edges")
new(object_path, object_class: ObjectType, overwrite=False) → ObjectType

Create a new object and add it to the project. Note that changes made to the created object will not appear in the view until save() or close() is called.

If this is called using a with statement, save() and close() are called automatically at the end of the with block.

Parameters

  • object_path (string) – Full path for new object. e.g. “surfaces/generated/new surface 1” If None, the new object will not be assigned a path and will only be available through its object ID.

  • object_class (class) – The type of the object to create. (e.g. Surface).

  • overwrite (bool) – If overwrite=False (default) a ValueError is raised if there is already an object at new_name. If overwrite=True then any object at object_path is replaced by the new object. The overwritten object is orphaned rather than deleted and may still be accessible through its id.

Yields

DataObject – The newly created object. The type of this will be object_class.

Raises

  • ValueError – If an object already exists at new_path and overwrite = False.

  • ValueError – If object path is blank, ‘.’ or ‘/’.

Notes

If an exception is raised while creating the object the object will not be saved.

If you do not assign a path to an object on creation, project.add_object() can be used to assign a path to the object after creation.

Examples

Create a new surface and set it to be a square with side length of two and centred at the origin.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Surface
>>> project = Project()
>>> points = [[-1, -1, 0], [1, -1, 0], [-1, 1, 0], [1, 1, 0]]
>>> facets = [[0, 1, 2], [1, 2, 3]]
>>> with project.new("surfaces/square", Surface) as new_surface:
...   new_surface.points = points
...   new_surface.facets = facets
...   # new_surface.close is called implicitly here.
edit(path_or_id)

Open an existing object in read/write mode. Unlike read, this allows changes to be made to the object. Note that changes made will not appear in the view until save() or close() is called.

If this is called using a with statement, save() and close() are called automatically at the end of the with block.

Parameters

path_or_id (str or ObjectID) – Path or ID of the object to edit.

Yields

DataObject – The object at the specified path opened for editing.

Raises

  • ObjectDoesNotExistError – If the object to edit does not exist.

  • TypeError – If the object type is not supported.

Notes

If an exception is raised while editing an object, any changes made inside the with block are not saved.

Examples

Edit the surface created in the example for project.new to a hourglass shape instead of a square.

>>> from mapteksdk.project import Project
>>> points = [[-1, -1, 0], [1, -1, 0], [-1, 1, 0], [1, 1, 0], [0, 0, 0]]
>>> facets = [[0, 1, 4], [2, 3, 4]]
>>> project = Project()
>>> with project.edit("surfaces/square") as edit_surface:
...     edit_surface.points = points
...     edit_surface.facets = facets
...     # edit_surface.close is called implicitly here.
new_or_edit(path, object_class: ObjectType, overwrite=False) → ObjectType

This function works as project.new if the specified object does not exist. Otherwise it acts as project.edit.

Parameters

  • path (string) – Path to the object to create or edit.

  • object_class (type) – Class of the object to create or edit.

  • overwrite (bool) – If False (default) and there is already an object at path whose type is not editable as object_class a ValueError is raised. If True, any object at path which is not object_class is orphaned to make room for the new object.

Yields

DataObject – The newly created object or the object at the specified path.

Raises

  • ValueError – If overwrite=False and there exists an object at path whose type is not object class.

  • AttributeError – If path is not a string.

add_object(full_path, new_object, overwrite=False)

Adds a new DataObject to the project. Normally this is not necessary because Project.new() will add the object for you. This should only need to be called if Project.new() was called with path = None or after a call to a function from the mapteksdk.io module.

Parameters

  • full_path (str) – Full path to the new object (e.g. ‘/surfaces/new obj’).

  • new_object (DataObject or ObjectID) – Instance or ObjectID of the object to store at full_path.

  • overwrite (bool) – If overwrite=False (default) a ValueError will be raised if there is already an object at full_path. If overwrite=True and there is an object at full_path it will be overwritten and full_path will now point to the new object. The overwritten object becomes an orphan.

Returns

ID of newly stored object. This will be the object ID of new_object.

Return type

ObjectID

Raises

  • ValueError – If invalid object name (E.g. ‘/’, ‘’, or (starting with) ‘.’ when project options don’t allow hidden objects).

  • ValueError – If paths contains back slashes ().

  • ValueError – If overwrite=False and there is already an object at full_path.

Notes

Has no effect if new_object is already at full_path.

get_children(path_or_id='')

Return the children of the container at path as (name, id) pairs.

Parameters

path_or_id (str or ObjectID) – The path or object ID of the container to work with.

Returns

Provides a sequence that can be iterated over to provide the (name, id) for each child. It also provides name() and ids() functions for querying just the names and object IDs respectively.

Return type

ChildView

Raises

  • ObjectDoesNotExistError – If the path does not exist in the project.

  • TypeError – If the path is not a container.

  • ValueError – If the path is a container but not suitable for accessing its children.

get_descendants(path_or_id='')

Return all descendants of the container at path as (name, id) pairs.

Parameters

path_or_id (str or ObjectID) – The path or object ID of the container to work with.

Returns

Provides a sequence that can be iterated over to provide the (name, id) for each child. It also provides name() and ids() functions for querying just the names and object IDs respectively.

Return type

ChildView

Raises

  • KeyError – If the path does not exist in the project.

  • TypeError: – If the path is not a container.

  • ValueError: – If the path is a container but not suitable for accessing its children.

copy_object(object_to_clone, new_path, overwrite=False, allow_standard_containers=False)

Deep clone DataObject to a new object (and ObjectID).

If this is called on a container, it will also copy all of the container’s contents.

Parameters

  • object_to_clone (DataObject or ObjectID or str) – The object to clone or the ID for the object to clone or a str representing the path to the object.

  • new_path (str) – full path to place the copy (e.g. ‘surfaces/new/my copy’). Set as None for just a backend object copy.

  • overwrite (bool) – If False (default) a ValueError will be raised if there is already an object at new_name. If True and there is an object at new_path the object at new_path is overwritten. The overwritten object is orphaned instead of deleted and may still be accessible via its id.

  • allow_standard_containers (bool) – If False (default) then attempting to copy a standard container will create a visual container instead. If True (not recommended) copying a standard container will create a new standard container.

Returns

  • ObjectID – Id of new object (The clone).

  • None – If the operation failed.

Raises

ValueError – If an object already exists at new_path and overwrite = False.

rename_object(object_to_rename, new_name, overwrite=False, allow_standard_containers=False)

Rename (and/or move) an object.

Renaming an object to its own name has no effect.

Parameters

  • object_to_rename (DataObject or ObjectID or str) – The object to rename or the ID of the object to rename or full path to object in dataengine.

  • new_name (str) – new name for object. Standalone name (e.g. ‘new tri’) will keep root path. Full path (e.g. ‘surfaces/new tri’) will change location. Prefix with ‘/’ (e.g. ‘/new tri’ to move to the root container).

  • overwrite (bool) – If False (default) then if there is already an object at new_name then a ValueError is raised. If True and if there is already an object at new_name then the object at new_name is overwritten. The overwritten object is orphaned rather than deleted and may still be accessible via its ID.

  • allow_standard_containers (bool) – If False (default) then attempting to rename a standard container will create a new container and move everything in the standard container into the new container. If True (not recommended) standard containers can be renamed.

Returns

True if rename/move successful, False if failed (overwrite checks failed).

Return type

bool

Raises

  • ValueError – New object name begins with full stop when project attribute allow_hidden_objects is False (default).

  • ValueError – New object name can’t be ‘.’.

  • ValueError – If there is already an object at new_name and overwrite=False.

  • ObjectDoesNotExistError – Attempting to rename an object that doesn’t exist.

  • DeleteRootError – Attempting to rename root container.

Notes

new_name can not start with a full stop ‘.’ when allow_hidden_objects is False and cannot be ‘/’ or ‘’ or ‘.’.

delete_container_contents(container)

Deletes all the contents of a container.

Parameters

container (DataObject or ObjectID or str) – the object to delete or the ID for the object to delete or path to container (e.g. ‘/surfaces/old’).

new_visual_container(parent_container, container_name)

Creates a new visual container.

Parameters

  • parent_container (str) – Parent container name.

  • container_name (str) – New container name.

Returns

The object ID for newly created container.

Return type

ObjectID

Raises

  • ValueError – When attempting to create a container name or part of path that would result in hidden objects (i.e. starts with ‘.’) and allow_hidden_objects is False.

  • ValueError – If the container name contains “/” characters.

delete(mdf_object_or_name, allow_standard_containers=False)

Deletes the given object.

Parameters

  • mdf_object_or_name (string or DataObject or ObjectID) – Container name, instance of object as DataObject or ObjectID of the object.

  • allow_standard_containers (bool) – If False (default) then attempting to delete a standard container will result in the container contents being deleted. If True then standard containers will be deleted. See warnings for why you shouldn’t do this.

Returns

True if deleted successfully or False if not.

Return type

bool

Raises

  • DeleteRootError – If attempting to delete the root container.

  • RuntimeError – If there is an error while deleting the object.

Warning

Deleting a standard container created by a Maptek application may cause the application to crash. The allow_standard_containers flag should only be used to delete standard containers you have created yourself (It is not recommended to create your own standard containers).

get_selected()

Return the IDs of the selected objects.

When connected to an existing application, these are the objects selected in that application (via the explorer, view or some other method).

Returns

A list of selected ObjectIDs.

Return type

list

set_selected(object_ids_or_paths=None, include_descendants=True)

Set active project selection to one or more objects. If None specified, selection will be cleared. If objects are provided but are not valid, they will not be selected. No action will be taken if entire selection specified is invalid. Any VisualContainer objects specified will include their descendants.

Parameters

  • mdf_objects_or_paths (list, str, ObjectID, or None) – List of object paths to select, List of ObjectID to select, path to object to select, ObjectID of object to select. Pass None or an empty list to clear the existing selection.

  • include_descendants (bool) – whether to also select descendants of any VisualContainer provided within the selection criteria (default=True).

Raises

ValueError – If any or all objects within the selection specified is invalid.

is_recycled(mdf_object)

Check if an object is in the recycle bin.

Parameters

mdf_object (DataObject or ObjectID) – Object to check.

Returns

True if the object is in the recycle bin (deleted) and False if it is not.

Return type

bool

static find_running_applications()

Return a list of applications that are candidates to be connected to.

No checking is performed on the application to determine if it is suitable to connect to. For example, if the product is too old to support the SDK.

Once you select which application is suitable then pass the result as the existing_mcpd parameter of the Project class’s constructor.

The list is ordered based on the creation time of the mcpd process with the latest time appearing first in the list.

Returns

The list of candidate applications (host) that are running.

Return type

list of ExistingMcpdInstance

Examples

Finds the running applications and chooses the oldest one.

>>> from mapteksdk.project import Project
>>> applications = Project.find_running_applications()
>>> project = Project(existing_mcpd=applications[-1])