x_ite 4.0.5 → 4.7.5

package/docs/tutorials/Controlling-how-textures-are-mapped.md

@@ -0,0 +1,277 @@
+# Controlling How Textures are Mapped
+
+## Motivation
+
+- By default, an entire texture image is mapped once around the shape
+- You can also:
+  - Extract only pieces of interest
+  - Create repeating patterns
+
+## Working through the texturing process
+
+- Imagine the texture image is a big piece of rubbery cookie dough
+- Select a texture image piece
+  - Define the shape of a cookie cutter
+  - Position and orient the cookie cutter
+  - Stamp out a piece of texture dough
+- Stretch the rubbery texture cookie to fit a face
+
+## Using texture coordinate system
+
+Texture images (the dough) are in a texture coordinate system:
+
+- **S** - direction is horizontal
+- **T** - direction is vertical
+- (0,0) at lower-left
+- (1,1) at upper-right
+
+## Specifying texture coordinates
+
+Texture coordinates and texture coordinate indexes specify a texture piece shape (the cookie cutter):
+
+|                        | Coordinates                     |
+|------------------------|---------------------------------|
+| ![Texture Mapping 1][] | 0.0 0.0 1.0 0.0 1.0 1.0 0.0 1.0 |
+
+  [Texture Mapping 1]: https://create3000.github.io/media/tutorials/images/texture-mapping-1.png
+
+## Applying texture transforms
+
+Texture transforms translate, rotate, and scale the texture coordinates (placing the cookie cutter):
+
+|                        |                        |
+|------------------------|------------------------|
+| ![Texture Mapping 2][] | ![Texture Mapping 3][] |
+
+  [Texture Mapping 2]: https://create3000.github.io/media/tutorials/images/texture-mapping-2.png
+  [Texture Mapping 3]: https://create3000.github.io/media/tutorials/images/texture-mapping-3.png
+
+## Texturing a face
+
+Bind the texture to a face (stretch the cookie and stick it):
+
+|               |               |
+|---------------|---------------|
+| ![Cookie 1][] | ![Cookie 2][] |
+
+  [Cookie 1]: https://create3000.github.io/media/tutorials/images/cookie-1.png
+  [Cookie 2]: https://create3000.github.io/media/tutorials/images/cookie-2.png
+
+## Working through the texturing process
+
+- Select piece with texture coordinates and indexes
+  - Create a cookie cutter
+- Transform the texture coordinates
+  - Position and orient the cookie cutter
+- Bind the texture to a face
+  - Stamp out the texture and stick it on a face
+- The process is very similar to creating faces!
+
+## Syntax: TextureCoordinate
+
+A [TextureCoordinate](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#TextureCoordinate) node contains a list of texture coordinates:
+
+### XML Encoding
+
+```xml
+<TextureCoordinate
+    point='0.2 0.2, 0.8 0.2, ...'/>
+```
+
+### Classic Encoding
+
+```js
+TextureCoordinate {
+  point [ 0.2 0.2, 0.8 0.2, ... ]
+}
+```
+
+Used as the *texCoord* field value of [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) or [ElevationGrid](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#ElevationGrid) nodes.
+
+## 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:
+
+- texCoord and texCoordIndex - specify texture pieces
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <IndexedFaceSet
+      texCoordIndex='...'
+      coordIndex='...'>
+    <TextureCoordinate ... />
+    <Coordinate ... />
+  </IndexedFaceSet>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry IndexedFaceSet {
+    texCoordIndex [ ... ]
+    coordIndex [ ... ]
+    texCoord TextureCoordinate { ... }
+    coord Coordinate { ... }
+  }
+}
+```
+
+## Syntax: ElevationGrid
+
+An [ElevationGrid](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#ElevationGrid) geometry node creates terrains:
+
+- *texCoord* - specify texture pieces
+- Automatically generated texture coordinate indexes
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --></Appearance>
+  <ElevationGrid
+      height='...'>
+    <TextureCoordinate ... />
+  </ElevationGrid>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry ElevationGrid {
+    texCoord TextureCoordinate { ... }
+    height [ ... ]
+  }
+}
+```
+
+## Syntax: Appearance
+
+An [Appearance](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shape.html#Appearance) node describes overall shape appearance:
+
+- *textureTransform* - transform
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material ... />
+    <ImageTexture ... />
+    <TextureTransform ... />
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { ... }
+    texture ImageTexture { ... }
+    textureTransform TextureTransform { ... }
+  }
+  geometry ...
+}
+```
+
+## Syntax: TextureTransform
+
+A [TextureTransform](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/texturing.html#TextureTransform) node transforms texture coordinates:
+
+- *translation* - position
+- *rotation* - orientation
+- *scale* - size
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material ... />
+    <ImageTexture ... />
+    <TextureTransform
+        translation='0.0 0.0'
+        rotation='0.0'
+        scale='1.0 1.0'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { ... }
+    texture ImageTexture { ... }
+    textureTransform TextureTransform {
+      translation 0.0 0.0
+      rotation    0.0
+      scale       1.0 1.0
+    }
+  }
+  geometry ...
+}
+```
+
+## Scaling, rotating, and translating
+
+Scale, Rotate, and Translate a texture cookie cutter one after the other:
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance>
+    <Material ... />
+    <ImageTexture ... />
+    <TextureTransform
+        translation='0.0 0.0'
+        rotation='0.785'
+        scale='8.5 8.5'/>
+  </Appearance>
+  <!-- geometry ... -->
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance {
+    material Material { ... }
+    texture ImageTexture { ... }
+    textureTransform TextureTransform {
+      translation 0.0 0.0
+      rotation    0.785
+      scale       8.5 8.5
+    }
+  }
+  geometry ...
+}
+```
+
+Read texture transform operations top-down:
+
+- The cookie cutter is translated, rotated, then scaled
+  Order is fixed, independent of field order
+- This is the reverse of a Transform node
+
+## Summary
+
+- Texture images are in a texture coordinate system
+- Texture coordinates and indexes describe a texture cookie cutter
+- Texture transforms translate, rotate, and scale place the cookie cutter
+- Texture indexes bind the cut-out cookie texture to a face on a shape

package/docs/tutorials/Controlling-navigation.md

@@ -0,0 +1,70 @@
+# Controlling Navigation
+
+## Motivation
+
+- Different types of worlds require different styles of navigation
+  - Walk through a dungeon
+  - Fly through a cloud world
+  - Examine shapes in a CAD application
+- You can select the navigation type
+- You can describe the size and speed of the viewer's avatar
+
+## Selecting navigation types
+
+There are five standard navigation keywords:
+
+- **WALK** - walk, pulled down by gravity
+- **FLY** - fly, unaffected by gravity
+- **EXAMINE** - examine an object at "arms length"
+- **NONE** - no navigation, movement controlled by world not viewer!
+- **ANY** - allows user to change navigation type
+
+Some browsers support additional navigation types.
+
+## Specifying avatars
+
+- Avatar size (width, height, step height) and speed can be specified
+
+## Controlling the headlight
+
+- By default, a headlight is placed on the avatar's head and aimed in the head direction
+- You can turn this headlight on and off
+  - Most browsers provide a menu option to control the headlight
+  - You can also control the headlight with the [NavigationInfo](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#NavigationInfo) node
+
+## Syntax: NavigationInfo
+
+A [NavigationInfo](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#NavigationInfo) node selects the navigation type and avatar characteristics:
+
+- *type* - navigation style
+- *avatarSize* and speed - avatar characteristics
+- *headlight* - headlight on or off
+
+### XML Encoding
+
+```xml
+<NavigationInfo
+  type='"WALK", "ANY"'
+  avatarSize='0.25, 1.6, 0.75'
+  speed='1.0'
+  headlight='true'/>
+```
+
+### Classic Encoding
+
+```js
+NavigationInfo {
+  type       [ "WALK", "ANY" ]
+  avatarSize [ 0.25, 1.6, 0.75 ]
+  speed      1.0
+  headlight  TRUE
+}
+```
+
+## Summary
+
+The navigation type specifies how a viewer can move in a world:
+
+- walk, fly, examine, or none
+
+The avatar overall size and speed specify the viewer's avatar characteristics.

package/docs/tutorials/Controlling-shading-on-coordinate-based-geometry.md

@@ -0,0 +1,180 @@
+# Controlling Shading on Coordinate-Based Geometry
+
+## Motivation
+
+- When shaded, the faces on a shape are obvious
+- To create a smooth shape you can use a large number of small faces
+  - Requires lots of faces, disk space, memory, and drawing time
+- Instead, use smooth shading to create the illusion of a smooth shape, but with a small number of faces
+
+## Controlling shading using the crease angle
+
+By default, faces are drawn with faceted shading.
+
+You can enable smooth shading using the creaseAngle field for:
+
+- [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet)
+- [ElevationGrid](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#ElevationGrid)
+- [Extrusion](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#Extrusion)
+
+## Selecting crease angles
+
+A crease angle is a threshold angle between two faces:
+
+- If face angle >= crease angle, use facet shading
+- If face angle < crease angle, use smooth shading
+
+## Using normals
+
+A normal vector indicates the direction a face is facing
+
+- If it faces a light, the face is shaded bright
+
+By default, normals are automatically generated by the X3D browser:
+
+- You can specify your own normals with a [Normal](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Normal) node
+- Usually automatically generated normals are good enough
+
+## Syntax: Normal
+
+A Normal node contains a list of normal vectors that override use of a crease angle.
+
+### XML Encoding
+
+```xml
+<Normal
+    vector='0.0 1.0 0.0, ...'/>
+```
+
+### Classic Encoding
+
+```js
+Normal {
+  vector [ 0.0 1.0 0.0, ... ]
+}
+```
+
+Normals can be given for [IndexedFaceSet](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#IndexedFaceSet) and [ElevationGrid](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#ElevationGrid) nodes.
+
+## 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:
+
+- *normal* - list of normals
+- *normalIndex* - selects normals from list
+- *normalPerVertex* - control normal binding
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --><Appearance>
+  <IndexedFaceSet
+      normalPerVertex='true'
+      normalIndex='...'
+      coordIndex='...'>
+    <Normal ... />
+    <Coordinate ... />
+  </IndexedFaceSet>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry IndexedFaceSet {
+    normalPerVertex TRUE
+    normalIndex [ ... ]
+    coordIndex [ ... ]
+    normal Normal { ... }
+    coord Coordinate { ... }
+  }
+}
+```
+
+## Controlling normal binding for face sets
+
+The *normalPerVertex* field controls how normal indexes are used
+
+- **FALSE:** one normal index to each face (ending at -1 coordinate indexes)
+- **TRUE:** one normal index to each coordinate index of each face (including -1 coordinate indexes)
+
+## Syntax: ElevationGrid
+
+An [ElevationGrid](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/geometry3D.html#ElevationGrid) geometry node creates terrains:
+
+- *normal* - list of normals
+- *normalPerVertex* - control normal binding
+- Always binds one normal to each grid point or square, in order
+
+### XML Encoding
+
+```xml
+<Shape>
+  <Appearance><!-- ... --><Appearance>
+  <ElevationGrid
+      normalPerVertex='true'
+      height='...'>
+    <Normal ... />
+  </ElevationGrid>
+</Shape>
+```
+
+### Classic Encoding
+
+```js
+Shape {
+  appearance Appearance { ... }
+  geometry ElevationGrid {
+    normalPerVertex TRUE
+    normal Normal { ... }
+    height [ ... ]
+  }
+}
+```
+
+## Controlling normal binding for elevation grids
+
+The *normalPerVertex* field controls how normal indexes are used (similar to face sets):
+
+- **FALSE:** one normal to each grid square
+- **TRUE:** one normal to each height for each grid square
+
+## Syntax: NormalInterpolator
+
+A [NormalInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#NormalInterpolator) node describes a normal set:
+
+- *keys* - key fractions
+- *keyValues* - key normal lists (X,Y,Z lists)
+- Interpolates lists of normals, similar to the [CoordinateInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#CoordinateInterpolator)
+
+### XML Encoding
+
+```xml
+<NormalInterpolator
+    key='0.0, ...'
+    keyValue='0.0 1.0 1.0, ...'/>
+```
+
+### Classic Encoding
+
+```js
+NormalInterpolator {
+  key [ 0.0, ... ]
+  keyValue [ 0.0 1.0 1.0, ... ]
+}
+```
+
+Typically route into a [Normal](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Normal) node's set\_vector input.
+
+## Summary
+
+- The *creaseAngle* field controls faceted or smooth shading
+- The [Normal](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/rendering.html#Normal) node lists normal vectors to use for parts of a shape
+  - Used as the value of the normal field
+  - Normal indexes select normals to use
+- Normals override *creaseAngle* value
+- The *normalPerVertex* field selects normal per face/grid square or normal per coordinate
+- The [NormalInterpolator](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/interp.html#NormalInterpolator) node converts times to normals

package/docs/tutorials/Controlling-the-viewpoint.md

@@ -0,0 +1,49 @@
+# Controlling the Viewpoint
+
+## Motivation
+
+- By default, the viewer enters a world at (0.0, 0.0, 10.0)
+- You can provide your own preferred view points
+  - Select the entry point position
+  - Select favorite views for the viewer
+  - Name the views for a browser menu
+
+## Creating viewpoints
+
+- Viewpoints specify a desired location, an orientation, and a camera field of view lens angle
+- Viewpoints can be transformed using a Transform node
+- The first viewpoint found in a file is the entry point
+
+## Syntax: Viewpoint
+
+A [Viewpoint](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Viewpoint) node specifies a named viewing location:
+
+- *position* and *orientation* - viewing location
+- *fieldOfView* - camera lens angle
+- *description* - description for viewpoint menu
+
+### XML Encoding
+
+```xml
+<Viewpoint
+    position='0.0 0.0 10.0'
+    orientation='0.0 0.0 1.0 0.0'
+    fieldOfView='0.785'
+    description='Entry View'/>
+```
+
+### Classic Encoding
+
+```js
+Viewpoint {
+  position  0.0 0.0 10.0
+  orientation 0.0 0.0 1.0 0.0
+  fieldOfView 0.785
+  description "Entry View"
+}
+```
+
+## Summary
+
+- Specify favorite viewpoints in [Viewpoint](https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/navigation.html#Viewpoint) nodes
+- The first viewpoint in the file is the entry viewpoint