AC3D Loader

Ac3dLoader is an implementation of the Java 3D Loader interface that is capable of loading model information from an AC3D file. This allows the developer to incorporate geometric data modeled in the AC3D file into their own Java programs using the Java 3D API. This loader does not support loading behavior, since the AC3D modeling tool and file format do not provide facilities for scripting automated behavior (such as animation). More information on AC3D can be found at the AC3D home page listed at the end of this page.

This loader only handles models generated with AC3D 3.0 or greater.

Code Outline

Parsing

For the parser implementation, the command pattern was chosen to mimic the token representation. Commands are implemented in a TokenHandler object that is registered with the parser during setup. This effectively decouples the parser from the data processing logic, since the parser has no awareness of the either the tokens or their associated command implementation. As long as the general structure of the file format does not change, implementing new TokenHandler instances should accommodate any future updates or needs without requiring modification to the parser. Additionally, introspection is used to provide the token-to-command mapping automatically in the TokenHandler base class. This reduces the amount of code required to implement a TokenHandler, since this eliminates the need to provide specialized handling code for each new TokenHandler implementation. (It also eliminates the need to stub code for unimplemented commands, since they are just ignored if a method to command mapping cannot be determined by the introspection handler.)

The UML outline of the classes involved in the parser process

The above diagram illustrates the relationship between the Ac3dParser and the TokenHandler instances. Upon registration of the TokenHandler with the Ac3dParser instance, versioning information is checked to ensure that the parser is compatible with the given token handler. (Ac3dParser also verifies the file is of the supported version when it parses the header, too.) This is statically done now, and a better approach would be to allow multiple LineTokenizer versions to support multiple file format versions. (This implies that the Ac3d file header will always be consistent.)

LineTokenizer performs the work of extracting all of the tokens contained within a line from an Ac3d file. Once the header is processed, LineTokenizer steps through the file line by line. For each command token (which is usually the first word in the line), the registered TokenHandler’s handle() method is invoked with the parsed data. This cycle continues until the end of the file is reached.

The TokenHandler base class contains the implementation of the handle() method. This is convenient, because all subclasses that extend TokenHandler are not responsible for handling commands when they are issued. (As mentioned earlier, this is accomplished by introspection.)

Three models were chosen to map the geometry: Ac3dMaterial, Ac3dObject, and Ac3dSurface. All three classes are simply modeling beans, with accessors and mutators for accessing their properties. Ac3dMaterial models the physical properties of an object. This includes lighting, color, and so on. Ac3dObject generally models a grouping. This can be a collection of other Ac3dObject or Ac3dSurface instances. This is where transformation and translation is usually applied, as well as texture information.

The UML outline of the classes involved in the model loading process

Ac3dTokenHandlerBase is where the command and data tokens are converted into a data model. This is an abstract class, since it does not do anything meaningful with the models once they are constructed. The modeling objects are generally acquired by accessing protected members by subclasses that actually use the models. It is important to note that, in order to subclass Ac3dTokenHandlerBase, any subclassed methods must call their superclass method. Otherwise, the overridden method in the superclass will not be called, and the data will not be modeled internally.

Finally, there are a few miscellaneous aspects that haven’t been covered. First, there is an interface in the parsing library called OutputHandler. A user can register an OutputHandler instance if they want to redirect any textual output Ac3dLoader generates. The default for this is ConsoleHandler, which just dumps output to the system console using the System class. Second, there is a support class in the org.j3d.loaders.ac3d.util package called ParserTest that was used during development to verify that the file was being parsed properly. This will dump the model data to the system console using the DebugTokenHandler object.

The Java3D Loader

The UML outline of the classes involved in the loader implementation

Within the Ac3d tool, it is possible to assign groups of points and surfaces a human text name. This name is maintained during the parsing and mapping of generic to Java 3D specific objects. This is useful when a developer wants to perform some sort of manipulation of the rendering tree at a given branch. (For example, to add behavior.)

To allow branch manipulation, the scene not compiled prior to return. Although this yielded a much more optimized structure, it effectively removed the ability to modify the structure. Compilation has subsequently been removed to allow the individual the most flexibility when using the library. The downside is that the user needs to manually force a recompile if you have no intentions of changing the scene graph at a later time after loading.

Known Bugs and Limitations

• Introspection implementation is not fast. Currently, the introspection occurs on each command invocation. This is not very efficient, and a more optimal solution is to create a hash table mapping command names to methods when the class is loaded. (I.e., in the static initialization block.)
• Geometry construction should be reviewed. Smooth surfaces aren’t facilitated, even when the crease angle is set. A sanity check is probably in order.
• Only supports texture maps in format supported by JDK Toolkit. Even though the Ac3d format specifies that the RGB file format is to be used for storing and loading textures, the loader does not support file formats outside of those readable by the JDK Toolkit. This is because the loader delegates the work of loading images to the Toolkit.

Other References

• AC3D Homepage This is the home page for the AC3D modeling tool. It is available for many different platforms, including Windows, Linux, and Solaris. There is a lot of very useful information contained within these pages pertaining to the use of AC3D, as well.
• AC3D File Format Specification