[x3d-public] Request for X3D encoding comment output from X3DPSAIL
Don Brutzman
don.brutzman at gmail.com
Mon Dec 29 10:52:39 PST 2025
John, thanks for many good possible ideas. Translating them into effective
results is not trivial.
Suggestion: you need to write clearer tickets, simpler test cases, and use
X3D Example Archives wherever possible.
Here is a detailed explanation of how to create actionable issues with
long-term value.
Summary. X3D is pretty amazing in that we can represent the same scene
graph in many ways. The goals for both X3DJSAIL Java and X3DPSAIL Python
are to provide programmers with APIs that can build and manipulate scene
graphs effectively, without errors. Both libraries have much capability,
with X3DJSAIL being actively worked on (for example, last night's
release). X3DPSAIL updates will follow in the coming year.
Equivalent X3D examples. If you want to see example encodings of comments,
please see
- X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 01
Technical Overview, Hello World
- Simple X3D model example: Hello World!
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorldIndex.html
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.x3d
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.java
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.py
Equivalent excerpts using X3D Documentation, XML, Java, and Python:
-
https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.html#31
- *(XML) * * <!-- Example scene to illustrate X3D nodes and fields
(XML elements and attributes) -->*
- *(Java) * *.addComments(" Example scene to illustrate X3D nodes
and fields (XML elements and attributes) ")*
- *(Python) * *# Example scene to illustrate X3D nodes and fields (XML
elements and attributes)*
Repeatable test evaluation. For all of our tests, we start with a single
.x3d (XML) file. Typical progression:
a. is the .x3d file valid,
b. is the conversion correct (for Java, Python, etc.)
c. does the relevant library correctly support the conversion.
Assets. We have thousands of examples in version control online. Using
those as test cases builds on existing validity testing and, for useful
test cases, means we are all progressing together.
- X3D Resources, Examples: Scene Archives for X3D
- https://www.web3d.org/x3d/content/examples/X3dResources.html#Examples
- Often when you discover some issue, it means we do not have test case
yet. Addition of examples is always welcome.
Additional notes.
a. You have seen firsthand how issue reports and examples are always
welcome. X3D is a big language, some tickets take time to resolve. Thanks
once again for your many efforts.
- Sourceforge: x3d tickets
- https://sourceforge.net/p/x3d/tickets
b. When an issue ticket is closed, it is typically fixed.
c. When an issue ticket reaches "wont-fix" status, that means the specific
ticket is not actionable. A worthy problem or two might well remain in
there somewhere, but the ticket doesn't describe it in a repeatable way.
Several tickets in that category have immense build logs that defy shared
understanding... Time to reset and redetermine what the problem really is.
d. Writing a pithy example that demonstrates expected functionality is
powerful and provides long-term benefits.
e. Sharing incredibly large and complex models to illustrate a single point
is rarely useful, it is too hard to handle multiple issues at once.
f. Simple new examples are welcome, but this is not a service for writing
and debugging large X3D models.
g. Programmers can write their code in many many ways. The libraries do
not mandate how a programmer codes, but internally they are highly
consistent. The given approaches to X3D Java and Python provide helpful
optional libraries for programmers to use when loading, building, adapting,
or exporting X3D models.
I am looking over your preceding message and not sure what you want to fix
something, or add a feature, or what. Am not disagreeing but am not
understanding whether there is a specific repeatable goal.
We do have Javadoc for X3DJSAIL, so if you want to look at many ways to
create an X3D comment in Java, please see
- X3DJSAIL Javadoc, X3D Java Scene Access Interface Library
- https://www.web3d.org/specifications/java/javadoc
-
https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/CommentsBlock.html
Perhaps you want to add a similar class in X3DPSAIL x3d.py for persistent
comments? The python output above is not persistent... perhaps
X3dToPython.xslt converter should use the following class in x3d.py instead:
>
> class Comment(_X3DStatement):
> """
> X3D statement containing zero or more comment strings.
> """
I have posted a new ticket to capture this point. Perhaps a useful
exemplar, as well.
- X3D SourceForge ticket #82 creating persistent comments in python when
converting from XML
- https://sourceforge.net/p/x3d/tickets/82/
Hope this helps. Again thanks for your many efforts. Have fun improving
X3D! 🤔 👍
all the best, Don
--
X3D Graphics, Maritime Robotics, Distributed Simulation
Relative Motion Consulting https://RelativeMotion.info
On Mon, Dec 29, 2025 at 3:25 AM John Carlson <yottzumm at gmail.com> wrote:
> Including Loren. Loren, Don and I have been discussing how to handle
> converting multi-line XML comments to Python in XSLT for X3DPSAIL programs.
> Particularly using X3dToPython.xslt. I am not an expert at XSLT, and
> don’t have appropriate tools, so I’ve been leaning on Don unduly.
>
> Note that I do like:
>
> “””
> comment here
> “””
>
> Python comments, but I don’t know if we can put them directly in the
> scenegraph. Just putting one “#” for a multi-line XML comment when
> translating to Python isn’t going to work. Maybe removing line endings
> would work. Also a “#” per comment line may also work.
>
> I think the combination of a “””…””” multi-line comment and a
> CommentsBlock class instance constructor wrapper around the comment may do
> the trick, and also fits in the scene graph for round-tripping. This has
> worked in X3DJSAIL, AFAIK. I don’t know about output from X3DPSAIL yet. I
> believe that X3DJSAIL also offers .addComments() methods to add
> CommentsBlock instances to the scenegraph, in many classes. I would
> primarily like this feature in order to do round-trip testing back to XML.
> Obviously there’s a whole discussion whether we should be converting XML to
> Java and Python. That’s how I create Java and Python test cases. Don
> prefers hand-coding tests, I think, and probably feels he is serving the
> programming community. I feel we have 4000+ XML examples that serve an
> excellent proving ground. Plus, I also have my own tests for my JSON
> loader I create from XML.
>
> Ultimately the above will be critical if we wish to output comments using
> the XML(), VRML() and JSON(), etc. methods in X3DPSAIL to produce
> documentation inside the scenegraph output. This will be useful for
> documenting X3D encoded files output from Maya, Blender, etc.
>
> Don hasn’t weighed in on this except to state he needs simple examples, or
> examples in the archive that he controls. Previous bug reports have been
> marked ‘won’t fix.’
>
> Joe and I created an .x3d file with multi-line comments that broke the
> Python generated by X3dToPython.xslt.
>
> I can find a multi-line comments in the XML in the X3D archive, if there
> are any there, the POSIX shell command is relatively simple. If you need
> help identifying multi-line comments to reduce to single-line comments,
> that should be a cinch! I can probably produce a list of files.
>
> Ultimately, the solution may just be to use single-line comments, but that
> doesn’t allow round-tripping.
>
> John
>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20251229/6eb2b645/attachment-0001.html>
More information about the x3d-public
mailing list