32:T4a2,md `## Introduction This notebook is a detailed discusssion of the DataVisual programming pattern. * Other notebooks in this series: * [***Hello, DataVisual!***](https://observablehq.com/@mariodelgadosr/hello-datavisual): provides a quick-start demonstration of the DataVisual framework's basic functionality. * [***DataVisual Event Handlers***](https://observablehq.com/@mariodelgadosr/datavisual-event-handlers): extends the quick-start with hover and doble-click event handlers. * [***DataVisual (Data + Visual) Design Pattern for WebGL 3D Assets using a glTF with Embedded Data***](https://observablehq.com/@mariodelgadosr/datavisual-data-visual-design-pattern-for-webgl-3d-assets-u) * [***DataVisual Visualization with Data-Embedded glTF Files***](https://observablehq.com/@mariodelgadosr/datavisual-visualization-with-data-embedded-gltf-files) * [***Data Visualization of Randomly Assigned Values to Objects in glTF Files***](https://observablehq.com/@mariodelgadosr/data-visualization-of-randomly-assigned-values-to-objects) * [***Warehouse Visualization with DataVisual***](https://observablehq.com/@mariodelgadosr/warehouse-visualization-with-datavisual) ` 33:T60c,md`## Why? With a **DataVisual** desing pattern, [set processing](https://www.datacamp.com/community/tutorials/sets-in-python) of a [*joined* set (the data + visual object)](https://www.essentialsql.com/what-is-the-difference-between-a-join-and-a-union/) is easily done to [programatically generate new *answer sets*](https://medium.com/poka-techblog/simplify-your-javascript-use-map-reduce-and-filter-bd02c593cc2d). Through the *join*, and its related properties and methods, the **DataVisual** keeps track of critical information important to the visualization task(s) like: * Determining the visual object in a scene that correponds to a specific data row; * Determining the data row that corresponds to a specific visual object in a scene (very helpful with [raycasting](https://threejs.org/docs/index.html#api/en/core/Raycaster)); * Determining which data row(s) don't have a corresponding visual object in the scene; * Maintaining the relative context (relationship) when [array processing methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#) are applied. The **DataVisual** [class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) includes methods for common interactive visualization tasks: * Isolate objects in a scene. * Show (unhide) all the objects in a scene. * Change the color of specified objects. * Show a default or custom tooltip when the mouse hovers over an object in the visual. * Handle the mouse double-click event for an object in the visaul. `34:T77e,md`## How? **aquaBot: A Use Case** This Observable notebook describes the pattern in detail with a demonstration use case for a U.S. Navy (Go Navy!, Beat Army!) salvage robot. The robot, aquaBot, develops a retrieval strategy with information available in a traditional data array **and** the spatial data inferred from the 3D scene; via a [glTF](https://en.wikipedia.org/wiki/GlTF) file that is [loaded](https://threejs.org/docs/index.html#examples/loaders/GLTFLoader) into Three.js. * While a glTF file is used in this demonstration, it is not a pre-requisite for using a **DataVisual**: * A Three.js scene can be built [programmatically](https://threejs.org/docs/#manual/en/introduction/Creating-a-scene) and then referenced as the *visual* parameter in the following method detailed below:

  dataVisual.joinDataToVisual(data,visual)

* [***Warehouse Visualization with DataVisual***](https://observablehq.com/@mariodelgadosr/warehouse-visualization-with-datavisual) is an example of the programmatically generated scene pattern. * [***DataVisual (Data + Visual) Design Pattern for WebGL 3D Assets using a glTF with Embedded Data***](https://observablehq.com/@mariodelgadosr/datavisual-data-visual-design-pattern-for-webgl-3d-assets-u) extends this notebook to the scenario where data is embedded in the glTF file itself; within its [*extras*](https://github.com/KhronosGroup/glTF/tree/master/specification/2.0#reference-extras) properties. * In that notebook, glTF extras are transformed to [Threee.js *userData* properties](https://threejs.org/docs/index.html#api/en/core/Object3D.userData) in a scene. * See [***DataVisual Visualization with Data-Embedded glTF Files***](https://observablehq.com/@mariodelgadosr/datavisual-visualization-with-data-embedded-gltf-files) for several real-world examples of this pattern. `35:T728,md`The primary components of the glTF file/JSON structure are the [meshes](https://threejs.org/docs/index.html#api/en/objects/Mesh) (*children* of the [*scene*](https://threejs.org/docs/index.html#api/en/scenes/Scene) property) that will be dynamically visualized: |uuid | name | type | userData.visualKey| material.name | |--------------------|---------------------|--------------|---------|----------| ${mutable seaScape.scene.children.filter(c => c.type == "Mesh").map(function(c){ return ` | ${c.uuid.substring(0,12) + "..." } | ${c.name} | ${c.type} | ${c.userData.visualKey} | ${c.material.name} `; }) } The [uuid](https://en.wikipedia.org/wiki/Universally_unique_identifier) property is a [dynamically generated unique identifier](https://threejs.org/docs/#api/en/core/Object3D.uuid) for every object in the Three.JS scene graph. There are two important things to notice about the 3D asset being described in the glTF: 1. The *name* and *userData.visualKey* properties are **not** exact matches; more on that in the next section: [**Data + Visual: 'Setting the Scene'**](#settingTheScene). 2. Each mesh has a unique [**material**](https://threejs.org/docs/index.html#api/en/materials/Material) associated with it. The relationship of a mesh to material is 1 to 1. In Three.js, this allows the visualization logic to 'drive' each visual object in the visualization. See [mrdoob (creator of Three.js)](https://mrdoob.com/)'s discussion on this issue in [**this**](https://stackoverflow.com/questions/25252132/how-to-change-the-color-of-material-of-an-object-individually-if-the-material-is?rq=1) stackoveflow post. The following is a [collapsible tree](https://observablehq.com/@mariodelgadosr/collapsibletree) for the scene in the loaded seaScape gltf file along with the seaScape javascript object itself: `36:T1803,md`### The Derived Join The following table, generated with properties in the newly instantiated *seaScapDataVisual*, has three 'key' (pun intended) properties in its *join* (data + visual) object: 1. .dataRow.name 2. .visualObj.name 3. .visualObj.userData.visualKey |join.dataRow.name | join.visualObj.name | join.visualObj.userData.visualKey | |-----------|------------------|------------| ${seaScapeDataVisualJoin.map( function (e) { return ` | ${e.dataRow.name} | ${e.visualObj.name} | ${e.visualObj.userData.visualKey} `; } )}

In addtion, the dataVisual exposes the following methods and properties: **Methods:** Method | Description -------| ----------- .joinDataToVisual(data, visual) | Join *data* to a *visual*'s mesh utilizing each object's *name* property .joinDataToVisual(data, visual, dataKey, visualKey) | Join *data* to a *visual* utilizing *data*'s *dataKey* property and *visual*'s *visualKey* property. *visualKey* can be a direct property of a mesh, or its *.userData* property. .joinDataToVisual(visual) | Creates a *dataVisual* object from a *visual* when the data is embedded within the [*userData*](https://threejs.org/docs/index.html#api/en/core/Object3D.userData) property for mesh(es). .getJoinByUUID(uuid) | Get a joined row by referencing a mesh's *uuid*. This method is very helpful with [raycasting](https://threejs.org/docs/index.html#api/en/core/Raycaster) techniques. .getJoinByUUID(uuid, "index") | Get a joined row's index by referencing a mesh's *uuid*. This method is very helpful with [raycasting](https://threejs.org/docs/index.html#api/en/core/Raycaster) techniques. .getJoinByKey(dataKey) | Get a joined row by referencing a dataRow's *dataKey*. .getJoinByKey(dataKey, "index") | Get a joined row's index by referencing a dataRow's *dataKey*. .getDataColumn(column) | Get an array of a specified column (attribute/property) from the *dataVisual*'s data. .setColorVisualObj(visualObj,color) | Set the material.color property for a mesh. The method utilizes the Three.js [traverse](https://threejs.org/docs/index.html#api/en/core/Object3D.traverse) method to set color for any children the mesh may have as well. .setColorByJoinIndex(index,color) | Set the material.color property for a mesh by referencing the index of the join. The method invokes .setColorVisualObj for the given index. .isolateObjects(visualObjs) | Isolate(s) the visual object(s) in the *visualObjs* array by assigning only their *visible* property = true. All other object(s) in the *dataVisual* have their *visible* property = false. .showAll() | Shows all visual objects in the *DataVisual* visible; *visible* = true; .addToolTip(renderer, camera[, getToolTipText]) | Implements a custom tooltip assuming the following parameters:

*renderer*: A Three.js [WebGLRenderer object](https://threejs.org/docs/index.html#api/en/renderers/WebGLRenderer) that has been attached to an HTML parent element.

*camera*: A Three.js [camera object](https://threejs.org/docs/index.html#api/en/cameras/Camera)

*getToolTipText*: An optional tooltip text callback function that will be passed two parameters: references to the *join* row and the *dataVisual* instance itself. With the second parameter (*dataVisual*) the callback has access to all the object's properties.

The *getToolTipText* callback function must return a [DOMString](https://developer.mozilla.org/en-US/docs/Web/API/DOMString) that will be assigned to the tooltip's [innerHTML](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) property. .onHover(renderer, camera, handleEnter [,handleLeave]) | Implements mouse hover handlers for joined objects. Both ***handleEnter*** and the optional ***handleLeave*** callback funtions will be passed two parameters: references to the *join* row and the *dataVisual* instance itself. With the second (*dataVisual*) parameter the callback has access to all the object's properties. .onDoublClick(renderer, camera, handleDblClick) |

Implements a mouse double-click event handler for joined objects. The ***handleDblClick*** callback function/handler will be passed two parameters: references to the *join* row and the *dataVisual* instance itself. With the second (*dataVisual*) parameter the callback has access to all the object's properties. **Properties:** Property | Description -------- | ----------- .join | A join object (array). Each element of the array will be an object referencing a joined (matching) dataRow and visuaObj. .join[n].dataRow | A reference to nth data row from the original data array that corresponds to the joined nth (matching) visualObj. .join[n].visualObj | A reference to the nth Three.js mesh being 'joined' to that corresponds to the joined nth (matching) dataRow. .data | The original data participating in the 'join'. .visual | The original visual participating in the 'join'. .dataKey | The data key attribute being used to join to a corresponding mesh in the visual. .visualKey |The visual key attribute being used to join to the visual's mesh. Property *visualKey* can be a direct property of a mesh or a property of the mesh's *.userData* member. .nonMatchingDataKeys | An array holding any dataKey(s) that did not join/match when the *joinDataToVisual* method was invoked.

**The *userData.visualKey* property:** As noted earlier, the *join.visualObj.name* and *join.visualObj.userData.visualKey* **don't** match in their values. This is a result of the the Three.js framework [**sanitizing**](https://discourse.threejs.org/t/issue-with-gltfloader-and-objects-with-dots-in-their-name-attribute/6726) the Blender generated *name* property when it was being [duplicated](https://docs.blender.org/manual/en/latest/scene_layout/object/editing/duplicate.html). This now explains why the *visualKey* sub-property for the *userData* property associated with mesh was specified in the *joinDataToVisual* method. The *visualKey* property can be set manually in Blender with the [Custom Properties](https://docs.blender.org/manual/en/latest/data_system/custom_properties.html) tool: `37:T6dc,md` Alternatively, [Python Scripts](https://github.com/MarioDelgadoSr/AddBlenderCustomPropertiesFromCSV) can be used to automate the 'keying' process for visuals with several objects to identify. The scripts are also useful for the embedded data strategy referred to earlier. If the *name* property for the *data* and *seaScape* glTF matched exactly **AFTER** it was [sanitized](https://discourse.threejs.org/t/issue-with-gltfloader-and-objects-with-dots-in-their-name-attribute/6726) by the Three.js import, the method would be invoked by simply referencing the *data* and *seaScape* objects:

const seaScapeDataVisual = new dataVisual()
      seaScapeDataVisual.joinDataToVisual(data, seaScape);

// Alternate instantiation pattern supported by the ES6 class:
// const seaScapeDataVisual = new dataVisual({data, visual: seaScape });

**Blender Development Tip**: * The visualization is being done on unique materials associated with a visual object. If materials are shared between objects, the visualization will not have the intended behavior. See [How to put a unique material on duplicated objects separately?](https://blender.stackexchange.com/questions/23386/how-to-put-a-unique-material-on-duplicated-objects-separately) for assigning unique materials to duplicate objects. * Also, [**Duplication** in the Blender Manual](https://docs.blender.org/manual/en/latest/editors/3dview/object/editing/duplication.html?highlight=linked%20materials). * Finally, Ctrl-C (copy into the Blender Buffer) and Ctrl-V (paste from the Blender Buffer) will duplicate an object and assign it a unique material; without requring an upate to the global user preferences as the Blender documentation suggests. `38:T83f,//seaScapeDataVisual set processsing //Note: This object has all the set processing operations (including sort) done for the visualization. //seaScapeDataVisualJoin is used to display the intermediary steps in this notebook before the final sort function setProcessSteps1_to_4(seaScapeDataVisual) { //Step 1 Calculate distance to each cube const originVector = new THREE.Vector3(0,0,0); seaScapeDataVisual.join.forEach(function (join){ join.originToVisualObjDistance = originVector.distanceTo(join.visualObj.position); }); //forEach //Step 2 sort descending on value seaScapeDataVisual .join .sort(function (join1,join2){ return d3.descending(join1.dataRow.value, join2.dataRow.value ); }); //Step 3 determine pre-rendering visibility predicting fuel consumption const fullTank = 150; var distanceLeft = fullTank; seaScapeDataVisual .join.forEach(function (join){ join.visible = distanceLeft > 0; join.distanceLeft = distanceLeft; distanceLeft -= (join.originToVisualObjDistance * 2); } ); //Step 4 Calculate visualization color with d3 color scale var maxValue = d3.max(seaScapeDataVisual.join, join => join.visible ? join.dataRow.value : 0); var minValue = d3.min(seaScapeDataVisual.join, join => join.visible ? join.dataRow.value : maxValue); var fnColor = d3.scaleSequential(d3.interpolateRdYlGn).domain([minValue, maxValue]); seaScapeDataVisual.join.forEach(function (join){ join.visualObj.visible = join.visible; join.color = fnColor(join.dataRow.value); if (join.visible) { seaScapeDataVisual .setColorVisualObj(join.visualObj,join.color ) } //if }); // forEach } // simulateSteps1_to_439:T9f3,md`### Step 4: Assign Visualization Colors The **dataVisual** (via the individual *join.visualObj*'s) is now ready to be visualized referencing the *join.visible* property and [D3 color scaling](https://github.com/d3/d3-scale-chromatic#interpolateRdYlGn): * The *join* is extended again with a *.color* property that will be refernced for the cubes and the legend/predicted fuel gauge. * Each *join* row in the array is iterated through and the cubes/visualObjs have their respective colors set with the *setColorVisualObj* method. * The method takes care of setting the color for any child material. * It's not the case for this demonstration, but scenes can: * Have [an indiviudal mesh with multiple materials](https://github.com/mrdoob/three.js/issues/12135); * Or utilize [Three.js Group(s)](https://threejs.org/docs/index.html#api/en/objects/Group); **not** to be confused with [Blender Group(s)](https://docs.blender.org/manual/en/dev/scene_layout/object/properties/relations/groups.html?highlight=group#fig-view3d-grouped-objects). * See discussion in [*Exporting groups to Three.js from Blender in gltf format*](https://stackoverflow.com/questions/54531833/exporting-group-to-three-js-from-blender-in-gltf-format) for the limitations on exporting [Blender Group(s)](https://docs.blender.org/manual/en/dev/scene_layout/object/properties/relations/groups.html?highlight=group#fig-view3d-grouped-objects) to glTF. As the discussion suggests, utilizing [Empty Object(s)](https://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/The_Empty_Object) is the recommended approach to associate a parent-child relationship when the intent is to export a scene via glTF to Three.js. * More information is available in the [supported Blender features for the glTF 2.0 exporter](https://docs.blender.org/manual/en/dev/addons/io_gltf2.html). * A **DataVisual**, with use of the *setColorVisualObj* method, is appropriate for setting the color of all materials of a parent that is *joined* to ([Empty Object(s)](https://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/The_Empty_Object) and/or [Three.js Group(s)](https://threejs.org/docs/index.html#api/en/objects/Group)) and their children. * This design pattern is **not** appropriate for objects that have multiple materials and the intent of the visualization is to individually assign a color to each of the sub materials; as is detailed in [*Multiple Materials Per Object*](https://en.wikibooks.org/wiki/Blender_3D:_Noob_to_Pro/Multiple_Materials_Per_Object). `3a:T819,md`## Visualization Finally, the [visualization](#title): * The next notebook cell contains the logic to display the Three.js scene at the top of this notebook. * The visualization shows aquaBot at the scene's origin (0,0,0) with animated, stylized lines illustrating the salvage strategy. * The [dat.gui](https://workshop.chromeexperiments.com/examples/gui/#1--Basic-Usage) control in the upper right corner displays the cubes' values before and after sorting/filtering. Moreover, only the post-sorted cubes that can be salvged are intially rendered. * Cubes that are not intially rendered can be displayed by enabling the checkbox on the [dat.gui](https://workshop.chromeexperiments.com/examples/gui/#1--Basic-Usage) control control. * Panning and zooming are enabled with the Three.js [OribitControls](https://threejs.org/docs/index.html#examples/controls/OrbitControls). * The **DataVisual** helps with user interactions in the visualization as well: * The built-in tooltip uses [Raycasting](https://threejs.org/docs/index.html#api/en/core/Raycaster) to display a default or custom tooltip. * It also exposes a mouse onHover method to update the [dat.gui](https://workshop.chromeexperiments.com/examples/gui/#1--Basic-Usage) control with indicators of the cube identified.

  
  seaScapeDataVisual.addToolTip(renderer, camera)
                    .onHover(renderer, camera, 
                             (join) => 
                               d3.select(datGui.domElement)
                               .selectAll(".property-name")
                               .text(function(){ 
                                      const searchText = d3.select(this).text().split("****");  
                                      const cubeName = searchText[searchText.length-1].trim();  
                                      return cubeName == join.dataRow.name ? "****" + cubeName : cubeName;                                                 }
                               ) // text
                     );

`3b:T1ab1,function fnDisplay(container, seaScapeDataVisual){ seaScapeDataVisual.visual.scene.background = new THREE.Color("#1c4a63") ; //Deep Sea Blue // Sea-scape surface const size = 100, divisions = 40; const gridHelper = new THREE.GridHelper( size, divisions ); seaScapeDataVisual.visual.scene.add( gridHelper ); //Using Variable reference as per: //https://observablehq.com/@tmcw/observable-anti-patterns-and-code-smells#reselectingElements //var container = document.getElementById("seaScapeDiv"); // Implements this patch: // https://talk.observablehq.com/t/before-content-for-li-element-affect-dat-gui-hoste-in-observable-notebook-cell/2050/2 const datGui = new dat.GUI({ autoPlace: false }); while (container.firstChild) { container.removeChild(container.firstChild); } container.appendChild(datGui.domElement); // Turn on the lights and render the visual referencing the scene seaScapeDataVisual.visual built. seaScapeDataVisual.visual.scene.add(new THREE.AmbientLight(0xffffff,0.5)); seaScapeDataVisual.visual.scene.add(new THREE.HemisphereLight(0xffffff,0xffffff,0.5)); //Observable has width pre-assigned: https://github.com/observablehq/stdlib/blob/master/README.md#width //var height = 800; const height = $(container).height(); // Under water view at twice maximum distance from origin const camera = new THREE.PerspectiveCamera( 75, width / height, 0.1, 1000 ); camera.position.set(0, -4, d3.max( seaScapeDataVisual.join, function(join){return join.originToVisualObjDistance} ) * 2 ); const renderer = new THREE.WebGLRenderer(); const controls = new THREE.OrbitControls( camera, renderer.domElement ); controls.autoRotate = true; renderer.setSize( width, height ); // Only datGui should be in here first time if (container.children.length <=1){ container.appendChild( renderer.domElement ); //Build dat.gui with viusalization fnBuildDatGui(datGui, container); } //if // aquaRobot const botGeometry = new THREE.IcosahedronGeometry(1); const botMaterial = new THREE.MeshBasicMaterial(); const aquaBot = new THREE.Mesh(botGeometry, botMaterial); seaScapeDataVisual.visual.scene.add(aquaBot); // Visualization of the retrieval/salvage path const material = new THREE.LineBasicMaterial({color: seaScapeDataVisual.join[0].visualObj.material.color }); const geometry = new THREE.Geometry(); geometry.vertices.push( new THREE.Vector3( 0, 0, 0 ), seaScapeDataVisual.join[0].visualObj.position.clone() ); const line = new THREE.Line( geometry, material ); seaScapeDataVisual.visual.scene.add( line ); //Animated aquaRobot's salvage strategy let index = 0; setInterval(function(){ //The join's visibiblity, not visualObj's visibility if (seaScapeDataVisual.join[index].visible){ line.material.color.setHex(seaScapeDataVisual.join[index].visualObj.material.color.getHex() ) line.geometry.vertices[1].copy(seaScapeDataVisual.join[index].visualObj.position); // https://threejs.org/docs/index.html#api/en/core/Geometry.verticesNeedUpdate line.geometry.verticesNeedUpdate = true; index = index >= (seaScapeDataVisual.join.length - 1) ? 0 : index + 1; } //if else { index = 0; } //else }, 1000); //setInterval seaScapeDataVisual.addToolTip(renderer, camera) .onHover(renderer, camera, (join) => d3.select(datGui.domElement) .selectAll(".property-name") .text(function(){ const searchText = d3.select(this).text().split("****"); const cubeName = searchText[searchText.length-1].trim(); return cubeName == join.dataRow.name ? "****" + cubeName : cubeName; } ) // text ); animate(); function animate() { requestAnimationFrame(animate); controls.update(); renderer.render( seaScapeDataVisual.visual.scene, camera ); } //animate //https://workshop.chromeexperiments.com/examples/gui/#1--Basic-Usage function fnBuildDatGui(datGui, container){ const guiDisplay = {"Show Hidden": false }; const chkShowHidden = datGui.add(guiDisplay, 'Show Hidden'); chkShowHidden.onChange(function (value){ seaScapeDataVisual.join.forEach(function(join){ join.visualObj.visible = value ? true : join.visible; }); }); //onchange // Utilizes seaScapeDataVisual.getJoinByUUID(intersect.object.uuid) datGui.addFolder("Double-click an object for more details"); let folder = datGui.addFolder("Value"); folder.open(); const maxDataValue = d3.max(seaScapeDataVisual.join, function(join){return join.dataRow.value; }); seaScapeDataVisual.data.forEach(function(datum){ guiDisplay[datum.name] = datum.value; folder.add(guiDisplay, datum.name, 0, maxDataValue); }); //Disable slider and input for read-only legend effect d3.select(folder.domElement) .selectAll(".c") .style("pointer-events","none") .selectAll("input") .attr("disabled", "true"); folder = datGui.addFolder("Salvage Order"); folder.open(); seaScapeDataVisual.join.forEach(function(join){ if (join.visible){ // + " " creates unique property guiDisplay[join.dataRow.name + " " ] = join.dataRow.value; folder.add(guiDisplay, join.dataRow.name + " ", 0, maxDataValue); // A little hack of dat Gui d3.select(folder.__controllers[folder.__controllers.length -1].domElement) .select(".slider-fg") // Find the slider-fg class ... .style("background-color", join.color); // Then use data driven visualization } //if }); //forEach //Disable slider and input for read-only legend effect d3.select(folder.domElement) .selectAll(".c") .style("pointer-events","none") .selectAll("input") .attr("disabled", "true"); // Observable notebook-specific positioning styling d3.select(datGui.domElement) .style("position","absolute") .style("top","0px") .style("right","20px"); } //fnBuildDatGui } //fnDisplay 3c:[{"id":"d489e30a343de0aa96d6a2411b6fe7aa44c7b9a7cb34f32e640f2fff7f00abe1cc141208c55cc6baee780a96c99c57aa60f56198f472e019ae05abdaed94e6ee","href":"https://static.observableusercontent.com/files/d489e30a343de0aa96d6a2411b6fe7aa44c7b9a7cb34f32e640f2fff7f00abe1cc141208c55cc6baee780a96c99c57aa60f56198f472e019ae05abdaed94e6ee","name":"seaScape.gltf","type":"model/gltf+json","lastModified":1662463360461.807,"size":44346}] 30:{"title":"DataVisual (Data + Visual) Design Pattern for WebGL 3D Assets","cells":[{"id":0,"value":"\ntitle = md`# DataVisual (Data + Visual) Design Pattern for WebGL 3D Assets\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":83,"value":"container = html`

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1405,"value":"toc(\"h2,h3,h4,h5\")\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":391,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":1385,"value":"md `## DataVisual\n\n[**DataVisual**](https://github.com/MarioDelgadoSr/datavisual) is a design/programming pattern, implemented in JavaScript, for data driven visualizations on 3D [WebGL](https://en.wikipedia.org/wiki/WebGL) assets. \n\n[Three.js](https://threejs.org/) and [D3](https://d3js.org/) are utilized as the primary frameworks to implement the pattern, but it is applicable to other frameworks as well; like [jQuery](http://jquery.com/) and [Babylon](https://www.babylonjs.com/).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":576,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":571,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":193,"value":"md`## Data\n\n\nThe design pattern uses information in an array of JSON objects for the *data*:\n\n|data.name | data.value | \n|-----------|------------------| ${data.map(join => `\\n | ${join.name} | ${join.value} | `)} \n\n

\naquaBot's task is to salvage as many high value cubes as it can before it runs out of fuel.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":122,"value":"// Data establishing a 'value' for each salvageable cube in the seaScape\nmutable data = {\n \n\t\t\tconst data = [\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\n\t\t\t\t\t\t\t{\"name\": \"Cube.001\", \"value\": 10},\t\t\n\t\t\t\t\t\t\t{\"name\": \"Cube.002\", \"value\": 100},\t\t\n\t\t\t\t\t\t\t{\"name\": \"Cube.003\", \"value\": 40},\t\t \n\t\t\t\t\t\t\t{\"name\": \"Cube.004\", \"value\": 20},\n\t\t\t\t\t\t\t{\"name\": \"Cube.005\", \"value\": 15},\n\t\t\t\t\t\t\t{\"name\": \"Cube.006\", \"value\": 40},\n\t\t\t\t\t\t\t{\"name\": \"Cube.007\", \"value\": 10},\n\t\t\t\t\t\t\t{\"name\": \"Cube.008\", \"value\": 55},\n\t\t\t\t\t\t\t{\"name\": \"Cube.009\", \"value\": 35},\n\t\t\t\t\t\t\t{\"name\": \"Cube.010\", \"value\": 45},\n\t\t\t\t\t\t ];\t\n \n return data;\n \n} ","pinned":false,"hidden":false,"mode":"ojs"},{"id":476,"value":"md`## glTF \n\nThe Three.js scene aquaBot will analyze is imported from a [glTF](https://en.wikipedia.org/wiki/GlTF) file built with [Blender](https://www.blender.org/) (more details on Blender below).\n\n\nThe [glTF (Graphics Library Transmission Format) specification](https://github.com/KhronosGroup/glTF/blob/master/specification/2.0/README.md) is very robust:\n\n

\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":528,"value":"md`[Khronos Group](https://www.khronos.org/)'s [webinar](https://www.khronos.org/events/webinar-khronos-gltf) is a good backgrounder:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":485,"value":"//https://observablehq.com/@tmcw/embedding-stuff-now-works\n// How to embed: https://youtu.be/iT97xCNh_-g\n\nhtml``\n\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":196,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":1315,"value":"collapsibleTree({data: seaScape.scene, labelTransform: {label: d => d.data.type + \": \" + d.data.name} , dx: 20 });","pinned":false,"hidden":false,"mode":"ojs"},{"id":64,"value":"// https://observablehq.com/@observablehq/introduction-to-promises\n// https://talk.observablehq.com/t/return-object-in-a-callback/292\n// Not needed, but interesting: Promisifying three.js loaders: https://blackthread.io/blog/promisifying-threejs-loaders/\n\nmutable seaScape = {\n //const gltfURL = 'https://gist.githubusercontent.com/MarioDelgadoSr/4aa24204072de1ad49a1fe541d707cfd/raw/6c987ae69e44fdda39d935b30788274b1b5eea79/seaScape.gltf';\n\n // https://observablehq.com/@observablehq/stdlib#fileAttachmentSection\n const gltfURL = await FileAttachment(\"seaScape.gltf\").url();\n\n const output = new Promise((resolve, reject) => {\n new THREE.GLTFLoader().load(gltfURL, (x) => {\n if (x) resolve(x);\n else reject(new Error(\"load failed\"));\n });\n });\n\n return output;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":295,"value":"settingTheScene = md`## Data + Visual (DataVisual): '*Setting the Scene*' `","pinned":false,"hidden":false,"mode":"ojs"},{"id":203,"value":"md`A **DataVisual** is instantiated with the [*dataVisual* class](https://github.com/MarioDelgadoSr/DataVisual/blob/master/lib/dataVisual.js): \n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":626,"value":"md`\n

\nconst seaScapeDataVisual = new dataVisual();\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\n      seaScapeDataVisual.joinDataToVisual(data, seaScape, \"name\", \"visualKey\");\n\n// Alternate instantiation pattern supported by the ES6 class:\n// const seaScapeDataVisual = new dataVisual({data, visual: seaScape, dataKey: \"name\", visualKey: \"visualKey\" });\n\n

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1241,"value":"mutable seaScapeDataVisual = new dataVisual({data, visual: seaScape, dataKey: \"name\", visualKey: \"visualKey\"});","pinned":false,"hidden":false,"mode":"ojs"},{"id":205,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":507,"value":"//https://observablehq.com/@tmcw/embedding-stuff-now-works\n// How to embed: https://youtu.be/iT97xCNh_-g\n\nhtml``","pinned":false,"hidden":false,"mode":"ojs"},{"id":502,"value":"$37","pinned":false,"hidden":false,"mode":"ojs"},{"id":747,"value":"setProcessing = { return md`## Set Processing\n\nWith the *join* in place the next 4 steps will prepare the *dataVisual*'s data for visualization:\n\n1. Calculate the distance from aquaBot to each salvageable cube and extend the *join* with the newly calculated distance property.\n\n2. Sort the complete *join* (high to low) by the value property for each *join.dataRow*.\n\n3. Determine the visibility of each *join.visualObj* as a function of the amount of predicted fuel left in aquaBot's tank.\n\n4. Assign [D3 scale coloring](https://github.com/d3/d3-scale-chromatic#interpolateRdYlGn) for the visualization -- only for the salvageable cubes.\n\n`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":215,"value":"//Following recommendations for mutable/immutable variables found here:\n//https://observablehq.com/d/179861198dccb0b1\n \nsteps_1_to_4 = { \n \n setProcessSteps1_to_4(mutable seaScapeDataVisual);\n \n return html`⬅ Click cell to see the set processing code for steps 1 through 4.`; \n} ","pinned":false,"hidden":false,"mode":"ojs"},{"id":1252,"value":"$38","pinned":false,"hidden":false,"mode":"ojs"},{"id":219,"value":"md`### Step 1: Calculate Distance\n\nTo calculate the distance from the aquaBot located, at the x=0, y=0, z=0, a Three.js origin vector is instantiated:\n\n

\n var originVector = new THREE.Vector3(0,0,0);\t\n

\n\n` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":230,"value":"md`The **DataVisual**'s *join* can now be leveraged to reference the spatial information in the WebGL scene and calculate the distance form the origin to each individual cube. \n\nThe Three.js [*distanceTo*]( https://threejs.org/docs/index.html#api/en/math/Vector3.distanceTo) method is used to extend the *seaScapeDataVisual.join* with a new property, *originToVisualObjDistance*, that contains the 1-way distance to a cube:\n\n

\n\tseaScapeDataVisual.join.forEach(function (join){     \t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t \n\n\t\tjoin.originToVisualObjDistance  = originVector.distanceTo(join.visualObj.position);        \t\t\t\t\t\t\t\n\t\n  });\t \n

\n\n\n|join.visualObj.name | join.originToVisualObjDistance |\n|-----------|-------------|${ seaScapeDataVisualJoin.sort((join1,join2) => d3.ascending(join1.visualObj.name,join2.visualObj.name))\n .map(j =>` \\n| ${j.visualObj.name} | ${j.originToVisualObjDistance} |`) }\n\nNotice that the distances are in the original cube order.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":245,"value":"md`### Step 2: Sort on value; high to low\n\nThe *join* can now be sorted (high to low) by the *dataRow.value* property:\n\n

\nseaScapeDataVisual.join\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\n    .sort(function (join1,join2){\n          return d3.descending(join1.dataRow.value, join2.dataRow.value ); \t\t\t\t\t\t\t\t\t\t\t\n    });  \n

\n\n|join.dataRow.value | join.visualObj.name | join.originToVisualObjDistance | \n|-----------|-------------|-----------| ${seaScapeDataVisualJoin.sort((join1,join2) => d3.descending(join1.dataRow.value,join2.dataRow.value))\n .map((e,i) => `\\n| ${e.dataRow.value} | ${e.visualObj.name} | ${e.originToVisualObjDistance}|`)}\n\n\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":258,"value":"md`### Step 3: Determine Pre-rendering Visibility\n\nLeveraging the *join* to determine visibilty is another benefit. On platforms with limited resources (eg: mobile devices) having a *renedring-only-what's-needed* strategy can be a user experience requirement. \n\naquaBot starts off with a full tank allowing it to navigate up to 150 units:\n\n

\n fullTank = 150;

\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":269,"value":"md` With the sorting complete, aquaBot determines how many cubes can retrieved before it runs out of fuel: \n\n* The *distanceLeft* variable is assigned the initial *fullTank* value.\n\n* The *dataVisual*'s *join* is iterated through in the high to low sort sequence determined by the sort.\n\n* Cubes that can be retreieved will have their [*visible* property](https://threejs.org/docs/index.html#api/en/core/Object3D.visible) set to *true* at rendering-time; those that can't are set to *false*. \n\n * To keep track of which cubes are salvagable, and will be intially rendered, the join is extended with it's own *.visible* property. \n\n This provides for flexibility with the 'Show Hidden' feature (see 'Show Hidden' checkbox above on the Three.js scene) that displays all cubes; those that are salvageable as well as those that are not.\n\n* The *originToVisualObjDistance* property is doubled when calculating how much distance is left in the fuel tank to account for the each retrieval's round trip:\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":687,"value":"md`

    \n    var distanceLeft = fullTank;\n\n    seaScapeDataVisual.join.forEach(function (join){     \t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t      \n\n                          join.visible = distanceLeft > 0;\t\t\t\t\t\t\t\t\t\t\t\t\n                          distanceLeft -=  (join.originToVisualObjDistance * 2);\t\t\t\t\t\t\n\n                      });\n

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":690,"value":"md`\n\nThe following table shows the results of the aquaBot's retrieval/prediction strategy. \n\nThree cubes won't be salvaged (Cube005, Cube001 and Cube007); and they won't be initially rendered:\n\n\n|.dataRow.value | .originToVisualObjDistance | .visible | .visualObj.name | .distanceLeft |\n|-----------|-------------|-----------|--------------| ${seaScapeDataVisual.join.map(function(e,i){ return `\n| ${e.dataRow.value} | ${e.originToVisualObjDistance} | ${e.visible} | ${e.visualObj.name} | ${e.distanceLeft} | `; }) }\n(All properties in the table are for *dataVisual.join*)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":287,"value":"$39","pinned":false,"hidden":false,"mode":"ojs"},{"id":770,"value":"md`

  \nvar maxValue = d3.max(seaScapeDataVisual.join, join => join.visible ? join.dataRow.value : 0);\t\nvar minValue = d3.min(seaScapeDataVisual.join, join => join.visible ? join.dataRow.value : maxValue);\nvar fnColor = d3.scaleSequential(d3.interpolateRdYlGn).domain([minValue, maxValue]);\n\nseaScapeDataVisual.join.forEach(function (join){    \t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t\t     \n\n  join.visualObj.visible = join.visible;   \t\t\t\t\t\t\t\t\t\n  join.color =  fnColor(join.dataRow.value);\t\t\t\t\n\n  if (join.visible) { \t\n\n    seaScapeDataVisual\n    .setColorVisualObj(join.visualObj, join.color );\n\n  } //if\n\n}); // forEach\t\n\n

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":291,"value":"$3a","pinned":false,"hidden":false,"mode":"ojs"},{"id":1208,"value":"visualization = { \n \n fnDisplay(container, seaScapeDataVisual);\n \n return html`⬅ Click cell to see visualization code.`; \n \n} ","pinned":false,"hidden":false,"mode":"ojs"},{"id":36,"value":"$3b","pinned":false,"hidden":false,"mode":"ojs"},{"id":824,"value":"md`### Known issues specific to using [dat.Gui](https://github.com/dataarts/dat.gui) with this Observable notebook\n\nThe [::before psuedo element](https://developer.mozilla.org/en-US/docs/Web/CSS/::before) is affecting the *li* elements in the dat.gui controller.\n\nThe post [*HTMLElement.pseudoStyle: Setting/Modifying :before and :after in javascript*](http://mcgivery.com/htmlelement-pseudostyle-settingmodifying-before-and-after-in-javascript/) claimed to have a resolution to the issue, but it doesn't work on Observable. \n\nI will be opening up a forum question on this issue.\n\n**Update**: [This patch](https://talk.observablehq.com/t/before-content-for-li-element-affect-dat-gui-hoste-in-observable-notebook-cell/2050/2) was implemeted.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1363,"value":"license = md `## License\n\nFree to all non-profit organizations. Businesses and commercial enterprises are granted a full-use license as long as they make their application freely available to non-profits. \n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":832,"value":"md`## Source Code on Github\n\nhttps://github.com/MarioDelgadoSr/DataVisual\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":836,"value":"md`## DataVisual in Use\n\n* [*My Data Visualizer*](https://github.com/MarioDelgadoSr/MyDataVisualizer)\n* [*My Warehouse Visualizer*](https://github.com/MarioDelgadoSr/MyWarehouseVisualizer)\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":30,"value":"md`## Imports`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1312,"value":"import {collapsibleTree} from \"@mariodelgadosr/collapsibletree\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":1402,"value":"//import {toc} from \"@mbostock/toc\"\nimport { toc } from \"@nebrius/indented-toc\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":305,"value":"md`### [DataVisual](https://github.com/MarioDelgadoSr/DataVisual) Class`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1181,"value":"import {dataVisual} from \"@mariodelgadosr/hello-datavisual\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":313,"value":"md`### [Three.js](https://threejs.org/) WebGL Framework`","pinned":false,"hidden":false,"mode":"ojs"},{"id":40,"value":"// THREE JS Module\nTHREE = {\n //const version = \"0.99.0\";\n const version = `0.104.0`;\n const THREE = (window.THREE =\n await require(`three@${version}/build/three.min.js`));\n await require(`three@${version}/examples/js/controls/OrbitControls.js`).catch(\n () => {}\n );\n await require(`three@${version}/examples/js/loaders/GLTFLoader.js`).catch(\n () => {}\n );\n return THREE;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":315,"value":"md`### [D3](https://d3js.org/) Data Visualization Framework`","pinned":false,"hidden":false,"mode":"ojs"},{"id":131,"value":"//D3 Reference\nd3 = require(\"d3@6\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":322,"value":"md`### [dat.Gui](https://github.com/dataarts/dat.gui) Contoller (used for the visualization legend and displaying cubes selected with [raycasting](https://threejs.org/docs/index.html#api/en/core/Raycaster)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":133,"value":"//dat.gui\ndat = require('dat.gui')","pinned":false,"hidden":false,"mode":"ojs"},{"id":872,"value":"md`### CSS Style to address [::before Observable CSS rule](https://talk.observablehq.com/t/before-content-for-li-element-affect-dat-gui-hoste-in-observable-notebook-cell/2050/2)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":871,"value":"html`