X3D Tidy for Scene Cleanup, Corrections and Modifications

X3D Tidy is an XSLT stylesheet that checks for simple authoring difficulties in X3D scenes and fixes them.

Overview | Availability | Corrections and Modifications | Parameters | References | Acknowledgements | Contact
X3D Resources: Quality Assurance (QA) | X3D Scene Authoring Hints

Overview

Authors can use X3D Tidy to fix minor errors and apply best practices for X3D scene authoring. X3D Tidy provides an additional degree of Quality Assurance (QA) that helps achieve intended results in X3D scenes and metadata.

X3D Tidy takes an .x3d scene (written using the X3D XML encoding) as input, and returns a modified .x3d scene as output. Any corrections are applied in place without changing the overall formatting or layout of the original X3D scene.

X3D Tidy does not attempt to make scene corrections which might change intended scene content or require an authoring decision.

Prerequisite: since X3dTidy.xslt is an XSLT stylesheet, the input .x3d scene must be encoded in valid XML. The X3D Validator and various other tools listed in X3D Resources: Quality Assurance (QA) can help to achieve this necessary level of compliance.

Availability

X3D Tidy is an XSLT stylesheet, available at X3dTidy.xslt.

• Online version is available at
  https://www.web3d.org/x3d/stylesheets/X3dTidy.xslt
• Version-control source is available at
  https://sourceforge.net/p/x3d/code/HEAD/tree/www.web3d.org/x3d/stylesheets/X3dTidy.xslt

X3D Tidy has passed a significant amount of testing with the open-source X3D Examples Archives. It is available as part of the following tools:

• X3D-Edit is an open-source Extensible 3D (X3D) Graphics authoring tool for simple error-free editing, authoring and validation of X3D scenes. Available under menu item X3D > Conversions > X3D Tidy
• Ant build.xml provides processScenes.X3dTidy and clean.X3dTidy targets, as well as a <X3dTidy> macro, which are used to automatically test all scenes in the X3D Examples Archives.
• X3D Validator which comprehensively checks X3D model validity.

Corrections

X3D Tidy is able to make the following unambiguous scene corrections.

1. Modify DOCTYPE and Schema references to match <X3D> element version in scene, if match is inconsistent or insufficient
2. Modify <X3D> element version to match a given value (by default this option is disabled; recommended version is 3.3)
3. Condense empty start-tag/end-tag elements as a singleton element, for example <WorldInfo></WorldInfo> as <WorldInfo/>
4. Omit default attribute values
5. Alphabetize or sort remaining attribute values in X3D Canonicalization (C14N) order
6. <meta> statements: if missing insert a default title, also title moved as first meta tag
7. <meta> statements: add provided or suggested license
8. <meta> statements: normalize dates to match suggested date format
9. <meta> statements: regularize capitalization and naming to match metadata conventions (for example name='image' to name='Image')
10. Fix MFString array "quotes" (such as <Text> node string array, or <ProtoInstance> fieldValue initializations)
11. Remove excess embedded SFString "quotes" (such as <Viewpoint> node description field)
12. Fix quoting of geoSystem values, replace deprecated values
13. Expand local url array to include online addresses, prepend .x3d variants to .wrl addresses, or append .wrl variants to .x3d addresses
14. <Script> node embedded source: replace deprecated javascript: or vrmlscript: prefix with ecmascript:, otherwise insert ecmascript: prefix if missing
15. For point and line geometry (PointSet, LineSet, IndexedLineSet, Arc2D, ArcClose2D, Circle2D): if no contained Color/ColorRGBA node is present, and if associated Appearance/Material emissiveColor value is default (black) or missing, then re-apply the diffuseColor value as emissiveColor value to regain visibility.
16. Correct erroneous attribute name: mustOutput renamed as forceOutput for Joint nodes in Rigid Body Physics component.
17. Remove unnecessary attribute name='OriginalProtoDeclareName' from <ProtoInstance USE='SomeProtoInstanceDEFname' containerField='someFieldName'/>
18. For index arrays in geometry nodes, detect omissions and append missing space character after -1 sentinel values if needed.
19. Convert deprecated fields in X3D4 models, such as GeoViewpoint navType.

TODO. More adjustment capabilities are planned, suggestions are welcome.

1. Check other MFString attributes besides urls, handle fixMFStringQuotes setting accordingly
2. Detect and fix embedded spaces within individual url values

Modifications

X3D Tidy is able to apply the following scene modifications.

1. Optionally add visualization spheres and lines to HAnimJoint and HAnimSegment nodes in an HAnimHumanoid skeleton.
2. Optionally add visualization shapes to HAnimSite nodes in an HAnimHumanoid skeleton.
3. Optionally add visualization lines to Viewpoint nodes embedded within an HAnimHumanoid skeleton.
4. TODO. Optionally remove Shape geometry from an HAnimHumanoid skeleton.
5. TODO. Optionally add visualization bones to HAnimSegment nodes in an HAnimHumanoid skeleton.
6. TODO. Optionally remove quotes surrounding SFString values.

TODO. More adjustment capabilities are planned, suggestions are welcome.

Parameters

Fine-grained control of X3D Tidy operation can be achieved by overriding any of the following XSLT stylesheet parameters at invocation time.

Default parameter default=value pairs follow:

    <!-- Default parameter values follow, can be overridden when invoking this stylesheet -->
    <xsl:param name="conversionRequired"          ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="title"                       ><xsl:text><!-- default title value for file name is empty --></xsl:text></xsl:param>
    <xsl:param name="modifyX3dVersion"            ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="revisedX3dVersion"           ><xsl:text>3.3</xsl:text></xsl:param>
    <xsl:param name="reviseCurrentDate"           ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="fixDateFormats"              ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="fixMFStringQuotes"           ><xsl:text>true</xsl:te xt></xsl:param>
    <xsl:param name="fixGeoSystemMetadata"        ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="fixMetaNamesMatchDublinCore" ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="omitObsoleteAttributes"      ><xsl:text>true</xsl:text></xsl:param>
    <!-- prependWorldInfoIfMissing values: true, false, or can also provide name to use -->
    <xsl:param name="prependWorldInfoIfMissing"   ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="replaceBlackEmissiveColor"   ><xsl:text>true</xsl:text></xsl:param>
    <!-- expand local url array to include online addresses -->
    <xsl:param name="fixUrlAdditionHttpAddresses" ><xsl:text>true</xsl:text></xsl:param>
    <!-- note that url quotes are always added if needed -->
    <xsl:param name="appendWrlAfterX3dAddresses"  ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="prependX3dBeforeWrlAddresses"><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="defaultUrlAddress"           ><xsl:text><!-- default value is empty --></xsl:text></xsl:param>
    <!-- baseUrlAvailable false means that stylesheet is being used by servlet, or else styled results won't be in original directory: -->
    <xsl:param name="baseUrlAvailable"            ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="changeJavascriptEcmascript"  ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="insertMissingEcmascript"     ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="insertMissingMetaLicense"    ><xsl:text>true</xsl:text></xsl:param>
    <xsl:param name="licenseLink"                 ><xsl:text>https://www.web3d.org/x3d/content/examples/license.html</xsl:text></xsl:param>

HAnim: illustrating or cleaning HAnimHumanoid skeletons of HAnimJoint/HAnimSegement/HAnimSite nodes:

    <!-- Default parameter values can be overridden when invoking this stylesheet -->
    <xsl:param name="HAnimGeometryRemove"         ><xsl:text>false</xsl:text></xsl:param>
    <xsl:param name="HAnimSkeletonIllustrate"     ><xsl:text>false</xsl:text></xsl:param>
    <xsl:param name="HAnimSiteIllustrate"         ><xsl:text>false</xsl:text></xsl:param>
    <xsl:param name="HAnimViewpointIllustrate"    ><xsl:text>false</xsl:text></xsl:param>

    <xsl:param name="jointColor"                  ><xsl:text>1 0.5 0</xsl:text></xsl:param>
    <xsl:param name="segmentColor"                ><xsl:text>1 1 0</xsl:text></xsl:param>
    <xsl:param name="siteColor"                   ><xsl:text>1 0 0</xsl:text></xsl:param>
    <xsl:param name="siteViewpointColor"          ><xsl:text>0 0 1</xsl:text></xsl:param>
TODO:
    <xsl:param name="HAnimAddBoneSegments"        ><xsl:text>false</xsl:text></xsl:param>

Authors can also suppress the external application of X3D Tidy corrections within an individual scene by including one or more of the following <meta/> statements in the <head> section of an X3D scene.

    <!-- Authors can override default X3D Tidy stylesheet parameter values by including meta tag(s) in an X3D scene. Examples follow. -->
    <meta name="X3dTidy" content="ignore"/>  <!-- ignores all corrections -->
    <meta name="X3dTidy" content="modifyX3dVersion=false"/>
    <meta name="X3dTidy" content="reviseCurrentDate=false"/>
    <meta name="X3dTidy" content="fixMFStringQuotes=false"/>
    <meta name="X3dTidy" content="fixGeoSystemMetadata=false"/>
    <meta name="X3dTidy" content="fixMetaNamesMatchDublinCore=false"/>
    <meta name="X3dTidy" content="fixDateFormats=false"/>
    <meta name="X3dTidy" content="replaceBlackEmissiveColor=false"/>
    <meta name="X3dTidy" content="fixUrlAdditionHttpAddresses=false"/>
    <meta name="X3dTidy" content="appendWrlAfterX3dAddresses=false"/>
    <meta name="X3dTidy" content="prependX3dBeforeWrlAddresses=false"/>
    <meta name="X3dTidy" content="changeJavascriptEcmascript=false"/>
    <meta name="X3dTidy" content="insertMissingEcmascript=false"/>
    <meta name="X3dTidy" content="insertMissingMetaLicense=false"/>

References

X3D Tidy has been developed as part of the X3D Quality Assurance (QA) (QA) efforts.

• X3D Resources: Quality Assurance (QA)
• X3D Validator
• X3D Scene Authoring Hints: Validation describes DOCTYPE (DTD) and XML Schema validation of X3D scenes in detail.

HTML Tidy provides inspiration for this work. The following references describe HTML Tidy functionality in further detail.

• HTML Tidy by HTML Tidy Advocacy Community Group (HTACG)
• The original: Clean up your Web pages with HTML TIDY by Dave Raggett
• Check your html content: HTML Tidy Online by Jonathan Hedley
• HTML Tidy Library Project on Sourceforge
• Wikipedia: HTML TIDY

Acknowledgements

Sincere thanks to the many people who have contributed content and suggestions to improve X3D Tidy:

John Carlson, Roy Walmsley, plus the many members of Web3D Consortium and X3D Community.

Contact

Updated: 2 July 2022

Maintained by Don Brutzman (brutzman at nps.edu). Comments & suggestions are welcome.

Revisions are found under Sourceforge version control. This page is available online at https://www.web3d.org/x3d/stylesheets/X3dTidy.html