Markup: Annotate Models Directly in Your Browser

The latest C3D Web Vision release offers new annotation tools. Markup is a tool to add annotations or comments to 3D models. The user can add entities to highlight some model fragments. Application developers can use various options to control and render an additional layer of information on top of the 3D scene.

Markup is a graphic TypeScript object in API C3D Web Vision defined as:

export type C3DViewMarkup = {
    type: C3DViewObjectTypes.Markup
    uuid?: string

    content: string
    position: {
        plane: C3DViewPlacement
        view: {
            positionDist: number
            targetDist: number
            projection: CameraProjection
        }
    }

    userData: C3DUserData
}

Where the content field is a string in the svg format. The string defines each entity in the Markup object as an svg entity. For instance, a markup line segment is represented as an svg line, and vice versa. The Markup object can read and write this string.

The position field contains several parameters to position the entity within the scene.

Let us create a Markup object.

Type: EditMarkupProcess (TypeScript):

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

The user can add such 2D entities as a line, polyline, rectangle, ellipse, and circle. The added entities are stored in the Markup object which exists until the user deletes it.

An entity to be added is first made semi-transparent, not immediately added to the target Markup object. With this, you can safely interrupt the construction without cluttering the scene: the process removes any uncompleted entities. After each completed construction the process hides the semi-transparent entity and adds it to the Markup object.

All entities are placed in the plane parallel to the screen. For this, Markup suspends any camera operations (pan, zoom, etc.) The user cannot move the camera as long as the Markup process is active. The Markup object saves the camera properties on each run and then restores them for subsequent editing.

After the Markup process is stopped, the camera operations are available again.

Modes

The process supports two modes: entity creation and editing. In the creation mode, a new Markup object is created. In the editing mode, an existing object is modified. The object to be edited must exist in the scene.

The ’Editing’ Property

The ’Editing’ property launches the Markup process in the editing mode. Let us take a closer look the this property.

1. uuid is a required field to find the Markup object with the specified uuid and make it editable. If an object with the specified uuid is not found, the process types a console error message and quits.
2. cameraRestoringDuration is an optional field that specifies the period of animated camera movements as the camera properties are restored.

By default, if the ’Editing’ property is not specified, the entity creation process starts.

Additional Properties

They define the process parameters:

• type specifies the type of the entity to be constructed
• pen specifies the entity color and line width
• phantomPen specifies the appearance of semi-transparent (phantom) entities.

Markup (Typescript) process properties:

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

Entity types:

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

Events

The process has its events to notify the user about changes in the rendered scene.

Available events:

1. onExit(uuid) is invoked when the user stops the process, and returns uuid of the created Markup process.
2. 2. onCameraProjectionChanged(prj) is invoked if the process changes the camera projection plane as the camera properties are restored, and returns the new camera projection plane prj. This event is invoked only in the editing mode, and the restored projection plane differs from the current one.

Starting the Markup Process

To launch the process, run the RunProcessCommand command with the EditMarkup process name.

Example. EditMarkup (TypeScript) process launch:

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

For the Editing mode:

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

Process Updating

Updating changes the process parameters specified at its launch. A generic update command (TypeScript):

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

Example. A command to update entities in the assembly (TypeScript):

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

Red Pencil or Markup is not the only annotation command available. The C3D Web Vision toolkit also offers comments (AddCommentProcess) and measurement tools which we will cover in the next article.

We are going to add text fields and a balloon-shaped entity in future releases.