@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/controls/DragControls.js

@@ -31,18 +31,79 @@ const STATE = {
 	ROTATE: 1
 };
 
+/**
+ * This class can be used to provide a drag'n'drop interaction.
+ *
+ * ```js
+ * const controls = new DragControls( objects, camera, renderer.domElement );
+ *
+ * // add event listener to highlight dragged objects
+ * controls.addEventListener( 'dragstart', function ( event ) {
+ *
+ * 	event.object.material.emissive.set( 0xaaaaaa );
+ *
+ * } );
+ *
+ * controls.addEventListener( 'dragend', function ( event ) {
+ *
+ * 	event.object.material.emissive.set( 0x000000 );
+ *
+ * } );
+ * ```
+ *
+ * @augments Controls
+ */
 class DragControls extends Controls {
 
+	/**
+	 * Constructs a new controls instance.
+	 *
+	 * @param {Array<Object3D>} objects - An array of draggable 3D objects.
+	 * @param {Camera} camera - The camera of the rendered scene.
+	 * @param {?HTMLDOMElement} [domElement=null] - The HTML DOM element used for event listeners.
+	 */
 	constructor( objects, camera, domElement = null ) {
 
 		super( camera, domElement );
 
+		/**
+		 * An array of draggable 3D objects.
+		 *
+		 * @type {Array<Object3D>}
+		 */
 		this.objects = objects;
 
+		/**
+		 * Whether children of draggable objects can be dragged independently from their parent.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.recursive = true;
+
+		/**
+		 * This option only works if the `objects` array contains a single draggable  group object.
+		 * If set to `true`, the controls does not transform individual objects but the entire group.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.transformGroup = false;
+
+		/**
+		 * The speed at which the object will rotate when dragged in `rotate` mode.
+		 * The higher the number the faster the rotation.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.rotateSpeed = 1;
 
+		/**
+		 * The raycaster used for detecting 3D objects.
+		 *
+		 * @type {Raycaster}
+		 */
 		this.raycaster = new Raycaster();
 
 		// interaction
@@ -61,13 +122,15 @@ class DragControls extends Controls {
 
 		if ( domElement !== null ) {
 
-			this.connect();
+			this.connect( domElement );
 
 		}
 
 	}
 
-	connect() {
+	connect( element ) {
+
+		super.connect( element );
 
 		this.domElement.addEventListener( 'pointermove', this._onPointerMove );
 		this.domElement.addEventListener( 'pointerdown', this._onPointerDown );
@@ -407,4 +470,32 @@ function findGroup( obj, group = null ) {
 
 }
 
+/**
+ * Fires when the user drags a 3D object.
+ *
+ * @event DragControls#drag
+ * @type {Object}
+ */
+
+/**
+ * Fires when the user has finished dragging a 3D object.
+ *
+ * @event DragControls#dragend
+ * @type {Object}
+ */
+
+/**
+ * Fires when the pointer is moved onto a 3D object, or onto one of its children.
+ *
+ * @event DragControls#hoveron
+ * @type {Object}
+ */
+
+/**
+ * Fires when the pointer is moved out of a 3D object.
+ *
+ * @event DragControls#hoveroff
+ * @type {Object}
+ */
+
 export { DragControls };

package/examples/jsm/controls/FirstPersonControls.js

@@ -10,31 +10,127 @@ const _spherical = new Spherical();
 const _target = new Vector3();
 const _targetPosition = new Vector3();
 
+/**
+ * This class is an alternative implementation of {@link FlyControls}.
+ *
+ * @augments Controls
+ */
 class FirstPersonControls 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
-
+		/**
+		 * The movement speed.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.movementSpeed = 1.0;
+
+		/**
+		 * The look around speed.
+		 *
+		 * @type {number}
+		 * @default 0.005
+		 */
 		this.lookSpeed = 0.005;
 
+		/**
+		 * Whether it's possible to vertically look around or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.lookVertical = true;
+
+		/**
+		 * Whether the camera is automatically moved forward or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.autoForward = false;
 
+		/**
+		 * Whether it's possible to look around or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.activeLook = true;
 
+		/**
+		 * Whether or not the camera's height influences the forward movement speed.
+		 * Use the properties `heightCoef`, `heightMin` and `heightMax` for configuration.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.heightSpeed = false;
+
+		/**
+		 * Determines how much faster the camera moves when it's y-component is near `heightMax`.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.heightCoef = 1.0;
+
+		/**
+		 * Lower camera height limit used for movement speed adjustment.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.heightMin = 0.0;
+
+		/**
+		 * Upper camera height limit used for movement speed adjustment.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.heightMax = 1.0;
 
+		/**
+		 * Whether or not looking around is vertically constrained by `verticalMin` and `verticalMax`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.constrainVertical = false;
+
+		/**
+		 * How far you can vertically look around, lower limit. Range is `0` to `Math.PI` in radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.verticalMin = 0;
+
+		/**
+		 * How far you can vertically look around, upper limit. Range is `0` to `Math.PI` in radians.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.verticalMax = Math.PI;
 
+		/**
+		 * Whether the mouse is pressed down or not.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		this.mouseDragOn = false;
 
 		// internals
@@ -68,7 +164,7 @@ class FirstPersonControls extends Controls {
 
 		if ( domElement !== null ) {
 
-			this.connect();
+			this.connect( domElement );
 
 			this.handleResize();
 
@@ -78,7 +174,9 @@ class FirstPersonControls extends Controls {
 
 	}
 
-	connect() {
+	connect( element ) {
+
+		super.connect( element );
 
 		window.addEventListener( 'keydown', this._onKeyDown );
 		window.addEventListener( 'keyup', this._onKeyUp );
@@ -108,6 +206,9 @@ class FirstPersonControls extends Controls {
 
 	}
 
+	/**
+	 * Must be called if the application window is resized.
+	 */
 	handleResize() {
 
 		if ( this.domElement === document ) {
@@ -124,6 +225,14 @@ class FirstPersonControls extends Controls {
 
 	}
 
+	/**
+	 * Rotates the camera towards the defined target position.
+	 *
+	 * @param {number|Vector3} x - The x coordinate of the target position or alternatively a vector representing the target position.
+	 * @param {number} y - The y coordinate of the target position.
+	 * @param {number} z - The z coordinate of the target position.
+	 * @return {FirstPersonControls} A reference to this controls.
+	 */
 	lookAt( x, y, z ) {
 
 		if ( x.isVector3 ) {

package/examples/jsm/controls/FlyControls.js

@@ -4,21 +4,66 @@ import {
 	Vector3
 } from 'three';
 
+/**
+ * Fires when the camera has been transformed by the controls.
+ *
+ * @event FlyControls#change
+ * @type {Object}
+ */
 const _changeEvent = { type: 'change' };
 
 const _EPS = 0.000001;
 const _tmpQuaternion = new Quaternion();
 
+/**
+ * This class enables a navigation similar to fly modes in DCC tools like Blender.
+ * You can arbitrarily transform the camera in 3D space without any limitations
+ * (e.g. focus on a specific target).
+ *
+ * @augments Controls
+ */
 class FlyControls 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 );
 
+		/**
+		 * The movement speed.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.movementSpeed = 1.0;
+
+		/**
+		 * The rotation speed.
+		 *
+		 * @type {number}
+		 * @default 0.005
+		 */
 		this.rollSpeed = 0.005;
 
+		/**
+		 * If set to `true`, you can only look around by performing a drag interaction.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.dragToLook = false;
+
+		/**
+		 * If set to `true`, the camera automatically moves forward (and does not stop) when initially translated.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.autoForward = false;
 
 		// internals
@@ -44,13 +89,15 @@ class FlyControls extends Controls {
 
 		if ( domElement !== null ) {
 
-			this.connect();
+			this.connect( domElement );
 
 		}
 
 	}
 
-	connect() {
+	connect( element ) {
+
+		super.connect( element );
 
 		window.addEventListener( 'keydown', this._onKeyDown );
 		window.addEventListener( 'keyup', this._onKeyUp );

package/examples/jsm/controls/MapControls.js

@@ -2,23 +2,56 @@ import { MOUSE, TOUCH } from 'three';
 
 import { OrbitControls } from './OrbitControls.js';
 
-// MapControls performs orbiting, dollying (zooming), and panning.
-// Unlike TrackballControls, it maintains the "up" direction object.up (+Y by default).
-//
-//    Orbit - right mouse, or left mouse + ctrl/meta/shiftKey / touch: two-finger rotate
-//    Zoom - middle mouse, or mousewheel / touch: two-finger spread or squish
-//    Pan - left mouse, or arrow keys / touch: one-finger move
-
+/**
+ * This class is intended for transforming a camera over a map from bird's eye perspective.
+ * The class shares its implementation with {@link OrbitControls} but uses a specific preset
+ * for mouse/touch interaction and disables screen space panning by default.
+ *
+ * - Orbit: Right mouse, or left mouse + ctrl/meta/shiftKey / touch: two-finger rotate.
+ * - Zoom: Middle mouse, or mousewheel / touch: two-finger spread or squish.
+ * - Pan: Left mouse, or arrow keys / touch: one-finger move.
+ *
+ * @augments OrbitControls
+ */
 class MapControls extends OrbitControls {
 
 	constructor( object, domElement ) {
 
 		super( object, domElement );
 
-		this.screenSpacePanning = false; // pan orthogonal to world-space direction camera.up
-
+		/**
+		 * Overwritten and set to `false` to pan orthogonal to world-space direction `camera.up`.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.screenSpacePanning = false;
+
+		/**
+		 * This object contains references to the mouse actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	LEFT: THREE.MOUSE.PAN,
+		 * 	MIDDLE: THREE.MOUSE.DOLLY,
+		 * 	RIGHT: THREE.MOUSE.ROTATE
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.mouseButtons = { LEFT: MOUSE.PAN, MIDDLE: MOUSE.DOLLY, RIGHT: MOUSE.ROTATE };
 
+		/**
+		 * This object contains references to the touch actions used by the controls.
+		 *
+		 * ```js
+		 * controls.mouseButtons = {
+		 * 	ONE: THREE.TOUCH.PAN,
+		 * 	TWO: THREE.TOUCH.DOLLY_ROTATE
+		 * }
+		 * ```
+		 * @type {Object}
+		 */
 		this.touches = { ONE: TOUCH.PAN, TWO: TOUCH.DOLLY_ROTATE };
 
 	}