[x3d-public] X3DJSAIL: Many DEFs with same value
John Carlson
yottzumm at gmail.com
Thu Apr 30 14:57:23 PDT 2026
On Thu, Apr 30, 2026 at 3:39 PM Don Brutzman <don.brutzman at gmail.com> wrote:
> 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.
>
Sorry, Don, there’s only one node, with reference from the root node
leading on two paths to the same node. Not cyclic (meaning a directed
cycle). Directed acyclic. The children don’t have parent links. You’re
thinking DOM, not X3DJSAIL scenegraph that I know of:
https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/sai/Core/X3DChildNode.html
No getParent(), setParent() or addParent()
Note that tree leaves have parents without having references to their
parents. DOM isn’t a tree, it’s a document. A directed *cyclic* graph.
> 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
>
> Study that carefully. No cycles implied. That’s DOM. You have directed
cyclic links with DOM. This is X3DJSAIL scenegraph, not HTML/X3DOM.
Very much directed. Not directed cyclic.
>
> - <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.
>
Try writing a specification of requirements and see if LLM solves the
problem.
>
> 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.
>
We’re just doing Java right now. Java can meet the architecture. Why
not? Plenty of people output DAGs without issues.
We both know that X3DJSAIL has a DOM parser, and converts DOM nodes into an
X3D scenegraph. X3dToJava.xslt generated code doesn’t create multiply
referenced nodes except through Strings that I know of. Feel freedom to
contradict.
>
Sure, have you tried multiple references to a DEF child node to see
X3DJSAIL validates it?
Why is there no Java output from your Java smoke test example? ?????
John
> 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/4f1d8427/attachment-0001.html>
More information about the x3d-public
mailing list