mapteksdk.view.view module

Interaction with a view in an applicable Maptek application.

The first step is opening a new view which returns a view controller for the new view. From there you can control the view by adding/removing objects, hiding/showing objects and querying what objects are in the view.

>>> from mapteksdk.project import Project
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> view = operations.open_new_view()
>>> view.add_objects([project.find_object('/cad')])
>>> view.close()
>>> project.unload_project()

class ViewController(view_id, *, viewer=None, manager=None)

Bases: object

Provides access onto a specified view.

This allows for objects to be added/removed/shown and hidden.

Parameters:

view_id (ObjectID[DataObject])
viewer (ViewerApi | None)
manager (CommunicationsManager | None)

property window_title: str

Return the window title.

This is the name of the view window as seen in the application.

close()

Close the view.

Avoid closing views that you didn’t open, as such avoid closing the view if it came from a non-empty active view. This is because you may close a view that was being used by another tool in the application.

A case where closing the view is a good idea is if the script creates one and is interactive and long-running. Think about when the script is done if the person running the script would miss seeing what is in the view, would find it a hassle to have to close it themself or if the content is no longer relevant after the script has exited.

Examples

Opens a new view then closes it.

>>> from mapteksdk.project import Project
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> view = operations.open_new_view()
>>> input('Press enter to finish')
>>> view.close()
>>> project.unload_project()

scene_extents()

Return the scene extents of this view.

Return type:: Extent

objects_in_view(object_filter=ObjectFilter.DEFAULT)

Return a list of objects that are in the the view.

Parameters:: object_filter (ObjectFilter) – A filter that limits what objects are returned.
Returns:: A list of object IDs of objects that are in the view that meet the filter criteria.
Return type:: list

add_objects(objects)

Adds the provided objects to the view.

Parameters:: objects (Iterable[ObjectID | DataObject | str]) – A list of IDs of objects to add to the view.

add_object(object_to_add)

Add a single object to the view.

Parameters:: object_to_add (ObjectID | DataObject | str) – The object to add, the ObjectID of the object to add, or a path string for the object to add.

remove_objects(objects)

Removes the provided objects from the view if present.

Removing objects not in the view will do nothing.

Parameters:: objects (Iterable[ObjectID | DataObject | str]) – A list of IDs of objects to remove from the view.

remove_object(object_to_remove)

Remove a single object from the view.

Parameters:: object_to_remove (ObjectID | DataObject | str) – The object to remove, the ObjectID of the object to remove, or a path string for the object to remove.

hide_objects(objects)

Hide the provided objects in the view.

Hiding objects not in the view will do nothing.

Parameters:: objects (Iterable[ObjectID | DataObject | str]) – A list of IDs of objects to hide.

hide_object(object_to_hide)

Hide a single object in the view.

Parameters:: object_to_hide (ObjectID | DataObject | str) – The object to hide, the ObjectID of the object to hide, or a path string for the object to hide.

show_objects(objects)

Show the provided objects in the view (if hidden).

If the objects are not in the view then they won’t be shown.

Parameters:: objects (Iterable[ObjectID | DataObject | str]) – A list of IDs of objects to hide.

show_object(object_to_show)

Show a single hidden object in the view.

Parameters:: object_to_show (ObjectID | DataObject | str) – The object to show, the ObjectID of the object to show, or a path string for the object to show.

add_transient_object(object_to_add, settings=TransientGeometrySettings(is_clippable=True, is_pickable=False, is_selectable=False))

Add a single object to the view as a transient object.

Transient objects by default are not pickable or selectable. They are typically used to show a preview of some operation.

You are responsible for removing the object from the view when you are done with it (or if you opened the view then close the view). The object should not be left in the view after you are done with it as this will leave the user with only the option of closing the view to get rid of it themselves. If you promote the transient object then it doesn’t need to be removed.

Parameters:

object_to_add (ObjectID | DataObject | str) – The object to add, the ObjectID of the object to add, or a path string for the object to add.
settings (TransientGeometrySettings) – The transient geometry settings that apply to the object_to_add.

See also

remove_object: To remove the object from the view.
promote_transient_object: To promote the transient object.

add_transient_objects(objects, settings=TransientGeometrySettings(is_clippable=True, is_pickable=False, is_selectable=False))

Adds the provided objects to the view as transient objects.

Transient objects by default are not pickable or selectable. They are typically used to show a preview of some operation.

You are responsible for removing the object from the view when you are done with it (or if you opened the view then close the view). The object should not be left in the view after you are done with it as this will leave the user with only the option of closing the view to get rid of it themselves. If you promote the transient object then it doesn’t need to be removed.

Parameters:

objects (Iterable[ObjectID | DataObject | str]) – A list of IDs of objects to add to the view.
settings (TransientGeometrySettings) – The transient geometry settings that apply to objects.

See also

remove_objects: To remove the object from the view.
promote_transient_objects: To promote transient objects.

promote_transient_object(data_object)

Promote a transient object to being a permanent object.

This is relevant to the view only, to ensure the geometry persists it should be added to the project.

Parameters:: data_object (ObjectID | DataObject | str)

promote_transient_objects(objects)

Promote transient objects to being permanent objects.

This is relevant to the view only, to ensure the objects persists they should be added to the project.

Parameters:: objects (Iterable[ObjectID | DataObject | str])

transient_objects_in_view()

Return the transient objects that are in the the view and their settings.

Returns:: A list of each transient object and their corresponding settings.
Return type:: list

property axes_visibility

The visibility of the axes in the view.

Examples

Querying the visibility of the axes in the view. >>> from mapteksdk.project import Project >>> from mapteksdk.operations import active_view >>> project = Project() >>> view = active_view() >>> view.axes_visibility True >>> project.unload_project()

Turn on axes in the current view.

>>> from mapteksdk.project import Project
>>> from mapteksdk.operations import active_view
>>> project = Project()
>>> view = active_view()
>>> view.axes_visibility = True
>>> project.unload_project()

Turn off axes in the current view.

>>> from mapteksdk.project import Project
>>> from mapteksdk.operations import active_view
>>> project = Project()
>>> view = active_view()
>>> view.axes_visibility = False
>>> project.unload_project()

action_plane_section_widths()

Return the widths of the section in this view.

Return type:: tuple[float, float]

set_action_plane_section_widths(back_width, front_width)

Change the section width of the view.

This will only take affect if view’s section mode is not SectionMode.NO_MODE.

It is typical for the same width to be given for both the front and back.

Parameters:

back_width (float) – The width of the section from the action plane to the back.
front_width (float) – The width of the section from the action plane to the front.

See also

action_plane_section_mode: Query the current section mode
set_action_plane_section_mode: Set the current section modes (enable sectioning)

action_plane_section_mode()

Return the current section mode of this view.

Return type:: SectionMode

set_action_plane_section_mode(section_mode)

Change the view’s section mode to the mode given.

Parameters:: section_mode (SectionMode) – The section mode to change to.

Examples

Turn on sectioning in the current view.

>>> from mapteksdk.project import Project
>>> from mapteksdk.operations import active_view
>>> from mapteksdk.view import SectionMode
>>> project = Project()
>>> view = active_view()
>>> view.set_action_plane_section_mode(SectionMode.STRIP)
>>> project.unload_project()

Turn off sectioning in the current view.

>>> from mapteksdk.project import Project
>>> from mapteksdk.operations import active_view
>>> from mapteksdk.view import SectionMode
>>> project = Project()
>>> view = active_view()
>>> view.set_action_plane_section_mode(SectionMode.NO_MODE)
>>> project.unload_project()

action_plane()

Return the action plane in this view.

Return type:: Plane

set_action_plane(plane)

Set the action plane in this view.

Parameters:: plane (Plane) – The plane to use for the action plane.

action_plane_section_step_distance()

The distance that the action plane will move if it is stepped by.

Return type:: float

set_action_plane_section_step_distance(step_distance)

Change the section step distance of the view.

Parameters:: step_distance (float) – The distance to step forward/back with the section.

See also

step_action_plane_section_forwards: Step forwards by the last distance.
step_action_plane_section_backwards: Step backwards by the last distance.

step_action_plane_section_forwards()

Step (moves) the action plane forwards.

The distance the plane will move is based on the last set step distance for the view.

See also

set_action_plane_section_step_distance: Set the step distance.
step_action_plane_section_backwards: Step in the other direction.

step_action_plane_section_backwards()

Step (moves) the action plane backwards.

The distance the plane will move is based on the last set step distance for the view.

See also

set_action_plane_section_step_distance: Set the step distance.
step_action_plane_section_forwards: Step in the other direction.

view_objects_by_extents(extent, look_direction, up_direction)

Change the camera such that it views all data in extent.

Use this to move the camera to view a specific object (or objects), based on its (or their) extents.

The camera will be looking at the centre of the extent from a point sufficiently far from the centre such that the entire extent will be visible in perspective projection, and a sufficiently large linear field of view to see the entire extent when in orthographic projection.

The specified look_direction and up_direction will be taken into account.

Parameters:

extent (Extent | None) – The extent of the objects that the view should focus on. If None, the view extent will be used.
look_direction (Sequence[float]) – The look direction is in the direction the camera should be looking and is from the camera towards to point of interest and should be towards the extent.
up_direction (Sequence[float]) – The up direction is a vector that points up relative to the camera, typically towards the sky and affects the camera’s tilt and roll.

use_predefined_view(view_direction, extent=None)

View the objects in the view from view_direction.

Parameters:

view_direction (PredefinedView) – The predefined view direction to use for the view.
extent (Extent | None) – The extent to view from the view direction. If None (default), then all objects currently in the view will be used to determine the extent.

look_at_point(point_to_look_at, camera_point)

Move the camera to camera_point and face it towards point_to_look_at.

This will implicitly change the view manipulation mode to ManipulationMode.LOOK_FROM if possible.

Parameters:

point_to_look_at (tuple[float, float, float]) – The point of interest for the camera to look at.
camera_point (tuple[float, float, float]) – The point to place the camera at.

Raises:

ValueError – If any ordinate in point_to_look_at or camera_point is not finite. If point_to_look_at and camera_point are the same point.

property background_colour: tuple[int, int, int, int]

The background colour of the view window.

This is represented as a tuple containing red, green, blue, alpha values of the colour. Each value is an integer in the range [0, 255].

When changing the background colour, the alpha is optional and the colour may be given as either a tuple, list or ndarray.

rotate_camera(angle, axis, centre=None)

Rotate the camera angle degrees around centre by axis.

Parameters:

angle (float) – The angle in radians to rotate the camera by.
axis (tuple[float, float, float] | Axis) – The axis to rotate around. This is of the form (x, y, z) and does not need to be normalised. Axis.X is equivalent to (1, 0, 0). Axis.Y is equivalent to (0, 1, 0). Axis.Z is equivalent to (0, 0, 1).
centre (tuple[float, float, float] | None) – The centre of rotation in the form (x, y, z). If None, the current centre of rotation of the view will be used.

translate_camera(vector)

Translate the camera by vector.

Parameters:: vector (tuple[float, float, float])

get_manipulation_mode()

Get the manipulation mode of the view.

This will return ManipulationMode.UNKNOWN if the view is non-standard (e.g. A stereonet view).

Return type:: ManipulationMode

set_manipulation_mode(mode)

Set the manipulation mode of the view.

This will be ignored if the current view does not support setting the manipulation mode.

Parameters:: mode (ManipulationMode)

class ViewWindow(*, width, height)

Bases: ViewWindowBase

A view window that this process created and owns.

This can be used as a context manager and used in a with statement. It is recommended to use it in a with statement to ensure the view window is closed when it’s not longer required.

Parameters:

width (int) – The width (horizontal length) of the viewer in pixels.
height (int) – The height (vertical length) of the viewer in pixels.

Example

Create a view with a triangle and save it to an image.

>>> from mapteksdk.project import Project
>>> from mapteksdk.data import Surface
>>> from mapteksdk.view import ViewWindow
>>> project = Project()
>>> with project.new("/surface/triangle", Surface) as surface:
...     surface.points = [(0.0, 0.0, 0.0), (5.0, 0.0, 0.0), (5.0, 5.0, 0.0)]
...     surface.facets = [(0, 1, 2)]
>>> with ViewWindow(width=1024, height=1024) as view:
...     view.controller.add_object(surface.id)
...     view.save_to_image("triangle.png")
>>> project.unload_project()

property view_id: ObjectID: The ID of the view object.

property controller: ViewController: Provides access to control this view.

save_to_image(path, overwrite=OverwriteMode.ERROR)

Save this view to an image file.

Objects should be added to the view before saving it to an image.

The view window should ideally only be used for saving images and not be shown directly to the user or allow user interaction.

Parameters:

path (PathLike | str) – The path to where the image should be saved. This ideally should have a PNG extension.
overwrite (OverwriteMode) – How to handle writing an image to a path that already exists.

Returns:

The path of the resulting image.

Return type:

pathlib.Path

Raises:

NotADirectoryError – If the directory the image should be saved in does not exist or is not a directory.
FileExistsError – If overwrite is OverwriteMode.ERROR and path already exists.
OSError – If overwrite is OverwriteMode.OVERWRITE and path can’t be deleted.