@combeenation/3d-viewer 4.0.0-beta1 → 4.0.0-beta2

package/src/api/util/globalTypes.ts

@@ -8,7 +8,6 @@ type VariantInstance = import("../classes/variantInstance").VariantInstance;
  */
 type VariantElement = import("../classes/element").Element;
 type DottedPath = import("../classes/dottedPath").DottedPath;
-type ViewerLight = import("../classes/viewerLight").ViewerLight;
 
 // global accessible types imported from BabylonJS
 type Scene = import("@babylonjs/core/scene").Scene;
@@ -69,10 +68,6 @@ type Asset = {
 	fileName: string | undefined
 };
 
-type ElementDefinitions = {
-	[name: string]: ElementDefinition | string[]
-};
-
 type ElementDefinition = {
 	paths: PathDefinitions,
 	traceables?: TraceableDefinitions,
@@ -97,9 +92,9 @@ type StructureJson = {
 	glTF?: Asset | string,
 	parameterDeclaration?: ParameterDeclarations,
 	parameters?: ParameterBag,
-	elements?: ElementDefinitions,
-	lights?: LightDefinitions,
-	grounds?: GroundDefinitions,
+	elements?: {
+		[name: string]: ElementDefinition | string[]
+	},
 	/**
 	 * `variants` is a declarative description of 3D-model variations in the configurator. Each variant itself is a
 	 * {@link StructureJson} which must at least define a `name` in the key of the list and the properties `glTF` and
@@ -128,7 +123,7 @@ type StructureJson = {
 	 */
 	variants?: {
 		[id: string]: StructureJson,
-	},
+	}
 };
 
 type SceneJson = {
@@ -149,7 +144,8 @@ type SceneJson = {
 
 type SceneDefinition = {
 	globals: SceneGlobals,
-	cameras?: CameraDefinitions,
+	lights?: LightDefinitions,
+	cameras?: CameraDefinitions
 };
 
 type SceneGlobals = {
@@ -193,29 +189,12 @@ type SceneGlobals = {
 	}
 };
 
-/**
- * {@link Viewer.screenshot} internally uses Babylons [ScreenshotTools.CreateScreenshotUsingRenderTarget](https://doc.babylonjs.com/typedoc/classes/babylon.screenshottools#createscreenshotusingrendertarget). \
- * See this link for additional info about the properties.
- */
 type ScreenshotSettings = {
-	/** Defaults to canvas width & height */
 	size?: IScreenshotSize,
-	/**
-	 * Default `image/png`
-	 * 
-	 * **Info regarding JPEG:** \
-	 * Use mimeType `image/jpeg` (**not** `image/jpg`) when creating jpeg's. \
-	 * Also ensure that {@link Scene.clearColor | viewer.scene.clearColor} has an alpha value of `1` as jpeg's don't support
-	 * transparency. Otherwise background will always be black for jpeg's.
-	 */
 	mimeType?: string,
-	/** Default `1` */
 	samples?: number,
-	/** Default `false` */
 	antialiasing?: boolean,
-	/** Default `screenshot.png` */
 	fileName?: string,
-	/** Default `false` */
 	renderSprites?: boolean
 };
 
@@ -231,40 +210,11 @@ type AutofocusSettings = {
 };
 
 type LightDefinitions = {
-	[name: string]: LightDefinition | string
+	[light: string]: LightDefinition
 };
 
 type LightDefinition = {
-	type: 'baked' | 'hemispheric' | 'point' | 'directional' | 'spot',
-	path?: string,
-	shadowGenerator?: ShadowGeneratorDefinition
-};
-
-type ShadowGeneratorDefinition = {
-	mapSize: number
-	[others: string]: any,
-	/**
-	 * Further properties like `usePoissonSampling` are set directly on the ShadowGenerator object.
-	 * [Shadows](https://doc.babylonjs.com/divingDeeper/lights/shadows)
-	 */
-};
-
-type GroundDefinitions = {
-	[ground: string]: GroundDefinition
-};
-
-type GroundDefinition = {
-	type: 'baked' | 'ground' | 'heightmap',
-	meshId?: string,
-	url?: string,
-	width?: number,
-	height?: number,
-	subdivisions?: number,
-	receiveShadows?: boolean,
-	minHeight?: number,
-	maxHeight?: number,
-	alphaFilter?: number,
-	onReady?: any
+	type: 'hemispheric' | 'point'
 };
 
 type CameraDefinitions = {
@@ -280,6 +230,10 @@ type CameraDefinition = {
 	/**
 	 * `arc` is a default camera position where the 3D-model is the center and the camera rotates around the 3D-model.
 	 * More Information about `arc` in [ArcRotateCamera](https://doc.babylonjs.com/typedoc/classes/babylon.arcrotatecamera).
+	 * 
+	 * NOTE: While "baked" camera definitions from a GLB or babylon file can currently not be instatiated within the `Specification`, it's still possible to use them in the viewer.\
+	 * For the moment all camera definitions inside these files are automatically added to the scene and can be actived using the {@link switchCamera} function.\
+	 * The `newCamera` input has to match the name of the camera node inside the GLB/babylon file.
 	 */
 	type: 'arc'
 	/**
@@ -304,8 +258,7 @@ type ParameterDeclarations = {
 };
 
 type ParameterDeclaration = {
-	type: 'string' | 'boolean' | 'number' | 'color' | 'select' | 'vector' | 'csl',
-	parser?: any,
+	type: 'string' | 'boolean' | 'number' | 'color' | 'select' | 'vector',
 	options?: ParameterValue[]
 };
 
@@ -315,10 +268,6 @@ type ParameterBag = {
 	[name: string]: ParameterValue
 };
 
-type ParsedParameterBag = {
-	[name: string]: any
-};
-
 type DottedPathArgument = string | string[] | DottedPath;
 
 type ParameterObserver = (
@@ -350,12 +299,6 @@ type AnimationDefinitions = {
  * liking and simply copy the `ease` function shown at the bottom of the visualizer into the `ease` property of your
  * {@link AnimationDefinition}.
  * 
- * The `GSAPTWeenVars` are extended by the `shortestWay` property.\
- * This property defines if the camera should move to the target position within the shortest possible distance.\
- * If `shortestWay` is `false`, the camera moves the whole difference between the current camera position and the target position
- * and that could be > 360, which can appear very unconvenient to the operator.\
- * The default value of this flag is `true`.
- * 
  * Example usage in {@link SceneJson | SceneJson.animations}:
  * 
  * ```js
@@ -373,4 +316,4 @@ type AnimationDefinitions = {
  * // ...
  * ```
  */
-type AnimationDefinition = GSAPTweenVars & { shortestWay?: boolean }
+type AnimationDefinition = GSAPTweenVars;

package/src/api/util/resourceHelper.ts

@@ -1,10 +1,5 @@
 import { emitter, Event } from '../classes/event';
 
-/**
- * Sleeps for a certain amount of microseconds.
- */
-const sleep = ( ms: number ) => new Promise( resolve => window.setTimeout( resolve, ms ) );
-
 /**
  * Loads any kind of response from given path.
  * @emits {@link Event.LOADING_START}
@@ -61,6 +56,16 @@ const debounce = function( func: Function, wait: number, immediate: boolean = fa
 	};
 };
 
+/**
+ * Creates a random uuidv4.
+ */
+const uuidv4 = function() {
+	// @ts-ignore
+	return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace( /[018]/g, c =>
+		(c ^ crypto.getRandomValues( new Uint8Array( 1 ) )[0] & 15 >> c / 4).toString( 16 )
+	);
+};
+
 /**
  * Merges multiple maps.
  */
@@ -75,31 +80,19 @@ const mergeMaps = function <TKey, TValue>( ...maps: Map<TKey, TValue>[] ): Map<T
 };
 
 /**
- * Creates an `ImageBitmap` from a SVG string using native `createImageBitmap` functionality.
+ * Converts a svg string into an URL with a base64 representation of that image.\
+ * This URL can be used as the basis of a paintable texture.
  */
-const createImageBitmapFromSvg = async function( svgSrc: string ): Promise<ImageBitmap> {
-	return new Promise( async resolve => {
-		const svgWithAssetsEmbedded = await _embedAssets( svgSrc );
-		const svgBlob = new Blob( [svgWithAssetsEmbedded], { type: 'image/svg+xml;charset=utf-8' } );
-		const svgBase64 = URL.createObjectURL( svgBlob );
-		let img = new Image();
-		img.onload = async () => {
-			const imgBitmap = await createImageBitmap( img );
-			resolve( imgBitmap );
-		};
-		img.src = svgBase64;
-	} );
-};
+const createImageUrlFromSvg = async function( svgSrc: string ): Promise<string> {
+	// replace assets with their base64 versions in svg source code 
+	const svgWithAssetsEmbedded = await _embedAssets( svgSrc );
 
-const createImageBitmapFromImgSrc = async function( imgSrc: string ): Promise<ImageBitmap> {
-	const img = new Image();
-	img.src = imgSrc;
-	return new Promise( resolve => {
-		img.onload = async () => {
-			const imgBitmap = await createImageBitmap( img );
-			resolve( imgBitmap );
-		};
-	} );
+	// create blob from that
+	const svgBlob = new Blob( [svgWithAssetsEmbedded], { type: 'image/svg+xml' } );
+
+	// create URL that can be used in HTML (?)
+	const imgUrl = URL.createObjectURL( svgBlob );
+	return imgUrl;
 };
 
 /**
@@ -154,11 +147,10 @@ const _fetchBase64AssetUrl = async function( assetUrl: string ): Promise<{ url:
 };
 
 export {
-	sleep,
 	loadJson,
 	loadText,
 	debounce,
+	uuidv4,
 	mergeMaps,
-	createImageBitmapFromSvg,
-	createImageBitmapFromImgSrc
+	createImageUrlFromSvg
 };

package/src/dev.ts

@@ -4,8 +4,10 @@ import { set } from 'lodash-es';
 
 import { Emitter, Viewer } from '.';
 
-import { createSpec, beforeBootstrap, afterBootstrap, createUIelements } from '../assets/CB-6062-async-check/main';
-
+/**
+ * (i) HERE YOU @TODO (1) ADJUST THE CURRENT DEMO YOU ARE WORKING ON.
+ */
+import { createSpec, beforeBootstrap, afterBootstrap, createUIelements } from '../assets/hulahoop/main';
 const loadingElement = document.getElementById( 'loading' ) as HTMLDivElement;
 
 Emitter.on( Event.BOOTSTRAP_START, () => {
@@ -39,5 +41,7 @@ async function bootstrapViewer() {
 	}
 	await afterBootstrap( viewer );
 	await createUIelements( viewer );
+	console.info( ' --- UI Initialized ---');
+
 	return viewer;
 }

package/src/index.ts

@@ -1,50 +1,48 @@
 /// <reference path="api/util/globalTypes.ts" />
 
-import { Animation as BabylonAnimation } from '@babylonjs/core/Animations/animation';
 import { ArcRotateCamera } from '@babylonjs/core/Cameras/arcRotateCamera';
 import { Engine } from '@babylonjs/core/Engines/engine';
-import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight';
-import { HemisphericLight } from '@babylonjs/core/Lights/hemisphericLight';
 import { Material } from '@babylonjs/core/Materials/material';
 import { PBRMaterial } from '@babylonjs/core/Materials/PBR/pbrMaterial';
 import { StandardMaterial } from '@babylonjs/core/Materials/standardMaterial';
-import { CubeTexture } from '@babylonjs/core/Materials/Textures/cubeTexture';
 import { DynamicTexture } from '@babylonjs/core/Materials/Textures/dynamicTexture';
-import { Texture } from '@babylonjs/core/Materials/Textures/texture';
 import { Color3, Color4 } from '@babylonjs/core/Maths/math.color';
 import { Vector3 } from '@babylonjs/core/Maths/math.vector';
 import { AbstractMesh } from '@babylonjs/core/Meshes/abstractMesh';
 import { InstancedMesh } from '@babylonjs/core/Meshes/instancedMesh';
 import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder';
 import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
 import { Node } from '@babylonjs/core/node';
-
-/**
- * Without explicitly importing the "BoundingBoxRenderer", we're getting "scene.getBoundingBoxRenderer is undefined"
- * errors when creating HighlightLayer instances. Not sure why but those errors only happen when using the built
- * version of the viewer (e.g. when pulling it from NPM etc.)...
- */
-import '@babylonjs/core/Rendering/boundingBoxRenderer';
 import { Scene } from '@babylonjs/core/scene';
-import { Parameterizable } from './api/classes/parameterizable';
-import { VariantParameterizable } from './api/classes/variantParameterizable';
+import { VariantInstance } from './api/classes/variantInstance';
+import { Viewer } from './api/classes/viewer';
+import { Event, emitter } from './api/classes/event';
 import { EventEmitter } from 'eventemitter3';
-import { Element } from './api/classes/element';
-import { emitter, Event } from './api/classes/event';
-import { EventBroadcaster } from './api/classes/eventBroadcaster';
 import { Parameter } from './api/classes/parameter';
-import { ParameterObservable } from './api/classes/parameterObservable';
-import { PlacementAnimation } from './api/classes/placementAnimation';
+import { CubeTexture } from '@babylonjs/core/Materials/Textures/cubeTexture';
+import { Animation as BabylonAnimation } from '@babylonjs/core/Animations/animation';
+import { MeshBuilder } from '@babylonjs/core/Meshes/meshBuilder';
+import { Texture } from '@babylonjs/core/Materials/Textures/texture';
+import { DirectionalLight } from '@babylonjs/core/Lights/directionalLight';
+import { HemisphericLight } from '@babylonjs/core/Lights/hemisphericLight';
 import { Variant } from './api/classes/variant';
-import { VariantInstance } from './api/classes/variantInstance';
-import { Viewer } from './api/classes/viewer';
-import { ViewerLight } from './api/classes/viewerLight';
+import { ParameterObservable } from './api/classes/parameterObservable';
+import { ElementParameterizable } from './api/classes/elementParameterizable';
+import { Element } from './api/classes/element';
+import { VariantInstanceManager } from './api/manager/variantInstanceManager';
 import { AnimationManager } from './api/manager/animationManager';
+import { EventBroadcaster } from './api/classes/eventBroadcaster';
 import { SceneManager } from './api/manager/sceneManager';
-import { VariantInstanceManager } from './api/manager/variantInstanceManager';
+import { PlacementAnimation } from './api/classes/placementAnimation';
 import * as BabylonHelper from './api/util/babylonHelper';
 
+/**
+ * Without explicitly importing the "BoundingBoxRenderer", we're getting "scene.getBoundingBoxRenderer is undefined"
+ * errors when creating HighlightLayer instances. Not sure why but those errors only happen when using the built
+ * version of the viewer (e.g. when pulling it from NPM etc.)...
+ */
+import '@babylonjs/core/Rendering/boundingBoxRenderer';
+
 /**
  * Expose some frequently used babylon modules by our consumers.
  */
@@ -54,9 +52,7 @@ export {
 	VariantInstanceManager,
 	Viewer,
 	ParameterObservable,
-	Parameterizable,
-	VariantParameterizable,
-	ViewerLight,
+	ElementParameterizable,
 	emitter as Emitter,
 	EventEmitter,
 	Event,

package/src/pagesconfig.json

@@ -32,21 +32,26 @@
       "pages": [
         {
           "title": "Specification",
-          "source": "./doc/Specification.md"
+          "source": "./doc/documentation/Specification.md"
         },
         {
           "title": "Parameters",
-          "source": "./doc/Parameters.md"
-        },
-        {
-          "title": "ViewerLights",
-          "source": "./doc/ViewerLights.md"
+          "source": "./doc/documentation/Parameters.md"
         },
         {
           "title": "Paintables",
-          "source": "./doc/Paintables.md"
+          "source": "./doc/documentation/Paintables.md"
+        }
+      ]
+    },
+    {
+      "title": "Best Practice",
+      "pages": [
+        {
+          "title": "How to change custom material properties",
+          "source": "./doc/best-practice/Custom-material-properties.md"
         }
       ]
     }
   ]
-}
+}

package/src/api/classes/variantParameterizable.ts

@@ -1,73 +0,0 @@
-import { DottedPath } from './../classes/dottedPath';
-import { Event } from './../classes/event';
-import { Parameterizable } from './../classes/parameterizable';
-import { Variant } from './../classes/variant';
-import { mergeMaps } from './../util/resourceHelper';
-import { camelToSnakeCase } from './../util/stringHelper';
-import { cloneDeep, concat, get, merge } from 'lodash-es';
-
-export abstract class VariantParameterizable extends Parameterizable {
-
-	protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
-
-	protected constructor( public readonly variant: Variant,
-	                       public readonly name: string ) {
-		super();
-	}
-
-	/**
-	 * Gets the inherited parameters from the {@link Variant} with cleaned {@link Parameterizable} prefix.
-	 */
-	get inheritedParameters(): ParameterBag {
-		const parameterBag: ParameterBag = {};
-		for( const parameter in this.variant.inheritedParameters ) {
-			const dpp = DottedPath.create( parameter );
-			if( dpp.firstPart !== this.name ) {
-				continue;
-			}
-			dpp.shiftPart();
-			parameterBag[dpp.path] = this.variant.inheritedParameters[parameter];
-		}
-		return parameterBag;
-	}
-
-	/**
-	 * Places the given {@link ParameterBag} in the {@link VariantParameterizable}'s parameters, replaces all patterns in the
-	 * {@link StructureJson} and broadcasts all {@link ParameterObserver}s.
-	 */
-	public async commitParameters( parameters?: ParameterBag ): Promise<VariantParameterizable> {
-		if( !parameters ) {
-			parameters = {};
-		}
-		const oldParameters = cloneDeep( this.parameters );
-		merge( this.parameters, parameters );
-		// handle parameter observers
-		let observerPromises: Promise<void | ParameterObserver>[] = [];
-		for( const parameter in this.parameters ) {
-			const oldParameterValue = oldParameters[parameter];
-			const newParameterValue = this.parameters[parameter];
-			this.variant.assertParameter( this.variant.inheritedParameterDeclaration, parameter, newParameterValue );
-			if( oldParameterValue === newParameterValue ) {
-				continue;
-			}
-			// parameter changed
-			const parameterObservers = mergeMaps( this._parameterObservers, this.parameterObservers );
-			if( parameterObservers.has( parameter ) ) {
-				const observers = parameterObservers.get( parameter )!;
-				observerPromises = concat( observerPromises, observers.map( observer => {
-					const observerResult = observer( this, oldParameterValue, newParameterValue );
-					const observerPromise = Promise.resolve( observerResult );
-					observerPromise.then( () => {
-						const clsName = camelToSnakeCase( this.constructor.name ).toUpperCase();
-						this.broadcastEvent( get( Event, clsName + '_PARAMETER_COMMITTED' ),
-							this, parameter, oldParameterValue, newParameterValue );
-					} );
-					return observerPromise;
-				} ) );
-			}
-		}
-		await Promise.all( observerPromises );
-		return this;
-	}
-
-}