Extensible 3D (X3D) encodings
Part 2: Classic VRML encoding
4 Concepts
4.1 Introduction and topicsThis clause describes key concepts in this part of ISO/IEC 19776. This includes the manner in which X3D how X3D Architecture constructs defined in ISO/IEC 19775-1 X3D Architecture are encoded using the Classic VRML encoding. (as specified in ISO/IEC 14772-1 Virtual Reality Modeling Language (VRML97).
Design for all of the X3D file encodings (this document, I19776-1 X3D XML encoding, and so forth in ISO/IEC 19776 series) and X3D programming-language bindings (ISO/IEC 19776 series) includes full expressive power for the X3D Architecture ISO/IEC 19775-1 X3D Architecture.
See Table 4.1 for the topics in this clause.
Editors note: work under review has matched corresponding organization found in
19776-1 XML Encoding Concepts
and
19776-2 Classic VRML Encoding Concepts.
Unchanged prose in this document is not highlighted if it is only moved.
Consistent document structure will further assist in the similar creation of
future X3D Encoding specifications (e.g. JSON, Turtle).
TODO support for id, class, and style attributes in order to support interoperability with other encodings, and to allow integration with X3D Architecture 4.0, Annex L, HTML Authoring Guidelines.
The following conventions are used throughout this part of ISO/IEC 19776:
Italics are used for event and field names, and are also used when new terms are introduced and equation variables are referenced.
A fixed-space font is used for URL addresses and source code
examples. ISO/IEC 19776 Classic VRML encoding examples appear in bold,
fixed-space font.
Node type names are appropriately capitalized (e.g., "The Billboard node is a grouping node..."). However, the concept of the node is often referred to in lower case in order to refer to the semantics of the node, not the node itself (e.g., "To rotate the billboard...").
The form "0xhh" expresses a byte as a hexadecimal number representing the bit configuration for that byte.
Normative references and informative Bibliography entries are linked via document identifiers.
EXAMPLE
Functional requirements are defined by
ISO/IEC 19775-1 X3D Architecture.
TODO follow this pattern throughout.
With the exception of International Standards, throughout this part of ISO/IEC 19776, references to external documents are denoted using the “x.[ABCD]” notation, where "x" denotes in which clause or annex the reference is described and “[ABCD]” is an abbreviation of the reference title. References without the "x." are references to the bibliography. International Standards are referenced by their number and link to the appropriate entry in 2 Normative references.
EXAMPLE [ABCD] refers to a reference described in Clause 2 and [ABCD] refers to a reference described in the Bibliography. TODO: fix, distinguish [ABCD] references
see Mantis 1125
TODO Remove "x." notation, express clearly. Remove [square brackets] from all references.
Follow form shown in ISO Directives Part 2, section 15.5.3 Referencing, using "ISO/IEC".
Identifiers can be used in the hyperlinks.
4.2 Overview
An X3D file is structured as defined
by 7.2.5 Abstract X3D structure
in
ISO/IEC 19775-1 X3D Architecture.
This part of ISO/IEC 19776 specifies
syntax for the Classic VRML encoding,
which was first defined for models using the
ISO/IEC 14772-1 Virtual Reality Modeling Language (VRML97).
In general, VRML97 syntax is nearly identical and model semantics are fully preserved.
a syntax that satisfies the requirements
specified by
ISO/IEC 19775-1 X3D Architecture.
There is a fundamental and complete correspondence between the elements of the abstract X3D scene graph and constructs in the Classic VRML encoding. The Classic VRML Encoding has full expressive power for all scene constructs defined by ISO/IEC 19775-1 X3D Architecture. This section describes the design patterns that govern the correspondence.
(the following was moved from original location in 4.3.2.1 Organization of statements)
After the required statements Header statement as defined in 4.2.3.1 File descriptor, X3D version and character encoding 4.3.2.2 Header statement syntax, an X3D file shall contain
NOTE
There is no Scene statement and no HEAD statement in the Classic VRML encoding.
After the model configuration information defined by the preceding paragraph, an X3D file may contain any combination of the following:
The following example shows a minimal but complete X3D model.
EXAMPLE Classic VRML syntax for a complete X3D model.
#X3D V4.0 utf8 PROFILE Immersive # [X3D] version=4.0 # [X3D] noNamespaceSchemaLocation=https://www.web3d.org/specifications/x3d-4.0.xsd # [head] COMPONENT Geospatial:1 COMPONENT NURBS:2 UNIT length Centimeters 0.01 META "description" "X3D scene header and prototype syntax examples." META "title" "X3dHeaderPrototypeSyntaxExamples.x3dv" META "identifier" "https://web3d.org/x3d/content/examples/Basic/development/X3dHeaderPrototypeSyntaxExamples.x3dv" # [Scene] ========== ========== ========== # Scene graph nodes are added here
This example indicates that the content is Classic VRML using the utf8 character encoding, matches X3D version 4.0, follows the Immersive Profile, and explicitly lists additional expected components. The X3D header section may also contain further semantic information, using META statements for metadataTerm=value pairs.
Header sections appear at the top of an X3D file to properly identify the file encoding, along with X3D version and profile information, thus enabling correct parsing to commence upon initial file loading. Additional information is also provided regarding document-specific information such as necessary components, unit conversions of numeric base types, and name=value pairs for document-specific metadata.
The header section for every Every Classic VRML-encoded X3D file shall begin with the following file-description line, where version number is one of the allowed X3D version values (e.g. V3.0, V3.1, V3.2, V3.3, or V4.0).
#X3D V4.0 <character encoding type> [optional comment] <line terminator>
#X3D V3.3 <character encoding type> [optional comment]<line terminator>
The file-description line header is a single line of UTF-8 text identifying the file as an X3D file and identifying the version of X3D encoded and character encoding type of the file. It may also contain an optional comment following the character encoding type specification.
There shall be exactly one space separating "#X3D" from "V4.0" “V3.3” and "V4.0" “V3.3” from "<character encoding type>".
This part of ISO/IEC 19776 specifies a single character encoding type, "utf8",
that indicates a clear text character encoding allowing for international
characters to be displayed using the UTF-8
encoding defined in
ISO/IEC 10646 Universal Coded Character Set (UCS)
(otherwise known as Unicode).
The usage of UTF-8 is specified in X3D Architecture
Text component
ISO/IEC 19775-1 X3D Architecture.
TODO: what about utf16? Suggest adding:
The character encoding "utf16" is also a permitted.
The "<character encoding type>" can be followed by one or more space
(0x20) or tab (0x09) characters
followed by any other characters providing an
"[optional comment]",
before being terminated by a
linefeed (0x0a) or carriage-return (0x0d) character.
Also, the "<character encoding type>" shall be followed by a
linefeed (0x0a) or carriage-return (0x0d) character, or by one or more space
(0x20) or tab (0x09) characters followed by any other characters, which are
treated as a comment, and terminated by a linefeed or carriage-return character.
A PROFILE statement consists of the word PROFILE followed by the name of any of the profiles specified in ISO/IEC 19775-1 X3D Architecture.
PROFILE <profileName>
Profiles are discussed in 4.6 Profiles of ISO/IEC 19775-1 X3D Architecture.
See A.2 General for details on PROFILE statement grammar rules.
A COMPONENT statement consists of the COMPONENT followed by a component support indication as follows:
COMPONENT <componentName>:<supportLevel>
The support level is an integer identifying one of the available support levels specified in the various component clauses of ISO/IEC 19775-1 X3D Architecture. or new clauses specified in additional parts of that document. Components are discussed in ISO/IEC 19775-1 X3D Architecture 4.5 Components.
See Annex A Grammar, A.2 General for details on COMPONENT statement grammar rules.
A UNIT statement consists of the UNIT keyword followed by a unit specification as follows:
UNIT <category> <name> <conversion_factor>
The <category> is one of the four base unit categories specified in ISO/IEC 19775-1 X3D Architecture 4.3.6. The <name> and <conversion_factor> fields are described in ISO/IEC 19775-1 X3D Architecture 7.2.5.5.
See A.2 General for details on UNIT statement grammar rules.
A META statement consists of META followed by a string identifier for the metadata and a string containing the value of the metadata as follows:
META <key> <value>
The three parts of the META statement shall be separated by white space. Both <key> and <value> are quoted strings that may contain any character in the set specified by character encoding type. "<character encoding type>".
See A.2 General for details on META statement grammar rules.
4.3 X3D Classic VRML encoding file syntaxThis clause describes the syntax of Classic VRML-encoded, human-readable X3D files. A more formal description of the syntax may be found in Annex A Grammar. The syntax of X3D in terms of the Classic VRML encoding are presented in this part of ISO/IEC 19776. The semantics of X3D are as defined in ISO/IEC 19775-1 X3D Architecture.
For the Classic VRML encoding, the # character begins a comment. The first line of the file, the header, also starts with a # character. Two forms of comment are allowed, a single line comment and a block comment. A single line comment starts with a # and continues until the next line or file terminator, whichever comes first. A block comment starts with #/* and continues until */#. Line terminators are ignored. An unterminated block comment is an error.
Within either a single line comment or a block comment, all characters are ignored except as described above. A single line or block comment cannot start within a double-quoted SFString or within MFString fields. Within an SFString or MFString field, the # character or #/* character sequence is considered part of the SFString or MFString field.
Commas, spaces, tabs, linefeeds, and carriage-returns are separator characters wherever they appear outside of string fields. Separator characters and comments are collectively termed whitespace.
An X3D document server may strip comments and extra separators including the comment portion of the header line from an X3D file before transmitting it. Metadata, as defined in ISO/IEC 19775-1 X3D Architecture 7.2.4, should be used for persistent information such as copyrights or author information.
Field, event, PROTO, EXTERNPROTO, and node names shall not contain control characters (0x0-0x1f, 0x7f), space (0x20), double or single quotes (0x22: ", 0x27: '), sharp (0x23: #), comma (0x2c: ,), period (0x2e: .), brackets (0x5b, 0x5d: []), backslash (0x5c: \) or braces (0x7b, 0x7d: {}). Further, their first character shall not be a digit (0x30-0x39), plus (0x2b: +), or minus (0x2d: -) character. Otherwise, names may contain any character encoded using UTF-8 as defined in ISO/IEC 10646 Universal Coded Character Set (UCS). X3D is case-sensitive.
EXAMPLE "Sphere" is different from "sphere" and "BEGIN" is different from "begin."
In order to maintain interoperable conversion capabilities between the various file encodings and programming-language bindings for X3D models, the The following reserved keywords shall not be used for field, event, PROTO, EXTERNPROTO, or node names:
(prior prose moved to 4.2.2 Structure of an X3D file )
It is important to note that X3D statements are distinct from X3D nodes and X3D fields, with separate semantics as defined by the ISO/IEC 19775-1 X3D Architecture.
PROFILE, COMPONENT, UNIT, and META are X3D statements and expressed syntactically as shown in Header section. Additional statements appear in the following subclauses.
NOTE
The following X3D statements are structural expressions suitable for the X3D XML encoding I19776-1 X3D XML encoding that do not need to be expressed syntactically in this document, the X3D Classic VRML encoding. Since they are structural, these statements can be inferred from a file using Classic VRML encoding if converting into another file encoding or programming-language binding. If desired, they can be included as informative comments.
- Scene which reinforces the location of the root note, following the head section, similar to HTML body element.
- connect which is helpful for expressing multiple IS connections to a single field.
- ProtoInterface which collects field declarations for a ProtoDeclare prototype declaration.
- ProtoInstance which provides a comment element name for prototype instances. This term is implicit in the Classic VRML encoding, each time a prototype is instantiated (including with DEF and USE).
A PROTO statement consists of the PROTO keyword, followed in order by the prototype name, prototype interface declaration, and prototype definition:
PROTO <name> [ <declaration> ] { <definition> }
See A.2 General for details on prototype statement grammar rules.
A prototype interface declaration consists of field declarations (see 4.3.4 4.3.2.8 Field statement syntax) enclosed in square brackets. Whitespace is not required before or after the brackets.
Field declarations consist of the keyword "field" followed by a field type, a name, and an initial field value of the given field type.
field <fieldType> <name> <initial field value>
The body of a node statement that is inside a prototype definition may contain IS statements. The IS statement is a replacement for the otherwise-required initialization value. An IS statement follows consists of the name of a field from the node's public interface and replaces the value with followed by the keyword IS followed by the name of a field from the prototype's interface declaration:
<fieldName> IS <fieldName>
See A.3 Nodes for details on prototype node body grammar rules.
An EXTERNPROTO statement consists of the EXTERNPROTO keyword followed in order by the prototype's name, its interface declaration, and a list (possibly empty) of double-quoted strings enclosed in square brackets. If there is only one member of the list, the brackets are optional.
EXTERNPROTO <name> [ <external interface declarations> ] URL or
[ URLs ]
An external prototype interface declaration consists of zero or more field declarations enclosed in square brackets (see 4.3.4 4.3.2.8 Field statement syntax). Declared fields do not include default initialization values since those are defined in the original PROTO. Whitespace is not required before or after the brackets.
See A.2 General for details on external prototype statement grammar rules.
(bullet list inserted for readability and clarity)
A ROUTE statement consists of the ROUTE keyword followed in order by
Whitespace is allowed but not required before or after the period characters.
Syntax summary:
ROUTE <DEFname>.<fieldName> TO <DEFname>.<fieldName>
ROUTE <name>.<field/eventName> TO <name>.<field/eventName>
See A.2 General for details on ROUTE statement grammar rules.
An EXPORT statement consists of the EXPORT keyword followed by a the name of the node to be exported, followed optionally by a space, the AS keyword, a space, and an alias for the exported node:
EXPORT <nodeToExport> [AS <alias>]
See A.2 General for details on EXPORT statement grammar rules.
An IMPORT statement consists of the IMPORT keyword followed by a the name of an Inline node, a period character, name of node to import, followed optionally by a space, the AS keyword, a space, and an alias for the imported node:
IMPORT <inlineNodeName>.<nodeToImport> [AS <alias>]
See A.2 General for details on IMPORT statement grammar rules.
Node and field definitions consist A node statement consists of an optional name for the node followed by the node's type and then the body of the node. A node is given a name using the keyword DEF followed by the name of the node. The node's body is enclosed in matching braces ("{ }"). Whitespace shall separate the DEF, name of the node, and node type, but is not required before or after the curly braces that enclose the node's body. See A.3 Nodes, for details on node grammar rules.
[DEF <name>] <nodeType> { <body> }
A node's body consists of any number of field statements, IS statements, ROUTE statements, PROTO statements or EXTERNPROTO statements, in any order.
A field definition statement consists of the name of the field followed by the field's value(s). The following illustrates the syntax for a single-valued field:
<fieldName> <fieldValue>
The following illustrates the syntax for a multiple-valued field:
<fieldName> [ <fieldValues> ]
See A.4 Fields for details on field statement grammar rules.
Each node type defines the names and types of the fields that each node of that type contains. The same field name may be used by multiple different node types. See ISO/IEC 19775-1 X3D Architecture 5 Field type reference for the specification of field types.
A USE statement consists of the USE keyword followed by a node DEF name:
USE <DEFname> <name>
For Classic VRML interoperable conversion,
note that certain characters are not allowed as DEF or USE identifiers,
as specified in Annex A Grammar.
Such characters are best avoided, especially the
period character (. or 0x2E)
since it is used as part of the syntax for ROUTE construction in the
Classic VRML encoding.
See A.2 General for details on USE statement grammar rules.
This subclause corresponds to XML encoding 4.3.2.2 ProtoInstance node and fieldValue statement syntax
Prototype instances are nodes that are created simply by using the name of a declared prototype or external prototype. These nodes can include zero or more field initializations that must be correctly typed, are only used for field definitions with accessType of initializeOnly or inputOutput, and override any default values defined in the corresponding prototype declaration.
EXAMPLE 1 Two PROTO instantiations using typed field initialization
Transform {
translation 0 -2.5 0
children [
Shape {
appearance Appearance {
EmissiveMaterial {
onlyColor 0.2 0.6 0.6
}
}
geometry Text {
string [ "Prototype syntax" "examples" ]
fontStyle FontStyle {
justify [ "MIDDLE" "MIDDLE" ]
}
}
}
]
}
DEF MyVPO ViewPositionOrientation {
enabled true
}
EXAMPLE 2 ProtoInstance USE node
USE MyVPO
Comments are often important for explaining model design or work in progress. Comments do not affect the rendering or interaction of an X3D model. Nevertheless, comments are essential information to communicate author intent, design considerations, model capabilities, and expectations for continued development. Comment functionality is described in ISO/IEC 19775-1 X3D Architecture X3D Architecture, Core component, 7.2.5.1 Organization.
Two forms of comment syntax are possible in the Classic VRML encoding, single-line comments and block comments, each described in Grammar A.1.2 Overview.
EXAMPLE
WorldInfo { } # this is a single-line comment between nodes or statements
WorldInfo {
title "comment test" # this is another single-line comment following a simple field
}
#/* This is a block comment
WorldInfo { }
Group { }
*/#
NOTE
X3D model comments might not necessarily be preserved by intermediate processes when compressed, or when X3D files are relayed over the Web. Further, the exact placement of comments within an X3D model's structure may necessarily vary among X3D file encodings and programming language bindings. When appropriate, critical model information can also be retained in a lossless and consistently structured fashion by capturing it within META statements or the various Metadata nodes.
4.4 X3D files and the World Wide Web
4.4 File extension and MIME typesThe file extension for Classic VRML UTF-8 encoded X3D files is ".x3dv". The MIME type (see RFC2077) for X3D files encoded in the Classic VRML encoding is "model/x3d+vrml".
For Classic VRML encoded X3D files that are compressed using gzip (see RFC1952), the file extension shall be either ".x3dvz" or ".x3dv.gz". The MIME type for such files is "model/x3d+vrml", and the . The content-encoding value is "gzip".
Consider adding section on how X3DV files can be loaded for usage within Web browsers by conversion to XML for HTML.
Consider adding section on informal methods for scene validation, including regular expressions (regexes) (see Mantis 1456).
Need at least two subclauses per clause, otherwise the single-subclause prose does not get numbered.