Adding Linear Dimension Process

The process is an interactive one which allows adding a new 3D linear dimension to a model by selecting two points.

Common type of the process (TypeScript):

export type AddLinearDimensionProcess = {
    name: "AddLinearDimension"
    surfaceInterpretation?: boolean
    snap?: SnapOptions
    direction?: C3DViewPoint
    options: C3DViewDimensionOptions
    events:{
        onNew?: () => string
        onCreate?:(uuid: string) => C3DUserData
        onStartPoint?: (p: C3DViewPoint) => C3DViewPoint | void
        onUpdatePoint?: (p: C3DViewPoint) => C3DViewPoint | void
        onEndPoint?: (p: C3DViewPoint) => C3DViewPoint | void
        onValue?:(value: number, p1: C3DViewPoint, p2: C3DViewPoint) => string
    }
}

The option snap allows to move the points indicated by the user’s mouse cursor to the nearest vertices of the triangle. More details in the section Snap option. This option is disabled by default.

The option direction allows to set along and parallel to which direction the dimension grows. The value of this property is coordinates of ordinary point, so you can specify the direction to grow along one, two or even three of the main axes (X, Y, Z). To specify if there is a direction along the corresponding axis, we recommend to use the numbers of 1 (direction is set) and 0 (no direction is set).

Surface mode

The mode is available if the surfaceInterpretation property is set to true. The dimensions are constructed by 2 points specified by a user in this mode. Every point detects a geometry placement surface on which a point is placed. If placements are parallel to each other, then a new linear dimension is added, otherwise the adding is canceled.

Options

The process uses the same options as the corresponding PMI object does. They are described here.

Callbacks

Available events.

onNew() is emitted before creating a new dimension. Returns a string which is used as a dimension label text instead of the default value.
onCreate(uuid) is emitted after creating a new dimension. It receives a UUID of a new object and allows to set custom dimension properties by returning them as an object.
onValue(value) is emitted when calculating a length between two selected points. It receives a calculated value and returns a string of a dimension label text.
onStartPoint(pnt) is emitted when a user specifies the first point of dimension by clicking on a geometry.
onUpdatePoint(pnt) is emitted when a user hovers the cursor over a geometry. Can be called only if the first point is already specified.
onEndPoint(pnt) is emitted when a user specifies the second point of dimension by clicking on a geometry. Can be called only if the first point is already specified.

Note

The default label text in the absence of options.text, events.New and events.onValue is just a digit of calculated length between two selected points.

New in version 1.8.0: Added the onStartPoint, onUpdatePoint, and onEndPoint callbacks.

Running

To run the process, you should call the command RunProcessCommand with the AddLinearDimension name of a process.

Example of running the process (TypeScript):

view.runCommand({
    name: "RunProcessCommand",
    process: {
        name: "AddLinearDimension",
        options: {},
        events: {
            onValue: (value: number) => `${value.toFixed(2)} mm`
        }
    }
})

Updating

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

Common type of the updating command (TypeScript):

type UpdateProcess = {
    name: "UpdateProcessCommand"
    options: {
        name: "AddLinearDimension"
        text?: string
        underlineText?: boolean
        font?: {
            family?: string,
            size?: number,
        }
        colors?: {
            text?: C3DViewRGB
            textBkg?: C3DViewRGB
            lines?: C3DViewRGB
        }
    }
}

Example of the command to update comment font size (TypeScript):

view.runCommand({
    name: "UpdateProcessCommand",
    options: {
        name: "AddLinearDimension",
        font: {
            size: 20
        }
    }
})