X3D Scene Authoring Hints
A collection of style guidelines, authoring tips and best practices to improve the quality, consistency and maintainability of X3D scenes.
Coordinate Systems |
Images and Videos |
Inlines and Prototypes |
meta Tags |
Naming Conventions |
URL Links |
X3D for Web Authors |
X3D Resources |
is an excellent open-source audio editing and recording tool (Windows Macintosh Linux).
is an excellent open-source music-score editing and recording tool that can produce
.wav files (Windows Macintosh Linux).
can typically play audio files.
X3D player support for the
.wav format is required, while
.mp3 support are recommended.
Other audio formats are optional, you are welcome to check documentation for browsers of interest.
So far, no streaming protocol is required to be supported in X3D players.
For reliability an author can use a variety of formats at once, if desired. See
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
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.
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
for questions about node and field usage.
These are embedded in X3D-Edit popups, and are also available separately in
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 (
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
frequently to learn more.
X3D Abstract Specification
is especially important since it describes X3D functionality in complete detail.
You may also want to extract and install a
on your local system.
(Local copies of all current X3D specifications are also bundled with X3D-Edit.)
Each Transform node can create a new relative coordinate system for all children nodes in the scene graph.
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.
- 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:
- Coordinate-system gimbals, including DIS axis conversions:
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.
Ensure that all contributors to your content receive proper credit.
Basic X3D Examples,
VRML 2.0 Sourcebook,
X3D ConformanceNist Suite,
X3D for Web Authors
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 respective owners.
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.
- Use meta tags to note the dates when a scene is created and revised:
<meta name='created' content='1 October 2003'/>
<meta name='revised' content='18 May 2013'/>
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,
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.
X3D MIME Types
wiki page contains lots of detail on character encodings for X3D.
Name identifiers (DEF/USE and Prototype names), sometimes referred to as
must only use UTF-8 characters.
Note that a variety of character encodings are possible for the XML-based .x3d encoding
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.
HTML is the publishing language of the World Wide Web.
HTML web pages can embed or launch X3D scenes.
is an open-source Web document editor from the World Wide Web Consortium (W3C)
supporting HTML5, stylesheets, SVG and other document formats.
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
is an example HTML scene with X3D object tag to copy, edit and reuse.
Ensure HTML content is valid.
Encoding values for special characters in XML/HTML files are found under
Character entity references in HTML.
Want to learn more about HTML? Many books and online tutorials are available.
Recommended: online lessons by
Looking ahead: the
X3D and HTML5
effort is working to ensure the best possible integration of X3D with HTML.
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.
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.
Choice of image file formats:
Choice of video file formats:
X3D browser support for the
MPEG1 video file format
format is required by the
definition in the
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
deserve credit for maintaining this important achievement. Feel free to join or contribute
so that such efforts can continue.
image file formats exist.
The best authoring practice is to use
to convert the original image
.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.
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
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
For an example conversion program, see
which was used to create
Do not add images or videos to open-source archives without proper permissions and
W3C Image Info Service
to check the properties of your online image.
- 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.
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.
Ensure that named
- 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
Include annotation tooltips for each field.
ProtoDeclare definitions into additional scenes,
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:
- 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
corresponding to each NewNodePrototype.x3d scene.
This encourages authors to avoid copying the
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
Listing default values used by the prototype can be helpful.
- 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
First debug proper
ProtoInstance operation in the scene defining the original
ProtoDeclare, rather than
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
ExternProtoDeclare is being referenced.
There are many kinds of
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
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 Chisel, Meshlab, X3D-Edit quality assurance (QA), Xj3D CAD filter, etc.
Tool names for nodes are often quite obscure.
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.
X3D CAD Working Group
is a good 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
can support secure distribution of sensitive portions of an X3D model (such as the high-value NURBS representation).
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.
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.
There are multiple requirements for characters allowed in DEF/USE names.
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.
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:
Good choices for directory and 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.
- .PhysicalLocation (for example .KauaiHawaii)
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.
By default, the X3D International Standard uses the
International System of Units
(Système international d'unités (SI)),
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
provides support for scene-wide definition of alternate measurement:
for angle (default radians),
length (default meters),
mass (default kilograms) and
force (default newtons).
supports convenient Transform scale selection or definition of alternate units.
Additional conversion tools include
Unit conversion information site,
Wikipedia unit conversion factors,
Online unit conversion site
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
Common scaling factors, from given angular unit to radians
|Degrees ||Full Circle ||Grads
|0.0174532925167 (Pi/180) ||6.283185307179 ||0.01570796326795
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
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
var declaration of variables.
Instead, declare any persistent variables as field definitions in the parent Script node.
Use lower-case boolean values
FALSE are only used in VRML syntax.
Be sure to set
<Script directOutput='true'> when using SFNode/MFNode fields.
Browser.print(...) rather than a simple
when printing to the console.
Browser.print(...) is the form supported by X3D,
print(...) was VRML97 syntax and is now obsolete.
For backwards compatibility, X3dToVrml97.xslt will strip
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
> from undesirable conversions by XML parsers.
Furthermore, it eliminates the need to use
> escape-character replacements (which make script code nonportable).
<field name="message" type="SFString" accessType="initializeOnly" value="World!"/>
function initialize (timestamp)
Browser.print ('Hello ' + message);
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:
Browser.print('[ScriptNameHere] ' + 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);
Caveat: more tips will be added when we begin working on Scene Access Interface (SAI) using Java.
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:
or, if using the equivalent but more awkward syntax for "double-quoted"
url attribute values:
Sample usage of multiple (relative and online) url fields
can be found in the
Run a link checker
to verify that URLs are correct and reachable.
This step is performed periodically on the X3D example archives.
Include "quotation marks" around each individual address,
url has type
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.
Validation using DTD and XML Schema
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
X3D Specifications: DTD and Schema Validation
provides links to the latest approved DTDs, schemas and documentation.
The following sections provides 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 will validate X3D v3.1 or v3.0 content, etc.
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.
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.
to hide high-detail viewpoints from the viewpoint list at long ranges.
This allows scalability of many objects in a single scene.
Volume Tools and Volume Visualization
Fiji and ImageJ (found under Images) support image slicing from volumes.
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 software library and file format designed to support scientific visualization and image processing involving N-dimensional raster data.
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).
is a multi-platform, free and open-source software package for visualization and medical-image computing
(Windows Macintosh Linux).
Updated: 15 December 2013
(brutzman at nps.edu).
Comments & suggestions are welcome.
These hints were collected while teaching X3D Graphics and writing
X3D for Web Authors.