Drawing Tools

This feature is still in the Beta-version!

While we tried to ensure that everything already works as expected, please let us know if that is not the case or if you find features missing.

The drawing tools feature can be used to create or edit point and line data. Points can be added, moved or removed. With the available settings, it's possible to fine tune the drawing tools to the needs of the user.

Multiple restrictions are available which can be used to restrict the point movement to either a grid, angular connections to neighboring lines or other geometry.

The complete API documentation of the drawing tools module can be found here.

This is a feature that can be added via a separate CDN or npm-module on top of our viewer module.

To install it call

CODE

npm install --save @shapediver/viewer.features.drawing-tools

or if you use the viewer via a CDN just can just get the SDVDrawingTools property from the window object.

Initial Setup

The initial setup of the drawing tools is quite straightforward. After creating a viewport (and a session) you can create the drawing tools as follows:

TYPESCRIPT

/**
  * Define the settings you want to use for the drawing tools
  */
const customizationProperties: Settings = {
  // add your settings here  
};

/**
  * Callback function for the drawing tool
  * executed when the drawing tool is updated
  * 
  * @param geometryData 
  */
const onUpdate = async (pointsData: PointsData) => {
    console.log('Drawing tools updated', pointsData);
};

/**
  * Callback function for the drawing tool
  * executed when the drawing tool is cancelled
  */
const onCancel = () => {
    console.log('Drawing tools cancelled');
};

const drawingToolsApi: IDrawingToolsApi | undefined = createDrawingTools(viewport, { onUpdate, onCancel }, customizationProperties);

The settings object of the drawing tools is the most important part to fine tune the drawing tools. For further information on the settings that are available, please visit the API documentation.

Key Settings

The settings object is organized into several top-level sections. Below are the most commonly used properties.

Geometry Settings (`geometry`)

Controls the shape being drawn:

Setting	Type	Description
`geometry.mode`	`'lines' \| 'points'`	Lines: points are connected in order. Points: independent, unconnected points.
`geometry.points`	`number[][]`	Initial points as `[x, y, z]` coordinate arrays.
`geometry.close`	`boolean`	Initial closed state (the user can toggle this). Connects last point to first.
`geometry.autoClose`	`boolean`	Forces the line to stay closed permanently. Default `false`.
`geometry.minPoints`	`number`	Minimum number of points required.
`geometry.maxPoints`	`number`	Maximum number of points allowed.

Restrictions (`restrictions`)

At least one restriction is required. Each restriction is a typed object with a type field:

Type	Key Properties	Description
`'plane'`	`origin`, `vector_u`, `vector_v`	Constrain points to a 2D plane. Can also host snap sub-restrictions.
`'point'`	`point`, `radius`	Snap to a specific 3D point within a radius.
`'line'`	`point1`, `point2`, `radius`	Snap to a line segment within a radius.
`'geometry'`	`nodes` or `nameFilter`	Snap to existing geometry surfaces in the scene.
`'camera_plane'`	—	Constrain points to the current camera plane.

Plane restrictions can additionally include nested snap sub-restrictions: gridSnapRestriction, angularSnapRestriction, and axisSnapRestriction. These are properties of the plane restriction object, not standalone settings.

Example with Settings

TYPESCRIPT

const settings = {
  geometry: {
    mode: "lines",
    points: [],
    close: true,
    autoClose: false,
    maxPoints: 10,
    minPoints: 3
  },
  restrictions: [
    {
      type: "plane",
      id: "ground",
      origin: [0, 0, 0],
      vector_u: [1, 0, 0],
      vector_v: [0, 1, 0],
      gridSnapRestriction: {
        gridSize: 5
      }
    }
  ]
};

const drawingToolsApi = createDrawingTools(
  viewport,
  { onUpdate, onCancel },
  settings
);

For the complete list of settings and their types, see the Drawing Tools API documentation.

Showcase

In this example you can see how a line can be edited. The corresponding geometry data is then used as an input for the model to create the building.

Additional Examples

Additional example can be found on the viewer examples page in the drawing tools section.