Manual

1. Overview

jrawio is a Service Provider Implementation for the Java™ ImageIO API. It provides the ability to read images coded in a digital "camera raw" format (such as NEF for Nikon or CRW/CR2 for Canon). It is to be pointed out that jrawio is implemented in 100% pure Java™. jrawio is an opensource product distributed under the MIT license.

The Java™ ImageIO API (java.sun.com/j2se/1.4.2/docs/guide/imageio) is an API which provides the ability to read and write images stored with different type of protocols (such as TIFF, JPEG, PNG and so on). The architecture of the ImageIO API is modular: programmers use a fixed, portable high-level API to control the load and store operations, while a set of "drivers" (called Service Provider Implementations, SPI) deal each one with a specific protocol. This solution enables the programmers to develop their imaging application abstracting storage details; moreover, an existing application can be augmented to deal with a new type of image files by just installing a new SPI.

If you ever heard of nefIO, jrawio is basically the same stuff. When we wrote nefIO we were focused only on Nikon NEF format, while jrawio scope is broader. Basically we want to support every format around, provided that people provide us with image samples or technical documentation.

2. Supported formats and cameras

jrawio is presently a Release Candidate for v1.0, so it's coming out of beta stage. Please refer also to the Release Notes for information about issues.

It has been tested with about 8,000 photos taken with Nikon D100 and D70 cameras and with about 250 samples of various cameras downloaded from the web. jrawio has been explicitly tested with the following models:

Maker Format Model
Canon CR2 Digital Rebel, EOS 1D MkII, EOS 1Ds MkII, EOS 350D
Canon CRW D30, EOD 10D, EOS 300D
Leica DNG R8, R9
Minolta MRW DiMAGE 5, DiMAGE 7i, DiMAGE 7Hi
Nikon NEF CoolPix 5400, CoolPix 5700, CoolPix 8700, CoolPix 8800, D1, D100, D1X, D200, D2H, D2X, D50, D70, D70s
Pentax PEF *ist D, *ist DL, *ist DS
Sony SRF F828
If you are interested in using jrawio with some files from a supported format, but produced by an untested camera, please contact us and provide some samples. We will work to fix the problem as soon as possible.

Please consider submitting your samples also to the RAWpository, a shared collection of camera raw sample files. This could be useful for other open source developers around the world.

3. Project website and tracking

The home page for this project is:

    jrawio.dev.java.net

All the tracking information about the project (issues, bugs, road map) is avaiable at:

    www.tidalwave.it/bluemarine/tracker/browse/JRW

4. Post-processing the raster

Photos read with the jrawio plugin will appear dark and greenish (so dark that most of them could look black). This is because by default jrawio delivers the raw data straight from the camera sensor.  As per the Camera Raw file specifications, these data need a heavy post-processing in order to be transformed in a display-ready color.

The official release of jrawio does not provide post-processing capabilities, which will be added with version 1.5, due to be released for the first half of 2006. Anyway an early-access post-processing engine is already available. It is named RAWProcessor and can be downloaded from the "Documents & Files" section. Read more about the RAWProcessor here.

5. Using jrawio and running the provided example

To use jrawio just place its jar file in the classpath of your application - no further action is needed and your application wil be able to open raw files by means of javax.imageio.ImageIO methods. As jrawio is still beta, you could find some bugs - just notify us about them. Some bugs related to integration with other applications have been already identified and quickly fixed.

In the directory examples there is a simple Java application that lets the user select an image file and shows it in a very simple viewer. The user can see the raw bitmap, the thumbnail(s) if present and the metadata (in XML format).

To compile the example:

    javac Main.java

To run the example:

    java -Xmx512M -cp jrawio-1.0.RC5.jar:. Main

Note that the example code is completely independent of jrawio, as it should be - it only uses standard Java™ ImageIO code.

Specifying a sufficient amount of memory might be required for large images. Remember that a 12 megapixels raw image needs 72+ megabytes of RAM!

If you want to run the example with the RAWProcessor enabled, use this command line:

    java -Xmx512M -cp jrawio-1.0.RC5.jar:reajent-xxx.jar:. Main

where xxx should be replaced with the version of the RAWProcessor you're using (make sure it's compatible with the jrawio version you're using).

6. Non standard classes

jrawio defines several subclasses of IIOMetadata for the different formats it supports. These are internal classes and are not part of the official API. There is no guarantee that they won't change in future - they could even be dropped or completely redesigned.

The standard way to access metadata is with XML, retrieved by the method getAsTree() as in the following example:

File file = new File(...);
imageReader.setInput(ImageIO.createImageInputStream(file));
IIOMetadata metadata = imageReader.getImageMetadata(0);
Node node = metadata.getAsTree(metadata.getNativeMetadataFormatName());


 

7. Documentation about RAW Formats

There are many pieces of documentation about RAW formats around the internet. As a spin-off of jrawio project a comprehensive documentation is being written at www.tidalwave.it/cameraraw