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 | CORS | Credits | Dates | Encodings | HTML | Images and Videos | Inlines and Prototypes | License | Meshes | meta Statements and Metadata Nodes | Motion Capture (MOCAP) | Naming Conventions | Scale Factors and Unit Conversions | Scripts (JavaJavaScriptJSON) | Strings | SVG | URL Links | Validation | Viewpoints and Navigation | Volumes | VRML | X3D Resources with additional references Savage Developers Guide | X3D‑Edit | X3D for Web Authors | X3D Resources | X3D Tooltips | X3D Validator | Contact


🔖 Audio and Sound 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. The use of containerField only occurs in XML-encoded files (.x3d format).

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 the correct parent-child field relationship with its parent node.

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. Coordinate, CoordinateDouble have default containerField='coord' when parent is an geometry node, have containerField value of skinCoord or skinBindingCoords when parent node is HAnimHumanoid and have containerField='controlPoint' when parent is a NURBS node.
6. 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.
7. HAnimHumanoid can contain a single Group, LOD, Shape or Transform with containerField='skin' rather than default containerField='children'. See containerFieldChoicesGroupLODShapeTransform.
8. HAnimJoint       has default containerField='children' when parent is another HAnimJoint, and has containerField value of joints or skeleton when parent node is HAnimHumanoid.
9. HAnimSegment has default containerField='children' when parent node is an HAnimJoint, and has containerField='segments' when parent node is HAnimHumanoid.
10. 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.
11. 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.
12. 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'). Important tooltips:
  1. Hint: typically use containerField="value" if the parent node is MetadataSet.
  2. Warning: default containerField="metadata" in X3D 3 changed to default containerField="value" in X3D 4.0, allowing construction of much terser MetadataSet vocabulary structures.
  3. Hint: explicitly defining containerField for Metadata nodes is always allowed and also unambiguous across each version of X3D.
13. Normal has default containerField='normal' when parent is an geometry node, and has containerField value of skinNormal or skinBindingNormals when parent node is HAnimHumanoid.
14. 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').
15. Sound can contain a single MovieTexture node with containerField='source' (rather than default containerField='texture').
16. 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').
17. 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.

🔖 Field name changes for improved consistency in X3D4 to top

Completed work for X3D Version 4 and X3D Unified Object Model (X3DUOM) makes a number of candidate optimizations possible and (in most cases) desirable. Consistent X3D scene-graph architecture across multiple file encodings and programming-language bindings is important.

The following consistency changes to SFNode/MFNode field names in X3D4 have the potential to reduce the number of containerField variations by more than half. Further simplification benefits are foreseen for X3D4 implementations, X3D authors, and X3D Ontology field disambiguation.

  1. ComposedCubeMapTexture: make six sets of field names identical to TextureBackground for contained textures, e.g. back becomes backTexture, top becomes topTexture, etc.
  2. DISEntityManager: when typically containing DISEntityTypeMapping, change that unnecessarily different containerField='mapping' and rename as containerField='children' instead.
  3. LoadSensor: change unnecessarily different field name containerField='watchList' and rename as containerField='children' instead. Child node restrictions can achieve a functionally equivalent effect and improve the object-oriented design.
  4. ParticleSystem: change unnecessarily different field names colorRamp, texCoordRamp and rename as regular defaults color, texCoord instead.
    Related: see issue Mantis 1322 to allow TextureCoordinateGenerator as an alternative to TextureCoordinate for that child node.

Not accepted for X3D4: nodes with working functionality but proposed design refinements were not workable.

For model authors and software implementers, few changes are needed for upgrading X3D and browsers from X3D3 to X3D4. These changes require modified parsers, validation tools and converters for proper handling. Performing this one-time effort now, when progressing from X3D3 to X3D4, means that future authors and modelers have a more streamlined and consistent interface, with less legacy baggage from earlier evolutions of the language.

These improvements support slight improvements to X3D4 authoring and animation. Issue resolution is tracked by X3D Working Group email summary X3D4 finalization endgame: Field naming reconciliation decision and Mantis 1331.

These changes to field names (for a handful of affected nodes) received close scrutiny by Web3D Consortium members with corresponding technical 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


🔖 Cross-Origin Resource Sharing (CORS) Restrictions to top

"Cross-Origin Resource Sharing (CORS) is a mechanism that allows restricted resources on a web page to be requested from another domain outside the domain from which the first resource was served." Wikipedia

CORS is important when locally launching an HTML page displaying X3D models when using the JavaScript-based players X_ITE or X3DOM. These are JavaScript players typically served from their originating websites, and so your local web browser may fail to load them (as well as your X3D model) due to CORS restrictions. This security restriction is an important protection against man-in-the-middle security exploits on your computer. Nevertheless it can can make testing difficult for X3D authors when modeling and debugging on a local system.

To develop .html/.x3d combinations on your own system, without uploading every time to an http servers somewhere, is difficult. The easiest way to handle CORS requirements is to have a local HTTPS server running privately on your system.

When preparing to handle CORS locally, here are some key points to remember.

  1. localhost http server is run on a port (for example, 8001) from subdirectory where .html page and .x3d model assets are found.
  2. local HTML file which uses X_ITE to retrieve an .x3d model must have a special prefix, e.g. http://localhost:8001/
  3. No special addition of http://localhost:8001/ is needed within the .html or .x3d files themselves, so they remain ready to publish externally without any internal changes.

🔖 CORS authoring on localhost to top

For authoring on localhost: examples follow, showing each step.


Step 1: Java http server

For example, if Java 18 or greater is installed, you can run the following Java command-line invocation in the directory of interest.

$ [system] cd 'installs\www.web3d.org\x3d\content\examples'
  [system] /cygdrive/c/x3d-code/www.web3d.org/x3d/content/examples

$ [system] jwebserver --port 8001 --bind-address 0.0.0.0 --output verbose
Serving C:\x3d-code\www.web3d.org\x3d\content\examples and subdirectories on 0.0.0.0 (all interfaces) port 8001
URL http://10.0.0.227:8001/

# To test localhost http server running:
# view directory contents by opening web browser with http://localhost:8001

Step 1, alternative: Python http server

For example, if Python 3 is installed, you can run the following command-line invocation in the directory of interest.

$ [system] cd 'C:\installs\www.web3d.org\x3d\content\examples'
  [system] /cygdrive/c/x3d-code/www.web3d.org/x3d/content/examples

$ [system] python -m http.server 8001
Serving HTTP on :: port 8001 (https://[::]:8001/) ...

# To test localhost http server running:
# view directory contents by opening web browser with http://localhost:8001

Step 2: HTML5 file invocation of X_ITE

Once the http server is running, use your web browser to select the .html page of interest containing your .3d model. For example:

Available capability: X3D-Edit authoring tool can launch a local http server to handle all CORS steps automatically when developing locally with X_ITE.


CORS client-side references:

🔖 CORS http server configuration to top

To configure an Apache http server, add the following directives:


    Header add Access-Control-Allow-Origin      "*"       # this advises browsers it is OK to submit a cross-origin request
    Header add Access-Control-Allow-Credentials "false"   # this advises browsers to not include cookies, authorization tokens, with a oross-origin request

CORS server-side references:


🔖 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 Libraries

BVH Tools


🔖 Naming Conventions to top

Clarity is essential for building a meaningful model. Naming conventions are appropriate for file names, DEF node identifiers and USE node references, prototype names, and more.

🔖 Typing of name attributes: to top

Small variations in SFString types for name attributes can occur in order to best achieve strict validation of content.

Naming of multiple similar files:

Naming multiple similar files can be difficult, especially when creating autogenerated files. One suggested approach is to concatenate the following name components as appropriate. Considering order and alphabetization can help. Avoid abbreviations since they complicate search.

For example you might 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) SFString, MFString .setString(new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""})
.setString(new MFString(new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""}))
.setString(new MFString("\"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.

X3D Regular Expressions (regexes) are used to validate the correctness of string and numeric array values in an X3D scene.


🔖 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 Volumes Visualization to top

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

Note that there are no required file formats, but at least one of the following formats is recommended for volume support in an X3D browser.

Tool recommendations:

Additional resources:


🔖 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 https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html and available in Sourceforge version control.

Updated: 24 August 2023