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