X3D Scene Authoring Hints

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 (Java, JavaScript, JSON) | 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

• Tool recommendations:
  • Audacity is an excellent open-source audio editing and recording tool (Windows Macintosh Linux).
  • MuseScore is an excellent open-source music-score editing and recording tool that can produce .midi and .wav files (Windows Macintosh Linux).
  • Video tools can typically play audio files.
• Sound formats:
  • X3D player support for the .wav format is required, while .midi and .mp3 support are recommended.
  • X3D4 adds support for MIDI 2.0 which extends prior versions to add numerous new capabilities. This important specification is developed and maintained by the MIDI Association for the benefit of artists and musicians around the world.
  • Other audio formats are optional, you are welcome to check documentation for all X3D browsers of interest.
  • So far, support for audio-streaming protocol is required in X3D players... but none is forbidden, either. Experimentation is good, the "X" in X3D stands for Extensible.
• For reliability an author can use a variety of formats at once, if desired. See URL Links for information how to link multiple formats/versions of an audio file.
• Do not add audio files to open-source archives without proper permissions and Credits.
• Further X3D resources:
  • X3D Tooltips: AudioClip, MovieTexture and Sound nodes.
  • X3D Architecture Sound Component specification.
  • X3D for Web Authors online course: Chapter 12 - Environment Sensor Sound, examples, slideset and video.
  • ConformanceNist X3D Examples Archive: AudioClip and Sound
  • VRML 2 Sourcebook X3D Examples Archive: Chapter 24 Sound
• Sound libraries are numerous, including:
  • Freesound is a collaborative database of Creative Commons Licensed sounds to browse, download and share.
  • Filmstro royalty-free library of background music.
  • Free Music Archive mission is sharing free, curated audio to all.
  • YouTube Audio Library includes free music for projects.
  • Zapsplat is an online library of free sound effects and royalty-free music.
• X3D version 4 look-ahead point paper on spatial sound model and audio rendering: Strategies to Improve X3D v4 Sound Component.

🔖 Authoring Practices

• Establishing a habit of following best practices for scene authoring can greatly increase your ability to create, debug and maintain high-quality X3D scenes.
• Validate, validate, validate! Detecting errors is extremely important: an undetected error is the worst error because it is only blocks end users instead of being discovered by the author.
• The five levels of X3D validation checking available include XML well-formedness checking, XML DOCTYPE (DTD) checking, XML Schema checking, X3D-to-VRML stylesheet conversions, and X3D Schematron rules.
• X3D Schematron provides an comprehensive form of XML validation for X3D scenes. Authors can use X3D Schematron reports to verify semantic correctness and detect internal-consistency problems.
• Actively fix any validation [Error], [Warning] and [Hint] messages in each scene. Allowing errors and warnings to persist, even when apparently harmless, can mask further problems. [Info] messages are informational and might not need corrective action by the author.
• Look in the X3D Tooltips (online) for questions about node and field usage. These are embedded in X3D-Edit popups, and are also available separately in Chinese, English, French, German, Italian, Korean, Portuguese, Spanish and Thai.
• XML pretty-print file formatters can help make scene source more readable. The most important and consistent is X3D Canonicalization (C14N) which is used prior to generating X3D Compressed Binary (.x3db) format or putting Web3D examples into version control.
• If a scene depends on having the default value of a field for proper operation, it is a good authoring practice to enter that default value in your original scene for emphasis. Note, however, that some optimizers (such as X3D Canonicalization C14N) may remove it again.
• Refer to the X3D Standards frequently to learn more. The X3D Abstract Specification is especially important since it describes X3D functionality in complete detail. You may also want to extract and install a copy on your local system. All current X3D specifications are also bundled with X3D-Edit.

🔖 Color

• Wikipedia: Color
• Color Calculator by Fraunhofer IGD
• Exporting to VRML and X3D for color printing by Shapeways
• X3D Example Archives: X3D for Web Authors, Chapter 07 - Event Animation Interpolation, Color Interpolator example
• X3D Example Archives: Savage, Tools, Animation, Color Sequencer prototype and example scene
• ColorBrewer 2.0 color advice for cartography
• CSS Color Names by Douglas Crockford
• InfoHound Color Schemer by Jonathan Hedley
• Paletton Color Scheme Designer
• COLOURlovers: Color Trends + Palettes
• 4096 Color Wheel by Jemima Pereira
• HyperText Markup Language (HTML) 5.2, section 2.4.6 Colors
• Cascading Style Sheets (CSS) Color Module Level 3
• Applying Color Theory to Digital Media and Visualization by Theresa-Marie Rhyne, Taylor & Francis, 2016.
• A Field Guide to Digital Color by Maureen Stone, A K Peters, 2003.
• Color: A Natural History of the Palette by Victoria Finlay, Random House Publishing Group, 2003.

Material

• Pellucid is a Java applet that simulates the VRML/X3D illumination model given a default view of a sphere, a default directional light with direction [ -1 -1 -1 ], and a default material.
  • example Pellucid screenshot).
  • Caveat: to run the applet, you may need to add this site to your Java Control Panel Security Exception Site List (documentation).
• The Basic X3D Example Archives includes Universal Media Materials, a large suite of color-coordinated X3D/VRML Materials for easy usage by authors.

🔖 containerField

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.

• Usually ignorable. Default containerField values for each node are correct in most cases, so the need to override default containerField values is relatively rare.
• Terse match to other X3D encodings. The containerField attribute is part of XML encoding for X3D scenes, and corresponds to the always-declared field labels in the ClassicVRML and VRML97 file encodings.
• Examples. Example values include containerField='geometry' for Box node, containerField='children' for Group node, containerField='proxy' for hidden proxy shape within a Collision node, etc.
• USE node flexibility. USE nodes are allowed to have a containerField value that is different than the corresponding DEF declaration of that node, since the containerField attribute describes each node's relationship with its parent.
• ProtoInstance node flexibility. ProtoInstance nodes are similarly allowed to have a containerField value that is different than default for their node type, again since the containerField attribute describes each node's relationship with its parent.

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

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

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

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.

• CADFace issue Mantis 1234 to change unnecessarily different containerField='shape' and rename as containerField='children' instead. This change was rejected since the field can only contain a single SFNode, making it functionally different that MFNode children.
• CollidableShape: issue to change field name containerField='shape' (which has different semantics than CADFace shape field) and rename as containerField='children' instead. This change was rejected since the field can only contain a Shape node and has accessType initializeOnly, making it functionally different.
• Collision: typed content-model definitions for a proxy node (containerField='proxy') might be insufficiently strict [X3DChildNode]. Mantis issue Mantis 1149 considered node-type restrictions "matching CADFace shape field" instead, i.e. [Shape|LOD|Transform]. This issue was reviewed but not approved, with no change applied.
• GeoLOD: see issue Mantis 920 to change unnecessarily different field name containerField='rootNode' and rename as containerField='children' instead. Also enter Mantis issue to implement object interface X3DUrlObject.
• GeoMetadata: has X3DUrlObject object interface applied for consistency, so no changes in field names necessary.

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

• Each Transform node can create a new relative coordinate system for all children nodes in the scene graph.
  • Each set of axes follows the right-hand rule (RHR) for coordinate systems.
• Angular rotations are expressed in radians, using right-hand rule (RHR) with thumb pointing along positive direction for axis of interest and the other fingers curling in the direction of positive rotation.
  • Each set of orientations follows the right-hand rule (RHR) for angle rotations.
• 3D Rotation Converter converts between different 3D rotation formats: axis-angle (X3D form), quaternions, rotation matrices, Euler angles, etc.
• Local/world coordinate systems: +X-axis is nose/East, +Y-axis is vertical/up, +Z-axis is right-hand side (RHS)/South.
• Entities (planes, trains, automobiles etc.) also must follow these coordinate system conventions. Consistent orientation allows models to be composed and animated together in combined scenes. Example scene: ModelOrientation.x3d (.wrl) (.html) (image)
• Coordinate-system example scene: CoordinateAxesNSEW.x3d (.wrl) (.html) (image)
• Coordinate-system gimbals, including DIS axis conversions: Gimbals.x3d (.wrl) (.html) (image)
• Position the default center of ground vehicles so that the bottom touches the ground. That way the entity can be properly animated by a parent Transform.
• Position the default center of airborne, space and underwater entities in the centroid (geometric center) or Center of Gravity (Cg) (for physics-based models).
  • Structured X3D metadata can record Center of Gravity (Cg) or Center of Buoyancy (Cb) information within a model. Such information can be read by simulation applications at run time.
  • Further information about this technique can be found in the NPS Savage Modeling and Analysis Language (SMAL) documentation, with corresponding example metadata templates.

🔖 Cross-Origin Resource Sharing (CORS) Restrictions

"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

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

CORS client-side references:

• Wikipedia: Cross-origin resource sharing
• Fetch Standard by WHATWG defines requests, responses, and the fetching process that binds them. See 3.2. CORS protocol.
• Mozilla documentation: Cross-Origin Resource Sharing (CORS)
• X_ITE Issue 72, Supporting CORS in X3D-Edit via Java to support X_ITE presentation of X3D models
• X_ITE Guidance, Using Firefox, Chrome and Opera with Local Files
• X3DOM documentation: Running X3DOM Applications with a Simple Python Server
• Julia Boes, JEP 408: Simple Web Server, JDK 18, 7 March 2022.
• Julia Boes, Java 18's Simple Web Server: A tool for the command line and beyond, 7 April 2022.
• HowToDoInJava, Java CORS Filter Example, 1 October 2022.
• Foojay Today, How to Create APIs with the Java 18 jwebserver Ready for Docker, 11 April 2022.
• Mozilla Developer Network (MDN), How do you set up a local testing server?.
• Holger Seelig, X_ITE documentation, Setup a localhost Server, 8 JAN 2023.
• Mozilla Developer Network (MDN), Reason: CORS header 'Access-Control-Allow-Origin' missing.
• Unni Manna, A Simple HTTP Server in Java, DZone, 11 January 2020.
• Additional TODO: add built-in CORS capabilities to X3D-Edit, X3DJSAIL Java, X3DPSAIL x3d.py python.

🔖 CORS http server configuration

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:

• Wikipedia: CORS simple request example
• StackOverflow: How to Enable CORS for Apache httpd server? (Step-By-Step Process)
• StackOverflow: How does the 'Access-Control-Allow-Origin' header work?
• CORS on Apache
• Ubiq: How to Enable CORS in Apache Web Server
• Apache httpd documentation TODO: find link to authoritative configuration details

🔖 Credits

• Ensure that all contributors to your content receive proper credit. Also see License for related details.
• The X3D for Web Authors, X3D for Advanced Modeling, VRML 2.0 Sourcebook, X3D ConformanceNist Suite, Basic X3D Examples, and Savage model archives are free for duplication and further use. Each model document gives appropriate credit to scene authors.
• Don't add scenes, images or audio files to the archive unless permission has been granted from the respective owners. This means that there are clear and documented distribution rights attached. This can accomplished through
  • Regular meta statement information documenting the model,
  • Simple WorldInfo node at the top of the model, or
  • License or email record from the original owner that accompanies the model.

🔖 Cascading Style Sheets (CSS)

TODO

• Overview
• Use in X3D
• References
• Tools: Amaya, X3D-Edit Firebug

🔖 Dates

• Use meta statements to note the dates when a scene is created and revised:

  <meta name='created' content='1 October 2003'/>
  <meta name='revised' content='18 June 2015'/>

• Use full 4-digit numbers for years, e.g. 2014.
• For consistency, readability, disambiguation and program parsability, please use the date format 4 July 2014 (rather than other forms such as July 4, 2014, 7/4/14, or 4/7/2014).
• Leading zeroes on dates are not usually used but are OK. They are sometimes helpful as part of filenames or tokens to ensure proper alphabetization of lists.

🔖 Encodings

• X3D MIME Media Types are approved two-part identifiers for X3D file formats on the Internet: x3d+xml (for .x3d files), x3d-vrml (for .x3dv files) and x3d+fastinfoset (for .x3db files).
• Name identifiers (DEF/USE and Prototype names), sometimes referred to as fragment identifiers, must only use UTF-8 characters.
• Note that a variety of character encodings are possible for the XML-based .x3d encoding (reference 19776-1 paragraph 4.4.1), while only the utf8 character encoding is allowed for the ClassicVRML .x3dv encoding.
• The Unicode FAQ UTF-8, UTF-16, UTF-32 & BOM contains further information.

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

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

• Tool recommendations:
  • Amaya is an open-source Web document editor from the World Wide Web Consortium (W3C) supporting HTML5, stylesheets, SVG and other document formats.
  • Netbeans and X3D-Edit are open-source integrated development environments (IDE) supporting HTML5, stylesheets, X3D and other source formats.
• HTML Object Tag for X3D shows how to place X3D objects within an HTML page, and newHtmlPageWithX3dObject.html is an example HTML scene with X3D object tag to copy, edit and reuse.
• Ensure HTML content is valid.
  • W3C Markup Validator Service and Nu Html Checker
  • HTML Tidy
  • WDG HTML Validator
  • HTML-Kit
• Want to learn more about HTML? Many books and online tutorials are available. Recommended: the following online lessons by Dave Raggett.
  • Introduction to HTML
  • More advanced HTML features
  • Adding a touch of style
• Character entity references in HTML defines encoding values for special characters in XML/HTML files. Additional resources:
  • Character Entity Reference Chart
  • List of XML and HTML character entity references
  • XML Entity Definitions for Characters (2nd Edition)
  • Stylized/curly quotation marks: David Baron's Quotation Marks in HTML examples, and David A. Wheeler's Curling Quotes in HTML, SGML, and XML essay.
• Internationalization (I18N) and Localization (L10N) requirement: when HTML pages include foreign-language characters, declare that the content is UTF-8. Example:

  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>

• Looking ahead: the X3D and HTML5 effort is working to ensure the best possible integration of X3D with HTML.
• Additional references:
  • HyperText Markup Language (HTML) Home Page
  • XHTML 1.0
  • HTML 4.01
  • Web Design Group's FAQ Archives
  • Recommended List of DOCTYPE Declarations (W3C QA) and Choosing a DOCTYPE (WDG Web Design Group)
  • Google HTML/CSS Style Guide (WDG Web Design Group)

🔖 Images and Videos

• Tool recommendations:
  • An excellent open-source image editor for scaling, resizing, clipping, reformatting etc. is the GNU Image Manipulation Program (GIMP).
  • Additional open-source image-modification tools of interest include Fiji (which extends ImageJ) and ImageMagick Image Converter (screenshot).
  • VLC is a free open-source cross-platform multimedia player that plays most multimedia files.
  • Audio tools can typically play soundtracks from video files.
• Follow Naming Conventions for image and video file names: no abbreviations, CamelCaseNaming, no embedded whitespace or underscore characters, etc.
  • Don't arbitrarily rename images provided from other sources.
  • Starting with the same name as the scene of interest helps directory alphabetization.
  • Ensure that filename extensions are lower case (e.g. CoolImage.png vice CoolImage.PNG).
• It is important to include DEF and USE when multiple copies of an image or video file are present in a scene. This avoids delays and reduces memory consumption that results from reloading the same file multiple times.
  • If the image file might be different each time it is retrieved, then DEF/USE isn't appropriate.
• Quality assurance (QA) image validator: W3C Online Image Info service
• Choice of image file formats:
  • Portable network graphics (PNG) is the preferred image format for capturing screen images, providing the best support for lossless compression and transparency.
  • Joint Photographic Experts Group (JPEG) format is also excellent. The preferred file extension is CoolImage.jpg. JPEG is the best choice for photographic images since it captures color gradations exceptionally well. Be careful to evaluate results when modifying JPEG compression quality, since it is lossy and highest image quality is often best. Note that JPEG does not support transparency.
  • Tagged Image File Format (TIFF) is a high-quality format for images, photographs and line art. However it is proprietary and not always supported.
  • Avoid using Graphics Interchange Format (GIF) if possible. It is technically inferior, larger size, and has licensing encumbrances. Rationale: PNG versus GIF considerations.
• Integrating textures. Exporting to VRML and X3D for color printing PixelTexture image-conversion import can embed an image directly inside a single X3D scene file by converting it into an SFImage array within a PixelTexture node.
• Choice of video file formats:
  • X3D browser support for the MPEG1 video file format format is required by the MovieTexture node definition in the X3D Specification.
  • X3D browsers may offer to support multiple video formats. Since the X3D url field is an ordered list, authors can provide and link more than one format if they wish. X3D browsers will honor the first successfully playable link that they find.
  • However consistent support for other formats beyond MPEG1 is not guaranteed since most popular video formats are highly encumbered by patents and licensing fees. Having authors or content providers account and pay for content is antithetical to the free growth of open standards and the World Wide Web.
  • If a royalty-free (RF) video format becomes sufficiently popular and has multiple efficient open-source and commercial codec software implementations available, then the X3D Graphics Working Group and Web3D Consortium members will likely adopt its usage as a required format. Until then, support for any video format other than MPEG1 remains optional for X3D.
  • Of related interest: the existence of the open X3D Graphics standard prevents a similar sad state of affairs from allowing patent-holding companies from "locking up" 3D graphics on the Web. Members of the Web3D Consortium deserve credit for maintaining this important achievement. Feel free to join or contribute so that such efforts can continue.
• Many other image file formats exist. The best authoring practice is to use GIMP to convert the original image into .png or .jpg format, as described above, to ensure the X3D player can display it. It is often best to save and provide both formats so that the original highest-quality image remains available. Example:
  

  <ImageTexture DEF='grid'
      url='"OahuGrid.png"
           "https://savage.nps.edu/Savage/Locations/Hawaii/OahuGrid.png"
           "OahuGrid.rgba"
           "https://savage.nps.edu/Savage/Locations/Hawaii/OahuGrid.rgba"'/>

• Use high-resolution quality (e.g. 300 dpi or better) since textured imagery is often viewed at close ranges. Try to keep image file size under 200-300 KB, if possible. Consider using both low-resolution and high-resolution versions as appropriate for level of detail (LOD) and Web delivery.
• An image file can be embedded inside an X3D scene by converting it into a PixelTexture node. These will take up more size (often by a factor of 10), but nevertheless do compress well and do not require a separate file fetch over the network. A PixelTexture image import feature is provided by X3D-Edit. For an example conversion program, see PixelTextureGenerator.java which was used to create PixelTextureNavyJackDontTreadOnMe.x3d in the Savage/Tools/Authoring collection.
• Do not add images or videos to open-source archives without proper permissions and Credits.
• Use the W3C Image Info Service to check the properties of your online image.
• Further resources:
  • X3D Architecture specification Texturing component.
  • X3D Architecture specification 17.2.2 Lighting model for interactions between lighting model, materials and textures.
  • X3D for Web Authors online course: Chapter 05 - Appearance Material Textures, examples, slideset and video.

🔖 Inline Scenes and Prototype Templates

• 🔖 Inline scenes load a file containing an external scene into the current scene
  • DEF/USE multiple instances of duplicate Inline, image, audio and video content. This approach is more maintainable, uses less memory and can reduce file-transfer delays.
  • Inline scenes ought to be interesting enough to have their own purpose, or stand on their own. If an Inline scene is unlikely to be reused more than once, then the X3D content probably ought to get incorporated in the parent scene.
  • Provide well-formed url addresses for reliability.
  • Ensure that named IMPORT/EXPORT connections match.
  • Inline tooltips and X3D specification describe functionality in detail.
  • Experimental: annotate Inline node with profile information to assist in overall scene validation. Example:

    <Inline url='"string array addressvalues"'> <MetadataString name='profile' value='Immersive'/> </Inline>

• 🔖 Prototype Declarations define a template for a new node
  • Follow Naming Conventions for node and field definitions.
  • Provide useful/safe default initialization values for each field, rather than depending on default field values internal to the ProtoBody.
  • Include annotation tooltips for each field.
  • Avoid copying ProtoDeclare definitions into additional scenes, instead copy ExternProtoDeclare/ProtoInstance definitions.
  • Tooltips for ProtoDeclare, ProtoInterface and ProtoBody
  • Avoid duplicate DEF names for nodes inside multiple prototype declarations contained in a single file. Although the DEF namespaces contained inside each independent ProtoBody declaration are logically independent from an X3D perspective, duplicate DEF names will provoke XML validation errors regarding duplicate ID names.
  • X3D Specification clause: Prototype Semantics
  
  
• 🔖 External Prototype Declarations refer to prototypes declared in another file
  • Do not wrap field definitions in a ProtoInterface element since that construct is illegal.
  • For important prototypes, make a separate NewNodeExample.x3d scene that provides copyable/reusable ExternProtoDeclare/ProtoInstance definitions corresponding to each NewNodePrototype.x3d scene. This encourages authors to avoid copying the ProtoDeclare definitions, so that a master version remains stable and improvable.
  • Do not include initialization values in field definitions. They are illegal since the defaults in the original ProtoDeclare field declarations take precedence.
  • Copy annotation tooltips from the corresponding ProtoDeclare annotation tooltips for each ExternProtoDeclare field. Listing default values used by the prototype can be helpful.
  • ExternProtoDeclare tooltips and X3D specification
  
  
• 🔖 Prototype Instances create example node instances using the declared prototype template
  • Explicitly include initialization values, even if they match default values, to ensure proper operation. Sometimes a prototype can have different initialization values than expected, if it is modified elsewhere.
  • Remember to include proper containerField attribute, identifying parent-node field name for this ProtoInstance. Default value: children. Example values: color, coord, geometry, fontStyle, proxy, sound, texture, textureTransform.
  • First debug proper ProtoInstance operation in the scene defining the original ProtoDeclare, rather than using an ExternProtoDeclare. Why - to make sure they work first! Browser debugging can be more cryptic for externally defined prototypes and different versions may occur in various remote url addresses, making it difficult to determine precisely which ExternProtoDeclare is being referenced.
  • If an author wants a ProtoInstance node to contain metadata like other X3D nodes, then first add a metadata field to the defining ProtoDeclare. For an example, see DoubleClickTouchSensorPrototype and DoubleClickTouchSensorExample.
  • Note that a ProtoInstance USE node does not include a name definition, since it is duplicative (i.e. the name is already defined in the DEF instance) and this approach avoids possible mismatched name values for ProtoInstance DEF nodes and USE references. Be aware that regular X3D file validation is often unable to detect this error.
  • ProtoInstance tooltips and X3D XML Encoding specification

🔖 License

• X3D authors can place meta statements in a scene to document what license being applied. For example, one of the following is typically included in the X3D scenes found in the Web3D Consortium and NPS open-source example archives:

  <meta name="license" content="../../license.html">

  <meta name="license" content="https://www.web3d.org/x3d/content/examples/license.html">

  <meta name="license" content="https://savage.nps.edu/Savage/license.html">

• This default open-source license is available for X3D models and source code produced by NPS (and others) for the various Web3D and Savage model archives.
  • The license is available as license.html and also available in plain-text form as license.txt for embedding in source-code files.
  • The terms of this non-viral BSD open-source license permit both commercial & non-commercial uses. The contributing authors retain original copyright as appropriate. This license can be adapted for use by other open-source contributors, as desired.
• The Open Source Initiative (OSI) lists alternate open-source licenses that are also acceptable for other public contributions to the Web3D Consortium's archives and resources.
• Book: Understanding Open Source and Free Software Licensing by Andrew M. St. Laurent, O'Reilly Media, Sebastopol California, 2004. Also available online.
• Creative Commons is another important resource for crafting appropriate licenses.
• The Savage Developers Guide includes further references of value regarding Intellectual Property Rights (IPR) issues: Free as in Freedom and Licensing.
• The X3DOM dual license is open source and includes both the MIT License and GNU General Public License (GPL) v3 or later.

🔖 Meshes

• There are many kinds of polygon mesh structures in 3D graphics. A wide variety of X3D nodes are available for representing various polygonal meshes.
• 3D modeling tools with 3D interfaces make it easy to create unusual and irregular geometry, but it often remains hard to size them correctly or shape them precisely. Use reference grids and cross-section slices to check that dimensions are accurate when creating new models.
• Polygon meshes can be created in many different tools. Results are easily exported to X3D, VRML, or other compatible formats. The X3D Resources page lists current conversion and translation tools.
• Exporting a model mesh to X3D polygons usually means that the shape(s) can only be transformed and scaled, with no internal animation modifications at run time. Therefore it is a good idea to split up any pieces of geometry that need to be animated separately.
• Scaling in meters is usually preferred. Using other units (feet, inches, millimeters etc.) is OK if that preserves the original data exactly. Simply adding a parent Transform node with uniform scaling can restore overall units to meters, but watch out for additional scale conversions of event streams if any internal components need animation.
• When maintaining models in an archive, keep both the original version and the .x3d version in case future modifications are needed. Saving documentation, README notes about construction and metadata information is also important.
• Exported polygon meshes often have geometric problems: misaligned front/back normals, clockwise vice counterclockwise (ccw) definition, one-sided versus two-sided, non-coplanar quadrilaterals, etc.
• Running output meshes through one or more "cleanup" tools can help identify and correct these otherwise-obscure errors.
• Useful tools include Blender, Chisel, MeshLab, X3D-Edit quality assurance (QA) with embedded Xj3D CAD filter, etc.
• Tool-assigned DEF/USE names for nodes are also often quite obscure. When possible, assign clear names for DEF/USE labels of top-most parts in order to make animation and inlining easier.
• Many of these issues are common to the export of Computer Aided Design (CAD) models from various formats into X3D. The X3D CAD Working Group is a long-standing source of resources, tools and best practices.
• Geometric compression in the .x3db binary encoding can reduce unnecessary significant digits, merge coplanar polygons, quantize colors and normals, etc.
• NURBS and other parametric surfaces are often preferable to polygonal meshes since they provide exact representations that are concise and work at any level of detail. Nevertheless polygon meshes may be preferable for public distribution if complex source needs to be protected. Including both types of representations within Switch or LOD nodes is another possibility.
• Applying X3D Security techniques can support secure distribution of sensitive portions of an X3D model (such as the high-value NURBS representation).

🔖 meta Statements

• Each X3D scene can contain metadata about the document itself. Top-level statements of interest are X3D, Scene, head, component and meta.
• Follow meta-tag norms found in newScene.x3d (.html)
• meta description statements are used for catalog entries. Ensure the first sentence provides a good overall description of the scene. Example:

  <meta name="description" value="This beautiful model of an actual clean bedroom will impress your mom."/>
  

• Update or remove meta statements with *default content descriptions*
• Remove extraneous trailing newline characters (which may be escaped as 
 character entities). Example:

  <meta name="description" value="This description has a trailing newline character.&#10;"/>
  

  X3D Canonicalization (C14N) rules include normalization of whitespace and C14N tools can take care of this cleanup.
• Ensure you include both <meta name="title"/> (for document name) and <meta name="identifier"/> (for document url) statements, with filename values ending in .x3d (rather than VRML97 .wrl) extension.
• Digital Object Identifier (DOI) system provides a technical and social infrastructure for the registration and use of persistent interoperable identifiers, called DOIs, for use on digital networks. DOIs are administered by the DOI Foundation as registration authority for ISO standard 26324. DOI resolution is also governed by IETF RFC 4452, The "info" URI Scheme for Information Assets with Identifiers in Public Namespaces.
• Dublin Core metadata terms define common conventions for default values used in name="value" attributes. Vocabulary support is provided by Dublin Core Metadata Initiative (DCMI), an open organization supporting innovation in metadata design and best practices across the metadata ecology.
• Commonly used meta names (metaNameValues) are documented in X3D XML schema (documentation), X3D Unified Object Model (X3DUOM) and X3DJSAIL metaNameValues.
• The XHTML1 strict DTD and schema include formal definitions for all meta attributes.
• Translation programs should indicate that the output file is a conversion by adding a meta tag such as

  <meta name="generator" content="X3D-Edit, https://savage.nps.edu/X3D-Edit"/>

  or, when using ClassicVRML encoding,

  META "generator" "X3D-Edit, https://savage.nps.edu/X3D-Edit"

  The X3D approach to meta statements matches best practices in HTML.
• Metadata terms for consistent referencing can be found in the following authoring resources:
  • Dublin Core Metadata Initiative (DCMI): Terms and Element Set
  • HTML5 section 4.2.5: The meta element
  • HTML4 section 7.4.4: Meta data
  • Dictionary of HTML META Tags (About)
• Metadata terms for language codes:
  • IETF Best Current Practice (BCP) 47: Tags for Identifying Languages
  • ISO 639-2: Codes for the Representation of Names of Languages
  • Internet Assigned Numbers Authority (IANA) Protocol Registries: Language Tags
• Chapter 1, Technical introduction section 2.5.5 for the book X3D for Web Authors (also slides) provides details on the use of meta statements in X3D scene headers.

🔖 Metadata Nodes

• Detailed description of the X3D Metadata nodes appears in
  • Core component of the X3D Abstract Specification
  • Chapter 15, Metadata information online chapter for the book X3D for Web Authors
  • X3D Tooltips: MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString and MetadataSet
• Typically the Metadata nodes have default containerField='metadata' except when they are child values of a MetadataSet node, in which case they have containerField='value'

🔖 Motion Capture (MOCAP)

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

BVH References

• Biovision Hierarchy, Wikipedia.

  The Biovision Hierarchy (BVH) character animation file format was developed by Biovision, a defunct motion capture services company, to give motion capture data to customers. This format largely displaced an earlier format Biovision providing skeleton hierarchy information as well as motion data. As of 2008, BVH is widely used, however not all applications support importing and exporting files in this format.

• The Motion Capture Society (MCS) is an international, professional, honorary nonprofit organization dedicated to advancing the arts, sciences, and applications of the motion capture industry.
• University of Wisconsin Biovision BVH course resources (with Table of Contents).

BVH Libraries

• Ohio State University (OSU) Advanced Computing Center for the Arts and Design (ACCAD) MoCap System and Data includes open-source MOCAP data.
• Mocap Club Motion Capture Library is free to the public and meant for educational purposes only. The library contains more than 500 different motions and it is possible in large part because of the generous contribution of the Motion Capture Society.

BVH Tools

• bvhacker (Windows) is an open-source tool for simple editing of bvh files.
• BVHplay is a free, open-source BVH animation player.
• Seamless3D imports and exports X3D, VRML and BVH files.
• X3D-Edit 4.0 imports BVH files as X3D models.

🔖 Naming Conventions

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.

• Using clear and consistent names for node names and DEF labels greatly improves the clarity of how a scene work. In effect, names can make the purpose of a scene self-documenting.
• CamelCaseNaming: capitalize each word, never use abbreviations, strive for clarity, and be brief but complete.
• startWithLowerCaseLetter when defining field names (i.e. attributes) within Prototypes and Scripts.
• Ensure consistent capitalization throughout. Of note: the Windows operating system is not case sensitive, but http servers are. Thus mismatched capitalization can hide target files, and this error only is revealed when placed on a server.
• Avoid embedding spaces in file names since they can be poorly (or inconsistently) handled by operating systems and tools. Whitespace is illegal within DEF/USE names and other name fields, since they become ambiguous and violate rules for ID/NMTOKEN type.
• Avoid embedding period characters in DEF/USE names since they interfere with ClassicVRML ROUTE syntax.
• Repeating recommendation regarding whitespace within file names: don't do that! Results are too prone to failure, often occurring inexplicably and undiagnosably within tool chains.
• Avoid use of underscores since they look like whitespace when part of a URL address. Occasionally it is acceptable to use the underscore character ("_") to indicate subscripts for definition of a mathematical variable.
• Avoid use of hyphens ("-") since these are erroneously turned into subtraction operators when converted into class or variable names.
• Combined: avoid use of whitespace characters, 'apostrophes' and "quotation marks" in file names since they can cause lots of problems for tools and search, especially when going from one operating system to another.
• Naming conventions can apply to .x3d files and reference files, as well as Prototype names, field names, and DEF/USE names. Starting names similarly (e.g. NavigationWalk, NavigationFly) can help alphabetize with indexing in the pretty-print HTML documentation, thus improving readability and searchability.
• Portability of each name is important especially since X3D models may get converted into a variety of programming languages and file formats.
• There are multiple requirements for characters allowed in DEF/USE names, and so using the strictest subset is useful.
  • .x3d, .x3db encodings: must follow XML requirements for ID/IDREF data type.
  • .x3dv, .wrl encodings: must follow ClassicVRML Grammar requirements for Id/IdFirstChar, which essentially match except for some special characters.
• Most restrictive and most interoperable guidance regarding choice of characters in names: can start with letter or underscore character, but not a number or a colon. Can then include letters, numbers, hyphen, underscore, or period characters. This interoperability is important so that files can be converted equivalently between encodings without validation problems.
• Use lower case for filename extensions. Examples: .png .jpg .txt. Although Windows systems are insensitive to upper/lower case, any differences will cause "file not found" failures on Unix systems (Apple, Linux) and http servers.
• Be consistent. When multiple files pertain to a single entity, start with the same name so that they will alphabetize adjacent to each other in the catalog and the directory listings. Examples: WaypointInterpolatorPrototype.x3d WaypointInterpolatorExample.x3d WaypointInterpolatorExample.png
• Similarly good choices for directory and subdirectory names can help keep scene names terse.
• Portability is important. Suggestions for XML Names in W3C XML 1.1 Recommendation describes best practices for construction of XML names and provides detailed character-set guidance. It also notes Names which are nonsensical, unpronounceable, hard to read, or easily confusable with other names should not be employed.
• Avoid file names which are identical to an X3D node name, since name collisions can thwart interoperability when converting among various programming languages.

🔖 Typing of name attributes:

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

• type="SFString" (meaning no restrictions) is applied to name attribute for meta statement, matching HTML. However, note that Dublin Core Metadata Initiative (DCMI) requires name to be a token appendable to a URI, so normal expectation for typical names is NMTOKEN.
• type="SFString" (meaning that embedded space characters are allowed) is applied to name attribute for meta statement, Core component X3DMetadataObject Metadata nodes, and also applied to CADGeometry component X3DProductStructureChildNode CAD nodes. This provides wider latitude when matching terminology structures from other metadata nomenclatures. Warning: note however that the included whitespace characters might be inconsistent. A name value containing whitespace might not validate or match other corresponding values.
• type="NMTOKEN" (meaning that no whitespace characters are allowed) is applied to name attribute for component and unit statements, simpleType SFString enumeration names, and prototype definitions (ProtoDeclare, ExternProtoDeclare, ProtoInstance, field and fieldValue).
• type="NMTOKEN" (meaning that no whitespace characters are allowed) is applied to name attribute for Humanoid Animation (HAnim) nodes. HAnim node names have a prefix if multiple Humanoids appear in a scene, e.g. "joe_r_upperarm". Note that an HAnimSite and HAnimDisplacer name starts with one of the HAnim featurePointNameValues. HAnimSite must end in '_tip' or '_view' or '_pt' suffix. HAnimDisplacer can end in '_feature' or '_action' or '_config' suffix.
• type="NMTOKEN" (meaning that no whitespace characters are allowed) is applied to name attribute for X3DVertexAttributeNode nodes (FloatVertexAttribute, Matrix3VertexAttribute, Matrix4VertexAttribute) that define Shader interface data structures. This provides maximum strictness supporting a variety of shader programming languages which typically do not support whitespace in names.

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.

• ConsistentDescriptiveName
• .PhysicalLocation (for example .HawaiiKauai)
• .SequenceNumber
• .21xxMonth01 (or timestamp, for sortability)
• .ext (filename extension)

General notes on naming conventions:

• These conventions are suitable for X3D scenes, XML tagset design, and corresponding Java classes.
• These conventions match the node and field naming conventions in the X3D Specification (and most XML).
• (Ironic) Success Metric: when is a name successful?
  Answer: when no one has to discuss that name any more, it is simply understood.

🔖 Scale Factors and Unit Conversions

• By default, the X3D International Standard uses the International System of Units Système international (d'unités) is the modern international standard version of the metric system.
• Scaling changes within a scene are possible (and usually a good practice) in order to match the measured values of 3D objects.
• For consistency in X3D scene composition, preferred scaling of length data is to use default units in meters.
• If portions of a scene use units other than meters, add a parent Transform node to uniformly scale back to meters.
• X3D version 3.3 UNIT statement provides support for scene-wide definition of alternate measurement. Allowed category values are:
  <unit/> for angle (default radians), length (default meters), mass (default kilograms) and force (default newtons).
• Note that authors can use any label they choose for the name field, since the category field provides the strict definition of how a conversionFactor field is applied.
• Example usage:

  • <unit category='length' conversionFactor='0.0254' name='INCH'/>

  • <unit category="length" conversionFactor="0.001"  name='MILLIMETER'/>

  • <unit category="length" conversionFactor="0.001"  name='MILLIMETRE'/> (note spelling of name)

• Example unit conversions from default Systeme International (SI) to English units:

  • <unit category='angle'  conversionFactor='0.0174532925167' name='DEGREES'/>

  • <unit category='length' conversionFactor='0.3048'          name='FEET'/>

  • <unit category='force'  conversionFactor='4.4482'          name='POUNDS-FORCE'/>

  • <unit category='mass'   conversionFactor='0.45359237'      name='POUNDS'/>

• X3D Tooltips: unit provides additional information and references.
• X3D-Edit supports convenient Transform scale selection or definition of alternate units.
• X3DJSAIL unit class provides conversion-factor enumeration constants as an authoring convenience.
• Additional conversion tools include Unit conversion information site, Wikipedia unit conversion factors, Online unit conversion site
• ISO STEP is an ISO standard for the computer-interpretable representation and exchange of product manufacturing information, often used for computer-aided design (CAD) 3D models. STEP includes expression of units, as shown in TYPE si_unit_name metadata terms.
• TODO: SEDRIS unit conversions
• TODO: ISO 80000 and standards-related unit conversions

• Length conversions:

  Common scaling factors, from given length unit to meters (m)
  Pica	Inches	Feet	Yards	Fathoms	Miles	Nautical Miles	Meters	Microns	Millimeters	Centimeters	Kilometers
  0.0042175176	0.0254	0.3048	0.9144	1.8288	1609.344	1852	1.0	0.000001	0.001	0.01	1000

  
  
• Angle conversions:

  Common scaling factors, from given angular unit to radians
  Degrees	Full Circle	Grads
  0.0174532925167 (Pi/180)	6.283185307179	0.01570796326795

  
  
• Force conversions:

  Common scaling factors, from given force unit to Newtons (N)
  Dynes	Kilogram-force	Pounds-force	Poundals
  0.00001	9.8068	4.4482	0.13826

  
  
• Mass conversions, avoirdupois:

  Common scaling factors, from given avoirdupois mass unit to kilogram (kg)
  Grains (gr)	Drams (dr)	Ounces (oz)	Troy Ounces (toz)	Pounds (lb)	Stone (14 lb)	Tons (U.S. short)
  0.00006479891	0.001771845195312	0.028349523125	0.0311034768	0.45359237	6.35029318	907.18474

  
  
• Mass conversions, metric:

  Common scaling factors, from given metric mass unit to kilogram (kg)
  Micrograms	Milligrams	Centigrams	Carats	Grams	Dekagrams	Metric Tonnes (t)
  0.000000001	0.000001	0.00001	0.0002	0.001	0.01	1000.0

🔖 Scripts

• The Script node embeds imperative programming code within a declarative X3D scene. It can perform computation as part of rendering a frame or reacting to user inputs.
• Event values are passed into and out of a Script using ROUTE connections. Field type and accessType matches are necessary for each value getting passed.
• For consistent response among differing browser JavaScript implementations, avoid var declaration of variables. Instead, declare any persistent variables as field definitions in the parent Script node.
• To aid portability and avoid unintended overloading of variable references, it is good practice for X3D Script authors to avoid the use of variables with global scope.
• newECMAscript.js is an editable example ECMAScript (JavaScript) source file for use with X3D Script node.
• Use lower-case boolean values true and false to match XML and ECMAScript/JavaScript rules. Capitalized TRUE and FALSE are only used in VRML syntax.
• Be sure to set <Script directOutput='true'> when modifiable SFNode/MFNode fields are part of the Script functionality.
• Browsers are not required to support any particular scripting language, but ECMAScript (JavaScript) is widely supported.
• X3D4 Architecture HTML authoring guidelines includes scripting and synchronization considerations.
• Equivalent script code written in multiple programming languages can be provided for portability, the first runnable version is chosen at run time. See X3D Abstract Specification, Scripting Component, 9.2.3 Scripting language protocols for an example.
• Source code can be placed in url attribute but may be unparsable due to escaping of special characters and elimination of line breaks (causing comments to nullify follow-on code). Use contained CDATA section instead for embedding source code.
• Preferred alternative to using the url field for Script nodes: insert a CDATA section to contain embedded source code. CDATA can protect literals like < and > from undesirable conversions by XML parsers. Furthermore, it eliminates the need to use < and > escape-character replacements (which make script code nonportable). Example:
  

  <Script mustEvaluate="true">
      <field name="message" type="SFString" accessType="initializeOnly" value="World!"/>
  <![CDATA[
  ecmascript:
  
  function initialize (timestamp)
  {
           Browser.print ('Hello ' + message);
  }
  ]]>
  </Script>
  

• If both url field and CDATA section are provided simultaneously, the url field is processed first. This approach allows utilization of update modifications or live queries in external scripts, while still providing reliable script source as a fallback alternative within the model itself. For further detail see X3D XML Encoding, 4.3.13 Encapsulating Script node code
• Use Browser.print(...) rather than a simple print(...) function when printing to the console. Browser.print(...) is the form supported by X3D, the unqualified print(...) was VRML97 syntax and is now obsolete. For backwards compatibility, X3dToVrml97.xslt will strip the preceding Browser. class qualifier when converting scripts to VRML97.
• For toggle-able tracing in ecmascript: scripts, first add the following field interface to the Script.
  

  <field accessType="initializeOnly" name="localTraceEnabled" type="SFBool" value="true"/>
  

  Then, at end of the CDATA section:
  

  function tracePrint(outputString)
  {
      if (localTraceEnabled)
           Browser.print('[ScriptNameHere] ' + outputString);
  }
  function forcePrint(outputString)
  {
           Browser.print('[ScriptNameHere] ' + outputString);
  }
  

  This lets the script author use trace-aware output functions as a substitute for Browser.print() as follows.
  

                    tracePrint('Only print when localTraceEnabled is true');
                    forcePrint('Always print: localTraceEnabled=' + localTraceEnabled);
  

• 🔖 Java Resources
  • Java.com install and Java Development Kit (JDK).
  • Savage Developers Guide: Java
  
  
• 🔖 JavaScript (ECMAScript) Resources

  JavaScript is a common programming language used in Web browsers for HTML and X3D scripts.

  • ECMAScript-262 specification defines JavaScript functionality required by the X3D specifications.
  • Douglas Crockford videos, book JavaScript: The Good Parts, Wrrrld Wide Web site and code conventions
  • Google JavaScript Style Guide
  • Mozilla Developer Network (MDN) JavaScript Guide
  • Savage Developers Guide: JavaScript
  • Wikipedia: ECMAScript including version correspondence
  • Wikipedia: JavaScript including version history

  Notes on JavaScript specification naming:

  • JavaScript is not the same as Java, they are different programming languages.
  • ECMAScript is the standardized version of JavaScript that is specified for use with the X3D international standards. ECMAScript is produced by the Ecma International (formerly European Computer Manufacturers Association) with subsequent ratification by the International Organization for Standardization (ISO).
  • VrmlScript was a subset of JavaScript originally proposed for use with VRML 97.
  
  
• 🔖 JavaScript Object Notation (JSON) Resources

  JSON is a data-structure convention for JavaScript.

  • Syntax correctness is testable using jslint and https://pro.jsonlint.com
  • jslint4java is a Java wrapper around Douglas Crockford's jslint tool,and https://code.google.com/p/jslint4java

🔖 Strings: SFString/MFString Encodings

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.

🔖 Scalable Vector Graphics (SVG)

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

• SVG can be used together with X3D in an HTML page.
• SVG can be used to export image files that can be utilized in ImageTexture nodes.
• SVG has been proposed for direct use in ImageTexture nodes as part of X3D version 4.

Tools

• Amaya is an open-source Web document editor from the World Wide Web Consortium (W3C) supporting HTML5, stylesheets, SVG and other document formats.
• Batik is a Java-based toolkit for applications or applets that want to use images in the Scalable Vector Graphics (SVG) format for display, generation or manipulation.
• Inkscape is a professional vector graphics editor for Windows, Mac OS X and Linux. It's free and open source.
• SVG-Edit is a fast, web-based, JavaScript-driven SVG drawing editor that works in any modern browser.

Resources

• SVG References and SVG Tutorial by Mozilla Developer Network (MDN)
• An SVG Primer for Today's Browsers by David Dailey, W3C Working Draft, September 2010
• Learn SVG site: coding, learning and resources

🔖 URL Links

• X3D url links are an ordered array of legal addresses for a given single resource. The first retrieved address which provides a legal result is used, otherwise the retrieval fails if no links work. The redundancy of this approach provides authors with greater portability and reliability for retrieval of content than is provided by HTML and other languages.
• Include both relative and persistent (online) url links. Use relative links first, since they are most portable and do not require unnecessary use of the network.
• Special case: use online links before relative links when updated network versions are preferred.
• Ensure each url link is valid. These can be easily checked manually via the pretty-print HTML version of the scene.
• Usage examples follow. First is the preferred form with 'single-quoted' url attribute values:

  <ImageTexture url='
     "earth-topo.png"
     "earth-topo-small.gif"
     "https://www.web3d.org/x3d/content/examples/earth-topo.png"
     "https://www.web3d.org/x3d/content/examples/earth-topo-small.gif"
  '/>
  

  or, if using the equivalent but more awkward syntax for "double-quoted" url attribute values:

  <ImageTexture url="
     &quot;earth-topo.png&quot;
     &quot;earth-topo-small.gif&quot;
     &quot;https://www.web3d.org/x3d/content/examples/earth-topo.png&quot;
     &quot;https://www.web3d.org/x3d/content/examples/earth-topo-small.gif&quot;
  "/>
  

• Sample usage of multiple (relative and online) url fields can be found in the X3D examples.
• Run a link checker to verify that URLs are correct and reachable. This step is performed periodically on the X3D example archives.
  • W3C Link Checker
  • Xenu's Link Sleuth
  • X3D-Edit node editing panes include url list editor checks for resource availability (green=found, black=retrieving, red=unavailable)
• Include "quotation marks" around each individual address in a url field, since url has type MFString.
• XML-aware editors may escape each " character as " as a compatible XML encoding. When using a text editor directly, it may be easiest to enclose the entire field in 'apostrophes' as shown next.
• Special URL values themselves (such as mailto: links) may require further special escaping if special characters are needed.
  • See Wikipedia: url encoding (Percent-encoding) for further details.
  • Escape characters can be tested at URL Decode and Endcode - Online site.
• References
  • X3D url tooltips
  • X3D specification: 9.2.1 URLs
  • Wikipedia: percent encoding (url encoding)
  • IETF RFC 1738, Uniform Resource Locators (URL)
  • IETF RFC 3986, Uniform Resource Identifier (URI): Generic Syntax
  • World Wide Web Consortium (W3C) Naming and Addressing: URIs, URLs, ...

🔖 Validation of X3D Scenes using DTD and XML Schema

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:

• X3D Validator is a Web application that comprehensively checks X3D scene validity.
• X3D Quality Assurance (QA) identifies errors and warnings in order to make X3D scene content more portable and reliable.
• X3D Specifications: DTD and Schema Validation includes the latest approved DTDs, schemas, change logs and documentation.

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.

• Warning: some XML-based tools are exceedingly sensitive to capitalization, whitespace, and quotation mark type used in the XML declaration as part of the document prolog. Be sure to follow the following definitions exactly.

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.

• 🔖 Version 4.0, experimental: X3D 4.0 draft specification DOCTYPE/DTD and schema

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 4.0//EN"
                       "https://www.web3d.org/specifications/x3d-4.0.dtd">
  <X3D profile="Immersive" version="4.0"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-4.0.xsd">
  

• 🔖 Version 3.3, approved: X3D 3.3 International Specification DOCTYPE/DTD and schema

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.3//EN"
                       "https://www.web3d.org/specifications/x3d-3.3.dtd">
  <X3D profile="Immersive" version="3.3"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-3.3.xsd">
  

• 🔖 Version 3.2: X3D 3.2 final specification DOCTYPE/DTD and schema

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.2//EN"
                       "https://www.web3d.org/specifications/x3d-3.2.dtd">
  <X3D profile="Immersive" version="3.2"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-3.2.xsd">
  

  Transitional DTD use is not recommended. There is no Transitional DTD beyond X3D 3.1 since this approach is no longer needed.

• 🔖 Version 3.1: X3D 3.1 final specification DOCTYPE/DTD and schema

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.1//EN"
                       "https://www.web3d.org/specifications/x3d-3.1.dtd">
  <X3D profile="Immersive" version="3.1"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-3.1.xsd">
  

  The Transitional X3D 3.1 DOCTYPE/DTD was originally used by some tools during development, but is no longer recommended since it is not portable across different machines.

  <?xml version="1.0" encoding="UTF-8"?>
  <!--Warning:  transitional DOCTYPE in source .x3d file-->
  <!DOCTYPE X3D PUBLIC "https://www.web3d.org/specifications/x3d-3.1.dtd"
                       "file:///www.web3d.org/TaskGroups/x3d/translation/x3d-3.1.dtd">
  <X3D profile="Immersive" version="3.1"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-3.1.xsd">
  

• 🔖 Version 3.0: X3D 3.0 final specification DOCTYPE/DTD and schema

  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.0//EN"
                       "https://www.web3d.org/specifications/x3d-3.0.dtd">
  <X3D profile="Immersive" version="3.0"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-3.0.xsd">
  

  The Transitional X3D 3.0 DOCTYPE/DTD was originally used by some tools during development, but it is no longer recommended since it is not portable across different machines.

  <?xml version="1.0" encoding="UTF-8"?>
  <!--Warning:  transitional DOCTYPE in source .x3d file-->
  <!DOCTYPE X3D PUBLIC "https://www.web3d.org/specifications/x3d-3.0.dtd"
                       "file:///www.web3d.org/TaskGroups/x3d/translation/x3d-3.0.dtd">
  <X3D profile="Immersive" version="3.0"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="https://www.web3d.org/specifications/x3d-3.0.xsd">
  

  When offline, X3D-Edit 3.1 can only load scenes containing the proper DTD one at a time. When disconnected from the network, click on a scene (or drag & drop the scene onto the X3D-Edit icon) to launch it - the DOCTYPE will be converted to Transitional DTD upon launch, and restored to Final DTD upon normal exit. Alternatively, use a different X3D/XML/text editor or the Transitional X3D DOCTYPE/DTD with X3D-Edit.

• 🔖 You can use X3dDoctypeChecker.java to convert from one DOCTYPE to the other:

  C:\www.web3d.org\x3d\content> java X3dDoctypeChecker
  
  usage: java X3dDoctypeChecker sceneName.x3d [-setFinalDTD | -setTransitionalDTD]
  

• 🔖 Errata-correction versions of the XML Document Type Definition (DOCTYPE DTD) and Schema are provided as part of the X3D-Edit distribution or directly online as follows.

  X3D XML DOCTYPE (DTD)	X3D XML Schema
  x3d-dtd-changelog.txt	x3d-schema-changelog.txt
  x3d-4.0.dtd and documentation x3d-4.0-InputOutputFields.dtd x3d-4.0-Web3dExtensionsPublic.dtd x3d-4.0-Web3dExtensionsPrivate.dtd	x3d-4.0.xsd and documentation (.zip) x3d-4.0-Web3dExtensionsPublic.xsd x3d-4.0-Web3dExtensionsPrivate.xsd
  x3d-3.3.dtd and documentation x3d-3.3-InputOutputFields.dtd x3d-3.3-Web3dExtensionsPublic.dtd x3d-3.3-Web3dExtensionsPrivate.dtd	x3d-3.3.xsd and documentation (.zip) x3d-3.3-Web3dExtensionsPublic.xsd x3d-3.3-Web3dExtensionsPrivate.xsd
  x3d-3.2.dtd and documentation x3d-3.2-InputOutputFields.dtd x3d-3.2-Web3dExtensionsPublic.dtd x3d-3.2-Web3dExtensionsPrivate.dtd	x3d-3.2.xsd and documentation (.zip) x3d-3.2-Web3dExtensionsPublic.xsd x3d-3.2-Web3dExtensionsPrivate.xsd
  x3d-3.1.dtd and documentation x3d-3.1-InputOutputFields.dtd x3d-3.1-Web3dExtensionsPublic.dtd x3d-3.1-Web3dExtensionsPrivate.dtd	x3d-3.1.xsd and documentation (.zip) x3d-3.1-Web3dExtensionsPublic.xsd x3d-3.1-Web3dExtensionsPrivate.xsd
  x3d-3.0.dtd and documentation x3d-3.0-InputOutputFields.dtd x3d-3.0-Web3dExtensionsPublic.dtd x3d-3.0-Web3dExtensionsPrivate.dtd	x3d-3.0.xsd and documentation (.zip) x3d-3.0-Web3dExtensionsPublic.xsd x3d-3.0-Web3dExtensionsPrivate.xsd

  Developmental versions of all X3D DTDs and schemas are maintained under version control at
  https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/specifications

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

🔖 Viewpoints and Navigation

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.

• Use clear, understandable Viewpoint description fields. Viewpoints are a primary user tool for scene navigation, so let users know what each Viewpoint is intended to show.
• Use an object's name first when many viewpoints follow, so that they are more easily identified in a viewpoint list that has many different objects in it. Examples: "Sports car driver view", "Sports car rear view mirror", "Sports car from above", etc.
• Use whitespace instead of underscores in Viewpoint (and sensor) descriptions.
• The default X3D initial viewpoint is typically on +Z-axis, looking toward origin along -Z-axis. This helps provide consistent catalog viewing since vehicles and other entities are aligned with their nose along the +X-axis.
• A good second viewpoint for vehicles provides an "over-the-shoulder" view, namely behind and above the geometry. This provides users with a good vantage point to follow the vehicle when it is animated in a scene.
• Since the default body coordinate system for an X3D scene with +Y-axis up, with the model body commonly pointed or aligned along the +X-axis, individual entities are typically pointed to the right when seen from the default view (on the +Z-axis looking towards the origin).
• Put objects in the center of a scene for default EXAMINE mode to work properly. Alternatively, use Viewpoint centerOfRotation field to indicate local center.
• Use Savage/HeadsUpDisplay/CrossHair online prototype to put a cross-hair overlay HUD in the center of a viewpoint.
• Use ViewpointGroup (X3D v3.2) to hide high-detail viewpoints from the viewpoint list at long ranges. This allows better navigability when there are many objects in a single aggregate scene.
• Use Savage/Tools/Authoring/AnimatedViewpointRecorderPrototype online prototype to hide high-detail viewpoints from the viewpoint list at long ranges. This allows scalability of many objects in a single scene.
• Key references: X3D Specification
• Further resources:
  • X3D Graphics specification: Navigation component, Viewpoint node (tooltip), NavigationInfo node (tooltip).
  • X3D for Web Authors online course: Chapter 04 - Viewing and Navigation, examples, slideset and video.

🔖 Volume Tools and Volumes Visualization

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.

• Microsoft DirectDraw Surface (DDS)
• Digital Imaging and Communications in Medicine (DICOM)
• Nearly Raw Raster Data (NRRD)
• Volume data format (VOL)

Tool recommendations:

• Fiji and ImageJ (found under Images) support image slicing from volumes.
• ITK-SNAP SNAP is a software application used to segment structures in 3D medical images. It provides semi-automatic segmentation using active contour methods, as well as manual delineation and image navigation Windows Macintosh Linux).
• Teem: nrrd (Nearly Raw Raster Data) is a file format and software library designed to support scientific visualization and image processing involving N-dimensional raster data.
• Seg3D is a free volume segmentation and processing tool that combines a flexible manual segmentation interface with powerful higher-dimensional image processing and segmentation algorithms from the Insight Toolkit (Windows Macintosh Linux).
• 3D Slicer is a multi-platform, free and open-source software package for visualization and medical-image computing (Windows Macintosh Linux).

Additional resources:

• Medical and Volume Visualization Tutorial by Nicholas F. Polys, Virginia Tech
• X3D Basic Examples Archive: Volume Rendering examples.

🔖 Virtual Reality Modeling Language (VRML97)

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):

• Copy the file, rename the .wrl file extension to a .x3dv file extension
• Change the scene header from

  #VRML V2.0 utf8
  

  to

  #VRML V3.3 utf8
  PROFILE Immersive
  

Additional X3D Resources of interest:

• Conversion and translation tools, many of which include VRML.
• VRML resource links plus a section on Books about X3D and VRML.

🔖 Contact

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