Adding light position configurability for surface and mesh3d, and general lighting configurability for the latter

package.json

@@ -61,7 +61,7 @@
     "gl-line2d": "^1.3.0",
     "gl-line3d": "^1.1.0",
     "gl-mat4": "^1.1.2",
-    "gl-mesh3d": "^1.0.7",
+    "gl-mesh3d": "^1.2.0",
     "gl-plot2d": "^1.1.6",
     "gl-plot3d": "^1.5.0",
     "gl-scatter2d": "^1.0.5",

src/traces/mesh3d/attributes.js

@@ -124,7 +124,29 @@ module.exports = {
     reversescale: colorscaleAttrs.reversescale,
     showscale: colorscaleAttrs.showscale,
 
-    lighting: extendFlat({}, surfaceAtts.lighting),
+    lightposition: {
+        'x': extendFlat({}, surfaceAtts.lightposition.x, {dflt: 1e5}),
+        'y': extendFlat({}, surfaceAtts.lightposition.y, {dflt: 1e5}),
+        'z': extendFlat({}, surfaceAtts.lightposition.z, {dflt: 0})
+    },
+    lighting: extendFlat({}, {
+        vertexnormalsepsilon: {
+            valType: 'number',
+            role: 'style',
+            min: 0.00,
+            max: 1,
+            dflt: 1e-12, // otherwise finely tessellated things eg. the brain will have no specular light reflection
+            description: 'Epsilon for vertex normals calculation avoids math issues arising from degenerate geometry.'
+        },
+        facenormalsepsilon: {
+            valType: 'number',
+            role: 'style',
+            min: 0.00,
+            max: 1,
+            dflt: 1e-6, // even the brain model doesn't appear to need finer than this
+            description: 'Epsilon for face normals calculation avoids math issues arising from degenerate geometry.'
+        }
+    }, surfaceAtts.lighting),
 
     _nestedModules: {  // nested module coupling
         'colorbar': 'Colorbar'

src/traces/mesh3d/convert.js

@@ -106,11 +106,14 @@ proto.update = function(data) {
     var config = {
         positions: positions,
         cells: cells,
+        lightPosition: [data.lightposition.x, data.lightposition.y, data.lightposition.z],
         ambient: data.lighting.ambient,
         diffuse: data.lighting.diffuse,
         specular: data.lighting.specular,
         roughness: data.lighting.roughness,
         fresnel: data.lighting.fresnel,
+        vertexNormalsEpsilon: data.lighting.vertexnormalsepsilon,
+        faceNormalsEpsilon: data.lighting.facenormalsepsilon,
         opacity: data.opacity,
         contourEnable: data.contour.show,
         contourColor: str2RgbaArray(data.contour.color).slice(0, 3),

src/traces/mesh3d/defaults.js

@@ -49,11 +49,17 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
     }
 
     //Coerce remaining properties
-    ['lighting.ambient',
+    [
+        'lighting.ambient',
         'lighting.diffuse',
         'lighting.specular',
         'lighting.roughness',
         'lighting.fresnel',
+        'lighting.vertexnormalsepsilon',
+        'lighting.facenormalsepsilon',
+        'lightposition.x',
+        'lightposition.y',
+        'lightposition.z',
         'contour.show',
         'contour.color',
         'contour.width',

src/traces/surface/attributes.js

@@ -147,41 +147,76 @@ module.exports = {
         ].join(' ')
     },
 
+    lightposition: {
+        x: {
+            valType: 'number',
+            role: 'style',
+            min: -1e5,
+            max: 1e5,
+            dflt: 10,
+            description: 'Numeric vector, representing the X coordinate for each vertex.'
+        },
+        y: {
+            valType: 'number',
+            role: 'style',
+            min: -1e5,
+            max: 1e5,
+            dflt: 1e5,
+            description: 'Numeric vector, representing the Y coordinate for each vertex.'
+        },
+        z: {
+            valType: 'number',
+            role: 'style',
+            min: -1e5,
+            max: 1e5,
+            dflt: 0,
+            description: 'Numeric vector, representing the Z coordinate for each vertex.'
+        }
+    },
+
     lighting: {
         ambient: {
             valType: 'number',
             role: 'style',
             min: 0.00,
             max: 1.0,
-            dflt: 0.8
+            dflt: 0.8,
+            description: 'Ambient light increases overall color visibility but can wash out the image.'
         },
         diffuse: {
             valType: 'number',
             role: 'style',
             min: 0.00,
             max: 1.00,
-            dflt: 0.8
+            dflt: 0.8,
+            description: 'Represents the extent that incident rays are reflected in a range of angles.'
         },
         specular: {
             valType: 'number',
             role: 'style',
             min: 0.00,
             max: 2.00,
-            dflt: 0.05
+            dflt: 0.05,
+            description: 'Represents the level that incident rays are reflected in a single direction, causing shine.'
         },
         roughness: {
             valType: 'number',
             role: 'style',
             min: 0.00,
             max: 1.00,
-            dflt: 0.5
+            dflt: 0.5,
+            description: 'Alters specular reflection; the rougher the surface, the wider and less contrasty the shine.'
         },
         fresnel: {
             valType: 'number',
             role: 'style',
             min: 0.00,
             max: 5.00,
-            dflt: 0.2
+            dflt: 0.2,
+            description: [
+                'Represents the reflectance as a dependency of the viewing angle; e.g. paper is reflective',
+                'when viewing it from the edge of the paper (almost 90 degrees), causing shine.'
+            ].join(' ')
         }
     },
 

src/traces/surface/convert.js

@@ -334,6 +334,16 @@ proto.update = function(data) {
         surface.fresnel = data.lighting.fresnel;
     }
 
+    if('lightposition' in data) {
+        if(surface.lightPosition === void(0)) {
+            surface.lightPosition = [data.lightposition.x, data.lightposition.y, data.lightposition.z];
+        } else {
+            surface.lightPosition.x = data.lightposition.x;
+            surface.lightPosition.y = data.lightposition.y;
+            surface.lightPosition.z = data.lightposition.z;
+        }
+    }
+
     if(alpha && alpha < 1) {
         surface.supportsTransparency = true;
     }

src/traces/surface/defaults.js

@@ -50,13 +50,19 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         }
     }
 
-    coerce('lighting.ambient');
-    coerce('lighting.diffuse');
-    coerce('lighting.specular');
-    coerce('lighting.roughness');
-    coerce('lighting.fresnel');
-    coerce('hidesurface');
-    coerce('opacity');
+    //Coerce remaining properties
+    [
+        'lighting.ambient',
+        'lighting.diffuse',
+        'lighting.specular',
+        'lighting.roughness',
+        'lighting.fresnel',
+        'lightposition.x',
+        'lightposition.y',
+        'lightposition.z',
+        'hidesurface',
+        'opacity'
+    ].forEach(function(x) { coerce(x); });
 
     var surfaceColor = coerce('surfacecolor');
 

test/image/mocks/gl3d_surface-lighting.json

@@ -510,12 +510,17 @@
           "show": false
         }
       },
+      "lightposition": {
+        "x": 1e5,
+        "y": 1e5,
+        "z": 1e5
+      },
       "lighting": {
-        "fresnel": 0.8,
-        "roughness": 0.5,
-        "diffuse": 0.5,
-        "ambient": 0.5,
-        "specular": 0.5
+        "fresnel": 0.2,
+        "roughness": 0.1,
+        "diffuse": 2,
+        "ambient": 0.15,
+        "specular": 2
       }
     }
   ],
@@ -550,18 +555,18 @@
       "xaxis": {
         "showbackground": true,
         "type": "linear",
-        "backgroundcolor": "rgb(255, 127, 14)",
+        "backgroundcolor": "rgba(255, 127, 14, 0.2)",
         "tickangle": 180
       },
       "yaxis": {
         "showbackground": true,
         "type": "linear",
-        "backgroundcolor": "rgb(255, 0, 0)",
+        "backgroundcolor": "rgba(255, 0, 0, 0.2)",
         "tickangle": -45
       },
       "zaxis": {
         "showbackground": true,
-        "backgroundcolor": "rgb(44, 160, 44)",
+        "backgroundcolor": "rgba(44, 160, 44, 0.35)",
         "tickangle": 30
       }
     }