![]() |
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 | Command Line | Conversions | Design Features | Downloads | Examples | Javadoc | License | Other Implementations | README | References | Specification Changes | TODO | Utility Methods | Contact
X3DJSAIL, the X3D Java Scene Access Interface Library is a set of strongly typed Java application programming interfaces (APIs) providing programmer access to an X3D scene graph. Two open-source Java packages are included that contain X3D SAI interfaces and support the X3D Standards for Java programmers.
org.web3d.x3d.jsail provides concrete implementation-oriented classes for building X3D scenes using standalone Java objects.
org.web3d.x3d.sai contains standard X3D SAI interfaces to independently compile Script-node source for use in X3D players.
Available products include Examples, Javadoc, source code, build classes and draft specification annexes for node interfaces and 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.
Multiple uses are intended for these libraries.
This work implements the X3D Unified Object Model (X3DUOM) in support of full and emerging X3D Specification capabilities.
version 1.0 release 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.
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.
Command line invocation is feasible through use of the org.x3d.jsail.CommandLine class.
java -classpath path/X3DJSAIL.3.3.full.jar [sourceModel.x3d | -help | -page | -resources | -tooltips]
[-tofile [resultFile.*]]
[-validate | -toX3D | -toXML | -toClassicVrml | -toJSON | -toVRML97 | -toX3DOM | -toX_ITE]
Example:
java -classpath path/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine -help
Example:
java -classpath path/X3DJSAIL.3.3.full.jar org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toVRML97 -toFile
X3DJSAIL.3.3.classes.jar
plus
Saxon stylesheet engine
saxon9he.jar
Example CLASSPATH confirmation: % 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'
Alternative CLASSPATH configuration: % echo $CLASSPATH
CLASSPATH='C:\x3d-code\www.web3d.org\x3d\stylesheets\java\jars\X3DJSAIL.3.3.full.jar'
java org.web3d.x3d.jsail.CommandLine [sourceModel.x3d | -help | -page | -resources | -tooltips]
[-tofile [resultFile.*]]
[-validate | -toX3D | -toXML | -toClassicVrml | -toJSON | -toVRML97 | -toX3DOM | -toX_ITE]
Example:
java org.web3d.x3d.jsail.CommandLine -help
Example:
java org.web3d.x3d.jsail.CommandLine HelloWorld.x3d -toClassicVRML
Model validation is always performed as part of X3DJSAIL operations.
Conversion capabilities continue to grow through multiple exporters and importers. Current and planned support is shown in the following table.
| Import loading | ||
X3D XML
encoding .x3d
(implemented)
|
X3D ClassicVRML
encoding .x3dv
|
X3D VRML97
encoding .wrl
|
X3D JSON
encoding .json
(work in progress)
|
.stl
and
.ply
geometry import
|
|
| 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)
|
X3D Compressed Binary Encoding (CBE)
.x3db
|
Efficient XML Interchange (EXI)
.exi
|
Efficient X3D Encoding
.x3de
|
| X3D canonical form (default output format) | XML Canonicalization (C14N) |
Shape Resource Container (SRC)
.src (once available)
|
| XML Signature for authentication | XML Encryption for confidential access and privacy |
X3DJSAIL
.java source using
X3dToJava.xslt
(implemented)
|
Note that X3D scene graph run-time capabilities are interoperable and functionally equivalent for all X3D file encodings and programming-language bindings.
Success metric: the X3D information model is sufficient to support round-trip conversion of any X3D scene from one encoding to another.
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.
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.
org.web3d.x3d.sai.InvalidFieldValueException exception is thrown.
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 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.
Initial codebase development is building out features in a single example "smoke test" program for comprehensive testing.
DEF, USE and class attributes.
.x3d source models in the
X3D Examples Archive.
IS/connect support,
improve ProtoInstance handling without needing containerField
containerField
values.
ID, IDREF, NMTOKEN and NMTOKENS.
appinfo and documentation fields.
Ensure that specification support for ProtoInstance includes DEF USE IS class and metadata fields.
java.util.logging options as alternatives to strict exception throwing.
Add
ConfigurationProperties
parameter(s) to enable verbose debugging output when desired.
SF/MF Image and Matrix* classes
(typically adapting source code from the Xj3D implementation).
DEF and name values
when first constructing HAnim nodes.
Include naming checks in each node's self-checking validate() method.
.stl and
.ply, others).
Adding native export to this codebase can likely be adapted to X3D SAI codebases in other programming languages.
import statements within autogenerated library source code.
.class byte code with various X3D players.
Utility methods provide additional helpful functionality to X3D Java programmers, going beyond the minimalist required interfaces in the X3D Java SAI specification. Long-term plans include creation (and possibly autogeneration) of a unit-test suite to always ensure that capabilities and features remain working.
File object if successful.
X3DObject.toFileDocumentationHtml(String filename)
and stylesheets
STYLESHEET_htmlDocumentation,
STYLESHEET_extrusionCrossSectionSVG
X3DObject.toFileX3DOM(String filename)
and stylesheet
STYLESHEET_X3DOM
X3DObject.toFileX_ITE(String sourceSceneName, String filename)
and stylesheet
STYLESHEET_X3DOM
(with parameter settings)
X3DObject.toFileJSON(String filename)
and stylesheet
STYLESHEET_JSON
X3DObject.toFileJava(String filename)
and stylesheet
STYLESHEET_JAVA
ConfigurationProperties.setXsltEngine(String filename)
with
XSLT_ENGINE_saxon
(default) or
XSLT_ENGINE_nativeJava.
createDeclarativeShapeTests().
addChild()
for nodes implementing the
X3DGroupingNode
interface. This is a big help because SAI-specified interfaces for
addChildren()
are required to return void.
findNodeByDEF(DEFvalue),
findElementByNameValue(nameValue),
findElementByNameValue(nameValue, elementName),
findAncestorElementByName(ancestorElementName)
and
hasAncestorElementByName(ancestorElementName).
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.
ProtoDeclare,
ProtoInterface,
ProtoBody,
ExternProtoDeclare,
ProtoInstance,
IS
and
connect.
fieldObject
and
fieldValueObject.
ROUTE fields using
ROUTEObject.validate()
method.
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.
DEF and USE attributes.
Follow up with related specification issues for abstract SAI and corresponding encoding specifications.
class attribute to Object Model for X3D (OM4X3D).
Follow up with related specification issues for abstract SAI and corresponding encoding specifications.
DEF name for immediate identification when creating a new node.
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).
addChildren/clearChildren
/removeChildren/setChildren and related accessor methods.
ArrayList
data structures.
ConfigurationProperties
serialization support for line indent character and indent increment.
addComments() methods for any node or statement, using
CommentsBlock
class.
0xRRGGBB integer colors (through defined constants and utility methods) to
SFColorObject
and related classes.
ROUTE connections, e.g.
OrientationInterpolatorObject.toField_SET_FRACTION
and
OrientationInterpolatorObject.fromField_VALUE_CHANGED.
getFieldType(fieldName) and getAccessType(fieldName)
for each X3DConcreteElement
unit statement
scale factors.
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.
headObject.getMetaByName(metaName)
getComponentByName(componentName) and getUnitByName(unitName),
ScriptObject.findFieldByName(fieldName) (also for ComposedShaderObject, ShaderPartObject and ShaderProgramObject),
and
ProtoInstanceObject.findFieldValueByName(fieldValueName)
X3DConcreteNode.getNodeByDEF(DEFName)
plus ancestor-finding
.findAncestorSceneObject() and
.hasAncestorSceneObject(),
.findAncestorX3DObject() and
.hasAncestorX3DObject(),
findAncestorProtoBody()
and
hasAncestorProtoBody().
cleanupEnclosingQuotes(singleValue)
and
cleanupEnumerationValue(values).
acceptableNodeTypes restrictions are met for operations on children nodes, such as
ViewpointGroupObject.
IMPORTObject
and
EXPORTObject.
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.
X3DConcreteNode.isNode(),
X3DConcreteStatement.isStatement()
and
CommentsBlock.isStatement()
ExtrusionObject
utility methods
isCrossSectionClosed(),
isSpineClosed()
and
toFileSvgCrossSection(fileName)
Updated 22 October 2017.
X3D Java Scene Access Interface Library (X3DJSAIL) deployed release version is available online at
http://www.web3d.org/specifications/java/X3DJSAIL.html
Test programs, results and autogeneration build scripts are available in Sourceforge version control.
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).