to X3D Resources

X3D Java Scene Access Interface Library (X3DJSAIL)

to Web3D home page

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

Abstract | Codebase | CLASSPATH and Command Line | 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 to top

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

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.

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

This library successfully supports multiple purposes:

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 to top

X3DJSAIL binaries are compatible with Java 1.8 and greater. X3DJSAIL source is compiled and tested under OpenJDK 22.0.1 (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.

🔖 CLASSPATH and Command Line to top

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

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

🔖 Configuration Properties to top

Setting X3DJSAIL properties can override default library values. See

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

🔖 Conversions to top

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

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

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

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

🔖 Blender Conversions to top

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

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.

🔖 MeshLab Conversions to top

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.

🔖 Design Features to top

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

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

The following software-architecture principles have influenced codebase design.

🔖 Downloads to top

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

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

🔖 Errors and Exceptions to top

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:

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:

🔖 Examples to top

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.

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

🔖 Efficient XML Interchange (EXI) Compression to top

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

  EXIficient GUI: to execute, save and launch .jar file (requires Java installed)

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

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

EXI References

🔖 Other X3D Java Implementations to top

Additional X3D Java implementations are also available.

🔖 References and Relevant X3D Specifications to top

🔖 Specification Changes under Consideration to top

🔖 TODO Planned and Completed Work to top

TODO: priority goals to keep pace with community needs

TODO: X3dToJava.xslt stylesheet improvements

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

TODO: X3DJSAIL source code and capability improvements to top

🔖 Utility Methods and Functionality to top

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

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.

🔖 Contact to top

Updated: 5 May 2024
X3D Java Scene Access Interface Library (X3DJSAIL) deployed release version is available online at
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 X3D.
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).