@shapediver/viewer.features.drawing-tools 3.1.0

package/src/business/interfaces/IDrawingToolsManager.ts

@@ -0,0 +1,313 @@
+import { AxisRestrictionProperties } from '../implementation/managers/interaction/restrictions/axis/AxisRestriction';
+import { GeometryRestrictionProperties } from '../implementation/managers/interaction/restrictions/geometry/GeometryRestriction';
+import { IManager } from './IManager';
+import { IMapData, IMaterialBasicLineDataProperties, IMaterialMultiPointDataProperties } from '@shapediver/viewer.shared.types';
+import { IRestriction, RestrictionProperties } from './IRestriction';
+import { PlaneRestrictionProperties } from '../implementation/managers/interaction/restrictions/plane/PlaneRestriction';
+import { vec3 } from 'gl-matrix';
+
+// #region Type aliases (5)
+
+/**
+ * The callbacks of the drawing tool.
+ * 
+ * Here you can define the callbacks that are used when interacting with the drawing tool.
+ * 
+ * @typedef Callbacks
+ */
+export type Callbacks = {
+    /**
+     * The callback that is called when the drawing tool is cancelled.
+     */
+    onCancel(): void;
+    /**
+     * The callback that is called when the drawing tool is updated.
+     * 
+     * @param pointsData The points data of the drawing tool.
+     */
+    onUpdate(pointsData: PointsData): void;
+};
+export type DefaultTextures = { [key: string]: Promise<IMapData> | IMapData }
+
+/**
+ * The data of the points.
+ * The points are defined as an array of arrays, where each array contains the x, y and z coordinates of the point.
+ * 
+ * @example [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0, 0, 0]]
+ * @typedef PointsData
+ */
+export type PointsData = number[][];
+/**
+ * The initial settings of the drawing tool.
+ * Here you can define the initial settings of the drawing tool.
+ * 
+ * @typedef Settings
+ * 
+ */
+export type Settings = {
+    /**
+     * The geometry settings of the drawing tool.
+     * 
+     * Here you can define the points, the mode and specific details of the geometry.
+     */
+    geometry: {
+        /**
+         * The points that are used when starting the drawing tool.
+         * The points are defined as an array of arrays, where each array contains the x, y and z coordinates of the point.
+         *  
+         * If the mode is set to 'lines', the points are connected in the order they are defined.
+         * If the mode is set to 'points', the points are not connected.
+         * 
+         * @default []
+         * @example [[0, 0, 0], [1, 0, 0], [1, 1, 0], [0, 1, 0], [0, 0, 0]]
+         */
+        points: PointsData;
+
+        /**
+         * The mode of the geometry.
+         * 
+         * If the mode is set to 'lines', the points are connected in the order they are defined.
+         * If the mode is set to 'points', the points are not connected.
+         * 
+         * @default 'lines'
+         */
+        mode: 'points' | 'lines';
+
+        /**
+         * The minimum amount of points, if undefined, the geometry is not restricted.
+         * This value is checked whenever the user tries to update or finish the drawing tool.
+         * 
+         * @default undefined
+         */
+        minPoints?: number;
+
+        /**
+         * The maximum amount of points, if undefined, the geometry is not restricted.
+         * This value is checked whenever the user tries to update or finish the drawing tool.
+         * 
+         * @default undefined
+         */
+        maxPoints?: number;
+
+        /**
+         * If the number of points is strictly checked during the drawing process.
+         * If this setting is set to true, once the minimum or maximum amount of points is reached, the user cannot add or remove points that would violate the restriction.
+         * If this setting is set to false, the user can add or remove points even if the minimum or maximum amount of points is exceeded temporarily.
+         * Once the user tries to update or finish the drawing tool, the amount of points is checked in either case.
+         * 
+         * @default true
+         */
+        strictMinMaxPoints?: boolean;
+
+        /**
+         * If the mode is set to 'lines', if it is a closed line or not.
+         * If the mode is set to 'points', this setting is ignored.
+         * 
+         * A line can be closed by connecting the last point with the first point.
+         * 
+         * @default true
+         */
+        close: boolean;
+
+        /**
+         * If the mode is set to 'lines', if the line is automatically closed.
+         * If the mode is set to 'points', this setting is ignored.
+         * 
+         * The first and last point are always connected if the line is automatically closed.
+         * 
+         * @default true
+         */
+        autoClose: boolean;
+
+    },
+
+    /**
+     * The restrictions of the drawing tool.
+     * 
+     * Here you can define the restrictions that are used when interacting with the drawing tool.
+     * At least one restriction is required, the plane and axis restrictions are added by default if no restrictions are defined.
+     */
+    restrictions: { [key: string]: RestrictionProperties | PlaneRestrictionProperties | GeometryRestrictionProperties | AxisRestrictionProperties };
+
+    /**
+     * The visualization settings of the drawing tool.
+     * 
+     * Here you can define the visualization of the drawing tool.
+     */
+    visualization: {
+        /**
+         * The multiplication factor of the point size when interactions are performed.
+         * If the factor is set to 2, the point size is doubled when interacting.
+         * 
+         * @default 2
+         */
+        distanceMultiplicationFactor: number,
+
+        /**
+         * If the point labels are shown.
+         * The point labels display the position of the points.
+         * 
+         * @default false
+         */
+        pointLabels: boolean,
+
+        /**
+         * If the distance labels are shown.
+         * The distance labels display the distance between the points.
+         * 
+         * @default true
+         */
+        distanceLabels: boolean,
+
+        /**
+         * The material properties of the points.
+         */
+        points: IMaterialMultiPointDataProperties,
+
+        /**
+         * The material properties of the lines.
+         */
+        lines: IMaterialBasicLineDataProperties
+
+    };
+
+    /**
+     * The control settings of the drawing tool.
+     * 
+     * Here you can define which keys are used for the different actions of the drawing tool.
+     */
+    controls: {
+        /**
+         * The key that is used to insert a point.
+         * 
+         * @default ['Insert','+']
+         */
+        insert: string | string[],
+
+        /**
+         * The key that is used to delete a point.
+         * 
+         * @default ['Delete','-']
+         */
+        delete: string | string[],
+
+        /**
+         * The key that is used to confirm actions.
+         * 
+         * @default 'Enter'
+         */
+        confirm: string | string[],
+
+        /**
+         * The key that is used to cancel drawing.
+         * 
+         * @default 'Escape'
+         */
+        cancel: string | string[],
+
+        /**
+         * The keys that are used to undo the last action.
+         * 
+         * @default 'Control+Z'
+         */
+        undo: string | string[],
+
+        /**
+         * The keys that are used to redo the last action.
+         * 
+         * @default 'Control+Y'
+         */
+        redo: string | string[]
+    };
+
+    /**
+     * The general settings of the drawing tool.
+     * 
+     * Here you can define general settings of the drawing tool.
+     */
+    general: {
+        /**
+         * If the drawing tool is started automatically when no points are defined.
+         * 
+         * @default true
+         */
+        autoStart: boolean;
+
+        /**
+         * If the drawing tool is updated automatically when the drawing is changed.
+         * 
+         * @default false
+         */
+        autoUpdate: boolean;
+        /**
+         * If the drawing tool is closed when the drawing is updated.
+         * 
+         * @default false
+         */
+        closeOnUpdate: boolean;
+
+        /** 
+         * The unit that will be displayed in the distance and point labels. 
+         * 
+         * @default ''
+         */
+        displayUnit: string;
+    }
+
+};
+export type SettingsOptional = {
+    geometry?: Partial<Settings['geometry']>;
+    restrictions?: Partial<Settings['restrictions']>;
+    visualization?: Partial<Settings['visualization']>;
+    controls?: Partial<Settings['controls']>;
+    general?: Partial<Settings['general']>;
+};
+
+// #endregion Type aliases (5)
+
+// #region Interfaces (1)
+
+export interface IDrawingToolsManager extends IManager {
+    // #region Properties (4)
+
+    readonly closed: boolean;
+    readonly restrictions: { [key: string]: IRestriction };
+
+    showDistanceLabels: boolean;
+    showPointLabels: boolean;
+
+    // #endregion Properties (4)
+
+    // #region Public Methods (13)
+
+    addPoint(index: number, position?: vec3, temporary?: boolean): void;
+    addRestriction(properties: RestrictionProperties, token?: string): string | undefined;
+    canRedo(): boolean;
+    canUndo(): boolean;
+    cancel(): void;
+    getPointsData(): PointsData;
+    movePoint(index: number, position: vec3, temporary?: boolean): void;
+    redo(): void;
+    removePoint(index: number, temporary?: boolean): void;
+    removePoints(indices: number[]): void;
+    removeRestriction(token: string): void;
+    undo(): void;
+    update(): PointsData | undefined;
+
+    // #endregion Public Methods (13)
+}
+
+// #endregion Interfaces (1)
+
+// #region Enums (1)
+
+export enum MATERIAL_INDEX {
+    DEFAULT = 0,
+    HOVERED = 1,
+    SELECTED = 2,
+    SELECTED_HOVERED = 3,
+    INSERTION = 4,
+    INSERTION_HOVERED = 5
+}
+
+// #endregion Enums (1)

package/src/business/interfaces/IManager.ts

@@ -0,0 +1,7 @@
+export interface IManager {
+    // #region Public Methods (1)
+
+    close(): void;
+
+    // #endregion Public Methods (1)
+}

package/src/business/interfaces/IRestriction.ts

@@ -0,0 +1,64 @@
+import { IRay } from '@shapediver/viewer.features.interaction';
+import { IRestrictionBase } from './IRestrictionBase';
+import { ISnapRestriction } from './ISnapRestriction';
+import { vec3 } from 'gl-matrix';
+
+// #region Type aliases (2)
+
+export type RestrictionMetaData = {
+    index?: number;
+    referencePoint?: vec3;
+}
+
+export type RestrictionProperties = {
+    /**
+     * Type of the restriction
+     */
+    type: RESTRICTION_TYPE;
+};
+
+// #endregion Type aliases (2)
+
+// #region Interfaces (1)
+
+export interface IRestriction extends IRestrictionBase {
+    // #region Properties (2)
+
+    /**
+     * Priority of the restriction
+     */
+    readonly priority: number;
+
+    /**
+     * The snap restrictions of the restriction.
+     */
+    snapRestrictions: { [key: string]: ISnapRestriction; }
+
+    // #endregion Properties (2)
+
+    // #region Public Methods (1)
+
+    /**
+     * Ray trace the restriction.
+     * If the ray does not intersect the restriction, the method returns undefined.
+     * 
+     * @param ray The ray to trace.
+     * @param metaData The meta data of the ray.
+     * @returns The intersection point of the ray with the restriction.
+     */
+    rayTrace(ray: IRay, metaData?: RestrictionMetaData): vec3 | undefined;
+
+    // #endregion Public Methods (1)
+}
+
+// #endregion Interfaces (1)
+
+// #region Enums (1)
+
+export enum RESTRICTION_TYPE {
+    AXIS = 'axis',
+    PLANE = 'plane',
+    GEOMETRY = 'geometry',
+}
+
+// #endregion Enums (1)

package/src/business/interfaces/IRestrictionBase.ts

@@ -0,0 +1,33 @@
+// #region Interfaces (1)
+
+export interface IRestrictionBase {
+    // #region Properties (3)
+
+    /**
+     * The unique identifier of the restriction.
+     */
+    readonly id: string;
+
+    /**
+     * Whether the restriction is enabled or not.
+     */
+    enabled: boolean;
+    
+    /**
+     * Whether the visualization of the restriction is shown or not (if there is one).
+     */
+    showVisualization: boolean;
+
+    // #endregion Properties (3)
+
+    // #region Public Methods (1)
+
+    /**
+     * Remove the visualization of the restriction.
+     */
+    removeVisualization(): void;
+
+    // #endregion Public Methods (1)
+}
+
+// #endregion Interfaces (1)

package/src/business/interfaces/ISnapRestriction.ts

@@ -0,0 +1,70 @@
+import { IRestrictionBase } from './IRestrictionBase';
+import { RestrictionMetaData } from './IRestriction';
+import { vec3 } from 'gl-matrix';
+
+// #region Type aliases (1)
+
+export type SnapRestrictionProperties = {
+    /**
+     * If the restriction should be enabled by default.
+     */
+    enabled?: boolean;
+    /**
+     * If the enabling or disabling of the restriction is allowed to the end user.
+     * If it is not editable, the default value for enabling or disabling the restriction is used.
+     */
+    enabledEditable?: boolean;
+    /**
+     * Priority of the restriction.
+     * The higher the priority, the sooner the restriction is applied.
+     * If the priority is the same, the result that is closer to the original point is chosen.
+     */
+    priority?: number;
+    /**
+     * The activation key of the restriction.
+     * If the key is not provided, no key is assigned.
+     * If the key is provided, the restriction is only active when the key is pressed.
+     */
+    activationKey?: string;
+};
+
+// #endregion Type aliases (1)
+
+// #region Interfaces (1)
+
+export interface ISnapRestriction extends IRestrictionBase {
+    // #region Properties (2)
+
+    /**
+     * If the enabling or disabling of the restriction is allowed to the end user.
+     * If it is not editable, the default value for enabling or disabling the restriction is used.
+     */
+    enabledEditable: boolean;
+
+    /**
+     * If the restriction is actively being used at the moment.
+     */
+    active: boolean;
+
+    /**
+     * The priority of the restriction.
+     */
+    priority: number;
+
+    // #endregion Properties (2)
+
+    // #region Public Methods (1)
+
+    /**
+     * Restrict the position of a point.
+     * 
+     * @param point The position of the point.
+     * @param metaData The meta data of the point.
+     * @returns The restricted position of the point.
+     */
+    snap(point: vec3, metaData?: RestrictionMetaData): vec3 | undefined;
+
+    // #endregion Public Methods (1)
+}
+
+// #endregion Interfaces (1)

package/src/business/interfaces/events/EventResponseMapping.ts

@@ -0,0 +1,19 @@
+import { EVENTTYPE_DRAWING_TOOLS } from '@shapediver/viewer';
+import { IDrawingToolsEvent } from './IDrawingToolsEvent';
+
+export type DrawingToolsEventResponseMapping = {
+    [EVENTTYPE_DRAWING_TOOLS.CANCEL]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.FINISH]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.ADDED]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.REMOVED]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.MOVED]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.GEOMETRY_CHANGED]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.SELECTED]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.DESELECTED]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.DRAG_START]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.DRAG_MOVE]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.DRAG_END]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.MINIMUM_POINTS]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.MAXIMUM_POINTS]: IDrawingToolsEvent,
+    [EVENTTYPE_DRAWING_TOOLS.UNCLOSED_LOOP]: IDrawingToolsEvent,
+}

package/src/business/interfaces/events/IDrawingToolsEvent.ts

@@ -0,0 +1,16 @@
+import { IViewportEvent } from '@shapediver/viewer';
+import { PointsData } from '../IDrawingToolsManager';
+
+export interface IDrawingToolsEvent extends IViewportEvent {
+    // #region Properties (7)
+
+    drawingToolId: string;
+    fromHistory?: boolean;
+    index?: number;
+    message?: string;
+    points?: PointsData;
+    recordHistory?: boolean;
+    temporary?: boolean;
+
+    // #endregion Properties (7)
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+import { AngularRestrictionApi } from './api/implementation/restrictions/plane/snap/AngularRestrictionApi';
+import { AngularRestrictionProperties } from './business/implementation/managers/interaction/restrictions/plane/snap/AngularRestriction';
+import { AxisRestrictionApi } from './api/implementation/restrictions/axis/AxisRestrictionApi';
+import { AxisRestrictionProperties } from './business/implementation/managers/interaction/restrictions/axis/AxisRestriction';
+import { Callbacks, PointsData, SettingsOptional } from './business/interfaces/IDrawingToolsManager';
+import { DrawingToolsApi } from './api/implementation/DrawingToolsApi';
+import { DrawingToolsEventResponseMapping } from './business/interfaces/events/EventResponseMapping';
+import { GeometryRestrictionApi } from './api/implementation/restrictions/geometry/GeometryRestrictionApi';
+import { GeometryRestrictionProperties } from './business/implementation/managers/interaction/restrictions/geometry/GeometryRestriction';
+import { GridRestrictionApi } from './api/implementation/restrictions/plane/snap/GridRestrictionApi';
+import { GridRestrictionProperties } from './business/implementation/managers/interaction/restrictions/plane/snap/GridRestriction';
+import { IDrawingToolsApi } from './api/interfaces/IDrawingToolsApi';
+import { IDrawingToolsEvent } from './business/interfaces/events/IDrawingToolsEvent';
+import {
+    IMapData,
+    IViewportApi,
+    MaterialEngine,
+    ShapeDiverViewerDrawingToolsError
+    } from '@shapediver/viewer';
+import {
+    IRestriction,
+    RESTRICTION_TYPE,
+    RestrictionMetaData,
+    RestrictionProperties
+    } from './business/interfaces/IRestriction';
+import { IRestrictionApi } from './api/interfaces/IRestrictionApi';
+import { IRestrictionBase } from './business/interfaces/IRestrictionBase';
+import { ISnapRestriction, SnapRestrictionProperties } from './business/interfaces/ISnapRestriction';
+import { PlaneRestrictionApi } from './api/implementation/restrictions/plane/PlaneRestrictionApi';
+import { PlaneRestrictionProperties } from './business/implementation/managers/interaction/restrictions/plane/PlaneRestriction';
+import { SystemInfo } from '@shapediver/viewer.shared.services';
+
+export {
+    SettingsOptional as Settings, Callbacks,
+    DrawingToolsEventResponseMapping, IDrawingToolsEvent,
+    IDrawingToolsApi, DrawingToolsApi, PointsData,
+    PlaneRestrictionProperties, GridRestrictionProperties, AngularRestrictionProperties,
+    GeometryRestrictionProperties,
+    AxisRestrictionProperties,
+    IRestrictionApi, PlaneRestrictionApi, GridRestrictionApi, AngularRestrictionApi, GeometryRestrictionApi, AxisRestrictionApi,
+    IRestrictionBase, RestrictionProperties, IRestriction, RestrictionMetaData, RESTRICTION_TYPE, SnapRestrictionProperties, ISnapRestriction,
+};
+
+const defaultTextures: { [key: string]: Promise<IMapData> | IMapData } = {};
+
+defaultTextures['variation_0'] = MaterialEngine.instance.loadMap('https://viewer.shapediver.com/v3/graphics/point_soft.png')
+    .then((mapData: IMapData | null) => {
+        defaultTextures['variation_0'] = mapData!;
+        return mapData!;
+    });
+
+let drawingTools: IDrawingToolsApi | undefined;
+
+/**
+ * Create a new instance of DrawingTools.
+ * 
+ * @param viewport The viewport to which the DrawingTools should be attached.
+ * @param callback The callback function that is called when the drawing is finished.
+ * @param properties The customization properties for the DrawingTools.
+ * @returns The DrawingTools instance.
+ * @throws An error if there is already an active instance of DrawingTools.
+ */
+export const createDrawingTools = (viewport: IViewportApi, callbacks: Callbacks, settings: SettingsOptional): IDrawingToolsApi => {
+    if (SystemInfo.instance.isMobile)
+        throw new ShapeDiverViewerDrawingToolsError('The DrawingTools are not supported on mobile devices.');
+
+    if (drawingTools && drawingTools.closed === false)
+        throw new ShapeDiverViewerDrawingToolsError('There can only be one instance of DrawingTools active at a time. Please close the current instance before creating a new one.');
+
+    drawingTools = new DrawingToolsApi(viewport, callbacks, settings, defaultTextures);
+    return drawingTools;
+};