[x3d-public] X3DJSAIL: Many DEFs with same value
John Carlson
yottzumm at gmail.com
Thu Apr 30 15:10:04 PDT 2026
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/8c8faec9/attachment-0001.html>
More information about the x3d-public
mailing list