[x3d-public] X3DJSAIL: Many DEFs with same value

[John Carlson]

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/66a976c3/attachment-0001.html>