Introduction
Chalice (version 1.2 or greater) allows developers to write plugins for its image I/O architecture. Developers are given access to the following features:
- Read/Write of N channel images
- 8 bit, 16 bit, and floating point data types
- Region of interest reads
- Line (or lines) at a time writes
- Format specific parameters
- Automatic filetype determination
This document attempts to give a developer all the information she needs to develop an image I/O plugin for Chalice. It also has some information on the TIFF implementation distributed with Chalice.
Important Note
In looking at the various header files and library functions provided with the Chalice distribution, you may notice that there is much more to the library than is documented here. Chalice's plugin I/O architecture is based on the ImFiles library created by GW Hannaway & Associates. The library has many features that are NOT used by the Chalice software. Only the features that are used by Chalice are documented here.
Overview
The ImFiles library is a C++ class hierarchy to which the developer will need to add two new classes. These classes will be combined into a DSO that will be runtime loaded into Chalice on startup and will make the new Image file format available to Chalice users.
ImFiles Classes
- Im
- This is the base class for ImFiles image pipeline architecture. It defines all the basic types and methods that are used throughout the rest of the hierarchy.
- ImFile
- This is a subclass of Im. It provides the basic association of an actual file with an Im. The header file 'ImFile.h' also provides the definition of ImFileMaker.
- ImFmt
- This class is a subclass of ImFile and provides some helper methods that may be useful in writing format plugins.
- ImFileMaker
- This class is used to construct new ImFile objects in a non class-specific way. You may think of it as a virtual constructor class. ImFileMaker also provides helper functions for dealing with file format options and other details.
- ImOpt
- This class provides descriptions of format options and acts as the database for the options' current values.
- ImSpecs
- This class provides the in-memory database of information about an image, including bit depth, data type, size in pixels, number of channels, etc. It is used by Im to keep track of this information.
- Im::SubArea
- The SubArea defines the portion of the image to be read or written. It can define many operations that are NEVER used by the Chalice software. A basic definition is always used.
Writing the ImFiles plugin
What follows is a list of the parts of an ImFiles plugin. You will want to
look at the sample formats that are shipped with Chalice for examples. These
are ImCdi (Chalice Direct Image) and ImTiff implementations.
ImFile sublcass
Your plugin DSO must contain a class subclassed off of ImFile (or ImFmt). In this class, you must define the following methods:
- Constructor for reading the file
- This constructor is used when reading an existing file.
- Constructor for writing the file
- This constructor is used when writing a new file.
- read(const SubArea &area, void *buffer)
- Reads the region defined by area into buffer. The buffer must be big enough to hold all of the image described by area. The file must be open for reading.
- write(const SubArea &bufArea, void *buffer, const SubArea &outArea)
- Writes buffer to the region specified by outArea. The buffer must contain all the data to be written. When used with Chalice, bufArea can be safely ignored. Only works on files opened for writing.
- cleanUp( ) (optional)
- After all reading or writing has been done on a file, cleanUp is called to do any final writes or other misc stuff to the file. Normally, this would be done by the destructor, but a destructor cannot return an error.
- getClassName( )
- getFormatName( )
- Return className and formatName respectively as defined below.
You must also define the following static class members:
- const char *className
- A string containing the class name. For instance the Adobe Photoshop format class is called "ImPhoto".
- const char *formatName
- A string containing a readable format name. For instance the Adobe Photoshop format class is called "Adobe Photoshop". This is what will be displayed in all menu and option tabs.
ImFileMaker subclass
Also in the DSO plugin, there must be a class subclassed off of ImFileMaker. In the subclass you should define the following methods.
- Constructor
- There are a pre-defined number of things that need to be done in this constructor.
- openIt for reading
- This function creates a new Im for reading a file of this type.
- openIt for writing
- This function creates a new Im for writting a file of this type.
- getFormat
- This function gets the format type and basic file information without having to create an Im object to get it. It is used for quick directory scans for files, etc.
- estimateSize
- Though not currently used in Chalice, it will be at some future date. This
extimates the size of the file that will be created given the input size information.
- isExtension (optional)
- This option function looks at a file extention like ".tiff" and returns true if it is associated with this filetype. This is used as a hint, not as the determining characteristic.
See ImCdi.[Ch] ImTiff.[Ch] for details on the implementation.
Once you are able to compile your new format, you will need to copy it to
the /usr/grail/chalice1.X/formats directory. That way Chalice can
automagically find your format and add it to it's format list. Before you
try running your format in Chalice, we recommend that you use ioharness
to test your format.