mapteksdk.labs.view module

Manipulation of views.

This module contains a view controller class with additional functionality which is still a work-in-progress. It is being provided through labs for earlier feedback.

To use the labs version of the ViewController, you can:

>>> from mapteksdk.project import Project
>>> from mapteksdk.labs.view import enable_labs_on_view_controller
>>> import mapteksdk.operations as operations
>>> project = Project()
>>> view = operations.open_new_view()
>>> enable_labs_on_view_controller(view)
>>> camera = view.camera()
>>> print(camera.origin, camera.artificial_scale)

class RigidTransform

Bases: InlineMessage

Represents a rigid body (6 degree of freedom) transformation in 3D space.

rotation: Tuple[Double, Double, Double, Double]

translation: Tuple[Double, Double, Double]

classmethod message_structure()

Read the structure of this message from the type hints.

Returns:: A dictionary where the key is the name of each property and the value is its type. For primitive types, the value will be str, bool or one of the types defined in primitives.py. For sequence types, this will be the List, Set or Tuple class defined in this class. Otherwise this will be the type read from the annotations.
Return type:: dict[str, Any]
Raises:: DataTypeNotSupported – If one of the data types in the type hints is not supported.

class Camera

Bases: Response

Response back for the Camera request.

origin: Tuple[Double, Double, Double]

artificial_scale: Tuple[Double, Double, Double]

rigid_transform: RigidTransform

angular_field_of_view: Double

linear_field_of_view: Double

perspective_factor: Double

classmethod message_structure()

Read the structure of this message from the type hints.

Returns:: A dictionary where the key is the name of each property and the value is its type. For primitive types, the value will be str, bool or one of the types defined in primitives.py. For sequence types, this will be the List, Set or Tuple class defined in this class. Otherwise this will be the type read from the annotations.
Return type:: dict[str, Any]
Raises:: DataTypeNotSupported – If one of the data types in the type hints is not supported.

classmethod repeating_field_type()

The type of values stored in the repeating field.

If None, this message does not have a repeating field.

property repeating_field_values: Sequence

The values of the repeating field.

Every value in the sequence must have the type defined by repeating_field_type otherwise a MalformedMessageError will be raised when the message is sent.

Raises:: TypeError – If this subclass has a repeating_field_type of None. This is the default repeating field type.

Examples

The property name “repeating_field_values” is rarely a good name for the repeating fields, so it is often best to define a new name for the property similar to below:

>>> class Group(SubMessage):
...   '''Message representing a group of people.'''
...   division: str
...
...   @classmethod
...   def repeating_field_type(cls):
...     return str
...
...   @property
...   def participants(self) -> typing.Sequence[str]:
...     '''The participants of the group.'''
...     return self.repeating_field_values
...
...   @participants.setter
...   def participants(self, value: typing.Sequence[str]):
...     self.repeating_field_values = value

class LabsViewController(view_id)

Bases: ViewController

Provides access onto a specified view, with additional work-in progress features.

Parameters:: view_id (ObjectID[DataObject]) –

camera(): Return the current camera (i.e position/orientation) for the view.

set_camera(new_camera, smoothly=True)

Change the current camera of the view.

Parameters:

new_camera (Camera) – The new camera to use for the view.
smoothly (bool) – Whether the camera should smoothly transition to the new state, or if it should change instantaneously.

change_camera(change_function, smoothly=True)

Change a part of the camera.

The part that is changed is based on what the change_function does. It is called with the current state of the camera and should make the appropriate modifications to it

Parameters:

change_function (callable) – A function that will be passed the current state of the camera and should modify it and return the modified version back.
smoothly (bool) – Whether the camera should smoothly transition to the new state, or if it should change instantaneously.

action_plane()

Return the action plane in this view.

Return type:: Plane

action_plane_section_mode()

Return the current selection mode of this view.

Return type:: SectionMode

action_plane_section_step_distance()

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

Return type:: float

action_plane_section_widths()

Return the widths of the section in this view.

Return type:: Tuple[float, float]

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.

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

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.

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.

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

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.

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.

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

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]) –

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.

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.

scene_extents()

Return the scene extents of this view.

Return type:: Extent

set_action_plane(plane)

Set the action plane in this view.

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

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)

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)

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.

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)

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.

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.

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.

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.

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 window_title: str

Return the window title.

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

enable_labs_on_view_controller(view_controller)

Enables the labs functionality on the given view controller.

Returns:

The provided view controller with labs functionality enabled.

Return type:

LabsViewController

Raises:

TypeError – If the labs functionality has already been enabled.
TypeError – If the object is not a view controller.