[x3d-public] X3D XML Encoding: example models for Inline EXPORT/IMPORT

Sat Jun 1 10:42:21 PDT 2024

The X in X3D is Extensible.  An important aspect of that is the ability of an X3D model to export a scene sub-graph node, for potential use by a parent model which can load and access it via Inline.  The IMPORT/EXPORT statements support the Inline node to establish this capability.  Events can then be ROUTEd to and fro between the parent model and the child Inline model.

Bottom line up front (BLUF):  it works!  Test screenshots for three players:

*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportCastleModelViewer.png
*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportX_ITE.png
*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportX3DOM.png

Details follow.  The X3D 4.0 Architecture specification defines this functionality:

*	X3D Architecture version 4.0 ISO/IEC 19775-1, clause 4 Concepts, 4.4.6 Import/Export 
*	https://www.web3d.org/specifications/X3Dv4/ISO-IEC19775-1v4-IS/Part01/concepts.html#ImportExportsemantics

4.4.6 Import/Export semantics

The IMPORT feature allows authors to incorporate content defined within Inline nodes or created programmatically into the namespace of the containing file for the purposes of event routing. In contrast with external prototyping (see 4.4.5 External prototype semantics), which allows access to individual fields of nodes defined as prototypes in external files, IMPORT provides access to all the fields of an externally defined node with a single statement (see 9.2.5 IMPORT statement).

Importing nodes from an Inlined file is accomplished with two statements: IMPORT and EXPORT. The IMPORT statement is used in the containing file to define which nodes of an Inline are to be incorporated into the containing file's namespace. The EXPORT statement is used in the file being Inlined, to control access over which nodes within a file are visible to other files (see 9.2.6 EXPORT statement). EXPORT statements are not allowed in prototype declarations.

Continuing:  Dick and I have been working on resolving all issues with the X3D XML Encoding revision to match X3D 4.0.  Making good progress, documenting resolution of all issues in Mantis (as usual).  We expect to submit this working draft to ISO in the coming weeks.  As part of these efforts, we realized that the XML example for X3D Inline/EXPORT/IMPORT was not in our example archives.  Implementing and evaluating further revealed an attribute error in the XML Encoding specification prose that implementers were able to figure out correctly.

*	Mantis 697, 4.3.12 IMPORT/EXPORT statement syntax - Attribute inconsistency
*	https://www.web3d.org/member-only/mantis/view.php?id=697

*	X3D XML Encoding version 4.0, clause 4 Concepts, 4.3.12 IMPORT/EXPORT statement syntax
*	https://web3d.org/specifications/X3Dv4Draft/ISO-IEC19776-1v4.0-WD1/Part01/concepts.html#IMPORT_EXPORTStatementSyntax

The following XML syntax applies to the IMPORT/EXPORT functionality of X3D.

An IMPORT statement consists of an IMPORT element followed by attributes inlineDEF, importedDEF, exportedDEF, and (optionally) AS.

An EXPORT statement consists of an EXPORT element followed by attributes localDEF and (optionally) AS.

EXAMPLE 15 2 The following depicts the XML encoding of an EXPORT statement within the inlined InlineExport.x3d model:

<!-- file InlineExport.x3d -->
<Transform DEF='T1'> <!-- contained 3D content --> </Transform>
<!-- Hint: EXPORT statement follows node of interest, since localDEF field is similar to USE with type IDREF -->
<EXPORT localDEF='T1' AS='RootTransform'/>

EXAMPLE 16  1 The following depicts the XML encoding of an IMPORT statement within a parent scene that corresponds to a separate Inline model:

<!-- file InlineImport.x3d -->
<Inline DEF='MyInlineModel' url='"InlineExport.x3d"' DEF='I1' url='"someUrl.x3d"'/>
<IMPORT
        inlineDEF='MyInlineModel'   inlineDEF='I1'
        importedDEF='RootTransform' exportedDEF='RootTransform'
        AS='MyInlineRootTransform'  AS='I1Root'/>
<OrientationInterpolator DEF='MySpinner' key='0 0.3333 0.6667 1' keyValue='0 1 0 0, 0 1 0 2.094395, 0 1 0 4.18879, 0 1 0 0'/>
<ROUTE
        fromNode='MySpinner' fromField='value_changed'
        toNode='MyInlineRootTransform' toNode='I1Root' toField='set_rotation'/>

I’ve created and added a pair of scenes to the X3D Examples archives to demonstrate this functionality.  Note that the child model has a Text description that remains stable, while the geometry can get animated by the parent model.  These paired models conclusively demonstrate that everything is working satisfactorily.

*	X3D Example Archives: Basic, X3D Specifications, Inline Export
*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineExport.x3d
*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineExportIndex.html

*	X3D Example Archives: Basic, X3D Specifications, Inline Import
*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImport.x3d
*	https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportIndex.html
*	

It was great to see this important functionality working in X3DOM, X_ITE, and Castle Model Viewer.  Congratulations and thanks!!

Correct authoring support for Inline, EXPORT and IMPORT nodes is also supported in X3D-Edit.

*	X3D-Edit is a free, open-source Extensible 3D (X3D) Graphics authoring tool for simple high-quality authoring, editing, import/export, validation and viewing of X3D scenes.
*	https://savage.nps.edu/X3D-Edit

Have fun with X3D4 extensibility!  😊

all the best, Don

-- 

Don Brutzman  Naval Postgraduate School, Code USW/Br        brutzman at nps.edu

Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA    +1.831.656.2149

X3D graphics, virtual worlds, navy robotics https://faculty.nps.edu/brutzman

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20240601/8552fb76/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image001.png
Type: image/png
Size: 25818 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20240601/8552fb76/attachment-0001.png>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 7709 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20240601/8552fb76/attachment-0001.p7s>