easy-three-utils 0.0.1

package/src/tileRenderer/plugins/three/objects/EllipsoidRegionHelper.js

@@ -0,0 +1,186 @@
+import { EllipsoidRegion } from '../../../three/math/EllipsoidRegion.js';
+import { Mesh, Vector3, MathUtils, BoxGeometry, BufferGeometry, EdgesGeometry, LineSegments, BufferAttribute } from 'three';
+
+const _norm = new Vector3();
+const _norm2 = new Vector3();
+const _pos = new Vector3();
+const _vec1 = new Vector3();
+const _vec2 = new Vector3();
+
+// Converts a geometry with a given set of groups rendering a smaller set of
+// geometry into a new one with only the relevant triangles.
+function toGroupGeometry( geometry ) {
+
+	// non indexed makes this process easier
+	geometry = geometry.toNonIndexed();
+
+	// prep the arrays
+	const { groups } = geometry;
+	const { position, normal } = geometry.attributes;
+	const newNorm = [];
+	const newPos = [];
+
+	// add the normals and the positions
+	for ( const group of groups ) {
+
+		const { start, count } = group;
+		for ( let i = start, l = ( start + count ); i < l; i ++ ) {
+
+			_vec1.fromBufferAttribute( position, i );
+			_vec2.fromBufferAttribute( normal, i );
+
+			newPos.push( ..._vec1 );
+			newNorm.push( ..._vec2 );
+
+		}
+
+	}
+
+	// set the new geometry
+	const newGeometry = new BufferGeometry();
+	newGeometry.setAttribute( 'position', new BufferAttribute( new Float32Array( newPos ), 3 ) );
+	newGeometry.setAttribute( 'normal', new BufferAttribute( new Float32Array( newNorm ), 3 ) );
+
+	return newGeometry;
+
+}
+
+function getRegionGeometry( ellipsoidRegion ) {
+
+	// retrieve the relevant fields
+	const {
+		latStart = - Math.PI / 2, latEnd = Math.PI / 2,
+		lonStart = 0, lonEnd = 2 * Math.PI,
+		heightStart = 0, heightEnd = 0,
+	} = ellipsoidRegion;
+
+	// get the attributes
+	const geometry = new BoxGeometry( 1, 1, 1, 32, 32 );
+	const { normal, position } = geometry.attributes;
+
+	// clone the position buffer so we can reference it for normal calculations later
+	const refPosition = position.clone();
+
+	// perturb the position buffer into an ellipsoid region
+	for ( let i = 0, l = position.count; i < l; i ++ ) {
+
+		_pos.fromBufferAttribute( position, i );
+
+		const lat = MathUtils.mapLinear( _pos.x, - 0.5, 0.5, latStart, latEnd );
+		const lon = MathUtils.mapLinear( _pos.y, - 0.5, 0.5, lonStart, lonEnd );
+
+		let height = heightStart;
+		ellipsoidRegion.getCartographicToNormal( lat, lon, _norm );
+		if ( _pos.z < 0 ) {
+
+			height = heightEnd;
+
+		}
+		ellipsoidRegion.getCartographicToPosition( lat, lon, height, _pos );
+		position.setXYZ( i, ..._pos );
+
+	}
+
+	// compute the vertex normals so we can get the edge normals
+	geometry.computeVertexNormals();
+
+	// compute the top and bottom cap normals
+	for ( let i = 0, l = refPosition.count; i < l; i ++ ) {
+
+		_pos.fromBufferAttribute( refPosition, i );
+
+		const lat = MathUtils.mapLinear( _pos.x, - 0.5, 0.5, latStart, latEnd );
+		const lon = MathUtils.mapLinear( _pos.y, - 0.5, 0.5, lonStart, lonEnd );
+
+		_norm.fromBufferAttribute( normal, i );
+		ellipsoidRegion.getCartographicToNormal( lat, lon, _norm2 );
+
+		// exclude the sides so we get sharp corners
+		if ( Math.abs( _norm.dot( _norm2 ) ) > 0.1 ) {
+
+			if ( _pos.z > 0 ) {
+
+				_norm2.multiplyScalar( - 1 );
+
+			}
+
+			normal.setXYZ( i, ..._norm2 );
+
+		}
+
+	}
+
+	return geometry;
+
+}
+
+export class EllipsoidRegionLineHelper extends LineSegments {
+
+	constructor( ellipsoidRegion = new EllipsoidRegion(), color = 0xffff00 ) {
+
+		super();
+		this.ellipsoidRegion = ellipsoidRegion;
+		this.material.color.set( color );
+		this.update();
+
+	}
+
+	update() {
+
+		const geometry = getRegionGeometry( this.ellipsoidRegion );
+		this.geometry.dispose();
+		this.geometry = new EdgesGeometry( geometry, 80 );
+
+	}
+
+	dispose() {
+
+		this.geometry.dispose();
+		this.material.dispose();
+
+	}
+
+}
+
+export class EllipsoidRegionHelper extends Mesh {
+
+	constructor( ellipsoidRegion = new EllipsoidRegion(), color = 0xffff00 ) {
+
+		super();
+		this.ellipsoidRegion = ellipsoidRegion;
+		this.material.color.set( color );
+		this.update();
+
+	}
+
+	update() {
+
+		// dispose of the existing geometry
+		this.geometry.dispose();
+
+		// retrieve the relevant fields
+		const geometry = getRegionGeometry( this.ellipsoidRegion );
+		const { lonStart, lonEnd } = this;
+
+		// exclude the side tris if the region wraps around
+		if ( lonEnd - lonStart >= 2 * Math.PI ) {
+
+			geometry.groups.splice( 2, 2 );
+			this.geometry = toGroupGeometry( geometry );
+
+		} else {
+
+			this.geometry = geometry;
+
+		}
+
+	}
+
+	dispose() {
+
+		this.geometry.dispose();
+		this.material.dispose();
+
+	}
+
+}

package/src/tileRenderer/plugins/three/objects/SphereHelper.js

@@ -0,0 +1,55 @@
+import { LineSegments, BufferGeometry, Vector3, BufferAttribute, LineBasicMaterial } from 'three';
+
+const _vector = new Vector3();
+const axes = [ 'x', 'y', 'z' ];
+export class SphereHelper extends LineSegments {
+
+	constructor( sphere, color = 0xffff00, angleSteps = 40 ) {
+
+		const geometry = new BufferGeometry();
+		const positions = [];
+		for ( let i = 0; i < 3; i ++ ) {
+
+			const axis1 = axes[ i ];
+			const axis2 = axes[ ( i + 1 ) % 3 ];
+			_vector.set( 0, 0, 0 );
+
+			for ( let a = 0; a < angleSteps; a ++ ) {
+
+				let angle;
+				angle = 2 * Math.PI * a / ( angleSteps - 1 );
+				_vector[ axis1 ] = Math.sin( angle );
+				_vector[ axis2 ] = Math.cos( angle );
+
+				positions.push( _vector.x, _vector.y, _vector.z );
+
+				angle = 2 * Math.PI * ( a + 1 ) / ( angleSteps - 1 );
+				_vector[ axis1 ] = Math.sin( angle );
+				_vector[ axis2 ] = Math.cos( angle );
+
+				positions.push( _vector.x, _vector.y, _vector.z );
+
+			}
+
+
+		}
+
+		geometry.setAttribute( 'position', new BufferAttribute( new Float32Array( positions ), 3 ) );
+		geometry.computeBoundingSphere();
+
+		super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
+		this.sphere = sphere;
+		this.type = 'SphereHelper';
+
+	}
+
+	updateMatrixWorld( force ) {
+
+		const sphere = this.sphere;
+		this.position.copy( sphere.center );
+		this.scale.setScalar( sphere.radius );
+		super.updateMatrixWorld( force );
+
+	}
+
+}

package/src/tileRenderer/r3f/README.md

@@ -0,0 +1,238 @@
+# 3D Tiles React Components
+
+Set of components for loading and rendering 3D Tiles in [@react-three/fiber](https://r3f.docs.pmnd.rs/).
+
+**Examples**
+
+[Basic example](https://nasa-ammos.github.io/3DTilesRendererJS/example/bundle/r3f/basic.html)
+
+[Cesium Ion example](https://nasa-ammos.github.io/3DTilesRendererJS/example/bundle/r3f/ion.html)
+
+[Google Photorealistic Tiles example](https://nasa-ammos.github.io/3DTilesRendererJS/example/bundle/r3f/globe.html)
+
+# Use
+
+## Simple
+
+```jsx
+import { TilesRenderer } from '3d-tiles-renderer/r3f';
+
+const TILESET_URL = /* your tile set url */;
+const cameraPosition = [ x, y, z ]; // Set the camera position so the tiles are visible
+export default function App() {
+  return (
+    <Canvas camera={ { position: cameraPosition } }>
+      <TilesRenderer url={ TILESET_URL } />
+    </Canvas>
+  );
+}
+```
+
+## With Plugins, Controls, & Attribution
+
+Basic set up for Google Photorealistic tiles, Globe controls, and an overlay for displaying data set attributions.
+
+```jsx
+import { TilesRenderer, TilesPlugin, GlobeControls, TilesAttributionOverlay } from '3d-tiles-renderer/r3f';
+import { DebugTilesPlugin, GoogleCloudAuthPlugin } from '3d-tiles-renderer';
+
+export default function App() {
+  return (
+    <Canvas camera={ { position: [ 0, 0, 1e8 ] } }>
+      <TilesRenderer>
+        <TilesPlugin plugin={ DebugTilesPlugin } displayBoxBounds={ true } />
+        <TilesPlugin plugin={ GoogleCloudAuthPlugin } args={ { apiToken: /* your api token here */ } } />
+        <GlobeControls />
+        <TilesAttributionOverlay />
+      </TilesRenderer>
+    </Canvas>
+  );
+}
+```
+
+## Cesium Ion & Google Cloud
+
+Simplified wrappers for using the TilesRenderer with Cesium Ion and Google Cloud for Photorealistic Tiles. Use the `TilesAttributionOverlay` to display appropriate credits for the data sets.
+
+```jsx
+import { TilesRenderer, TilesPlugin } from '3d-tiles-renderer/r3f';
+import { CesiumIonAuthPlugin, GoogleCloudAuthPlugin } from '3d-tiles-renderer';
+
+function GoogleTilesRenderer( { children, apiToken, ...rest } ) {
+  return (
+    <TilesRenderer { ...rest } key={ apiToken }>
+      <TilesPlugin plugin={ GoogleCloudAuthPlugin } args={ { apiToken } } />
+      { children }
+    </TilesRenderer>
+  );
+}
+
+function CesiumIonTilesRenderer( { children, apiToken, assetId, ...rest } ) {
+  return (
+    <TilesRenderer { ...rest } key={ apiToken + assetId }>
+      <TilesPlugin plugin={ CesiumIonAuthPlugin } args={ { apiToken, assetId } } />
+      { children }
+    </TilesRenderer>
+  );
+}
+```
+
+# Components
+
+## TilesRenderer
+
+Wrapper for the three.js `TilesRenderer` class. Listening for events are specified with a camel-case property prefixed with `on`, such as `onModelLoad`, and all other properties are specified as individual properties with dashes being used to indicate nested properties. For example, `lruCache-minSize` is used to set `lruCache.minSize`.
+
+```jsx
+<TilesRenderer
+  url={ tilesetUrl }
+
+	// pass properties to apply to the tile set root object
+	group={ {
+		position: [ 0, 10, 0 ],
+		rotation: [ Math.PI / 2, 0, 0 ],
+	} }
+
+  // set options to the TilesRenderer object
+  errorTarget={ 6 }
+  errorThreshold={ 10 }
+
+  // set nested object options of the TilesRenderer
+  parseQueue-maxJobs={ 30 }
+  downloadQueue-maxJobs={ 10 }
+  lruCache-minBytesSize={ 0.25 * 1e6 }
+  lruCache-maxBytesSize={ 0.5 * 1e6 }
+
+  // event registration
+  onTileSetLoad={ onTileSetLoadCallback }
+  onModelLoad={ onModelLoadCallback }
+/>
+```
+
+## TilesPlugin
+
+Plugins can be set as children of the TilesRenderer component to add additional functionality. TilePlugin components must be nested inside a TilesRenderer component. Constructor arguments are passed via the `args` parameter while local members can be passed via the regular properties. But note that depending on the plugin some properties cannot be changed after construction and initialization.
+
+See the [PLUGINS documentation](https://github.com/NASA-AMMOS/3DTilesRendererJS/blob/master/PLUGINS.md) for docs on all avilable plugins.
+
+```jsx
+<TilesRenderer url={ tilesetUrl }>
+  <TilesPlugin
+    plugin={ PluginClassName }
+    args={ /* constructor arguments as array or object */ }
+    { ...pluginProps }
+  />
+</TilesRenderer>
+```
+
+And a practical example of creating and using a plugin:
+
+```jsx
+<TilesRenderer url={ tilesetUrl } >
+  <TilesPlugin plugin={ GLTFExtensionsPlugin }
+    dracoLoader={ dracoLoader }
+    ktxLoader={ ktx2Loader }
+    autoDispose={ false }
+    { /*
+      // alternatively the options can be passed via constructor arguments
+      // or a mix of both can be used.
+      args = { {
+        dracoLoader,
+        ktxLoader,
+        autoDispose: false,
+      } }
+    */ }
+  />
+</TilesRenderer>
+```
+
+## Controls
+
+These `EnvironmentControls` and `GlobeControls` classes have been wrapped as components to handle user-interaction. They will both be set to the `controls` react three fiber state field when in use. All properties on the original classes can be passed as properties:
+
+```jsx
+<>
+  <TilesRenderer url={ url } { ...props } />
+  <EnvironmentControls enableDamping={ true } enabled={ true } />
+</>
+```
+
+The `GlobeControls` component must be set as a child of the `TilesRenderer` component that is providing the ellipsoid to orbit around.
+
+```jsx
+<TilesRenderer url={ url } { ...props }>
+  <GlobeControls enableDamping={ true } />
+</TilesRenderer>
+```
+
+## EastNorthUpFrame
+
+The `EastNorthUpFrame` creates a root object that is centered on the provided point relative to the tile sets ellipsoid, specified via lat/lon/height and euler angle props and is used to place 3D objects relative to that point. It does not rotate the original tile set and must be a child of a `TilesRenderer` component.
+
+It can be used to place markers on the surface of the ellipsoid, such as a cone for pointing to a location:
+
+```jsx
+<TilesRenderer url={ url } { ...props }>
+  { /* ... */ }
+  <EastNorthUpFrame
+    {/* The latitude and longitude to place the frame at in radians */}
+    lat={ lat }
+    lon={ lon }
+
+    {/* The height above the ellipsoid to place the frame at in meters */}
+    height={ 100 }
+
+    {/*
+      The azimuth, elevation, and roll around the "north" axis, applied
+      in that order intrinsicly, in radians
+    */}
+    az={ 0 }
+    el={ 0 }
+    roll={ 0 }
+  >
+    {/* Children are position relative to the east, north, up frame */}
+    <mesh rotation-x={ - Math.PI / 2 } scale={ 100 } position-z={ 50 }>
+      <coneGeometry args={ [ 0.5 ] } />
+      <meshStandardMaterial color={ 'red' } />
+    </mesh>
+  </EastNorthUpFrame>
+</TilesRenderer>
+```
+
+## TilesAttributionOverlay
+
+The `TilesAttributionOverlay` component must be embedded in a tile set and will automatically display the credits associated with the loaded data set.
+
+```jsx
+<TilesRenderer url={ url } { ...props }>
+  <TilesAttributionOverlay />
+</TilesRenderer>
+```
+
+## CompassGizmo
+
+Adds a compass to the bottom right of the page that orients to "north" based on the camera position and orientation. Must be nested in a `TilesRenderer` component.
+
+Any children passed into the class will replace the default red and white compass design with +Y pointing north and +X pointing east. The graphic children should fit within a volume from - 0.5 to 0.5 along all axes.
+
+```jsx
+<CompassGizmo
+	{/* Specifies whether the compass will render in '2d' or '3d' */}
+	mode={ '3d' }
+
+	{/* The size of the compass in pixels */}
+	scale={ 35 }
+
+	{/* The number pixels in margin to add relative to the bottom right of the screen */}
+	margin={ 10 }
+
+	{/* Whether to render the main scene */}
+	overrideRenderLoop={ true }
+
+	{/* Whether the gizmo is visible and rendering */}
+	visible={ true }
+
+	{/* Any remaining props including click events are passed through to the parent group */}
+	onClick={ () => console.log( 'compass clicked!' ) }
+/>
+```

package/src/tileRenderer/r3f/components/CameraControls.jsx

@@ -0,0 +1,132 @@
+import { forwardRef, useMemo, useEffect, useContext } from 'react';
+import { useThree, useFrame } from '@react-three/fiber';
+import { EnvironmentControls as EnvironmentControlsImpl } from '../../three/controls/EnvironmentControls.js';
+import { GlobeControls as GlobeControlsImpl } from '../../three/controls/GlobeControls.js';
+import { useShallowOptions } from '../utilities/useOptions.jsx';
+import { TilesRendererContext } from './TilesRenderer.jsx';
+
+// Add a base component implementation for both EnvironmentControls and GlobeControls
+const ControlsBaseComponent = forwardRef( function ControlsBaseComponent( props, ref ) {
+
+	const { controlsConstructor, domElement, scene, camera, tilesRenderer, ...rest } = props;
+
+	const [ defaultCamera ] = useThree( state => [ state.camera ] );
+	const [ gl ] = useThree( state => [ state.gl ] );
+	const [ defaultScene ] = useThree( state => [ state.scene ] );
+	const [ invalidate ] = useThree( state => [ state.invalidate ] );
+	const [ get ] = useThree( state => [ state.get ] );
+	const [ set ] = useThree( state => [ state.set ] );
+
+	const defaultTilesRenderer = useContext( TilesRendererContext );
+	const appliedCamera = camera || defaultCamera || null;
+	const appliedScene = scene || defaultScene || null;
+	const appliedDomElement = domElement || gl.domElement || null;
+	const appliedTilesRenderer = tilesRenderer || defaultTilesRenderer || null;
+
+	// create a controls instance
+	const controls = useMemo( () => {
+
+		return new controlsConstructor();
+
+	}, [ controlsConstructor ] );
+
+	// assign / call the reference
+	useEffect( () => {
+
+		if ( ref ) {
+
+			if ( ref instanceof Function ) {
+
+				ref( controls );
+
+			} else {
+
+				ref.current = controls;
+
+			}
+
+		}
+
+	}, [ controls, ref ] );
+
+	// fire invalidate callbacks
+	useEffect( () => {
+
+		const callback = () => invalidate();
+		controls.addEventListener( 'change', callback );
+		controls.addEventListener( 'start', callback );
+		controls.addEventListener( 'end', callback );
+		return () => {
+
+			controls.removeEventListener( 'change', callback );
+			controls.removeEventListener( 'start', callback );
+			controls.removeEventListener( 'end', callback );
+
+		};
+
+	}, [ controls, invalidate ] );
+
+	// assign the camera
+	useEffect( () => {
+
+		controls.setCamera( appliedCamera );
+
+	}, [ controls, appliedCamera ] );
+
+	// assign the scene
+	useEffect( () => {
+
+		controls.setScene( appliedScene );
+
+	}, [ controls, appliedScene ] );
+
+	// assign the tiles renderer
+	useEffect( () => {
+
+		controls.setTilesRenderer( appliedTilesRenderer );
+
+	}, [ controls, appliedTilesRenderer ] );
+
+	// attach to the dom element
+	useEffect( () => {
+
+		controls.attach( appliedDomElement );
+		return () => {
+
+			controls.detach();
+
+		};
+
+	}, [ controls, appliedDomElement ] );
+
+	// set the controls for global use
+	useEffect( () => {
+
+		const old = get().controls;
+		set( { controls } );
+		return () => set( { controls: old } );
+
+	}, [ controls, get, set ] );
+
+	// update the controls with a priority of - 1 so it happens before tiles renderer update
+	useFrame( () => {
+
+		controls.update();
+
+	}, - 1 );
+
+	useShallowOptions( controls, rest );
+
+} );
+
+export function EnvironmentControls( props ) {
+
+	return <ControlsBaseComponent { ...props } controlsConstructor={ EnvironmentControlsImpl } />;
+
+}
+
+export function GlobeControls( props ) {
+
+	return <ControlsBaseComponent { ...props } controlsConstructor={ GlobeControlsImpl } />;
+
+}