[x3d-public] allowing full capabilities for X3D node reuse with Inline EXPORT/IMPORT AS/USE
Don Brutzman
don.brutzman at gmail.com
Wed Oct 8 12:26:24 PDT 2025
[BLUF summary: proposed specification change to allow regular re-USE of
imported node references.]
Am trying to write a prototype for HAnim, and hoped that I might EXPORT a
large model so that a smaller scene might IMPORT the HAnimHumanoid for
further reuse (as a USE node in a prototype). Example EXPORT:
- 3D Example Archives: Humanoid Animation, Characters, Jin LOA 2
- Articulated 3D game character designed with a general graphics tool,
then converted into an X3D HAnim model and available for IMPORT as JinLOA2.
-
https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2Index.html
- <!-- This node has an EXPORT
<https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#JinLOA2>
connection
that can exchange events with a parent X3D model. -->
<HAnimHumanoid DEF='hanim_JinLOA2
<https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#hanim_JinLOA2>
' loa='2' name='JinLOA2' scale='0.0225 0.0225 0.0225'> on line 30
<https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#30>
- <EXPORT localDEF='hanim_JinLOA2
<https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#hanim_JinLOA2>
' AS='JinLOA2'/> on line 1319
<https://www.web3d.org/x3d/content/examples/HumanoidAnimation/Characters/JinLOA2.html#1319>
Hmmm, please notice that medium-size HAnim model is (1319 - 30 = 1289) lines
long... gee, wouldn't it be nice to Inline and IMPORT that model in ~3
lines instead, with added benefit of being able to reuse pose and motion
animations with it also.
However the current X3D Architecture appears to restrict the usage of
imported nodes solely to receiving/sending events. That restriction
permits writing ROUTE connections, but a blocker if trying to write a
prototype or trying other node re-USE.
EXPORT and IMPORT statements are rarely used, but have been around a long
time... since X3D 3.0, about 25 years maybe. They have potential for great
expressive power and extensibility (the X in X3D). However, am guessing
that the reuse limitation of IMPORT nodes has likely inhibited our
adoption. If I recall correctly, the primary objection (way back then) to
allowing full access to an imported node reference was uncertainty about
how it might all work, perhaps complicated by run-time synchronization
concerns.
We have come a long way since then. It seems pretty clear that an Inline
node loads an external scene graph into the current scene graph. Further,
the EXPORT statement identifies a specific node (sub graph) within that
inlined scene graph.
The straightforward way to think about this: Inline EXPORT/IMPORT provides
a reference to a node in the currently loaded scene graph. Given that the
author has a reference to an active node, they ought to be able to utilize
that node reference just like any other DEF/USE node reference.
I propose we relax the legacy (25-year) restriction and allow IMPORT node
references to be treated the same as USE node references.
Towards that end, have written out suggested changes in the draft v4.1
architecture, adding to a number of editorial improvements already
accomplished as part of
- Mantis 1470: add EXPORT/IMPORT field DESCRIPTION for X3D Architecture
4.1; also allow reuse
- https://mantis.web3d.org/view.php?id=14701470: add EXPORT/IMPORT field
DESCRIPTION for X3D Architecture 4.1
Request review, considerations and reactions. The markup changes at first
look complex but are essentially all geared towards the single objective of
allowing re-use of IMPORT nodes. Lots of markup shows that there are few
actual changes to existing prose, most of it is simply editorial
re-organization for clarity.
This is a good topic for this week's specification editors call on Friday
(9 pacific).
______________________________
For easy review, current markup follows. *First is Concepts.*
- X3D Architecture v4.1, clause 4 Concepts, 4.4.6 EXPORT/IMPORT semantics
-
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics
4.4.6 EXPORT/IMPORT semantics Import/Export semantics
Editors note: there are few actual changes here, most are simply switching
the order of EXPORT and IMPORT. Added functionality: imported node reuse.
The EXPORT feature allows authors to identify specific parts of an X3D
model which might be safely shared and reused by other X3D models. 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 and reusing scene subgraphs on a per-node
basis. In contrast with external prototyping (see 4.4.5 External prototype
semantics
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#Externalprototypesemantics>),
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.6 IMPORT statement
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement>
).
Importing nodes from an Inlined file is accomplished with two
statements: EXPORT
and IMPORT. 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.5 EXPORT statement
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement>).
EXPORT statements are not allowed in prototype declarations. 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.
In contrast with external prototyping (see 4.4.5 External prototype
semantics
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#Externalprototypesemantics>),
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.6 IMPORT statement
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement>
).
______________________________
*Next is the EXPORT statement.*
- X3D Architecture v4.1, clause 9 Networking component, 9.2.5 EXPORT
statement
-
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement
9.2.5 EXPORT statement
The EXPORT statement is used within an X3D file to specify nodes that may
be imported into other scenes when Inlining that file. Only named nodes
exported with an EXPORT statement are eligible to be imported into another
scene. file. DEF names are used to identify exported nodes. See 4.4.6
EXPORT/IMPORT semantics
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics>
for
further details.
EXPORT statements may appear anywhere in the file and have the following
form:
EXPORT <NodeDEFName> [ AS <ExportedNodeDEFName> ]
[DESCRIPTION "a simple description of intended EXPORT purpose"]
EXPORT <NodeName> [ AS <ExportedNodeName> ]
The EXPORT statement has the following components:
1. The local DEF name of the node to be exported if the current scene is
retrieved externally via Inline,
2. An optional alternative DEF name that is used AS a default as an alias
for the exported node when importing it into other scenes, files,
3. An optional simple DESCRIPTION of intended purpose for the node
provided via EXPORT.
The EXPORT statement has the following semantics:
4. Once imported into a containing scene, events may be routed to or
from the fields of an exported node in exactly the same manner as any
node defined with DEF.
5. Exported nodes imported into a containing scene may be referenced via
a USE statement in the importing scene. may not be instanced via the USE
statement.
6. Exportation may not be propagated across multiple files; that is, a
node imported into one scene using the IMPORT statement may not then be
further exported into another scene using the EXPORT statement.
7. Nodes shall not be exported from within the body of a PROTO
declaration.
8. Any scene with an EXPORT statement shall apply UNIT statement
adjustments as needed to the fields of any exported nodes and child nodes.
9. The EXPORT statement can appear wherever a ROUTE statement is
allowed, and shall be contained within the Inline node to which it refers.
The following example illustrates the use of the EXPORT statement
(Classic VRML encoding):
EXAMPLE
DEF T1 Transform {
# additional nodes and fields...
}# additional nodes and fields...
EXPORT T1 AS rootTransform
In the above example, node T1 is exported for use by other X3D scenes. The
optional AS keyword defines the exported name of *T1* as *rootTransform* (
*i.e.*, other scenes may import the node only using the name rootTransform).
All defined alias AS names shall also meet appropriate uniqueness
requirements in the local DEF namespace of the parent scene.
______________________________
*Next is the IMPORT statement.*
- X3D Architecture v4.1, clause 9 Networking component, 9.2.6 IMPORT
statement
-
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement
9.2.6 IMPORT statement
The IMPORT statement is used within an X3D file to specify nodes, which are
defined within Inline files or programmatically created content, that are
to be brought into the namespace of the containing file for the purposes of
event routing. Once a node is imported, events may be sent to its fields
via ROUTEs, or routed from any fields of the node which have output events. DEF
names are used to identify nodes. See 4.4.6 EXPORT/IMPORT semantics
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics>
for
further details.
IMPORT statements may appear anywhere in the file and have the following
form:
IMPORT <InlineNodeDEFName>*.*<ExportedNameFromInlinedFile> [ AS
<NewLocalNodeDEFName> ]
[DESCRIPTION "a simple description of intended IMPORT purpose"]
IMPORT <InlineNodeName>*.*<ExportedNameFromInlinedFile> [ AS
<NewLocalNodeName> ]
The IMPORT statement has the following components:
1. The DEF name of the Inline node that contains the node to be imported,
2. The DEF name of the node to import,
3. An optional alternative DEF name that is used AS as an alias for the
imported node within the run-time name scope, to help prevent avoid
potential DEF name clashes within the parent scene containing the IMPORT
statement,
4. An optional simple DESCRIPTION of intended purpose for the node
provided via IMPORT.
The IMPORT statement has the following semantics:
5. Once imported, events may be routed to or from the fields of an imported
node in the Inline scene, in exactly the same manner as any node defined
locally with DEF.
6. Editors note: the following is an important change, otherwise an
imported node cannot be utilized other than by receiving ROUTEd events (as
shown by the InlineImport.x3d
<https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportIndex.html>
example).
Nodes imported into an X3D scene using the IMPORT statement may be
referenced not be instanced via the USE statement.
7. Only nodes that are exported from within the Inline scene via an
EXPORT statement may be imported using a corresponding IMPORT statement.
8. The IMPORT statement can appear wherever a ROUTE statement is
allowed, and shall follow the Inline node to which it refers.
Any node reference that is obtained via IMPORT from an exporting scene is
also available as a USE node in the importing scene. This requirement is
necessary for the node reference retrieved by IMPORT to have full
capabilities in the importing scene. Nevertheless, important
synchronization considerations arise when one or more Inline models are
loaded as part of the current scene graph.
9. A single Inline node is allowed to have multiple IMPORT statements.
The state of nodes within that currently loaded Inline model are
consistently maintained as part of the current scene.
10. Multiple Inline nodes with separate IMPORT statements are completely
independent, even if each independent Inline is retrieving a copy of the
same original model.
The following example illustrates the use of the IMPORT statement
(Classic VRML encoding syntax):
EXAMPLE
DEF MyInline I1 Inline {
url "someurl.x3d"
}
IMPORT MyInline.rootTransform AS ImportedTransform I1.rootTransform AS
I1Root ...
# ROUTE events into the imported node, which is now a part of an
Inline scene subgraph
DEF PI PositionInterpolator { } { ... }
ROUTE PI.value_changed TO ImportedTransform.set_translation
I1Root.set_translation
# also USE the imported node (and associated scene subgraph) elsewhere
in the parent scene
Group {
USE ImportedTransform
}
# also USE the imported node when defining an instance of a
MyNewTransform prototype
MyNewTransform {
children USE ImportedTransform
}
In the above example,
- rootTransform is externally defined as a Transform node in the file
someurl.x3d and exported via an EXPORT statement. (see 4.4.6
Import/Export semantics
<https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#ExportImportSemantics>
).
- The optional AS keyword in the IMPORT statement defines an alias for
the MyInline.rootTransform rootTransform DEF. , so that
- Within the containing scene, the node is referenced using the AS alias
name ImportedTransform. DEF name I1Root.
All defined alias AS names shall also meet appropriate uniqueness
requirements in the local DEF namespace of the parent scene.
______________________________
Additional thanks to Joe Williams, Holger Seelig, and Nicholas Polys for
contributing to this analysis and potential improvement.
All feedback welcome! This simple functional refinement has potential for
much X3D scalability and extensibility.
Thanks in advance for considering the possibilities.
all the best, Don
--
X3D Graphics, Maritime Robotics, Distributed Simulation
Relative Motion Consulting https://RelativeMotion.info
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20251008/e8d0755c/attachment-0001.html>
More information about the x3d-public
mailing list