![]() |
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
.midi
and .wav
files (Windows Macintosh Linux).
.wav
format is required, while .midi
and .mp3
support are recommended.
.x3db
) format
or putting Web3D examples into version control.
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.
containerField
values for each node are correct in most cases, so the need to override default containerField
values is relatively rare.
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.
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.
1. |
CADFace
can contain a single
Shape,
LOD or
Transform
node with containerField='shape'
(rather than default containerField='children' ).
|
2. |
CollidableShape
can contain a single
Shape
node with containerField='shape'
(rather than default containerField='children' ).
See
containerFieldChoicesGroupLODShapeTransform .
|
3. |
Collision
can contain a single nonrendered proxy
Shape
(or X3DGroupingNode )
node with containerField='proxy'
(rather than default containerField='children' ).
See
containerFieldChoicesGroupLODShapeTransform .
|
4. |
ComposedCubeMapTexture
can contain up to six X3DTexture2DNode (e.g.
ImageTexture)
nodes, each with a unique containerField value: back, bottom, front, left, right, or top
(rather than default containerField='texture' ).
|
5. |
Coordinate,
CoordinateDouble
have default containerField='coord' when parent is an geometry node,
have containerField value of skinCoord or skinBindingCoords when parent node is
HAnimHumanoid
and have containerField='controlPoint' when parent is a NURBS node.
|
6. |
GeoLOD
can contain multiple X3DChildNode nodes with containerField='rootNode' .
Curiously
GeoLOD
is not allowed to have child nodes with default containerField='children' defined in a scene,
since that field is defined differently with accessType outputOnly and
thus is only able to send MFNode events at run time.
|
7. |
HAnimHumanoid
can contain a single
Group,
LOD,
Shape
or
Transform
with containerField='skin'
rather than default containerField='children' . See
containerFieldChoicesGroupLODShapeTransform .
|
8. |
HAnimJoint
has default containerField='children' when parent is another
HAnimJoint,
and has containerField value of joints or skeleton when parent node is
HAnimHumanoid.
|
9. |
HAnimSegment
has default containerField='children' when parent node is an
HAnimJoint,
and has containerField='segments' when parent node is
HAnimHumanoid.
|
10. |
HAnimSite
has default containerField='children' when parent node is an
HAnimSegment,
and has containerField value of sites , skeleton or viewpoints when parent node is
HAnimHumanoid.
|
11. |
LoadSensor
is a parent node that can monitor the loading of one or multiple child nodes
having containerField='watchlist' .
Such child nodes implement object interface
X3DUrlObject
and include
Anchor,
AudioClip,
DISEntityTypeMapping,
GeoMetadata,
ImageCubeMapTexture,
ImageTexture,
ImageTexture3D,
Inline,
MovieTexture,
PackagedShader,
Script,
ShaderPart
and
ShaderProgram.
|
12. |
MetadataSet
can contain multiple other child X3DMetadataNode nodes by setting their containerField='value'
(rather than default containerField='metadata' ).
Similar to the other metadata nodes,
MetadataSet
can also contain a single X3DMetadataNode node describing itself (with default containerField='metadata' ).
Important tooltips:
|
13. |
Normal
has default containerField='normal' when parent is an geometry node,
and has containerField value of skinNormal or skinBindingNormals when parent node is
HAnimHumanoid.
|
14. |
ParticleSystem
can contain a single
Color
or
ColorRGBA
node with containerField='colorRamp'
(rather than default containerField='color' ).
ParticleSystem
can also contain a single
TextureCoordinate
node with containerField='texCoordRamp'
(rather than default containerField='texCoord' ).
|
15. |
Sound
can contain a single
MovieTexture
node with containerField='source'
(rather than default containerField='texture' ).
|
16. |
TextureBackground
can contain up to six X3DTexture2DNode (e.g.
ImageTexture)
nodes, each with unique containerField values: backTexture, bottomTexture, frontTexture, leftTexture, rightTexture, or topTexture
(rather than default containerField='texture' ).
|
17. |
X3DTexture3DNode
nodes
ComposedTexture3D,
ImageTexture3D
and
PixelTexture3D
nodes can have one of several containerField values, depending on relationship to parent node:
texture (default), gradients, surfaceNormals, segmentIdentifiers , watchList (for ImageTexture3D with parent LoadSensor), or voxels .
|
All of the various X3D file encodings define parent-child relationships, in one way or another.
The containerField
attribute is used to express this relationship in the .x3d XML encoding.
Since only a relatively small number of node usages ever require a non-default containerField value,
the XML encoding is actually much more terse than other X3D encodings.
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.
containerFieldChoicesAudioClip
for
AudioClip.
containerFieldChoicesColor
for
Color,
ColorRGBA.
containerFieldChoicesDISEntityTypeMapping
for
DISEntityTypeMapping.
containerFieldChoicesGroupLODShapeTransform
for
Group,
LOD,
Shape,
Transform.
containerFieldChoicesHAnimJoint
for
HAnimJoint
containerFieldChoicesHAnimSegment
for
HAnimSegment.
containerFieldChoicesHAnimSite
for
HAnimSite.
containerFieldChoicesMetadata
for six Metadata* nodes
MetadataBoolean,
MetadataDouble,
MetadataFloat,
MetadataInteger,
MetadataString,
MetadataSet.
containerFieldChoicesPackagedShader
for
PackagedShader.
containerFieldChoicesShaderPart
for
ShaderPart.
containerFieldChoicesTextureCoordinate
for
TextureCoordinate,
TextureCoordinateGenerator.
containerFieldChoicesX3DTexture2DNode
for
PixelTexture,
MultiTexture.
containerFieldChoicesX3DTexture3DNode
for nodes with abstract type
X3DTexture3DNode,
namely
ComposedTexture3D,
ImageTexture3D,
PixelTexture3D.
containerFieldChoicesX3DUrlObject
for non-texture nodes supporting abstract type
X3DUrlObject,
namely
Anchor,
GeoMetadata,
Inline,
Script.
containerFieldChoicesX3dUrlObjectTexture
for texture nodes supporting abstract type
X3DUrlObject,
namely
ImageTexture,
MovieTexture,
ImageCubeMapTexture.
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.
back
becomes backTexture
, top
becomes topTexture
, etc.
containerField='mapping'
and rename as
containerField='children'
instead.
containerField='watchList'
and rename as
containerField='children'
instead.
Child node restrictions can achieve a functionally equivalent effect and improve the object-oriented design.
colorRamp
, texCoordRamp
and rename as regular defaults
color
, texCoord
instead.
Not accepted for X3D4: nodes with working functionality but proposed design refinements were not workable.
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
.
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.
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.
containerField='rootNode'
and rename as
containerField='children'
instead.
Also enter Mantis issue
to implement object interface
X3DUrlObject.
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.
"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.
http://localhost:8001/
http://localhost:8001/
is needed within the .html or .x3d files themselves, so
they remain ready to publish externally without any internal changes.
For authoring on localhost: examples follow, showing each step.
Step 1: Java http server
For example, if Java 18 or greater is installed, you can run the following Java command-line invocation in the directory of interest.
$ [system] cd 'installs\www.web3d.org\x3d\content\examples' [system] /cygdrive/c/x3d-code/www.web3d.org/x3d/content/examples $ [system] jwebserver --port 8001 --bind-address 0.0.0.0 --output verbose Serving C:\x3d-code\www.web3d.org\x3d\content\examples and subdirectories on 0.0.0.0 (all interfaces) port 8001 URL http://10.0.0.227:8001/ # To test localhost http server running: # view directory contents by opening web browser with http://localhost:8001
Step 1, alternative: Python http server
For example, if Python 3 is installed, you can run the following command-line invocation in the directory of interest.
$ [system] cd 'C:\installs\www.web3d.org\x3d\content\examples' [system] /cygdrive/c/x3d-code/www.web3d.org/x3d/content/examples $ [system] python -m http.server 8001 Serving HTTP on :: port 8001 (https://[::]:8001/) ... # To test localhost http server running: # view directory contents by opening web browser with http://localhost:8001
Step 2: HTML5 file invocation of X_ITE
Once the http server is running, use your web browser to select the .html page of interest containing your .3d model. For example:
http://localhost:8001/HelloWorldX_ITE.html
(online)
http://localhost:8001/HelloWorldX_ITE.localhost.html
(online)
Available capability: X3D-Edit authoring tool can launch a local http server to handle all CORS steps automatically when developing locally with X_ITE.
CORS client-side references:
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:
License
for related details.
TODO
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'/>
4 July 2014
(rather than other forms such as
July 4, 2014
,
7/4/14
,
or
4/7/2014
).
x3d+xml
(for .x3d files), x3d-vrml
(for .x3dv files) and x3d+fastinfoset
(for .x3db files).
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 is the publishing language of the World Wide Web. HTML web pages can embed or launch X3D scenes.
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
CoolImage.png
vice CoolImage.PNG)
.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.
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.
.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"'/>
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.
IMPORT
/EXPORT
connections match.
Inline
tooltips
and
X3D specification
describe functionality in detail.
Inline
node with profile information to assist in overall scene validation. Example:
<Inline url='"string array addressvalues"'> <MetadataString name='profile' value='Immersive'/> </Inline>
ProtoBody
.
ProtoDeclare
definitions into additional scenes,
instead copy ExternProtoDeclare
/ProtoInstance
definitions.
ProtoDeclare
,
ProtoInterface
and
ProtoBody
field
definitions in a ProtoInterface
element since that construct is illegal.
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.
ProtoDeclare
annotation tooltips for each ExternProtoDeclare
field
.
Listing default values used by the prototype can be helpful.
ExternProtoDeclare
tooltips
and
X3D specification
containerField
attribute, identifying parent-node field name for this ProtoInstance
.
Default value: children
.
Example values: color
, coord
, geometry
, fontStyle
, proxy
, sound
, texture
, textureTransform
.
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.
metadata
field to the defining ProtoDeclare. For an example, see
DoubleClickTouchSensorPrototype
and
DoubleClickTouchSensorExample.
ProtoInstance
tooltips
and
X3D XML Encoding specification
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">
meta
Statements
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."/>
meta
statements with *default content descriptions*
<meta name="description" value="This description has a trailing newline character. "/>X3D Canonicalization (C14N) rules include normalization of whitespace and C14N tools can take care of this cleanup.
<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.
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.
meta
attributes.
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.
meta
statements in X3D scene headers.
containerField='metadata'
except when they are child values of a MetadataSet
node, in which case they have
containerField='value'
Motion capture (MOCAP) can be used for adding behaviors to Humanoid Animation (H-Anim) files).
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.
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.
.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.
Names which are nonsensical, unpronounceable, hard to read, or easily confusable with other names should not be employed.
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.
General notes on naming conventions:
<unit/>
for angle (default radians),
length (default meters),
mass (default kilograms) and
force (default newtons).
name
field,
since the category
field provides the strict definition of how a
conversionFactor
field is applied.
<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)
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'/>
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 |
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 |
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 |
var
declaration of variables.
Instead, declare any persistent variables as field definitions in the parent Script node.
true
and false
to match XML and ECMAScript/JavaScript rules.
Capitalized TRUE
and FALSE
are only used in VRML syntax.
<Script directOutput='true'>
when modifiable SFNode/MFNode fields are part of the Script functionality.
<
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>
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.
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);
JavaScript is a common programming language used in Web browsers for HTML and X3D scripts.
Notes on JavaScript specification naming:
JSON is a data-structure convention for JavaScript.
Strings describe text, typically for display in the
Text
node.
SFString/MFString
refers to single-field string values and multi-field string arrays, respectively.
The empty string ""
represents a blank line in an MFString array.
Representation | Specification | Equivalent Value | Example |
---|---|---|---|
Abstract Specification
(actual display value) |
5.3.14 SFString and MFString |
One, Two, Three
|
index |
XML encoding (.x3d) | 5.3.14 SFString and MFString |
string='"One, Two, Three" "" "He said, \"Immel did it!\""'
or else various XML character-entity substitution alternatives such as string='"One, Two, Three" "" "He said, \"Immel did it!\""'
string=""One, Two, Three" "" "He said, \"Immel did it!\"""
|
.x3d |
Compressed Binary Encoding (CBE) | 4.2.3 X3D canonical form |
string='"One, Two, Three" "" "He said, \"Immel did it!\""'
|
.xml |
ClassicVRML encoding (.x3dv) |
5.15 SFString and MFString
and Grammar |
string [ "One, Two, Three", "", "He said, \"Immel did it!\"" ]
|
.x3dv |
VRML97 (.wrl) |
5.15 SFString and MFString
and Grammar |
string [ "One, Two, Three", "", "He said, \"Immel did it!\"" ]
|
.wrl |
JSON encoding (.json) | X3D to JSON Stylesheet Converter: JSON strings |
"@string": [ "One, Two, Three", "", "He said, \"Immel did it!\"" ]
|
.json |
Java Scene Access Interface (SAI) | B.4.25 SFString, B.4.26 MFString |
new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""}
|
|
X3DJSAIL (.java) | SFString, MFString |
.setString(new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""})
.setString(new MFString(new String [] {"One, Two, Three", "", "He said, \"Immel did it!\""}))
.setString(new MFString("\"One, Two, Three\" \"\" \"He said, \\\"Immel did it!\\\"\""))
|
.java |
Scalable Vector Graphics (SVG) 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.
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=" "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" "/>
url
field,
since url
has type MFString
.
mailto:
links)
may require further special escaping if special characters are needed.
This section shows example declarations of DTD and Schema in X3D scenes.
One of the biggest benefits of the .x3d file encoding is XML validation. XML checks for well-formed documents, DTD validation and schema validation greatly improve quality assurance (QA) for X3D scenes. This approach exposes many possible errors and helps authors eliminate Garbage In Garbage Out (GIGO) problems. Useful links:
XML validation is defined by the Extensible Markup Language (XML) 1.0. A number of document variations are possible for X3D scenes. For example, encoding information is optional and may designate a variety of character sets. The X3D specifications are carefully designed to be fully compatible with XML requirements.
The following sections provide detailed information on the proper file syntax for X3D DTD and XML Schema headers in an .x3d scene. Each version matches the corresponding X3D version (3.0, 3.1, 3.2, and 3.3). Thanks to X3D stability, each version is backwards compatible. For example, the X3D v3.2 DTD and schema can validate X3D v3.2, v3.1, or v3.0 content, but not v3.3 content.
<?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">
<?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">
<?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.
<?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">
<?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.
C:\www.web3d.org\x3d\content> java X3dDoctypeChecker usage: java X3dDoctypeChecker sceneName.x3d [-setFinalDTD | -setTransitionalDTD]
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 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.
The X3D Graphics Volume Rendering component describes how voxels and polygons can live together in harmony within a single scene.
Note that there are no required file formats, but at least one of the following formats is recommended for volume support in an X3D browser.
Tool recommendations:
Additional resources:
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):
#VRML V2.0 utf8to
#VRML V3.3 utf8 PROFILE Immersive
Additional X3D Resources of interest:
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: 5 May 2024