[x3d-public] X3DJSAIL: Many DEFs with same value
John Carlson
yottzumm at gmail.com
Thu Apr 30 15:43:00 PDT 2026
So the real question is, how can we describe the exception when several
DEFs are found in the X3DJSAIL validator, when the problem could be far up
the Java hierarchy from the DEF, and multiple DEFs aren’t obvious in the
Java code? It would seem like XML output is useful for debugging (pretty
print version).
It’s actually perfectly fine with me if USE appears before DEF, if our
tools can handle it. I’m guessing quite a few of my old tools may rely on
DEF first. Probably Blender import as well. This doesn’t feel right.
Only limiting tools to browsers is limited.
John
On Thu, Apr 30, 2026 at 5:23 PM John Carlson <yottzumm at gmail.com> wrote:
> Oh, you make a copy. Already figured that out.
>
> John
>
> On Thu, Apr 30, 2026 at 5:10 PM John Carlson <yottzumm at gmail.com> wrote:
>
>> Ah, I get it. Nodes with multiple parents (without links) have to have
>> DEF or USE! So that limits a child being referenced more than one time
>> *must* have a DEF. Michalis, do you handle the other case, where it
>> doesn’t? How?
>>
>> On Thu, Apr 30, 2026 at 4:57 PM John Carlson <yottzumm at gmail.com> wrote:
>>
>>>
>>>
>>> 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/ca4f0637/attachment-0001.html>
More information about the x3d-public
mailing list