#82 creating persistent comments in python when converting from XML

[Don Brutzman]

When the X3dToPython.xslt converter converts an X3D model comment in an XML file, it simply prepends a # hash tag in the resulting python source. This means that the comment is not persistent, and is not preserved if the Python program later saves the original X3D model back into another form.

Example:

• (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)

A better approach for conversion would be to use the Comment class in x3d.py for conversion output.

class Comment(_X3DStatement):
"""
X3D statement containing zero or more comment strings.
"""

Reference example for testing:

• 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

[Don Brutzman]

Background discussion:

• [x3d-public] Request for X3D encoding comment output from X3DPSAIL
• https://web3d.org/pipermail/x3d-public_web3d.org/2025-December/022165.html

[Don Brutzman]

In the X3DPSAIL Examples, sample program PythonX3dSmokeTests.py demonstrates both inline (transient) comments using # hash tag, and also use of Comment() class on line 1328.

modelTest = X3D(
    head=head(
        children=[
            # enumerations test diagnostic: name='Group' vice name='Grouping'
            component(name='Grouping',level=2),
            Comment("hello persistent comment in head children"),
            unit(category='length',conversionFactor=0.001,name='MILLIMETER'),
            meta(name='description', content='name-value pair & solitary-ampersand test'),
            meta(name='info',   content='diagnostic test 1'),
            meta(name='hint',   content='diagnostic test 2'),
            meta(name='warning',content='diagnostic test 3'),
            meta(name='error',  content='diagnostic test 4')]
    ),

[Don Brutzman]

This is not an easy fix for converting all comments in .x3d files using X3dToPython.xslt because Comment is not part of the content model for all nodes. Solving this worthy improvement will probably require extending class _ X3DNode in x3d.py and sorting out possible subclass collisions. It will also be difficult to retain the original order of child nodes and child comments within a parent node.

After some effort I got it working for head, Scene, field, fieldValue prototypes, and X3DGroupingNode children. This might be fully fixable someday - deferred as future work.

[John W Carlson]

I agree that your ticket captures one aspect of Comment instances, but I fear it doesn’t capture the multi-line aspect of .x3d comments, hence the python output from X3dToPython.xslt will still be invalid from valid .x3d files with multi-line comments.

[Don Brutzman]

There are no validation requirements for the content of comment statements.

X3D Canonicalization (C14N) removes excess whitespace (including newlines) from comments in the XML encoding. Similar handling occurs for XML Canonicalization, which requires a comment-stripping capability and recommends a comment-retention capability. Thus handling multiple single-line comments is the appropriate goal for X3dToPython.xslt stylesheet conversion. When fully supported, that means that there is no loss of X3D model information even if newlines are normalized as a whitespace character.

In other words, preserving line breaks and newlines is not an interoperability requirement and not a current goal. Preserving newlines when converting comments might be a possible feature someday, but it has questionable value. Note that some file encodings (such as VRML97 and ClassicVRML) use single-line # hash characters and have no way of explicitly representing such a comment.

[Don Brutzman]

The persistent Comment class is now supported for many cases when converting comments from .x3d XML source, one line at a time. It is a tricky business, and has required significant rework in X3dToPython.xslt stylesheet that is now working when a Comment is next to other children nodes, in the head section, within an HAnimHumanoid, and a number of other places. No comments are lost, and other cases are handled as before with a # indicator at the beginning of a line. Continuing improvements will occur gradually.

[John W Carlson]

I'm sure you are aware of these use cases, even though it appears in a Legacy folder, or just in my code:

`<MetadataSet containerField='metadata' name='warnings' reference='HAnim'>
    <!-- TODO experimental -->
    <MetadataString containerField='value' name='SymmetricalLeftRight' reference='correction options: ignore, warn, average, left, right, largest, smallest' value='"ignore"'/>
  </MetadataSet>
<Shape DEF='AxisLinesShape'> <!-- RGB lines showing XYZ axes -->
<IndexedLineSet colorIndex='0 1 2' colorPerVertex='false' coordIndex='0 1 -1 0 2 -1 0 3 -1'>
 <Coordinate point='0 0 0 0.1 0 0 0 0.1 0 0 0 0.1'/>
 <Color color='1 0 0 0 0.6 0 0 0 1'/>
</IndexedLineSet>
<Shape>

I'm going to save this, in hopes that specifying the code button will not mess up the XML

[Don Brutzman]

Have implemented improved handling of Comments class when appearing as first member of field or fieldValue list. Deployed X3dToPython.xslt and x3d.py with improvements. Still need support for Shape and Appearance, likely other nodes too.