Requesting an Object Pick

The object_pick() function requests the user to select an object in the running application. When you click on an object, its ObjectID is returned to the Python script. This provides you an intuitive way to select an object. The following example shows how to query the path and type name for the picked object.

from mapteksdk.pointstudio.operations import object_pick, write_report
from mapteksdk.project import Project
 
project = Project()
 
oid = object_pick()
 
path = oid.path
type_name = oid.type_name
 
write_report("Object pick", f"The object at {path} is a {type_name}")

Object picks for specific types

The object_types parameter of object_pick() allows you to restrict an object pick to a specific type. For example, the following script restricts an object pick to only accept Surface objects:

from mapteksdk.project import Project
from mapteksdk.data import Surface, ObjectID, Topology
from mapteksdk.operations import (
        object_pick, primitive_pick, show_toast_notification,
        SelectablePrimitiveType, Primitive, PickFailedError)
import numpy as np

def pick_primitive_on_object(
        oid: ObjectID[Topology],
        primitive_type: SelectablePrimitiveType) -> Primitive:
    """Pick a primitive of the specified type on the specified type.

    Parameters
    ----------
    oid
        Object ID of the object the picked primitive should be part of.
    primitive_type
        Primitive type to pick.

    Returns
    -------
    Primitive
        The picked primitive.

    Raises
    ------
    PickFailedError
        If the user cancels the pick.

    Warnings
    --------
    If oid does not have any primitives of the given type, it will be
    impossible to satisfy the pick and this will loop until the user
    cancels the pick operation.
    """
    while True:
        primitive = primitive_pick(
                primitive_type,
                label=f"Pick a {primitive_type.name} on {oid.path}")
        if primitive.path != oid.path:
            show_toast_notification(
                "Invalid surface pick",
                f"The picked facet must be on {oid.path}"
            )
            continue
        return primitive

if __name__ == "__main__":
    with Project() as project:
        try:
            surface_id = object_pick(
                object_types=Surface, label="Pick a surface")
            while True:
            # Because the pick was restricted to a Surface, surface_id
            # must be the id of a Surface. This ensures
            # pick_primitive_on_object() won't enter an infinite loop.
            facet_primitive = pick_primitive_on_object(
                surface_id, SelectablePrimitiveType.FACET)
            with project.edit(surface_id) as surface:
                # A bitwise not will invert the colour. The slice ensures
                # the alpha component is not inverted, because that would
                # make a fully-visible facet invisible.
                np.bitwise_not(
                    surface.facet_colours[facet_primitive.index][:3],
                    out=surface.facet_colours[facet_primitive.index][:3])
        except PickFailedError:
            pass

The following animation represents this script using a simple cube as an example:

Note

Assigning object_types to a single type will restrict the pick to that type. For example, to restrict the pick to Surface objects:
```
surface_id = object_pick(
    object_types=Surface, label="Pick a surface")
```
Assigning object_types to a tuple of types will allow the pick to accept an object of any of the specified types. For example, to restrict the pick to a dense, subblocked or sparse block model:
```
block_id = object_pick(
    object_types=(
        DenseBlockModel, SubblockedBlockModel, SparseBlockModel),
        label="Pick a block model")
```

Customising the pick operation messages

The messages that appear in the application during the pick operations can be customised by the label, support_label and help_text parameters of the function. The example below demonstrates using those three parameters to customise the messages shown by an object pick operation.

from mapteksdk.pointstudio.operations import object_pick, write_report
from mapteksdk.project import Project

project = Project()

object = object_pick(label="This is the label",
support_label="This is the support label",
help_text="This is the help text")

If you run this script, before picking a point, you will see:

The support label text, which will appear at the top of the view in a yellow box.
The label text, which appears in the bottom left hand corner of the screen.
The help text, which will appear in a tooltip when the mouse hovers over the label.