Support disabling white balance (any uneven by-channel scaling) #15

ReadMe.md

@@ -2,6 +2,8 @@ ijp-dcraw
 =========
 
 [![Scala CI](https://github.com/ij-plugins/ijp-dcraw/actions/workflows/scala.yml/badge.svg)](https://github.com/ij-plugins/ijp-dcraw/actions/workflows/scala.yml)
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.sf.ij-plugins/ijp_dcraw/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.sf.ij-plugins/ijp_dcraw)
+[![Javadoc](https://javadoc.io/badge2/net.sf.ij-plugins/ijp_dcraw/javadoc.svg)](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
@@ -14,13 +16,16 @@ There are two plugins:
 
 ![Image Calibrator](assets/DCRaw_Reader_Dialog.png)
 
-`ijp-dcraw` distribution, available from [Releases] page, provides native binaries for Windows and macOS. Binaries for other
+`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.
+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` and `raw-identifyExecutable.path` to location of the `dcraw` and `raw-identify` executables, for instance:
+1. Setting Java system property `dcrawExecutable.path` and `raw-identifyExecutable.path` to location of the `dcraw`
+   and `raw-identify` executables, for instance:
 
   ```
     -DdcrawExecutable.path=bin/dcraw_emu.exe -Draw-identifyExecutable.path=bin/raw-identify.exe
@@ -39,7 +44,8 @@ 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
+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
 
@@ -62,6 +68,31 @@ ij-dcraw is executing by turning on the "Debug Mode". Select in ImageJ menu: "Ed
 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,

notes/v.1.7.0.md

@@ -1,24 +1,42 @@
 v.1.7.0
 ========
 
-New features:
+### Breaking changes:
+
+* Due to confusion about how the white balance is applied by RCRaw, the name of the white balance option "None" was
+  changed to "Derived", and new option "Disable" was added. See a more detailed description in project documentation
+  section [White Balance Options](https://github.com/ij-plugins/ijp-dcraw#white-balance-options) and Issue [#15]
+
+### New features:
+
 * Read raw metadata using 'raw-identify' tool [#7]
 * Friendlier API for using DCRawReader from Java [#11]
 * Improve Java 8 binary compatibility [#12]
 * DCRaw Reader supports image flipping options [#14]
+* Support disabling by-channel scaling [#15] - added as disabling of white balance
+
+### Bug fixes:
 
-Bug fixes:
 * Some runtime errors are not show to the user [#13]
 
-Plugin 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` binary in the subdirectory "dcraw" of the ImageJ plugins folder.
+### Plugin 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` binary in the
+   subdirectory "dcraw" of the ImageJ plugins folder.
 3. Restart ImageJ
 
 [LibRaw]: https://www.libraw.org/about
 
 [#7]: https://github.com/ij-plugins/ijp-dcraw/issues/7
+
 [#11]: https://github.com/ij-plugins/ijp-dcraw/issues/11
+
 [#12]: https://github.com/ij-plugins/ijp-dcraw/issues/12
+
 [#13]: https://github.com/ij-plugins/ijp-dcraw/issues/13
-[#14]: https://github.com/ij-plugins/ijp-dcraw/issues/14
+
+[#14]: https://github.com/ij-plugins/ijp-dcraw/issues/14
+
+[#15]: https://github.com/ij-plugins/ijp-dcraw/issues/15

src/main/java/ij_plugins/dcraw/DCRawReader.java

@@ -31,6 +31,7 @@
 import java.nio.file.Files;
 import java.nio.file.StandardCopyOption;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Optional;
 
@@ -50,7 +51,7 @@ public final class DCRawReader {
      */
     public static class Config {
         /**
-         * White balance to use: none, camera, averaging (-w, -a)
+         * White balance to use: disable (-r 1 1 1 1), none, camera (-w), averaging (-a)
          */
         public WhiteBalanceOption whiteBalance = WhiteBalanceOption.CAMERA;
         /**
@@ -222,16 +223,16 @@ private List<String> buildCommandLine(final Config config, final File actualInpu
         // Command line components
         final List<String> commandList = new ArrayList<>();
 
-        // Turn on verbose messages
+        // Turn on verbose messages (-v repeated for increased verbosity)
+        commandList.add("-v");
+        commandList.add("-v");
         commandList.add("-v");
 
         // Convert images to TIFF (otherwise DCRAW may produce PPM or PGM depending on processing)
         commandList.add("-T");
 
         // White balance
-        if (!config.whiteBalance.getOption().trim().isEmpty()) {
-            commandList.add(config.whiteBalance.getOption());
-        }
+        commandList.addAll(Arrays.asList(config.whiteBalance.getOption()));
 
         // Brightness adjustment
         if (config.doNotAutomaticallyBrightenTheImage) {
@@ -311,14 +312,15 @@ private static String toProcessedFileName(final String rawFileName) {
     }
 
     public enum WhiteBalanceOption {
-        NONE("None", ""),
-        CAMERA("Camera white balance", "-w"),
-        AVERAGING("Averaging the entire image", "-a");
+        DISABLE("Disable", new String[]{"-r", "1", "1", "1", "1"}),
+        DERIVED("Derived", new String[0]),
+        CAMERA("Camera white balance", new String[]{"-w"}),
+        AVERAGING("Averaging the entire image", new String[]{"-a"});
         private final String name;
-        private final String option;
+        private final String[] option;
 
 
-        WhiteBalanceOption(final String name, final String option) {
+        WhiteBalanceOption(final String name, final String[] option) {
             this.name = name;
             this.option = option;
         }
@@ -330,7 +332,7 @@ public static WhiteBalanceOption byName(final String name) {
             throw new IllegalArgumentException("WhiteBalanceOption has no value with name '" + name + "'.");
         }
 
-        public String getOption() {
+        public String[] getOption() {
             return option;
         }