 |
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 | Conversions | Design Features | Downloads | Examples | EXI | Javadoc | License | Other Implementations | README | References | Specification Changes | TODO | Utility Methods | 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 open-source Java packages are included that contain X3D SAI interfaces and support the X3D Standards for Java programmers.
-
org.web3d.x3d.jsailprovides concrete implementation-oriented classes for building X3D scenes using standalone Java objects. -
org.web3d.x3d.saicontains 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
This work implements the X3D Unified Object Model (X3DUOM) in support of complete current and emerging X3D Specification capabilities.
- This is a beta software release that is adding further capabilities while undergoing software testing and public review. See the TODO list for work details.
-
Initial
version 1.0release is complete following satisfactory conversions of all X3D Examples Archives.. Javadoc links are provided for all archives. See build.log.java.txt for console logs from all examples. - This codebase is automatically generated from the X3D Object Model (.xml) which in turn is automatically generated from the annotated X3D XML Schema.
- X3DJSAIL rigorously matches the data types and parent-child relationships of the X3D specifications.
- Schema to object model to codebase conversion is performed by two XSLT stylesheets, BuildObjectModelXmlFile.xslt and CreateX3dSceneAccessInterfaceJava.xslt, one after the other.
- Explanatory information about the functionality of X3D nodes and fields is inserted into source code and Javadoc using the X3D Tooltips (specifically the X3D English tooltips XML source file).
- Build functionality is invoked via the X3D Stylesheets build.xml file and Ant.
- X3D Resource Examples: Scene Archives for X3D lists Javadoc links for all archives.
-
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 / src / org / web3d / x3d / tests
TODO under active development: the X3DJSAIL library-creation files currently require multiple external assets and local configuration. Ongoing work will combine these and other resources into an independently buildable project.
🔖
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.3.3.full.jar
[sourceModel.x3d | package.path.ProgramName | -help | -page | -resources | -tooltips]
[-tofile [resultFile.*]] [-properties [propertiesFile]] [-validate]
[sourceModel.exi -fromEXI] [sourceModel.gz -fromGZIP] [sourceModel.zip -fromZIP]
[-toX3D | -toXML | -toHTML | -toMarkdown | -toTidy | -toClassicVrml | -toJava | -toJSON | -toVRML97 | -toX3DOM | -toX_ITE | -toGZIP | -toZIP]Example:
java -classpath someLocalPath/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine -helpExample:
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.jarExample CLASSPATH confirmation:
% echo $CLASSPATH
CLASSPATH='C:\x3d-code\www.web3d.org\x3d\stylesheets\java\jars\X3DJSAIL.3.3.full.jar' -
Alternative: For developers, an alternative CLASSPATH configuration is "skinny jar"
X3DJSAIL.3.3.classes.jarbut 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 proper CLASSPATH configuration:
-
java org.web3d.x3d.jsail.CommandLine
[sourceModel.x3d | package.path.ProgramName | -help | -page | -resources | -tooltips]
[-tofile [resultFile.*]] [-properties [propertiesFile]] [-validate]
[sourceModel.exi -fromEXI] [sourceModel.gz -fromGZIP] [sourceModel.zip -fromZIP]
[-toX3D | -toXML | -toHTML | -toMarkdown | -toTidy | -toClassicVrml | -toJava | -toJSON | -toVRML97 | -toX3DOM | -toX_ITE | -toGZIP | -toZIP]Example:
java org.web3d.x3d.jsail.CommandLine -helpExample:
java org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toClassicVRMLExample:
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).
🔖
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.
| 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 EXIficient; OpenEXI to follow) |
GZIP-compressed .x3d
(implemented)
|
ZIP-compressed .x3d
(implemented)
|
X3D JSON
encoding .json
(TODO)
|
.stl
and
.ply
geometry import
(TODO)
|
|
| File/stream Export serialization | ||
X3D XML .x3d encoding
(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)
|
X3D .json encoding
(implemented)
|
Efficient XML Interchange (EXI)
.exi
(implemented with EXIficient, OpenEXI to follow) |
GZIP
.gz
(implemented)
|
ZIP
.zip
(implemented)
|
X3D Compressed Binary Encoding (CBE)
.x3db
(TODO)
|
Efficient X3D Encoding
.x3de
(proposed)
|
X3DJSAIL
.java source using
X3dToJava.xslt
(implemented)
|
| X3D canonical form (implemented as default output format) | XML Canonicalization (C14N) (TODO) |
Shape Resource Container (SRC)
.src
(no longer planned for X3D v4) |
| XML Signature for authentication (TODO) | XML Encryption for confidential access and privacy (TODO) | |
Conversion capabilities continue to grow through multiple exporters and importers.
🔖 Blender
Blender is an open-source 3D authoring tool that includes support for X3D import/export (FreeBSD Linux, MacOSX, Windows) (download).
- TODO, work in progress.
- 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,.wrlVRML97,U3D,COLLADAand others. -
Example invocations in HelloWorldProgram.java:
System.out.println("Blender default path=" + ConfigurationProperties.getBlenderPath()); BlenderLauncher.checkBlenderPath(); System.out.println("Blender.checkBlenderPath() new path=" + ConfigurationProperties.getBlenderPath()); System.out.println("BlenderLauncher.hasBlender()=" + BlenderLauncher.hasBlender()); System.out.println("Blender version=" + BlenderLauncher.getBlenderVersion()); -
Example invocations in
stylesheets/build.xml target="test.X3DJSAIL"TODO
-
Useful references
- Blender and Blender Quickstart Introduction
- 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
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,.wrlVRML,, 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 target="test.X3DJSAIL"<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
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.saiJava 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.jsailpackage 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.InvalidFieldValueExceptionexception is thrown.
🔖
Downloads
X3DJSAIL can be used in any Java project by including one of the following jar files in the application CLASSPATH.
- X3DJSAIL.3.3.full.jar (30MB) is a fat jar with all necessary binaries, source, and documentation.
- X3DJSAIL.3.3.classes.jar (12MB) is a minimalist jar that only contains X3DJSAIL classes and assets.
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.
- CreateX3dSceneAccessInterfaceJava.xslt stylesheet
- stylesheets/java/ directory holds stubs and deployment files
🔖
Examples
Initial codebase development is building out features in a single example "smoke test" program for comprehensive testing.
- HelloWorldProgram.java source code that exercises the X3D Java SAI Library (console output)
- Program-generated X3D model, ClassicVRML model, VRML97 model and JSON encoding
- X3DOM scene page, X_ITE scene page, console output, screenshot image and movie
- Concise program-produced java source to produce the resulting scene graph: HelloWorldProgramOutput.java
- Load the produced scene HelloWorldProgramOutput.x3d (validator) using X3DLoaderObject, then write resulting DOM back out to HelloWorldProgramOutput.ReloadedDOM.x3d (validator)
- Stylesheet-generated pretty-print X3D model documentation
- Experimental HelloWorldProgramOutput.ReloadedDOM.x3d using X3DLoaderObject
- HelloWorldProgramOutput.java source-code serialization using X3DObject.toFileJava(filename) and X3dToJava.xslt stylesheet.
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
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 Java Implementations
- Xj3D
- FreeWrl
- InstantReality
- BS Contact and BS Contact J
- Others?
🔖
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 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,USEandclassattributes. - 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
TODO: X3dToJava.xslt stylesheet improvements
-
Continued testing and improvement with conversion of
.x3dsource 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/connectsupport, improveProtoInstancehandling without needingcontainerField
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
containerFieldvalues. -
Implement specialty string subtypes such as
ID,IDREF,NMTOKENandNMTOKENS. - 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
appinfoanddocumentationfields. Ensure that specification support for ProtoInstance includesDEF USE IS classandmetadatafields.
TODO: X3DJSAIL source code and capability improvements
- Ongoing. Test X3D scene creation and file serialization using the X3D Examples Archives, together providing over 3900 diverse models for unit testing.
- 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.loggingoptions as alternatives to strict exception throwing. ProvidesConfigurationProperties.debugModeActiveinitializer andConfigurationProperties.setDebugModeActive(boolean),ConfigurationProperties.isDebugModeActive()methods to enable verbose debugging output when desired. -
Method
ConfigurationProperties.setExiEngine(String)
with enumeration constants
EXI_ENGINE_OPENEXIandEXI_ENGINE_EXIFICIENTfor selection between implementations EXIficient (implemented) and Nagasena OpenEXI (TODO) 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 ImageandMatrix*classes (typically adapting source code from the Xj3D implementation). -
Automatically support naming correspondences for
DEFandnamevalues when first constructing HAnim nodes. Include naming checks in each node's self-checkingvalidate()method. -
Consider adding import/export for different file encodings (for example
.stl,.plyand 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
importstatements 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
.classbyte 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 security standards for XML: XML-Signature Syntax and Processing and XML Encryption Syntax and Processing.
- 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.
Warning: note that, by default, creating or decompressing files may overwrite prior versions.
See
ConfigurationProperties.isOverwriteExistingFiles()
and
setOverwriteExistingFiles(newValue)
to modify overwrite permissions.
-
Complete.
Setting X3DJSAIL properties can override default values. See
-
X3DJSAIL.properties.templateand exampleX3DJSAIL.properties -
ConfigurationProperties.PROPERTIES_FILENAME_DEFAULT,ConfigurationProperties.getPropertiesFileName(),ConfigurationProperties.setPropertiesFileName(fileName),ConfigurationProperties.loadProperties(),ConfigurationProperties.isNormalizeCommentWhitespace()
-
-
Complete.
Import loading: ability to load X3D scene-graph files.
-
X3DObject.loadModelFromFileX3D(fileName),X3DObject.loadModelFromFileX3D(x3dFile),X3DObject.replace(newX3DObject) -
X3DObject.fromFileEXI(exiFileName)(using EXIficient; OpenEXI to follow) -
X3DObject.fromFileGZIP(gzipFileName) -
X3DObject.fromFileZIP(zipFileName, modelFileName)
If nomodelFileNameis provided, then the first.x3dmodel encountered in the zip file is returned (if any). -
X3DLoaderObject.loadModelFromFileX3D(fileName),X3DLoaderObject.loadModelFromFileX3D(x3dFile),X3DLoaderObject.getValidationResult() -
X3DLoaderObject.getDomDocument(),X3DLoaderObject.getX3dObjectTree()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
Fileobject if successful. SimilartoStringEncodingandtoStringLanguagemethods are also provided.-
X3DObject.toFileJSON(fileName) -
X3DObject.toFileEXI(resultFileName)(using EXIficient, OpenEXI to follow) -
X3DObject.toFileGZIP(resultFileName) -
X3DObject.toFileZIP(zipFileName,modelName)
-
-
Complete.
Export serialization: XSLT stylesheet support that subsequently converts an intermediate XML X3D scene.
-
Pretty-print HTML documentation
using method
X3DObject.toFileDocumentationHtml(String filename)with stylesheetsSTYLESHEET_htmlDocumentation,STYLESHEET_extrusionCrossSectionSVG -
X3DOM page presentation
using method
X3DObject.toFileX3DOM(String filename)with stylesheetSTYLESHEET_X3DOM -
X_ITE page presentation
using method
X3DObject.toFileX_ITE(String sourceSceneName, String filename)with stylesheetSTYLESHEET_X3DOM(with parameter settings) -
X3D-Tidy
(example)
using method
X3DObject.toFileX3dTidy(String filename)andX3DObject.toStringX3dTidy()with stylesheetSTYLESHEET_X3DTIDY(TODO add parameter settings) -
Model Meta Information to Markdown
using methods
X3DObject.toFileModelMetaMarkdown(String filename)andX3DObject.toStringModelMetaMarkdown()with stylesheetSTYLESHEET_MODEL_META_TO_MARKDOWN -
JSON encoding
using method
X3DObject.toFileJSON(String filename)with stylesheetSTYLESHEET_JSON -
Java language binding
using method
X3DObject.toFileJava(String filename)with stylesheetSTYLESHEET_JAVA -
Choice of XSLT engines, can use method
ConfigurationProperties.setXsltEngine(String filename)withXSLT_ENGINE_saxon(default) orXSLT_ENGINE_nativeJava.
-
Pretty-print HTML documentation
using method
-
Complete.
Demonstrated declarative programming style in
HelloWorldProgram.java
method
createDeclarativeShapeTests().-
Further method-pipelining support provided by chainable utility method
addChild()for nodes implementing theX3DGroupingNodeinterface. This is a big help because SAI-specified interfaces foraddChildren()are required to returnvoid. -
Ancestor-finding Utility methods
.hasAncestorSceneObject()and.findAncestorSceneObject().hasAncestorX3DObject()and.findAncestorX3DObject(),findAncestorProtoBody()andhasAncestorProtoBody(). - 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)andhasAncestorElementByName(ancestorElementName). - Possible future work: autogenerate a subset codebase for X3D CAD Profile (or another profile) tuned for Java Micro Edition/Android use.
-
Further method-pipelining support provided by chainable utility method
-
Complete.
For convenience add
containerField_DEFAULTto each node, as well as a handful ofcontainerField_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,ISandconnect. -
All value handling is now strongly typed for
fieldObjectandfieldValueObject. -
Complete.
Add type and accessType checking of
ROUTEfields usingROUTEObject.validate()method. -
Complete.
Add a subtree-walking
X3DObject.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
DEFandUSEattributes. Follow up with related specification issues for abstract SAI and corresponding encoding specifications. -
Complete.
Add
classattribute 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
DEFname for immediate identification when creating a new node. -
Complete.
Add support for concrete
SFNodeandMFNodeinstantiation. Add booleanhasSomeFieldName()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/setChildrenand related accessor methods. - Complete. Check node types and min/max range values, throw exceptions before setting fields incorrectly.
-
Complete.
Convert concrete arrays to
ArrayListdata structures. -
Complete.
Add
ConfigurationPropertiesserialization 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, usingCommentsBlockclass. -
Complete.
Add support for numerous hexadecimal
0xRRGGBBinteger colors (through defined constants and utility methods) toSFColorObjectand related classes. -
Complete.
Add string constants that name each field eligible for
ROUTEconnections, e.g.OrientationInterpolatorObject.toField_SET_FRACTIONandOrientationInterpolatorObject.fromField_VALUE_CHANGED. -
Complete.
Utility methods
getFieldType(fieldName)andgetAccessType(fieldName)for each X3DConcreteElement -
Complete.
Add
conversionFactor convenience constants
for
unitstatement scale factors. -
Complete.
Default
toStringX3D()serialization-output settings support X3D canonical form, withConfigurationPropertiesproviding additional settings for showing defaultattribute=valuepairs. Thus additional X3D Canonicalization (C14N) integration is no longer needed. -
Complete.
Utility methods
headObject.getMetaByName(metaName)getComponentByName(componentName)andgetUnitByName(unitName),ScriptObject.findFieldByName(fieldName)(also forComposedShaderObject,ShaderPartObjectandShaderProgramObject), andProtoInstanceObject.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)andcleanupEnumerationValue(values). -
Complete.
Added run-time checks to ensure
acceptableNodeTypesrestrictions are met for operations onchildrennodes, such asViewpointGroupObject. -
Complete.
Scene-graph construction and run-time checks for
IMPORTObjectandEXPORTObject. -
Complete.
Add
ConfigurationProperties.setValidationExceptionAllowedto set whether partial results are allowed if validation exception occurs when serializing scene output. Can be useful technique for debugging,validationExceptionAllowed_DEFAULTvalue is false for strict operation. - Complete. Add X3D profile-validation and component-validation checks.
-
Complete.
Utility methods
X3DConcreteNode.isNode(),X3DConcreteStatement.isStatement()andCommentsBlock.isStatement() -
Complete.
ExtrusionObjectutility methodsisCrossSectionClosed(),isSpineClosed()andtoFileSvgCrossSection(fileName) -
Complete.
X3D Regular Expression (regex)
support in field types, for example SFVec3fObject
REGEXstring,pattern,validate(),matches()andmatches(String value). -
Complete.
SFImage support for
SFColorObject.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 forMF/SFImage.toString(),.toStringHexadecimal()and.toStringDecimal(). -
Complete.
X3D Regular Expression (regex)
support for special types, for example
SFVec3fObject.matchesBboxSizeType(String value). - Complete. Provide annotation descriptions for abstract node types in XML Schema.
- Complete. In addition to allowed node types, permit setting ProtoInstanceObject as part of MFNode field arrays.
🔖
Contact
Updated 13 October 2018.
X3D Java Scene Access Interface Library (X3DJSAIL) deployed release version is available online at
http://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).