X3DJSAIL, X3D Java Scene Access Interface Library

.
to X3D Resources
               

X3D Java Scene Access Interface Library (X3DJSAIL)

               
to Web3D home page

X3D Java Scene Access Interface Library (X3DJSAIL) supports programmers with standards-based X3D Java interfaces and objects, all as open source.

Abstract | Codebase | CLASSPATH and Command Line | Conversions including Blender, MeshLab | Design Features | Downloads | Examples | EXI | Javadoc | License | Other Implementations | README | References | Specification Changes | TODO | Utility Methods | Contact


🔖 Abstract to top

X3DJSAIL, the X3D Java Scene Access Interface Library is a set of strongly typed Java application programming interfaces (APIs) providing programmer access to an X3D scene graph. Two open-source Java packages are included that contain X3D SAI interfaces and support the X3D Standards for Java programmers.

  • org.web3d.x3d.jsail provides concrete implementation-oriented classes for building X3D scenes using standalone Java objects.
  • org.web3d.x3d.sai     contains standard X3D SAI interfaces to independently compile Script-node source for use in X3D players.

Available products include Javadoc documentation, several thousand self-validating Examples, source code, compiled classes build support, run-time jar archives, and draft specification annexes for node interfaces and abstract-node type interfaces.

Goals include making it easy to create an X3D scene graph using Java, while also making it hard to create an incorrect or invalid X3D model.

This library supports multiple uses:

  • Create high-performance standalone Java applications using a Plain Old Java Object (POJO) implementation for X3D.
  • Compiling Java source code used in X3D Script nodes.
  • Test ongoing development of X3D version 4.
  • Future: serve as a design template for planned autogeneration of similar codebases using ECMAScript, C#/C++/C, and Python programming languages.

🔖 Codebase Production to top

X3DJSAIL binaries are compatible with Java 1.8 and greater.

X3DJSAIL source is compiled and tested under OpenJDK 12 (default) as well as Oracle JDK 12 and Oracle JDK 1.8.

This work supports X3Dv4 development. X3DJSAIL implements the X3D Unified Object Model (X3DUOM) in support of current and emerging capabilities found in the Web3D Recommended Standards.

For developers, the Savage Developers Guide provides further details on compilation configuration settings for Ant, Java, and Netbeans.

TODO under active development: the X3DJSAIL library-creation files currently require multiple external assets and local configuration for complete assembly. Ongoing work may eventually combine these and other resources into an independently buildable project.


🔖 CLASSPATH and Command Line to top

Command line invocation is feasible through use of the org.x3d.jsail.CommandLine class.

Note that model validation is always performed as part of X3DJSAIL operations.

  • CommandLine invocation using console with standalone .jar in local directory:

    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine
         [-help | -version | -home | -javadoc | -resources | -hints | -regexes | -tooltips | -X3DUOM]
         [-properties [propertiesFile]]
         [sourceModel.x3d | sourceModel.exi [-fromEXI] | sourceModel.gz [-fromGZIP] | sourceModel.zip [-fromZIP]]
         [-canonical] [-validate]    [-EXIFICIENT | -OpenEXI]
         [-Tidy | -toX3D | -toXML | -toClassicVrml | -toJava | -toJSON | -toPython | -toVRML97]
         [-toHTML | -toX3DOM | -toX_ITE | -toMarkdown | -toEXI | -toGZIP | -toZIP]
         [-tofile [resultFile.*]] [-toImage [snapshotName.*]]

    Example:    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine -help

    Example:    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toVRML97 -toFile

  • Setup CLASSPATH for repeated invocation using local libraries:
     
    • Primary: CLASSPATH correctly containing "fat jar" X3DJSAIL.3.3.full.jar

      Example CLASSPATH confirmation:
      % echo $CLASSPATH
      CLASSPATH='C:\x3d-code\www.web3d.org\x3d\stylesheets\java\jars\X3DJSAIL.3.3.full.jar'

    • Developer alternative: For developers, an alternative CLASSPATH configuration is "skinny jar" X3DJSAIL.3.3.classes.jar but note that Saxon stylesheet engine and other EXI .jar dependencies must also be provided.
      % echo $CLASSPATH
      CLASSPATH='C:\x3d-code\www.web3d.org\x3d\stylesheets\java\jars\X3DJSAIL.3.3.classes.jar;
      C:\x3d-code\www.web3d.org\x3d\stylesheets\java\lib\saxon9he.jar;
      C:\x3d-code\www.web3d.org\x3d\stylesheets\java\lib\exificient-gui-jar-with-dependencies.jar;
      C:\x3d-code\www.web3d.org\x3d\stylesheets\java\lib\nagasena.jar'

  • CommandLine invocation using console with prior CLASSPATH configuration:
    • java org.web3d.x3d.jsail.CommandLine
           [-help | -version | -home | -javadoc | -resources | -hints | -regexes | -tooltips | -X3DUOM]
           [-properties [propertiesFile]]
           [sourceModel.x3d | sourceModel.exi [-fromEXI] | sourceModel.gz [-fromGZIP] | sourceModel.zip [-fromZIP]]
           [-canonical] [-validate]    [-EXIFICIENT | -OpenEXI]
           [-Tidy | -toX3D | -toXML | -toClassicVrml | -toJava | -toJSON | -toPython | -toVRML97]
           [-toHTML | -toX3DOM | -toX_ITE | -toMarkdown | -toEXI | -toGZIP | -toZIP]
           [-tofile [resultFile.*]] [-toImage [snapshotName.*]]

      Example:    java org.web3d.x3d.jsail.CommandLine -help

      Example:    java org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toClassicVRML

      Example:    java org.web3d.x3d.jsail.CommandLine HelloWorld.x3d.gz -fromGZIP

  • CommandLine invocation using Ant build.xml:
    <target name="test.X3DJSAIL" depends="" description="Test X3DJSAIL" >
            <echo message="==========================================="/>
            <echo message="helpful invocations for CommandLine debugging"/>
            <echo message="org.web3d.x3d.jsail.CommandLine -help"/>
            <java classname="org.web3d.x3d.jsail.CommandLine"
                  classpath="${saxon.dir}/${saxon.jar};${java.jars.dir}/${jsai.full.archive.jar.name};.">
                    <arg value="-help"/>
            </java>
            <echo message="==========================================="/>
            <echo message="org.web3d.x3d.jsail.CommandLine -properties ${java.examples.dir}/X3DJSAIL.properties"/>
            <java classname="org.web3d.x3d.jsail.CommandLine"
                  classpath="${saxon.dir}/${saxon.jar};${java.jars.dir}/${jsai.full.archive.jar.name};.">
                    <arg value="-properties"/>
                    <arg value="${java.examples.dir}/X3DJSAIL.properties"/>
            </java>
    </target>
    
  • CommandLine invocation using Java source code:
    System.out.println ("===========================================");
    System.out.println ("Test CommandLine invocations");
    String[] args = {"-help" };
    System.out.println ("CommandLine " + Arrays.toString(args));
    CommandLine.run (args); // run these commands
    System.out.println ("===========================================");
    args = new String[] {"HelloWorldProgramOutput.x3d", "-toX3D", "-toFile", "HelloWorldProgramOutput.CommandLine.x3d" };
    System.out.println ("CommandLine " + Arrays.toString(args));
    CommandLine.run (args); // run these commands
    System.out.println ("===========================================");
    args = new String[] {"HelloWorldProgramOutput.x3d", "-EXIFICIENT", "-toEXI", "-toFile", "HelloWorldProgramOutput.CommandLine.EXIFICIENT.exi"};
    System.out.println ("CommandLine " + Arrays.toString(args));
    CommandLine.run (args); // run these commands
    System.out.println ("===========================================");
    
  • CommandLine is also used by Java source code that gets created using X3dToJava.xslt stylesheet, setting ConfigurationProperties via inherited method X3DObject.handleArguments(args).
  • 🔖 Example -help output: to top
    $ java org.web3d.x3d.jsail.CommandLine -help
    
    Usage: java [-classpath X3DJSAIL.*.jar] org.web3d.x3d.jsail.CommandLine
           [-help | -version | -home | -javadoc | -resources | -hints | -regexes | -tooltips | -X3DUOM]
           [-properties [propertiesFile]]
           [sourceModel.x3d | sourceModel.exi [-fromEXI] | sourceModel.gz [-fromGZIP] | sourceModel.zip [-fromZIP]]
           [-canonical] [-validate] [-EXIFICIENT | -OpenEXI]
           [-Tidy | -toX3D | -toXML | -toClassicVrml | -toJava | -toJSON | -toPython | -toVRML97]
           [-toHTML | -toX3DOM | -toX_ITE | -toMarkdown | -toEXI | -toGZIP | -toZIP]
           [-tofile [resultFile.*]] [-toImage [snapshotName.*]]
    
    -classpath X3DJSAIL.*.jar         # optional classpath, can be set as environment variable
    org.web3d.x3d.jsail.CommandLine   # CommandLine application
    ==================================#====== informational ======================
    -help                             # provide this help message
    -version                          # version date when this X3DJSAIL build was autogenerated
    -home                             # launch X3DJSAIL home page
    -javadoc                          # launch X3DJSAIL javadoc page
    -resources                        # launch X3D Resources page
    -hints                            # launch X3D Scene Authoring Hints page
    -regexes                          # launch X3D Regular Expressions page
    -tooltips                         # launch X3D Tooltips page
    -X3DUOM                           # launch X3D Unified Object Model (X3DUOM) page
    ==================================#====== inputs =============================
    -properties [propertiesFile]      # override X3DJSAIL properties (default file: X3DJSAIL.properties)
    -EXIFICIENT                       # use Exificient (default) as EXI_ENGINE
    -OpenEXI                          # use OpenEXI (Nagasena)   as EXI_ENGINE (testing in progress)
    sourceModel.x3d                   # source model file name, X3D  format
    sourceModel.exi -fromEXI          # source model file name, EXI  format
    sourceModel.gz  -fromGZIP         # source model file name, GZIP format
    sourceModel.zip -fromZIP          # source model file name, ZIP  format
    ==================================#====== operations =========================
    -canonical                        # canonical XML output using X3D Canonicalization (c14n)
    -validate                         # validate correctness of loaded model
    -Tidy                             # X3D-Tidy cleanup in .x3d (XML) format
    -toX3D                            # output in .x3d (XML) format
    -toXML                            # output in .xml (X3D) format
    -toClassicVrml                    # output in .x3dv (ClassicVrml) X3D format
    -toJava                           # output in .java source code using X3DJSAIL
    -toJSON                           # output in .json (JavaScript Object Notation) format
    -toPython                         # output in .py Python source code
    -toVRML97                         # output in .wrl  (VRML97) format
    -toHTML                           # output in .html  pretty-print documentation
    -toX3DOM                          # output in .xhtml page with X3DOM display of X3D model
    -toX_ITE                          # output in .html  page with X_ITE display of X3D model
    -toMarkdown                       # output document metadata (meta tags) in .md (Markdown) format
    -toEXI                            # output in .exi (Efficient XML Interchange) compressed-XML format
    -toGZIP                           # output in .gz  (X3D XML) format, with gzip compression
    -toZIP                            # output in .zip (X3D XML) format, with zip  compression
    ==================================#====== outputs ============================
    -tofile  [resultFile.*]           # specify output filename (otherwise original name with extension)
    -toImage [snapshotName.*]         # create output images for each Viewpoint using Blender
    

🔖 Conversions to top

X3D scene graph run-time capabilities are interoperable and functionally equivalent for all X3D file encodings and programming-language bindings. Current and planned support is shown in the following table.

File Load and Import
X3D XML encoding .x3d (implemented using DOM) X3D ClassicVRML encoding .x3dv (TODO) X3D VRML97 encoding .wrl (TODO)
Efficient XML Interchange (EXI) compressed .exi
(implemented with choice of EXIficient or OpenEXI)
GZIP-compressed .x3d (implemented) ZIP-compressed .x3d (implemented)
X3D JSON encoding .json (TODO) Geometry import: .stl (implemented) and .ply (TODO)  
File/Stream Export Serialization
X3D XML .x3d encoding, using X3D canonical form default output serialization format (implemented) ClassicVRML .x3dv encoding (implemented) VRML97 .wrl encoding (implemented)
X3DOM scene page X3dom.xhtml (implemented) X_ITE scene page (formerly Cobweb) X_ITE.html (implemented) -toImage .png screenshot using locally installed Blender (implemented)
X3DJSAIL .java source using X3dToJava.xslt (implemented) X3D  .json encoding using X3dToJson.xslt (implemented) X3D  Python .py source using X3dToPython.xslt (implemented)
Efficient XML Interchange (EXI) .exi
(implemented with choice of EXIficient or OpenEXI)
GZIP .gz (implemented) ZIP .zip (implemented)
X3D Compressed Binary Encoding (CBE) .x3db (TODO) Efficient X3D Encoding .x3de (proposed) Shape Resource Container (SRC) .src
(no longer planned for X3D v4, will allow .gltf instead)
XML Canonicalization (C14N) (compatible, stricter X3D Canonical) as CommandLine -canonical XML Signature for authentication (TODO) XML Encryption for confidential access and privacy (TODO)

X3DJSAIL conversion capabilities continue to grow through addition of multiple exporters and importers. Open source rocks!

Related references: X3D Resources: Conversions and Translation Tools plus Export and Import by Applications.

🔖 Blender Conversions to top

Blender is an open-source 3D authoring tool that includes support for X3D import/export (FreeBSD Linux, MacOSX, Windows) (download).

  • TODO: support multiple formats and multiple X3D viewpoints.
  • BlenderLauncher is a utility class for invoking and launching Blender via local operating system to perform a variety of conversion tasks.
  • Available model formats for import/export conversion include .stl, .x3d, .ply, .obj, .3ds, .wrl (VRML97), U3D, COLLADA and others.
  • Blender Python scripts and tests available at src/python/blenderScripts
  • (TODO testing needed) Example command-line arguments and invocations:
    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.BlenderLauncher -help

    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.BlenderLauncher -l logfile.txt -convert file1.stl file2.x3d
    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.BlenderLauncher -l logfile.txt -toImage file.x3d
  • Example invocations in HelloWorldProgram.java:
    System.out.println("BlenderLauncher.run(\"-help\")");
    org.web3d.x3d.jsail.BlenderLauncher.run("-help");
    System.out.println("===========================================");
    // ordinarily path shenanigans are not needed, but this is included as test code
    System.out.print("Blender default path=" + ConfigurationProperties.getBlenderPath());
    if (ConfigurationProperties.getBlenderPath().isEmpty())
    {
        System.out.print("[not set]");
    }
    System.out.println();
    BlenderLauncher.checkBlenderPath(); // check local path and reset to OS-specific default if needed
    System.out.println("Blender.checkBlenderPath() updated path=" + ConfigurationProperties.getBlenderPath());
    System.out.println("=================================");
    System.out.println("BlenderLauncher.hasBlender()=" + BlenderLauncher.hasBlender());
    System.out.println("=================================");
    System.out.println("Blender version=" + BlenderLauncher.getBlenderVersion());
    System.out.println("BlenderLauncher.run(\"CleatClamp.x3d -toImage\")");
    org.web3d.x3d.jsail.BlenderLauncher.run ("CleatClamp.x3d -toImage");
    System.out.println("CommandLine.run(\"CleatClamp.x3d -toImage\") tests pass through");
    org.web3d.x3d.jsail.CommandLine.run ("CleatClamp.x3d -toImage");
    
  • Example invocations in stylesheets/build.xml
            <echo message="==========================================="/>
            <antcall target="test.X3DJSAIL.BlenderLauncher"/>
                    <echo message="now test pass-through invocation:"/>
            <echo   message="org.web3d.x3d.jsail.CommandLine ${java.examples.dir}/CleatClamp.stl -toImage"/>
            <java classname="org.web3d.x3d.jsail.CommandLine" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
                <arg value="${java.examples.dir}/CleatClamp.stl"/>
                <arg value="-toImage"/>
            </java>
    
        <target name="test.X3DJSAIL.BlenderLauncher" description="Test BlenderLauncher capabilities" >
            <echo message="==========================================="/>
            <echo   message="org.web3d.x3d.jsail.BlenderLauncher -help"/>
            <java classname="org.web3d.x3d.jsail.BlenderLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
                <arg value="-help"/>
            </java>
            <echo message="==========================================="/>
            <echo   message="org.web3d.x3d.jsail.BlenderLauncher -properties ${java.examples.dir}/X3DJSAIL.properties"/>
            <java classname="org.web3d.x3d.jsail.BlenderLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
                <arg value="-properties"/>
                <arg value="${java.examples.dir}/X3DJSAIL.properties"/>
            </java>
            <echo message="==========================================="/>
            <echo   message="org.web3d.x3d.jsail.BlenderLauncher -BLENDER_PATH ${env.BLENDER_PATH}"/>
            <java classname="org.web3d.x3d.jsail.BlenderLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
                <arg value="-BLENDER_PATH"/>
                <arg value="${env.BLENDER_PATH}"/>
            </java>
            <echo message="==========================================="/>
            <echo   message="org.web3d.x3d.jsail.BlenderLauncher ${java.examples.dir}/CleatClamp.stl -toImage"/>
            <java classname="org.web3d.x3d.jsail.BlenderLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
                <arg value="${java.examples.dir}/CleatClamp.stl"/>
                <arg value="-toImage"/>
            </java>
        </target>
    
  • Useful Blender references:

🔖 MeshLab Conversions to top

MeshLab is an open source, portable, and extensible system for the processing and editing of unstructured 3D triangular meshes (Win64, MacOS, Linux Snap) (download).

  • MeshLabLauncher is a utility class for invoking and launching MeshLab via local operating system to perform a variety of conversion tasks.
  • Available model formats for import/export conversion include .stl, .x3d, .ply, .obj, .3ds, .wrl (VRML97), U3D, COLLADA, and others.
  • Example command-line switches and invocations:
    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.MeshLabLauncher -help

    java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.MeshLabLauncher -l logfile.txt -i file1.stl -o file2.x3d
  • Example invocations in HelloWorldProgram.java:
    System.out.println("MeshLab default path=" + ConfigurationProperties.getMeshLabPath());
    meshLabLauncher.checkMeshLabPath();
    System.out.println("MeshLab.checkMeshLabPath() new path=" + ConfigurationProperties.getMeshLabPath());
    System.out.println(       "MeshLabLauncher.hasMeshLab()=" + MeshLabLauncher.hasMeshLab());
    System.out.println("MeshLabLauncher.getMeshLabVersion()=" + MeshLabLauncher.getMeshLabVersion());
    boolean conversionResult = meshLabLauncher.convertModel(
        "C:/x3d-code/www.web3d.org/x3d/stylesheets/java/examples",   
        "CleatClamp.stl", "CleatClamp.RoundTrip.stl"); // converts ascii to binary
    X3DObject importedX3D = MeshLabLauncher.importModel(
        "C:/x3d-code/www.web3d.org/x3d/stylesheets/java/examples",
        "CleatClamp.stl");
    System.out.println("MeshLabLauncher.wasPriorCommandSuccessful()=" + MeshLabLauncher.wasPriorCommandSuccessful());
    System.out.println("meshLabLauncher.getPriorMeshLabTraceLogFileName()=" + MeshLabLauncher.getPriorMeshLabTraceLogFilePath());
    System.out.print  ("meshLabLauncher.getPriorMeshLabTraceLogContents()=" + meshLabLauncher.getPriorMeshLabTraceLogContents()); 
    
  • Example invocations in stylesheets/build.xml
    <echo   message="org.web3d.x3d.jsail.MeshLabLauncher -help"/>
    <java classname="org.web3d.x3d.jsail.MeshLabLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
        <arg value="-help"/>
    </java>
    <echo message="==========================================="/>
    <echo   message="org.web3d.x3d.jsail.MeshLabLauncher ${java.examples.dir}/CleatClamp.stl ${java.examples.dir}/CleatClamp.MeshLabLauncher.x3d"/>
    <java classname="org.web3d.x3d.jsail.MeshLabLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
        <arg value="${java.examples.dir}/CleatClamp.stl"/>                 <!--  input model -->
        <arg value="${java.examples.dir}/CleatClamp.MeshLabLauncher.x3d"/> <!-- output model -->
    </java>
    <echo message="==========================================="/>
    <echo   message="org.web3d.x3d.jsail.MeshLabLauncher ${java.examples.dir}/CleatClamp.stl ${java.examples.dir}/CleatClamp.MeshLabLauncher.stl"/>
    <java classname="org.web3d.x3d.jsail.MeshLabLauncher" classpath="${java.jars.dir}/${jsai.full.archive.jar.name};." fork="${fork}">
        <arg value="${java.examples.dir}/CleatClamp.stl"/>                 <!--  input model -->
        <arg value="${java.examples.dir}/CleatClamp.MeshLabLauncher.stl"/> <!-- output model -->
    </java>
    
  • Useful references

🔖 Design Features to top

This work implements the X3D Unified Object Model (X3DUOM) in support of current and emerging capabilities found in the Web3D Recommended Standards, especially X3Dv4.

Success metric: the X3D information model is sufficient to support round-trip conversion of any X3D scene from one encoding to another.

  • In the X3D language binding for Java, field and node types are defined as org.web3d.x3d.sai Java interfaces so that author-created source code for Script nodes can be precompiled and later work with a variety of X3D player implementations.
  • A separate org.web3d.x3d.jsail package of SAI concrete objects that defines instantiable classes, constants and utility methods. Complementary design enables standalone X3D Java programming, with no X3D Script node or external HTML browser required.

The following software-architecture principles have influenced codebase design.

  • Strong checking throughout of node content models and field data types, at compile time, using type safety to avoid run-time errors wherever possible.
  • Strict, extensible string enumerations are provided to avoid simple spelling errors (which otherwise are discovered only by users at run time).
  • Method pipelining to allow setting multiple fields on a single node at one time.
  • Strict checking when setting values using set methods for fields. If a parameter with an illegal value or incorrect length is provided, then no change is applied and an org.web3d.x3d.sai.InvalidFieldValueException exception is thrown.

🔖 Downloads to top

X3DJSAIL can be used in any Java project (version 1.8 or greater) by including one of the following jar files in the application CLASSPATH.

X3DJSAIL.3.3.full.jar can be unzipped to create a complete local copy of all source, binaries, documentation and example programs. It is also executable on the Command Line.

X3DJSAIL.3.3.classes.jar can be used by developers for server-side usage or integration in other applications. Further CLASSPATH modifications may be needed to to use it. For full operation, third-party dependency jars found in the lib subdirectory must also be in the application CLASSPATH. Examples are shown under Command Line use.


🔖 Examples to top

Initial codebase development is building out features in a single example "smoke test" program for comprehensive testing.

Long-term plans include creation (and possibly autogeneration) of a unit-test suite to always ensure that capabilities and features remain working.


🔖 Efficient XML Interchange (EXI) Compression to top

Efficient XML Interchange (EXI) is a World Wide Web Consortium (W3C) Recommendation that provides compact, high-performance compression for XML and JSON files.

 

The OpenEXI introduction whitepaper describes how EXI design produces documents that decompress directly into computer memory, with no parsing of decompressed data required.

EXI file compaction and computational performance have been demonstrated to be superior to a variety other compression schemes including gzip, zip, BSON, CBOR, and other compressed file formats.

EXI References


🔖 Other X3D Java Implementations to top

Other X3D Java implementations are partial and seldom updated.


🔖 References and Relevant X3D Specifications to top


🔖 Specification Changes under Consideration to top

  • X3dJavaSpecificationChangesAndIssues.txt lists noted problems with the governing specification X3D Java SAI Language Bindings (ISO/IEC 19777-2).
  • Significant specification work is needed to align X3D Abstract Scene Access Interface (SAI) and corresponding language-binding specifications, including the X3D Java SAI.
  • Specification prose is needed to define necessary support for DEF, USE and class attributes.
  • Not needed: adding Annex D Java SAI Concrete Classes for standalone scene programming, since other approaches can be accomplished compatibly.
  • Mantis issue tracker keeps track of details, alternatives and resolution for each specification issue.
  • Web3D Consortium github (member-only access) is used to maintain editors-draft Web3D specifications in version control.

🔖 TODO Planned Work to top

TODO: X3dToJava.xslt stylesheet improvements

  • Continued testing and improvement with conversion of .x3d source models in the X3D Examples Archive.
  • Continued resolution of issue reports on x3d-public@web3d.org mailing list (archives).
  • Partially addressed: handle too-large initialization methods (greater than 64K compiled) by splitting off arrays portions as separate data structures, when needed, rather than pipelined functional-style instantiations.
  • Prototypes: check IS/connect support, improve ProtoInstance handling without needing containerField.
  • Add utility method that loads a file referenced by an ExternProtoDeclare in order to load the defined scene subgraph and determine the contained node type.

TODO: X3D Unified Object Model (X3DUOM) issues to top

  • Available: tutorial from Web3D 2017 Conference. Note originally named Object Model for X3D (OM4X3D).
  • Available: transcribe definitions into XML Schema, automate addition of the very-short set of allowed alternative containerField values.
  • Complete: implement specialty string subtypes such as ID, IDREF, NMTOKEN and NMTOKENS.
  • Document how ROUTEs and comments can be children of nodes and statements (but not on a per-field basis).
  • Confirm consistent handling of ROUTE, ProtoInstance, ProtoDeclare, ExternProtoDeclare. Ensure that specification support for ProtoDeclare and ExternProtoDeclare includes appinfo and documentation fields. Ensure that specification support for ProtoInstance includes DEF USE IS class and metadata fields.
  • Add properties for common EXI settings (e.g. schema-informed versus schema-less compression). Perform round-trip unit testing of EXIficient and OpenEXI implementations to confirm compatibility.

TODO: X3DJSAIL source code and capability improvements to top

  • Ongoing. Test X3D scene creation and file serialization using the X3D Examples Archives, together providing over 3900 diverse models for unit testing.
  • X3D JSON loading (output serialization already supported)
  • In progress. coderextreme/X3DJSAIL development is testing and building many capabilities. Nashorn JavaScript usage is demonstrated, and Maven build support is under consideration.
  • Add validation of min/max inclusive/exclusive bounds when setting values for arrays.
  • Add XML Catalog capabilities for XML Schema, DTD etc. in order to support off-line use without an Internet connection.
  • Provide enumeration constants for Humanoid Animation (HAnim) nodes.
  • Provide programmer with java.util.logging options as alternatives to strict exception throwing. Provides ConfigurationProperties.debugModeActive initializer and ConfigurationProperties.setDebugModeActive(boolean), ConfigurationProperties.isDebugModeActive() methods to enable verbose debugging output when desired.
  • Method ConfigurationProperties.setExiEngine(String) with enumeration constants EXI_ENGINE_OPENEXI and EXI_ENGINE_EXIFICIENT for selection between implementations EXIficient (implemented) and Nagasena OpenEXI (testing in progress) to provide XML-based Efficient XML Interchange (EXI) compression.
  • Internationalization (I18N): confirm proper handling of XML character entities and UTF-8 characters, both in Java source and when serializing to other X3D encodings.
  • Measure and profile performance. Aside from stylesheet-driven file conversions, current execution times seem (screamingly?) fast. Further speedups in stylesheet conversions might be possible if stylesheets are precompiled using Saxon.
  • Confirm support for Browser services and connections: 4.2.4 Browser services and 6.2.1 BrowserFactory.
  • Missing capability: need to finish implementation of partial-stub methods for SF/MF Image and Matrix* classes (typically adapting source code from the Xj3D implementation).
  • Automatically support naming correspondences for DEF and name values when first constructing HAnim nodes. Include naming checks in each node's self-checking validate() method.
  • Consider adding import/export for different file encodings (for example .stl, .ply and others). Adding native export to this codebase can likely be adapted to X3D SAI codebases in other programming languages. Even so, robust conversion support in open-source MeshLab and Blender handles most needs.
  • Filter redundant import statements within autogenerated library source code.
  • Add and fully integrate relevant external libraries as needed: jgeom for NURBS, OpenDIS, and likely others.
  • Test compilation with existing X3D Script-node example source code.
  • Test interoperability of resulting .class byte code with various X3D players.
  • Add X3DJSAIL support to next-generation X3D-Edit authoring tool.
  • Explore feasibility of using jsweet transcompilation transpiler to convert X3DJSAIL java libraries into JavaScript.
  • Explore feasibility of using PyJNIus Python module to access Java classes as Python classes using Java Native Interface (JNI).
  • Confirm support for Java Scene Access Interface (SAI) requirements, including Java Scene Access Interface (SAI).
  • Add validate() testing for special fields requiring a higher-than-default component level, when they occur. Example: Inline load field. Requires additional information in X3D Unified Object Model.
  • Integrate support for Apache Santuario project implementing the primary XML security standards: XML-Signature Syntax and Processing (for authentication) and XML Encryption Syntax and Processing (for privacy).
  • Add a variety of utility methods, as needed. Suggestions are welcome!

🔖 Utility Methods and Functionality to top

Utility methods provide additional helpful functionality to X3D Java programmers, going beyond the minimalist required interfaces in the X3D Java SAI specification.

Warning: note that, by default, creating or decompressing files may overwrite prior versions. See ConfigurationProperties.isOverwriteExistingFiles() and setOverwriteExistingFiles(newValue) to modify overwrite permissions.


🔖 Contact to top

Updated 18 August 2019
X3D Java Scene Access Interface Library (X3DJSAIL) deployed release version is available online at
https://www.web3d.org/specifications/java/X3DJSAIL.html
Version-control open source for test programs, results and autogeneration build scripts are available in Sourceforge repository.
Questions, suggestions, additions and comments regarding the X3D Java SAI Library (X3DJSAIL) and X3D Unified Object Model (X3DUOM) design are welcome. Please send them to Don Brutzman (brutzman at nps.edu), John Carlson (yottzumm at gmail.com), and Roy Walmsley (roy.walmsley at ntlworld.com).
Packages 
Package Description
org.web3d.x3d.jsail  
org.web3d.x3d.jsail.CADGeometry  
org.web3d.x3d.jsail.Core  
org.web3d.x3d.jsail.CubeMapTexturing  
org.web3d.x3d.jsail.DIS  
org.web3d.x3d.jsail.EnvironmentalEffects  
org.web3d.x3d.jsail.EnvironmentalSensor  
org.web3d.x3d.jsail.EventUtilities  
org.web3d.x3d.jsail.fields  
org.web3d.x3d.jsail.Followers  
org.web3d.x3d.jsail.Geometry2D  
org.web3d.x3d.jsail.Geometry3D  
org.web3d.x3d.jsail.Geospatial  
org.web3d.x3d.jsail.Grouping  
org.web3d.x3d.jsail.HAnim  
org.web3d.x3d.jsail.Interpolation  
org.web3d.x3d.jsail.KeyDeviceSensor  
org.web3d.x3d.jsail.Layering  
org.web3d.x3d.jsail.Layout  
org.web3d.x3d.jsail.Lighting  
org.web3d.x3d.jsail.Navigation  
org.web3d.x3d.jsail.Networking  
org.web3d.x3d.jsail.NURBS  
org.web3d.x3d.jsail.ParticleSystems  
org.web3d.x3d.jsail.Picking  
org.web3d.x3d.jsail.PointingDeviceSensor  
org.web3d.x3d.jsail.Rendering  
org.web3d.x3d.jsail.RigidBodyPhysics  
org.web3d.x3d.jsail.Scripting  
org.web3d.x3d.jsail.Shaders  
org.web3d.x3d.jsail.Shape  
org.web3d.x3d.jsail.Sound  
org.web3d.x3d.jsail.Text  
org.web3d.x3d.jsail.Texturing  
org.web3d.x3d.jsail.Texturing3D  
org.web3d.x3d.jsail.Time  
org.web3d.x3d.jsail.VolumeRendering  
org.web3d.x3d.sai  
org.web3d.x3d.sai.CADGeometry  
org.web3d.x3d.sai.Core  
org.web3d.x3d.sai.CubeMapTexturing  
org.web3d.x3d.sai.DIS  
org.web3d.x3d.sai.EnvironmentalEffects  
org.web3d.x3d.sai.EnvironmentalSensor  
org.web3d.x3d.sai.EventUtilities  
org.web3d.x3d.sai.Followers  
org.web3d.x3d.sai.Geometry2D  
org.web3d.x3d.sai.Geometry3D  
org.web3d.x3d.sai.Geospatial  
org.web3d.x3d.sai.Grouping  
org.web3d.x3d.sai.HAnim  
org.web3d.x3d.sai.Interpolation  
org.web3d.x3d.sai.KeyDeviceSensor  
org.web3d.x3d.sai.Layering  
org.web3d.x3d.sai.Layout  
org.web3d.x3d.sai.Lighting  
org.web3d.x3d.sai.Navigation  
org.web3d.x3d.sai.Networking  
org.web3d.x3d.sai.NURBS  
org.web3d.x3d.sai.ParticleSystems  
org.web3d.x3d.sai.Picking  
org.web3d.x3d.sai.PointingDeviceSensor  
org.web3d.x3d.sai.Rendering  
org.web3d.x3d.sai.RigidBodyPhysics  
org.web3d.x3d.sai.Scripting  
org.web3d.x3d.sai.Shaders  
org.web3d.x3d.sai.Shape  
org.web3d.x3d.sai.Sound  
org.web3d.x3d.sai.Text  
org.web3d.x3d.sai.Texturing  
org.web3d.x3d.sai.Texturing3D  
org.web3d.x3d.sai.Time  
org.web3d.x3d.sai.VolumeRendering  
org.web3d.x3d.util.exi  
org.web3d.x3d.util.x3duom