mesh3d document update

Author: monfera

src/traces/mesh3d/attributes.js

@@ -16,28 +16,57 @@ var extendFlat = require('../../lib/extend').extendFlat;
 module.exports = {
     x: {
         valType: 'data_array',
-        description: 'Sets the x coordinates of the vertices'
+        description: [
+            'Sets the X coordinates of the vertices. The nth element of vectors `x`, `y` and `z`',
+            'jointly represent the X, Y and Z coordinates of the nth vertex.'
+        ].join(' ')
     },
     y: {
         valType: 'data_array',
-        description: 'Sets the y coordinates of the vertices'
+        description: [
+            'Sets the Y coordinates of the vertices. The nth element of vectors `x`, `y` and `z`',
+            'jointly represent the X, Y and Z coordinates of the nth vertex.'
+        ].join(' ')
     },
     z: {
         valType: 'data_array',
-        description: 'Sets the z coordinates of the vertices'
+        description: [
+            'Sets the X coordinates of the vertices. The nth element of vectors `x`, `y` and `z`',
+            'jointly represent the X, Y and Z coordinates of the nth vertex.'
+        ].join(' ')
     },
 
     i: {
         valType: 'data_array',
-        description: 'Sets the indices of x coordinates of the vertices'
+        description: [
+            'A vector of vertex indices, i.e. integer values between 0 and the length of the vertex',
+            'vectors, representing the *first* vertex of a triangle. For example, `{i[m], j[m], k[m]}`',
+            'together represent face m (triangle m) in the mesh, where `i[m] = n` points to the triplet',
+            '`{x[n], y[n], z[v]}` in the vertex arrays. Therefore, each element in `i` represents a',
+            'point in space, which is the first vertex of a triangle.'
+        ].join(' ')
     },
     j: {
         valType: 'data_array',
-        description: 'Sets the indices of y coordinates of the vertices'
+        description: [
+            'A vector of vertex indices, i.e. integer values between 0 and the length of the vertex',
+            'vectors, representing the *second* vertex of a triangle. For example, `{i[m], j[m], k[m]}` ',
+            'together represent face m (triangle m) in the mesh, where `j[m] = n` points to the triplet',
+            '`{x[n], y[n], z[v]}` in the vertex arrays. Therefore, each element in `j` represents a',
+            'point in space, which is the second vertex of a triangle.'
+        ].join(' ')
+
     },
     k: {
         valType: 'data_array',
-        description: 'Sets the indices of z coordinates of the vertices'
+        description: [
+            'A vector of vertex indices, i.e. integer values between 0 and the length of the vertex',
+            'vectors, representing the *third* vertex of a triangle. For example, `{i[m], j[m], k[m]}`',
+            'together represent face m (triangle m) in the mesh, where `k[m] = n` points to the triplet ',
+            '`{x[n], y[n], z[v]}` in the vertex arrays. Therefore, each element in `k` represents a',
+            'point in space, which is the third vertex of a triangle.'
+        ].join(' ')
+
     },
 
     delaunayaxis: {
@@ -46,9 +75,10 @@ module.exports = {
         values: [ 'x', 'y', 'z' ],
         dflt: 'z',
         description: [
-            'Sets the Delaunay axis from which the triangulation of the mesh',
-            'takes place.',
-            'An alternative to setting the `i`, `j`, `k` indices triplets.'
+            'Sets the Delaunay axis, which is the axis that is perpendicular to the surface of the',
+            'Delaunay triangulation.',
+            'It has an effect if `i`, `j`, `k` are not provided and `alphahull` is set to indicate',
+            'Delaunay triangulation.'
         ].join(' ')
     },
 
@@ -57,11 +87,28 @@ module.exports = {
         role: 'style',
         dflt: -1,
         description: [
-            'Sets the shape of the mesh',
-            'If *-1*, Delaunay triangulation is used',
-            'If *>0*, the alpha-shape algorithm is used',
-            'If *0*,  the convex-hull algorithm is used',
-            'An alternative to the `i`, `j`, `k` indices triplets.'
+            'Determines how the mesh surface triangles are derived from the set of',
+            'vertices (points) represented by the `x`, `y` and `z` arrays, if',
+            'the `i`, `j`, `k` arrays are not supplied.',
+            'For general use of `mesh3d` it is preferred that `i`, `j`, `k` are',
+            'supplied, because calculating the surface from points can be very',
+            'time consuming and usually lead to artifacts.',
+
+            'If *-1*, Delaunay triangulation is used, which is mainly suitable if the',
+            'mesh is a single, more or less layer surface that is perpendicular to `delaunayaxis`.',
+            'In case the `delaunayaxis` intersects the mesh surface at more than one point',
+            '(e.g. sphere, cube, potato, animal, donut etc. shapes) it will lead to triangles',
+            'that are very long in the dimension of `delaunayaxis`.',
+
+            'If *>0*, the alpha-shape algorithm is used. In this case, the `alphahull` value',
+            'not only signals the intention to choose the alpha-shape algorithm, but its value',
+            'acts as the parameter for the mesh fitting. It can take minutes to calculate a large',
+            'mesh (e.g. over 10 thousand points), and the result is very sensitive to the',
+            'chosen value. ',
+
+            'If *0*,  the convex-hull algorithm is used. It is suitable for convex bodies',
+            'or if the intention is to enclose the `x`, `y` and `z` point set into a convex',
+            'hull. However it can not generate concave surfaces.'
         ].join(' ')
     },
 
@@ -106,7 +153,7 @@ module.exports = {
         dflt: false,
         description: [
             'Determines whether or not normal smoothing is applied to the meshes,',
-            'creating meshes with a low-poly look.'
+            'creating meshes with an angular, low-poly look via flat reflections.'
         ].join(' ')
     },