[x3d-public] appinfo attribute/field
Michalis Kamburelis
michalis.kambi at gmail.com
Fri Aug 22 03:14:26 PDT 2025
Thank Don for the information!
My main question was about the classic encoding. "How do we encode
appinfo/documentation in X3D classic encoding". From the link you
pointed ( https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExample.html#21
), I tracked the "classic" encoding version on
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExample.x3dv
.
Alas, this doesn't really show how do we encode them --- the appinfo
there is just placed in a comment:
"""
EXTERNPROTO HeadsUpDisplay [
# [appinfo] Heads-up display (HUD) keeps child geometry aligned on
screen in a consistent location
inputOutput SFVec3f screenOffset # [appinfo] offset
position for HUD relative to current view location, default 0 0 -5
inputOutput MFNode children # [appinfo] X3D content
positioned at HUD offset
outputOnly SFVec3f position_changed # [appinfo] HUD
position update (in world coordinates) relative to original location
outputOnly SFRotation orientation_changed # [appinfo] HUD
orientation update relative to original location
]
"""
So, this is not a way to encode the information in X3D classic
encoding, it's just a comment, according to classic spec. The readers
for "classic" encoding (in CGE and I assume in other browser) just
ignore comments at the "token scanning" stage.
Are we supposed to look at special comment contents that start with
"[appinfo]"? This is not a standard approach for parsing X3D classic
content, but if this is a decision, I guess we can adapt to it. (But
let's document it in classic encoding spec then :) )
Regards,
Michalis
czw., 21 sie 2025 o 19:25 Don Brutzman via x3d-public
<x3d-public at web3d.org> napisał(a):
>
> Thanks for all scrutiny. Answers and links for many of the questions follow.
>
> 1. First: X3D version 4.0 is authoritative. X3D version 4.1 is draft and collects a variety of changes, with details discussed on mailing lists and progress synopsized in Mantis. Updating the online draft to match best-case understandings to date has been very helpful. Each addiotion/deletion change in the 4.1 draft is carefully marked up and cross-referenced using Mantis, so that all evolution from X3D version 4.0 is immediately obvious.
>
> X3D version 4.1 draft Architecture
> X3D Architecture 4.1 draft — ISO/IEC 19775-1:202x — X3D Architecture index page
>
> More broadly, all specifications are linked and maintained up to date on the X3D Progress page.
>
> X3D Standards Progress
> https://www.web3d.org/x3d/progress
>
> 2. Second: the motivation for appinfo and documentation annotations is pretty straightforward. The X in X3D stands for Extensible, and one of our major mechanisms for that is prototype declaration. Essentially prototypes define new nodes as a combination of existing nodes plus scripting. Documenting such new designs is important for understanding and for correct implementation.
>
> The approach used by World Wide Web Consortium (W3C) for defining such new elements is well developed and well implemented as part of the XML Schema specification.
>
> W3C XML Schema
> https://www.w3.org/XML/Schema
> W3C XML Schema Definition Language (XSD) 1.1 Part 1, section 3.15 Annotations
> https://www.w3.org/TR/xmlschema11-1/#cAnnotations
> "Annotations provide for human- and machine-targeted annotations of schema components."
>
> Given this motivation, and given that this well-developed and well-supported approach for new-element annotations has been proven in W3C Schema, it was a natural thing for us to follow the same design pattern in the X3D XML Encoding. (Pretty helpful too, we didn't have to reinvent that wheel.) Having shown that, we generalized it in the X3D Architecture (as part of 4.0, I believed). As Michalis pointed out,
>
> X3D Architecture 4.0, clause 4 Concepts, 4.4.4.2 PROTO interface declaration semantics
> "Prototype and field declarations may optionally include appinfo functional descriptions (i.e., tooltip summary) and a documentation url providing a link to further related information."
> https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics
>
> Given that functional definition, we already have good patterns for equivalently representing the same information in XML, ClassicVRML, VRML, JSON, and programming languages. One of many examples in our archives:
>
> X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 14 Prototypes
> https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes
> X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 14 Prototypes, Heads Up Display Example
> https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExampleIndex.html
> <ExternProtoDeclare name='HeadsUpDisplay' appinfo='Heads-up display (HUD) keeps child geometry aligned on screen in a consistent location' url=' "HeadsUpDisplayPrototype.x3d#HeadsUpDisplay" "https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay" "HeadsUpDisplayPrototype.wrl#HeadsUpDisplay" "https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay" '>
> https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayExample.html#21
>
> Multiple examples are shown there for many of our file encodings and programming APIs - XML, classicVRML, binary, JSON, Turtle, Java, Python. For example, JSON:
>
> { "ExternProtoDeclare":
> {
> "@name":"HeadsUpDisplay",
> "@appinfo":"Heads-up display (HUD) keeps child geometry aligned on screen in a consistent location",
> "@url":["HeadsUpDisplayPrototype.x3d#HeadsUpDisplay","https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.x3d#HeadsUpDisplay","HeadsUpDisplayPrototype.wrl#HeadsUpDisplay","https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter14Prototypes/HeadsUpDisplayPrototype.wrl#HeadsUpDisplay"],
>
> Looking ahead, formalizing JSON and all the other file-encoding specifications is our objective for 2025. We already have mature drafts for XML, ClassicVRML and X3D Binary; probably JSON will be next effort.
>
> 3. Third, the addition of a DESCRIPTION statement for IMPORT/EXPORT has been proposed and we are currently working on a possible way to do this. Thanks Holger for noting the draft 4.1 changes, we are tracking in Mantis (accessible to Web3D Members) and will bring this forward for group review + comment in the near future.
>
> Mantis 1470: add EXPORT/IMPORT field DESCRIPTION for X3D Architecture 4.1
> https://mantis.web3d.org/view.php?id=1470
>
> Am very appreciative of excellent interest and scrutiny. The appinfo and documentation definitions for prototypes and fields seems to be a quite valuable part of X3D extensibility, making new capabilities well documented and re-usable in the long term. Conceptual improvements and issue identification/resolution are always welcome.
>
> Have fun with well-documented X3D extensibility! 😀👍
>
> all the best, Don
>
>
>
> On Thu, Aug 21, 2025 at 5:20 AM Holger Seelig via x3d-public <x3d-public at web3d.org> wrote:
>>
>> To add fuel to the fire, X3D 4.1 now defines a DESCRIPTION string for IMPORT and EXPORT that must be parsed, currently for Classic Encoding. This description overlaps significantly with appInfo or documentation attributes.
>>
>> On the other hand, it has not yet been specified how this DESCRIPTION should be encoded in JSON and XML, but it will certainly be similar.
>>
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#IMPORTStatement
>>
>> https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4.1-CD/Part01/components/networking.html#EXPORTStatement
>>
>> Best regards,
>> Holger
>>
>> —
>> Holger Seelig
>> Leipzig, Germany
>>
>> holger.seelig at yahoo.de
>> https://create3000.github.io/x_ite/
>> https://patreon.com/X_ITE
>>
>>
>>
>> Am 21.08.2025 um 12:42 schrieb Michalis Kamburelis via x3d-public <x3d-public at web3d.org>:
>>
>> Thank you -- but that's not yet enough :)
>>
>> The fact that appinfo is SFString says what information it can carry
>> (OK, 1 string), but not yet how it's encoded. If "appinfo" would be a
>> regular field inside a regular X3D node, it would be all we need...
>> alas, it is not.
>>
>> As it stands, "appinfo" is part of "ProtoDeclare" and "field" in
>> prototype interface -- these are special concepts with special syntax,
>> in both X3D XML and classic encodings.
>>
>> - For the X3D 3.3 classic encoding, this is the relevant section:
>> https://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/concepts.html#PROTOStatementSyntax
>>
>> - For the X3D 3.3 XML encoding, this is the relevant section:
>> https://www.web3d.org/documents/specifications/19776-1/V3.3/Part01/concepts.html#PrototypeAndFieldDeclarationSyntax
>>
>> I think we need "X3D 4.0 classic encoding" and "X3D 4.0 XML encoding"
>> specs and they should extend above sections to include how the
>> additional X3D 4.0 information ("appinfo", "documentation") is
>> encoded.
>>
>> The XML encoding is kind of obvious in this case (as "ProtoDeclare"
>> and "field" are XML elements, so "appinfo" and "documentation" can be
>> just XML attributes), so it's not a big question. But classic encoding
>> of them is really unknown, at least to me :)
>>
>> Regards,
>> Michalis
>>
>> wt., 19 sie 2025 o 18:59 John Carlson via x3d-public
>> <x3d-public at web3d.org> napisał(a):
>>
>>
>> What I meant to say is appinfo is an SFString, but I don’t know if that’s enough information for the classic encoding. Anyone?
>>
>> John
>>
>> On Tue, Aug 19, 2025 at 11:17 AM John Carlson <yottzumm at gmail.com> wrote:
>>
>>
>> Sorry, I the previous message contained 2 large images.
>>
>> The direct links are:
>>
>> https://www.web3d.org/x3d/content/X3dTooltips.html#ProtoDeclare.appinfo
>>
>>
>> https://www.web3d.org/x3d/content/X3dTooltips.html#field.appinfo
>>
>> John
>>
>> ---------- Forwarded message ---------
>> From: John Carlson <yottzumm at gmail.com>
>> Date: Tue, Aug 19, 2025 at 10:54 AM
>> Subject: Re: [x3d-public] appinfo attribute/field
>> To: Michalis Kamburelis <michalis.kambi at gmail.com>
>> CC: Extensible 3D (X3D) Graphics public discussion <x3d-public at web3d.org>
>>
>>
>> Michalis:
>>
>> Tooltips may help again here, they are SFStrings. I don’t know the meaning of CDATA or #IMPLIED though, see attached images. The issue you mentioned contains direct links, FMI.
>>
>> Thanks,
>>
>> John
>>
>>
>> On Tue, Aug 19, 2025 at 10:46 AM Michalis Kamburelis <michalis.kambi at gmail.com> wrote:
>>
>>
>> Let me add another question to this thread: Where is the specification
>> of how to *encode* appinfo information in the X3D classic encoding?
>>
>> To add some background/context to this question:
>>
>> - Thanks to John pointing out in
>> https://github.com/castle-engine/castle-engine/issues/688 , in CGE we
>> lack support for "appinfo" attribute in ProtoDeclare / field.
>>
>> - I found a mention of new "appinfo" and "documentation" in the
>> abstract X3D 4.0 spec:
>> https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/concepts.html#PROTOinterfacedeclsemantics
>> ,"""Prototype and field declarations may optionally include appinfo
>> functional descriptions (i.e., tooltip summary) and a documentation
>> url providing a link to further related information."""
>>
>> - However, as the above is the "abstract" part of the spec ("X3D
>> Abstract : Architecture and base components") so it naturally doesn't
>> say how these "appinfo" and "documentation" are actually encoded. The
>> official XML encoding and classic encoding specs are now at 3.3
>> version -- so they don't mention how to encode this new X3D 4.0
>> feature.
>>
>> - For XML encoding, it seems straightforward, judging from the
>> testcase in https://github.com/castle-engine/castle-engine/issues/688
>> . They are just XML attributes.
>>
>> <ProtoDeclare appinfo='...' name='...' ...>
>>
>> <field appinfo='...' ...>'
>>
>> OK, so XML encoding is simple enough:)
>>
>> - We need to know how to encode this information in X3D classic, to
>> enable lossless conversion between X3D encodings (classic, XML etc.).
>>
>> - If there is a spec, and/or a clear example of how to do this in X3D
>> classic encoding, please point me to it :) Thank you!
>>
>> Regards,
>> Michalis
>>
>>
>> _______________________________________________
>> x3d-public mailing list
>> x3d-public at web3d.org
>> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>>
>>
>> _______________________________________________
>> x3d-public mailing list
>> x3d-public at web3d.org
>> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>>
>>
>> _______________________________________________
>> x3d-public mailing list
>> x3d-public at web3d.org
>> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
>
> _______________________________________________
> x3d-public mailing list
> x3d-public at web3d.org
> http://web3d.org/mailman/listinfo/x3d-public_web3d.org
More information about the x3d-public
mailing list