@combeenation/3d-viewer 4.0.0-beta3 → 4.0.0

package/src/api/util/globalTypes.ts

@@ -8,6 +8,7 @@ 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;
@@ -68,6 +69,10 @@ type Asset = {
 	fileName: string | undefined
 };
 
+type ElementDefinitions = {
+	[name: string]: ElementDefinition | string[]
+};
+
 type ElementDefinition = {
 	paths: PathDefinitions,
 	traceables?: TraceableDefinitions,
@@ -92,9 +97,9 @@ type StructureJson = {
 	glTF?: Asset | string,
 	parameterDeclaration?: ParameterDeclarations,
 	parameters?: ParameterBag,
-	elements?: {
-		[name: string]: ElementDefinition | string[]
-	},
+	elements?: ElementDefinitions,
+	lights?: LightDefinitions,
+	grounds?: GroundDefinitions,
 	/**
 	 * `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
@@ -123,7 +128,7 @@ type StructureJson = {
 	 */
 	variants?: {
 		[id: string]: StructureJson,
-	}
+	},
 };
 
 type SceneJson = {
@@ -144,8 +149,7 @@ type SceneJson = {
 
 type SceneDefinition = {
 	globals: SceneGlobals,
-	lights?: LightDefinitions,
-	cameras?: CameraDefinitions
+	cameras?: CameraDefinitions,
 };
 
 type SceneGlobals = {
@@ -189,12 +193,29 @@ 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
 };
 
@@ -210,11 +231,40 @@ type AutofocusSettings = {
 };
 
 type LightDefinitions = {
-	[light: string]: LightDefinition
+	[name: string]: LightDefinition | string
 };
 
 type LightDefinition = {
-	type: 'hemispheric' | 'point'
+	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 CameraDefinitions = {
@@ -258,7 +308,8 @@ type ParameterDeclarations = {
 };
 
 type ParameterDeclaration = {
-	type: 'string' | 'boolean' | 'number' | 'color' | 'select' | 'vector',
+	type: 'string' | 'boolean' | 'number' | 'color' | 'select' | 'vector' | 'csl',
+	parser?: any,
 	options?: ParameterValue[]
 };
 
@@ -268,6 +319,10 @@ type ParameterBag = {
 	[name: string]: ParameterValue
 };
 
+type ParsedParameterBag = {
+	[name: string]: any
+};
+
 type DottedPathArgument = string | string[] | DottedPath;
 
 type ParameterObserver = (
@@ -299,6 +354,12 @@ 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
@@ -316,4 +377,4 @@ type AnimationDefinitions = {
  * // ...
  * ```
  */
-type AnimationDefinition = GSAPTweenVars;
+type AnimationDefinition = GSAPTweenVars & { shortestWay?: boolean }

package/src/api/util/resourceHelper.ts

@@ -1,5 +1,10 @@
 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}
@@ -56,16 +61,6 @@ 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.
  */
@@ -80,8 +75,8 @@ const mergeMaps = function <TKey, TValue>( ...maps: Map<TKey, TValue>[] ): Map<T
 };
 
 /**
- * Creates a HTML image element based on a SVG string, whereas all the embedded assets in the SVG
- * (eg: fonts, images) are already loaded and exchanged by their base64 representation.\
+ * Creates a HTML image element based on a SVG string, whereas all the embedded assets in the SVG (eg: fonts, images)
+ * are already loaded and exchanged by their base64 representation.\
  * There the output image can exist as "standalone" image and may be used for example as a paintable.
  * 
  * !!CAUTION!!: The used functions within this code section are very well evaluated since most alternatives
@@ -107,12 +102,17 @@ const createImageFromSvg = async function( svgSrc: string ): Promise<HTMLImageEl
  * - https://bugs.webkit.org/show_bug.cgi?id=39059
  * - https://bugs.webkit.org/show_bug.cgi?id=219770
  * 
- * It's not 100% ensured that the timeout solves the issue in any case, but there is no other way unfortunately.\
+ * It's not 100% ensured that the timeout solves the issue in every case, but there is no other way unfortunately.\
  * => Keep an eye on it in future projects
+ * 
+ * @param imgSrc Theoretically every source is valid which is also supported by
+ *               [HTMLImageElement.src](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/src).\
+ *               Known exceptions are SVGs with embedded assets that are provided as object URL. See comments in
+ *               {@link createImageFromSvg} for further details.
  */
-const createImageFromImgSrc = async function ( imgSrc: string ): Promise<HTMLImageElement> {
+ const createImageFromImgSrc = async function ( imgSrc: string ): Promise<HTMLImageElement> {
 	let img = new Image();
-	
+
 	await new Promise(resolve => {
 		img.onload = () => {
 			setTimeout(resolve, 0);
@@ -175,10 +175,10 @@ const _fetchBase64AssetUrl = async function( assetUrl: string ): Promise<{ url:
 };
 
 export {
+	sleep,
 	loadJson,
 	loadText,
 	debounce,
-	uuidv4,
 	mergeMaps,
 	createImageFromSvg,
 	createImageFromImgSrc

package/src/api/util/stringHelper.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 )
+	);
+};
+
+/**
+ * Converts a string from camel case to snake case.
+ */
+const camelToSnakeCase = function( str: string ): string {
+	return str
+		.replace( /([A-Z])/g, " $1" )
+		.trim()
+		.split( ' ' )
+		.join('_')
+		.toLowerCase();
+};
+
+export {
+	uuidv4,
+	camelToSnakeCase,
+};

package/src/dev.ts

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

package/src/index.ts

@@ -1,40 +1,24 @@
 /// <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';
-import { Scene } from '@babylonjs/core/scene';
-import { VariantInstance } from './api/classes/variantInstance';
-import { Viewer } from './api/classes/viewer';
-import { Event, emitter } from './api/classes/event';
-import { EventEmitter } from 'eventemitter3';
-import { Parameter } from './api/classes/parameter';
-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 { 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 { PlacementAnimation } from './api/classes/placementAnimation';
-import * as BabylonHelper from './api/util/babylonHelper';
 
 /**
  * Without explicitly importing the "BoundingBoxRenderer", we're getting "scene.getBoundingBoxRenderer is undefined"
@@ -42,6 +26,24 @@ import * as BabylonHelper from './api/util/babylonHelper';
  * 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 { 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 { Variant } from './api/classes/variant';
+import { VariantInstance } from './api/classes/variantInstance';
+import { Viewer } from './api/classes/viewer';
+import { ViewerLight } from './api/classes/viewerLight';
+import { AnimationManager } from './api/manager/animationManager';
+import { SceneManager } from './api/manager/sceneManager';
+import { VariantInstanceManager } from './api/manager/variantInstanceManager';
+import * as BabylonHelper from './api/util/babylonHelper';
 
 /**
  * Expose some frequently used babylon modules by our consumers.
@@ -52,7 +54,9 @@ export {
 	VariantInstanceManager,
 	Viewer,
 	ParameterObservable,
-	ElementParameterizable,
+	Parameterizable,
+	VariantParameterizable,
+	ViewerLight,
 	emitter as Emitter,
 	EventEmitter,
 	Event,

package/src/pagesconfig.json

@@ -38,6 +38,10 @@
           "title": "Parameters",
           "source": "./doc/documentation/Parameters.md"
         },
+        {
+          "title": "ViewerLights",
+          "source": "./doc/ViewerLights.md"
+        },
         {
           "title": "Paintables",
           "source": "./doc/documentation/Paintables.md"