to X3D Resources
     

X3D Scene Authoring Hints

     
to Web3D home page

These hints provide a collection of style guidelines, authoring tips and best practices to improve the quality, consistency and maintainability of Extensible 3D (X3D) Graphics models.

Audio | Authoring | Color | containerField | Coordinate Systems, Rotations | Credits | Dates | Encodings | HTML | Images and Videos | Inlines and Prototypes | License | Meshes | meta Statements and Metadata Nodes | Motion Capture (MOCAP) | Naming Conventions | Scale Factors | Scripts (JavaJavaScriptJSON) | Strings | SVG | Tooltips | URL Links | Validation | Viewpoints and Navigation | Volumes | VRML | X3D‑Edit | X3D for Web Authors | X3D Resources | X3D Validator | Contact


🔖 Audio and Sound Tools to top


🔖 Authoring Practices to top


🔖 Color to top

Material


🔖 containerField to top

Each containerField value is the field name from the X3D Specification that indicates a contained node's relationship to its parent node.

Addition of containerField values only occurs in the XML encoding of .x3d scenes. For example: <Transform><Shape containerField='children'/></Transform> indicates that the Shape node is one of the children of the Transform node.

The X3D XML Schema, X3D DTD and X3D Tooltips each define all default containerField values, which are optional and typically can be omitted for scene terseness.

Disambiguation of parent-child field relationships is sometimes necessary, since a few parent nodes have more than one child field that can accept the same node type. In those ambiguous cases, the child node must have a correct containerField value in order to precisely define parent-child field relationships.

Specifically, care must be taken with the following non-default child containerField values.

🔖 Variations from containerField defaults to top

1. CADFace can contain a single Shape, LOD or Transform node with containerField='shape' (rather than default containerField='children').
2. CollidableShape can contain a single Shape node with containerField='shape' (rather than default containerField='children'). See containerFieldChoicesGroupLODShapeTransform.
3. Collision can contain a single nonrendered proxy Shape (or X3DGroupingNode) node with containerField='proxy' (rather than default containerField='children'). See containerFieldChoicesGroupLODShapeTransform.
4. ComposedCubeMapTexture can contain up to six X3DTexture2DNode (e.g. ImageTexture) nodes, each with a unique containerField value: back, bottom, front, left, right, or top (rather than default containerField='texture').
5. GeoLOD can contain multiple X3DChildNode nodes with containerField='rootNode'. Curiously GeoLOD is not allowed to have child nodes with default containerField='children' defined in a scene, since that field is defined differently with accessType outputOnly and thus is only able to send MFNode events at run time.
6. HAnimHumanoid can contain a single Group, LOD, Shape or Transform with containerField='skin' rather than default containerField='children'. See containerFieldChoicesGroupLODShapeTransform.
7. HAnimJoint       has default containerField='children' when parent is another HAnimJoint, and has containerField value of joints or skeleton when parent node is HAnimHumanoid.
8. HAnimSegment has default containerField='children' when parent node is an HAnimJoint, and has containerField='segments' when parent node is HAnimHumanoid.
9. HAnimSite        has default containerField='children' when parent node is an HAnimSegment, and has containerField value of sites, skeleton or viewpoints when parent node is HAnimHumanoid.
10. LoadSensor is a parent node that can monitor the loading of one or multiple child nodes having containerField='watchlist'. Such child nodes implement object interface X3DUrlObject and include Anchor, AudioClip, DISEntityTypeMapping, GeoMetadata, ImageCubeMapTexture, ImageTexture, ImageTexture3D, Inline, MovieTexture, PackagedShader, Script, ShaderPart and ShaderProgram.
11. MetadataSet can contain multiple other child X3DMetadataNode nodes by setting their containerField='value' (rather than default containerField='metadata'). Similar to the other metadata nodes, MetadataSet can also contain a single X3DMetadataNode node describing itself (with default containerField='metadata').
12. ParticleSystem can contain a single Color or ColorRGBA node with containerField='colorRamp' (rather than default containerField='color'). ParticleSystem can also contain a single TextureCoordinate node with containerField='texCoordRamp' (rather than default containerField='texCoord').
13. Sound can contain a single MovieTexture node with containerField='source' (rather than default containerField='texture').
14. TextureBackground can contain up to six X3DTexture2DNode (e.g. ImageTexture) nodes, each with unique containerField values: backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, or topTexture (rather than default containerField='texture').
15. X3DTexture3DNode nodes ComposedTexture3D, ImageTexture3D and PixelTexture3D nodes can have one of several containerField values, depending on relationship to parent node: texture (default), gradients, surfaceNormals, segmentIdentifiers, watchList (for ImageTexture3D with parent LoadSensor), or voxels.

All of the various X3D file encodings define parent-child relationships, in one way or another. The containerField attribute is used to express this relationship in the .x3d XML encoding. Since only a relatively small number of node usages ever require a non-default containerField value, the XML encoding is actually much more terse than other X3D encodings.

🔖 Validation choices for containerField to top

Quality Assurance (QA): the X3D Validator checks default and defined containerField values for logical correctness. Current work is showing that complete validation of all legal containerField values can be accomplished.

The following simple types are defined in X3D Schema and X3D DOCTYPE definitions to explicitly validate these allowed-value relationships.

  1. containerFieldChoicesAudioClip for AudioClip.
  2. containerFieldChoicesColor for Color, ColorRGBA.
  3. containerFieldChoicesDISEntityTypeMapping for DISEntityTypeMapping.
  4. containerFieldChoicesGroupLODShapeTransform for Group, LOD, Shape, Transform.
  5. containerFieldChoicesHAnimJoint for HAnimJoint
  6. containerFieldChoicesHAnimSegment for HAnimSegment.
  7. containerFieldChoicesHAnimSite for HAnimSite.
  8. containerFieldChoicesMetadata for six Metadata* nodes MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString, MetadataSet.
  9. containerFieldChoicesPackagedShader for PackagedShader.
  10. containerFieldChoicesShaderPart for ShaderPart.
  11. containerFieldChoicesTextureCoordinate for TextureCoordinate, TextureCoordinateGenerator.
  12. containerFieldChoicesX3DTexture2DNode for PixelTexture, MultiTexture.
  13. containerFieldChoicesX3DTexture3DNode for nodes with abstract type X3DTexture3DNode, namely ComposedTexture3D, ImageTexture3D, PixelTexture3D.
  14. containerFieldChoicesX3DUrlObject for non-texture nodes supporting abstract type X3DUrlObject, namely Anchor, GeoMetadata, Inline, Script.
  15. containerFieldChoicesX3dUrlObjectTexture for texture nodes supporting abstract type X3DUrlObject, namely ImageTexture, MovieTexture, ImageCubeMapTexture.

🔖 Potential future changes for improving containerField to top

Ongoing work for X3D Version 4 and X3D Unified Object Model (X3DUOM) makes a number of candidate optimizations possible and (perhaps) desirable. The following changes to SFNode/MFNode field names might reduce the number of containerField variations by more than half.

These changes will be considered by Web3D Consortium members with subsequent review by the X3D Community. Companies, institutions, agencies and individuals are invited to Join Web3D Consortium to participate and influence this important continuing evolution of X3D.


🔖 Coordinate Systems and Rotations to top


🔖 Credits to top


🔖 Cascading Style Sheets (CSS) to top

TODO


-->

🔖 Dates to top


🔖 Encodings to top

Do not allow a text editor to insert a Byte Order Mark (BOM) as the first character of a scene file. They are not included in the X3D specification and typically cause players to fail mysteriously.


🔖 HTML to top

HTML is the publishing language of the World Wide Web. HTML web pages can embed or launch X3D scenes.


🔖 Images and Videos to top


🔖 Inline Scenes and Prototype Templates to top


🔖 License to top


🔖 Meshes to top


🔖 meta Statements to top


🔖 Metadata Nodes to top


🔖 Motion Capture (MOCAP) to top

Motion capture (MOCAP) can be used for adding behaviors to Humanoid Animation (H-Anim) files).

BVH references

BVH tools


🔖 Naming Conventions to top

Naming of multiple similar autogenerated files: Concatenate the following name components as appropriate. Separate components by period characters, since underscores disappear as part of a url and since hyphens will break across a line.

General notes on naming conventions:


🔖 Scale Factors and Unit Conversions to top


🔖 Scripts to top


🔖 Strings: SFString/MFString Encodings to top

Strings describe text, typically for display in the Text node. SFString/MFString refers to single-field string values and multi-field string arrays, respectively.

The empty string "" represents a blank line in an MFString array.

Representation Specification Equivalent Value Example
Abstract Specification
(actual display value)
5.3.14 SFString and MFString One, Two, Three
He said, "Immel did it!"
index
XML encoding (.x3d) 5.3.14 SFString and MFString string='"One, Two, Three" "" "He said, \"Immel did it!\""'
or else various XML character-entity substitution alternatives such as

string='"One, Two, Three" "" "He said, \&quot;Immel did it!\&quot;"'

string="&quot;One, Two, Three&quot; &quot;&quot; "He said, \&quot;Immel did it!\&quot;&quot;"
.x3d
Compressed Binary Encoding (CBE) 4.2.3 X3D canonical form string='"One, Two, Three" "" "He said, \"Immel did it!\""' .xml
ClassicVRML encoding (.x3dv) 5.15 SFString and MFString
and Grammar
string [ "One, Two, Three", "", "He said, \"Immel did it!\"" ] .x3dv
VRML97 (.wrl) 5.15 SFString and MFString
and Grammar
string [ "One, Two, Three", "", "He said, \"Immel did it!\"" ] .wrl
JSON encoding (.json) X3D to JSON Stylesheet Converter: JSON strings "@string": [ "One, Two, Three", "", "He said, \"Immel did it!\"" ] .json
Java Scene Access Interface (SAI) B.4.25 SFString, B.4.26 MFString new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""}
X3DJSAIL (.java) SFStringObject, MFStringObject .setString(new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""})
.setString(new MFStringObject(new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""}))
.setString(new MFStringObject("\"One, Two, Three\" \"\" \"He said, \\\"Immel did it!\\\"\""))
.java

🔖 Scalable Vector Graphics (SVG) to top

Scalable Vector Graphics (SVG) is a markup language for describing two-dimensional graphics applications and images, and a set of related graphics script interfaces. SVG is supported by all modern browsers for desktop and mobile systems. There are many SVG authoring tools, and export to SVG is supported by all major vector graphics authoring tools.

Use with X3D

Tools

Resources


🔖 URL Links to top


🔖 Validation of X3D Scenes using DTD and XML Schema to top

This section shows example declarations of DTD and Schema in X3D scenes.

One of the biggest benefits of the .x3d file encoding is XML validation. XML checks for well-formed documents, DTD validation and schema validation greatly improve quality assurance (QA) for X3D scenes. This approach exposes many possible errors and helps authors eliminate Garbage In Garbage Out (GIGO) problems. Useful links:

XML validation is defined by the Extensible Markup Language (XML) 1.0. A number of document variations are possible for X3D scenes. For example, encoding information is optional and may designate a variety of character sets. The X3D specifications are carefully designed to be fully compatible with XML requirements.

The following sections provide detailed information on the proper file syntax for X3D DTD and XML Schema headers in an .x3d scene. Each version matches the corresponding X3D version (3.0, 3.1, 3.2, and 3.3). Thanks to X3D stability, each version is backwards compatible. For example, the X3D v3.2 DTD and schema can validate X3D v3.2, v3.1, or v3.0 content, but not v3.3 content.


🔖 Viewpoints and Navigation to top

Viewpoints are typically the most important mechanism for an author to suggest scene navigation to a user. Recommended keyboard defaults are listed in Annex G Recommended navigation behaviours. In this way, new users interacting with an X3D scene can have a relatively consistent experience, regardless of which X3D player might be used.


🔖 Volume Tools and Volume Visualization to top

The X3D Graphics Volume Rendering component. describes how voxels and polygons can live together in harmony within a single scene.


🔖 Virtual Reality Modeling Language (VRML97) to top

The X3D Graphics ClassicVRML Encoding is a direct successor of the VRML97 International Standard. Thanks to the careful design of X3D, full backwards compatibility is available.

Converting a VRML scene (.wrl file) to an X3D ClassicVRML scene (.x3dv file):

Additional X3D Resources of interest:


🔖 Contact to top

Questions, suggestions, additions and comments about this X3D Scene Authoring Hints page are welcome. Please send them to Don Brutzman (brutzman at nps.edu) who maintains it.

These hints were collected while teaching X3D Graphics and writing X3D for Web Authors. Questions, suggestions, additions and comments are welcome.

Online at http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html

Updated: 10 December 2018.