[x3d-public] Inconsistencies in the draft for 4.1
Don Brutzman
don.brutzman at gmail.com
Mon Sep 1 05:45:14 PDT 2025
Again thanks for noticing Holger that some work had been done with
IMPORT/EXPORT. Change summaries are found in Mantis, reviews of draft
specification prose are performed by Dick Puk and I as specification
editors.
- Mantis 1470: add EXPORT/IMPORT field DESCRIPTION for X3D Architecture
4.1
- https://mantis.web3d.org/view.php?id=1470
Primary motivation follows for this proposed change, and much further
detail appears in the Mantis issue.
- X3D EXPORT/IMPORT is a powerful extensibility mechanism for simply
sharing model characteristics for scene interoperability, animation, and
repeatable reuse.
- Adding a DESCRIPTION field to these statements for X3D Architecture
4.1 will help authors describe the purpose of the nodes and fields that the
EXPORT and IMPORT statements are referring to. This will help document
author intent for shared comprehension and correct usage of IMPORT/EXPORT
for these models.
- Aside from supporting persistent parsing of a string (and optional
interface display) of each DESCRIPTION, no further functionality is
required of browser implementations.
Here is current draft:
- X3D v4.1 Draft Architecture, clause 9 Networking component
- 9.2.5 IMPORT statement and 9.2.6 EXPORT statement
-
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement
-
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement
9.2.5 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.
> 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,
>
>
> 1. The DEF name of the node to import,
>
>
> 1. 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,
>
>
> 1. An optional simple DESCRIPTION of intended purpose for the node
> provided via IMPORT.
>
> The IMPORT statement has the following semantics:
>
> 4. 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.
>
>
> 4. Nodes imported into an X3D scene using the IMPORT statement may not
> be instanced via the USE statement.
>
>
> 4. Only nodes that are exported from within the Inline via an EXPORT
> statement may be imported using a corresponding IMPORT statement.
>
>
> 4. The IMPORT statement can appear wherever a ROUTE statement is
> allowed, and shall follow the Inline node to which it refers.
>
> The following example illustrates the use of the IMPORT statement
> (Classic VRML encoding syntax):
> DEF I1 Inline {
> url "someurl.x3d"
> }
> . . .
> IMPORT I1.rootTransform AS I1Root
> DEF PI PositionInterpolator { ... }
> ROUTE PI.value_changed TO I1Root.set_translation
> In the above example, rootTransform is defined as a Transform node in the
> file someurl.x3d and exported via an EXPORT statement (see 4.4.6.3 EXPORT
> semantics
> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#EXPORTSemantics>).
> The optional AS keyword defines an alias for the rootTransform DEF, so
> that within the containing scene the node is referenced using the DEF name
> I1Root. All defined alias AS names shall also meet appropriate uniqueness
> requirements in the local DEF namespace of the parent scene.
>
9.2.6 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 nodes.
> 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,
>
>
> 1. 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,
>
>
> 1. An optional simple DESCRIPTION of intended purpose for the node
> provided via EXPORT.
>
> The EXPORT statement has the following semantics:
>
> 3. 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.
>
>
> 3. Exported nodes imported into a containing scene may not be
> instanced via the USE statement.
>
>
> 3. 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.
>
>
> 3. Nodes shall not be exported from the body of a PROTO declaration.
>
>
> 3. 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):
> DEF T1 Transform {
> ...
> }
> . . .
> 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.
As everyone can see, primary improvements above are clarity. Continuing
refinements are of course welcome.
The *description *field was shown to be valuable for authors using any of
the Sensor nodes in X3D 4.0, further offering authors the ability to
communicate semantics and intent to end users.
Adding an optional DESCRIPTION further lets authors communicate semantics
and intent to other authors (now and in future) when using this X3D
extensibility feature. Such DESCRIPTION information is expected to be a
persistent part of the model, not transient or removable as comments are.
This gap cannot be filled by Metadata nodes, since they cannot be attached
to stateemnts.
Since IMPORT and EXPORT are statements, rather than nodes, the syntax for
those simple DESCRIPTION strings is expected to vary a bit when applied to
each of the X3D file formats and programming-language bindings. These will
be formally updated as we work through each of the specifications. I'm not
ready to add them to the following examples until an X3D 4.1 DOCTYPE and
XML Schema are created - sometime this fall I hope. When that is ready,
example/suggested syntax will be found at the following pair of example
models:
- *X3D Example Archives: Basic, X3D Specifications, Inline Export*
- X3D encodings example: demonstrate reuse and adaptation of content
instances through Inline IMPORT, EXPORT statements. This scene does not
animate, see InlineImport.x3d for selective animation of scene subgraph
EXPORT localDEF=T1 AS=RootTransform
-
https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineExportIndex.html
and
- *X3D Example Archives: Basic, X3D Specifications, Inline Import*
X3D encodings example: demonstrate reuse and adaptation of content
instances through Inline IMPORT, EXPORT statements. This scene animates
only a portion of model InlineExport.x3d that exposes a Transform scene
subgraph.
-
https://www.web3d.org/x3d/content/examples/Basic/X3dSpecifications/InlineImportIndex.html
Hope this looks sensible. Again, careful scrutiny and all potential
improvements are welcome.
Step by step, onward we go. Have fun with X3D Extensibility using
IMPORT/EXPORT!
all the best, Don
On Mon, Aug 18, 2025 at 7:16 AM Don Brutzman <don.brutzman at gmail.com> wrote:
> Holger, thanks for these excellent comments on recent specification draft
> editing.
>
> I expect to start working on them later this week. Will report back here,
> also ensuring that these issues are tracked satisfactorily using Mantis.
>
> - Mantis 1510: X3D Architecture 4.1 draft specification errata
> - https://mantis.web3d.org/view.php?id=1510
>
> all the best, Don
>
> On Mon, Aug 18, 2025 at 4:52 AM Holger Seelig via x3d-public <
> x3d-public at web3d.org> wrote:
>
>> Inconsistencies in the draft for 4.1
>>
>> * Immersive profile, Full profile, MedicalInterchange profile include now
>> the new FontFamily node but the level for the Text component in these
>> profiles is still 1 but should be 2
>>
>> * There is now a new Tangent node, which can be child of a lot of
>> geometry nodes, but should be a possible child of even more nodes, still
>> missing a tangent field: ElevationGrid, PointSet, IndexedLineSet, LineSet.
>> Why? All these nodes also have a normal field and can be affected by
>> lighting and shading with Material or PhysicalMaterial (probably with a
>> normalTexture which then requires a Tangent node). Example of lines and
>> points with normals and shading:
>> https://create3000.github.io/x_ite/laboratory/gltf-sample-viewer/?url=https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/PrimitiveModeNormalsTest/glTF/PrimitiveModeNormalsTest.gltf
>>
>> * LayoutGroup is now of type X3DNode but specification says: "Thus, a
>> LayoutGroup can only be a child of a LayoutLayer node or another
>> LayoutGroup node.“ But LayoutGroup children/addChildren/removeChildren only
>> accept X3DChildNode which in turn does not include the LayoutGroup itself
>> anymore.
>>
>> I think some things can be easily fixed, others require further
>> discussion, but it's better to know all of this.
>>
>> Daft for 4.1:
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/
>>
>> Best regards
>> Holger
>>
>> —
>> Holger Seelig
>> Leipzig, Germany
>>
>> holger.seelig at yahoo.de
>> https://create3000.github.io/x_ite/
>> https://patreon.com/X_ITE
>>
>>
>>
>> _______________________________________________
>> x3d-public mailing list
>> x3d-public at web3d.org
>> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20250901/26256dbd/attachment-0001.html>
More information about the x3d-public
mailing list