X3D Java Scene Access Interface Library (X3DJSAIL)

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 | Configuration Properties | Conversions including Blender, MeshLab | Design Features | Downloads | Errors and Exceptions | Examples | EXI | Javadoc | License | Other Implementations | README | References | Specification Changes | TODO | Utility Methods | X3D Regexes | X3D Resources | X3D Scene Authoring Hints | X3D Tooltips | X3DUOM | Contact

🔖 Abstract

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 integrated Java packages are included that contain X3D SAI interfaces and support the X3D Graphics 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.

Goal outcomes: make it easy to create a fully valid X3D scene graph using Java, while also making it hard to create an incorrect or invalid X3D model. X3DJSAIL has succeeded in accomplishing these goals.

• Software design patterns are autogenerated from rigorous definitions of all X3D node and field relationships using the X3D Unified Object Model (X3DUOM).
• Validation of individual fields includes application of X3D Regular Expressions (regexes).
• X3DJSAIL Javadoc includes all descriptions, links, hints, and warnings from the X3D Tooltips.

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

This library successfully supports multiple purposes:

• Create high-performance standalone Java applications using a Plain Old Java Object (POJO) implementation for X3D.
• Such X3D-capable Java applications can be client-based, server-based, or driven via command-line invocation (CLI) such as Java Console (jconsole).
• No additional Java packages are necessary, with all included code offered under a royalty-free license suitable for any legitimate purpose.
• Confirms correct implementation of ISO standard X3D version 4.0 while maintaining full support for prior X3D versions 3.0 through 3.3.

X3DJSAIL also serves as a design template to autogenerate similar codebases for Python and X3D Ontology using Turtle. Similar future possibilities include ECMAScript and JSON Schema, C#/C++/C, and potentially programming languages.

🔖 Codebase Production

X3DJSAIL binaries are compatible with Java 1.8 and greater. X3DJSAIL source is compiled and tested under latest Java OpenJDK (default) and occasionally Oracle JDK.

The Savage Developers Guide provides further details on current compilation configuration settings for Ant, Java, and NetBeans.

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

• X3DJSAIL rigorously matches the data types and parent-child relationships of the X3D specifications.
• This is a mature stable software release that is adding further capabilities while undergoing software testing and public review. X3DJSAIL is tracking development of X3D version 4 International Standard. See the TODO list for work details.
• This codebase is automatically generated from X3DUOM (.xml) definitions, which in turn are automatically generated from the annotated X3D XML Schema. Thus X3DJSAIL always remains "up to date" with respect to the latest version of X3D.
• Initial version 4.0 release is complete following satisfactory conversions of all X3D Examples Archives. Javadoc links are provided for all model archives. See build.java.all.log.txt (version control) for console logs from all examples.
• X3D Resource Examples: Scene Archives for X3D links Javadoc package descriptions for all of these archives.
• Build functionality is invoked via the X3D Stylesheets build.xml file and Ant. Schema to object model to codebase conversion is performed by two XSLT stylesheets, BuildX3dUnifiedObjectModelXmlFile.xslt and CreateX3dSceneAccessInterfaceJava.xslt, one after the other.
• Validation of ClassicVRML (.x3dv) and VRML97 (.wrl) output files is performed using castle-model-viewer in command-line mode.
• For developers, example build output is found at build.create.X3DJSAIL.txt console output.
• Explanatory information about the functionality of all X3D nodes and fields is inserted into source code and Javadoc using the X3D Tooltips (specifically the X3D English tooltips XML source file).
• Source code for most classes is not maintained in version control when autogenerated. Source code for test cases is maintained in version control on Sourceforge at
  www.web3d.org / x3d / stylesheets / java / tests / org / web3d / x3d / tests
• The X3DJSAIL library-creation files currently require multiple external assets and a small amount of local configuration for complete assembly.

🔖 CLASSPATH and Command Line

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.4.0.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.4.0.full.jar org.web3d.x3d.jsail.CommandLine -help

  Example:    java -classpath someLocalPath/X3DJSAIL.4.0.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.4.0.full.jar

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

  • Developer alternative: For developers, an alternative CLASSPATH configuration is "skinny jar" X3DJSAIL.4.0.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.4.0.classes.jar;
C:\x3d-code\www.web3d.org\x3d\stylesheets\java\lib\saxon-he-12.5.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 X3D.handleArguments(args).

• 🔖 Example -help output:

  $ 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
  

🔖 Configuration Properties

Setting X3DJSAIL properties can override default library values. See

• X3DJSAIL.properties and
• X3DJSAIL.properties.template example

X3DJSAIL properties can also be accessed programmatically using the ConfigurationProperties utility class. Example constants and accessor methods:

• ConfigurationProperties.PROPERTIES_FILENAME_DEFAULT
• ConfigurationProperties.getPropertiesFileName()
• ConfigurationProperties.setPropertiesFileName(fileName)
• ConfigurationProperties.loadProperties()
• ConfigurationProperties.ERROR_NOT_CONNECTED_TO_SCENE_GRAPH
• ConfigurationProperties.WARNING_PROTOINSTANCE_NOT_FOUND
• ConfigurationProperties.isNormalizeCommentWhitespace()
• ConfigurationProperties.setNormalizeCommentWhitespace(boolean)
• ConfigurationProperties.isStripTrailingZeroes()
• ConfigurationProperties.setStripDefaultAttributes(boolean) etc.

🔖 Conversions

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.

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

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

If you have a local copy of Blender installed on your system, X3DJSAIL can invoke it via the BLENDER_PATH property found either in the system environment variables or else the X3DJSAIL.properties file.

• 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
• Example command-line arguments and invocations:
  
  java -classpath someLocalPath/X3DJSAIL.4.0.full.jar org.web3d.x3d.jsail.BlenderLauncher -help
  
  java -classpath someLocalPath/X3DJSAIL.4.0.full.jar org.web3d.x3d.jsail.BlenderLauncher -l logfile.txt -convert file1.stl file2.x3d
java -classpath someLocalPath/X3DJSAIL.4.0.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="==========================================="/>
  
      <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:
  • Blender and Blender Quickstart Introduction
  • Blender Command Line
  • Blender API Introduction, Blender Python API Documentation and Scripting & Extending Blender
  • Blender 3D: Noob to Pro book and Blender 3D: Noob to Pro/Advanced Tutorials/Python Scripting/Introduction
  • Video: Blender Tutorial Introduction to Python Scripting: Writing a Script That Makes a Simple 3D Model

🔖 MeshLab Conversions

Change notice. MeshLab is now on a monthly release cycle. The latest versions have removed meshlabserver which is used below (see Where is Meshlabserver.exe in 2020.12 for details). MeshLab now provides Python scripting capabilities instead. Review and revision is pending.

TODO: fix X3DJSAIL to support major upgrade to PyMeshLab. The following example invocation no longer works.

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

If you have a local copy installed on your system, X3DJSAIL can invoke it via the MESHLAB_PATH property in the X3DJSAIL.properties file.

• X3DJSAIL 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.4.0.full.jar org.web3d.x3d.jsail.MeshLabLauncher -help
  
  java -classpath someLocalPath/X3DJSAIL.4.0.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
  X3D 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
  • MeshLab, MeshLab References and Wikipedia: MeshLab
  • SourceForge: meshlab in command-line?
  • SourceForge: Automating Meshlab conversion
  • GitHub: meshlabserver.txt command-line help
  • GitHub: TheNerdJedi/MeshlabAuto
  • Mr. P. MeshLab Tutorials: MeshLab Basics, 3D Scanning pipeline, Features, Cleaning
  • StackOverflow: MeshLab
  • GitHub: MeshlabAuto and GitHub: Meshlab issues

🔖 Design Features

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

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

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.4.0.full.jar     (55MB) is a fat jar with all necessary binaries, source, and documentation.
• X3DJSAIL.4.0.classes.jar (6MB) is a minimalist jar that only contains X3DJSAIL classes and assets.

X3DJSAIL.4.0.full.jar can be unzipped to create a complete local copy of all source, binaries, documentation and example programs. If visible via CLASSPATH, it is also executable via the Command Line.

X3DJSAIL.4.0.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.

X3DJSAIL development:

• CreateX3dSceneAccessInterfaceJava.xslt stylesheet creates open-source X3D Java Scene Access Interface (SAI) Library (X3DJSAIL) from X3D Unified Object Model (X3DUOM)
• stylesheets/java/ directory holds stubs and deployment files. The X3DJSAIL autogenerated java source code is so massive, and with details evolving, that it is only provided as part of the distribution and not checked into version control. This is typically not a problem since programmers do not need to use internal class methods.
• The X3dToJava.xslt stylesheet is used by the X3D Examples Archives to perform thousands of model conversions as X3DJSAIL regression tests.
• build.java.all.log.txt (version control) shows latest outputs for this regression testing.

🔖 Errors and Exceptions

X3DJSAIL compilation errors typically indicate a problem with the X3D model itself. Because X3D is so strongly typed, X3DJSAIL usually does not permit creation of an incorrect model.

Such strictness is good - no really! It is much better to learn about errors when authoring than it might be do deliver a broken model to an end user.

Special compilation errors:

• error: code too large, or
  error: too many constants.
  • Java has an internal limit of 64K bytes per compiled method. Unfortunately if you get this error, it likely means your geometry definitions are simply too big to handle. There is no direct programmatic workaround available or planned (as of JDK 20). Alternative approaches are loading X3D content from a file, or possibly geometry simplifications.
  • StackOverflow: Java "too many constants" JVM error
  • StackOverflow: javac error "code too large"?
  • StackOverflow: "Code too large" compilation error in Java

X3DJSAIL exception handling provides warnings or error reports when unexpected conditions occur at run time.

X3DJSAIL Javadoc provides descriptions, documentation, and helpful reference links for every class, method and value in the programming library.

Java Tutorials Lesson: Exceptions is helpful for learning more about run-time exception analysis and debugging using Java. Additionally, the NetBeans Visual Debugger provides excellent capabilities for Java programmers.

Still stuck? You can keep going:

• The X3D-Edit authoring tool is an independent Java application that has many capabilities for X3D model validation and Quality Assurance (QA).
• The x3d-public@web3d.org mailing list (archives) is an excellent way to get community feedback.
• Please contact us with a trouble report - thanks in advance for providing sufficient detail that might allow us to diagnose things further.

🔖 Examples

The X3D Examples Archives includes Javadoc for multiple archives. Ongoing support includes autogeneration and compilation of thousands of X3D model examples as a unit-test suite, to always ensure that capabilities and features remain working.

	Basic	The X3D Graphics Basic Examples Archive provides a wide variety of basic open-source examples that show how to design and build X3D scenes.
	ConformanceNist	The ConformanceNist X3D Examples Archive was converted from the original VRML Test Suite (VTS) providing full coverage of the Virtual Reality Modeling Language (VRML97) Specification. It was produced by a team of experts at the U.S. National Institute of Science and Technology (NIST) in 1999.
	HumanoidAnimation	The HumanoidAnimation (HAnim) X3D Examples Archive includes a growing number of humanoid models using joints, segments, skin, and animation behaviors.
	Vrml2Sourcebook	The VRML 2 Sourcebook was written by Andrea L. Ames, David R. Nadeau, and John L. Moreland, published by John Wiley & Sons, 1996.
	X3dForWebAuthors	X3D for Web Authors is an introductory reference textbook for learning Extensible 3D (X3D) Graphics.
	X3dForAdvancedModeling	The X3D for Advanced Modeling Examples Archive is a developmental resource for learning advanced X3D Graphics modeling techniques.
	Savage	The NPS Scenario Authoring and Visualization for Advanced Graphical Environments (SAVAGE) Research Group maintains a large archive of dynamic 3D military models and authoring tools, all open source and built using Extensible 3D (X3D) graphics.
	SavageDefense	The NPS Scenario Authoring and Visualization for Advanced Graphical Environments (SAVAGE) Research Group maintains a large archive of dynamic 3D military models and authoring tools, all open source and built using Extensible 3D (X3D) graphics. SavageDefense is the corresponding restricted-access Controlled Unclassified Information (CUI) archive.

• For instance, the Geometry Primitive Nodes index page includes links to corresponding GeometryPrimitiveNodes.java source and archive javadoc.
• build.java.all.log.txt (version control) records comprehensive conversion, compilation and execution results.

X3DJSAIL codebase development often builds new features using a single example "smoke test" program for comprehensive testing.

• Smoke test: HelloWorldProgram.java source exercises many X3DJSAIL features, as shown by build.test.X3DJSAIL.txt.
• Program-generated outputs include X3D model, ClassicVRML model, VRML97 model, JSON encoding, Java source, Python source, X3DOM scene page, X_ITE scene page, screenshot image and movie
• Concise autogenerated java source produces the resulting X3D scene-graph program: HelloWorldProgramOutput.java
• Load the produced scene HelloWorldProgramOutput.x3d (validator) then write resulting DOM back out to HelloWorldProgramOutput.ReloadedDOM.x3d (validator)
• Stylesheet-generated pretty-print X3D model documentation
• Experimental HelloWorldProgramOutput.ReloadedDOM.x3d using the X3DLoaderDOM class
• HelloWorldProgramOutput.java source-code serialization using X3D.toFileJava(filename) and X3dToJava.xslt stylesheet.

🔖 Efficient XML Interchange (EXI) Compression

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

• OpenEXI Nagasena project: overview video, introduction whitepaper and implementation tutorial with code available as open source in OpenEXI Sourceforge project repository.
• EXIficient project implementation in Java, JavaScript, and C/C++ programming languages with code available as open source in EXIficient github project repository.
• EXI Working Group Public Page describes work in progress and how to get involved.
• Efficient XML Interchange (EXI) Format 1.0 (Second Edition), W3C Recommendation, 11 February 2014. EXI is a very compact representation for the Extensible Markup Language (XML) Information Set that is intended to simultaneously optimize performance and the utilization of computational resources.
• EXI Primer provides a more-easily readable technical background on the Efficient XML Interchange (EXI) format.
• Canonical EXI, W3C Candidate Recommendation, 03 Nov 2016. Canonical EXI describes a relatively simple method for generating a consistent canonical form of an EXI document that accounts for permissible differences that might otherwise occur when using different applications. Canonical form specifies a unique representation for any document, encouraging consistent document interchange and data-centric security.
• EXI4JSON (EXI for JSON), Second Public Working Draft, 23 August 2016. With a relatively small set of transformations EXI may also be applied to compress JavaScript Object Notation(JSON), a popular format for exchange of structured data on the Web.
• Efficient Messaging considerations for afloat networking and Network Optional Warfare (NOW).

🔖 Other X3D Implementations using Java

Additional X3D implementations supporting Java are also available.

• X3D-Edit authoring tool
• Xj3D
• FreeWrl (Script code)
• InstantReality (Script code)

🔖 References and Relevant X3D Specifications

• X3D Java SAI Language Bindings (ISO/IEC 19777-2) that these packages implement.
  • Autogenerated: draft Annex B Node type interfaces (former original Abstract node interfaces)
  • Autogenerated: draft Annex C Node interfaces         (former original Concrete node interfaces)
• X3D Abstract Specification (ISO/IEC 19775-1) providing functional definitions for X3D scene graphs.
• X3D SAI Abstract Specification (ISO/IEC 19775-2) abstract interface definitions for all SAI programming language bindings.
• X3D JSON Encoding, JSON schema (documentation) and draft X3D JSON specification.
• X3D JSON implementations: X3D to JSON Stylesheet Converter and X3DJSONLD JavaScript conversion library.
• Roy Walmsley, Don Brutzman and John Carlson, "A JSON Encoding for X3D", Web3D 2016 Conference, Anaheim California, 22-24 July 2016.
• X3D Python implementations: X3D to Python Stylesheet Converter and Python X3D Package x3d.py.
• X3D Example Archives: Basic, Script Conformance and X3D for Web Authors, Chapter 09 - Event Utilities Scripting
• The Virtual Reality Modeling Language (VRML) and Java, Don Brutzman, Communications of the ACM, vol. 41 no. 6, June 1998, pp. 57-64.
• Functional Programming in Java: Harnessing the Power of Java 8 Lambda Expressions, Venkat Subramaniam, Pragmatic Bookshelf, Dallas Texas, 2014.
• Java Reflection in Action, Ira R. Forman and Nate Forman, Manning Press, Greenwich England, 2005.
• Java Tutorials: Reflection API, Transforming XML Data with XSLT

🔖 Specification Changes under Consideration

• 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 and Completed Work

TODO: priority goals to keep pace with community needs

• Stable and ongoing. Check X3D scene creation and file serialization using the X3D Examples Archives, together providing over four thousand diverse models for unit testing.
• In order to help reduce model bloat for CAD and related exports, provide ability to limit resolution (significant digits) of floating-point outputs in order to reduce output file size. Provide separate optional settings for lengths, rotations, and texture coordinates, both on a scene and per-node basis. Note precision values as contained metadata.
• When updating specifications for X3D 4.0, use Java Annotations to confirm support for abstract 19775-2 X3D Scene Access Interface (SAI) requirements, once eventually applying updates to 19777-2 Java Scene Access Interface (SAI).
• As part of X3D4 deployment: show effective connections to external tools such as MeshLab and Blender as they further evolve.

TODO: X3dToJava.xslt stylesheet improvements

• Stable and ongoing. Continued regression testing and improvement with conversion of thousands of .x3d source models in the X3D Examples Archives is at a high level of maturity.
• Continued resolution of issue reports on x3d-public@web3d.org mailing list (archives) and SourceForge tickets list.
• Limitations of Java memory handling: many methods with large blocks of data (greater than 64K compiled) are supported by splitting off arrays portions as separate data structures, when needed, rather than pipelined functional-style instantiations. However some of the extremely large X3D models are simply... too large. See build.java.all.log.txt (version control) for console logs from all examples.
• Prototypes: in-depth checking of 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 actual contained node type (matching first node in the prototype body).

TODO: X3D Unified Object Model (X3DUOM) issues

• 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

• X3D JSON loading (output serialization already supported)
• Complete, nashorn engine is no longer supported. 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.
• Complete. Update XML Catalog capabilities for XML Schema, DTD etc. in order to speed validation without requiring online retrieval.
• Complete. Provide enumeration constants for Humanoid Animation (HAnim) nodes, versions 1 and 2. See corresponding HAnim nodes in Package org.web3d.x3d.jsail.HAnim
• 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, or else (more likely) propose removal from SAI: 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).
• Utility methods to 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 supporting Java in the Script node (if any).
• Add X3DJSAIL support to next-generation X3D-Edit authoring tool.
• Complete: problematic, discontinued. Explore feasibility of using jsweet transcompilation transpiler to convert X3DJSAIL java libraries into JavaScript.
• Complete: problematic, discontinued. Explore feasibility of using PyJNIus Python module to access Java classes as Python classes using Java Native Interface (JNI).
• 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).
• Complete. Added support for sourceCode methods to embed ecmascript: source without escape characters, equivalent to last entry in the url list.
• Add a variety of utility methods, as needed. Suggestions are welcome!

🔖 Utility Methods and Functionality

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

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

• Complete. Utility methods for X3D model attributes when used as part of HTML pages.
  • Methods of interest for common HTML attributes are present but have slightly different names to clearly differentiate them from X3D fields.
  • Specific patterns include getHtmlID(), getCssClass(), getCssStyle() and setHtmlID(newValue), setCssClass(newValue), setCssStyle(newValue).
  • Example methods: Box.getHtmlID() and Box.setHtmlID(java.lang.String), Box.getCssClass() and Box.setCssClass(java.lang.String), Box.getCssStyle() and Box.setCssStyle(java.lang.String)
  • Example test model: HelloWorldX3D4.x3d (pretty print) and HelloWorldX3D4.java
• Complete. Import loading: ability to load X3D scene-graph files.
  • X3D.loadModelFromFileX3D(fileName), X3D.loadModelFromFileX3D(x3dFile), X3D.replace(newX3DObject)
  • X3D.fromFileEXI(exiFileName) (using EXIficient, OpenEXI testing in progress)
  • X3D.fromFileGZIP(gzipFileName)
  • X3D.fromFileZIP(zipFileName, modelFileName)
    If no modelFileName is provided, then the first .x3d model encountered in the zip file is returned (if any).
  • X3DLoaderDOM.loadModelFromFileX3D(fileName), X3DLoaderDOM.loadModelFromFileX3D(x3dFile), X3DLoaderDOM.getValidationResult()
  • X3DLoaderDOM.getDomDocument(), X3DLoaderDOM.toX3dModelInstance() and other methods.
• Complete. Export serialization: ability to save X3D scene-graph files in various file encodings and language bindings, with each returning the resulting File object if successful. Similar toStringEncoding and toStringLanguage methods are also provided.

  X3D.toFileX3D(fileName) X3D.toFileClassicVRML(fileName) X3D.toFileVRML97(fileName) X3D.toFileJava(fileName)

  X3D.toFileJSON(fileName) X3D.toFilePython(fileName) X3D.toFileEXI(resultFileName) (using EXIficient, OpenEXI testing in progress) X3D.toFileGZIP(resultFileName) X3D.toFileZIP(zipFileName,modelName)

• Complete. Export serialization: XSLT stylesheet support that subsequently converts an intermediate XML X3D scene.
  • Pretty-print HTML documentation using method X3D.toFileDocumentationHtml(String filename) with stylesheets STYLESHEET_HTML_DOCUMENTATION, STYLESHEET_ExtrusionCrossSectionSVG
  • X3DOM page presentation using method X3D.toFileX3DOM(String filename) with stylesheet STYLESHEET_X3DOM
  • X_ITE page presentation using method X3D.toFileX_ITE(String sourceSceneName, String filename) with stylesheet STYLESHEET_X3DOM (with parameter settings)
  • X3D-Tidy (example) using method X3D.toFileX3dTidy(String filename) and X3D.toStringX3dTidy() with stylesheet STYLESHEET_X3DTIDY (TODO add parameter settings)
  • Model Meta Information to Markdown using methods X3D.toFileModelMetaMarkdown(String filename) and X3D.toStringModelMetaMarkdown() with stylesheet STYLESHEET_MODEL_META_TO_MARKDOWN
  • JSON encoding using method X3D.toFileJSON(String filename) with stylesheet STYLESHEET_JSON
  • Java language binding using method X3D.toFileJava(String filename) with stylesheet STYLESHEET_JAVA
  • Choice of XSLT engines, can use method ConfigurationProperties.setXsltEngine(String filename) with XSLT_ENGINE_saxon (default) or XSLT_ENGINE_nativeJava.
• Complete. Demonstrated declarative programming style in HelloWorldProgram.java method createDeclarativeShapeTests().
  • Further method-pipelining support provided by chainable utility method addChild() for nodes implementing the X3DGroupingNode interface. This is a big help because SAI-specified interfaces for addChildren() are required to return void.
  • Ancestor-finding Utility methods .hasAncestorSceneObject() and .findAncestorSceneObject() .hasAncestorX3DObject() and .findAncestorX3DObject(), findAncestorProtoBody() and hasAncestorProtoBody().
  • Be sure to first utilize one of the preceding find methods if finding elements in the scene graph.
  • Further declarative-style support provided by utility methods findNodeByDEF(DEFvalue), findElementByNameValue(nameValue), findElementByNameValue(nameValue, elementName), findAncestorElementByName(ancestorElementName) and hasAncestorElementByName(ancestorElementName).
  • Possible future work: autogenerate a subset codebase for X3D CAD Profile (or another profile) tuned for Java Micro Edition/Android use.
• Complete. For convenience add containerField_DEFAULT to each node, as well as a handful of containerField_ALTERNATE_VALUES. Interestingly these values are typically never needed in Java SAI programs (unless someone is writing a low-level XML parser or somesuch). For more detail: X3D Scene Authoring Hints: containerField.
• Complete. Test concrete field-type classes for SFBool/MFBool through SFNode/MFNode to support value instantiation, including creation of type-checked new values from strings. A number of new data types have been added since X3D version 3.0 and the original Java SAI, so extra attention is needed to ensure that new classes and methods consistently support new specification additions.
• Complete. Build examples, test and finish support for prototypes: ProtoDeclare, ProtoInterface, ProtoBody, ExternProtoDeclare, ProtoInstance, IS and connect.
• All value handling is now strongly typed for fieldObject and fieldValueObject.
• Complete. Add type and accessType checking of ROUTE fields using ROUTE.validate() method.
• Complete. Add a subtree-walking X3D.validate() to confirm correctness of all attribute and contained-node values. This feature essentially confirms the strongly typed design and value-range checks already in place.
• Complete. Add support for DEF and USE attributes. Follow up with related specification issues for abstract SAI and corresponding encoding specifications.
• Complete. Add class attribute to Object Model for X3D (OM4X3D). Follow up with related specification issues for abstract SAI and corresponding encoding specifications.
• Complete. Utility constructor for nodes that includes DEF name for immediate identification when creating a new node.
• Complete. Add support for concrete SFNode and MFNode instantiation. Add boolean hasSomeFieldName() methods to indicate whether each SFNode/MFNode field contains either strongly typed node(s) or ProtoInstance node(s).
• Complete. Add concrete utility variants for addChildren/clearChildren /removeChildren/setChildren and related accessor methods.
• Complete. Check node types and min/max range values, throw exceptions before setting fields incorrectly.
• Complete. Convert concrete arrays to ArrayList data structures.
• Complete. Add ConfigurationProperties serialization support for line indent character and indent increment.
• Complete. Confirm generation of default attribute values and constructors for concrete objects.
• Complete. Concrete objects for X3D statements, also confirming that attributes are properly reflected as fields.
• Complete. Support for persistent scene-graph comments, providing addComments() methods for any node or statement, using CommentsBlock class.
• Complete. Add support for numerous hexadecimal 0xRRGGBB integer colors (through defined constants and utility methods) to SFColorObject and related classes.
• Complete. Add string constants that name each field eligible for ROUTE connections, e.g. OrientationInterpolator.toField_SET_FRACTION and OrientationInterpolator.fromField_VALUE_CHANGED.
• Complete. Utility methods getFieldType(fieldName) and getAccessType(fieldName) for each X3DConcreteElement
• Complete. Add conversionFactor convenience constants for unit statement scale factors.
• Complete. Default toStringX3D() serialization-output settings support X3D canonical form, with ConfigurationProperties providing additional settings for showing default attribute=value pairs. Thus additional X3D Canonicalization (C14N) integration is no longer needed.
• Complete. Utility methods headObject.getMetaByName(metaName) getComponentByName(componentName) and getUnitByName(unitName), ScriptObject.findFieldByName(fieldName) (also for ComposedShaderObject, ShaderPartObject and ShaderProgramObject), and ProtoInstanceObject.findFieldValueByName(fieldValueName)
• Complete. Convenience methods to set a single String or SFString into an MFStringObject field, plus additional static convenience methods for enumeration handling such as cleanupEnclosingQuotes(singleValue) and cleanupEnumerationValue(values).
• Complete. Added run-time checks to ensure acceptableNodeTypes restrictions are met for operations on children nodes, such as ViewpointGroupObject.
• Complete. Scene-graph construction and run-time checks for IMPORTObject and EXPORTObject.
• Complete. Add ConfigurationProperties.setValidationExceptionAllowed to set whether partial results are allowed if validation exception occurs when serializing scene output. Can be useful technique for debugging, validationExceptionAllowed_DEFAULT value is false for strict operation.
• Complete. Add X3D profile-validation and component-validation checks.
• Complete. Utility methods X3DConcreteNode.isNode(), X3DConcreteStatement.isStatement() and CommentsBlock.isStatement()
• Complete. ExtrusionObject utility methods isCrossSectionClosed(), isSpineClosed() and toFileSvgCrossSection(fileName)
• Complete.     X3D Regular Expression (regex) support in field types, for example SFVec3fObject REGEX string, pattern, validate(), matches() and matches(String value).
• Complete. SFImage support for SFColor.toStringCSS() and .toStringHTML() methods.
• Complete. Add X3D Regular Expressions (regexes), apply them in X3D XML Schema, then include in X3DUOM and X3DJSAIL.
• Complete. Add ConfigurationProperties.isSFImagePixelOutputHexadecimal() and .setSFImagePixelOutputHexadecimal(boolean) serialization support for MF/SFImage.toString(), .toStringHexadecimal() and .toStringDecimal().
• Complete. X3D Regular Expression (regex) support for special types, for example SFVec3f.matchesBboxSizeType(String value).
• Complete. Provide annotation descriptions for abstract node types in XML Schema.
• Complete. In addition to allowed node types, permit setting ProtoInstance as part of MFNode field arrays.
• Complete. All class names are now simplified and no longer require Object appended.

🔖 Contact

Updated: 12 December 2024

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.

Acknowledgements: we gratefully acknowledge the contributions of Terry Norbraten, Mike Bailey and Don McGregor of NPS, John Carlson, Roy Walmsley for original design considerations, and numerous other contributors to the X3D Graphics International Standard.

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).