From dfd29d41d35f4a5b9b42adab0d4c50c72d3ca89e Mon Sep 17 00:00:00 2001 From: Robert Monfera Date: Wed, 1 Jun 2016 15:47:31 +0200 Subject: [PATCH 1/2] mesh3d document update --- src/traces/mesh3d/attributes.js | 77 ++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 15 deletions(-) diff --git a/src/traces/mesh3d/attributes.js b/src/traces/mesh3d/attributes.js index a423183f6a4..bf237077587 100644 --- a/src/traces/mesh3d/attributes.js +++ b/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(' ') }, From f256361edcc302b53e176426f69354dbb835317d Mon Sep 17 00:00:00 2001 From: Robert Monfera Date: Wed, 1 Jun 2016 17:37:12 +0200 Subject: [PATCH 2/2] mesh3d document update - review feedback --- src/traces/mesh3d/attributes.js | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/src/traces/mesh3d/attributes.js b/src/traces/mesh3d/attributes.js index bf237077587..6c4cdd87f23 100644 --- a/src/traces/mesh3d/attributes.js +++ b/src/traces/mesh3d/attributes.js @@ -31,7 +31,7 @@ module.exports = { z: { valType: 'data_array', description: [ - 'Sets the X coordinates of the vertices. The nth element of vectors `x`, `y` and `z`', + 'Sets the Z 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(' ') }, @@ -42,7 +42,7 @@ module.exports = { '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', + '`{x[n], y[n], z[n]}` in the vertex arrays. Therefore, each element in `i` represents a', 'point in space, which is the first vertex of a triangle.' ].join(' ') }, @@ -52,7 +52,7 @@ module.exports = { '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', + '`{x[n], y[n], z[n]}` in the vertex arrays. Therefore, each element in `j` represents a', 'point in space, which is the second vertex of a triangle.' ].join(' ') @@ -63,7 +63,7 @@ module.exports = { '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', + '`{x[n], y[n], z[n]}` in the vertex arrays. Therefore, each element in `k` represents a', 'point in space, which is the third vertex of a triangle.' ].join(' ') @@ -91,24 +91,20 @@ module.exports = { '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.', + 'supplied.', '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`.', + 'it will result 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 alpha-shape algorithm is used. In this case, the positive `alphahull` value', + 'signals the use of the alpha-shape algorithm, _and_ its value', + 'acts as the parameter for the mesh fitting.', '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.' + 'hull.' ].join(' ') },