x_ite 8.8.6 → 8.9.0

package/docs/_posts/components/Geometry3D/Extrusion.md

@@ -1,6 +1,6 @@
 ---
 title: Extrusion
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Geometry3D
 categories: [components, Geometry3D]
 tags: [Extrusion, Geometry3D]
@@ -13,9 +13,9 @@ tags: [Extrusion, Geometry3D]
 
 ## Overview
 
-Extrusion is a geometry node stretching a 2D cross section along a 3D-spine path in the local coordinate system. Scaling/rotating cross-sections can produce a variety of shapes.
+Extrusion is a geometry node that sequentially stretches a 2D cross section along a 3D-spine path in the local coordinate system, creating an outer hull. Scaling and rotating the crossSection 2D outline at each control point can modify the outer hull of the Extrusion to produce a wide variety of interesting shapes.
 
-The Extrusion node belongs to the **Geometry3D** component and its default container field is *geometry.* It is available since X3D version 2.0 or later.
+The Extrusion node belongs to the **Geometry3D** component and its default container field is *geometry.* It is available from X3D version 2.0 or higher.
 
 ## Hierarchy
 
@@ -29,43 +29,60 @@ The Extrusion node belongs to the **Geometry3D** component and its default conta
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### MFVec2f [in] **set_crossSection** <small>(-∞,∞)</small>
 
-An ordered set of 2D points drawing a piecewise-linear curve and forming a planar series of connected vertices. This provides a silhouette of the outer surface.
+The *crossSection* array defines a silhouette outline of the outer Extrusion surface. *crossSection* is an ordered set of 2D points that draw a piecewise-linear curve which is extruded to form a series of connected vertices.
 
-#### Warning
+#### Warnings
 
-- Match clockwise/counterclockwise or impossible/inverted geometry can result!
+- If the order of *crossSection* point definition does not match clockwise/counterclockwise setting of ccw field, then self-intersecting, impossible or inverted geometry can result!
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### MFRotation [in] **set_orientation** <small>[-1,1] or (-∞,∞)</small>
 
-Orientation is a list of axis-angle orientation 4-tuples applied at each spine-aligned cross-section plane.
+The *orientation* array is a list of axis-angle 4-tuple values applied at each spine-aligned cross-section plane.
 
-#### Hint
+#### Hints
+
+- If the *orientation* array contains a single 4-tuple value, it is applied at all spine-aligned crossSection planes.
+- Number of values must all match for 3-tuple spine points, 2-tuple scale values, and 4-tuple *orientation* values.
+
+#### Warning
 
-- Number of spine points, scale values and orientation values must be the same.
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### MFVec2f [in] **set_scale** <small>(0,∞)</small>
 
-Scale is a list of 2D-scale parameters applied at each spine-aligned cross-section plane.
+*scale* is a list of 2D-*scale* parameters applied at each spine-aligned cross-section plane.
 
 #### Hint
 
-- Number of spine points, scale values and orientation values must be the same.
+- Number of values must all match for 3-tuple spine points, 2-tuple *scale* values, and 4-tuple orientation values.
 
-#### Warning
+#### Warnings
 
-- Zero or negative scale values not allowed.
+- Zero or negative *scale* values not allowed.
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### MFVec3f [in] **set_spine** <small>(-∞,∞)</small>
 
-Spine is a list of 3D points for a piecewise-linear curve forming a series of connected vertices, open or closed. This is the path along which the crossSection is extruded.
+The *spine* array defines a center-line sequence of 3D points that define a piecewise-linear curve forming a series of connected vertices. The *spine* is set of points along which a 2D crossSection is extruded, scaled and oriented.
 
-#### Hint
+#### Hints
+
+- The *spine* array can be open or closed (closed means that endpoints are coincident).
+- Number of values must all match for 3-tuple *spine* points, 2-tuple scale values, and 4-tuple orientation values.
+
+#### Warnings
 
-- Number of spine points, scale values and orientation values must be the same.
+- Special care is needed if creating loops or spirals since self-intersecting, impossible or inverted geometry can result!
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### SFBool [ ] **beginCap** TRUE
 
@@ -73,23 +90,25 @@ Whether beginning cap is drawn (similar to Cylinder top cap).
 
 #### Warning
 
-- Cannot be changed after initial creation.
+- Since this field has accessType initializeOnly, the value cannot be changed after initial creation.
 
 ### SFBool [ ] **endCap** TRUE
 
-Whether end cap is drawn (similar to Cylinder end cap).
+Whether end cap is drawn (similar to Cylinder bottom cap).
 
 #### Warning
 
-- Cannot be changed after initial creation.
+- Since this field has accessType initializeOnly, the value cannot be changed after initial creation.
 
 ### SFBool [ ] **solid** TRUE
 
-Setting solid true means draw only one side of polygons (backface culling on), setting solid false means draw both sides of polygons (backface culling off).
+Setting *solid* true means draw only one side of polygons (backface culling on), setting *solid* false means draw both sides of polygons (backface culling off).
 
-#### Hint
+#### Hints
 
-- If in doubt, use solid='false' for maximum visibility.
+- Mnemonic "this geometry is *solid* like a brick" (you don't render the inside of a brick).
+- If in doubt, use *solid*='false' for maximum visibility.
+- (X3D version 4.0 draft) accessType relaxed to inputOutput in order to support animation and visualization.
 
 #### Warning
 
@@ -97,74 +116,107 @@ Setting solid true means draw only one side of polygons (backface culling on), s
 
 ### SFBool [ ] **ccw** TRUE
 
-*ccw* = counterclockwise: ordering of vertex-coordinates orientation.
+The *ccw* field indicates counterclockwise ordering of vertex-coordinates orientation.
 
-#### Hint
+#### Hints
+
+- A good debugging technique for problematic polygons is to try changing the value of *ccw*, which can reverse solid effects (single-sided backface culling) and normal-vector direction.
+- [Clockwise](https://en.wikipedia.org/wiki/Clockwise){:target="_blank"}
 
-- *ccw* false can reverse solid (backface culling) and normal-vector orientation.
+#### Warning
+
+- Consistent and correct ordering of left-handed or right-handed point sequences is important throughout the coord array of point values.
 
 ### SFBool [ ] **convex** TRUE
 
-Whether all polygons in a shape are convex (true), or possibly concave (false). A convex polygon is planar, does not intersect itself, and has all interior angles \< 180 degrees.
+The *convex* field is a hint to renderers whether all polygons in a shape are *convex* (true), or possibly concave (false). A *convex* polygon is planar, does not intersect itself, and has all interior angles \< 180 degrees.
+
+#### Hints
+
+- Concave is the opposite of *convex*.
+- Select *convex*=false (i.e. concave) and solid=false (i.e. two-sided display) for greatest visibility of geometry.
+- [*convex* polygon](https://en.wikipedia.org/wiki/Convex_polygon){:target="_blank"}
+- [Tessellation](https://en.wikipedia.org/wiki/Tessellation){:target="_blank"}
 
 #### Warning
 
-- Concave geometry may be invisible default convex=true.
+- Concave or inverted geometry may be invisible when using default value *convex*=true, since some renderers use more-efficient algorithms to perform tessellation that may inadvertently fail on concave geometry.
 
 ### SFFloat [ ] **creaseAngle** 0 <small>[0,∞)</small>
 
-*creaseAngle* defines angle (in radians) where adjacent polygons are drawn with sharp edges or smooth shading. If angle between normals of two adjacent polygons is less than creaseAngle, smooth shading is rendered across the shared line segment.
+*creaseAngle* defines angle (in radians) where adjacent polygons are drawn with sharp edges or smooth shading. If angle between normals of two adjacent polygons is less than *creaseAngle*, smooth shading is rendered across the shared line segment.
 
-#### Hint
+#### Hints
 
-- CreaseAngle=0 means render all edges sharply, creaseAngle=3.14159 means render all edges smoothly.
+- *creaseAngle*=0 means render all edges sharply, *creaseAngle*=3.14159 means render all edges smoothly.
+- [Radian units for angular measure](https://en.wikipedia.org/wiki/Radian){:target="_blank"}
 
 ### MFVec2f [ ] **crossSection** [ 1 1, 1 -1, -1 -1, -1 1, 1 1 ] <small>(-∞,∞)</small>
 
-An ordered set of 2D points drawing a piecewise-linear curve and forming a planar series of connected vertices. This provides a silhouette of the outer surface.
+The *crossSection* array defines a silhouette outline of the outer Extrusion surface. *crossSection* is an ordered set of 2D points that draw a piecewise-linear curve which is extruded to form a series of connected vertices.
 
-#### Warning
+#### Hints
+
+- The *crossSection* array can be open or closed (closed means that endpoints are coincident).
+- Number of values must all match for 3-tuple spine points, 2-tuple scale values, and 4-tuple orientation values.
+
+#### Warnings
 
-- Match clockwise/counterclockwise or impossible/inverted geometry can result!
+- If the order of *crossSection* point definition does not match clockwise/counterclockwise setting of ccw field, then self-intersecting, impossible or inverted geometry can result!
+- Avoid self-intersecting polygon line segments, otherwise defined geometry is irregular and rendering results are undefined (especially for end caps).
 
 ### MFRotation [ ] **orientation** 0 0 1 0 <small>[-1,1] or (-∞,∞)</small>
 
-*orientation* is a list of axis-angle orientation 4-tuples applied at each spine-aligned cross-section plane.
+The *orientation* array is a list of axis-angle 4-tuple values applied at each spine-aligned cross-section plane.
 
-#### Hint
+#### Hints
 
-- Number of spine points, scale values and orientation values must be the same.
+- If the *orientation* array contains a single 4-tuple value, it is applied at all spine-aligned crossSection planes.
+- Number of values must all match for 3-tuple spine points, 2-tuple scale values, and 4-tuple *orientation* values.
 
 ### MFVec2f [ ] **scale** 1 1 <small>(0,∞)</small>
 
-*scale* is a list of 2D-scale parameters applied at each spine-aligned cross-section plane.
+*scale* is a list of 2D-*scale* parameters applied at each spine-aligned cross-section plane.
 
-#### Hint
+#### Hints
 
-- Number of spine points, scale values and orientation values must be the same.
+- Number of values must all match for 3-tuple spine points, 2-tuple *scale* values, and 4-tuple orientation values.
+- If the *scale* array contains one value, it is applied at all spine-aligned crossSection planes.
 
 #### Warning
 
-- Zero or negative scale values not allowed.
+- Zero or negative *scale* values not allowed.
 
 ### MFVec3f [ ] **spine** [ 0 0 0, 0 1 0 ] <small>(-∞,∞)</small>
 
-*spine* is a list of 3D points for a piecewise-linear curve forming a series of connected vertices, open or closed. This is the path along which the crossSection is extruded.
+The *spine* array defines a center-line sequence of 3D points that define a piecewise-linear curve forming a series of connected vertices. The *spine* is set of points along which a 2D crossSection is extruded, scaled and oriented.
 
-#### Hint
+#### Hints
+
+- The *spine* array can be open or closed (closed means that endpoints are coincident).
+- Number of values must all match for 3-tuple *spine* points, 2-tuple scale values, and 4-tuple orientation values.
+- If a *spine* is closed (or nearly closed) then the inner diameter usually needs to be greater than the corresponding crossSection width.
 
-- Number of spine points, scale values and orientation values must be the same.
+#### Warnings
 
-## Description
+- Special care is needed if creating loops or spirals since self-intersecting, impossible or inverted geometry can result!
+- Ensure that *spine* segments have non-zero length and are not coincident with each other.
 
-### Hint
+## Advisories
 
+### Hints
+
+- [Extrusion](https://en.wikipedia.org/wiki/Extrusion){:target="_blank"}
 - Insert a Shape node before adding geometry or Appearance.
 
+### Warning
+
+- Take care to avoid defining parameter combinations that create self-intersecting, impossible or inverted geometry.
+
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/Geometry3D/Extrusion/Extrusion.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of Extrusion](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/geometry3D.html#Extrusion){:target="_blank"}
+- [X3D Specification of Extrusion node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/geometry3D.html#Extrusion){:target="_blank"}

package/docs/_posts/components/Geometry3D/IndexedFaceSet.md

@@ -1,6 +1,6 @@
 ---
 title: IndexedFaceSet
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Geometry3D
 categories: [components, Geometry3D]
 tags: [IndexedFaceSet, Geometry3D]
@@ -13,9 +13,9 @@ tags: [IndexedFaceSet, Geometry3D]
 
 ## Overview
 
-IndexedFaceSet is a geometry node that can contain a Color/ColorRGBA, Coordinate/CoordinateDouble, Normal and TextureCoordinate nodes.
+IndexedFaceSet defines polygons using index lists corresponding to vertex coordinates. IndexedFaceSet is a geometry node containing a Coordinate or CoordinateDouble node, and can also contain Color or ColorRGBA, Normal and TextureCoordinate nodes.
 
-The IndexedFaceSet node belongs to the **Geometry3D** component and its default container field is *geometry.* It is available since X3D version 2.0 or later.
+The IndexedFaceSet node belongs to the **Geometry3D** component and its default container field is *geometry.* It is available from X3D version 2.0 or higher.
 
 ## Hierarchy
 
@@ -30,17 +30,25 @@ The IndexedFaceSet node belongs to the **Geometry3D** component and its default
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### MFInt32 [in] **set_colorIndex** <small>[0,∞) or -1</small>
 
-*colorIndex* values define the order in which Color|ColorRGBA values are applied to polygons (or vertices).
+*colorIndex* values define the order in which Color or ColorRGBA values are applied to polygons (or vertices).
 
 #### Hints
 
-- If *colorIndex* array is not provided, then Color|ColorRGBA values are indexed according to the coordIndex field.
+- If *colorIndex* array is not provided, then Color or ColorRGBA values are indexed according to the coordIndex field.
 - If colorPerVertex='false' then one index is provided for each polygon defined by the coordIndex array. No sentinel -1 values are included.
-- If colorPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual
+- If colorPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual values in the coordIndex array polygon definitions.
+
+#### Warning
+
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### MFInt32 [in] **set_texCoordIndex** <small>[-1,∞)</small>
 
@@ -48,36 +56,41 @@ List of texture-coordinate indices mapping attached texture to corresponding coo
 
 #### Hint
 
-- If *texCoordIndex* array is not provided, then TextureCoordinate values are indexed according to the coordIndex field.
 - Use a tool!
 
+#### Warning
+
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
+
 ### MFInt32 [in] **set_normalIndex** <small>[0,∞) or -1</small>
 
-*normalIndex* values define the order in which normal vectors are applied to polygons (or vertices).
+*normalIndex* values define the order in which normal vectors are applied to polygons (or vertices). Interchange profile hint: this field may be ignored, applying the default value regardless.
 
-#### Hints
+#### Warning
 
-- If normalPerVertex='false' then one index is provided for each polygon defined by the coordIndex array. No sentinel -1 values are included.
-- If normalPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual values in the coordIndex array polygon definitions.
-- If no child Normal node is provided, the X3D browser shall automatically generate normals, using creaseAngle to determine smoothed shading across shared vertices.
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### MFInt32 [in] **set_coordIndex** <small>[0,∞) or -1</small>
 
-**colorIndex** values define the order in which Color|ColorRGBA values are applied to polygons (or vertices).
+*coordIndex* indices provide the order in which coordinates are applied to construct each polygon face. Order starts at index 0, commas are optional between sets.
 
-#### Hints
+#### Hint
 
-- If *colorIndex* array is not provided, then Color|ColorRGBA values are indexed according to the coordIndex field.
-- If colorPerVertex='false' then one index is provided for each polygon defined by the coordIndex array. No sentinel -1 values are included.
-- If colorPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual values in the coordIndex array polygon definitions.
+- Sentinel value -1 is used to separate indices for each successive polygon.
+
+#### Warning
+
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### SFBool [ ] **solid** TRUE
 
-Setting solid true means draw only one side of polygons (backface culling on), setting solid false means draw both sides of polygons (backface culling off).
+Setting *solid* true means draw only one side of polygons (backface culling on), setting *solid* false means draw both sides of polygons (backface culling off).
 
-#### Hint
+#### Hints
 
-- If in doubt, use solid='false' for maximum visibility.
+- Mnemonic "this geometry is *solid* like a brick" (you don't render the inside of a brick).
+- If in doubt, use *solid*='false' for maximum visibility.
+- (X3D version 4.0 draft) accessType relaxed to inputOutput in order to support animation and visualization.
 
 #### Warning
 
@@ -85,55 +98,80 @@ Setting solid true means draw only one side of polygons (backface culling on), s
 
 ### SFBool [ ] **ccw** TRUE
 
-*ccw* = counterclockwise: ordering of vertex coordinates orientation.
+*ccw* defines clockwise/counterclockwise ordering of vertex coordinates, which in turn defines front/back orientation of polygon normals according to Right-Hand Rule (RHR).
 
-#### Hint
+#### Hints
 
-- *ccw* false can reverse solid (backface culling) and normal-vector orientation.
+- A good debugging technique for problematic polygons is to try changing the value of *ccw*, which can reverse solid effects (single-sided backface culling) and normal-vector direction.
+- [Clockwise](https://en.wikipedia.org/wiki/Clockwise){:target="_blank"}
+
+#### Warning
+
+- Consistent and correct ordering of left-handed or right-handed point sequences is important throughout the coord array of point values.
 
 ### SFBool [ ] **convex** TRUE
 
-Whether all polygons in a shape are convex (true), or possibly concave (false) A convex polygon is planar, does not intersect itself, and has all interior angles \< 180 degrees. Interchange profile hint: only convex=true IndexedFaceSets are supported.
+The *convex* field is a hint to renderers whether all polygons in a shape are *convex* (true), or possibly concave (false). A *convex* polygon is planar, does not intersect itself, and has all interior angles \< 180 degrees.
+
+#### Hints
+
+- Concave is the opposite of *convex*. Interchange profile hint: only *convex*=true IndexedFaceSets have guaranteed support.
+- Select *convex*=false (i.e. concave) and solid=false (i.e. two-sided display) for greatest visibility of geometry.
+- [*convex* polygon](https://en.wikipedia.org/wiki/Convex_polygon){:target="_blank"}
+- [Tessellation](https://en.wikipedia.org/wiki/Tessellation){:target="_blank"}
 
 #### Warning
 
-- Concave geometry may be invisible default convex=true.
+- Concave or inverted geometry may be invisible when using default value *convex*=true, since some renderers use more-efficient algorithms to perform tessellation that may inadvertently fail on concave geometry.
 
 ### SFFloat [ ] **creaseAngle** 0 <small>[0,∞)</small>
 
-*creaseAngle* defines angle (in radians) for determining whether adjacent polygons are drawn with sharp edges or smooth shading. If angle between normals of two adjacent polygons is less than creaseAngle, smooth shading is rendered across the shared line segment. Interchange profile hint: only 0 and π radians supported.
+*creaseAngle* defines angle (in radians) for determining whether adjacent polygons are drawn with sharp edges or smooth shading. If angle between normals of two adjacent polygons is less than *creaseAngle*, smooth shading is rendered across the shared line segment. Interchange profile hint: only 0 and π radians supported.
 
-#### Hint
+#### Hints
 
-- CreaseAngle=0 means render all edges sharply, creaseAngle=3.14159 means render all edges smoothly.
+- *creaseAngle*=0 means render all edges sharply, *creaseAngle*=3.14159 means render all edges smoothly.
+- [Radian units for angular measure](https://en.wikipedia.org/wiki/Radian){:target="_blank"}
 
 ### SFBool [ ] **colorPerVertex** TRUE
 
-Whether Color node color values are applied to each vertex (true) or to each polygon face (false).
+Whether Color or ColorRGBA values are applied to each point vertex (true) or to each polygon face (false).
 
-#### See Also
+#### Hint
 
 - [X3D Scene Authoring Hints, Color](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Color){:target="_blank"}
 
+#### Warning
+
+- If child Color or ColorRGBA node is not provided, then geometry is rendered using corresponding Appearance and material/texture values.
+
 ### SFBool [ ] **normalPerVertex** TRUE
 
-Whether Normal node vector values are applied to each vertex (true) or to each polygon face (false).
+Whether Normal node vector values are applied to each point vertex (true) or to each polygon face (false).
+
+#### Hint
+
+- If no child Normal node is provided, the X3D browser shall automatically generate normals, using creaseAngle to determine smoothed shading across shared vertices.
 
 ### MFInt32 [ ] **colorIndex** [ ] <small>[0,∞) or -1</small>
 
-*colorIndex* values define the order in which Color|ColorRGBA values are applied to polygons (or vertices).
+*colorIndex* values define the order in which Color or ColorRGBA values are applied to polygons (or vertices).
 
 #### Hints
 
-- If *colorIndex* array is not provided, then Color|ColorRGBA values are indexed according to the coordIndex field.
+- If *colorIndex* array is not provided, then Color or ColorRGBA values are indexed according to the coordIndex field.
 - If colorPerVertex='false' then one index is provided for each polygon defined by the coordIndex array. No sentinel -1 values are included.
-- If colorPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual
+- If colorPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual values in the coordIndex array polygon definitions.
+
+#### Warning
+
+- If child Color or ColorRGBA node is not provided, then geometry is rendered using corresponding Appearance and material/texture values.
 
 ### MFInt32 [ ] **texCoordIndex** [ ] <small>[-1,∞)</small>
 
 List of texture-coordinate indices mapping attached texture to corresponding coordinates.
 
-#### Hint
+#### Hints
 
 - If *texCoordIndex* array is not provided, then TextureCoordinate values are indexed according to the coordIndex field.
 - Use a tool!
@@ -146,7 +184,7 @@ List of texture-coordinate indices mapping attached texture to corresponding coo
 
 - If normalPerVertex='false' then one index is provided for each polygon defined by the coordIndex array. No sentinel -1 values are included.
 - If normalPerVertex='true' then a matching set of indices is provided, each separated by sentinel -1, that exactly corresponds to individual values in the coordIndex array polygon definitions.
-- If no child Normal node is provided, the X3D browser shall automatically generate normals, using creaseAngle to determine smoothed shading across shared vertices.
+- If no child Normal node is provided, the X3D browser shall automatically generate normals, using creaseAngle to determine smoothed shading across shared vertices. Interchange profile hint: this field may be ignored, applying the default value regardless.
 
 #### Warning
 
@@ -160,9 +198,13 @@ List of texture-coordinate indices mapping attached texture to corresponding coo
 
 - Sentinel value -1 is used to separate indices for each successive polygon.
 
+#### Warning
+
+- *coordIndex* is required in order to connect contained coordinate point values.
+
 ### MFNode [in, out] **attrib** [ ] <small>[X3DVertexAttributeNode]</small>
 
-Multiple contained FloatVertexAttribute nodes that can specify list of per-vertex attribute information for programmable shaders.
+Single contained FloatVertexAttribute node that can specify list of per-vertex attribute information for programmable shaders.
 
 #### Hint
 
@@ -174,7 +216,7 @@ Single contained FogCoordinate node that can specify depth parameters for fog in
 
 ### SFNode [in, out] **color** NULL <small>[X3DColorNode]</small>
 
-Single contained Color or ColorRGBA node that can specify color values applied to corresponding vertices according to colorIndex and colorPerVertex fields.
+Single contained Color or ColorRGBA node that can specify *color* values applied to corresponding vertices according to colorIndex and colorPerVertex fields.
 
 ### SFNode [in, out] **texCoord** NULL <small>[X3DTextureCoordinateNode]</small>
 
@@ -188,21 +230,31 @@ Single contained Normal node that can specify perpendicular vectors for correspo
 
 - Useful for special effects. Normal vector computation by 3D graphics hardware is quite fast so adding normals to a scene is typically unnecessary.
 
+#### Warning
+
+- *normal* vectors increase file size, typically doubling geometry definitions.
+
 ### SFNode [in, out] **coord** NULL <small>[X3DCoordinateNode]</small>
 
 Single contained Coordinate or CoordinateDouble node that can specify a list of vertex values.
 
-## Description
+## Advisories
 
 ### Hints
 
+- [Polygon](https://en.wikipedia.org/wiki/Polygon){:target="_blank"}
 - Insert a Shape node before adding geometry or Appearance.
-- You can also substitute a type-matched ProtoInstance node for contained content.
+- For advanced extensibility, authors can substitute a type-matched ProtoInstance node (with correct containerField value) for contained node content.
+
+### Warnings
+
+- Rendering characteristics are undefined if polygons are not planar.
+- Avoid self-intersecting polygon line segments, otherwise defined geometry is irregular and rendering results are undefined.
 
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/Geometry3D/IndexedFaceSet/IndexedFaceSet.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/geometry3D.html#IndexedFaceSet){:target="_blank"}
+- [X3D Specification of IndexedFaceSet node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/geometry3D.html#IndexedFaceSet){:target="_blank"}

package/docs/_posts/components/Geometry3D/Sphere.md

@@ -1,6 +1,6 @@
 ---
 title: Sphere
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Geometry3D
 categories: [components, Geometry3D]
 tags: [Sphere, Geometry3D]
@@ -13,9 +13,9 @@ tags: [Sphere, Geometry3D]
 
 ## Overview
 
-Sphere is a geometry node.
+Sphere is a geometry node, representing a perfectly round geometrical object that is the surface of a completely round ball.
 
-The Sphere node belongs to the **Geometry3D** component and its default container field is *geometry.* It is available since X3D version 2.0 or later.
+The Sphere node belongs to the **Geometry3D** component and its default container field is *geometry.* It is available from X3D version 2.0 or higher.
 
 ## Hierarchy
 
@@ -29,38 +29,50 @@ The Sphere node belongs to the **Geometry3D** component and its default containe
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### SFFloat [ ] **radius** 1 <small>(0,∞)</small>
 
 Size in meters.
 
+#### Hint
+
+- For size animation, modify the scale of a parent/ancestor Transform node instead.
+
 #### Warning
 
-- Simple-geometry dimensions are initializeOnly and cannot be changed after initial creation, for animation use Transform scale instead.
+- Simple-geometry dimensions are initializeOnly and cannot be changed after initial creation, avoiding the need for potentially expensive tessellation at run time.
 
 ### SFBool [ ] **solid** TRUE
 
-Setting solid true means draw only one side of polygons (backface culling on), setting solid false means draw both sides of polygons (backface culling off).
+Setting *solid* true means draw only one side of polygons (backface culling on), setting *solid* false means draw both sides of polygons (backface culling off).
 
-#### Hint
+#### Hints
 
-- If in doubt, use solid='false' for maximum visibility.
+- Mnemonic "this geometry is *solid* like a brick" (you don't render the inside of a brick).
+- If in doubt, use *solid*='false' for maximum visibility.
+- (X3D version 4.0 draft) accessType relaxed to inputOutput in order to support animation and visualization.
 
 #### Warnings
 
-- Default value true can completely hide geometry if viewed from wrong side! Solid false not supported in VRML97.
+- Default value true can completely hide geometry if viewed from wrong side!
+- *solid* false not supported in VRML97.
 
-## Description
+## Advisories
 
-### Hint
+### Hints
 
+- [Sphere](https://en.wikipedia.org/wiki/Sphere){:target="_blank"}
 - Insert a Shape node before adding geometry or Appearance.
 
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/Geometry3D/Sphere/Sphere.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of Sphere](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/geometry3D.html#Sphere){:target="_blank"}
+- [X3D Specification of Sphere node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/geometry3D.html#Sphere){:target="_blank"}