X3D file structure: Difference between revisions

The educational technology and digital learning wiki
Jump to navigation Jump to search
 
(11 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{stub}}
{{stub}}
{{under construction}}
{{X3D tutorial|none|beginner|}}
{{X3D tutorial|none|beginner|}}
 
<categorytree mode="pages" depth="0" style="float:right; clear:right; margin-left:3px; border:1px solid gray; padding:0.7ex; background-color:#f9f9f9;">X3D tutorials</categorytree>
== Introduction ==
== Introduction ==


This is a short summary explaining the file structure of a [[X3D]] model.
This is a short summary explaining the file structure of a [[X3D]] model. In order to understand "the message", you will need some knowledge about [[XML]], in particular XML file structure, wellformedness and validity.


[[X3D]] is a modular standard and therefore the X3D file structure is defined through several [http://www.web3d.org/x3d/specifications ISO Specifications].
[[X3D]] is a modular standard and therefore the X3D file structure is defined through several [http://www.web3d.org/x3d/specifications ISO Specifications].


Combined, these specifications are then available in terms of three types of schemas: DTD, XML Schema (XSD) and  
Combined, these specifications are then available in terms of three types of schemas: DTD, XML Schema (XSD) and Schematron


* [http://www.web3d.org/specifications/x3d-3.2.dtd x3d-3.2.dtd]. Can ensure proper parent-child element relations and attribute naming  
* [http://www.web3d.org/specifications/x3d-3.2.dtd x3d-3.2.dtd]. Can ensure proper parent-child element relations and attribute naming  
Line 17: Line 16:
== The X3D file structure ==
== The X3D file structure ==


A X3D scene is defined by the contents of a [[URL]] (i.e. either an X3D file or some generator). This resource then can include additional elements.
A X3D scene is defined by the contents of a [[URL]] (i.e. either an X3D file or some generator). This resource then can include additional elements with an ''Inline'' node.


X3D scene files have a common file structure:
X3D scene files have a common file structure:


* File header (XML, ClassicVRML, Compressed Binary)
* File header (either XML, ClassicVRML, or Compressed Binary)
* Start of the ''X3D root node'' including ''version'' and ''profile'' attributes
* Start of the ''X3D root node'' including ''version'' and ''profile'' attributes
* A ''head'' section with ''Component'' and ''Meta'' statements (both optional)
* A ''head'' section with ''Component'' and ''Meta'' statements (both optional)
* X3D ''scene'' graph and its child nodes
* The X3D ''Scene'' graph and its child nodes
* End of the X3D root node
* End of the X3D root node


We shall shortly describe these elements below. But before, let's have a look at the code of a simple exemple scene, inserted XML comments identify the elements:
We shall shortly describe these elements below. But before, let's have a look at the code of a simple exemple scene, [http://tecfa.unige.ch/guides/x3d/www.web3d.org/x3d/content/examples/HelloWorld.x3d HelloWorld.x3d], retrieved on oct. 2010 from [http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter01-TechnicalOverview/index.html Chapter 01 - Technical Overview] at [http://x3dgraphics.com/ x3dgraphics.com/]
 
Inserted XML comments identify the elements:
<source lang="xml">
<source lang="xml">


Line 86: Line 87:
<!-- -------------------- footer, closing X3D toot element -->
<!-- -------------------- footer, closing X3D toot element -->
</X3D>
</X3D>
</source>
In case you don't have a X3D client for [http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter01-TechnicalOverview/_pages/page03.html looking at this scene], it should render like this:
[[image:HelloWorld.gif|frame|none|Hello World scene screen capture]]


More complex X3D scenes are usually split over several files. To include a scene one usually positions and scales the included object, e.g. like in the example fragment below taken from the Kelp Forest exhibit that can be found at [http://x3dgraphics.com/examples/X3dForWebAuthors/KelpForestExhibit/index.html x3dgraphics.com]. Click on [http://x3dgraphics.com/examples/X3dForWebAuthors/KelpForestExhibit/_pages/page22.html Kelp Forest Main] to look at the scene, then play around with the viewpoints.
The following code can be found in the main file (KelpForestMain.x3d) and will load "Lucy the shark" from the first local or remote URL that the client can retrieve. As you can see, one also can load *.wrl files into *.X3D.
<source lang="xml">
  <Transform>
    <Inline url='"SharkLucyLocale.x3d"
                  "http://X3dGraphics.com/examples/X3dForWebAuthors/KelpForestExhibit/SharkLucyLocale.x3d"
                  "SharkLucyLocale.wrl"
                  "http://X3dGraphics.com/examples/X3dForWebAuthors/KelpForestExhibit/SharkLucyLocale.wrl"'/>
    </Transform>
</source>
</source>


Line 108: Line 123:
* version 3.1  
* version 3.1  
* version 3.2 (Version 3.2.2 was published in April 2005 and should be supported by most browsers)
* version 3.2 (Version 3.2.2 was published in April 2005 and should be supported by most browsers)
To us, it is totally unclear where versions are defined and where one can find central information about support profiles and versions by various clients and other tools - [[User:Daniel K. Schneider|Daniel K. Schneider]] 14:33, 5 October 2010 (CEST).
To us, it is totally unclear where versions are defined and where one can find central information about support profiles and versions by various clients and other tools - [[User:Daniel K. Schneider|Daniel K. Schneider]] 15:35, 5 October 2010 (CEST).


See below for more information about profiles and components
See below for more information about profiles and components
Line 180: Line 195:
  PROFILE Immersive
  PROFILE Immersive


Additional components with respect to the ones includes in the declared profile can be included in the had section as in the following [http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter01-TechnicalOverview/_pages/page01.html Header Profile Component Meta Example] (retrieved 14:33, 5 October 2010 (CEST)). The component tags raise the support level from Immersive profile to include other components included in the X3D 3.0 Full profile.
Additional components with respect to the ones includes in the declared profile can be included in the had section as in the following [http://x3dgraphics.com/examples/X3dForWebAuthors/Chapter01-TechnicalOverview/_pages/page01.html Header Profile Component Meta Example] (retrieved 15:35, 5 October 2010 (CEST)). The component tags raise the support level from Immersive profile to include other components included in the X3D 3.0 Full profile.


<source lang="xml">
<source lang="xml">
Line 199: Line 214:
=== Meta statements ===  
=== Meta statements ===  


Meta statements provide information about the X3D scene as a whole
Meta statements provide information about the X3D scene '''as a whole'''.


Information is provided as name-value pairs, for example
Information is provided as name-content pairs, for example
   <meta name='created' value='1 January 2008'/>
   <meta content='30 October 2000' name='created'/>
 
  <meta content='Don Brutzman'    name='creator'/>
This approach is thus very general and a wide variety of metadata can be represented. The X3D approach matches same approach used by HTML for regular hypertext web pages.
  <meta content='done'            name='status'/>
One can use any value in the name and content field, but there are some informal recommendations. This approach is thus very general and a wide variety of metadata can be represented. The X3D approach matches same approach used by HTML for regular hypertext web pages.


=== The X3D scene graph ===
=== The X3D scene graph ===
Line 234: Line 250:
</X3D>
</X3D>
</source>
</source>
X3D (and other) scene graphs follow a model-centric approach to 3D that hierarchically defines geometry shape, appearance, position and orientation, etc. In other words, all parameters of interest (except some scripted behaviors) are defined declaratively.
In X3D, a graph has a root node and no loops, i.e. a '''directed acyclic graph''' (DAG).
Most [[Computer-aided design and manufacturing|Computer Aided Design]] (CAD) models follow a similar approach.
In opposition, most narrative programming languages use an approach like "draw this triangle, that triangle, recompute", etc.
Read more on [[X3D shape and geometry]]


== X3D ClassicVRML syntax ==
== X3D ClassicVRML syntax ==
Line 274: Line 299:


; Specification and Schema documentation
; Specification and Schema documentation
* [http://www.web3d.org/x3d/wiki/index.php/Node_Reference Node Reference]
* [http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html X3D Scene Authoring Hints]
* [http://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html X3D Scene Authoring Hints]
* [http://www.web3d.org/specifications/X3dSchemaDocumentation3.2/x3d-3.2.html X3D v3.2 Schema Documentation]
* [http://www.web3d.org/specifications/X3dSchemaDocumentation3.2/x3d-3.2.html X3D v3.2 Schema Documentation] (very technical, this page can bring your computer to a crawling halt)
* [http://www.web3d.org/specifications/X3dDoctypeDocumentation3.2.html X3D v3.2 Doctype Documentation]
* [http://www.web3d.org/specifications/X3dDoctypeDocumentation3.2.html X3D v3.2 Doctype Documentation] (very technical)


; X3D Examples
; X3D Examples


* [http://x3dgraphics.com/examples/X3dForWebAuthors/index.html X3D for Web Authors Examples Archive]. This archive also can used as a kind of manual.
* [http://x3dgraphics.com/examples/X3dForWebAuthors/index.html X3D for Web Authors Examples Archive]. This archive also can be used as a kind of manual.
* [http://x3dgraphics.com/examples/X3dForWebAuthors/ X3D: Extensible 3D Graphics for Web Authors]. Examples from the X3D: 3D Graphics for Web Authors, by Don Brutzman and Leonard Daly, published by Morgan Kaufmann Publishers, 2007 (same web site)
* [http://x3dgraphics.com/examples/X3dForWebAuthors/ X3D: Extensible 3D Graphics for Web Authors]. Examples from the X3D: 3D Graphics for Web Authors, by Don Brutzman and Leonard Daly, published by Morgan Kaufmann Publishers, 2007 (same web site)
* In case these URLs break, we got an outdated [http://tecfa.unige.ch/guides/x3d/ local copy].
* In case these URLs break, we got an outdated [http://tecfa.unige.ch/guides/x3d/ local copy].

Latest revision as of 14:16, 6 April 2016

Draft

X3D tutorials

Introduction

This is a short summary explaining the file structure of a X3D model. In order to understand "the message", you will need some knowledge about XML, in particular XML file structure, wellformedness and validity.

X3D is a modular standard and therefore the X3D file structure is defined through several ISO Specifications.

Combined, these specifications are then available in terms of three types of schemas: DTD, XML Schema (XSD) and Schematron

  • x3d-3.2.dtd. Can ensure proper parent-child element relations and attribute naming
  • x3d-3.2.xsd. In addition, can ensure proper type-checking of most attribute values.
  • X3D Schematron. For additional validation that can't be handled by XSD.

The X3D file structure

A X3D scene is defined by the contents of a URL (i.e. either an X3D file or some generator). This resource then can include additional elements with an Inline node.

X3D scene files have a common file structure:

  • File header (either XML, ClassicVRML, or Compressed Binary)
  • Start of the X3D root node including version and profile attributes
  • A head section with Component and Meta statements (both optional)
  • The X3D Scene graph and its child nodes
  • End of the X3D root node

We shall shortly describe these elements below. But before, let's have a look at the code of a simple exemple scene, HelloWorld.x3d, retrieved on oct. 2010 from Chapter 01 - Technical Overview at x3dgraphics.com/

Inserted XML comments identify the elements: 

<?xml version="1.0" encoding="UTF-8"?>

<!-- -------------------- X3D header and X3D root node with profile declaration -->
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.2//EN"
                     "http://www.web3d.org/specifications/x3d-3.2.dtd">
<X3D profile='Immersive' version='3.2' 
     xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance'
     xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.2.xsd'>

<!-- -------------------- head section with included meta data -->
  <head>
    <meta content='HelloWorld.x3d' name='title'/>
    <meta content='Simple X3D example' name='description'/>
    <meta content='30 October 2000' name='created'/>
    <meta content='7 August 2010' name='modified'/>
    <meta content='Don Brutzman' name='creator'/>
    <meta content='http://www.web3D.org' name='reference'/>
    <meta content='http://x3dGraphics.com' name='reference'/>
    <meta content='http://www.web3d.org/x3d/content/examples/HelloWorld.x3d' name='identifier'/>
    <meta content='http://www.web3d.org/x3d/content/examples/HelloWorldTall.png' name='image'/>
    <meta content='http://www.web3d.org/x3d/content/examples/license.html' name='license'/>
    <meta content='X3D-Edit 3.2, https://savage.nps.edu/X3D-Edit' name='generator'/>
  </head>

<!-- -------------------- the X3D scene node with X3D nodes -->
  <Scene>
    <!-- Example scene to illustrate X3D nodes and fields (XML elements and attributes) -->
    <Group>
      <Viewpoint centerOfRotation='0 -1 0' description='Hello world!' position='0 -1 7'/>
      <Transform rotation='0 1 0 3'>
        <Shape>
          <Sphere/>
          <Appearance>
            <Material diffuseColor='0 0.5 1'/>
            <ImageTexture url='"earth-topo.png" "earth-topo.jpg" "earth-topo-small.gif" 
	    "http://www.web3d.org/x3d/content/examples/Basic/earth-topo.png"
	    "http://www.web3d.org/x3d/content/examples/Basic/earth-topo.jpg"
	    "http://www.web3d.org/x3d/content/examples/Basic/earth-topo-small.gif"'/>
          </Appearance>
        </Shape>
      </Transform>
      <Transform translation='0 -2 0'>
        <Shape>
          <Text string='"Hello" "world!"'>
            <FontStyle justify='"MIDDLE" "MIDDLE"'/>
          </Text>
          <Appearance>
            <Material diffuseColor='0.1 0.5 1'/>
          </Appearance>
        </Shape>
      </Transform>
    </Group>
  </Scene>

<!-- -------------------- footer, closing X3D toot element -->
</X3D>

In case you don't have a X3D client for looking at this scene, it should render like this:

Hello World scene screen capture

More complex X3D scenes are usually split over several files. To include a scene one usually positions and scales the included object, e.g. like in the example fragment below taken from the Kelp Forest exhibit that can be found at x3dgraphics.com. Click on Kelp Forest Main to look at the scene, then play around with the viewpoints.

The following code can be found in the main file (KelpForestMain.x3d) and will load "Lucy the shark" from the first local or remote URL that the client can retrieve. As you can see, one also can load *.wrl files into *.X3D. 

   <Transform>
     <Inline url='"SharkLucyLocale.x3d" 
                  "http://X3dGraphics.com/examples/X3dForWebAuthors/KelpForestExhibit/SharkLucyLocale.x3d"
                  "SharkLucyLocale.wrl"
                  "http://X3dGraphics.com/examples/X3dForWebAuthors/KelpForestExhibit/SharkLucyLocale.wrl"'/>
    </Transform>

X3D file header and filename extensions

Since X3D has grown out of VRML it has both an XML and a VRML syntax. In addition, both formats can be delivered in compressed format.

The Header for X3D / XML needs an XML declartion and an optional DTD. The XML Schema (XSD) is declared in the root node which must include a version and a profile attribute. 

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

As of october, there exist several final X3D versions:

  • version 3.0
  • version 3.1
  • version 3.2 (Version 3.2.2 was published in April 2005 and should be supported by most browsers)

To us, it is totally unclear where versions are defined and where one can find central information about support profiles and versions by various clients and other tools - Daniel K. Schneider 15:35, 5 October 2010 (CEST).

See below for more information about profiles and components

The following file extensions should be used for X3D contents:

X3D Encoding File Extension MIME Type
Classic VRML .x3dv model/x3d+vrml
XML .x3d model/x3d+xml
Binary .x3db model/x3d+binary

E.g. if you have an Apache server you could add the following lines to a *.conf file: 

AddType model/x3d+xml .x3d
AddType model/x3d+vrml .x3dv
AddType model/x3d+binary .x3db
AddEncoding gzip .x3dvz
AddEncoding gzip .x3dbz

Profiles, components

X3D has a modular architecture that defines 4 to 6 baseline profiles (depending on the version) which are are predefined collections of components. Profiles are defined with XML attributes in the X3D root node or as VRML statements on top.

In addition, within the head section, authors can specify more precisely what components are needed. Components are predefined collections of nodes and match chapters in the specification. Each profile can be augmented by adding other components

Both the mandatory profile definition and the optional components statements tells the X3D browser what level of support is needed for run-time operation.

The 3.2 specification includes six profiles:

  • Core is just the core (probably not useful for authors)
  • Interchange is the basic profile for communicating between applications. It supports geometry, texturing, basic lighting, and animation
  • CADInterchange adds support for CADGeometry component nodes to Interchange Profile.
  • Interactive enables basic interaction with a 3D environment by adding various sensor nodes for user navigation and interaction (e.g., PlanseSensor, TouchSensor, etc.), enhanced timing, and additional lighting (Spotlight, PointLight).
  • Immersive enables full 3D graphics and interaction, including audio support, collision, fog, and scripting. Corresponds to the power of VRML 97 plus minor additions.
  • MPEG4Interactive
  • Full includes all defined nodes including NURBS, H-Anim (animated interactive Avatars) and GeoSpatial components.
X3D Baseline Profiles: Source: What is X3D?, retrieved 11:53, 26 August 2010 (UTC)

Examples of X3D profile declarations 

<X3D profile='Immersive' version='3.2' 
     xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance'
     xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.2.xsd'>
</X3D>

<X3D profile='Interactive' version='3.2' 
     xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance'
     xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.2.xsd'>
</X3D>

Examples of X3D ClassicVRML profile declarations 

PROFILE Immersive

Additional components with respect to the ones includes in the declared profile can be included in the had section as in the following Header Profile Component Meta Example (retrieved 15:35, 5 October 2010 (CEST)). The component tags raise the support level from Immersive profile to include other components included in the X3D 3.0 Full profile. 

<?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 '>
<head>
<component level='1' name='DIS'/>
<component level='1' name='Geospatial'/>
<component level='1' name='H-Anim'/>
<component level='3' name='NURBS'/> 
<!-- .... content deleted -->
</head>
</X3D>

Meta statements

Meta statements provide information about the X3D scene as a whole.

Information is provided as name-content pairs, for example 

 <meta content='30 October 2000' name='created'/>
 <meta content='Don Brutzman'    name='creator'/>
 <meta content='done'            name='status'/>

One can use any value in the name and content field, but there are some informal recommendations. This approach is thus very general and a wide variety of metadata can be represented. The X3D approach matches same approach used by HTML for regular hypertext web pages.

The X3D scene graph

Each X3D file only can include one X3D scene according to XML principles. In other words there must be a single root element.

At the content level, the same principle as for HTML applies. There can be only a single scene in the same way that in HTML there is only one body

A very minimalistic valid X3D file would look like this 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE X3D PUBLIC "ISO//Web3D//DTD X3D 3.2//EN"
  "http://www.web3d.org/specifications/x3d-3.2.dtd">
 <X3D profile='Immersive' version='3.2'
      xmlns:xsd='http://www.w3.org/2001/XMLSchema-instance'
      xsd:noNamespaceSchemaLocation='http://www.web3d.org/specifications/x3d-3.2.xsd'>
 <head>
 </head>
 <Scene>
    <!-- Scene graph with a single red ball -->
    <Shape>
      <Sphere radius='2.0'/>
      <Appearance>
         <Material diffuseColor='1.0 0.0 0.0'/>
      </Appearance>
    </Shape>
 </Scene>
</X3D>

X3D (and other) scene graphs follow a model-centric approach to 3D that hierarchically defines geometry shape, appearance, position and orientation, etc. In other words, all parameters of interest (except some scripted behaviors) are defined declaratively.

In X3D, a graph has a root node and no loops, i.e. a directed acyclic graph (DAG). Most Computer Aided Design (CAD) models follow a similar approach.

In opposition, most narrative programming languages use an approach like "draw this triangle, that triangle, recompute", etc.

Read more on X3D shape and geometry

X3D ClassicVRML syntax

In our tutorials we shall not explain VRML syntax. See the VRML Primer and Tutorial we made over 10 years ago. We just point out that X3D/ClassicVRML is different from VRML1997, i.e. the ClassicVRML profile looks like VRML and uses the same syntax, but there are some changes between the last VRML standard (ISO/IEC 14772-1) and the new X3D-based ISO/IEC 19776-2. In particular, the scripting interface has been totally overhauled.

It is also important to understand the most X3D clients can render VRML 1997 (and the other way round if the VRML client is recent). 

#X3D V3.2 utf8

PROFILE Immersive

META "title" "HelloWorld.x3d"
META "description" "Simple X3D example"
META "created" "30 October 2000"
META "modified" "7 August 2010"
META "creator" "Don Brutzman"
META "reference" "http://www.web3D.org"
META "reference" "http://x3dGraphics.com"
META "identifier" "http://www.web3d.org/x3d/content/examples/HelloWorld.x3d"
META "image" "http://www.web3d.org/x3d/content/examples/HelloWorldTall.png"
META "license" "http://www.web3d.org/x3d/content/examples/license.html"
META "generator" "X3D-Edit 3.2, https://savage.nps.edu/X3D-Edit"

NavigationInfo { type [ "EXAMINE" "ANY" ] } ###  Default X3D NavigationInfo

# Example scene to illustrate a single X3D node in VRMLClassic syntax
Shape {
       geometry Sphere {  }
       appearance Appearance {
           material Material {
           diffuseColor 0 0.5 1
           }
       }
}

Links

Specification and Schema documentation
X3D Examples

Credits and Copyright modificiation

Retrieved from "https://edutechwiki.unige.ch/mediawiki/index.php?title=X3D_file_structure&oldid=58228"