Skip to content

Latest commit

 

History

History
252 lines (190 loc) · 10.1 KB

ReadMe.md

File metadata and controls

252 lines (190 loc) · 10.1 KB
Raw

ijp-dcraw

Scala CI Maven Central Javadoc

ijp-dcraw provides ImageJ plugin "DCRaw Reader" to open raw images from digital cameras. Originally the backend was provided by dcraw tool. Current versions is using LibRaw/dcraw_emu tool. The hundreds of supported cameras are listed on LibRaw Supported Cameras page.

There are two plugins:

  • DCRaw Reader - reads images in camera raw format
  • DCRaw Identify - provides info about the raw image, like camera make and metadata contained in the raw file
  • DCRaw Unprocessed - reads mostly unprocessed raw image, it may be still before demosaicing. You may need a plugin like ijp-DeBayer2SX to convert it to a color image.

Image Calibrator

ijp-dcraw distribution, available from Releases page, provides native binaries for Windows and macOS. Binaries for other system can be added manually.

By default, the "DCRaw Reader" plugin looks for the dcraw_emu and raw-identify executables in the subdirectory dcraw of ImageJ plugins folder. Alternative location can be specified by one of:

  1. Setting Java system property dcrawExecutable.path, raw-identifyExecutable.path, and unprocessed_rawExecutable.path to location of the dcraw, raw-identify, and unprocessed_raw executables, for instance:
  -DdcrawExecutable.path=bin/dcraw_emu.exe -Draw-identifyExecutable.path=bin/raw-identify.exe
  1. or adding property .dcrawExecutable.path to ImageJ properties file IJ_Props.txt. Note period at the beginning of property name, it is required by ImageJ. Example line that should be added to IJ_Props.txt
  .dcrawExecutable.path=C:/apps/bin/dcraw_emu.exe
  .raw-identifyExecutable.path==C:/apps/bin/raw-identify.exe
  .unprocessed_rawExecutable.path==C:/apps/bin/unprocessed_raw.exe

Installation

  1. Download ijp-dcraw_plugins_*_win_macos.zip from the Releases page. Binaries, taken from the LibRaw release are provided for Windows and macOS.
  2. Unzip to ImageJ plugins directory. By default, the DCRaw Reader looks for the dcraw_emu and raw-identify executables in the subdirectory "dcraw" of the ImageJ plugins folder.
  3. Restart ImageJ

The plugin installs under Plugins > Input-Output > DCRaw Reader....

Related Plugins

Tips and Tricks

See What Backend Options Passed to dcraw_emu

If you wander what is going on behind the scenes, how dcraw_emu executable is used, you can see the exact command line ij-dcraw is executing by turning on the "Debug Mode". Select in ImageJ menu: "Edit" > "Options" > "Misc" and select " Debug Mode". Now open an image using DCRaw Reader and watch the Log window, it will show the command line with the options used and the output log generated by dcraw_emu.

White Balance Options

DCRaw offers a couple of options for applying white balance to processed raw image. In the backend they are implemented as separate options. In the front end we try to bring some consistency and clarity. The front end provides following white balance options:

  • Disable - force not to use any white balance - all channels are scaled the same way. This is the same as command line option -r 1 1 1 1 (white balance multiplier set to 1 for all channels). This useful to for best preservation of the raw image data, for instance, when multiple images need to be compared.
  • Derived - white balance multipliers are derived from the color conversion matrices embedded in the raw image metadata. This is done without utilizing the information about camera recorded white balance. This is the default behaviour of DCRaw. This option was in the past called "None". The name was changes as could indicate all channels have the same multipliers. You can see what are the channel multipliers using the "Raw Identify" with the "verbose" option. In the output look to an entry named "Derived multipliers". It maybe at the very end of the output and look something like this: 
    Derived D65 multipliers: 2.441519 0.995024 1.658339
    This may recover manufacturers "default white balance" for the camera, but in some cases may lead to issues, like image saturation (in example above the red channel is multiplied significantly more than other channels and may get saturated for bright pixels)
  • Camera - use white balance coefficients recorded by the camera. They also can be seen using the "Raw Identify" plugin.
  • Averaging - compute white balance multiplier by averaging the entire image.

Sample ImageJ macro for batch image conversion

Example of using "DCRaw Reader" plugin from an ImageJ macro. The macro converts all images in an input directory, assumed to be some supported raw format, to TIFF saved in the output directory. The source code for the macro is located in macros/Batch_convert_dcraw.ijm.

//Get File Directory and file names
dirSrc = getDirectory("Select Input Directory");
dirDest = getDirectory("Select Output Directory");
fileList = getFileList(dirSrc);
caption = "dcraw batch converter";

print(caption + " - Starting");
print("Reading from : " + dirSrc);
print("Writing to   : " + dirDest);

// Create output directory
File.makeDirectory(dirDest);

setBatchMode(true);
fileNumber = 0;
while (fileNumber < fileList.length) {
    id = fileList[fileNumber++];

    print(toString(fileNumber) + "/" + toString(fileList.length) + ": " + id);

    // Read input image
    run("DCRaw Reader...",
        "open=" + dirSrc + id + " " +
        "use_temporary_directory " +
        "white_balance=[Camera white balance] " +
        //            "do_not_automatically_brighten " +
        "output_colorspace=[sRGB] " +
        "read_as=[8-bit] " +
        "interpolation=[DHT] " +
        //            "half_size " +
        //            "do_not_rotate " +
        "");
    idSrc = getImageID();

    // Save result
    saveAs("Tiff", dirDest + id);

    // Cleanup
    if (isOpen(idSrc)) {
        selectImage(idSrc);
        close();
    }
}
print(caption + " - Completed");

Using ij-dcraw directly from Java

Example of using DCRawReader API from a Java code. The source code is located in src/test/java/demo/DCRawReaderDemo.java.

import ij.ImagePlus;
import ij_plugins.dcraw.DCRawException;
import ij_plugins.dcraw.DCRawReader;

import java.io.File;

class DCRawReaderDemo {

    public static void main(String[] args) throws DCRawException {

        final File inFile = new File("../test/data/IMG_5604.CR2");
        final ImagePlus imp = new DCRawReader().read(inFile);
    }
}

Using low-level API to call DCRaw

You can also call dcraw by passing command line options. This may give access to some functionality that may not be yet exposed through higher level DCRawReader API.

import ij.IJ;
import ij.ImagePlus;
import ij_plugins.dcraw.DCRawException;
import ij_plugins.dcraw.util.ExecProxy;

import java.io.File;
import java.util.Optional;

import static ij_plugins.dcraw.IJPUtils.isBlank;

/**
 * Example of calling dcraw executable directly, passing command native line options
 */
public class DCRawExecProxyDemo {
    public static void main(String[] args) throws DCRawException {
        // Input file
        final File inFile = new File("../test/data/IMG_5604.CR2");

        // Output file that will be generated by dcraw
        final File outputFile = new File(inFile.getAbsolutePath() + ".tiff");

        // dcraw wrapper
        final ExecProxy proxy = new ExecProxy("dcraw_emu", "dcrawExecutable.path",
                Optional.of(m -> System.out.println("status: " + m)),
                Optional.of(m -> System.out.println("error : " + m)));

        // Execute dcraw
        ExecProxy.Result r = proxy.executeCommand(new String[]{
                "-v",      // Print verbose messages
                "-q", "0", // Use high-speed, low-quality bilinear interpolation.
                "-w",      // Use camera white balance, if possible
                "-T",      // Write TIFF instead of PPM
                "-j",      // Don't stretch or rotate raw pixels
                "-W",      // Don't automatically brighten the image
                inFile.getAbsolutePath()});

        System.out.println("dcraw_emu stdErr: '" + r.stdErr + "'");
        System.out.println("dcraw_emu stdOut:\n" + r.stdOut);

        if (isBlank(r.stdErr)) {
            // Load converted file, it is the same location as original raw file but with extension '.tiff'
            final ImagePlus imp = IJ.openImage(outputFile.getAbsolutePath());
            System.out.println("Loaded converted raw file: " + imp.getWidth() + " by " + imp.getHeight());
        }
    }
}

Notes

ijp-dcraw project was originally hosted on SourceForge. Releases 1.5 and older can be found there.