@plastic-software/three 0.174.0 → 0.175.1

package/examples/jsm/controls/TrackballControls.js

@@ -7,8 +7,28 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * Fires when the camera has been transformed by the controls.
+ *
+ * @event TrackballControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires when an interaction was initiated.
+ *
+ * @event TrackballControls#start
+ * @type {Object}
+ */
 const _startEvent = { type: 'start' };
+
+/**
+ * Fires when an interaction has finished.
+ *
+ * @event TrackballControls#end
+ * @type {Object}
+ */
 const _endEvent = { type: 'end' };
 
 const _EPS = 0.000001;
@@ -25,45 +45,168 @@ const _objectUpDirection = new Vector3();
 const _objectSidewaysDirection = new Vector3();
 const _moveDirection = new Vector3();
 
+/**
+ * This class is similar to {@link OrbitControls}. However, it does not maintain a constant camera
+ * `up` vector. That means if the camera orbits over the “north” and “south” poles, it does not flip
+ * to stay "right side up".
+ *
+ * @augments Controls
+ */
 class TrackballControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Object3D} object - The object that is managed by the controls.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( object, domElement = null ) {
 
 		super( object, domElement );
 
-		// API
-
-		this.enabled = true;
-
+		/**
+		 * Represents the properties of the screen. Automatically set when `handleResize()` is called.
+		 *
+		 * @type {Object}
+		 * @readonly
+		 */
 		this.screen = { left: 0, top: 0, width: 0, height: 0 };
 
+		/**
+		 * The rotation speed.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.rotateSpeed = 1.0;
+
+		/**
+		 * The zoom speed.
+		 *
+		 * @type {number}
+		 * @default 1.2
+		 */
 		this.zoomSpeed = 1.2;
+
+		/**
+		 * The pan speed.
+		 *
+		 * @type {number}
+		 * @default 0.3
+		 */
 		this.panSpeed = 0.3;
 
+		/**
+		 * Whether rotation is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.noRotate = false;
+
+		/**
+		 * Whether zooming is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.noZoom = false;
+
+		/**
+		 * Whether panning is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.noPan = false;
 
+		/**
+		 * Whether damping is disabled or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.staticMoving = false;
+
+		/**
+		 * Defines the intensity of damping. Only considered if `staticMoving` is set to `false`.
+		 *
+		 * @type {number}
+		 * @default 0.2
+		 */
 		this.dynamicDampingFactor = 0.2;
 
+		/**
+		 * How far you can dolly in (perspective camera only).
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minDistance = 0;
+
+		/**
+		 * How far you can dolly out (perspective camera only).
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxDistance = Infinity;
 
+		/**
+		 * How far you can zoom in (orthographic camera only).
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.minZoom = 0;
+
+		/**
+		 * How far you can zoom out (orthographic camera only).
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.maxZoom = Infinity;
 
+		/**
+		 * This array holds keycodes for controlling interactions.
+		 *
+		 * - When the first defined key is pressed, all mouse interactions (left, middle, right) performs orbiting.
+		 * - When the second defined key is pressed, all mouse interactions (left, middle, right) performs zooming.
+		 * - When the third defined key is pressed, all mouse interactions (left, middle, right) performs panning.
+		 *
+		 * Default is *KeyA, KeyS, KeyD* which represents A, S, D.
+		 *
+		 * @type {Array<string>}
+		 */
 		this.keys = [ 'KeyA' /*A*/, 'KeyS' /*S*/, 'KeyD' /*D*/ ];
 
+		/**
+		 * This object contains references to the mouse actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	LEFT: THREE.MOUSE.ROTATE,
+		 * 	MIDDLE: THREE.MOUSE.DOLLY,
+		 * 	RIGHT: THREE.MOUSE.PAN
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.mouseButtons = { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.PAN };
-		this.state = _STATE.NONE;
-		this.keyState = _STATE.NONE;
 
+		/**
+		 * The focus point of the controls.
+		 *
+		 * @type {Vector3}
+		 */
 		this.target = new Vector3();
 
 		// internals
 
+		this.state = _STATE.NONE;
+		this.keyState = _STATE.NONE;
+
 		this._lastPosition = new Vector3();
 		this._lastZoom = 1;
 		this._touchZoomDistanceStart = 0;
@@ -114,7 +257,7 @@ class TrackballControls extends Controls {
 
 		if ( domElement !== null ) {
 
-			this.connect();
+			this.connect( domElement );
 
 			this.handleResize();
 
@@ -125,7 +268,9 @@ class TrackballControls extends Controls {
 
 	}
 
-	connect() {
+	connect( element ) {
+
+		super.connect( element );
 
 		window.addEventListener( 'keydown', this._onKeyDown );
 		window.addEventListener( 'keyup', this._onKeyUp );
@@ -161,6 +306,9 @@ class TrackballControls extends Controls {
 
 	}
 
+	/**
+	 * Must be called if the application window is resized.
+	 */
 	handleResize() {
 
 		const box = this.domElement.getBoundingClientRect();
@@ -233,6 +381,9 @@ class TrackballControls extends Controls {
 
 	}
 
+	/**
+	 * Resets the controls to its initial state.
+	 */
 	reset() {
 
 		this.state = _STATE.NONE;

package/examples/jsm/controls/TransformControls.js

@@ -32,13 +32,55 @@ const _unit = {
 	Z: new Vector3( 0, 0, 1 )
 };
 
+/**
+ * Fires if any type of change (object or property change) is performed. Property changes
+ * are separate events you can add event listeners to. The event type is "propertyname-changed".
+ *
+ * @event TransformControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
+
+/**
+ * Fires if a pointer (mouse/touch) becomes active.
+ *
+ * @event TransformControls#mouseDown
+ * @type {Object}
+ */
 const _mouseDownEvent = { type: 'mouseDown', mode: null };
+
+/**
+ * Fires if a pointer (mouse/touch) is no longer active.
+ *
+ * @event TransformControls#mouseUp
+ * @type {Object}
+ */
 const _mouseUpEvent = { type: 'mouseUp', mode: null };
+
+/**
+ * Fires if the controlled 3D object is changed.
+ *
+ * @event TransformControls#objectChange
+ * @type {Object}
+ */
 const _objectChangeEvent = { type: 'objectChange' };
 
+/**
+ * This class can be used to transform objects in 3D space by adapting a similar interaction model
+ * of DCC tools like Blender. Unlike other controls, it is not intended to transform the scene's camera.
+ *
+ * `TransformControls` expects that its attached 3D object is part of the scene graph.
+ *
+ * @augments Controls
+ */
 class TransformControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Camera} camera - The camera of the rendered scene.
+	 * @param {?HTMLDOMElement} domElement - The HTML element used for event listeners.
+	 */
 	constructor( camera, domElement = null ) {
 
 		super( undefined, domElement );
@@ -96,25 +138,170 @@ class TransformControls extends Controls {
 		// Setting the defined property will automatically trigger change event
 		// Defined properties are passed down to gizmo and plane
 
+		/**
+		 * The camera of the rendered scene.
+		 *
+		 * @name TransformControls#camera
+		 * @type {Camera}
+		 */
 		defineProperty( 'camera', camera );
 		defineProperty( 'object', undefined );
 		defineProperty( 'enabled', true );
+
+		/**
+		 * The current transformation axis.
+		 *
+		 * @name TransformControls#axis
+		 * @type {string}
+		 */
 		defineProperty( 'axis', null );
+
+		/**
+		 * The current transformation axis.
+		 *
+		 * @name TransformControls#mode
+		 * @type {('translate'|'rotate'|'scale')}
+		 * @default 'translate'
+		 */
 		defineProperty( 'mode', 'translate' );
+
+		/**
+		 * By default, 3D objects are continuously translated. If you set this property to a numeric
+		 * value (world units), you can define in which steps the 3D object should be translated.
+		 *
+		 * @name TransformControls#translationSnap
+		 * @type {?number}
+		 * @default null
+		 */
 		defineProperty( 'translationSnap', null );
+
+		/**
+		 * By default, 3D objects are continuously rotated. If you set this property to a numeric
+		 * value (radians), you can define in which steps the 3D object should be rotated.
+		 *
+		 * @name TransformControls#rotationSnap
+		 * @type {?number}
+		 * @default null
+		 */
 		defineProperty( 'rotationSnap', null );
+
+		/**
+		 * By default, 3D objects are continuously scaled. If you set this property to a numeric
+		 * value, you can define in which steps the 3D object should be scaled.
+		 *
+		 * @name TransformControls#scaleSnap
+		 * @type {?number}
+		 * @default null
+		 */
 		defineProperty( 'scaleSnap', null );
+
+		/**
+		 * Defines in which coordinate space transformations should be performed.
+		 *
+		 * @name TransformControls#space
+		 * @type {('world'|'local')}
+		 * @default 'world'
+		 */
 		defineProperty( 'space', 'world' );
+
+		/**
+		 * The size of the helper UI (axes/planes).
+		 *
+		 * @name TransformControls#size
+		 * @type {number}
+		 * @default 1
+		 */
 		defineProperty( 'size', 1 );
+
+		/**
+		 * Whether dragging is currently performed or not.
+		 *
+		 * @name TransformControls#dragging
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		defineProperty( 'dragging', false );
+
+		/**
+		 * Whether the x-axis helper should be visible or not.
+		 *
+		 * @name TransformControls#showX
+		 * @type {boolean}
+		 * @default true
+		 */
 		defineProperty( 'showX', true );
+
+		/**
+		 * Whether the y-axis helper should be visible or not.
+		 *
+		 * @name TransformControls#showY
+		 * @type {boolean}
+		 * @default true
+		 */
 		defineProperty( 'showY', true );
+
+		/**
+		 * Whether the z-axis helper should be visible or not.
+		 *
+		 * @name TransformControls#showZ
+		 * @type {boolean}
+		 * @default true
+		 */
 		defineProperty( 'showZ', true );
+
+		/**
+		 * The minimum allowed X position during translation.
+		 *
+		 * @name TransformControls#minX
+		 * @type {number}
+		 * @default -Infinity
+		 */
 		defineProperty( 'minX', - Infinity );
+
+		/**
+		 * The maximum allowed X position during translation.
+		 *
+		 * @name TransformControls#maxX
+		 * @type {number}
+		 * @default Infinity
+		 */
 		defineProperty( 'maxX', Infinity );
+
+		/**
+		 * The minimum allowed y position during translation.
+		 *
+		 * @name TransformControls#minY
+		 * @type {number}
+		 * @default -Infinity
+		 */
 		defineProperty( 'minY', - Infinity );
+
+		/**
+		 * The maximum allowed Y position during translation.
+		 *
+		 * @name TransformControls#maxY
+		 * @type {number}
+		 * @default Infinity
+		 */
 		defineProperty( 'maxY', Infinity );
+
+		/**
+		 * The minimum allowed z position during translation.
+		 *
+		 * @name TransformControls#minZ
+		 * @type {number}
+		 * @default -Infinity
+		 */
 		defineProperty( 'minZ', - Infinity );
+
+		/**
+		 * The maximum allowed Z position during translation.
+		 *
+		 * @name TransformControls#maxZ
+		 * @type {number}
+		 * @default Infinity
+		 */
 		defineProperty( 'maxZ', Infinity );
 
 		// Reusable utility variables
@@ -171,13 +358,15 @@ class TransformControls extends Controls {
 
 		if ( domElement !== null ) {
 
-			this.connect();
+			this.connect( domElement );
 
 		}
 
 	}
 
-	connect() {
+	connect( element ) {
+
+		super.connect( element );
 
 		this.domElement.addEventListener( 'pointerdown', this._onPointerDown );
 		this.domElement.addEventListener( 'pointermove', this._onPointerHover );
@@ -198,6 +387,12 @@ class TransformControls extends Controls {
 
 	}
 
+	/**
+	 * Returns the visual representation of the controls. Add the helper to your scene to
+	 * visually transform the attached  3D object.
+	 *
+	 * @return {TransformControlsRoot} The helper.
+	 */
 	getHelper() {
 
 		return this._root;
@@ -550,7 +745,12 @@ class TransformControls extends Controls {
 
 	}
 
-	// Set current object
+	/**
+	 * Sets the 3D object that should be transformed and ensures the controls UI is visible.
+	 *
+	 * @param {Object3D} object -  The 3D object that should be transformed.
+	 * @return {TransformControls} A reference to this controls.
+	 */
 	attach( object ) {
 
 		this.object = object;
@@ -560,7 +760,11 @@ class TransformControls extends Controls {
 
 	}
 
-	// Detach from object
+	/**
+	 * Removes the current 3D object from the controls and makes the helper UI invisible.
+	 *
+	 * @return {TransformControls} A reference to this controls.
+	 */
 	detach() {
 
 		this.object = undefined;
@@ -572,6 +776,9 @@ class TransformControls extends Controls {
 
 	}
 
+	/**
+	 * Resets the object's position, rotation and scale to when the current transform began.
+	 */
 	reset() {
 
 		if ( ! this.enabled ) return;
@@ -591,50 +798,89 @@ class TransformControls extends Controls {
 
 	}
 
+	/**
+	 * Returns the raycaster that is used for user interaction. This object is shared between all
+	 * instances of `TransformControls`.
+	 *
+	 * @returns {Raycaster} The internal raycaster.
+	 */
 	getRaycaster() {
 
 		return _raycaster;
 
 	}
 
-	// TODO: deprecate
-
+	/**
+	 * Returns the transformation mode.
+	 *
+	 * @returns {'translate'|'rotate'|'scale'} The transformation mode.
+	 */
 	getMode() {
 
 		return this.mode;
 
 	}
 
+	/**
+	 * Sets the given transformation mode.
+	 *
+	 * @param {'translate'|'rotate'|'scale'} mode - The transformation mode to set.
+	 */
 	setMode( mode ) {
 
 		this.mode = mode;
 
 	}
 
+	/**
+	 * Sets the translation snap.
+	 *
+	 * @param {?number} translationSnap - The translation snap to set.
+	 */
 	setTranslationSnap( translationSnap ) {
 
 		this.translationSnap = translationSnap;
 
 	}
 
+	/**
+	 * Sets the rotation snap.
+	 *
+	 * @param {?number} rotationSnap - The rotation snap to set.
+	 */
 	setRotationSnap( rotationSnap ) {
 
 		this.rotationSnap = rotationSnap;
 
 	}
 
+	/**
+	 * Sets the scale snap.
+	 *
+	 * @param {?number} scaleSnap - The scale snap to set.
+	 */
 	setScaleSnap( scaleSnap ) {
 
 		this.scaleSnap = scaleSnap;
 
 	}
 
+	/**
+	 * Sets the size of the helper UI.
+	 *
+	 * @param {number} size - The size to set.
+	 */
 	setSize( size ) {
 
 		this.size = size;
 
 	}
 
+	/**
+	 * Sets the coordinate space in which transformations are applied.
+	 *
+	 * @param {'world'|'local'} space - The space to set.
+	 */
 	setSpace( space ) {
 
 		this.space = space;