@shapediver/viewer.features.transformation-tools

This is the npm package for the ShapeDiver Viewer Transformation Tools features. Please have a look at our help desk section for this feature.

For more information on ShapeDiver, please visit our homepage. If you need help, have a look at our help desk.

This package provides two transformation tools: GumballTransform for full 3D translation, rotation, and scaling via a 3D gizmo, and RectangleTransform for 2D translation, rotation, and scaling on a defined plane via a rectangular handle. Both tools have already been integrated with App Builder, allowing you to initialize them via a Grasshopper component without any coding.

Installation

npm install --save @shapediver/viewer.features.transformation-tools
Copy

Usage

As this is an additional package to the @shapediver/viewer package, we omit the initial setup. Please have a look here.

GumballTransform

The GumballTransform allows you to translate, rotate, and scale geometry in 3D using a familiar gizmo. This is the standard behavior found in most 3D software.

The GumballTransform has already been integrated with App Builder. This allows you to use a component in Grasshopper to initialize the GumballTransform. With this approach, no coding is needed.

Initial Setup

The GumballTransform is initialized with the viewport in which it should be created and the nodes it should act on.

Once the GumballTransform has been created, you can listen to the EVENTTYPE_TRANSFORMATION_TOOLS.MATRIX_CHANGED event which is emitted whenever the movement of the GumballTransform ends. In this event you get the current nodes and the matrices that are applied to it.

import {
	GumballTransform,
	EventResponseMapping,
} from "@shapediver/viewer.features.transformation-tools";
import {addListener, EVENTTYPE_TRANSFORMATION_TOOLS} from "@shapediver/viewer";

// create the GumballTransform with a viewport and the nodes
const gumballTransform = new GumballTransform(viewport, nodes);

// listen to the event to be notified of changes
const eventListenerToken = addListener(
	EVENTTYPE_TRANSFORMATION_TOOLS.MATRIX_CHANGED,
	(e) => {
		const event =
			e as EventResponseMapping[EVENTTYPE_TRANSFORMATION_TOOLS.MATRIX_CHANGED];

		console.log(
			`GumballTransform has changed: 
        - viewportId: ${event.viewportId}
        - nodes: ${event.nodes}
        - transformations: ${event.transformations}`,
		);
	},
);
Copy

The nodes can either be taken from the scene tree or supplied by a user selection. For further information on the settings that are available, please visit the API documentation.

Settings

General (inherited from all Transformation Tools):

Name	Description	Default
enableRotation	Enable or disable rotation.	true
enableScaling	Enable or disable scaling.	true
enableTranslation	Enable or disable translation.	true
reuseTransformation	Reuse the transformation already applied to the nodes.	true
restrictions	Restrictions applied to the transformation (keyed by id).	{}

GumballTransform-specific:

Name	Description	Default
scale	The scale of the gizmo compared to the screen size.	0.15
space	The space in which the gizmo operates ("local" or "world").	local
enableRotationAxes	Fine-grained enable/disable per rotation axis (x, y, z, xy, yz, xz).	all true
enableScalingAxes	Fine-grained enable/disable per scaling axis (x, y, z, xy, yz, xz).	all true
enableTranslationAxes	Fine-grained enable/disable per translation axis (x, y, z, xy, yz, xz).	all true

---

RectangleTransform

The RectangleTransform allows you to translate, rotate and scale geometry in the scene using a 2D rectangular handle that lives on a defined plane. It is well-suited for flat or planar objects where a 3D gizmo would be unnecessarily complex.

The RectangleTransform has already been integrated with App Builder. This allows you to use a component in Grasshopper to initialize the RectangleTransform. With this approach, no coding is needed.

Initial Setup

The RectangleTransform is initialized with the viewport, the nodes to transform, and a settings object. The plane setting is required and defines the plane on which the rectangle is drawn and interacted with.

import {
	RectangleTransform,
	EventResponseMapping,
} from "@shapediver/viewer.features.transformation-tools";
import {addListener, EVENTTYPE_TRANSFORMATION_TOOLS} from "@shapediver/viewer";

// create the RectangleTransform with a viewport, nodes, and a plane definition
const rectangleTransform = new RectangleTransform(viewport, nodes, {
	plane: {
		origin: [0, 0, 0],
		vector_u: [1, 0, 0],
		vector_v: [0, 1, 0],
	},
});

// listen to the event to be notified of changes
const eventListenerToken = addListener(
	EVENTTYPE_TRANSFORMATION_TOOLS.MATRIX_CHANGED,
	(e) => {
		const event =
			e as EventResponseMapping[EVENTTYPE_TRANSFORMATION_TOOLS.MATRIX_CHANGED];

		// filter for this specific instance when multiple instances are active
		if (event.id !== rectangleTransform.id) return;

		console.log(
			`RectangleTransform has changed:
        - viewportId: ${event.viewportId}
        - nodes: ${event.nodes}
        - transformations: ${event.transformations}`,
		);
	},
);
Copy

The nodes can either be taken from the scene tree or supplied by a user selection. For further information on the settings that are available, please visit the API documentation.

Settings

There are different settings that can be used to tailor the RectangleTransform to your needs.

General (inherited from all Transformation Tools):

Name	Description	Default
enableRotation	Enable or disable rotation.	true
enableScaling	Enable or disable scaling.	true
enableTranslation	Enable or disable translation.	true
reuseTransformation	Reuse the transformation already applied to the nodes.	true
restrictions	Restrictions applied to the transformation (keyed by id).	{}

RectangleTransform-specific:

Name	Description	Default
plane	The plane on which the rectangle is drawn. Requires origin, vector_u, and vector_v.	XY plane
corners.topLeft	Enable or disable the top-left corner handle.	true
corners.topRight	Enable or disable the top-right corner handle.	true
corners.bottomLeft	Enable or disable the bottom-left corner handle.	true
corners.bottomRight	Enable or disable the bottom-right corner handle.	true
edgeControls.top	Enable or disable the top edge handle.	true
edgeControls.bottom	Enable or disable the bottom edge handle.	true
edgeControls.left	Enable or disable the left edge handle.	true
edgeControls.right	Enable or disable the right edge handle.	true
scaling.uniform	If true, scale equally in both directions.	false
scaling.uMin / uMax	Minimum / maximum allowed length along the U axis.	undefined
scaling.vMin / vMax	Minimum / maximum allowed length along the V axis.	undefined
scaling.step	Snap step size for scaling (in world units).	undefined
scaling.visualization	Customize the appearance of the scaling handles and outline.	undefined
rotation.step	Snap step size for rotation (in degrees).	undefined
rotation.stepThreshold	Proximity threshold for snapping during rotation (in degrees).	undefined
rotation.min / max	Minimum / maximum allowed rotation angle (in degrees).	undefined
rotation.handleDistance	Distance of the rotation handle above the top edge, as a fraction of the rectangle's height.	0.25
rotation.visualization	Customize the appearance of the rotation handle.	undefined