x_ite 8.8.7 → 8.9.1

package/docs/_posts/components/Picking/PrimitivePickSensor.md

@@ -1,6 +1,6 @@
 ---
 title: PrimitivePickSensor
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Picking
 categories: [components, Picking]
 tags: [PrimitivePickSensor, Picking]
@@ -13,9 +13,9 @@ tags: [PrimitivePickSensor, Picking]
 
 ## Overview
 
-PrimitivePickSensor tests picking intersections using one of the basic primitive shapes specified in the pickingGeometry field [Cone|Cylinder|Sphere|Box] against the pickTarget geometry.
+PrimitivePickSensor tests picking intersections using one of the basic primitive shapes specified in the pickingGeometry field [Cone or Cylinder or Sphere or Box] against the pickTarget geometry.
 
-The PrimitivePickSensor node belongs to the **Picking** component and its default container field is *children.* It is available since X3D version 3.2 or later.
+The PrimitivePickSensor node belongs to the **Picking** component and its default container field is *children.* It is available from X3D version 3.2 or higher.
 
 ## Hierarchy
 
@@ -31,7 +31,11 @@ The PrimitivePickSensor node belongs to the **Picking** component and its defaul
 
 ### 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"}
 
 ### SFBool [in, out] **enabled** TRUE
 
@@ -39,11 +43,12 @@ Enables/disables node operation.
 
 ### MFString [in, out] **objectType** "ALL" <small>["ALL", "NONE", "TERRAIN", ...]</small>
 
-The objectType field specifies a set of labels used in the picking process. Each string specified is treated as an independent label that needs to be matched against the same type in one of the pick sensor instances.
+The *objectType* field specifies a set of labels used in the picking process. Each string specified is treated as an independent label that needs to be matched against the same type in one of the pick sensor instances. Example: labeling a PickableGroup with the *objectType* value "WATER" and then attempting to intersect a pick sensor with *objectType* value "GROUND" fails since the *objectType* values do not match. Example: the special value "ALL" means that each node is available for picking regardless of the type specified by the pick sensor. Example: the special value "NONE" effectively disables all picking for this node and is the equivalent of setting the pickable field of the corresponding PickableGroup to false.
 
 #### Hints
 
-- Authors may define any value for objectType. MFString arrays can have multiple values, so "separate each individual string" "by using quote marks".
+- Authors may define any value for *objectType*.
+- MFString arrays can have multiple values, so "separate each individual string" "by using quote marks".
 
 ### SFString [in, out] **matchCriterion** "MATCH_ANY" <small>["MATCH_ANY"|"MATCH_EVERY"|"MATCH_ONLY_ONE"]</small>
 
@@ -55,7 +60,7 @@ Defines whether the intersection test (i.e. pick) by this X3DPickSensorNode must
 
 #### Hint
 
-- IntersectionType constants may be extended by the browser to provide additional options.
+- *intersectionType* constants may be extended by the browser to provide additional options.
 
 #### Warning
 
@@ -63,7 +68,7 @@ Defines whether the intersection test (i.e. pick) by this X3DPickSensorNode must
 
 ### SFString [ ] **sortOrder** "CLOSEST" <small>["ANY"|"CLOSEST"|"ALL"|"ALL_SORTED"]</small>
 
-The sortOrder field determines the order provided for picked output events.
+The *sortOrder* field determines the order provided for picked output events. Example: ANY means any single object that can satisfy picking conditions for this pick sensor. Consistency of results is not guaranteed. Example: ALL means that every object that satisfies the picking conditions for this pick sensor shall be returned. Example: ALL_SORTED means that every object that satisfies the picking conditions for this pick sensor shall be returned with the order of the output fields provided in a distance-sorted order from closest to farthest away. The exact algorithm for sorting is defined by the individual node definitions. Example: CLOSEST means that the closest object by distance that satisfies the conditions of this pick sensor. *The exact algorithm for distance determination shall be defined by individual node definitions*.
 
 #### Hint
 
@@ -75,7 +80,11 @@ The sortOrder field determines the order provided for picked output events.
 
 ### SFBool [out] **isActive**
 
-*isActive* indicates when the intersecting object is picked by the picking geometry. Output event isActive=true gets sent once a picked item is found. Output event isActive=false gets sent once no picked item is found.
+*isActive* indicates when the intersecting object is picked by the picking geometry. Output event *isActive*=true gets sent once a picked item is found. Output event *isActive*=false gets sent once no picked item is found.
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
 ### SFNode [in, out] **pickingGeometry** NULL <small>[Cone|Cylinder|Sphere|Box]</small>
 
@@ -89,30 +98,29 @@ The sortOrder field determines the order provided for picked output events.
 
 Output event containing the node or nodes that have been found to intersect with the picking geometry from the last time this node performed a picking operation, given in the local coordinate system.
 
-## Description
+#### Warning
 
-### Example
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
-- A Cylinder without end caps is still treated as an enclosed Cylinder.
+## Advisories
 
 ### Hints
 
 - Sorting is defined based on the primitive type as follows. For Cone, the closest picked primitive is defined to be that closest to the vertex point. For Cylinder, Box, and Sphere, the closest picked primitive is defined to be that closest to the center.
 - Picking is performed between rendered frames of the event model. An author sets up the picking request in one frame by placing a LinePickSensor in the desired location. At the start of the next frame, any picking intersections are reported by the pick sensor.
 - Picking notification is performed at the start of the frame for all enabled pick sensors once all other sensors are processed.
+- [Event timing details are explained in X3D Specification 4.4.8.3 Execution model](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/concepts.html#ExecutionModel){:target="_blank"}
 - Box, Cone, Cylinder or Sphere can be used for pickingGeometry node.
 
 ### Warnings
 
-- Boolean fields used to control visibility of primitive pickingGeometry subsections are ignored when evaluating picking intersections.
+- Boolean fields used to control visibility of primitive pickingGeometry subsections are ignored when evaluating picking intersections. Example: a Cylinder without end caps is still treated as an enclosed Cylinder.
 - Order of contained nodes is significant, single pickingGeometry node must precede pickTarget node array.
 
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/Picking/PrimitivePickSensor/PrimitivePickSensor.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of PrimitivePickSensor](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/picking.html#PrimitivePickSensor){:target="_blank"}
-- [Event timing details are explained in 4.4.8.3 Execution model](https://www.web3d.org/files/specifications/19775-1/V3.3/Part01/concepts.html#ExecutionModel){:target="_blank"}
-- A Cylinder without end caps is still treated as an enclosed Cylinder.
+- [X3D Specification of PrimitivePickSensor node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/picking.html#PrimitivePickSensor){:target="_blank"}

package/docs/_posts/components/Picking/VolumePickSensor.md

@@ -1,6 +1,6 @@
 ---
 title: VolumePickSensor
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Picking
 categories: [components, Picking]
 tags: [VolumePickSensor, Picking]
@@ -15,7 +15,7 @@ tags: [VolumePickSensor, Picking]
 
 VolumePickSensor tests picking intersections using the pickingGeometry against the pickTarget geometry volume.
 
-The VolumePickSensor node belongs to the **Picking** component and its default container field is *children.* It is available since X3D version 3.2 or later.
+The VolumePickSensor node belongs to the **Picking** component and its default container field is *children.* It is available from X3D version 3.2 or higher.
 
 ## Hierarchy
 
@@ -31,7 +31,11 @@ The VolumePickSensor node belongs to the **Picking** component and its default c
 
 ### 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"}
 
 ### SFBool [in, out] **enabled** TRUE
 
@@ -39,11 +43,12 @@ Enables/disables node operation.
 
 ### MFString [in, out] **objectType** "ALL" <small>["ALL", "NONE", "TERRAIN", ...]</small>
 
-The objectType field specifies a set of labels used in the picking process. Each string specified is treated as an independent label that needs to be matched against the same type in one of the pick sensor instances.
+The *objectType* field specifies a set of labels used in the picking process. Each string specified is treated as an independent label that needs to be matched against the same type in one of the pick sensor instances. Example: labeling a PickableGroup with the *objectType* value "WATER" and then attempting to intersect a pick sensor with *objectType* value "GROUND" fails since the *objectType* values do not match. Example: the special value "ALL" means that each node is available for picking regardless of the type specified by the pick sensor. Example: the special value "NONE" effectively disables all picking for this node and is the equivalent of setting the pickable field of the corresponding PickableGroup to false.
 
 #### Hints
 
-- Authors may define any value for objectType. MFString arrays can have multiple values, so "separate each individual string" "by using quote marks".
+- Authors may define any value for *objectType*.
+- MFString arrays can have multiple values, so "separate each individual string" "by using quote marks".
 
 ### SFString [in, out] **matchCriterion** "MATCH_ANY" <small>["MATCH_ANY"|"MATCH_EVERY"|"MATCH_ONLY_ONE"]</small>
 
@@ -55,7 +60,7 @@ Defines whether the intersection test (i.e. pick) by this X3DPickSensorNode must
 
 #### Hint
 
-- IntersectionType constants may be extended by the browser to provide additional options.
+- *intersectionType* constants may be extended by the browser to provide additional options.
 
 #### Warning
 
@@ -63,7 +68,7 @@ Defines whether the intersection test (i.e. pick) by this X3DPickSensorNode must
 
 ### SFString [ ] **sortOrder** "CLOSEST" <small>["ANY"|"CLOSEST"|"ALL"|"ALL_SORTED"]</small>
 
-The sortOrder field determines the order provided for picked output events.
+The *sortOrder* field determines the order provided for picked output events. Example: ANY means any single object that can satisfy picking conditions for this pick sensor. Consistency of results is not guaranteed. Example: ALL means that every object that satisfies the picking conditions for this pick sensor shall be returned. Example: ALL_SORTED means that every object that satisfies the picking conditions for this pick sensor shall be returned with the order of the output fields provided in a distance-sorted order from closest to farthest away. The exact algorithm for sorting is defined by the individual node definitions. Example: CLOSEST means that the closest object by distance that satisfies the conditions of this pick sensor. *The exact algorithm for distance determination shall be defined by individual node definitions*.
 
 #### Hint
 
@@ -75,7 +80,11 @@ The sortOrder field determines the order provided for picked output events.
 
 ### SFBool [out] **isActive**
 
-*isActive* indicates when the intersecting object is picked by the picking geometry. Output event isActive=true gets sent once a picked item is found. Output event isActive=false gets sent once no picked item is found.
+*isActive* indicates when the intersecting object is picked by the picking geometry. Output event *isActive*=true gets sent once a picked item is found. Output event *isActive*=false gets sent once no picked item is found.
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
 ### SFNode [in, out] **pickingGeometry** NULL <small>[X3DGeometryNode]</small>
 
@@ -89,7 +98,11 @@ The sortOrder field determines the order provided for picked output events.
 
 Output event containing the node or nodes that have been found to intersect with the picking geometry from the last time this node performed a picking operation, given in the local coordinate system.
 
-## Description
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
+## Advisories
 
 ### Hints
 
@@ -98,6 +111,7 @@ Output event containing the node or nodes that have been found to intersect with
 - Sorting is defined based on distance between the centers of the bounds of the picking geometry and the picked geometry.
 - Picking is performed between rendered frames of the event model. An author sets up the picking request in one frame by placing a LinePickSensor in the desired location. At the start of the next frame, any picking intersections are reported by the pick sensor.
 - Picking notification is performed at the start of the frame for all enabled pick sensors once all other sensors are processed.
+- [Event timing details are explained in X3D Specification 4.4.8.3 Execution model](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/concepts.html#ExecutionModel){:target="_blank"}
 - Any geometry can be used for pickingGeometry node.
 
 ### Warnings
@@ -105,7 +119,6 @@ Output event containing the node or nodes that have been found to intersect with
 - PickingGeometry volume is defined by the convex hull of the enclosing planes of the provided X3DGeometryNode. If the provided volume is not manifold, pick results are undefined.
 - Order of contained nodes is significant, single pickingGeometry node must precede pickTarget node array.
 
-## External Links
+## See Also
 
-- [X3D Specification of VolumePickSensor](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/picking.html#VolumePickSensor){:target="_blank"}
-- [Event timing details are explained in 4.4.8.3 Execution model](https://www.web3d.org/files/specifications/19775-1/V3.3/Part01/concepts.html#ExecutionModel){:target="_blank"}
+- [X3D Specification of VolumePickSensor node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/picking.html#VolumePickSensor){:target="_blank"}

package/docs/_posts/components/PointingDeviceSensor/CylinderSensor.md

@@ -1,6 +1,6 @@
 ---
 title: CylinderSensor
-date: 2022-01-07
+date: 2023-01-07
 nav: components-PointingDeviceSensor
 categories: [components, PointingDeviceSensor]
 tags: [CylinderSensor, PointingDeviceSensor]
@@ -15,7 +15,7 @@ tags: [CylinderSensor, PointingDeviceSensor]
 
 CylinderSensor converts pointer motion (for example, a mouse or wand) into rotation values using an invisible cylinder aligned with local Y-axis.
 
-The CylinderSensor node belongs to the **PointingDeviceSensor** component and its default container field is *children.* It is available since X3D version 2.0 or later.
+The CylinderSensor node belongs to the **PointingDeviceSensor** component and its default container field is *children.* It is available from X3D version 2.0 or higher.
 
 ## Hierarchy
 
@@ -32,15 +32,20 @@ The CylinderSensor node belongs to the **PointingDeviceSensor** component and it
 
 ### 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"}
 
 ### SFString [in, out] **description** ""
 
-Author-provided text tooltip that tells users the expected action of this node.
+Author-provided prose that describes intended purpose of this node.
 
 #### Hints
 
-- Use spaces, make descriptions clear and readable. Many XML tools substitute XML character references automatically if needed (such as &amp;#38; for &amp; ampersand, or &amp;#34; for " quotation mark).
+- Include space characters since a *description* is not a DEF identifier. Write short phrases that make descriptions clear and readable.
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFBool [in, out] **enabled** TRUE
 
@@ -56,23 +61,25 @@ Help decide rotation behavior from initial relative bearing of pointer drag: acu
 
 #### Hint
 
-- DiskAngle 0 forces disk-like behavior, diskAngle 1.570796 (90 degrees) forces cylinder-like behavior.
+- *diskAngle* 0 forces disk-like behavior, *diskAngle* 1.570796 (90 degrees) forces cylinder-like behavior.
 
 ### SFFloat [in, out] **minAngle** 0 <small>[-2π,2π]</small>
 
 Clamps rotation_changed events within range of min/max values
 
-#### Hint
+#### Hints
 
-- If minAngle \> maxAngle, rotation is not clamped.
+- If *minAngle* \> maxAngle, rotation is not clamped.
+- [Radian units for angular measure](https://en.wikipedia.org/wiki/Radian){:target="_blank"}
 
 ### SFFloat [in, out] **maxAngle** -1 <small>[-2π,2π]</small>
 
 Clamps rotation_changed events within range of min/max values
 
-#### Hint
+#### Hints
 
-- If minAngle \> maxAngle, rotation is not clamped.
+- If minAngle \> *maxAngle*, rotation is not clamped.
+- [Radian units for angular measure](https://en.wikipedia.org/wiki/Radian){:target="_blank"}
 
 ### SFFloat [in, out] **offset** 0 <small>(-∞,∞)</small>
 
@@ -90,33 +97,51 @@ Determines whether previous offset values are remembered/accumulated.
 
 *trackPoint_changed* events give intersection point of bearing with sensor's virtual geometry.
 
+#### Warnings
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+- *trackPoint_changed* events represent unclamped intersection points on plane surface. Browsers can interpret drags off of the surface in various ways. Note that translation_changed events are clamped by minPosition/maxPosition and thus may be preferable.
+
 ### SFRotation [out] **rotation_changed**
 
 *rotation_changed* events equal sum of relative bearing changes plus offset value about Y-axis in local coordinate system.
 
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
 ### SFBool [out] **isOver**
 
-Hover over geometry by aiming the mouse (or pointing device) to generate isOver events. Sensor sends output event isOver=true event when pointing device moves over sensor's geometry, and later sends output event isOver=false event when pointing device moves off.
+Hover over geometry by aiming the mouse (or pointing device) to generate *isOver* events. Sensor sends output event *isOver*=true event when pointing device moves over sensor's geometry, and later sends output event *isOver*=false event when pointing device moves off.
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
 ### SFBool [out] **isActive**
 
-Select geometry by activating the pointing device (e.g. clicking the mouse) to generate isActive events. Output event isActive=true is sent when geometry is selected (e.g. when primary mouse button is pressed), output event isActive=false is sent when geometry is deselected (e.g. when primary mouse button is released).
+Select geometry by activating the pointing device (for example, clicking the mouse) to generate *isActive* events. Output event *isActive*=true is sent when geometry is selected (for example, when primary mouse button is pressed), output event *isActive*=false is sent when geometry is deselected (for example, when primary mouse button is released).
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
-## Description
+## Advisories
 
 ### Hints
 
 - This sensor detects user interactions affecting peer nodes and their child geometry.
 - Add semi-transparent surrounding geometry to see the effect of the sensor.
 - Initial relative bearing of pointer drag determines whether cylinder sides or end-cap disks are used for manipulation.
+- [X3D Architecture 20.2.1 Overview of pointing device sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#OverviewOfPointingDeviceSensors){:target="_blank"}
+- [X3D Architecture 20.2.2 Drag sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#DragSensors){:target="_blank"}
+- [X3D Architecture 20.2.3 Activating and manipulating pointing device sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#Activatingandmanipulating){:target="_blank"}
+- [Example scenes and authoring assets](https://x3dgraphics.com/examples/X3dForWebAuthors/Chapter08UserInteractivity){:target="_blank"}
 
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/PointingDeviceSensor/CylinderSensor/CylinderSensor.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of CylinderSensor](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#CylinderSensor){:target="_blank"}
-- [See X3D Specification 20.2.1 Overview of pointing device sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#OverviewOfPointingDeviceSensors){:target="_blank"}
-- [See X3D Specification 20.2.2 Drag sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#DragSensors){:target="_blank"}
-- [See X3D Specification 20.2.3 Activating and manipulating pointing device sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#Activatingandmanipulating){:target="_blank"}
+- [X3D Specification of CylinderSensor node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#CylinderSensor){:target="_blank"}

package/docs/_posts/components/PointingDeviceSensor/PlaneSensor.md

@@ -1,6 +1,6 @@
 ---
 title: PlaneSensor
-date: 2022-01-07
+date: 2023-01-07
 nav: components-PointingDeviceSensor
 categories: [components, PointingDeviceSensor]
 tags: [PlaneSensor, PointingDeviceSensor]
@@ -15,7 +15,7 @@ tags: [PlaneSensor, PointingDeviceSensor]
 
 PlaneSensor converts pointing device motion into 2D translation parallel to the local Z=0 plane.
 
-The PlaneSensor node belongs to the **PointingDeviceSensor** component and its default container field is *children.* It is available since X3D version 2.0 or later.
+The PlaneSensor node belongs to the **PointingDeviceSensor** component and its default container field is *children.* It is available from X3D version 2.0 or higher.
 
 ## Hierarchy
 
@@ -32,15 +32,20 @@ The PlaneSensor node belongs to the **PointingDeviceSensor** component and its d
 
 ### 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"}
 
 ### SFString [in, out] **description** ""
 
-Author-provided text tooltip that tells users the expected action of this node.
+Author-provided prose that describes intended purpose of this node.
 
 #### Hints
 
-- Use spaces, make descriptions clear and readable. Many XML tools substitute XML character references automatically if needed (such as &amp;#38; for &amp; ampersand, or &amp;#34; for " quotation mark).
+- Include space characters since a *description* is not a DEF identifier. Write short phrases that make descriptions clear and readable.
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFBool [in, out] **enabled** TRUE
 
@@ -64,51 +69,69 @@ Sends event and remembers last value sensed.
 
 ### SFVec2f [in, out] **minPosition** 0 0 <small>(-∞,∞)</small>
 
-*minPosition* and maxPosition clamp translations to a range of values measured from origin of Z=0 plane default maxPosition \< minPosition means no clamping.
+*minPosition* and maxPosition clamp translations to a range of values measured from origin of Z=0 plane default maxPosition \< *minPosition* means no clamping.
 
 #### Hint
 
-- Create a LineSensor by constraining one axis (minPosition.x=maxPosition.x) or (minPosition.y=maxPosition.y).
+- Create a LineSensor by constraining one axis (*minPosition*.x=maxPosition.x) or (*minPosition*.y=maxPosition.y).
 
 ### SFVec2f [in, out] **maxPosition** -1 -1 <small>(-∞,∞)</small>
 
-MinPosition and maxPosition clamp translations to a range of values measured from origin of Z=0 plane default maxPosition \< minPosition means no clamping.
+MinPosition and *maxPosition* clamp translations to a range of values measured from origin of Z=0 plane default *maxPosition* \< minPosition means no clamping.
 
 #### Hint
 
-- Create a LineSensor by constraining one axis (minPosition.x=maxPosition.x) or (minPosition.y=maxPosition.y).
+- Create a LineSensor by constraining one axis (minPosition.x=*maxPosition*.x) or (minPosition.y=*maxPosition*.y).
 
 ### SFVec3f [out] **trackPoint_changed**
 
 *trackPoint_changed* events give intersection point of bearing with sensor's virtual geometry.
 
+#### Warnings
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+- *trackPoint_changed* events represent unclamped intersection points on plane surface. Browsers can interpret drags off of the surface in various ways. Note that translation_changed events are clamped by minPosition/maxPosition and thus may be preferable.
+
 ### SFVec3f [out] **translation_changed**
 
 *translation_changed* events equal sum of relative translation change plus offset value.
 
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
 ### SFBool [out] **isOver**
 
-Hover over geometry by aiming the mouse (or pointing device) to generate isOver events. Sensor sends output event isOver=true event when pointing device moves over sensor's geometry, and later sends output event isOver=false event when pointing device moves off.
+Hover over geometry by aiming the mouse (or pointing device) to generate *isOver* events. Sensor sends output event *isOver*=true event when pointing device moves over sensor's geometry, and later sends output event *isOver*=false event when pointing device moves off.
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
 ### SFBool [out] **isActive**
 
-Select geometry by activating the pointing device (e.g. clicking the mouse) to generate isActive events. Output event isActive=true is sent when geometry is selected (e.g. when primary mouse button is pressed), output event isActive=false is sent when geometry is deselected (e.g. when primary mouse button is released).
+Select geometry by activating the pointing device (for example, clicking the mouse) to generate *isActive* events. Output event *isActive*=true is sent when geometry is selected (for example, when primary mouse button is pressed), output event *isActive*=false is sent when geometry is deselected (for example, when primary mouse button is released).
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
-## Description
+## Advisories
 
 ### Hints
 
 - Create a LineSensor by constraining one axis: (minPosition.x=maxPosition.x) or (minPosition.y=maxPosition.y).
 - This sensor detects user interactions affecting peer nodes and their child geometry.
 - Add semi-transparent surrounding geometry to see the effect of the sensor.
+- [X3D Architecture 20.2.1 Overview of pointing device sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#OverviewOfPointingDeviceSensors){:target="_blank"}
+- [X3D Architecture 20.2.2 Drag sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#DragSensors){:target="_blank"}
+- [X3D Architecture 20.2.3 Activating and manipulating pointing device sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#Activatingandmanipulating){:target="_blank"}
+- [Example scenes and authoring assets](https://x3dgraphics.com/examples/X3dForWebAuthors/Chapter08UserInteractivity){:target="_blank"}
 
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/PointingDeviceSensor/PlaneSensor/PlaneSensor.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of PlaneSensor](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#PlaneSensor){:target="_blank"}
-- [See X3D Specification 20.2.1 Overview of pointing device sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#OverviewOfPointingDeviceSensors){:target="_blank"}
-- [See X3D Specification 20.2.2 Drag sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#DragSensors){:target="_blank"}
-- [See X3D Specification 20.2.3 Activating and manipulating pointing device sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#Activatingandmanipulating){:target="_blank"}
+- [X3D Specification of PlaneSensor node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#PlaneSensor){:target="_blank"}

package/docs/_posts/components/PointingDeviceSensor/SphereSensor.md

@@ -1,6 +1,6 @@
 ---
 title: SphereSensor
-date: 2022-01-07
+date: 2023-01-07
 nav: components-PointingDeviceSensor
 categories: [components, PointingDeviceSensor]
 tags: [SphereSensor, PointingDeviceSensor]
@@ -15,7 +15,7 @@ tags: [SphereSensor, PointingDeviceSensor]
 
 SphereSensor converts pointing device motion into a spherical rotation about the origin of the local coordinate system.
 
-The SphereSensor node belongs to the **PointingDeviceSensor** component and its default container field is *children.* It is available since X3D version 2.0 or later.
+The SphereSensor node belongs to the **PointingDeviceSensor** component and its default container field is *children.* It is available from X3D version 2.0 or higher.
 
 ## Hierarchy
 
@@ -32,15 +32,20 @@ The SphereSensor node belongs to the **PointingDeviceSensor** component and its
 
 ### 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"}
 
 ### SFString [in, out] **description** ""
 
-Author-provided text tooltip that tells users the expected action of this node.
+Author-provided prose that describes intended purpose of this node.
 
 #### Hints
 
-- Use spaces, make descriptions clear and readable. Many XML tools substitute XML character references automatically if needed (such as &amp;#38; for &amp; ampersand, or &amp;#34; for " quotation mark).
+- Include space characters since a *description* is not a DEF identifier. Write short phrases that make descriptions clear and readable.
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFBool [in, out] **enabled** TRUE
 
@@ -62,28 +67,45 @@ Sends event and remembers last value sensed.
 
 *trackPoint_changed* events give intersection point of bearing with sensor's virtual geometry.
 
+#### Warnings
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+- *trackPoint_changed* events represent unclamped intersection points on plane surface. Browsers can interpret drags off of the surface in various ways. Note that translation_changed events are clamped by minPosition/maxPosition and thus may be preferable.
+
 ### SFRotation [out] **rotation_changed**
 
 *rotation_changed* events equal sum of relative bearing changes plus offset value.
 
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
 ### SFBool [out] **isOver**
 
-Hover over geometry by aiming the mouse (or pointing device) to generate isOver events. Sensor sends output event isOver=true event when pointing device moves over sensor's geometry, and later sends output event isOver=false event when pointing device moves off.
+Hover over geometry by aiming the mouse (or pointing device) to generate *isOver* events. Sensor sends output event *isOver*=true event when pointing device moves over sensor's geometry, and later sends output event *isOver*=false event when pointing device moves off.
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
 ### SFBool [out] **isActive**
 
-Select geometry by activating the pointing device (e.g. clicking the mouse) to generate isActive events. Output event isActive=true is sent when geometry is selected (e.g. when primary mouse button is pressed), output event isActive=false is sent when geometry is deselected (e.g. when primary mouse button is released).
+Select geometry by activating the pointing device (for example, clicking the mouse) to generate *isActive* events. Output event *isActive*=true is sent when geometry is selected (for example, when primary mouse button is pressed), output event *isActive*=false is sent when geometry is deselected (for example, when primary mouse button is released).
+
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
-## Description
+## Advisories
 
 ### Hints
 
 - This sensor detects user interactions affecting peer nodes and their child geometry.
 - Add semi-transparent surrounding geometry to see the effect of the sensor.
+- [X3D Architecture 20.2.1 Overview of pointing device sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#OverviewOfPointingDeviceSensors){:target="_blank"}
+- [X3D Architecture 20.2.2 Drag sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#DragSensors){:target="_blank"}
+- [X3D Architecture 20.2.3 Activating and manipulating pointing device sensors](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/pointingDeviceSensor.html#Activatingandmanipulating){:target="_blank"}
 
-## External Links
+## See Also
 
-- [X3D Specification of SphereSensor](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#SphereSensor){:target="_blank"}
-- [See X3D Specification 20.2.1 Overview of pointing device sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#OverviewOfPointingDeviceSensors){:target="_blank"}
-- [See X3D Specification 20.2.2 Drag sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#DragSensors){:target="_blank"}
-- [See X3D Specification 20.2.3 Activating and manipulating pointing device sensors](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#Activatingandmanipulating){:target="_blank"}
+- [X3D Specification of SphereSensor node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/pointingDeviceSensor.html#SphereSensor){:target="_blank"}