[x3d-public] X3DJSAIL: Many DEFs with same value
Don Brutzman
don.brutzman at gmail.com
Thu Apr 30 13:39:33 PDT 2026
Am not trying to be convincing, rather am just listing why an X3D scene
graph containing multiple nodes with the same value for DEF identifiers is
a bad practice and typically invalid.
A related fact is that if an X3D scene graph has any node with two parents,
then the graph is not a Directed Acyclic Graph (DAG) as required.
- Wikipedia Directed Acyclic Graph (DAG)
- https://en.wikipedia.org/wiki/Directed_acyclic_graph
Permitting USE references before creating DEF nodes is a recent relaxation
since X3D parsing speed is no longer a performance bottleneck.
These constraints are carefully chosen in X3D design. Programming
languages can create many other variations that do not meet these important
X3D Architecture requirements. Thus validation of results always remains
useful, for each file encoding (XML, VRML, JSON, x3db) and programming
language (JavaScript, Java, Python, others) that might be used to create an
X3D model.
Hopefully this helps you and others when designing X3D models, by whatever
means you choose.
all the best, Don
--
X3D Graphics, Maritime Robotics, Distributed Simulation
Relative Motion Consulting https://RelativeMotion.info
On Thu, Apr 30, 2026 at 1:14 PM John Carlson <yottzumm at gmail.com> wrote:
> Thanks, Don, but you’re not convincing when both Michalis and Holger solve
> the same problem. I agree that they don’t export Java *from XML*.
>
> X3D model or scenegraph? This is really trying to fix USE before DEF in
> XML output or 2+ DEFs with the same value in XML output. *It’s couched in
> terms of multiple DEFs, but there’s only one in the scene graph. The same
> ideas apply. I’m actually not creating multiple DEFs,* I’m using a
> variable reference to an instance in a Java in multiple parents node
> setters and adders. AFAIK, multiple references to a node with a DEF (or a
> DEF in a descendant) should be allowed in the scenegraph (not XML). I’m
> actually preventing duplication of a lot of data if a DEF is midway down
> the descendant hierarchy in the scenegraph, and the hierarchy is inserted
> twice.
>
> From below: *“**Instead, the same node is inserted into the scene graph
> a second time, resulting in the node having multiple parents”*. That’s
> exactly what addChild() does perfectly, except for containerField
> (containerField is an ancestor and is only in XML, but it might throw a
> wrench in my idea, clarification welcome). AFAIK, it’s perfectly fine to
> add a child more than one time with no DEF in the child’s descendants. So
> there’s some mysterious restriction that in some cases, you can’t call an
> addChild passing the same node twice.
>
> I think most of us would agree that the restriction should be lifted, and
> XML output should be fixed, according to Michalis’ method. Please talk to
> Michalis about how he does it in the castle model converter.
>
> There’s no need to put USE before DEF.
>
> From what I gather, *this is a well known pattern in dealing with
> outputting DAGs in enterprise software and should not be considered
> problematic* (maybe patented? IDK. ThreadLocal should prevent threading
> issues). Even vectors are patented for real world purposes. See
> GeoVector.l
>
> I haven’t decided whether to eliminate the USE nodes in the scenegraph
> yet, but reread the quote above. Let’s deal with the cases where a DEF is
> halfway down a tree I have a reference to, and I want to create another
> reference to the tree. Are you saying I have to do a deep copy of the
> tree, and create a USE node halfway down?
>
> Think this through in Java or Pascal. Put the emphasis on how to
> serialize a DAG without creating duplicate subtrees by outputting USE
> instead of a whole tree.
>
> But yeah, solving according to author intent would be cool too, just much
> harder, I would say.
>
> Since the USE is created in XML in any case, there will be no issue
> converting that to Java. X3dToJava.xslt, etc. can remain the same. I’m
> fairly sure we can keep setUSE() as is.
>
> The main reason not to do this is to allow XML snippets. Create an output
> function that initializes the DEF table , serializes a node, and clears the
> table
>
> You seem to always avoid the quote above when it’s brought up. Why? You
> even probably quoted it on purpose?
>
> Please be use a more precise term than model. I am referring to
> scenegraphs in memory or CPU cache, not something in a file on disk.
>
> Note that the code I shared only works when there’s only one DEF value for
> a single node and follows the quote when dealing with USE nodes. If you’re
> not following the quote, the code will’s change slightly, but you’ll get
> the idea if you look at it. And the ThreadLocal Stack for name scoping.
>
> If desired, I can create examples instead of emailing. Say the word.
>
> Is the quote wrong and not what X3DJSAIL does?
>
> But, yeah, adding a few lines of Java is to a stylesheet is harder than
> changing a standard?
>
> Thanks,
>
> John
> On Thu, Apr 30, 2026 at 1:05 PM Don Brutzman <don.brutzman at gmail.com>
> wrote:
>
>> Multiple duplicate DEF names in a single X3D model is a bad practice, for
>> multiple reasons.
>>
>> I've updated Scene Authoring Hints accordingly, see highlighted text
>> which follows plus additional references. Hope this helps.
>>
>> - X3D Scene Authoring Hints: Naming Conventions
>> -
>> https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions
>>
>> 🔖
>>> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions>
>>> *Naming Conventions*
>>>
>>> Models are simple representations for some part of reality. Simulations
>>> show the behavior of models over time.
>>>
>>> 1. Clarity is essential when naming components to design a
>>> meaningful model.
>>> 2. Names matter, suggesting how to think about purpose and
>>> relationships.
>>> 3. These naming conventions are suitable for X3D scenes, XML tagset
>>> design, accompanying HTML pages, and corresponding source code written
>>> JavaScript/Java/Python/etc.
>>> 4. These naming conventions also match the node and field naming
>>> conventions found in the X3D Standards
>>> <https://www.web3d.org/x3d/progress> themselves (and elsewhere).
>>> 5. Success Metric: when is a name successful?
>>> (Ironic) Answer: when no one has to discuss that name any more, it
>>> is simply understood.
>>>
>>> Naming conventions are appropriate for file names, DEF node identifiers
>>> and USE node references, prototype names, unique IDs, and more.
>>>
>>> Here is a combined set of guidelines.
>>>
>>> 1. Using clear and consistent names for node names and DEF labels
>>> greatly improves the clarity of how a scene works.
>>> 2. In effect, descriptive names can make the purpose and mechanics
>>> of a scene self-documenting.
>>> 3. Avoid duplicate DEF
>>> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#DuplicateDEF> identifier
>>> naming as a bad practice, even when identical names might seem
>>> reasonable when declaring a prototype in a model. The resulting model will
>>> fail XML validation, fail semantic query, and not make sense due to unclear
>>> definitions. Bookmarks in X3D Documentation pages will also fail since
>>> duplicate paragraph anchors will be present.
>>>
>>> [...]
>>
>>
>>> 🔖
>>> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#ProtoDeclare>
>>> *Prototype Declarations* define a template for a new node
>>>
>>> - Follow Naming Conventions
>>> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions> for
>>> node and field
>>> <https://www.web3d.org/x3d/content/X3dTooltips.html#field>
>>> definitions.
>>> - Provide useful/safe default initialization values for each field,
>>> rather than depending on default field values internal to the
>>> ProtoBody.
>>> - Include annotation tooltips for each field.
>>> - Avoid copying ProtoDeclare definitions into additional scenes,
>>> instead copy ExternProtoDeclare/ProtoInstance definitions.
>>> - Tooltips for ProtoDeclare
>>> <https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoDeclare>,
>>> ProtoInterface
>>> <https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoInterface>
>>> and ProtoBody
>>> <https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoBody>
>>> - Avoid duplicate DEF names for nodes inside multiple prototype
>>> declarations contained in a single file. Although the DEF namespaces
>>> contained inside each independent ProtoBody declaration are logically
>>> independent from an X3D perspective, duplicate DEF names will provoke XML
>>> validation errors regarding duplicate ID names. They can also easily lead
>>> to author confusion, providing semantic ambiguity both notionally and if
>>> performing Semantic Web Queries in Turtle.
>>> - X3D Specification clause: Prototype Semantic
>>> <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/concepts.html#PrototypeSemantics>
>>>
>>> Further discussion can also be found in
>>
>> - *X3D: Extensible 3D Graphics for Web Authors
>> <https://x3dgraphics.com/>,* Don Brutzman and Leonard Daly, Morgan
>> Kaufmann Publishers, Elsevier, 2007
>> - https://x3dgraphics.com
>> - Chapter 3 Grouping Nodes, 2. Concepts, 1.4 DEF and USE (pp 71-72)
>>
>> 2.4. DEF and USE
>>> DEF and USE names are the X3D mechanism for efficiently defining and
>>> copying a
>>> node, multiple nodes, or even groups of nodes. Copied nodes require far
>>> less memory
>>> and computation because they need only be created once. This efficiency
>>> can greatly
>>> improve rendering performance when extensively used in large scenes.
>>> When a node is given a DEF name, that name is an identification label
>>> that is unique
>>> in the file. The DEF name must start with a letter and can contain
>>> letters, numbers, and
>>> the special characters underscore, hyphen, and period. DEF names must
>>> not include
>>> whitespace or other special characters. Uppercase and lowercase
>>> alphabetic characters
>>> are considered strictly different; therefore, DEF names are case
>>> sensitive.
>>> USE names refer back to a node with a DEF name. These references allow
>>> faster and
>>> more efficient rendering of graphics objects. Note that the actual DEF
>>> node name definition
>>> must be located in the scene graph before any USE references. This
>>> permits X3D
>>> browsers to read and load a scene graph in a single pass, avoiding
>>> undefined references
>>> and thereby yielding faster parsing and loading. This performance boost
>>> not only helps
>>> when users first load a scene, but is also valuable when further
>>> subscenes are loaded
>>> within a parent scene. Authors also must be careful with animation of
>>> the fields of a DEF
>>> node, because this will equally affect all of the USE copies.
>>> When authoring large scenes, using descriptive DEF names improves
>>> clarity and
>>> helps document a model. CamelCaseNaming is a good way to accomplish
>>> this: capitalize
>>> each word, never use abbreviations, strive for clarity, and be brief but
>>> complete.
>>> Avoiding underscore characters improves readability, because
>>> pretty-print HTML versions
>>> of scenes usually hyperlink these names, and underlined hyperlinks hide
>>
>> underscore characters from the user. ROUTE statements that connect one
>>> node’s field to
>>
>> another node’s field are much more understandable when the purpose and
>>> type of the
>>> node are evident in the DEF names themselves. Examples provided with
>>> this book strive
>>> to provide useful examples of good naming practices. ROUTE connections
>>> are covered
>>> in Chapter 7, Event Animation and Interpolation.
>>> A good rule of thumb is that a proper DEF name can be sensibly used in a
>>> sentence.
>>> For example, “The fraction_changed field of the SpinningBoxClock
>>> TimeSensor node
>>> is ROUTED to the set_fraction field of the SpinningBoxInterpolator
>>> node.” Although
>>> a bit long winded, such sentences provide a clear and sensible
>>> explanation for a given
>>> behavior.
>>
>>
>> Authoritative reference is always X3D Architecture.
>>
>> - X3D Architecture v4.1 draft, clause 4 Concepts, 4.4.3 DEF/USE
>> semantics
>> -
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#DEF_USE_Semantics
>>
>> 4.4.3 DEF/USE semantics
>>>
>>> Node DEF names are limited in scope to a single X3D file, prototype
>>> definition, or string submitted to either CreateX3DFromString,
>>> CreateX3DFromStream, or CreateX3DFromURL X3D browser service (as specified
>>> in ISO/IEC 19775-2
>>> <https://www.web3d.org/specifications/X3Dv4Draft/references.html#I19775_2>
>>> ).
>>>
>>> The USE statement does not create a copy of the node identified by a DEF
>>> name. Instead, the same node is inserted into the scene graph a second
>>> time, resulting in the node having multiple parents (see 4.3.5
>>> Transformation hierarchy
>>> <https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/concepts.html#TransformationHierarchy>,
>>> for restrictions on self-referential nodes).
>>>
>>> Node names shall be unique in the context within which the associated
>>> DEF name occurs. Any USE node reference without a corresponding DEF,
>>> within the scope of the current scene or prototype declaration, is an error.
>>>
>>> NOTE DEF names are not required to precede USE references.
>>>
>> Have fun building understandable models with X3D! 😁 👍
>>
>> all the best, Don
>> --
>> X3D Graphics, Maritime Robotics, Distributed Simulation
>> Relative Motion Consulting https://RelativeMotion.info
>>
>>
>> On Thu, Apr 30, 2026 at 3:25 AM John Carlson via x3d-public <
>> x3d-public at web3d.org> wrote:
>>
>>> Summary: to employ multiple DEFs with same value, employ a table per
>>> name scope of DEF information in per Java thread java.lang.ThreadLocal
>>> memory for encoded output with one DEF per DEF/USE value. See bolded table
>>> description below.
>>>
>>> Feel free to forward.
>>>
>>> Is many DEFs with same value for a scenegraph node being considered in
>>> discussions? Say I want to addChild() the same Shape node several times to
>>> different Transforms, and the Shape node or descendants have DEFs in
>>> them. In X3DJSAIL, of course. This is easily done in an SAI binding
>>> like X3DJSAIL, just use the same variable passed to several addChild()
>>> methods.
>>>
>>> If it is allowed, what comes out in XML? I am hoping one leading DEF
>>> and several USEs for backwards compatibility. I think Castle has shown
>>> that this is doable.
>>>
>>> I am not saying VRML, XML, DOM, or HTML should have multiple parents of
>>> a child node. If a browser wants to implement a proxy when a DEF/USE
>>> appears more than once, they should be free to do that. (Hint:
>>> JavaScript’s Proxy class.) Maybe each mention of a DEF value (second or
>>> following) or USE value (any natural number of them) should create a Proxy
>>> on setting or adding?
>>>
>>> I do think the encodings are doing the right thing, no changes there.
>>> How can we achieve that output and support multiple parents (references or
>>> proxies to children) in X3DJSAIL with one DEF node per DEF value output?
>>>
>>> I’m particularly wondering for X3DJSAIL.
>>>
>>> Do we need proxies, or will table(s) also solve the issue of multiple
>>> DEFs, and replace all but the first with USE on output? Also perhaps
>>> assuming there’s a DEF table per name scope. How does X3DJSAIL support
>>> name scopes? (I’m clueless, currently). *I’m imagining a table with
>>> DEF_value, DEF_found, reference_count, DEF_nodes and USE_nodes columns.
>>> Maybe a name_scope and node_type_name as well.* These table(s) would
>>> be initialized when output begins potentially when a name scope is entered,
>>> and filled out as the XML is created. Multiple threads? The table can be
>>> stored in ThreadLocal memory. Bingo, if it’s still a thing.
>>>
>>> Please let me know if such a thing is already available.
>>>
>>> Someone else can solve for X3DPSAIL?
>>>
>>> Will this also handle USE before DEF?
>>>
>>> John
>>>
>> _______________________________________________
>>> 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/20260430/bf267d0a/attachment-0001.html>
More information about the x3d-public
mailing list