https://github.com/ij-plugins/ijp-dcraw
ImageJ plugin to open camera raw images using dcraw
https://github.com/ij-plugins/ijp-dcraw
Last synced: 10 months ago
JSON representation
ImageJ plugin to open camera raw images using dcraw
- Host: GitHub
- URL: https://github.com/ij-plugins/ijp-dcraw
- Owner: ij-plugins
- Created: 2021-08-13T01:08:34.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-05-16T23:56:50.000Z (about 3 years ago)
- Last Synced: 2023-09-07T18:20:53.280Z (almost 3 years ago)
- Language: Java
- Homepage:
- Size: 25.9 MB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: ReadMe.md
Awesome Lists containing this project
README
ijp-dcraw
=========
[](https://github.com/ij-plugins/ijp-dcraw/actions/workflows/scala.yml)
[](https://maven-badges.herokuapp.com/maven-central/net.sf.ij-plugins/ijp_dcraw)
[](https://javadoc.io/doc/net.sf.ij-plugins/ijp_dcraw)
`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.
`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
```
2. 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
---------------
* [ijp-color] Contains plugin [IJP Color Calibrator] that can be used to color calibrated raw images. For instance, it
works well with "16-bit linear" images.
* [ijp-DeBayer2SX] an alternative way to demosaic raw images
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].
```javascript
//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].
```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.
```java
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][SourceForge].
[dcraw]: https://en.wikipedia.org/wiki/Dcraw
[LibRaw]: https://www.libraw.org/about
[LibRaw Supported Cameras]: https://www.libraw.org/supported-cameras
[Releases]: https://github.com/ij-plugins/ijp-dcraw/releases
[SourceForge]: http://ij-plugins.sourceforge.net/plugins/dcraw/index.html
[ijp-color]: https://github.com/ij-plugins/ijp-color
[ijp-DeBayer2SX]: https://github.com/ij-plugins/ijp-DeBayer2SX
[IJP Color Calibrator]: https://github.com/ij-plugins/ijp-color/wiki/Color-Calibrator
[macros/Batch_convert_dcraw.ijm]: https://github.com/ij-plugins/ijp-dcraw/blob/master/macros/Batch_convert_dcraw.ijm
[src/test/java/demo/DCRawReaderDemo.java]: https://github.com/ij-plugins/ijp-dcraw/blob/master/src/test/java/demo/DCRawReaderDemo.java