X3D Scene Authoring Hints

Don Brutzman (brutzman at nps.navy.mil)

A collection of style guidelines and authoring tips to improve the quality, consistency and maintainability of X3D scenes.

Authoring practices

Actively fix any X3D-Edit [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.
Keep a local copy of the X3D Specification on your system and refer to it frequently. (Local copies of all current specifications are bundled with X3D-Edit.)
Utilize the X3D Tooltips. These are embedded in X3D-Edit popups, and are also available separately in Chinese, English, French, German, Italian, Portuguese and Spanish.
If a scene depends on having the default value of a field, it is a good practice to enter that default value in your original scene for emphasis. Note, however, that some optimizers may remove it again.

Verify that you are using the latest version of X3D-Edit as follows.
Here is the locally installed version number of X3D-Edit.
Here is the latest available version number of X3D-Edit, online at http://www.web3d.org/x3d/content/X3D-Edit.zip

Use the correct X3D version 3.0 final specification DOCTYPE/DTD:

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

The Transitional X3D 3.0 DOCTYPE/DTD is used by some tools:

<?xml version="1.0" encoding="UTF-8"?>
<!--Warning:  transitional DOCTYPE in source .x3d file-->
<!DOCTYPE X3D PUBLIC "http://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="http://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="http://www.web3d.org/specifications/x3d-3.0.xsd">

When offline, X3D-Edit 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.

Preferred: X3D Amendment 1 version 3.1 specification DOCTYPE/DTD:

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

The Transitional X3D 3.1 DOCTYPE/DTD is used by some tools:

<?xml version="1.0" encoding="UTF-8"?>
<!--Warning:  transitional DOCTYPE in source .x3d file-->
<!DOCTYPE X3D PUBLIC "http://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="http://www.w3.org/2001/XMLSchema-instance" xsd:noNamespaceSchemaLocation="http://www.web3d.org/specifications/x3d-3.1.xsd">

You can use X3dDtdChecker.java to convert from one DOCTYPE to the other:

C:\www.web3d.org\x3d\content> java X3dDtdChecker

usage: java X3dDtdChecker 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-3.0.dtd x3d-3.0-InputOutputFields.dtd x3d-3.0-Web3dExtensionsPublic.dtd x3d-3.0-Web3dExtensionsPrivate.dtd	x3d-3.0.xsd and documentation x3d-3.0-Web3dExtensionsPublic.xsd x3d-3.0-Web3dExtensionsPrivate.xsd
x3d-3.1.dtd x3d-3.1-InputOutputFields.dtd x3d-3.1-Web3dExtensionsPublic.dtd x3d-3.1-Web3dExtensionsPrivate.dtd	x3d-3.1.xsd and documentation x3d-3.1-Web3dExtensionsPublic.xsd x3d-3.1-Web3dExtensionsPrivate.xsd
	X3dSchemaDocumentation.zip

Coordinate systems for 3D

Always use default scaling, with units in meters. If any content uses units other than meters, add a parent Transform node to uniformly scale back to meters.
Coordinate systems: +X-axis is nose/North, +Y-axis is vertical/up, +Z-axis is right-hand side (RHS)/East.
Entities (planes, trains, automobiles etc.) also must follow these coordinate system conventions. Example scene: ModelOrientation.x3d (.wrl) (.html) (image)
Position the default center of airborne, space and underwater entities in the centroid (geometric center) or center of gravity (for physics-based models). 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.
Coordinate-system example scene: CoordinateAxesNSEW.x3d (.wrl) (.html) (image)
Coordinate-system gimbals, including DIS axis conversions: Gimbals.x3d (.wrl) (.html) (image)
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.

Credits

Ensure that all contributors receive proper credit for content.
The Basic X3D Examples, VRML 2.0 Sourcebook, X3D Conformance Suite and Savage model archives are free for duplication and further use.
Don't add scenes, images or audio files to the archive unless permission has been granted from the owner. This means that there are clear and documented distribution rights attached. This can be meta tag information, WorldInfo node at the top, or a email/document statement by the owner duplicated locally.

Dates

Use meta tags to note the dates when a scene is created and revised:
<meta name='created' content='18 October 2003'/>
<meta name='revised' content='19 October 2004'/>
For consistency and possible parsability, please use the date format 10 July 2004 (rather than other forms such as July 10, 2004 or 10/7/2004).
Leading zeroes on dates are not usually used but are OK.
Use full 4-digit numbers for years, e.g. 2004.

HTML

Ensure HTML content is valid.
Encoding values for special characters in XML/HTML files are found under Character entity references in HTML.
Other references:

Images

Do not add images to the archive without proper permissions and Credits.
Follow Naming Conventions for image 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).
Portable network graphics (PNG) is the preferred image format.
- Please avoid use of Graphics Interchange Format (GIF) if possible.
- Further tips: PNG versus GIF considerations.
- Joint Photographic Experts Group (JPG) format is acceptable, and often does a good job on photographs. Be wary of JPG compression quality, which is adjustable (best quality is usually preferred).
Use high-resolution quality (e.g. 300 dpi or better). Try to keep image filesize under 200-300 KB, if possible.
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 compress well and do not require a separate network fetch. For an example, see PixelTextureGenerator.java which was used to create PixelTextureNavyJackDontTreadOnMe.x3d in the Savage/Tools/Authoring collection.
Use the W3C Image Info Service to check the properties of your online image.

Inline and Prototype Subscenes

Inline scenes
- 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.
- Inlined scenes ought to be interesting enough to stand on their own. If an Inlined 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 urls for reliability.
- Ensure that named IMPORT/EXPORT connections match.
- Inline tooltips and X3D specification
Prototype Declarations
- Follow X3D 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
- X3D specification
External Prototype Declarations
- 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.
- ExternProtoDeclare tooltips and X3D specification
Prototype Instances
- 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.
- ProtoInstance tooltips and X3D specification

License

An open-source license is applied to X3D models and source code produced by NPS (and others) for the various Web3D and Savage model archives. Typically the following meta tag is included in archived X3D scenes:
```
<meta name="license" content="../../license.html">
```
The license is available as license.html and also available in plain-text form as license.txt for embedding in source-code files. Under the terms of this BSD open-source license both commercial & noncommercial uses are permitted, and the contributing authors retain original copyright as appropriate. This license can be adapted for use by other open-source contributors, if desired. Discussion, rationale and references regarding this license are available via the XMSF bugtracker license entry.

`meta` tags

Follow meta-tag norms found in newScene.x3d (.html)
Description tags 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 tags with *default content descriptions*
Remove extraneous trailing newline characters.
Ensure you include both <meta name="filename"/> and <meta name="url"/> tags, with filename values ending in .x3d (rather than .wrl).
Default metadata conventions are defined by the Dublin Core metadata terms.
Translation programs should indicate that the output file is a conversion by adding a meta tag such as
<meta name="generator" content="X3D-Edit, http://www.web3d.org/x3d/content/README.X3D-Edit.html"/>
or
META "generator" "X3D-Edit, http://www.web3d.org/x3d/content/README.X3D-Edit.html"
This matches best practices in XHTML.

Naming Conventions

CamelCaseNaming: capitalize each word, never use abbreviations, strive for clarity, and be brief but complete.
startWithLowerCaseLetter when defining field names (i.e. attributes) for 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.
Use the underscore character ("_") to indicate subscripts on mathematical variables. Otherwise avoid use of underscores since they look like whitespace when part of a URL address.
Avoid use of hyphens ("-") since these are erroneously turned into subtraction operators when converted into class or variable names.
Naming conventions apply to .x3d files, image files, and Prototypes. It is also a good idea to follow them for DEF/USE names.
Use lower case for filename extensions. Examples: .png .jpg .txt
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
Good choice of directory & subdirectory names can help keep scene names terse.

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

ConsistentDescriptiveName
.PhysicalLocation (for example .KauaiHawaii)
.SequenceNumber
.01Month200x
.ext

General notes on naming conventions:

These conventions are suitable for X3D scenes, XML tagset design, and corresponding Java classes.
This approach matches 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.

Scripts

Caveat: many more tips will be added as we begin working on Scene Access Interface (SAI).
Be sure to set <Script directOutput='true'> when using SFNode/MFNode fields.
Use Browser.print(...) rather than a simple print(...) function when printing to the console. For backwards compatibility, X3dToVrml97.xslt will strip the preceding Browser. class qualifier when converting scripts to VRLM97.
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>
```

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

URL Links

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.
Look at X3D examples and SAVAGE examples for sample usage of multiple (relative and online) url fields.
Run a link checker to verify URLs are correct. This step is performed periodically on the X3D/Savage content archives.
- W3C Link Checker (with documentation)
- Xenu's Link Sleuth
Include "quotation marks" around each individual address, since url has type MFString.
XML-aware editors may escape each " character as " for proper XML encoding. When using a text editor directly, it may be easiest to enclose the entire field in 'apostrophes' as shown next.

Usage examples:

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

<ImageTexture url="&quot;earth-topo.png&quot;&#10;&quot;earth-topo-small.gif&quot;"/>

References

Viewpoints

Initial viewpoint is typically on +Z-axis, looking toward origin along -Z-axis. This helps provide consistent catalog viewing.
Since the default body coordinate system is aligned along +X-axis with +Y-axis up, individual entities are typically pointed to right when seen from default view.
Use clear, understandable description fields. Viewpoints are a primary user tool for scene navigation.
Use the object's name first when many viewpoints follow, so that they are more easily identified in the viewpoint list.
Use whitespace instead of underscores in Viewpoint (and sensor) descriptions.
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 development/ViewpointGroup prototype (online prototype) to hide high-detail viewpoints from the viewpoint list at long ranges. This allows scalability of many objects in a single 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.

Updated: 14 April 2007
Maintained by Don Brutzman (brutzman at nps.edu). Comments & suggestions are welcome.
Online at http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html