Markup Process

The markup allows the user communicate different information about updates, changes or something critical. Its toolset offers various options for users to manage and display an extra layer of information on top of the visual 3D scene.

Below we will consider the markup process.

EditMarkupProcess type (TypeScript):

export type EditMarkupProcess = {
    name: "EditMarkup",
    editing?: {
        uuid: string,
        cameraRestoringDuration?: number
    }
    options: MarkupOptions
    events: {
        onExit?: (uuid: string) => void
        onCameraProjectionChanged?: (prj: CameraProjection) => void
        onCameraRestored?: (uuid: string) => void
    }
}

The process allows a user to build (draw) any 2D primitive specified in the list.

Built (drawn) primitives are stored in a markup object which keeps existing till a user removes it from the scene. When being built, any primitive is drawn as a phantom and not added instantly to a finite markup object. It allows safely interrupting building of any primitive, and it will no longer exist anymore in the scene as the process clears a phantom object. After every successful building of a primitive, the process clears a phantom and adds a built primitive to a markup object.

Primitives in a markup object are always drawn on the plane parallel to the plane of the screen. For this purpose the process disables all the camera processes (pan, zoom, etc.), so a user cannot somehow change its parameters (e.g. position) while the process is active. This leads to the fact that a markup object strongly depends on the camera parameters. Therefore the process stores them in a markup object every time it (process) is run in creating mode and uses them to restore the camera every time it’s run in editing mode.

After the process is stopped, all the camera processes are restored and a user is responsible for further displaying a markup object.

Modes

The process can operate in two modes: creating and editing. The creating mode determines that the process creates a new markup object. The editing mode determines that the process edits an existing markup object. Obviously, the process in such a mode can be run successfully only if a specified object exists in the scene.

Property ‘Editing’

The property editing allows to run the markup process in the editing mode. Let’s consider the options of this property.

  1. uuid is a required field needed to search for a markup object with the specified uuid and prepare it for editing. If no object with the uuid found, the process shows an error message on a console and stops operating.

  2. cameraRestoringDuration is an optional field needed to set the duration of animation of restoring the camera parameters.

By default, i.e. if the editing property is not passed, the process is run in the creating mode.

Additional Options

Markup Options type (Typescript):

export type MarkupOptions = {
    type?: MarkupType
    pen?: {
        color?: C3DViewRGB
        width?: number
    }
    phantomPen?: {
        color?: C3DViewRGB
        width?: number
    }
}

The options allows to set up options of the process:

  • type specifies the type of starting primitive to be built;

  • pen allows to set up the appearance of finite markup object primitives (color and width of lines);

  • phantomPen allows to set up the appearance of phantom object primitives.

Let’s consider the options:

Name

Description

type

The list of available primitives. The default is ["None"]

pen.color

The color of the markup pen. The default is {r: 0, g: 0, b: 0}

pen.width

The width of the markup pen. The default is 1

phantomPen.color

The color of the phantom pen. The default is {r: 0, g: 0, b: 0}

phantomPen.width

The width of the phantom pen. The default is 1

Markup Type

export enum MarkupType {
    LineSegment = 'lineSegment',
    Polyline = 'polyline',
    Rectangle = 'rect',
    Ellipse = 'ellipse',
    Circle = 'circle',
    Eraser = 'eraser',
    None = 'none'
}

Events

Available events.

  1. onExit(uuid) is called when a user stops the process and returns the uuid of a created markup object.

  2. onCameraProjectionChanged(prj) is called if the process changes the projection of camera when restoring its parameters and returns a “new” camera projection prj. This event is called only when the process is run in editing mode and a restored projection actually differs from the current one.

  3. onCameraRestored(uuid) is called right after the process restores the camera parameters. This event is called only when the process is run in editing mode.

Running the Process

To run the process, you should call the command RunProcessCommand with the EditMarkup name of the process:

Example of running the EditMarkup process (TypeScript):

view.runCommand({
    name: "RunProcessCommand",
    process: {
        name: "EditMarkup",
        options: {
            type: MarkupType.LineSegment
        },
        events: {}
    }
})

or the same in editing mode:

view.runCommand({
    name: "RunProcessCommand",
    process: {
        name: "EditMarkup",
        editing: {
            uuid: "..."
        },
        options: {
            type: MarkupType.LineSegment
        },
        events: {}
    }
})

Updating the Process

Updating allows to change the options which are set when the process is run.

Common type of the updating command (TypeScript):

type UpdateProcess = {
    name: "UpdateProcessCommand"
    options: { name: "EditMarkup" } & MarkupOptions
}

Example of a command to update markup primitive to be built (TypeScript):

view.runCommand({
    name: "UpdateProcessCommand",
    options: {
        name: "EditMarkup",
        type: MarkupType.LineSegment
    }
})