x_ite 4.0.5 → 4.7.5

package/docs/tutorials/Building-extruded-shapes.md

@@ -0,0 +1,145 @@
+# Build Extruded Shapes
+
+## Motivation
+
+Extruded shapes are very common
+
+- Tubes, pipes, bars, vases, donuts
+- Other tricky uses...
+
+How can you do it:
+
+- You can build extruded shapes using an [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) node.
+- You can build extruded shapes more easily and efficiently using an [Extrusion](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Extrusion) node.
+
+## Creating extruded shapes
+
+Extruded shapes are described by:
+
+- A 2-D cross-section
+- A 3-D spine along which to sweep the cross-section
+
+Extruded shapes are like long bubbles created with a bubble wand:
+
+- The bubble wand's outline is the cross-section
+- The path along which you swing the wand is the spine
+
+## Syntax: Extrusion
+
+An [Extrusion](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Extrusion) geometry node creates extruded geometry:
+
+- *crossSection* - 2-D cross-section
+- *spine* - 3-D sweep path
+- *endCap* and *beginCap* - cap ends
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <Extrusion
+      crossSection='...'
+      spine='...'
+      endCap='true'
+      beginCap='true'
+      ... />
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry Extrusion {
+    crossSection [ ... ]
+    spine [ ...  ]
+    endCap TRUE
+    beginCap TRUE
+    ...
+  }
+}
+```
+
+An [Extrusion](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Extrusion) geometry node creates extruded geometry:
+
+- *solid* - shape is solid
+- *ccw* - faces are counter-clockwise
+- *convex* - faces are convex
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <Extrusion
+      ...
+      solid='true'
+      ccw='true'
+      convex='true'/>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry Extrusion {
+    ...
+    solid TRUE
+    ccw TRUE
+    convex TRUE
+  }
+}
+```
+
+## Squishing and twisting extruded shapes
+
+You can scale the cross-section along the spine:
+
+- Vases, musical instruments
+- Surfaces of revolution
+
+You can rotate the cross-section along the spine
+
+- Twisting ribbons
+
+## Syntax: Extrusion
+
+An [Extrusion](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Extrusion) geometry node creates geometry using:
+
+- *scale* - cross-section scaling per spine point
+- *orientation* - cross-section rotation per spine point
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <Extrusion
+      ...
+      scale='...'
+      orientation='...'/>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry Extrusion {
+    ...
+    scale [ ... ]
+    orientation [ ... ]
+  }
+}
+```
+
+## Summary
+
+- An [Extrusion](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Extrusion) node efficiently creates extruded shapes
+- The *crossSection* field specifies the cross-section
+- The *spine* field specifies the sweep path
+- The *scale* and *orientation* fields specify scaling and rotation at each spine point

package/docs/tutorials/Building-primitive-shapes.md

@@ -0,0 +1,204 @@
+# Building Primitive Shapes
+
+## Motivation
+
+Shapes are the building blocks of a X3D world. Primitive Shapes are standard building blocks:
+
+- [Box](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Box)
+- [Cone](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Cone)
+- [Cylinder](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Cylinder)
+- [Sphere](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Sphere)
+- [Text](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/text.html#Text)
+- and more from the [CADGeometry](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/CADGeometry.html)**,** [Geometry2D](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry2D.html)**,** and [Rendering](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html) component
+
+## Syntax: Shape
+
+- A [Shape](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Shape) node builds a shape
+  - *appearance* - color and texture
+  - *geometry* - form, or structure
+
+### XML Encoding
+
+```xml
+<Shape>
+  <!-- appearance ... -->
+  <!-- geometry ... -->
+<Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance ...
+  geometry ...
+}
+```
+
+## Specifying appearance
+
+- [Shape](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Shape) appearance is described by appearance nodes
+- For now, we'll use nodes to create a shaded white appearance:
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { }
+  }
+  geometry ...
+}
+```
+
+## Specifying geometry
+
+[Shape](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Shape) geometry is built with geometry nodes:
+
+### XML Encoding
+
+```xml
+<Box ... />
+<Cone ... />
+<Cylinder ... />
+<Sphere ... />
+<Text ... />
+```
+
+### Classic Encoding
+
+```js
+Box { ... }
+Cone { ... }
+Cylinder { ... }
+Sphere { ... }
+Text { ... }
+```
+
+- Geometry node fields control dimensions
+  - Dimensions usually in meters, but can be anything
+
+## A sample primitive shape
+
+### XML Encoding
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+
+<X3D profile='Full' version='3.3' xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance' xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.3.xsd'>
+  <Scene>
+    <Shape>
+      <Appearance>
+        <Material/>
+      </Appearance>
+      <Cylinder
+          radius='1.5'/>
+    </Shape>
+  </Scene>
+</X3D>
+```
+
+### Classic Encoding
+
+```js
+#X3D V3.3 utf8
+# A cylinder
+Shape {
+  appearance Appearance {
+    material Material { }
+  }
+  geometry Cylinder {
+    height 2.0
+    radius 1.5
+  }
+}
+```
+
+[![Cylinder](https://create3000.github.io/media/tutorials/scenes/cylinder1/screenshot.png)](https://create3000.github.io/media/tutorials/scenes/cylinder1/example.html)
+
+[View scene in this window.](https://create3000.github.io/media/tutorials/scenes/cylinder1/example.html)
+
+[Download ZIP Archive](https://create3000.github.io/media/tutorials/scenes/cylinder1/cylinder1.zip)
+
+## Building multiple shapes
+
+- Shapes are built centered in the world
+- A X3D file can contain multiple shapes
+- Shapes overlap when built at the same location
+
+## A sample file with multiple shapes
+
+### XML Encoding
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+
+<X3D profile='Full' version='3.3' xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance' xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.3.xsd'>
+  <Scene>
+    <Shape>
+      <Appearance>
+        <Material/>
+      </Appearance>
+      <Box
+          size='1 1 1'/>
+    </Shape>
+    <Shape>
+      <Appearance>
+        <Material/>
+      </Appearance>
+      <Sphere
+          radius='0.7'/>
+    </Shape>
+    <!-- ... -->
+  </Scene>
+</X3D>
+```
+
+### Classic Encoding
+
+```js
+#X3D V3.3 utf8
+
+Shape {
+  appearance Appearance {
+    material Material { }
+  }
+  geometry Box {
+    size 1.0 1.0 1.0
+  }
+}
+
+Shape {
+  appearance Appearance {
+    material Material { }
+  }
+  geometry Sphere {
+    radius 0.7
+  }
+}
+
+...
+```
+
+[![Multiple Shapes](https://create3000.github.io/media/tutorials/scenes/multiple-shapes/screenshot.png)](https://create3000.github.io/media/tutorials/scenes/multiple-shapes/example.html)
+
+[View scene in this window.](https://create3000.github.io/media/tutorials/scenes/multiple-shapes/example.html)
+
+[Download ZIP Archive](https://create3000.github.io/media/tutorials/scenes/multiple-shapes/multiple-shapes.zip)
+
+## Summary
+
+- Shapes are built using a [Shape](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Shape) node
+- [Shape](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Shape) geometry is built using geometry nodes, such as [Box](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Box), [Cone](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Cone), [Cylinder](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Cylinder), [Sphere](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Sphere), and [Text](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/text.html#Text)
+- Text fonts are controlled using a [FontStyle](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/text.html#FontStyle) node

package/docs/tutorials/Building-shapes-out-of-points,-lines,-and-faces.md

@@ -0,0 +1,311 @@
+
+# Building Shapes out of Points, Lines, and Faces
+
+## Motivation
+
+Complex shapes are hard to build with primitive shapes:
+
+- TerrainAnimals
+- Plants
+- Machinery
+
+Instead, build shapes out of atomic components:
+
+- Points, lines, and faces
+
+## Building shapes using coordinates
+
+Shape building is like a 3-D connect-the-dots game:
+
+- Place dots at 3-D locations
+- Connect-the-dots to form shapes
+
+A coordinate specifies a 3-D dot location. Measured relative to a coordinate system origin. A geometry node specifies how to connect the dots.
+
+## Syntax: Coordinate
+
+A [Coordinate](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Coordinate) node contains a list of coordinates for use in building a shape.
+
+### XML Encoding
+
+```xml
+<!-- X Y Z -->
+<Coordinate
+    point='2.0 1.0 3.0, 4.0 2.5 5.3, ...'/>
+```
+
+### Classic Encoding
+
+```js
+Coordinate {
+  point [
+   #X   Y   Z
+    2.0 1.0 3.0,
+    4.0 2.5 5.3,
+    ...
+  ]
+}
+```
+
+## Using geometry coordinates
+
+Build coordinate-based shapes using geometry nodes:
+
+- [PointSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#PointSet)
+- [IndexedLineSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#IndexedLineSet)
+- [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet)
+
+For all three nodes, use a [Coordinate](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Coordinate) node as the value of the coord field.
+
+## Syntax: PointSet
+
+A [PointSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#PointSet) geometry node creates geometry out of points:
+
+- One point (a dot) is placed at each coordinate
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <PointSet>
+    <Coordinate
+        point='...'/>
+  </PointSet>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry PointSet {
+    coord Coordinate {
+      point [  ...  ]
+    }
+  }
+}
+```
+
+## Syntax: IndexedLineSet
+
+An [IndexedLineSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#IndexedLineSet) geometry node creates geometry out of lines:
+
+- A straight line is drawn between pairs of selected coordinates
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <IndexedLineSet
+      coordIndex='...'>
+    <Coordinate>
+        point='...'/>
+  </IndexedLineSet>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry  IndexedLineSet {
+    coordIndex [ ... ]
+    coord Coordinate {
+      point [ ... ]
+    }
+  }
+}
+```
+
+## Using line set coordinate indexes
+
+Each coordinate in a [Coordinate](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Coordinate) node is implicitly numbered
+
+- Index 0 is the first coordinate
+- Index **1** is the second coordinate, etc.
+
+To build a line shape:
+
+- Make a list of coordinates, using their indexes
+- List coordinate indexes in the *coordIndex* field of the [IndexedLineSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#IndexedLineSet) node
+
+A line is drawn between pairs of coordinate indexes:
+
+- **-1** marks a break in the line
+- A line is not automatically drawn from the last index back to the first
+
+|                                                |                                 |
+|------------------------------------------------|---------------------------------|
+| *coordIndex* \[ 1, 0, 3, 8, -1, 5, 9, 0, -1 \] |                                 |
+| 1, 0, 3, 8,                                    | Draw line from 1 to 0 to 3 to 8 |
+| -1,                                            | End line, start next            |
+| 5, 9, 0                                        | Draw line from 5 to 9 to 0      |
+
+## Syntax: IndexedFaceSet
+
+An [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) geometry node creates geometry out of faces:
+
+- A flat face (polygon) is drawn using an outline specified by coordinate indexes
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <IndexedFaceSet
+      coordIndex='...'>
+    <Coordinate>
+        point='...'/>
+  </IndexedFaceSet>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry IndexedFaceSet {
+    coordIndex [ ... ]
+    coord Coordinate {
+      point [  ...  ]
+    }
+  }
+}
+```
+
+## Using face set coordinate index lists
+
+To build a face shape
+
+- Make a list of coordinates, using their indexes
+- List coordinate indexes in the *coordIndex* field of the [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) node
+
+A triangle is drawn connecting sequences of coordinate indexes:
+
+- **-1** marks a break in the sequence
+- Each face is automatically closed, connecting the last index back to the first
+
+|                                                |                                      |
+|------------------------------------------------|--------------------------------------|
+| *coordIndex* \[ 1, 0, 3, 8, -1, 5, 9, 0, -1 \] |                                      |
+| 1, 0, 3, 8                                     | Draw face from 1 to 0 to 3 to 8 to 1 |
+| -1,                                            | End face, start next                 |
+| 5, 9, 0                                        | Draw face from 5 to 9 to 0 to 5      |
+| -1                                             | End face                             |
+
+## Syntax: IndexedFaceSet
+
+An [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) geometry node creates geometry out of faces:
+
+- *solid* - shape is solid
+- *ccw* - faces are counter-clockwise
+- *convex* - faces are convex
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <IndexedFaceSet
+      solid='true'
+      ccw='true'
+      convex='true'
+      coordIndex='...'>
+    <Coordinate ... />
+  </IndexedFaceSet>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry IndexedFaceSet {
+    solid TRUE
+    ccw TRUE
+    convex TRUE
+    coordIndex [ ... ]
+    coord Coordinate { ... }
+  }
+}
+```
+
+## Using shape control
+
+A solid shape is one where the insides are never seen:
+
+- If never seen, don't attempt to draw them
+- When *solid* **TRUE**, the back sides (inside) of faces are not drawn
+
+The front of a face has coordinates in counter-clockwise order:
+
+- When *ccw* **FALSE**, the other side is the front
+
+Faces are assumed to be convex
+
+- When *convex* **FALSE,** concave faces are automatically broken into multiple convex faces
+
+## Syntax: CoordinateInterpolator
+
+A [CoordinateInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#CoordinateInterpolator) node describes a coordinate path:
+
+- *keys* - key fractions
+- *keyValues* - key coordinate lists (X, Y, Z lists)
+
+### XML Encoding
+
+```xml
+<CoordinateInterpolator
+    key='0.0, ...'
+    keyValue='0.0 1.0 0.0, ...'/>
+```
+
+### Classic Encoding
+
+```js
+CoordinateInterpolator {
+  key [ 0.0, ... ]
+  keyValue [ 0.0 1.0 0.0, ... ]
+}
+```
+
+Typically route into a [Coordinate](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Coordinate) node's set\_point input.
+
+## Interpolating coordinate lists
+
+A [CoordinateInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#CoordinateInterpolator) node interpolates lists of coordinates:
+
+- Each output is a list of coordinates
+
+If n output coordinates are needed for t fractional times:
+
+- n × t coordinates are needed in the key value list
+
+## Summary
+
+- Shapes are built by connecting together coordinates
+- Coordinates are listed in a [Coordinate](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Coordinate) node
+- Coordinates are implicitly numbers starting at 0
+- Coordinate index lists give the order in which to use coordinates
+
+The [PointSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#PointSet) node draws a dot at every coordinate:
+
+- The *coord* field value is a Coordinate node
+
+The [IndexedLineSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#IndexedLineSet) node draws lines between coordinates:
+
+- The *coord* field value is a Coordinate node
+- The *coordIndex* field value is a list of coordinate indexes
+
+The [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) node draws faces outlined by coordinates:
+
+- The *coord* field value is a Coordinate node
+- The *coordIndex* field value is a list of coordinate indexes
+
+The [CoordinateInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#CoordinateInterpolator) node converts times to coordinates.