RawPedia - User contributions [en]

Favorites Tab

2019-03-28T13:07:46Z

Sguyader: Corrected a typo: "Favorites" is in plural in the options file

== Introduction ==

RawTherapee 5.6 introduced a new "Favorites" tab, which allows you to list your favorite tools for quick access. Tools listed in the Favorites tab are removed from their tabs of origin.

The Favorites tab is hidden by default, and appears when tools are added to it.

A graphical user interface for easily marking tools as "favorited" is being worked on, but due to time constraints related to the release date, this GUI is not ready for 5.6 and will feature in a future release. For the time being, users who wish to "favorite" specific tools need to do so manually, as described below.

== Usage ==

To add a tool to the Favorites tab:
# Edit the <code>[[File Paths|options]]</code> file in a text editor.
# Locate the <code>Favorites=</code> key in the <code>GUI</code> section.
# Add tools by their code-name (listed below), separated by a semicolon and ending with a semicolon. They appear in the order in which they are listed in the key. For example, to add Exposure, Shadows/Highlights and Resize to the Favorites tab, set the key as follows: <code>Favorites=tonecurve;shadowshighlights;resize;</code>

Tool code-names:

* Exposure
** Exposure - <code>tonecurve</code>
** Shadows/Highlights - <code>shadowshighlights</code>
** Tone Mapping - <code>epd</code>
** Dynamic Range Compression - <code>fattal</code>
** Vignette Filter - <code>pcvignette</code>
** Graduated Filter - <code>gradient</code>
** L*a*b* Adjustments - <code>labcurves</code>

* Detail
** Sharpening - <code>sharpening</code>
** Local Contrast - <code>localcontrast</code>
** Edges - <code>sharpenedge</code>
** Microcontrast - <code>sharpenmicro</code>
** Impulse Noise Reduction - <code>impulsedenoise</code>
** Noise Reduction - <code>dirpyrdenoise</code>
** Defringe - <code>defringe</code>
** Contrast by Detail Levels - <code>dirpyrequalizer</code>
** Haze Removal - <code>dehaze</code>

* Color
** White Balance - <code>whitebalance</code>
** Vibrance - <code>vibrance</code>
** Channel Mixer - <code>chmixer</code>
** Black-and-White - <code>blackwhite</code>
** HSV Equalizer - <code>hsvequalizer</code>
** Film Simulation - <code>filmsimulation</code>
** Soft Light - <code>softlight</code>
** RGB Curves - <code>rgbcurves</code>
** Color Toning - <code>colortoning</code>
** Color Management - <code>icm</code>

* Advanced
*** Retinex - <code>retinex</code>
*** Wavelet Levels - <code>wavelet</code>

* Transform
** Crop - <code>crop</code>
** Resize - <code>resize</code>
*** Post-Resize Sharpening - <code>prsharpening</code>
** Lens / Geometry - <code>lensgeom</code>
*** Rotate - <code>rotate</code>
*** Perspective - <code>perspective</code>
*** Profiled Lens Correction - <code>lensprof</code>
*** Distortion Correction - <code>distortion</code>
*** Chromatic Aberration Correction - <code>cacorrection</code>
*** Vignetting Correction - <code>vignetting</code>

* Raw
** Sensor with Bayer Matrix - <code>sensorbayer</code>
*** Demosaicing - <code>bayerprocess</code>
*** Raw Black Points - <code>bayerrawexposure</code>
*** Preprocessing - <code>bayerpreprocess</code>
*** Chromatic Aberration - <code>rawcacorrection</code>
** Sensor with X-Trans Matrix - <code>sensorxtrans</code>
*** Demosaicing - <code>xtransprocess</code>
*** Raw Black Points - <code>xtransrawexposure</code>
** Dark-Frame - <code>darkframe</code>
** Flat-Field - <code>flatfield</code>
** Raw White Points - <code>rawexposure</code>
** Preprocessing - <code>preprocess</code>

Windows

2018-01-25T13:44:33Z

Sguyader: /* Copy RawTherapee and required DLLs */

This guide documents how to build RawTherapee for 32-bit or 64-bit versions of Windows using the MinGW-w64 runtime. Begin by installing and updating MSYS2 using the instructions from the [https://msys2.github.io/ MSYS2 website]. Then run the following commands using either "''MinGW-w64 Win32 Shell''" if you want to build a 32-bit version, or "''MinGW-w64 Win64 Shell''" if you want to build a 64-bit version.

RawTherapee can be built using GTK+ versions 2 or 3. To build using GTK2 use the <code>gtk2</code> branch; to build using GTK3 use the <code>dev</code> branch. The last version of RawTherapee to support GTK2 is 5.0-r1-gtk2 released on 2017-02-02. Use the <code>dev</code> branch for the latest code - it requires GTK+ >=3.16. We recommend using GTK+ 3.22.24 or newer as this is the first version to support native windows, without which the RawTherapee window could exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior] such as maximizing under the taskbar in Windows 10.

== Install tools and libraries ==

First, install a few miscellaneous tools:
<pre style="white-space: pre-wrap">
$ pacman -S tar gzip nano make diffutils intltool git
</pre>

Then install the necessary development tools:
<pre style="white-space: pre-wrap">
# win32
$ pacman -S mingw-w64-i686-gcc mingw-w64-i686-gdb mingw-w64-i686-make mingw-w64-i686-pkg-config mingw-w64-i686-cmake
# win64
$ pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-make mingw-w64-x86_64-pkg-config mingw-w64-x86_64-cmake
</pre>
and the required libraries:
<pre style="white-space: pre-wrap">
# win32
$ pacman -S mingw-w64-i686-gtkmm mingw-w64-i686-gtkmm3 mingw-w64-i686-lcms2 mingw-w64-i686-fftw
# win64
$ pacman -S mingw-w64-x86_64-gtkmm mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun
</pre>

== Download and build libiptcdata ==

The libiptcdata library is not yet provided by MSYS2, therefore it should be downloaded and configured using:
<pre style="white-space: pre-wrap">
$ curl -LO http://downloads.sourceforge.net/project/libiptcdata/libiptcdata/1.0.4/libiptcdata-1.0.4.tar.gz
$ tar xzf libiptcdata-1.0.4.tar.gz
$ cd libiptcdata-1.0.4

# win32
$ ./configure --prefix=/mingw32
# win64
$ ./configure --prefix=/mingw64
</pre>

Afterwards the <code>Makefile</code> needs to be opened using a text editor to remove <code>iptc</code> and <code>docs</code> from the lists named <code>SUBDIRS</code> and <code>DIST_SUBDIRS</code>, as building or installing will fail otherwise:
<pre style="white-space: pre-wrap">
$ nano Makefile

# Replace
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# with
DIST_SUBDIRS = m4 libiptcdata po win python

# And replace
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)
</pre>

Finally build and install the library:
<pre style="white-space: pre-wrap">
$ make
$ make install
$ cd
</pre>

== Download and build Clearlooks ==

If you are building RawTherapee using GTK2 then you need the Clearlooks theme engine. You do not need it if you are building using GTK3.

Download and build it:
<pre style="white-space: pre-wrap">
$ curl -LO http://sources.archlinux.org/other/gtk-engines/gtk-engines-2.21.0.tar.gz
$ tar xzf gtk-engines-2.21.0.tar.gz
$ cd gtk-engines-2.21.0

# win32
$ ./configure --prefix=/mingw32 --disable-all --enable-clearlooks
# win64
$ ./configure --prefix=/mingw64 --disable-all --enable-clearlooks

$ make
$ make install
$ cd
</pre>

== Clone and build RawTherapee ==

Clone RawTherapee's Git repository. The build process will fail if there is a space character anywhere in your <code>build</code> folder path. For example if your Windows username is "Zank Frappa" then your home path will be <code>C:\Users\Zank Frappa\</code> and if you clone RawTherapee inside there then the build will fail during compilation. Simply clone to a folder where neither it nor its parent folders have a space in their name, for example <code>C:\code\repo-rt</code>
<pre style="white-space: pre-wrap">
$ git clone http://github.com/Beep6581/RawTherapee.git /c/code/repo-rt
$ cd /c/code/repo-rt
</pre>

RawTherapee can be built using GTK+ versions 2 or 3. To build using GTK2 use the <code>gtk2</code> branch; to build using GTK3 use the <code>dev</code> branch. The last version of RawTherapee to support GTK2 is 5.0-r1-gtk2 released on 2017-02-02. Use the <code>dev</code> branch for the latest code - it requires GTK+ >=3.16. When you clone the repository you will automatically find yourself in the <code>dev</code> branch. To switch to the <code>dev</code> branch manually, do the following:
<pre style="white-space: pre-wrap">
$ git checkout dev
</pre>

Create a separate directory for the build:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note that if you switch branches then you must delete and recreate the <code>build</code> folder so that compilation starts from scratch in an empty folder, otherwise compilation is likely to fail. However if you are just updating without changing branches then you do not have to start with an empty build folder - you can just go into the existing one, and compilation will be faster because not everything will need to be recompiled.

Run CMake and Make:
<pre style="white-space: pre-wrap">
$ cmake -G "MSYS Makefiles" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ make install
</pre>

You can find an explanation of the various CMake options in the [[Linux#CMake|Linux article]], including an explanation of the various "BUILD_TYPE" options.

If you are building for 32-bit Windows XP and are using the <code>release</code> or <code>relwithdebinfo</code> "BUILD_TYPE", you will need to add the <code>-mstackrealign</code> compiler flag before the last two dots <code>..</code> of the CMake command above:
<pre style="white-space: pre-wrap">
-DCMAKE_C_FLAGS="-mstackrealign" -DCMAKE_CXX_FLAGS="-mstackrealign"
</pre>

== Copy RawTherapee and required DLLs ==

RawTherapee can now be started from the MSYS2 command line:
<pre style="white-space: pre-wrap">
# for debug builds
$ cd debug
# for release builds
$ cd release
# for relwithdebinfo builds
$ cd relwithdebinfo
$ ./rawtherapee.exe
</pre>

The file manager can be used to copy the contents of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> together with the necessary DLLs from <code><prefix>\bin</code> into <code>.</code>, where:
*<code><prefix></code> is <code><MSYS2>\<mingw32|mingw64></code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the Rawtherapee installation folder.

The current list of required DLLs is:
<pre style="white-space: pre-wrap">
libatk-1.0-0.dll
libatkmm-1.6-1.dll
libbz2-1.dll
libcairo-2.dll
libcairo-gobject-2.dll
libcairomm-1.0-1.dll
libcroco-0.6-3.dll
libepoxy-0.dll
libexpat-1.dll
libfﬁ-6.dll
libfftw3f-3.dll
libfontconﬁg-1.dll
libfreetype-6.dll
libgcc_s_seh-1.dll
libgdk_pixbuf-2.0-0.dll
libgdk-3-0.dll
libgdkmm-3.0-1.dll
libgio-2.0-0.dll
libgiomm-2.4-1.dll
libglib-2.0-0.dll
libglibmm-2.4-1.dll
libgmodule-2.0-0.dll
libgobject-2.0-0.dll
libgomp-1.dll
libgraphite2.dll
libgtk-3-0.dll
libgtkmm-3.0-1.dll
libharfbuzz-0.dll
libiconv-2.dll
libintl-8.dll
libjpeg-8.dll
liblcms2-2.dll
liblensfun.dll
liblzma-5.dll
libpango-1.0-0.dll
libpangocairo-1.0-0.dll
libpangoft2-1.0-0.dll
libpangomm-1.4-1.dll
libpangowin32-1.0-0.dll
libpcre-1.dll
libpixman-1-0.dll
libpng16-16.dll
librsvg-2-2.dll
libsigc-2.0-0.dll
libstdc++-6.dll
libsystre-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
zlib1.dll
</pre>

The following list of Adwaita theme files should be copied from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
16x16\actions\*
16x16\devices\*
16x16\mimetypes\*
16x16\places\*
16x16\status\*
48x48\devices\*
24x24\status\image-missing.png

icon-theme.cache
index.theme

cursors\plus.cur
cursors\sb_h_double_arrow.cur
cursors\sb_left_arrow.cur
cursors\sb_right_arrow.cur
cursors\sb_v_double_arrow.cur
</pre>

The following files also need to be copied:
<pre style="white-space: pre-wrap">
<prefix>\bin\gspawn-<win32|win64>-helper.exe -> .
<prefix>\bin\gspawn-<win32|win64>-helper-console.exe -> .

<prefix>\lib\gdk-pixbuf-2.0 -> .\lib\gdk-pixbuf-2.0

<prefix>\share\glib-2.0\schemas\gschemas.compiled -> .\share\glib-2.0\schemas
<prefix>\share\lensfun\version_1\* -> .\share\lensfun
</pre>

== Creating a distributable package ==

If you plan to distribute RawTherapee packages for the Windows platform, as a first step you need to make sure that RawTherapee will be built for the "generic" processor target. To do so, use <code>-DPROC_TARGET_NUMBER="1"</code> in the CMake command.

During compilation, a script named <code>WindowsInnoSetup.iss</code> is created in the RawTherapee installation folder. This script is used by Inno Setup [http://www.jrsoftware.org/isinfo.php], a program which is used to generate installers for Windows programs. It is advised to download the Unicode version [http://www.jrsoftware.org/download.php/is-unicode.exe] to avoid problems with some languages.

The current <code>WindowsInnoSetup.iss</code> script is designed for the <code>gtk2</code> branch. If you want to create a package for a GTK3 build (<code>dev</code> or <code>releases</code> branches) you will need to edit the script and replace the line:

<pre style="white-space: pre-wrap">
Source: "{#MyBuildBasePath}\lib\*"; DestDir: "{app}\lib\"; Flags: ignoreversion recursesubdirs createallsubdirs
</pre>

with

<pre style="white-space: pre-wrap">
Source: "{#MyBuildBasePath}\share\*"; DestDir: "{app}\share\"; Flags: ignoreversion recursesubdirs createallsubdirs
</pre>

so that icons and schemas will be copied into the package.

To help users [[How_to_write_useful_bug_reports|write useful bug reports]], package maintainers are encouraged to produce builds which include both a "release" and a "debug" executable, and to bundle them together with the GDB debugger executable. In other words, put the <code>rawtherapee.exe</code> (release) file together with the <code>rawtherapee-debug.exe</code> (debug) file and the <code>gdb.exe</code> file together into the same installer or the same archive. An alternative is to produce "relwithdebinfo" builds - these are much faster than "debug" but not as optimized as "release" builds, yet they provide just about as much useful information as "debug" builds. When making "relwithdebinfo" or "debug" builds you must provide the GDB debugger executable. Windows binaries of the debugger <code>gdb.exe</code> can be downloaded from [http://www.equation.com/servlet/equation.cmd?fa=gdb here] in 32- and 64-bit versions.

The <code>gdb.exe</code> binary, available from http://www.gnu.org/software/gdb/, should be copied into the RawTherapee installation folder and, if using Inno Setup to generate the package, the <code>WindowsInnoSetup.iss</code> script should be edited by uncommenting (removing the semicolon from the front of) the following around line 114 of the script:

<pre style="white-space: pre-wrap">
;Source: "{#MyBuildBasePath}\gdb.exe"; DestDir: "{app}"; Flags: ignoreversion
</pre>

Now that everything is set up, to create the package right-click on the <code>WindowsInnoSetup.iss</code> script and choose ''Compile'' from the context menu. It will automatically generate the installer and place it in the parent folder.

To make your new package compatible with the RawTherapee website's upload panel, create a zip archive in which you will place both the newly created installer and the corresponding ''AboutThisBuild.txt'' file which can be found at the same place. Name the resulting zip archive following this template:
<code>RawTherapee_<WinXP|WinVista>_<32|64>_<version>_<buildtype>.zip</code>

* "WinXP" means that the build is only for Windows XP. "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.2</code> if you checkout the <code>5.2</code> tag, or <code>5.2-dev-g1a2b3c4d</code> if you checkout the <code>dev</code> branch after 5.2 was tagged.
* If you are shipping more than one build type in an installer, include the names of all build types, e.g. <code>release_debug</code>.

For example:
* <code>RawTherapee_WinVista_64_5.2_release.zip</code>
* <code>RawTherapee_WinVista_64_5.2_release_debug.zip</code>
* <code>RawTherapee_WinVista_64_5.2-dev-g1a2b3c4d_release_debug.zip</code>

Windows

2018-01-25T12:59:20Z

Sguyader: /* Copy RawTherapee and required DLLs */

This guide documents how to build RawTherapee for 32-bit or 64-bit versions of Windows using the MinGW-w64 runtime. Begin by installing and updating MSYS2 using the instructions from the [https://msys2.github.io/ MSYS2 website]. Then run the following commands using either "''MinGW-w64 Win32 Shell''" if you want to build a 32-bit version, or "''MinGW-w64 Win64 Shell''" if you want to build a 64-bit version.

RawTherapee can be built using GTK+ versions 2 or 3. To build using GTK2 use the <code>gtk2</code> branch; to build using GTK3 use the <code>dev</code> branch. The last version of RawTherapee to support GTK2 is 5.0-r1-gtk2 released on 2017-02-02. Use the <code>dev</code> branch for the latest code - it requires GTK+ >=3.16. We recommend using GTK+ 3.22.24 or newer as this is the first version to support native windows, without which the RawTherapee window could exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior] such as maximizing under the taskbar in Windows 10.

== Install tools and libraries ==

First, install a few miscellaneous tools:
<pre style="white-space: pre-wrap">
$ pacman -S tar gzip nano make diffutils intltool git
</pre>

Then install the necessary development tools:
<pre style="white-space: pre-wrap">
# win32
$ pacman -S mingw-w64-i686-gcc mingw-w64-i686-gdb mingw-w64-i686-make mingw-w64-i686-pkg-config mingw-w64-i686-cmake
# win64
$ pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-make mingw-w64-x86_64-pkg-config mingw-w64-x86_64-cmake
</pre>
and the required libraries:
<pre style="white-space: pre-wrap">
# win32
$ pacman -S mingw-w64-i686-gtkmm mingw-w64-i686-gtkmm3 mingw-w64-i686-lcms2 mingw-w64-i686-fftw
# win64
$ pacman -S mingw-w64-x86_64-gtkmm mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun
</pre>

== Download and build libiptcdata ==

The libiptcdata library is not yet provided by MSYS2, therefore it should be downloaded and configured using:
<pre style="white-space: pre-wrap">
$ curl -LO http://downloads.sourceforge.net/project/libiptcdata/libiptcdata/1.0.4/libiptcdata-1.0.4.tar.gz
$ tar xzf libiptcdata-1.0.4.tar.gz
$ cd libiptcdata-1.0.4

# win32
$ ./configure --prefix=/mingw32
# win64
$ ./configure --prefix=/mingw64
</pre>

Afterwards the <code>Makefile</code> needs to be opened using a text editor to remove <code>iptc</code> and <code>docs</code> from the lists named <code>SUBDIRS</code> and <code>DIST_SUBDIRS</code>, as building or installing will fail otherwise:
<pre style="white-space: pre-wrap">
$ nano Makefile

# Replace
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# with
DIST_SUBDIRS = m4 libiptcdata po win python

# And replace
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)
</pre>

Finally build and install the library:
<pre style="white-space: pre-wrap">
$ make
$ make install
$ cd
</pre>

== Download and build Clearlooks ==

If you are building RawTherapee using GTK2 then you need the Clearlooks theme engine. You do not need it if you are building using GTK3.

Download and build it:
<pre style="white-space: pre-wrap">
$ curl -LO http://sources.archlinux.org/other/gtk-engines/gtk-engines-2.21.0.tar.gz
$ tar xzf gtk-engines-2.21.0.tar.gz
$ cd gtk-engines-2.21.0

# win32
$ ./configure --prefix=/mingw32 --disable-all --enable-clearlooks
# win64
$ ./configure --prefix=/mingw64 --disable-all --enable-clearlooks

$ make
$ make install
$ cd
</pre>

== Clone and build RawTherapee ==

Clone RawTherapee's Git repository. The build process will fail if there is a space character anywhere in your <code>build</code> folder path. For example if your Windows username is "Zank Frappa" then your home path will be <code>C:\Users\Zank Frappa\</code> and if you clone RawTherapee inside there then the build will fail during compilation. Simply clone to a folder where neither it nor its parent folders have a space in their name, for example <code>C:\code\repo-rt</code>
<pre style="white-space: pre-wrap">
$ git clone http://github.com/Beep6581/RawTherapee.git /c/code/repo-rt
$ cd /c/code/repo-rt
</pre>

RawTherapee can be built using GTK+ versions 2 or 3. To build using GTK2 use the <code>gtk2</code> branch; to build using GTK3 use the <code>dev</code> branch. The last version of RawTherapee to support GTK2 is 5.0-r1-gtk2 released on 2017-02-02. Use the <code>dev</code> branch for the latest code - it requires GTK+ >=3.16. When you clone the repository you will automatically find yourself in the <code>dev</code> branch. To switch to the <code>dev</code> branch manually, do the following:
<pre style="white-space: pre-wrap">
$ git checkout dev
</pre>

Create a separate directory for the build:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note that if you switch branches then you must delete and recreate the <code>build</code> folder so that compilation starts from scratch in an empty folder, otherwise compilation is likely to fail. However if you are just updating without changing branches then you do not have to start with an empty build folder - you can just go into the existing one, and compilation will be faster because not everything will need to be recompiled.

Run CMake and Make:
<pre style="white-space: pre-wrap">
$ cmake -G "MSYS Makefiles" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ make install
</pre>

You can find an explanation of the various CMake options in the [[Linux#CMake|Linux article]], including an explanation of the various "BUILD_TYPE" options.

If you are building for 32-bit Windows XP and are using the <code>release</code> or <code>relwithdebinfo</code> "BUILD_TYPE", you will need to add the <code>-mstackrealign</code> compiler flag before the last two dots <code>..</code> of the CMake command above:
<pre style="white-space: pre-wrap">
-DCMAKE_C_FLAGS="-mstackrealign" -DCMAKE_CXX_FLAGS="-mstackrealign"
</pre>

== Copy RawTherapee and required DLLs ==

RawTherapee can now be started from the MSYS2 command line:
<pre style="white-space: pre-wrap">
# for debug builds
$ cd debug
# for release builds
$ cd release
# for relwithdebinfo builds
$ cd relwithdebinfo
$ ./rawtherapee.exe
</pre>

The file manager can be used to copy the contents of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> together with the necessary DLLs from <code><MSYS2>\<mingw32|mingw64>\bin</code> into a RawTherapee installation folder, where <code><MSYS2></code> is the MSYS2 installation folder.

A (possibly incomplete) list of required DLLs is:
<pre style="white-space: pre-wrap">
libatk-1.0-0.dll
libatkmm-1.6-1.dll
libbz2-1.dll
libcairo-2.dll
libcairo-gobject-2.dll
libcairomm-1.0-1.dll
libcroco-0.6-3.dll
libepoxy-0.dll
libexpat-1.dll
libfﬁ-6.dll
libfftw3f-3.dll
libfontconﬁg-1.dll
libfreetype-6.dll
libgcc_s_seh-1.dll
libgdk_pixbuf-2.0-0.dll
libgdk-3-0.dll
libgdkmm-3.0-1.dll
libgio-2.0-0.dll
libgiomm-2.4-1.dll
libglib-2.0-0.dll
libglibmm-2.4-1.dll
libgmodule-2.0-0.dll
libgobject-2.0-0.dll
libgomp-1.dll
libgraphite2.dll
libgtk-3-0.dll
libgtkmm-3.0-1.dll
libharfbuzz-0.dll
libiconv-2.dll
libintl-8.dll
libjpeg-8.dll
liblcms2-2.dll
liblensfun.dll
liblzma-5.dll
libpango-1.0-0.dll
libpangocairo-1.0-0.dll
libpangoft2-1.0-0.dll
libpangomm-1.4-1.dll
libpangowin32-1.0-0.dll
libpcre-1.dll
libpixman-1-0.dll
libpng16-16.dll
librsvg-2-2.dll
libsigc-2.0-0.dll
libstdc++-6.dll
libsystre-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
zlib1.dll
</pre>

The following files also need to be copied:
<pre style="white-space: pre-wrap">
<prefix>\bin\gspawn-<win32|win64>-helper.exe -> .
<prefix>\bin\gspawn-<win32|win64>-helper-console.exe -> .

<prefix>\lib\gdk-pixbuf-2.0 -> .\lib\gdk-pixbuf-2.0

<prefix>\share\glib-2.0\schemas\gschemas.compiled -> .\share\glib-2.0\schemas
<prefix>\share\lensfun\version_1\* -> .\share\lensfun
</pre>
where <code><prefix></code> is <code><MSYS2>\<mingw32|mingw64></code> from above and <code>.</code> is the installation folder.

== Creating a distributable package ==

If you plan to distribute RawTherapee packages for the Windows platform, as a first step you need to make sure that RawTherapee will be built for the "generic" processor target. To do so, use <code>-DPROC_TARGET_NUMBER="1"</code> in the CMake command.

During compilation, a script named <code>WindowsInnoSetup.iss</code> is created in the RawTherapee installation folder. This script is used by Inno Setup [http://www.jrsoftware.org/isinfo.php], a program which is used to generate installers for Windows programs. It is advised to download the Unicode version [http://www.jrsoftware.org/download.php/is-unicode.exe] to avoid problems with some languages.

The current <code>WindowsInnoSetup.iss</code> script is designed for the <code>gtk2</code> branch. If you want to create a package for a GTK3 build (<code>dev</code> or <code>releases</code> branches) you will need to edit the script and replace the line:

<pre style="white-space: pre-wrap">
Source: "{#MyBuildBasePath}\lib\*"; DestDir: "{app}\lib\"; Flags: ignoreversion recursesubdirs createallsubdirs
</pre>

with

<pre style="white-space: pre-wrap">
Source: "{#MyBuildBasePath}\share\*"; DestDir: "{app}\share\"; Flags: ignoreversion recursesubdirs createallsubdirs
</pre>

so that icons and schemas will be copied into the package.

To help users [[How_to_write_useful_bug_reports|write useful bug reports]], package maintainers are encouraged to produce builds which include both a "release" and a "debug" executable, and to bundle them together with the GDB debugger executable. In other words, put the <code>rawtherapee.exe</code> (release) file together with the <code>rawtherapee-debug.exe</code> (debug) file and the <code>gdb.exe</code> file together into the same installer or the same archive. An alternative is to produce "relwithdebinfo" builds - these are much faster than "debug" but not as optimized as "release" builds, yet they provide just about as much useful information as "debug" builds. When making "relwithdebinfo" or "debug" builds you must provide the GDB debugger executable. Windows binaries of the debugger <code>gdb.exe</code> can be downloaded from [http://www.equation.com/servlet/equation.cmd?fa=gdb here] in 32- and 64-bit versions.

The <code>gdb.exe</code> binary, available from http://www.gnu.org/software/gdb/, should be copied into the RawTherapee installation folder and, if using Inno Setup to generate the package, the <code>WindowsInnoSetup.iss</code> script should be edited by uncommenting (removing the semicolon from the front of) the following around line 114 of the script:

<pre style="white-space: pre-wrap">
;Source: "{#MyBuildBasePath}\gdb.exe"; DestDir: "{app}"; Flags: ignoreversion
</pre>

Now that everything is set up, to create the package right-click on the <code>WindowsInnoSetup.iss</code> script and choose ''Compile'' from the context menu. It will automatically generate the installer and place it in the parent folder.

To make your new package compatible with the RawTherapee website's upload panel, create a zip archive in which you will place both the newly created installer and the corresponding ''AboutThisBuild.txt'' file which can be found at the same place. Name the resulting zip archive following this template:
<code>RawTherapee_<WinXP|WinVista>_<32|64>_<version>_<buildtype>.zip</code>

* "WinXP" means that the build is only for Windows XP. "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.2</code> if you checkout the <code>5.2</code> tag, or <code>5.2-dev-g1a2b3c4d</code> if you checkout the <code>dev</code> branch after 5.2 was tagged.
* If you are shipping more than one build type in an installer, include the names of all build types, e.g. <code>release_debug</code>.

For example:
* <code>RawTherapee_WinVista_64_5.2_release.zip</code>
* <code>RawTherapee_WinVista_64_5.2_release_debug.zip</code>
* <code>RawTherapee_WinVista_64_5.2-dev-g1a2b3c4d_release_debug.zip</code>

Local Lab Controls

2017-11-20T00:11:26Z

Sguyader: /* Processing time and memory use */

==What kind of local control?==

Several types of local control exist in mainstream applications :
# “lasso”, associated with layers and fusion masks (e.g. Photoshop©). This kind of control is widespread (Photoshop, Gimp, Darktable…) and users tend to favor those, at the expense of the type described in 3. below, which is less well known;
# dedicated tools for the removal of image defects such as “red eyes”, or “spots” associated with sensor imperfections or dirt;
# “U-points” controls, used until recently in Nikon Capture NX2©, or as an add-on to other software such as Nik Software©. For those (rare now) who tried such programs, there’s no way turning back to layers and fusion masks! This type of local control requires learning something different, and a cognitive “reprogramming”. In my opinion, this kind of local control is globally more efficient.

The algorithm developed in the current version of RawTherapee is close in its principle to the U-points described above. Of course, the code used in Nik Software is not disclosed, but several years ago I was attracted by the simplicity of use and the efficiency of U-points, and I started developing a product which would use neither lassos, nor layers or fusion masks. Of course, nothing prevents us from having all 3 types of local control in the same program.

The current version of the filter is perfectible, particularly regarding the user interface (GUI):
* for managing and viewing the RT-spots (control spots) on screen,
* for manipulating the different sliders, which would ideally be better if integrated to the actual control points, as done in Nik Software.

However, those two aspects don’t harm everyday use, nor code portability.

In order to improve manipulation and avoid long menus on screen, I added a GUI interface which is similar to the one used in the Wavelet tab, with “expanders”. Thus for each module (“Color and Light”, “Blur”, “Retinex”, …) you can choose to:
# display (or not) the full list of commands: sliders methods, curves…
# activate (or not) all the functions of the module.

Warning: The second choice activates or cancels all the RT-spots. (It would be possible in theory to add this capability to every single RT-spot, but for what purpose?)

===Lab and RGB local controls===
* The first algorithms are coded in L*a*b* mode with the following modules: “Color and Light”, “Blur / Add noise”, “Retinex”, “Tone mapping”, “Sharpen”, “Contrast by Detail Levels”, “Denoise”. Two additional modules have been added: “Exposure” and “Vibrance”.
* See below for the principles of the different algorithms, but one key point to remember for shape detection and artifact limitation, is that the Lab mode preserves the “hue” tint, which is crucial.
* The idea of an “RGB” module comes to one’s mind, with ''a minima'':
** a “White balance” module, which would allow to locally adjust the white balance, for example to warm up shadows, or to deal with mixed scene lighting such as “daylight” and “tungsten”. This module needs to be inserted just after “demosaic”.

====Auto White balance====
The “White balance” module (in the “autowblocal” branch) serves two purposes:
* allowing a local adjustment of the white balance (of course)
* testing new algorithms for automatic white balance adjustment:
** in general use (full image), in order to achieve better results than with the current algorithm. Of course one will tell me that I should create a specific branch for “White balance”, but here I’m trying to hit two targets with one bullet.

As a reminder, I’ve been asked in 2012 and 2013 to develop an iterative white balance “Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]”. At that time, another developer and I had spent a lot of time on this for an unsatisfactory result, so we gave up. Since then, benefiting from this experience, I resumed this work but in the reverse way! Now, if I’m correct, the algorithm works. I took advantage of this new capability (currently working on raw images only) to search in the academic literature for other auto WB algorithms. I found, and developed two new algorithms:
* “auto edge”[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]: the idea is to create an accentuation mask allowing to reinforce parts of the image where details are more prevalent, compared to flatter regions.
* “auto standard deviation”[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]: here, the image (or part of it for the local control) is divided in 12 zones, for each of which mean and standard deviation are computed, and the result assembled.
A third algorithm, “Color by correlation”[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf], looks promising but I’m facing several difficulties. After many trials of many types, the results are just too erratic…

I also added the notion of gamma:
* the same principles which deal with luminance distribution – gamma sRGB – used in the main RawTherapee code.

Bear in mind that the automatic white balancing is a totally non deterministic mathematical problem. The algorithms may perform more or less well (and faster or slower), but a perfect result can’t exist! Why is it so? If one is referring to the principles of color management ([http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]), it is necessary to have knowledge of the three of: the coloured object, the illuminant and the observer. At least two of those are unknown in practice. In addition, the environment in which an image is shot is not known while it has an effect on the perception (CIECAM), and the same is true during both image editing and viewing. The mission is thus almost impossible!

The aim of the “White balance” module is '''for testing the algorithms''', there are 7 of them at least, and twice that number if “gamma sRGB” is considered. Indeed, in order to circumvent the obstacles encountered five years ago, instead of the using the image before demosaicing, I used the image just after demosaicing, allowing to apply (or not) “gamma sRGB”, ending in the same conditions as in normal use (but without normal “White balance” and “ICC or DCP” profile).

Ideally, we should test the algorithms on many images, as well: which algorithm(s) to keep and implement in normal – global RGB – mode (maybe one or two, in addition to the current algorithm which we should keep for compatibility).

====Local control of White balance====
The local control is currently limited to 1 spot only, but there’s no difficulty to increase this if users want so… while waiting for the evolution of “locallab”.

Of course, I hear voices say “it doesn’t work”, or “the output doesn’t match with the preview”. But it does work! And it is more than evident that matching exactly the preview is by definition almost impossible… (differences between shadows, sun light, different illuminants, etc…) whatever the relevance of the algorithm.

==What are the challenges we need to solve?==
Several general issues need to be solved so as to achieve smoothness in use:
* allow an (almost) unlimited number of RT-spots (the name we chose for the control spots in RawTherapee);
* adapt the local algorithms to be aware of scale, because many of them take the image size – the treated area – into account. This aspect is fundamental, particularly with curves which act on the whole image;
* minimise memory use and computation time for JPG and TIFF output;
* allow easy updates in case of evolution of either the algorithms or the number of methods/modules;
* optimise (minimise) the differences between the preview and the output.
* etc…

For each RT-spot:
* allow for the action to occur, on user choice, either inside or outside (“Inverse” mode) of the selection area;
* allow shape detection, on user choice, in order to limit the action based on features/shapes;
* take care of the transition between the center of the treated area and the other parts of the image;
* etc…

Currently, RT-spots are operational in Lab mode with the following modules and methods:
# “Colour and Light”: “Lightness”, “Chrominance”, “Contrast” in normal mode with 4 curves L=f(L), L=f(H), C=f(C), H=f(H), and in “inverse” mode;
# “Exposure”: normal mode only;
# “Vibrance:” normal mode only;
# “Blur & noise”: normal and “inverse” modes;
# “Retinex”: normal and “inverse” modes, now also with “transmission gain” curve;
# “Sharpening”: normal and “inverse” modes;
# “Contrast by detail levels” (CBDL): normal mode only;
# “Denoise”: normal mode only.

==General principles==
===The RT-spot object===
As I mentioned earlier, the system used in RT is similar to the one developed in Nik Software, but with some significant differences:
* each RT-spot can be viewed as an object with a number of fields (about 70 as of today), made of sliders, curves, control points, etc…;
* each field, grouped in modules, can be activated or not, and have different parameter values according to their nature;
* the modules are made to be coherent for the user: “Color and Light”, “Exposure”, “Contrast”, “Vibrance”, “Blur”, “Retinex”, “Sharpening”, “Tone Mapping”, “Contrast by detail levels”, “Denoise”;
* the number of RT-spot objects can vary from 2 up to 500;
* data describing the RT-spot objects are stored in text files with .mip extension;
* creating, modifying and tracking of the RT-spot objects are done in a “for” loop;
* there’s no code duplication.

===Partitioning into 4 zones – previewing the RT-spot area===
When the user selects an RT-spot, the screen preview shows:
* a centre, made of a circle whose diameter and position can be adjusted directly using the mouse or the sliders;
* two horizontal and two vertical handles, whose position can be modified directly using the mouse or the provided sliders, controlling the extent of the area affected by the RT-spot;
* if "Show spot delimiters" is checked in "Preferences" > "General" tab > "Local adjustments", one can visualise approximately the area affected by the spot. Because I couldn’t work cleanly with the « arc/ellipse/scale » function in the Cairo graphics library, I made each quadrant defined by a pseudo-ellipse made of 3 Bézier curves joining each other. In most cases the approximation is satisfying… To help grabbing the 4 handles, I made them longer (the Bézier curves are inactive!).

We obtain 4 zones, whose orientation cannot be modified (the default rotation angle is set to zero). Those 4 zones have each of their vertices connected by imaginary ellipses.

It is possible to drag the handles outside the image preview area.

It should be possible to replace the ellipse with a hand drawn curve (even if I think its usefulness is debatable because of the existence of the shape detection algorithm), as long as the homothetic transform of the curve doesn’t intersect with the original curve. Although the benefits from this intellectually satisfying “improvement” should negligible in the case of the RT-spots, it will be possible to make the current RT-spots and lasso type of controls coexist eventually.

===The "normal" and "excluding" types of RT-spots===
Two types of RT-spots are available:
* "Normal": these are the spots which do the local retouching. Each new RT-spot takes into account the effect of existing spots when their zone of influence overlap (a sort of recursive action).
* "Excluding": adding a new "excluding" RT-spot allows to revert the effect created by a "normal" RT-spot in their overlapping zone of influence , from the original image data (but doing its calculations from the reference values of the area affected by the "normal" RT-spot).

For both types, the user has access to most of the modules ("Color and Light", "Contrast by detail levels", "Blur", ...)

====Comments about the "excluding" RT-spot====
* The principle of the "excluding" spot is similar to the "counterpoint" in Capture NX2, and is useful when for example, the effect of a "normal" RT-spot bleeds into an area which the user wants to be unaffected. This unwanted effect happens when when the tints of the two areas (the area the user wants to be affected, and the area one wants to remain unaffected) are to close.
* The underlying algorithm is similar to the main algorithms used elsewhere in "locallab", and is based on tint differences. While it's not perfect it should give satisfaction 70% of the time.
* I implemented an additional algorithm (with no guarantee that it will actually work one day) to help discriminate the areas, based on a Sobel-Canny transform. The transform is coded but is not yet accessible to the user, as I'm still working to make it more efficient.

====How to use the "excluding" RT-spot, and its limitations====
# Create a new RT-spot over the area you want to restore.
# In the "Settings" panel, from the "Spot method" combobox choose "Excluding spot".
# Adjust "Scope", "Transition" and "Spot size" as well as the shape of the zone of influence using the 4 handles, until you get the desired reversion of the effect. You can use complimentary adjustments such as "Color and light", etc.
The algorithm computes the reference values (tint, chroma, luma) from the the current image (see below). As a consequence, the "excluding" effect won't work if the image area is black (for example when the user uses a normal RT-spot using "Color and light" in inverse mode to create a black frame).
Sometimes, when the "inverse" mode is selected, the "excluding" spot algorithm may not work as expected and lead to a difference between the preview and the output (JPG, TIFF) image. Increasing the value of "Scope" of the "excluding" RT-spot should help in this situation.

===Tint, chroma, luminance references and the algorithm principle in “normal” mode===
In order to develop an efficient shape detection algorithm:
* The central circle zone is used as the reference. Based on the diameter value chosen by the user, the algorithm computes the tint (hue), chroma and luminance averages.
* The choice of the central zone diameter depends on the use intent. For example, if working on a foliage area the user would benefit from choosing a smaller diameter value in order to select only the foliage green; in contrast, for skin tones the user should increase the diameter to avoid the detection of parasites (noise, eye lashes…).
* For each quadrant, depending on the the value of the “Scope” slider, the algorithm does:
# take into account the tint difference between the zone centre and the affected pixel;
# through a complex algorithm based on the deltaE notion (perceived difference between two colours, taking tint, chroma and luminance into account), decrease the amount of applied effect as a function of the difference between the central zone and the affected pixel;
# follow either a linear or a parabolic law to adjust the amount of applied effect, based on the specific the case.

This allows adapting the amount of effect according to the above-mentioned criteria. For example, if the central circle is located on foliage, the action will be limited to the leaves, without touching the background (which would be impossible to obtain with the lasso type of controls). Additionally, if some other foliage resides within the area covered by the RT-spot, it will also be affected.
* Adjusting the value of the “Transition” slider modifies the transition of the effect (from the centre to the edge): on 50, the inner (linear) half will get the full 100% action/effect, while the effect in the outer half will gradually transition from 100% to 0% towards the edge;
* By increasing the value of “Scope”, progressively more of the selected area is taken into account, whatever the tint, chroma and luminance;
* Conversely, by decreasing the “Scope” value the effect will get limited to the pixels which are more similar (in terms of deltaE) to the reference zone.

The shape detection algorithm works in “Normal” mode except for some modules (“Denoise”). It’s not implemented in “Inverse” mode, doing so would not make sense.

The algorithm will see its performance increase when the user chooses “Enhanced” or “Enhanced + chroma denoise” in the “Global quality:” combobox. The second choice additionally applies a low amount of chroma noise reduction in order to get rid of artefacts which could be brought up by the “Enhanced” algorithm (note that the chroma denoise step increases memory use and computing time).

The algorithm is used in full capacity for “scope” < 20.

===Why no alternative algorithms?===
It should be possible to implement other shape detection algorithms than the deltaE-based one used currently, for example:
* edge detection algorithms such as “Canny” or “Sobel”;
* wavelet decomposition.

But in both cases, everything would have to be done!

===Functioning in “inverse” mode===
When it is available, the “Inverse” mode is extremely simplified: only the “Transition” slider can be used to apply the effect.
As of late October 2017, I devised a new method for “Inverse” mode. It is limited to the “Blur & Noise” module (see the corresponding section below).

===Maximum number of RT-spots===
By default the number of available RT-spots is 8. You can choose any number between 2 and 499. For this you only need to change the parameter “Nspot” in the “options” file (for example: Nspot=12). Restart RawTherapee for the modification to be taken into account.

===The “super” algorithm===
The key to “success” was the algorithm implemented in late January 2017, which works this way:
# on the pixel data which are within the area covered by the RT-spot, the algorithm applies either a “traditional” curve, a slider, or a normal transfer function (“Retinex”, “Tone Mapping”, “Contrast by detail levels”, “Vibrance”, …);
# the LUT or the transfer function is converted into an equivalent of a slider, separating negative and positive values so that the function can be viewed as multiple sliders (as many sliders as there are pixels) in the -100, 0, +100 interval;
# the data are passed to the shape detection function – the 4 quadrants. For every pixel, the difference in terms of tint, chroma and luma is computed with regards to the central reference. The linear variation equations are estimated for luminance (L=f(L)), chroma (C=f(C)) or transfer functions;
# different corrections are applied to account for the environment (sky, skin tones…)
# a correction is made (with threshold and iterations) in order to avoid correcting (or only slightly, based on the user’s choice) the grey or neutral tones which are in the same tint as the reference (but with a low chroma value);
# the parameters are weighted based on the shape of the RT-spot (ellipses) and the transition zone;
# the values of the “Global quality:” parameters are important, particularly so for images with a low amount of noise – chroma noise is interpreted by the algorithm being of the same colour as the spot. It is thus necessary to suppress this noise, that is the purpose of “Enhanced + chroma denoise” (this algorithm may not be sufficient, though – in this case using the local “Denoise” module may be useful).

This new (“super”) algorithm seems to perform generally well, but in the event when the RT-spot is located in a grey/neutral or flat area, the algorithm may fail. In such cases, using the old algorithm is recommended (except for “Retinex”, “Tone Mapping” and “Contrast by detail levels” for which it is made unavailable for the sake of code simplicity).

===Artefact reduction and the “Global quality” algorithms===
By default, “Global quality:” is set to “Enhanced + chroma denoise”. Whereas it increases computation time, it is still generally preferable. In case one wants a more responsive preview, “Enhance” or “Standard” can be chosen (good for exploring the image).
* two sliders allow reducing artefacts and improving the algorithm’s rendering. They work based on chroma, in neutral/gray tones. To completely remove its effect, one can simply set “iterations=0”. These sliders may be used for "Color light", "Exposure", "Retinex", "Vibrance", "Tone mapping" and "Contrast by detail levels";
* for (even slightly) noisy images, the algorithms may be misled. In this case it is recommended to keep "Global quality:” set to “Enhanced + chroma denoise", and (sometimes) activate the local “Denoise” module and adjust the sliders very gently (including “Luminance”);
* under some circumstances, with “Tone Mapping” for example, the artefact reduction algorithm may actually generate more artefacts. When it happens, set “iterations=0”.

If your images are generally clean (no or very low noise), you can choose to have “Standard” as the default for “Global quality:” – this will speed up the image processing. To do so, go to “Preferences” > “Performance and quality” tab > “Local adjustments” and choose the “Standard” algorithm among the 3 options. This will become the new default when new RT-spots are created, but of course the algorithm can still be changed on the fly by choosing from the “Global quality” combo box.

===Avoid color shift===
The “Avoid color shift” checkbox serves two purposes:
* put the colours within the current working profile gamut, using a relative colorimetry;
* adjust colours using a “Munsell” correction – particularly for red-orange and blue-purple colours, when saturation in the L*a*b* space has changed significantly.

===“mip” files – Principles of the multi-point algorithm===
For the local control system to work and keep track of RT-spot objects, a text file – similar to a pp3 – is written in 2 possible places:
* next to the edited image file. If, for example, you edit an image named ASC4509.NEF, a new file named ASC4509.NEF.mip will be generated in the same folder. In this case, several sessions can be open for the same image, as long as copies of the image are stored in different folders. However, the folder names in the path have to contain ASCII characters only, otherwise it will make the program crash;
* in the dedicated “mip” folder, within the “cache” directory (through an MD5 hash number which identifies the file). This is the default. If chosen, when multiple copies of the same file exist in distinct folders, editing them creates as many “mip” files. This option allows the use of non ASCII characters in the folder names and path.

The choice between these two behaviours is made in “Preferences” > “Image processing” tab > “Mip profiles”.

The “mip” files contain the data which are passed to RawTherapee through processes of the “procparams” type, and LUTs which allow editing in zoom mode. When updating RawTherapee to a new version, it may be required to delete the “mip” files (or the whole cache) to avoid a potential crash of the application. This can be achieved by going to “Preferences” > “File browser” tab, then choosing “Clear mip” and/or “Clear pp3” – all this is valid only if “mip” and “pp3” files have been set to be saved to the cache folder, otherwise they will have to be manually deleted from the working folder. Keeping older “mip” and “pp3” files may lead to instability or crashes of the application.

====Architecture of the filter====
When I “ventured” into a multi-point, no-layer and no-mask system, code duplication had to be avoided. Indeed, it is unthinkable to consider, for 10 RT-spots, generating 10 GUI code blocks, and just as many code blocks in “rtengine”. After careful consideration, the idea was to have a file updating and tracking in real time – i.e. a file which would follow each modification made by the user – the actions/modifications history.

Of course, the parameters used by RawTherapee for the GUI and for the main code through “params” are of different types:
* numeric: integer, float, double,…
* Boolean
* string (in choice menus for the different modules)
* curves, through “vectors” of type double with dynamic dimension
* …

====Data conversion====
In order to simplify data management, the first step is to convert all data to integers. Sometimes this can lead to a slight precision loss, which I think is negligible.
* This operation is very simple for numeric values, even though in some cases (such as hue, which is expressed in radian in the interval [-Pi, +Pi]) it needs a double “float*100 and /100 conversion to keep precision.
* It is logical for Boolean operations and methods.
* However, it is a complex matter regarding curves. The values to be recorded in the “mip” file are of type vector<double>, in a dynamic table of numeric values. There may be a simpler way, by using existing functions from “procparams”, but I didn’t succeed.
Nevertheless, I could get around this by:
# converting doubles to integers with 3 significant figures – which is largely enough,
# then converting the “vector” to a variable length character string,
# the writing and reading of this character string and converting to a vector dynamically using an appropriate function (”strcurv_data”). Note that this function allows adjusting the curves within the limit of 16 inflection points (Bézier curve) for the flat curve, and 32 points for the diagonal, which should be enough. Whether this would not be enough, it should be possible to increase that number, though compatibility would be compromised.

====Some elements about curves====
The implementation of curves has been a complex task, particularly since:
# each curve needs its own reset function – resize() at each iteration,
# which implies oddities regarding their description, for example the diagonal curve gets initialised with several points, despite it looks being “empty”. This is mandatory for correct functioning, but this means that the curve is always open/active. Consequently, to avoid some unwanted loss of computation time in “preview” mode, the user has to activate the curve by clicking on the “curves” combobox. The same activation is necessary for L=f(H) and C=f(C) curves. While clicking enabling the “curves” (linear) would seem to be a better solution, it didn’t work despite many trials.
# during all the procedure, we need to set each "params" value to "clear" for curves, for each LUT, at each iteration and then through a "vector" to reassign the good, updated values to "curve params".

====Data storing and dynamic use====
Once data have been converted:
* they are stored in a text (mip) file,
* each one is referenced inside a 2-dimension dynamical table:
# dataspot[x][y] for numeric and boolean values and methods, where “x” is the representative index of the parameter (e.g. “9” is for “lightness”) and “y” represents the current RT-spot (control spot). Value “0” represents the current in-use value (the one stores in “params”).
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] for parameters of type “curve”. Currently there are only 8 parameters, used for local “Retinex”, “Color and light” (L=f(L), C=f(C), L=f(H), H=F(H)), “Vibrance” and “Exposure”, but it is easy to add more. “y” is used as above in 1.

The way data are stored and used fits well with improccoordinator.cc (current management / preview) and simpleprocess.cc (TIFF / JPG output) files, but not so with dcrop.cc and the partial display of the image (RawTherapee’s pipeline).

In this case (zoom / preview) another solution had to be found in order to synchronise the modifications in real time. I made use of LUTs, so that to each entry referenced in the table described above a LUTi(z) is associated, with z=500 possible entries (500 corresponds to the current maximum number of RT-spots, but this limit can be decreased or increased). The LUTi “z” corresponds to the dataspot “y”. A 25,000 entries LUTi (arbitrary number) is used for “retistr”, “llstr”, “lhstr”, “ccstr”, “hhstr”, “skinstr”, “pthstr”, “exstr” for storing each “vector” curve value in memory (up to 69 values stored as integers).

During data processing, exchanges occur between: params, dynamic tables and LUTi. The values used by dcrop.cc are dynamically linked to dynamical tables by parent→.

====Exchange processes and dynamic data storing====
# reading of the “mip” file to check the version number and guide the updates
# creating the “mip” file if it doesn’t exist
# storing the data in LUTi and dynamic tables from the values stored in “params” (index 0 values)
# first interactive update with the GUI through a transfer function between “rtengine” and locallab.cc (aloListener → localretChanged). This is one of the 3 functions required for the process to work correctly
# reading of the “mip” file and data storing in dynamic tables (index values ==> y) according to the number of RT-spots
# creating a loop – according to the number of RT-spots – which updates LUTi (required by “dcrop”) and “params” values from values stored in the dynamic tables
# call to the “Lab_local” function which contains the algorithms controlling each RT-spot (luminance, sharpness, retinex, denoise, …)
# second interactive update with the GUI through another transfer function between “rtengine” and “locallab.cc”
# treatment of the current RT-spot by using the index (0) values from the dynamic tables. These values are attributed to 1) “params”, 2) LUTi and 3) current index values
# call to the “Lab_local” function for the current RT-spots
# saving to the “mip” file.

Note that if the user modifies the curve (amplitude, number of inflection points) a third interactive update is made in order to conform all of the data according to events.

====A few unavoidable “fantasies”====
Of course everything looks simple, the process works if, and only if, all the data are dynamically updated. I’ve tried a lot, went groping, and finally found a working solution… but an uncanny one. There’s probably a more “informatically” correct way to do it, but at this point I’ve done as explained above and hereafter.

The 3 exchanges between “rtengine” and the GUI occur with 3 parameters which actually do nothing in the program except doing the update process:
# “anbspot” which takes values of 0 or 1
# “cTgainshaperab” (curve) which takes any value bewteen 0.70 and 0.90
# “retrab” which varies around 500.
I have added 3 more parameters (in the form of sliders) – hueref, chromaref and lumaref – hidden from the user but which are used to update the system in real time, to correctly take into account the reference “spot” values. Allowing those 3 parameters to vary brings stability and allows real time updates. Increasing the number of those “fantasy” parameters should not be necessary. These extra parameters are hidden to the user, and are only visible in the history.

In addition, I had to add some empirical time delays, giving time to time… Time delay is used for example when the user modifies the curve (amplitude, number of inflection points).

==Specificity of the local mode (as compared to “Lab adjustments”)==
Hereafter is some useful information for the user, often specific to the local mode.

===Color and Light===
* The algorithms used for luminance and contrast in local mode differ from the ones used in “Lab adjustments”, which may lead to differences in rendering.
* The luminance algorithm is made such that below -90 and down to -100 for “Lightness”, it is possible to increase the image's “darkness”, almost to the point of getting a luminance value close to 0. To accentuate this effect, “Chrominance” can be decreased and “Scope” increased.
* The inverse mode can be used for creating graduated frames. If “Ligthness” is set to -100 and "Chrominance" is reduced, the “frame border” will be black.
* For the “Lightness” and “Contrast” sliders, the user can choose among 2 algorithms: the first one (default) is close to that in “Lab adjustments” while the second one, activated through “Lightness - Contrast ‘Super’” is close to the algorithm used for the L=f(L) “Super” curve.
* Do not hesitate, when needed, to activate “Enhanced” or “Enhanced + chroma denoise” in the “Global Quality:” combobox.

====Curves====
* An L=f(L) or C=f(C) curves allow controlling the luminance and chrominance for each RT-spot as a function of luminance or chrominance.
* An L=f(H) curve allows controlling the luminance for each RT-spot as a function of tint.
* An H=f(H) curve allows controlling the tint for each RT-spot as a function of tint.
The curves are activated by selecting one of the two algorithms from the “Curves types” combobox:
* “Normal”: the curves – particularly the one that is the most difficult to manage, L=f(L) – use an algorithm close to the one used with the sliders (Normal mode),
* “Super”: using a new algorithm, which I think performs very well (it even surprised me the first time I used it).

Caution: when the RT-spot resides in an area which is neutral, grey or very uniform, the artefacts introduced by the new algorithm (“Super” algorithm for the curve or the slider) may be impossible to get rid of. Use one of the 2 older algorithms to avoid that.

===Exposure===
The “Exposure” module may look like the the one in global RGB mode, but:
* it works entirely in L*a*b* mode, hence the differences in rendering;
* there’s no “Lightness”, “Chroma” or “Contrast” slider, whose functions are already fulfilled in the “Color and Light” module;
* there’s only one “Contrast” curve, similar to the L=f(L) firm “Color and Light”. Of course its effect is different from “Tone curve” which works in RGB mode. If needed, two L=f(L) curves can be activated, one under “Color and Light” and the other under “Exposure”.

===Vibrance===
This module is similar to the main one (from RawTherapee's "Exposure" tab).

===Blur & Noise===
“Blur” is activated only when “Radius” =< 2.
By significantly lowering the default value of “Scope” and possibly checking “Blur luminance only”, it is possible to get a different amount of blur for the different tints.
Since October 2017, 3 methods are proposed:
* “Normal”: the shape detection algorithm has been improved, it is now closer to shape detection algorithm proposed in the other modules;
* “Inverse”: a simplified algorithm, which doesn’t make use of “Scope”. The inversion is coarse and doesn’t allow a fine separation between the affected and unaffected areas;
* “Symmetric”: this new algorithm uses the same processes as “Normal”, and adjusting “Scope” the user can target the process with more precision.
Caution:
* Using the “Inverse” mode will blur large portions of the image, which can not be corrected later on.
* The action of “Scope” may sometimes appear puzzling: for instance, in a portrait, the eyes (which of course differ from the skin) may be blurred if the value of “Scope” is too low.

===Tone Mapping===
Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Retinex===
Compared to the standard “Retinex” module, the local “Retinex module has simplified controls, and is applied at the end of the pipeline instead of the beginning. Since “mip” version 10002, the “Transmission gain” is specific to each RT-spot.

===Sharpening===
Only the “RL Deconvolution” algorithm is provided here.

===Contrast by detail levels===
Compared to the main RGB mode module, this one has:
* 5 levels instead of 6,
* no slider for “skin tone” protection (not needed since the algorithm works locally on the RT-spot area),
* an additional “Chroma” slider.

Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Denoise===
Compared to the main RGB mode module, this one has:
* only the wavelet tool working (no Fourier function, nor medians),
* less sliders and curves,
* the possibility to work differentially on fine or coarse noise for both luminance and chrominance noise.

==A specific use case : reduction of image defects (dirty sensor, red eyes, …)==
“Locallab” had not been thought with the idea of correcting small image defects. However, some visible, “photographically disturbing” defects may actually be tamed or even removed. Of course, this is not incompatible with other more specialised modules which could be introduced (or not) into “Locallab”… At least 3 existing modules can serve this purpose, alone or in combination, by adapting their use:
* “Color and Light” for spot-like defects;
* “Contrast by detail levels” for spread out defects;
* “Blur and Noise” as an optional complement (caution, this is a destructive action, use moderately).

These modules can be used either on the main image (raw, TIFF, …) or on a flat-field image.

===Using the “Color and Light” module===
* Activate “Color and Light”
* A red eye removal tool equivalent can be obtained by framing closely around the eye – central circle zone centered on the eye’s red, spot handles close to the eye – low “Scope” value, then lowering “Lightness” and “Chrominance” to -100.
* The same idea allows reducing the “IR spot” kind of defect by framing closely around the defect – central circle zone centred on the defect, spot handles close to the defect area – then lowering “Chrominance” to taste, and if needed lowering the “scope” value.
* In some (simple) situations, a “dirty sensor” defect can be reduced, in particular in the case of “sensor grease”. It can be seen as stains or spots on a uniform background. To attenuate this, choose a tight framing of around the defect – central circle on the centre of the defect (adapt the size of the RT-spot), drag the handles so that they are not too close to the border of the defect (this will make the transition less noticeable). Then: a) decrease “Transition” towards lower values; b) check “Lightness - Contrast “Super”; c) adjust “Lightness” and “Chrominance” as needed to bring the defect area closer to the unaffected area; d) if needed adjust slightly “Scope” to achieve the best result.

===Using the “Contrast by detail levels” module===
When the sensor is dirty (grease), and when the affected area is large or if there are multiple small defects, “Contrast by detail levels” may be used, working as a sort of “wavelet” tool on luminance, and if needed on chrominance. In such cases: a) place the RT-spot on one of the stronger defects (adjust the size as needed); b) drag the handles so as to cover most of the affected area; c) set “Transition” to higher value; d) activate “Contrast by detail levels” and decrease the contrast of levels 3 and 4 (or lower); you can adjust the “Chroma” slider if needed.

==Settings in the Preferences dialog==
Below is a list of the settings (already mentioned above in several places) which can be accessed from the “Preferences” dialog:
* In “Preferences” > “General” tab > “Local adjustments”, by checking the “Show spot delimiters” checkbox, an approximate zone delimitation is drawn which helps viewing the area affected by the RT-spot and its settings.
* If your images generally have low noise, you can set the default for “Global quality” to “Standard”, and get a significant speedup in processing time. This setting is found under “Preferences” > “Performance & Quality” tab > “Local adjustments”. The three choices for quality are selected from the “Local adjustments Quality method” combobox. Default is “Enhanced + chroma denoise”.
* Regarding “mip” files:
** the choice for “mip” files destination folder is set from “Preferences” > “Image processing” tab > “Mip Profiles”;
** in order to clean the generated “mip” profiles, go to “Preferences” > “File Browser” tab > “Cache Options” and click on the “Clear mip” button and/or “Clear pp3” – this is valid in the case where you chose to store “mip” files in the cache, otherwise if you chose to let RT write the “mip” files next to the input file, you will have to delete them manually. Note that the presence of older versions of “mip” and “pp3” files may lead to instability or even crashes of RawTherapee.

==Processing time and memory use==
At image export time (output to JPG, TIFF…), for the “normal” mode, the algorithms compute the data only for in the RT-spot delimited areas, not for the whole image. Thus, processing time and memory stay reasonable. Note that of course, this will depend on the number of RT-spots, their size, and the type(s) of treatment done in these RT-spots.

Excluding “Denoise” and “Sharpen”, processing time is in the order of a few tenths of a second per RT-spot, and memory use of a few hundred MB.

Two settings have a strong influence on resource use:
* “Denoise” which adds around 1 sec. of processing time, and 1 MB of memory use;
* “Global quality: Enhanced + chroma denoise” which adds around 0.5 sec. And 0.6 MB.
These figures depend on the size of the RT-spot.

==Future evolution==
Besides usual tweaking, bug corrections, improvements (settings, user interface)… it would be desirable to improve the GUI with regards to the creation/selection/modification of individual RT-spots.

From a programming point of view, it should be possible to improve code readability and maintainability, and to integrate all the “mip” files code parts (as done in “rgbproc.cc”) which currently are linearly integrated to void procedures in “improccoordinator.cc”, “dcrop.cc” and “simpleprocess.cc”.

Local Lab Controls

2017-11-20T00:10:33Z

Sguyader: /* Processing time and memory use */

==What kind of local control?==

Several types of local control exist in mainstream applications :
# “lasso”, associated with layers and fusion masks (e.g. Photoshop©). This kind of control is widespread (Photoshop, Gimp, Darktable…) and users tend to favor those, at the expense of the type described in 3. below, which is less well known;
# dedicated tools for the removal of image defects such as “red eyes”, or “spots” associated with sensor imperfections or dirt;
# “U-points” controls, used until recently in Nikon Capture NX2©, or as an add-on to other software such as Nik Software©. For those (rare now) who tried such programs, there’s no way turning back to layers and fusion masks! This type of local control requires learning something different, and a cognitive “reprogramming”. In my opinion, this kind of local control is globally more efficient.

The algorithm developed in the current version of RawTherapee is close in its principle to the U-points described above. Of course, the code used in Nik Software is not disclosed, but several years ago I was attracted by the simplicity of use and the efficiency of U-points, and I started developing a product which would use neither lassos, nor layers or fusion masks. Of course, nothing prevents us from having all 3 types of local control in the same program.

The current version of the filter is perfectible, particularly regarding the user interface (GUI):
* for managing and viewing the RT-spots (control spots) on screen,
* for manipulating the different sliders, which would ideally be better if integrated to the actual control points, as done in Nik Software.

However, those two aspects don’t harm everyday use, nor code portability.

In order to improve manipulation and avoid long menus on screen, I added a GUI interface which is similar to the one used in the Wavelet tab, with “expanders”. Thus for each module (“Color and Light”, “Blur”, “Retinex”, …) you can choose to:
# display (or not) the full list of commands: sliders methods, curves…
# activate (or not) all the functions of the module.

Warning: The second choice activates or cancels all the RT-spots. (It would be possible in theory to add this capability to every single RT-spot, but for what purpose?)

===Lab and RGB local controls===
* The first algorithms are coded in L*a*b* mode with the following modules: “Color and Light”, “Blur / Add noise”, “Retinex”, “Tone mapping”, “Sharpen”, “Contrast by Detail Levels”, “Denoise”. Two additional modules have been added: “Exposure” and “Vibrance”.
* See below for the principles of the different algorithms, but one key point to remember for shape detection and artifact limitation, is that the Lab mode preserves the “hue” tint, which is crucial.
* The idea of an “RGB” module comes to one’s mind, with ''a minima'':
** a “White balance” module, which would allow to locally adjust the white balance, for example to warm up shadows, or to deal with mixed scene lighting such as “daylight” and “tungsten”. This module needs to be inserted just after “demosaic”.

====Auto White balance====
The “White balance” module (in the “autowblocal” branch) serves two purposes:
* allowing a local adjustment of the white balance (of course)
* testing new algorithms for automatic white balance adjustment:
** in general use (full image), in order to achieve better results than with the current algorithm. Of course one will tell me that I should create a specific branch for “White balance”, but here I’m trying to hit two targets with one bullet.

As a reminder, I’ve been asked in 2012 and 2013 to develop an iterative white balance “Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]”. At that time, another developer and I had spent a lot of time on this for an unsatisfactory result, so we gave up. Since then, benefiting from this experience, I resumed this work but in the reverse way! Now, if I’m correct, the algorithm works. I took advantage of this new capability (currently working on raw images only) to search in the academic literature for other auto WB algorithms. I found, and developed two new algorithms:
* “auto edge”[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]: the idea is to create an accentuation mask allowing to reinforce parts of the image where details are more prevalent, compared to flatter regions.
* “auto standard deviation”[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]: here, the image (or part of it for the local control) is divided in 12 zones, for each of which mean and standard deviation are computed, and the result assembled.
A third algorithm, “Color by correlation”[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf], looks promising but I’m facing several difficulties. After many trials of many types, the results are just too erratic…

I also added the notion of gamma:
* the same principles which deal with luminance distribution – gamma sRGB – used in the main RawTherapee code.

Bear in mind that the automatic white balancing is a totally non deterministic mathematical problem. The algorithms may perform more or less well (and faster or slower), but a perfect result can’t exist! Why is it so? If one is referring to the principles of color management ([http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]), it is necessary to have knowledge of the three of: the coloured object, the illuminant and the observer. At least two of those are unknown in practice. In addition, the environment in which an image is shot is not known while it has an effect on the perception (CIECAM), and the same is true during both image editing and viewing. The mission is thus almost impossible!

The aim of the “White balance” module is '''for testing the algorithms''', there are 7 of them at least, and twice that number if “gamma sRGB” is considered. Indeed, in order to circumvent the obstacles encountered five years ago, instead of the using the image before demosaicing, I used the image just after demosaicing, allowing to apply (or not) “gamma sRGB”, ending in the same conditions as in normal use (but without normal “White balance” and “ICC or DCP” profile).

Ideally, we should test the algorithms on many images, as well: which algorithm(s) to keep and implement in normal – global RGB – mode (maybe one or two, in addition to the current algorithm which we should keep for compatibility).

====Local control of White balance====
The local control is currently limited to 1 spot only, but there’s no difficulty to increase this if users want so… while waiting for the evolution of “locallab”.

Of course, I hear voices say “it doesn’t work”, or “the output doesn’t match with the preview”. But it does work! And it is more than evident that matching exactly the preview is by definition almost impossible… (differences between shadows, sun light, different illuminants, etc…) whatever the relevance of the algorithm.

==What are the challenges we need to solve?==
Several general issues need to be solved so as to achieve smoothness in use:
* allow an (almost) unlimited number of RT-spots (the name we chose for the control spots in RawTherapee);
* adapt the local algorithms to be aware of scale, because many of them take the image size – the treated area – into account. This aspect is fundamental, particularly with curves which act on the whole image;
* minimise memory use and computation time for JPG and TIFF output;
* allow easy updates in case of evolution of either the algorithms or the number of methods/modules;
* optimise (minimise) the differences between the preview and the output.
* etc…

For each RT-spot:
* allow for the action to occur, on user choice, either inside or outside (“Inverse” mode) of the selection area;
* allow shape detection, on user choice, in order to limit the action based on features/shapes;
* take care of the transition between the center of the treated area and the other parts of the image;
* etc…

Currently, RT-spots are operational in Lab mode with the following modules and methods:
# “Colour and Light”: “Lightness”, “Chrominance”, “Contrast” in normal mode with 4 curves L=f(L), L=f(H), C=f(C), H=f(H), and in “inverse” mode;
# “Exposure”: normal mode only;
# “Vibrance:” normal mode only;
# “Blur & noise”: normal and “inverse” modes;
# “Retinex”: normal and “inverse” modes, now also with “transmission gain” curve;
# “Sharpening”: normal and “inverse” modes;
# “Contrast by detail levels” (CBDL): normal mode only;
# “Denoise”: normal mode only.

==General principles==
===The RT-spot object===
As I mentioned earlier, the system used in RT is similar to the one developed in Nik Software, but with some significant differences:
* each RT-spot can be viewed as an object with a number of fields (about 70 as of today), made of sliders, curves, control points, etc…;
* each field, grouped in modules, can be activated or not, and have different parameter values according to their nature;
* the modules are made to be coherent for the user: “Color and Light”, “Exposure”, “Contrast”, “Vibrance”, “Blur”, “Retinex”, “Sharpening”, “Tone Mapping”, “Contrast by detail levels”, “Denoise”;
* the number of RT-spot objects can vary from 2 up to 500;
* data describing the RT-spot objects are stored in text files with .mip extension;
* creating, modifying and tracking of the RT-spot objects are done in a “for” loop;
* there’s no code duplication.

===Partitioning into 4 zones – previewing the RT-spot area===
When the user selects an RT-spot, the screen preview shows:
* a centre, made of a circle whose diameter and position can be adjusted directly using the mouse or the sliders;
* two horizontal and two vertical handles, whose position can be modified directly using the mouse or the provided sliders, controlling the extent of the area affected by the RT-spot;
* if "Show spot delimiters" is checked in "Preferences" > "General" tab > "Local adjustments", one can visualise approximately the area affected by the spot. Because I couldn’t work cleanly with the « arc/ellipse/scale » function in the Cairo graphics library, I made each quadrant defined by a pseudo-ellipse made of 3 Bézier curves joining each other. In most cases the approximation is satisfying… To help grabbing the 4 handles, I made them longer (the Bézier curves are inactive!).

We obtain 4 zones, whose orientation cannot be modified (the default rotation angle is set to zero). Those 4 zones have each of their vertices connected by imaginary ellipses.

It is possible to drag the handles outside the image preview area.

It should be possible to replace the ellipse with a hand drawn curve (even if I think its usefulness is debatable because of the existence of the shape detection algorithm), as long as the homothetic transform of the curve doesn’t intersect with the original curve. Although the benefits from this intellectually satisfying “improvement” should negligible in the case of the RT-spots, it will be possible to make the current RT-spots and lasso type of controls coexist eventually.

===The "normal" and "excluding" types of RT-spots===
Two types of RT-spots are available:
* "Normal": these are the spots which do the local retouching. Each new RT-spot takes into account the effect of existing spots when their zone of influence overlap (a sort of recursive action).
* "Excluding": adding a new "excluding" RT-spot allows to revert the effect created by a "normal" RT-spot in their overlapping zone of influence , from the original image data (but doing its calculations from the reference values of the area affected by the "normal" RT-spot).

For both types, the user has access to most of the modules ("Color and Light", "Contrast by detail levels", "Blur", ...)

====Comments about the "excluding" RT-spot====
* The principle of the "excluding" spot is similar to the "counterpoint" in Capture NX2, and is useful when for example, the effect of a "normal" RT-spot bleeds into an area which the user wants to be unaffected. This unwanted effect happens when when the tints of the two areas (the area the user wants to be affected, and the area one wants to remain unaffected) are to close.
* The underlying algorithm is similar to the main algorithms used elsewhere in "locallab", and is based on tint differences. While it's not perfect it should give satisfaction 70% of the time.
* I implemented an additional algorithm (with no guarantee that it will actually work one day) to help discriminate the areas, based on a Sobel-Canny transform. The transform is coded but is not yet accessible to the user, as I'm still working to make it more efficient.

====How to use the "excluding" RT-spot, and its limitations====
# Create a new RT-spot over the area you want to restore.
# In the "Settings" panel, from the "Spot method" combobox choose "Excluding spot".
# Adjust "Scope", "Transition" and "Spot size" as well as the shape of the zone of influence using the 4 handles, until you get the desired reversion of the effect. You can use complimentary adjustments such as "Color and light", etc.
The algorithm computes the reference values (tint, chroma, luma) from the the current image (see below). As a consequence, the "excluding" effect won't work if the image area is black (for example when the user uses a normal RT-spot using "Color and light" in inverse mode to create a black frame).
Sometimes, when the "inverse" mode is selected, the "excluding" spot algorithm may not work as expected and lead to a difference between the preview and the output (JPG, TIFF) image. Increasing the value of "Scope" of the "excluding" RT-spot should help in this situation.

===Tint, chroma, luminance references and the algorithm principle in “normal” mode===
In order to develop an efficient shape detection algorithm:
* The central circle zone is used as the reference. Based on the diameter value chosen by the user, the algorithm computes the tint (hue), chroma and luminance averages.
* The choice of the central zone diameter depends on the use intent. For example, if working on a foliage area the user would benefit from choosing a smaller diameter value in order to select only the foliage green; in contrast, for skin tones the user should increase the diameter to avoid the detection of parasites (noise, eye lashes…).
* For each quadrant, depending on the the value of the “Scope” slider, the algorithm does:
# take into account the tint difference between the zone centre and the affected pixel;
# through a complex algorithm based on the deltaE notion (perceived difference between two colours, taking tint, chroma and luminance into account), decrease the amount of applied effect as a function of the difference between the central zone and the affected pixel;
# follow either a linear or a parabolic law to adjust the amount of applied effect, based on the specific the case.

This allows adapting the amount of effect according to the above-mentioned criteria. For example, if the central circle is located on foliage, the action will be limited to the leaves, without touching the background (which would be impossible to obtain with the lasso type of controls). Additionally, if some other foliage resides within the area covered by the RT-spot, it will also be affected.
* Adjusting the value of the “Transition” slider modifies the transition of the effect (from the centre to the edge): on 50, the inner (linear) half will get the full 100% action/effect, while the effect in the outer half will gradually transition from 100% to 0% towards the edge;
* By increasing the value of “Scope”, progressively more of the selected area is taken into account, whatever the tint, chroma and luminance;
* Conversely, by decreasing the “Scope” value the effect will get limited to the pixels which are more similar (in terms of deltaE) to the reference zone.

The shape detection algorithm works in “Normal” mode except for some modules (“Denoise”). It’s not implemented in “Inverse” mode, doing so would not make sense.

The algorithm will see its performance increase when the user chooses “Enhanced” or “Enhanced + chroma denoise” in the “Global quality:” combobox. The second choice additionally applies a low amount of chroma noise reduction in order to get rid of artefacts which could be brought up by the “Enhanced” algorithm (note that the chroma denoise step increases memory use and computing time).

The algorithm is used in full capacity for “scope” < 20.

===Why no alternative algorithms?===
It should be possible to implement other shape detection algorithms than the deltaE-based one used currently, for example:
* edge detection algorithms such as “Canny” or “Sobel”;
* wavelet decomposition.

But in both cases, everything would have to be done!

===Functioning in “inverse” mode===
When it is available, the “Inverse” mode is extremely simplified: only the “Transition” slider can be used to apply the effect.
As of late October 2017, I devised a new method for “Inverse” mode. It is limited to the “Blur & Noise” module (see the corresponding section below).

===Maximum number of RT-spots===
By default the number of available RT-spots is 8. You can choose any number between 2 and 499. For this you only need to change the parameter “Nspot” in the “options” file (for example: Nspot=12). Restart RawTherapee for the modification to be taken into account.

===The “super” algorithm===
The key to “success” was the algorithm implemented in late January 2017, which works this way:
# on the pixel data which are within the area covered by the RT-spot, the algorithm applies either a “traditional” curve, a slider, or a normal transfer function (“Retinex”, “Tone Mapping”, “Contrast by detail levels”, “Vibrance”, …);
# the LUT or the transfer function is converted into an equivalent of a slider, separating negative and positive values so that the function can be viewed as multiple sliders (as many sliders as there are pixels) in the -100, 0, +100 interval;
# the data are passed to the shape detection function – the 4 quadrants. For every pixel, the difference in terms of tint, chroma and luma is computed with regards to the central reference. The linear variation equations are estimated for luminance (L=f(L)), chroma (C=f(C)) or transfer functions;
# different corrections are applied to account for the environment (sky, skin tones…)
# a correction is made (with threshold and iterations) in order to avoid correcting (or only slightly, based on the user’s choice) the grey or neutral tones which are in the same tint as the reference (but with a low chroma value);
# the parameters are weighted based on the shape of the RT-spot (ellipses) and the transition zone;
# the values of the “Global quality:” parameters are important, particularly so for images with a low amount of noise – chroma noise is interpreted by the algorithm being of the same colour as the spot. It is thus necessary to suppress this noise, that is the purpose of “Enhanced + chroma denoise” (this algorithm may not be sufficient, though – in this case using the local “Denoise” module may be useful).

This new (“super”) algorithm seems to perform generally well, but in the event when the RT-spot is located in a grey/neutral or flat area, the algorithm may fail. In such cases, using the old algorithm is recommended (except for “Retinex”, “Tone Mapping” and “Contrast by detail levels” for which it is made unavailable for the sake of code simplicity).

===Artefact reduction and the “Global quality” algorithms===
By default, “Global quality:” is set to “Enhanced + chroma denoise”. Whereas it increases computation time, it is still generally preferable. In case one wants a more responsive preview, “Enhance” or “Standard” can be chosen (good for exploring the image).
* two sliders allow reducing artefacts and improving the algorithm’s rendering. They work based on chroma, in neutral/gray tones. To completely remove its effect, one can simply set “iterations=0”. These sliders may be used for "Color light", "Exposure", "Retinex", "Vibrance", "Tone mapping" and "Contrast by detail levels";
* for (even slightly) noisy images, the algorithms may be misled. In this case it is recommended to keep "Global quality:” set to “Enhanced + chroma denoise", and (sometimes) activate the local “Denoise” module and adjust the sliders very gently (including “Luminance”);
* under some circumstances, with “Tone Mapping” for example, the artefact reduction algorithm may actually generate more artefacts. When it happens, set “iterations=0”.

If your images are generally clean (no or very low noise), you can choose to have “Standard” as the default for “Global quality:” – this will speed up the image processing. To do so, go to “Preferences” > “Performance and quality” tab > “Local adjustments” and choose the “Standard” algorithm among the 3 options. This will become the new default when new RT-spots are created, but of course the algorithm can still be changed on the fly by choosing from the “Global quality” combo box.

===Avoid color shift===
The “Avoid color shift” checkbox serves two purposes:
* put the colours within the current working profile gamut, using a relative colorimetry;
* adjust colours using a “Munsell” correction – particularly for red-orange and blue-purple colours, when saturation in the L*a*b* space has changed significantly.

===“mip” files – Principles of the multi-point algorithm===
For the local control system to work and keep track of RT-spot objects, a text file – similar to a pp3 – is written in 2 possible places:
* next to the edited image file. If, for example, you edit an image named ASC4509.NEF, a new file named ASC4509.NEF.mip will be generated in the same folder. In this case, several sessions can be open for the same image, as long as copies of the image are stored in different folders. However, the folder names in the path have to contain ASCII characters only, otherwise it will make the program crash;
* in the dedicated “mip” folder, within the “cache” directory (through an MD5 hash number which identifies the file). This is the default. If chosen, when multiple copies of the same file exist in distinct folders, editing them creates as many “mip” files. This option allows the use of non ASCII characters in the folder names and path.

The choice between these two behaviours is made in “Preferences” > “Image processing” tab > “Mip profiles”.

The “mip” files contain the data which are passed to RawTherapee through processes of the “procparams” type, and LUTs which allow editing in zoom mode. When updating RawTherapee to a new version, it may be required to delete the “mip” files (or the whole cache) to avoid a potential crash of the application. This can be achieved by going to “Preferences” > “File browser” tab, then choosing “Clear mip” and/or “Clear pp3” – all this is valid only if “mip” and “pp3” files have been set to be saved to the cache folder, otherwise they will have to be manually deleted from the working folder. Keeping older “mip” and “pp3” files may lead to instability or crashes of the application.

====Architecture of the filter====
When I “ventured” into a multi-point, no-layer and no-mask system, code duplication had to be avoided. Indeed, it is unthinkable to consider, for 10 RT-spots, generating 10 GUI code blocks, and just as many code blocks in “rtengine”. After careful consideration, the idea was to have a file updating and tracking in real time – i.e. a file which would follow each modification made by the user – the actions/modifications history.

Of course, the parameters used by RawTherapee for the GUI and for the main code through “params” are of different types:
* numeric: integer, float, double,…
* Boolean
* string (in choice menus for the different modules)
* curves, through “vectors” of type double with dynamic dimension
* …

====Data conversion====
In order to simplify data management, the first step is to convert all data to integers. Sometimes this can lead to a slight precision loss, which I think is negligible.
* This operation is very simple for numeric values, even though in some cases (such as hue, which is expressed in radian in the interval [-Pi, +Pi]) it needs a double “float*100 and /100 conversion to keep precision.
* It is logical for Boolean operations and methods.
* However, it is a complex matter regarding curves. The values to be recorded in the “mip” file are of type vector<double>, in a dynamic table of numeric values. There may be a simpler way, by using existing functions from “procparams”, but I didn’t succeed.
Nevertheless, I could get around this by:
# converting doubles to integers with 3 significant figures – which is largely enough,
# then converting the “vector” to a variable length character string,
# the writing and reading of this character string and converting to a vector dynamically using an appropriate function (”strcurv_data”). Note that this function allows adjusting the curves within the limit of 16 inflection points (Bézier curve) for the flat curve, and 32 points for the diagonal, which should be enough. Whether this would not be enough, it should be possible to increase that number, though compatibility would be compromised.

====Some elements about curves====
The implementation of curves has been a complex task, particularly since:
# each curve needs its own reset function – resize() at each iteration,
# which implies oddities regarding their description, for example the diagonal curve gets initialised with several points, despite it looks being “empty”. This is mandatory for correct functioning, but this means that the curve is always open/active. Consequently, to avoid some unwanted loss of computation time in “preview” mode, the user has to activate the curve by clicking on the “curves” combobox. The same activation is necessary for L=f(H) and C=f(C) curves. While clicking enabling the “curves” (linear) would seem to be a better solution, it didn’t work despite many trials.
# during all the procedure, we need to set each "params" value to "clear" for curves, for each LUT, at each iteration and then through a "vector" to reassign the good, updated values to "curve params".

====Data storing and dynamic use====
Once data have been converted:
* they are stored in a text (mip) file,
* each one is referenced inside a 2-dimension dynamical table:
# dataspot[x][y] for numeric and boolean values and methods, where “x” is the representative index of the parameter (e.g. “9” is for “lightness”) and “y” represents the current RT-spot (control spot). Value “0” represents the current in-use value (the one stores in “params”).
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] for parameters of type “curve”. Currently there are only 8 parameters, used for local “Retinex”, “Color and light” (L=f(L), C=f(C), L=f(H), H=F(H)), “Vibrance” and “Exposure”, but it is easy to add more. “y” is used as above in 1.

The way data are stored and used fits well with improccoordinator.cc (current management / preview) and simpleprocess.cc (TIFF / JPG output) files, but not so with dcrop.cc and the partial display of the image (RawTherapee’s pipeline).

In this case (zoom / preview) another solution had to be found in order to synchronise the modifications in real time. I made use of LUTs, so that to each entry referenced in the table described above a LUTi(z) is associated, with z=500 possible entries (500 corresponds to the current maximum number of RT-spots, but this limit can be decreased or increased). The LUTi “z” corresponds to the dataspot “y”. A 25,000 entries LUTi (arbitrary number) is used for “retistr”, “llstr”, “lhstr”, “ccstr”, “hhstr”, “skinstr”, “pthstr”, “exstr” for storing each “vector” curve value in memory (up to 69 values stored as integers).

During data processing, exchanges occur between: params, dynamic tables and LUTi. The values used by dcrop.cc are dynamically linked to dynamical tables by parent→.

====Exchange processes and dynamic data storing====
# reading of the “mip” file to check the version number and guide the updates
# creating the “mip” file if it doesn’t exist
# storing the data in LUTi and dynamic tables from the values stored in “params” (index 0 values)
# first interactive update with the GUI through a transfer function between “rtengine” and locallab.cc (aloListener → localretChanged). This is one of the 3 functions required for the process to work correctly
# reading of the “mip” file and data storing in dynamic tables (index values ==> y) according to the number of RT-spots
# creating a loop – according to the number of RT-spots – which updates LUTi (required by “dcrop”) and “params” values from values stored in the dynamic tables
# call to the “Lab_local” function which contains the algorithms controlling each RT-spot (luminance, sharpness, retinex, denoise, …)
# second interactive update with the GUI through another transfer function between “rtengine” and “locallab.cc”
# treatment of the current RT-spot by using the index (0) values from the dynamic tables. These values are attributed to 1) “params”, 2) LUTi and 3) current index values
# call to the “Lab_local” function for the current RT-spots
# saving to the “mip” file.

Note that if the user modifies the curve (amplitude, number of inflection points) a third interactive update is made in order to conform all of the data according to events.

====A few unavoidable “fantasies”====
Of course everything looks simple, the process works if, and only if, all the data are dynamically updated. I’ve tried a lot, went groping, and finally found a working solution… but an uncanny one. There’s probably a more “informatically” correct way to do it, but at this point I’ve done as explained above and hereafter.

The 3 exchanges between “rtengine” and the GUI occur with 3 parameters which actually do nothing in the program except doing the update process:
# “anbspot” which takes values of 0 or 1
# “cTgainshaperab” (curve) which takes any value bewteen 0.70 and 0.90
# “retrab” which varies around 500.
I have added 3 more parameters (in the form of sliders) – hueref, chromaref and lumaref – hidden from the user but which are used to update the system in real time, to correctly take into account the reference “spot” values. Allowing those 3 parameters to vary brings stability and allows real time updates. Increasing the number of those “fantasy” parameters should not be necessary. These extra parameters are hidden to the user, and are only visible in the history.

In addition, I had to add some empirical time delays, giving time to time… Time delay is used for example when the user modifies the curve (amplitude, number of inflection points).

==Specificity of the local mode (as compared to “Lab adjustments”)==
Hereafter is some useful information for the user, often specific to the local mode.

===Color and Light===
* The algorithms used for luminance and contrast in local mode differ from the ones used in “Lab adjustments”, which may lead to differences in rendering.
* The luminance algorithm is made such that below -90 and down to -100 for “Lightness”, it is possible to increase the image's “darkness”, almost to the point of getting a luminance value close to 0. To accentuate this effect, “Chrominance” can be decreased and “Scope” increased.
* The inverse mode can be used for creating graduated frames. If “Ligthness” is set to -100 and "Chrominance" is reduced, the “frame border” will be black.
* For the “Lightness” and “Contrast” sliders, the user can choose among 2 algorithms: the first one (default) is close to that in “Lab adjustments” while the second one, activated through “Lightness - Contrast ‘Super’” is close to the algorithm used for the L=f(L) “Super” curve.
* Do not hesitate, when needed, to activate “Enhanced” or “Enhanced + chroma denoise” in the “Global Quality:” combobox.

====Curves====
* An L=f(L) or C=f(C) curves allow controlling the luminance and chrominance for each RT-spot as a function of luminance or chrominance.
* An L=f(H) curve allows controlling the luminance for each RT-spot as a function of tint.
* An H=f(H) curve allows controlling the tint for each RT-spot as a function of tint.
The curves are activated by selecting one of the two algorithms from the “Curves types” combobox:
* “Normal”: the curves – particularly the one that is the most difficult to manage, L=f(L) – use an algorithm close to the one used with the sliders (Normal mode),
* “Super”: using a new algorithm, which I think performs very well (it even surprised me the first time I used it).

Caution: when the RT-spot resides in an area which is neutral, grey or very uniform, the artefacts introduced by the new algorithm (“Super” algorithm for the curve or the slider) may be impossible to get rid of. Use one of the 2 older algorithms to avoid that.

===Exposure===
The “Exposure” module may look like the the one in global RGB mode, but:
* it works entirely in L*a*b* mode, hence the differences in rendering;
* there’s no “Lightness”, “Chroma” or “Contrast” slider, whose functions are already fulfilled in the “Color and Light” module;
* there’s only one “Contrast” curve, similar to the L=f(L) firm “Color and Light”. Of course its effect is different from “Tone curve” which works in RGB mode. If needed, two L=f(L) curves can be activated, one under “Color and Light” and the other under “Exposure”.

===Vibrance===
This module is similar to the main one (from RawTherapee's "Exposure" tab).

===Blur & Noise===
“Blur” is activated only when “Radius” =< 2.
By significantly lowering the default value of “Scope” and possibly checking “Blur luminance only”, it is possible to get a different amount of blur for the different tints.
Since October 2017, 3 methods are proposed:
* “Normal”: the shape detection algorithm has been improved, it is now closer to shape detection algorithm proposed in the other modules;
* “Inverse”: a simplified algorithm, which doesn’t make use of “Scope”. The inversion is coarse and doesn’t allow a fine separation between the affected and unaffected areas;
* “Symmetric”: this new algorithm uses the same processes as “Normal”, and adjusting “Scope” the user can target the process with more precision.
Caution:
* Using the “Inverse” mode will blur large portions of the image, which can not be corrected later on.
* The action of “Scope” may sometimes appear puzzling: for instance, in a portrait, the eyes (which of course differ from the skin) may be blurred if the value of “Scope” is too low.

===Tone Mapping===
Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Retinex===
Compared to the standard “Retinex” module, the local “Retinex module has simplified controls, and is applied at the end of the pipeline instead of the beginning. Since “mip” version 10002, the “Transmission gain” is specific to each RT-spot.

===Sharpening===
Only the “RL Deconvolution” algorithm is provided here.

===Contrast by detail levels===
Compared to the main RGB mode module, this one has:
* 5 levels instead of 6,
* no slider for “skin tone” protection (not needed since the algorithm works locally on the RT-spot area),
* an additional “Chroma” slider.

Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Denoise===
Compared to the main RGB mode module, this one has:
* only the wavelet tool working (no Fourier function, nor medians),
* less sliders and curves,
* the possibility to work differentially on fine or coarse noise for both luminance and chrominance noise.

==A specific use case : reduction of image defects (dirty sensor, red eyes, …)==
“Locallab” had not been thought with the idea of correcting small image defects. However, some visible, “photographically disturbing” defects may actually be tamed or even removed. Of course, this is not incompatible with other more specialised modules which could be introduced (or not) into “Locallab”… At least 3 existing modules can serve this purpose, alone or in combination, by adapting their use:
* “Color and Light” for spot-like defects;
* “Contrast by detail levels” for spread out defects;
* “Blur and Noise” as an optional complement (caution, this is a destructive action, use moderately).

These modules can be used either on the main image (raw, TIFF, …) or on a flat-field image.

===Using the “Color and Light” module===
* Activate “Color and Light”
* A red eye removal tool equivalent can be obtained by framing closely around the eye – central circle zone centered on the eye’s red, spot handles close to the eye – low “Scope” value, then lowering “Lightness” and “Chrominance” to -100.
* The same idea allows reducing the “IR spot” kind of defect by framing closely around the defect – central circle zone centred on the defect, spot handles close to the defect area – then lowering “Chrominance” to taste, and if needed lowering the “scope” value.
* In some (simple) situations, a “dirty sensor” defect can be reduced, in particular in the case of “sensor grease”. It can be seen as stains or spots on a uniform background. To attenuate this, choose a tight framing of around the defect – central circle on the centre of the defect (adapt the size of the RT-spot), drag the handles so that they are not too close to the border of the defect (this will make the transition less noticeable). Then: a) decrease “Transition” towards lower values; b) check “Lightness - Contrast “Super”; c) adjust “Lightness” and “Chrominance” as needed to bring the defect area closer to the unaffected area; d) if needed adjust slightly “Scope” to achieve the best result.

===Using the “Contrast by detail levels” module===
When the sensor is dirty (grease), and when the affected area is large or if there are multiple small defects, “Contrast by detail levels” may be used, working as a sort of “wavelet” tool on luminance, and if needed on chrominance. In such cases: a) place the RT-spot on one of the stronger defects (adjust the size as needed); b) drag the handles so as to cover most of the affected area; c) set “Transition” to higher value; d) activate “Contrast by detail levels” and decrease the contrast of levels 3 and 4 (or lower); you can adjust the “Chroma” slider if needed.

==Settings in the Preferences dialog==
Below is a list of the settings (already mentioned above in several places) which can be accessed from the “Preferences” dialog:
* In “Preferences” > “General” tab > “Local adjustments”, by checking the “Show spot delimiters” checkbox, an approximate zone delimitation is drawn which helps viewing the area affected by the RT-spot and its settings.
* If your images generally have low noise, you can set the default for “Global quality” to “Standard”, and get a significant speedup in processing time. This setting is found under “Preferences” > “Performance & Quality” tab > “Local adjustments”. The three choices for quality are selected from the “Local adjustments Quality method” combobox. Default is “Enhanced + chroma denoise”.
* Regarding “mip” files:
** the choice for “mip” files destination folder is set from “Preferences” > “Image processing” tab > “Mip Profiles”;
** in order to clean the generated “mip” profiles, go to “Preferences” > “File Browser” tab > “Cache Options” and click on the “Clear mip” button and/or “Clear pp3” – this is valid in the case where you chose to store “mip” files in the cache, otherwise if you chose to let RT write the “mip” files next to the input file, you will have to delete them manually. Note that the presence of older versions of “mip” and “pp3” files may lead to instability or even crashes of RawTherapee.

==Processing time and memory use==
At image export time (output to JPG, TIFF…), for the “normal” mode, the algorithms compute the data only for in the RT-spot delimited areas, not for the whole image. Thus, processing time and memory stay reasonable. Note that of course, this will depend on the number of RT-spots, their size, and the type(s) of treatment done in these RT-spots.

Excluding “Denoise” and “Sharpen”, processing time is in the order of a few tenths of a second per RT-spot, and memory use of a few hundred MB.

Two settings have a strong influence on resource use:
• “Denoise” which adds around 1 sec. of processing time, and 1 MB of memory use;
• “Global quality: Enhanced + chroma denoise” which adds around 0.5 sec. And 0.6 MB.
These figures depend on the size of the RT-spot.

==Future evolution==
Besides usual tweaking, bug corrections, improvements (settings, user interface)… it would be desirable to improve the GUI with regards to the creation/selection/modification of individual RT-spots.

From a programming point of view, it should be possible to improve code readability and maintainability, and to integrate all the “mip” files code parts (as done in “rgbproc.cc”) which currently are linearly integrated to void procedures in “improccoordinator.cc”, “dcrop.cc” and “simpleprocess.cc”.

Local Lab Controls

2017-11-20T00:10:04Z

Sguyader: /* Color and Light */

==What kind of local control?==

Several types of local control exist in mainstream applications :
# “lasso”, associated with layers and fusion masks (e.g. Photoshop©). This kind of control is widespread (Photoshop, Gimp, Darktable…) and users tend to favor those, at the expense of the type described in 3. below, which is less well known;
# dedicated tools for the removal of image defects such as “red eyes”, or “spots” associated with sensor imperfections or dirt;
# “U-points” controls, used until recently in Nikon Capture NX2©, or as an add-on to other software such as Nik Software©. For those (rare now) who tried such programs, there’s no way turning back to layers and fusion masks! This type of local control requires learning something different, and a cognitive “reprogramming”. In my opinion, this kind of local control is globally more efficient.

The algorithm developed in the current version of RawTherapee is close in its principle to the U-points described above. Of course, the code used in Nik Software is not disclosed, but several years ago I was attracted by the simplicity of use and the efficiency of U-points, and I started developing a product which would use neither lassos, nor layers or fusion masks. Of course, nothing prevents us from having all 3 types of local control in the same program.

The current version of the filter is perfectible, particularly regarding the user interface (GUI):
* for managing and viewing the RT-spots (control spots) on screen,
* for manipulating the different sliders, which would ideally be better if integrated to the actual control points, as done in Nik Software.

However, those two aspects don’t harm everyday use, nor code portability.

In order to improve manipulation and avoid long menus on screen, I added a GUI interface which is similar to the one used in the Wavelet tab, with “expanders”. Thus for each module (“Color and Light”, “Blur”, “Retinex”, …) you can choose to:
# display (or not) the full list of commands: sliders methods, curves…
# activate (or not) all the functions of the module.

Warning: The second choice activates or cancels all the RT-spots. (It would be possible in theory to add this capability to every single RT-spot, but for what purpose?)

===Lab and RGB local controls===
* The first algorithms are coded in L*a*b* mode with the following modules: “Color and Light”, “Blur / Add noise”, “Retinex”, “Tone mapping”, “Sharpen”, “Contrast by Detail Levels”, “Denoise”. Two additional modules have been added: “Exposure” and “Vibrance”.
* See below for the principles of the different algorithms, but one key point to remember for shape detection and artifact limitation, is that the Lab mode preserves the “hue” tint, which is crucial.
* The idea of an “RGB” module comes to one’s mind, with ''a minima'':
** a “White balance” module, which would allow to locally adjust the white balance, for example to warm up shadows, or to deal with mixed scene lighting such as “daylight” and “tungsten”. This module needs to be inserted just after “demosaic”.

====Auto White balance====
The “White balance” module (in the “autowblocal” branch) serves two purposes:
* allowing a local adjustment of the white balance (of course)
* testing new algorithms for automatic white balance adjustment:
** in general use (full image), in order to achieve better results than with the current algorithm. Of course one will tell me that I should create a specific branch for “White balance”, but here I’m trying to hit two targets with one bullet.

As a reminder, I’ve been asked in 2012 and 2013 to develop an iterative white balance “Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]”. At that time, another developer and I had spent a lot of time on this for an unsatisfactory result, so we gave up. Since then, benefiting from this experience, I resumed this work but in the reverse way! Now, if I’m correct, the algorithm works. I took advantage of this new capability (currently working on raw images only) to search in the academic literature for other auto WB algorithms. I found, and developed two new algorithms:
* “auto edge”[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]: the idea is to create an accentuation mask allowing to reinforce parts of the image where details are more prevalent, compared to flatter regions.
* “auto standard deviation”[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]: here, the image (or part of it for the local control) is divided in 12 zones, for each of which mean and standard deviation are computed, and the result assembled.
A third algorithm, “Color by correlation”[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf], looks promising but I’m facing several difficulties. After many trials of many types, the results are just too erratic…

I also added the notion of gamma:
* the same principles which deal with luminance distribution – gamma sRGB – used in the main RawTherapee code.

Bear in mind that the automatic white balancing is a totally non deterministic mathematical problem. The algorithms may perform more or less well (and faster or slower), but a perfect result can’t exist! Why is it so? If one is referring to the principles of color management ([http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]), it is necessary to have knowledge of the three of: the coloured object, the illuminant and the observer. At least two of those are unknown in practice. In addition, the environment in which an image is shot is not known while it has an effect on the perception (CIECAM), and the same is true during both image editing and viewing. The mission is thus almost impossible!

The aim of the “White balance” module is '''for testing the algorithms''', there are 7 of them at least, and twice that number if “gamma sRGB” is considered. Indeed, in order to circumvent the obstacles encountered five years ago, instead of the using the image before demosaicing, I used the image just after demosaicing, allowing to apply (or not) “gamma sRGB”, ending in the same conditions as in normal use (but without normal “White balance” and “ICC or DCP” profile).

Ideally, we should test the algorithms on many images, as well: which algorithm(s) to keep and implement in normal – global RGB – mode (maybe one or two, in addition to the current algorithm which we should keep for compatibility).

====Local control of White balance====
The local control is currently limited to 1 spot only, but there’s no difficulty to increase this if users want so… while waiting for the evolution of “locallab”.

Of course, I hear voices say “it doesn’t work”, or “the output doesn’t match with the preview”. But it does work! And it is more than evident that matching exactly the preview is by definition almost impossible… (differences between shadows, sun light, different illuminants, etc…) whatever the relevance of the algorithm.

==What are the challenges we need to solve?==
Several general issues need to be solved so as to achieve smoothness in use:
* allow an (almost) unlimited number of RT-spots (the name we chose for the control spots in RawTherapee);
* adapt the local algorithms to be aware of scale, because many of them take the image size – the treated area – into account. This aspect is fundamental, particularly with curves which act on the whole image;
* minimise memory use and computation time for JPG and TIFF output;
* allow easy updates in case of evolution of either the algorithms or the number of methods/modules;
* optimise (minimise) the differences between the preview and the output.
* etc…

For each RT-spot:
* allow for the action to occur, on user choice, either inside or outside (“Inverse” mode) of the selection area;
* allow shape detection, on user choice, in order to limit the action based on features/shapes;
* take care of the transition between the center of the treated area and the other parts of the image;
* etc…

Currently, RT-spots are operational in Lab mode with the following modules and methods:
# “Colour and Light”: “Lightness”, “Chrominance”, “Contrast” in normal mode with 4 curves L=f(L), L=f(H), C=f(C), H=f(H), and in “inverse” mode;
# “Exposure”: normal mode only;
# “Vibrance:” normal mode only;
# “Blur & noise”: normal and “inverse” modes;
# “Retinex”: normal and “inverse” modes, now also with “transmission gain” curve;
# “Sharpening”: normal and “inverse” modes;
# “Contrast by detail levels” (CBDL): normal mode only;
# “Denoise”: normal mode only.

==General principles==
===The RT-spot object===
As I mentioned earlier, the system used in RT is similar to the one developed in Nik Software, but with some significant differences:
* each RT-spot can be viewed as an object with a number of fields (about 70 as of today), made of sliders, curves, control points, etc…;
* each field, grouped in modules, can be activated or not, and have different parameter values according to their nature;
* the modules are made to be coherent for the user: “Color and Light”, “Exposure”, “Contrast”, “Vibrance”, “Blur”, “Retinex”, “Sharpening”, “Tone Mapping”, “Contrast by detail levels”, “Denoise”;
* the number of RT-spot objects can vary from 2 up to 500;
* data describing the RT-spot objects are stored in text files with .mip extension;
* creating, modifying and tracking of the RT-spot objects are done in a “for” loop;
* there’s no code duplication.

===Partitioning into 4 zones – previewing the RT-spot area===
When the user selects an RT-spot, the screen preview shows:
* a centre, made of a circle whose diameter and position can be adjusted directly using the mouse or the sliders;
* two horizontal and two vertical handles, whose position can be modified directly using the mouse or the provided sliders, controlling the extent of the area affected by the RT-spot;
* if "Show spot delimiters" is checked in "Preferences" > "General" tab > "Local adjustments", one can visualise approximately the area affected by the spot. Because I couldn’t work cleanly with the « arc/ellipse/scale » function in the Cairo graphics library, I made each quadrant defined by a pseudo-ellipse made of 3 Bézier curves joining each other. In most cases the approximation is satisfying… To help grabbing the 4 handles, I made them longer (the Bézier curves are inactive!).

We obtain 4 zones, whose orientation cannot be modified (the default rotation angle is set to zero). Those 4 zones have each of their vertices connected by imaginary ellipses.

It is possible to drag the handles outside the image preview area.

It should be possible to replace the ellipse with a hand drawn curve (even if I think its usefulness is debatable because of the existence of the shape detection algorithm), as long as the homothetic transform of the curve doesn’t intersect with the original curve. Although the benefits from this intellectually satisfying “improvement” should negligible in the case of the RT-spots, it will be possible to make the current RT-spots and lasso type of controls coexist eventually.

===The "normal" and "excluding" types of RT-spots===
Two types of RT-spots are available:
* "Normal": these are the spots which do the local retouching. Each new RT-spot takes into account the effect of existing spots when their zone of influence overlap (a sort of recursive action).
* "Excluding": adding a new "excluding" RT-spot allows to revert the effect created by a "normal" RT-spot in their overlapping zone of influence , from the original image data (but doing its calculations from the reference values of the area affected by the "normal" RT-spot).

For both types, the user has access to most of the modules ("Color and Light", "Contrast by detail levels", "Blur", ...)

====Comments about the "excluding" RT-spot====
* The principle of the "excluding" spot is similar to the "counterpoint" in Capture NX2, and is useful when for example, the effect of a "normal" RT-spot bleeds into an area which the user wants to be unaffected. This unwanted effect happens when when the tints of the two areas (the area the user wants to be affected, and the area one wants to remain unaffected) are to close.
* The underlying algorithm is similar to the main algorithms used elsewhere in "locallab", and is based on tint differences. While it's not perfect it should give satisfaction 70% of the time.
* I implemented an additional algorithm (with no guarantee that it will actually work one day) to help discriminate the areas, based on a Sobel-Canny transform. The transform is coded but is not yet accessible to the user, as I'm still working to make it more efficient.

====How to use the "excluding" RT-spot, and its limitations====
# Create a new RT-spot over the area you want to restore.
# In the "Settings" panel, from the "Spot method" combobox choose "Excluding spot".
# Adjust "Scope", "Transition" and "Spot size" as well as the shape of the zone of influence using the 4 handles, until you get the desired reversion of the effect. You can use complimentary adjustments such as "Color and light", etc.
The algorithm computes the reference values (tint, chroma, luma) from the the current image (see below). As a consequence, the "excluding" effect won't work if the image area is black (for example when the user uses a normal RT-spot using "Color and light" in inverse mode to create a black frame).
Sometimes, when the "inverse" mode is selected, the "excluding" spot algorithm may not work as expected and lead to a difference between the preview and the output (JPG, TIFF) image. Increasing the value of "Scope" of the "excluding" RT-spot should help in this situation.

===Tint, chroma, luminance references and the algorithm principle in “normal” mode===
In order to develop an efficient shape detection algorithm:
* The central circle zone is used as the reference. Based on the diameter value chosen by the user, the algorithm computes the tint (hue), chroma and luminance averages.
* The choice of the central zone diameter depends on the use intent. For example, if working on a foliage area the user would benefit from choosing a smaller diameter value in order to select only the foliage green; in contrast, for skin tones the user should increase the diameter to avoid the detection of parasites (noise, eye lashes…).
* For each quadrant, depending on the the value of the “Scope” slider, the algorithm does:
# take into account the tint difference between the zone centre and the affected pixel;
# through a complex algorithm based on the deltaE notion (perceived difference between two colours, taking tint, chroma and luminance into account), decrease the amount of applied effect as a function of the difference between the central zone and the affected pixel;
# follow either a linear or a parabolic law to adjust the amount of applied effect, based on the specific the case.

This allows adapting the amount of effect according to the above-mentioned criteria. For example, if the central circle is located on foliage, the action will be limited to the leaves, without touching the background (which would be impossible to obtain with the lasso type of controls). Additionally, if some other foliage resides within the area covered by the RT-spot, it will also be affected.
* Adjusting the value of the “Transition” slider modifies the transition of the effect (from the centre to the edge): on 50, the inner (linear) half will get the full 100% action/effect, while the effect in the outer half will gradually transition from 100% to 0% towards the edge;
* By increasing the value of “Scope”, progressively more of the selected area is taken into account, whatever the tint, chroma and luminance;
* Conversely, by decreasing the “Scope” value the effect will get limited to the pixels which are more similar (in terms of deltaE) to the reference zone.

The shape detection algorithm works in “Normal” mode except for some modules (“Denoise”). It’s not implemented in “Inverse” mode, doing so would not make sense.

The algorithm will see its performance increase when the user chooses “Enhanced” or “Enhanced + chroma denoise” in the “Global quality:” combobox. The second choice additionally applies a low amount of chroma noise reduction in order to get rid of artefacts which could be brought up by the “Enhanced” algorithm (note that the chroma denoise step increases memory use and computing time).

The algorithm is used in full capacity for “scope” < 20.

===Why no alternative algorithms?===
It should be possible to implement other shape detection algorithms than the deltaE-based one used currently, for example:
* edge detection algorithms such as “Canny” or “Sobel”;
* wavelet decomposition.

But in both cases, everything would have to be done!

===Functioning in “inverse” mode===
When it is available, the “Inverse” mode is extremely simplified: only the “Transition” slider can be used to apply the effect.
As of late October 2017, I devised a new method for “Inverse” mode. It is limited to the “Blur & Noise” module (see the corresponding section below).

===Maximum number of RT-spots===
By default the number of available RT-spots is 8. You can choose any number between 2 and 499. For this you only need to change the parameter “Nspot” in the “options” file (for example: Nspot=12). Restart RawTherapee for the modification to be taken into account.

===The “super” algorithm===
The key to “success” was the algorithm implemented in late January 2017, which works this way:
# on the pixel data which are within the area covered by the RT-spot, the algorithm applies either a “traditional” curve, a slider, or a normal transfer function (“Retinex”, “Tone Mapping”, “Contrast by detail levels”, “Vibrance”, …);
# the LUT or the transfer function is converted into an equivalent of a slider, separating negative and positive values so that the function can be viewed as multiple sliders (as many sliders as there are pixels) in the -100, 0, +100 interval;
# the data are passed to the shape detection function – the 4 quadrants. For every pixel, the difference in terms of tint, chroma and luma is computed with regards to the central reference. The linear variation equations are estimated for luminance (L=f(L)), chroma (C=f(C)) or transfer functions;
# different corrections are applied to account for the environment (sky, skin tones…)
# a correction is made (with threshold and iterations) in order to avoid correcting (or only slightly, based on the user’s choice) the grey or neutral tones which are in the same tint as the reference (but with a low chroma value);
# the parameters are weighted based on the shape of the RT-spot (ellipses) and the transition zone;
# the values of the “Global quality:” parameters are important, particularly so for images with a low amount of noise – chroma noise is interpreted by the algorithm being of the same colour as the spot. It is thus necessary to suppress this noise, that is the purpose of “Enhanced + chroma denoise” (this algorithm may not be sufficient, though – in this case using the local “Denoise” module may be useful).

This new (“super”) algorithm seems to perform generally well, but in the event when the RT-spot is located in a grey/neutral or flat area, the algorithm may fail. In such cases, using the old algorithm is recommended (except for “Retinex”, “Tone Mapping” and “Contrast by detail levels” for which it is made unavailable for the sake of code simplicity).

===Artefact reduction and the “Global quality” algorithms===
By default, “Global quality:” is set to “Enhanced + chroma denoise”. Whereas it increases computation time, it is still generally preferable. In case one wants a more responsive preview, “Enhance” or “Standard” can be chosen (good for exploring the image).
* two sliders allow reducing artefacts and improving the algorithm’s rendering. They work based on chroma, in neutral/gray tones. To completely remove its effect, one can simply set “iterations=0”. These sliders may be used for "Color light", "Exposure", "Retinex", "Vibrance", "Tone mapping" and "Contrast by detail levels";
* for (even slightly) noisy images, the algorithms may be misled. In this case it is recommended to keep "Global quality:” set to “Enhanced + chroma denoise", and (sometimes) activate the local “Denoise” module and adjust the sliders very gently (including “Luminance”);
* under some circumstances, with “Tone Mapping” for example, the artefact reduction algorithm may actually generate more artefacts. When it happens, set “iterations=0”.

If your images are generally clean (no or very low noise), you can choose to have “Standard” as the default for “Global quality:” – this will speed up the image processing. To do so, go to “Preferences” > “Performance and quality” tab > “Local adjustments” and choose the “Standard” algorithm among the 3 options. This will become the new default when new RT-spots are created, but of course the algorithm can still be changed on the fly by choosing from the “Global quality” combo box.

===Avoid color shift===
The “Avoid color shift” checkbox serves two purposes:
* put the colours within the current working profile gamut, using a relative colorimetry;
* adjust colours using a “Munsell” correction – particularly for red-orange and blue-purple colours, when saturation in the L*a*b* space has changed significantly.

===“mip” files – Principles of the multi-point algorithm===
For the local control system to work and keep track of RT-spot objects, a text file – similar to a pp3 – is written in 2 possible places:
* next to the edited image file. If, for example, you edit an image named ASC4509.NEF, a new file named ASC4509.NEF.mip will be generated in the same folder. In this case, several sessions can be open for the same image, as long as copies of the image are stored in different folders. However, the folder names in the path have to contain ASCII characters only, otherwise it will make the program crash;
* in the dedicated “mip” folder, within the “cache” directory (through an MD5 hash number which identifies the file). This is the default. If chosen, when multiple copies of the same file exist in distinct folders, editing them creates as many “mip” files. This option allows the use of non ASCII characters in the folder names and path.

The choice between these two behaviours is made in “Preferences” > “Image processing” tab > “Mip profiles”.

The “mip” files contain the data which are passed to RawTherapee through processes of the “procparams” type, and LUTs which allow editing in zoom mode. When updating RawTherapee to a new version, it may be required to delete the “mip” files (or the whole cache) to avoid a potential crash of the application. This can be achieved by going to “Preferences” > “File browser” tab, then choosing “Clear mip” and/or “Clear pp3” – all this is valid only if “mip” and “pp3” files have been set to be saved to the cache folder, otherwise they will have to be manually deleted from the working folder. Keeping older “mip” and “pp3” files may lead to instability or crashes of the application.

====Architecture of the filter====
When I “ventured” into a multi-point, no-layer and no-mask system, code duplication had to be avoided. Indeed, it is unthinkable to consider, for 10 RT-spots, generating 10 GUI code blocks, and just as many code blocks in “rtengine”. After careful consideration, the idea was to have a file updating and tracking in real time – i.e. a file which would follow each modification made by the user – the actions/modifications history.

Of course, the parameters used by RawTherapee for the GUI and for the main code through “params” are of different types:
* numeric: integer, float, double,…
* Boolean
* string (in choice menus for the different modules)
* curves, through “vectors” of type double with dynamic dimension
* …

====Data conversion====
In order to simplify data management, the first step is to convert all data to integers. Sometimes this can lead to a slight precision loss, which I think is negligible.
* This operation is very simple for numeric values, even though in some cases (such as hue, which is expressed in radian in the interval [-Pi, +Pi]) it needs a double “float*100 and /100 conversion to keep precision.
* It is logical for Boolean operations and methods.
* However, it is a complex matter regarding curves. The values to be recorded in the “mip” file are of type vector<double>, in a dynamic table of numeric values. There may be a simpler way, by using existing functions from “procparams”, but I didn’t succeed.
Nevertheless, I could get around this by:
# converting doubles to integers with 3 significant figures – which is largely enough,
# then converting the “vector” to a variable length character string,
# the writing and reading of this character string and converting to a vector dynamically using an appropriate function (”strcurv_data”). Note that this function allows adjusting the curves within the limit of 16 inflection points (Bézier curve) for the flat curve, and 32 points for the diagonal, which should be enough. Whether this would not be enough, it should be possible to increase that number, though compatibility would be compromised.

====Some elements about curves====
The implementation of curves has been a complex task, particularly since:
# each curve needs its own reset function – resize() at each iteration,
# which implies oddities regarding their description, for example the diagonal curve gets initialised with several points, despite it looks being “empty”. This is mandatory for correct functioning, but this means that the curve is always open/active. Consequently, to avoid some unwanted loss of computation time in “preview” mode, the user has to activate the curve by clicking on the “curves” combobox. The same activation is necessary for L=f(H) and C=f(C) curves. While clicking enabling the “curves” (linear) would seem to be a better solution, it didn’t work despite many trials.
# during all the procedure, we need to set each "params" value to "clear" for curves, for each LUT, at each iteration and then through a "vector" to reassign the good, updated values to "curve params".

====Data storing and dynamic use====
Once data have been converted:
* they are stored in a text (mip) file,
* each one is referenced inside a 2-dimension dynamical table:
# dataspot[x][y] for numeric and boolean values and methods, where “x” is the representative index of the parameter (e.g. “9” is for “lightness”) and “y” represents the current RT-spot (control spot). Value “0” represents the current in-use value (the one stores in “params”).
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] for parameters of type “curve”. Currently there are only 8 parameters, used for local “Retinex”, “Color and light” (L=f(L), C=f(C), L=f(H), H=F(H)), “Vibrance” and “Exposure”, but it is easy to add more. “y” is used as above in 1.

The way data are stored and used fits well with improccoordinator.cc (current management / preview) and simpleprocess.cc (TIFF / JPG output) files, but not so with dcrop.cc and the partial display of the image (RawTherapee’s pipeline).

In this case (zoom / preview) another solution had to be found in order to synchronise the modifications in real time. I made use of LUTs, so that to each entry referenced in the table described above a LUTi(z) is associated, with z=500 possible entries (500 corresponds to the current maximum number of RT-spots, but this limit can be decreased or increased). The LUTi “z” corresponds to the dataspot “y”. A 25,000 entries LUTi (arbitrary number) is used for “retistr”, “llstr”, “lhstr”, “ccstr”, “hhstr”, “skinstr”, “pthstr”, “exstr” for storing each “vector” curve value in memory (up to 69 values stored as integers).

During data processing, exchanges occur between: params, dynamic tables and LUTi. The values used by dcrop.cc are dynamically linked to dynamical tables by parent→.

====Exchange processes and dynamic data storing====
# reading of the “mip” file to check the version number and guide the updates
# creating the “mip” file if it doesn’t exist
# storing the data in LUTi and dynamic tables from the values stored in “params” (index 0 values)
# first interactive update with the GUI through a transfer function between “rtengine” and locallab.cc (aloListener → localretChanged). This is one of the 3 functions required for the process to work correctly
# reading of the “mip” file and data storing in dynamic tables (index values ==> y) according to the number of RT-spots
# creating a loop – according to the number of RT-spots – which updates LUTi (required by “dcrop”) and “params” values from values stored in the dynamic tables
# call to the “Lab_local” function which contains the algorithms controlling each RT-spot (luminance, sharpness, retinex, denoise, …)
# second interactive update with the GUI through another transfer function between “rtengine” and “locallab.cc”
# treatment of the current RT-spot by using the index (0) values from the dynamic tables. These values are attributed to 1) “params”, 2) LUTi and 3) current index values
# call to the “Lab_local” function for the current RT-spots
# saving to the “mip” file.

Note that if the user modifies the curve (amplitude, number of inflection points) a third interactive update is made in order to conform all of the data according to events.

====A few unavoidable “fantasies”====
Of course everything looks simple, the process works if, and only if, all the data are dynamically updated. I’ve tried a lot, went groping, and finally found a working solution… but an uncanny one. There’s probably a more “informatically” correct way to do it, but at this point I’ve done as explained above and hereafter.

The 3 exchanges between “rtengine” and the GUI occur with 3 parameters which actually do nothing in the program except doing the update process:
# “anbspot” which takes values of 0 or 1
# “cTgainshaperab” (curve) which takes any value bewteen 0.70 and 0.90
# “retrab” which varies around 500.
I have added 3 more parameters (in the form of sliders) – hueref, chromaref and lumaref – hidden from the user but which are used to update the system in real time, to correctly take into account the reference “spot” values. Allowing those 3 parameters to vary brings stability and allows real time updates. Increasing the number of those “fantasy” parameters should not be necessary. These extra parameters are hidden to the user, and are only visible in the history.

In addition, I had to add some empirical time delays, giving time to time… Time delay is used for example when the user modifies the curve (amplitude, number of inflection points).

==Specificity of the local mode (as compared to “Lab adjustments”)==
Hereafter is some useful information for the user, often specific to the local mode.

===Color and Light===
* The algorithms used for luminance and contrast in local mode differ from the ones used in “Lab adjustments”, which may lead to differences in rendering.
* The luminance algorithm is made such that below -90 and down to -100 for “Lightness”, it is possible to increase the image's “darkness”, almost to the point of getting a luminance value close to 0. To accentuate this effect, “Chrominance” can be decreased and “Scope” increased.
* The inverse mode can be used for creating graduated frames. If “Ligthness” is set to -100 and "Chrominance" is reduced, the “frame border” will be black.
* For the “Lightness” and “Contrast” sliders, the user can choose among 2 algorithms: the first one (default) is close to that in “Lab adjustments” while the second one, activated through “Lightness - Contrast ‘Super’” is close to the algorithm used for the L=f(L) “Super” curve.
* Do not hesitate, when needed, to activate “Enhanced” or “Enhanced + chroma denoise” in the “Global Quality:” combobox.

====Curves====
* An L=f(L) or C=f(C) curves allow controlling the luminance and chrominance for each RT-spot as a function of luminance or chrominance.
* An L=f(H) curve allows controlling the luminance for each RT-spot as a function of tint.
* An H=f(H) curve allows controlling the tint for each RT-spot as a function of tint.
The curves are activated by selecting one of the two algorithms from the “Curves types” combobox:
* “Normal”: the curves – particularly the one that is the most difficult to manage, L=f(L) – use an algorithm close to the one used with the sliders (Normal mode),
* “Super”: using a new algorithm, which I think performs very well (it even surprised me the first time I used it).

Caution: when the RT-spot resides in an area which is neutral, grey or very uniform, the artefacts introduced by the new algorithm (“Super” algorithm for the curve or the slider) may be impossible to get rid of. Use one of the 2 older algorithms to avoid that.

===Exposure===
The “Exposure” module may look like the the one in global RGB mode, but:
* it works entirely in L*a*b* mode, hence the differences in rendering;
* there’s no “Lightness”, “Chroma” or “Contrast” slider, whose functions are already fulfilled in the “Color and Light” module;
* there’s only one “Contrast” curve, similar to the L=f(L) firm “Color and Light”. Of course its effect is different from “Tone curve” which works in RGB mode. If needed, two L=f(L) curves can be activated, one under “Color and Light” and the other under “Exposure”.

===Vibrance===
This module is similar to the main one (from RawTherapee's "Exposure" tab).

===Blur & Noise===
“Blur” is activated only when “Radius” =< 2.
By significantly lowering the default value of “Scope” and possibly checking “Blur luminance only”, it is possible to get a different amount of blur for the different tints.
Since October 2017, 3 methods are proposed:
* “Normal”: the shape detection algorithm has been improved, it is now closer to shape detection algorithm proposed in the other modules;
* “Inverse”: a simplified algorithm, which doesn’t make use of “Scope”. The inversion is coarse and doesn’t allow a fine separation between the affected and unaffected areas;
* “Symmetric”: this new algorithm uses the same processes as “Normal”, and adjusting “Scope” the user can target the process with more precision.
Caution:
* Using the “Inverse” mode will blur large portions of the image, which can not be corrected later on.
* The action of “Scope” may sometimes appear puzzling: for instance, in a portrait, the eyes (which of course differ from the skin) may be blurred if the value of “Scope” is too low.

===Tone Mapping===
Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Retinex===
Compared to the standard “Retinex” module, the local “Retinex module has simplified controls, and is applied at the end of the pipeline instead of the beginning. Since “mip” version 10002, the “Transmission gain” is specific to each RT-spot.

===Sharpening===
Only the “RL Deconvolution” algorithm is provided here.

===Contrast by detail levels===
Compared to the main RGB mode module, this one has:
* 5 levels instead of 6,
* no slider for “skin tone” protection (not needed since the algorithm works locally on the RT-spot area),
* an additional “Chroma” slider.

Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Denoise===
Compared to the main RGB mode module, this one has:
* only the wavelet tool working (no Fourier function, nor medians),
* less sliders and curves,
* the possibility to work differentially on fine or coarse noise for both luminance and chrominance noise.

==A specific use case : reduction of image defects (dirty sensor, red eyes, …)==
“Locallab” had not been thought with the idea of correcting small image defects. However, some visible, “photographically disturbing” defects may actually be tamed or even removed. Of course, this is not incompatible with other more specialised modules which could be introduced (or not) into “Locallab”… At least 3 existing modules can serve this purpose, alone or in combination, by adapting their use:
* “Color and Light” for spot-like defects;
* “Contrast by detail levels” for spread out defects;
* “Blur and Noise” as an optional complement (caution, this is a destructive action, use moderately).

These modules can be used either on the main image (raw, TIFF, …) or on a flat-field image.

===Using the “Color and Light” module===
* Activate “Color and Light”
* A red eye removal tool equivalent can be obtained by framing closely around the eye – central circle zone centered on the eye’s red, spot handles close to the eye – low “Scope” value, then lowering “Lightness” and “Chrominance” to -100.
* The same idea allows reducing the “IR spot” kind of defect by framing closely around the defect – central circle zone centred on the defect, spot handles close to the defect area – then lowering “Chrominance” to taste, and if needed lowering the “scope” value.
* In some (simple) situations, a “dirty sensor” defect can be reduced, in particular in the case of “sensor grease”. It can be seen as stains or spots on a uniform background. To attenuate this, choose a tight framing of around the defect – central circle on the centre of the defect (adapt the size of the RT-spot), drag the handles so that they are not too close to the border of the defect (this will make the transition less noticeable). Then: a) decrease “Transition” towards lower values; b) check “Lightness - Contrast “Super”; c) adjust “Lightness” and “Chrominance” as needed to bring the defect area closer to the unaffected area; d) if needed adjust slightly “Scope” to achieve the best result.

===Using the “Contrast by detail levels” module===
When the sensor is dirty (grease), and when the affected area is large or if there are multiple small defects, “Contrast by detail levels” may be used, working as a sort of “wavelet” tool on luminance, and if needed on chrominance. In such cases: a) place the RT-spot on one of the stronger defects (adjust the size as needed); b) drag the handles so as to cover most of the affected area; c) set “Transition” to higher value; d) activate “Contrast by detail levels” and decrease the contrast of levels 3 and 4 (or lower); you can adjust the “Chroma” slider if needed.

==Settings in the Preferences dialog==
Below is a list of the settings (already mentioned above in several places) which can be accessed from the “Preferences” dialog:
* In “Preferences” > “General” tab > “Local adjustments”, by checking the “Show spot delimiters” checkbox, an approximate zone delimitation is drawn which helps viewing the area affected by the RT-spot and its settings.
* If your images generally have low noise, you can set the default for “Global quality” to “Standard”, and get a significant speedup in processing time. This setting is found under “Preferences” > “Performance & Quality” tab > “Local adjustments”. The three choices for quality are selected from the “Local adjustments Quality method” combobox. Default is “Enhanced + chroma denoise”.
* Regarding “mip” files:
** the choice for “mip” files destination folder is set from “Preferences” > “Image processing” tab > “Mip Profiles”;
** in order to clean the generated “mip” profiles, go to “Preferences” > “File Browser” tab > “Cache Options” and click on the “Clear mip” button and/or “Clear pp3” – this is valid in the case where you chose to store “mip” files in the cache, otherwise if you chose to let RT write the “mip” files next to the input file, you will have to delete them manually. Note that the presence of older versions of “mip” and “pp3” files may lead to instability or even crashes of RawTherapee.

==Processing time and memory use==
At image export time (output to JPG, TIFF…), for the “normal” mode, the algorithms compute the data only for in the RT-spot delimited areas, not for the whole image. Thus, processing time and memory stay reasonable. Note that of course, this will depend on the number of RT-spots, their size, and the type(s) of treatment done in these RT-spots.

Excluding “Denoise” and “Sharpen”, processing time is in the order of a few tenths of a second per RT-spot, and memory use of a few hundred MB.

Two settings have a strong influence on resource use:
• “Denoise” which adds around 1 sec. of processing time, and 1 MB of memory use;
• “Global quality: Enhanced + chroma denoise” which adds around 0.5 sec. And 0.6 MB.
These figures depend on the size of the RT-spot.

==Future evolution==
Besides usual tweaking, bug corrections, improvements (settings, user interface)… it would be desirable to improve the GUI with regards to the creation/selection/modification of individual RT-spots.

From a programming point of view, it should be possible to improve code readability and maintainability, and to integrate all the “mip” files code parts (as done in “rgbproc.cc”) which currently are linearly integrated to void procedures in “improccoordinator.cc”, “dcrop.cc” and “simpleprocess.cc”.

Local Lab Controls

2017-11-10T20:35:52Z

Sguyader: Add the information regarding the "excluding" RT-spot

==What kind of local control?==

Several types of local control exist in mainstream applications :
# “lasso”, associated with layers and fusion masks (e.g. Photoshop©). This kind of control is widespread (Photoshop, Gimp, Darktable…) and users tend to favor those, at the expense of the type described in 3. below, which is less well known;
# dedicated tools for the removal of image defects such as “red eyes”, or “spots” associated with sensor imperfections or dirt;
# “U-points” controls, used until recently in Nikon Capture NX2©, or as an add-on to other software such as Nik Software©. For those (rare now) who tried such programs, there’s no way turning back to layers and fusion masks! This type of local control requires learning something different, and a cognitive “reprogramming”. In my opinion, this kind of local control is globally more efficient.

The algorithm developed in the current version of RawTherapee is close in its principle to the U-points described above. Of course, the code used in Nik Software is not disclosed, but several years ago I was attracted by the simplicity of use and the efficiency of U-points, and I started developing a product which would use neither lassos, nor layers or fusion masks. Of course, nothing prevents us from having all 3 types of local control in the same program.

The current version of the filter is perfectible, particularly regarding the user interface (GUI):
* for managing and viewing the RT-spots (control spots) on screen,
* for manipulating the different sliders, which would ideally be better if integrated to the actual control points, as done in Nik Software.

However, those two aspects don’t harm everyday use, nor code portability.

In order to improve manipulation and avoid long menus on screen, I added a GUI interface which is similar to the one used in the Wavelet tab, with “expanders”. Thus for each module (“Color and Light”, “Blur”, “Retinex”, …) you can choose to:
# display (or not) the full list of commands: sliders methods, curves…
# activate (or not) all the functions of the module.

Warning: The second choice activates or cancels all the RT-spots. (It would be possible in theory to add this capability to every single RT-spot, but for what purpose?)

===Lab and RGB local controls===
* The first algorithms are coded in L*a*b* mode with the following modules: “Color and Light”, “Blur / Add noise”, “Retinex”, “Tone mapping”, “Sharpen”, “Contrast by Detail Levels”, “Denoise”. Two additional modules have been added: “Exposure” and “Vibrance”.
* See below for the principles of the different algorithms, but one key point to remember for shape detection and artifact limitation, is that the Lab mode preserves the “hue” tint, which is crucial.
* The idea of an “RGB” module comes to one’s mind, with ''a minima'':
** a “White balance” module, which would allow to locally adjust the white balance, for example to warm up shadows, or to deal with mixed scene lighting such as “daylight” and “tungsten”. This module needs to be inserted just after “demosaic”.

====Auto White balance====
The “White balance” module (in the “autowblocal” branch) serves two purposes:
* allowing a local adjustment of the white balance (of course)
* testing new algorithms for automatic white balance adjustment:
** in general use (full image), in order to achieve better results than with the current algorithm. Of course one will tell me that I should create a specific branch for “White balance”, but here I’m trying to hit two targets with one bullet.

As a reminder, I’ve been asked in 2012 and 2013 to develop an iterative white balance “Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]”. At that time, another developer and I had spent a lot of time on this for an unsatisfactory result, so we gave up. Since then, benefiting from this experience, I resumed this work but in the reverse way! Now, if I’m correct, the algorithm works. I took advantage of this new capability (currently working on raw images only) to search in the academic literature for other auto WB algorithms. I found, and developed two new algorithms:
* “auto edge”[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]: the idea is to create an accentuation mask allowing to reinforce parts of the image where details are more prevalent, compared to flatter regions.
* “auto standard deviation”[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]: here, the image (or part of it for the local control) is divided in 12 zones, for each of which mean and standard deviation are computed, and the result assembled.
A third algorithm, “Color by correlation”[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf], looks promising but I’m facing several difficulties. After many trials of many types, the results are just too erratic…

I also added the notion of gamma:
* the same principles which deal with luminance distribution – gamma sRGB – used in the main RawTherapee code.

Bear in mind that the automatic white balancing is a totally non deterministic mathematical problem. The algorithms may perform more or less well (and faster or slower), but a perfect result can’t exist! Why is it so? If one is referring to the principles of color management ([http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]), it is necessary to have knowledge of the three of: the coloured object, the illuminant and the observer. At least two of those are unknown in practice. In addition, the environment in which an image is shot is not known while it has an effect on the perception (CIECAM), and the same is true during both image editing and viewing. The mission is thus almost impossible!

The aim of the “White balance” module is '''for testing the algorithms''', there are 7 of them at least, and twice that number if “gamma sRGB” is considered. Indeed, in order to circumvent the obstacles encountered five years ago, instead of the using the image before demosaicing, I used the image just after demosaicing, allowing to apply (or not) “gamma sRGB”, ending in the same conditions as in normal use (but without normal “White balance” and “ICC or DCP” profile).

Ideally, we should test the algorithms on many images, as well: which algorithm(s) to keep and implement in normal – global RGB – mode (maybe one or two, in addition to the current algorithm which we should keep for compatibility).

====Local control of White balance====
The local control is currently limited to 1 spot only, but there’s no difficulty to increase this if users want so… while waiting for the evolution of “locallab”.

Of course, I hear voices say “it doesn’t work”, or “the output doesn’t match with the preview”. But it does work! And it is more than evident that matching exactly the preview is by definition almost impossible… (differences between shadows, sun light, different illuminants, etc…) whatever the relevance of the algorithm.

==What are the challenges we need to solve?==
Several general issues need to be solved so as to achieve smoothness in use:
* allow an (almost) unlimited number of RT-spots (the name we chose for the control spots in RawTherapee);
* adapt the local algorithms to be aware of scale, because many of them take the image size – the treated area – into account. This aspect is fundamental, particularly with curves which act on the whole image;
* minimise memory use and computation time for JPG and TIFF output;
* allow easy updates in case of evolution of either the algorithms or the number of methods/modules;
* optimise (minimise) the differences between the preview and the output.
* etc…

For each RT-spot:
* allow for the action to occur, on user choice, either inside or outside (“Inverse” mode) of the selection area;
* allow shape detection, on user choice, in order to limit the action based on features/shapes;
* take care of the transition between the center of the treated area and the other parts of the image;
* etc…

Currently, RT-spots are operational in Lab mode with the following modules and methods:
# “Colour and Light”: “Lightness”, “Chrominance”, “Contrast” in normal mode with 4 curves L=f(L), L=f(H), C=f(C), H=f(H), and in “inverse” mode;
# “Exposure”: normal mode only;
# “Vibrance:” normal mode only;
# “Blur & noise”: normal and “inverse” modes;
# “Retinex”: normal and “inverse” modes, now also with “transmission gain” curve;
# “Sharpening”: normal and “inverse” modes;
# “Contrast by detail levels” (CBDL): normal mode only;
# “Denoise”: normal mode only.

==General principles==
===The RT-spot object===
As I mentioned earlier, the system used in RT is similar to the one developed in Nik Software, but with some significant differences:
* each RT-spot can be viewed as an object with a number of fields (about 70 as of today), made of sliders, curves, control points, etc…;
* each field, grouped in modules, can be activated or not, and have different parameter values according to their nature;
* the modules are made to be coherent for the user: “Color and Light”, “Exposure”, “Contrast”, “Vibrance”, “Blur”, “Retinex”, “Sharpening”, “Tone Mapping”, “Contrast by detail levels”, “Denoise”;
* the number of RT-spot objects can vary from 2 up to 500;
* data describing the RT-spot objects are stored in text files with .mip extension;
* creating, modifying and tracking of the RT-spot objects are done in a “for” loop;
* there’s no code duplication.

===Partitioning into 4 zones – previewing the RT-spot area===
When the user selects an RT-spot, the screen preview shows:
* a centre, made of a circle whose diameter and position can be adjusted directly using the mouse or the sliders;
* two horizontal and two vertical handles, whose position can be modified directly using the mouse or the provided sliders, controlling the extent of the area affected by the RT-spot;
* if "Show spot delimiters" is checked in "Preferences" > "General" tab > "Local adjustments", one can visualise approximately the area affected by the spot. Because I couldn’t work cleanly with the « arc/ellipse/scale » function in the Cairo graphics library, I made each quadrant defined by a pseudo-ellipse made of 3 Bézier curves joining each other. In most cases the approximation is satisfying… To help grabbing the 4 handles, I made them longer (the Bézier curves are inactive!).

We obtain 4 zones, whose orientation cannot be modified (the default rotation angle is set to zero). Those 4 zones have each of their vertices connected by imaginary ellipses.

It is possible to drag the handles outside the image preview area.

It should be possible to replace the ellipse with a hand drawn curve (even if I think its usefulness is debatable because of the existence of the shape detection algorithm), as long as the homothetic transform of the curve doesn’t intersect with the original curve. Although the benefits from this intellectually satisfying “improvement” should negligible in the case of the RT-spots, it will be possible to make the current RT-spots and lasso type of controls coexist eventually.

===The "normal" and "excluding" types of RT-spots===
Two types of RT-spots are available:
* "Normal": these are the spots which do the local retouching. Each new RT-spot takes into account the effect of existing spots when their zone of influence overlap (a sort of recursive action).
* "Excluding": adding a new "excluding" RT-spot allows to revert the effect created by a "normal" RT-spot in their overlapping zone of influence , from the original image data (but doing its calculations from the reference values of the area affected by the "normal" RT-spot).

For both types, the user has access to most of the modules ("Color and Light", "Contrast by detail levels", "Blur", ...)

====Comments about the "excluding" RT-spot====
* The principle of the "excluding" spot is similar to the "counterpoint" in Capture NX2, and is useful when for example, the effect of a "normal" RT-spot bleeds into an area which the user wants to be unaffected. This unwanted effect happens when when the tints of the two areas (the area the user wants to be affected, and the area one wants to remain unaffected) are to close.
* The underlying algorithm is similar to the main algorithms used elsewhere in "locallab", and is based on tint differences. While it's not perfect it should give satisfaction 70% of the time.
* I implemented an additional algorithm (with no guarantee that it will actually work one day) to help discriminate the areas, based on a Sobel-Canny transform. The transform is coded but is not yet accessible to the user, as I'm still working to make it more efficient.

====How to use the "excluding" RT-spot, and its limitations====
# Create a new RT-spot over the area you want to restore.
# In the "Settings" panel, from the "Spot method" combobox choose "Excluding spot".
# Adjust "Scope", "Transition" and "Spot size" as well as the shape of the zone of influence using the 4 handles, until you get the desired reversion of the effect. You can use complimentary adjustments such as "Color and light", etc.
The algorithm computes the reference values (tint, chroma, luma) from the the current image (see below). As a consequence, the "excluding" effect won't work if the image area is black (for example when the user uses a normal RT-spot using "Color and light" in inverse mode to create a black frame).
Sometimes, when the "inverse" mode is selected, the "excluding" spot algorithm may not work as expected and lead to a difference between the preview and the output (JPG, TIFF) image. Increasing the value of "Scope" of the "excluding" RT-spot should help in this situation.

===Tint, chroma, luminance references and the algorithm principle in “normal” mode===
In order to develop an efficient shape detection algorithm:
* The central circle zone is used as the reference. Based on the diameter value chosen by the user, the algorithm computes the tint (hue), chroma and luminance averages.
* The choice of the central zone diameter depends on the use intent. For example, if working on a foliage area the user would benefit from choosing a smaller diameter value in order to select only the foliage green; in contrast, for skin tones the user should increase the diameter to avoid the detection of parasites (noise, eye lashes…).
* For each quadrant, depending on the the value of the “Scope” slider, the algorithm does:
# take into account the tint difference between the zone centre and the affected pixel;
# through a complex algorithm based on the deltaE notion (perceived difference between two colours, taking tint, chroma and luminance into account), decrease the amount of applied effect as a function of the difference between the central zone and the affected pixel;
# follow either a linear or a parabolic law to adjust the amount of applied effect, based on the specific the case.

This allows adapting the amount of effect according to the above-mentioned criteria. For example, if the central circle is located on foliage, the action will be limited to the leaves, without touching the background (which would be impossible to obtain with the lasso type of controls). Additionally, if some other foliage resides within the area covered by the RT-spot, it will also be affected.
* Adjusting the value of the “Transition” slider modifies the transition of the effect (from the centre to the edge): on 50, the inner (linear) half will get the full 100% action/effect, while the effect in the outer half will gradually transition from 100% to 0% towards the edge;
* By increasing the value of “Scope”, progressively more of the selected area is taken into account, whatever the tint, chroma and luminance;
* Conversely, by decreasing the “Scope” value the effect will get limited to the pixels which are more similar (in terms of deltaE) to the reference zone.

The shape detection algorithm works in “Normal” mode except for some modules (“Denoise”). It’s not implemented in “Inverse” mode, doing so would not make sense.

The algorithm will see its performance increase when the user chooses “Enhanced” or “Enhanced + chroma denoise” in the “Global quality:” combobox. The second choice additionally applies a low amount of chroma noise reduction in order to get rid of artefacts which could be brought up by the “Enhanced” algorithm (note that the chroma denoise step increases memory use and computing time).

The algorithm is used in full capacity for “scope” < 20.

===Why no alternative algorithms?===
It should be possible to implement other shape detection algorithms than the deltaE-based one used currently, for example:
* edge detection algorithms such as “Canny” or “Sobel”;
* wavelet decomposition.

But in both cases, everything would have to be done!

===Functioning in “inverse” mode===
When it is available, the “Inverse” mode is extremely simplified: only the “Transition” slider can be used to apply the effect.
As of late October 2017, I devised a new method for “Inverse” mode. It is limited to the “Blur & Noise” module (see the corresponding section below).

===Maximum number of RT-spots===
By default the number of available RT-spots is 8. You can choose any number between 2 and 499. For this you only need to change the parameter “Nspot” in the “options” file (for example: Nspot=12). Restart RawTherapee for the modification to be taken into account.

===The “super” algorithm===
The key to “success” was the algorithm implemented in late January 2017, which works this way:
# on the pixel data which are within the area covered by the RT-spot, the algorithm applies either a “traditional” curve, a slider, or a normal transfer function (“Retinex”, “Tone Mapping”, “Contrast by detail levels”, “Vibrance”, …);
# the LUT or the transfer function is converted into an equivalent of a slider, separating negative and positive values so that the function can be viewed as multiple sliders (as many sliders as there are pixels) in the -100, 0, +100 interval;
# the data are passed to the shape detection function – the 4 quadrants. For every pixel, the difference in terms of tint, chroma and luma is computed with regards to the central reference. The linear variation equations are estimated for luminance (L=f(L)), chroma (C=f(C)) or transfer functions;
# different corrections are applied to account for the environment (sky, skin tones…)
# a correction is made (with threshold and iterations) in order to avoid correcting (or only slightly, based on the user’s choice) the grey or neutral tones which are in the same tint as the reference (but with a low chroma value);
# the parameters are weighted based on the shape of the RT-spot (ellipses) and the transition zone;
# the values of the “Global quality:” parameters are important, particularly so for images with a low amount of noise – chroma noise is interpreted by the algorithm being of the same colour as the spot. It is thus necessary to suppress this noise, that is the purpose of “Enhanced + chroma denoise” (this algorithm may not be sufficient, though – in this case using the local “Denoise” module may be useful).

This new (“super”) algorithm seems to perform generally well, but in the event when the RT-spot is located in a grey/neutral or flat area, the algorithm may fail. In such cases, using the old algorithm is recommended (except for “Retinex”, “Tone Mapping” and “Contrast by detail levels” for which it is made unavailable for the sake of code simplicity).

===Artefact reduction and the “Global quality” algorithms===
By default, “Global quality:” is set to “Enhanced + chroma denoise”. Whereas it increases computation time, it is still generally preferable. In case one wants a more responsive preview, “Enhance” or “Standard” can be chosen (good for exploring the image).
* two sliders allow reducing artefacts and improving the algorithm’s rendering. They work based on chroma, in neutral/gray tones. To completely remove its effect, one can simply set “iterations=0”. These sliders may be used for "Color light", "Exposure", "Retinex", "Vibrance", "Tone mapping" and "Contrast by detail levels";
* for (even slightly) noisy images, the algorithms may be misled. In this case it is recommended to keep "Global quality:” set to “Enhanced + chroma denoise", and (sometimes) activate the local “Denoise” module and adjust the sliders very gently (including “Luminance”);
* under some circumstances, with “Tone Mapping” for example, the artefact reduction algorithm may actually generate more artefacts. When it happens, set “iterations=0”.

If your images are generally clean (no or very low noise), you can choose to have “Standard” as the default for “Global quality:” – this will speed up the image processing. To do so, go to “Preferences” > “Performance and quality” tab > “Local adjustments” and choose the “Standard” algorithm among the 3 options. This will become the new default when new RT-spots are created, but of course the algorithm can still be changed on the fly by choosing from the “Global quality” combo box.

===Avoid color shift===
The “Avoid color shift” checkbox serves two purposes:
* put the colours within the current working profile gamut, using a relative colorimetry;
* adjust colours using a “Munsell” correction – particularly for red-orange and blue-purple colours, when saturation in the L*a*b* space has changed significantly.

===“mip” files – Principles of the multi-point algorithm===
For the local control system to work and keep track of RT-spot objects, a text file – similar to a pp3 – is written in 2 possible places:
* next to the edited image file. If, for example, you edit an image named ASC4509.NEF, a new file named ASC4509.NEF.mip will be generated in the same folder. In this case, several sessions can be open for the same image, as long as copies of the image are stored in different folders. However, the folder names in the path have to contain ASCII characters only, otherwise it will make the program crash;
* in the dedicated “mip” folder, within the “cache” directory (through an MD5 hash number which identifies the file). This is the default. If chosen, when multiple copies of the same file exist in distinct folders, editing them creates as many “mip” files. This option allows the use of non ASCII characters in the folder names and path.

The choice between these two behaviours is made in “Preferences” > “Image processing” tab > “Mip profiles”.

The “mip” files contain the data which are passed to RawTherapee through processes of the “procparams” type, and LUTs which allow editing in zoom mode. When updating RawTherapee to a new version, it may be required to delete the “mip” files (or the whole cache) to avoid a potential crash of the application. This can be achieved by going to “Preferences” > “File browser” tab, then choosing “Clear mip” and/or “Clear pp3” – all this is valid only if “mip” and “pp3” files have been set to be saved to the cache folder, otherwise they will have to be manually deleted from the working folder. Keeping older “mip” and “pp3” files may lead to instability or crashes of the application.

====Architecture of the filter====
When I “ventured” into a multi-point, no-layer and no-mask system, code duplication had to be avoided. Indeed, it is unthinkable to consider, for 10 RT-spots, generating 10 GUI code blocks, and just as many code blocks in “rtengine”. After careful consideration, the idea was to have a file updating and tracking in real time – i.e. a file which would follow each modification made by the user – the actions/modifications history.

Of course, the parameters used by RawTherapee for the GUI and for the main code through “params” are of different types:
* numeric: integer, float, double,…
* Boolean
* string (in choice menus for the different modules)
* curves, through “vectors” of type double with dynamic dimension
* …

====Data conversion====
In order to simplify data management, the first step is to convert all data to integers. Sometimes this can lead to a slight precision loss, which I think is negligible.
* This operation is very simple for numeric values, even though in some cases (such as hue, which is expressed in radian in the interval [-Pi, +Pi]) it needs a double “float*100 and /100 conversion to keep precision.
* It is logical for Boolean operations and methods.
* However, it is a complex matter regarding curves. The values to be recorded in the “mip” file are of type vector<double>, in a dynamic table of numeric values. There may be a simpler way, by using existing functions from “procparams”, but I didn’t succeed.
Nevertheless, I could get around this by:
# converting doubles to integers with 3 significant figures – which is largely enough,
# then converting the “vector” to a variable length character string,
# the writing and reading of this character string and converting to a vector dynamically using an appropriate function (”strcurv_data”). Note that this function allows adjusting the curves within the limit of 16 inflection points (Bézier curve) for the flat curve, and 32 points for the diagonal, which should be enough. Whether this would not be enough, it should be possible to increase that number, though compatibility would be compromised.

====Some elements about curves====
The implementation of curves has been a complex task, particularly since:
# each curve needs its own reset function – resize() at each iteration,
# which implies oddities regarding their description, for example the diagonal curve gets initialised with several points, despite it looks being “empty”. This is mandatory for correct functioning, but this means that the curve is always open/active. Consequently, to avoid some unwanted loss of computation time in “preview” mode, the user has to activate the curve by clicking on the “curves” combobox. The same activation is necessary for L=f(H) and C=f(C) curves. While clicking enabling the “curves” (linear) would seem to be a better solution, it didn’t work despite many trials.
# during all the procedure, we need to set each "params" value to "clear" for curves, for each LUT, at each iteration and then through a "vector" to reassign the good, updated values to "curve params".

====Data storing and dynamic use====
Once data have been converted:
* they are stored in a text (mip) file,
* each one is referenced inside a 2-dimension dynamical table:
# dataspot[x][y] for numeric and boolean values and methods, where “x” is the representative index of the parameter (e.g. “9” is for “lightness”) and “y” represents the current RT-spot (control spot). Value “0” represents the current in-use value (the one stores in “params”).
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] for parameters of type “curve”. Currently there are only 8 parameters, used for local “Retinex”, “Color and light” (L=f(L), C=f(C), L=f(H), H=F(H)), “Vibrance” and “Exposure”, but it is easy to add more. “y” is used as above in 1.

The way data are stored and used fits well with improccoordinator.cc (current management / preview) and simpleprocess.cc (TIFF / JPG output) files, but not so with dcrop.cc and the partial display of the image (RawTherapee’s pipeline).

In this case (zoom / preview) another solution had to be found in order to synchronise the modifications in real time. I made use of LUTs, so that to each entry referenced in the table described above a LUTi(z) is associated, with z=500 possible entries (500 corresponds to the current maximum number of RT-spots, but this limit can be decreased or increased). The LUTi “z” corresponds to the dataspot “y”. A 25,000 entries LUTi (arbitrary number) is used for “retistr”, “llstr”, “lhstr”, “ccstr”, “hhstr”, “skinstr”, “pthstr”, “exstr” for storing each “vector” curve value in memory (up to 69 values stored as integers).

During data processing, exchanges occur between: params, dynamic tables and LUTi. The values used by dcrop.cc are dynamically linked to dynamical tables by parent→.

====Exchange processes and dynamic data storing====
# reading of the “mip” file to check the version number and guide the updates
# creating the “mip” file if it doesn’t exist
# storing the data in LUTi and dynamic tables from the values stored in “params” (index 0 values)
# first interactive update with the GUI through a transfer function between “rtengine” and locallab.cc (aloListener → localretChanged). This is one of the 3 functions required for the process to work correctly
# reading of the “mip” file and data storing in dynamic tables (index values ==> y) according to the number of RT-spots
# creating a loop – according to the number of RT-spots – which updates LUTi (required by “dcrop”) and “params” values from values stored in the dynamic tables
# call to the “Lab_local” function which contains the algorithms controlling each RT-spot (luminance, sharpness, retinex, denoise, …)
# second interactive update with the GUI through another transfer function between “rtengine” and “locallab.cc”
# treatment of the current RT-spot by using the index (0) values from the dynamic tables. These values are attributed to 1) “params”, 2) LUTi and 3) current index values
# call to the “Lab_local” function for the current RT-spots
# saving to the “mip” file.

Note that if the user modifies the curve (amplitude, number of inflection points) a third interactive update is made in order to conform all of the data according to events.

====A few unavoidable “fantasies”====
Of course everything looks simple, the process works if, and only if, all the data are dynamically updated. I’ve tried a lot, went groping, and finally found a working solution… but an uncanny one. There’s probably a more “informatically” correct way to do it, but at this point I’ve done as explained above and hereafter.

The 3 exchanges between “rtengine” and the GUI occur with 3 parameters which actually do nothing in the program except doing the update process:
# “anbspot” which takes values of 0 or 1
# “cTgainshaperab” (curve) which takes any value bewteen 0.70 and 0.90
# “retrab” which varies around 500.
I have added 3 more parameters (in the form of sliders) – hueref, chromaref and lumaref – hidden from the user but which are used to update the system in real time, to correctly take into account the reference “spot” values. Allowing those 3 parameters to vary brings stability and allows real time updates. Increasing the number of those “fantasy” parameters should not be necessary. These extra parameters are hidden to the user, and are only visible in the history.

In addition, I had to add some empirical time delays, giving time to time… Time delay is used for example when the user modifies the curve (amplitude, number of inflection points).

==Specificity of the local mode (as compared to “Lab adjustments”)==
Hereafter is some useful information for the user, often specific to the local mode.

===Color and Light===
* The algorithms used for luminance and contrast in local mode differ from the ones used in “Lab adjustments”, which may lead to differences in rendering.
* The luminance algorithm is made such that below -90 and down to -100 for “Lightness”, it is possible to increase the image's “darkness”, almost to the point of getting a luminance value close to 0. To accentuate this effect, “Chrominance” can be decreased and “Scope” increased.
* The inverse mode can be used for creating graduated frames. If “Ligthness” is set to -100 and "Chrominance" is reduced, the “frame border” will be black.
* For the “Lightness” and “Contrast” sliders, the user can choose among 2 algorithms: the first one (default) is close to that in “Lab adjustments” while the second one, activated through “Lightness - Contrast ‘Super’” is close to the algorithm used for the L=f(L) “Super” curve.
* Do not hesitate, when needed, to activate “Enhanced” or “Enhanced + chroma denoise” in the “Global Quality:” combobox.

====Curves====
* An L=f(L) or C=f(C) curves allow controlling the luminance and chrominance for each RT-spot as a function of luminance or chrominance.
* An L=f(H) curve allows controlling the luminance for each RT-spot as a function of tint.
* An H=f(H) curve allows controlling the tint for each RT-spot as a function of tint.
The curves are activated by selecting one of the two algorithms from the “Curves types” combobox:
* “Normal”: the curves – particularly the one that is the most difficult to manage, L=f(L) – use an algorithm close to the one used with the sliders (Normal mode),
* “Super”: using a new algorithm, which I think performs very well (it even surprised me the first time I used it).

Caution: when the RT-spot resides in an area which is neutral, grey or very uniform, the artefacts introduced by the new algorithm (“Super” algorithm for the curve or the slider) may be impossible to get rid of. Use one of the 2 older algorithms to avoid that.

===Exposure===
The “Exposure” module may look like the the one in global RGB mode, but:
* it works entirely in L*a*b* mode, hence the differences in rendering;
* there’s no “Lightness”, “Chroma” or “Contrast” slider, whose functions are already fulfilled in the “Color and Light” module;
* there’s only one “Contrast” curve, similar to the L=f(L) firm “Color and Light”. Of course its effect is different from “Tone curve” which works in RGB mode. If needed, two L=f(L) curves can be activated, one under “Color and Light” and the other under “Exposure”.

===Vibrance===
This module is similar to the main one (from RawTherapee's "Exposure" tab).

===Blur & Noise===
“Blur” is activated only when “Radius” =< 2.
By significantly lowering the default value of “Scope” and possibly checking “Blur luminance only”, it is possible to get a different amount of blur for the different tints.
Since October 2017, 3 methods are proposed:
* “Normal”: the shape detection algorithm has been improved, it is now closer to shape detection algorithm proposed in the other modules;
* “Inverse”: a simplified algorithm, which doesn’t make use of “Scope”. The inversion is coarse and doesn’t allow a fine separation between the affected and unaffected areas;
* “Symmetric”: this new algorithm uses the same processes as “Normal”, and adjusting “Scope” the user can target the process with more precision.
Caution:
* Using the “Inverse” mode will blur large portions of the image, which can not be corrected later on.
* The action of “Scope” may sometimes appear puzzling: for instance, in a portrait, the eyes (which of course differ from the skin) may be blurred if the value of “Scope” is too low.

===Tone Mapping===
Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Retinex===
Compared to the standard “Retinex” module, the local “Retinex module has simplified controls, and is applied at the end of the pipeline instead of the beginning. Since “mip” version 10002, the “Transmission gain” is specific to each RT-spot.

===Sharpening===
Only the “RL Deconvolution” algorithm is provided here.

===Contrast by detail levels===
Compared to the main RGB mode module, this one has:
* 5 levels instead of 6,
* no slider for “skin tone” protection (not needed since the algorithm works locally on the RT-spot area),
* an additional “Chroma” slider.

Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Denoise===
Compared to the main RGB mode module, this one has:
* only the wavelet tool working (no Fourier function, nor medians),
* less sliders and curves,
* the possibility to work differentially on fine or coarse noise for both luminance and chrominance noise.

==A specific use case : reduction of image defects (dirty sensor, red eyes, …)==
“Locallab” had not been thought with the idea of correcting small image defects. However, some visible, “photographically disturbing” defects may actually be tamed or even removed. Of course, this is not incompatible with other more specialised modules which could be introduced (or not) into “Locallab”… At least 3 existing modules can serve this purpose, alone or in combination, by adapting their use:
* “Color and Light” for spot-like defects;
* “Contrast by detail levels” for spread out defects;
* “Blur and Noise” as an optional complement (caution, this is a destructive action, use moderately).

These modules can be used either on the main image (raw, TIFF, …) or on a flat-field image.

===Using the “Color and Light” module===
* Activate “Color and Light”
* A red eye removal tool equivalent can be obtained by framing closely around the eye – central circle zone centered on the eye’s red, spot handles close to the eye – low “Scope” value, then lowering “Lightness” and “Chrominance” to -100.
* The same idea allows reducing the “IR spot” kind of defect by framing closely around the defect – central circle zone centred on the defect, spot handles close to the defect area – then lowering “Chrominance” to taste, and if needed lowering the “scope” value.
* In some (simple) situations, a “dirty sensor” defect can be reduced, in particular in the case of “sensor grease”. It can be seen as stains or spots on a uniform background. To attenuate this, choose a tight framing of around the defect – central circle on the centre of the defect (adapt the size of the RT-spot), drag the handles so that they are not too close to the border of the defect (this will make the transition less noticeable). Then: a) decrease “Transition” towards lower values; b) check “Lightness - Contrast “Super”; c) adjust “Lightness” and “Chrominance” as needed to bring the defect area closer to the unaffected area; d) if needed adjust slightly “Scope” to achieve the best result.

===Using the “Contrast by detail levels” module===
When the sensor is dirty (grease), and when the affected area is large or if there are multiple small defects, “Contrast by detail levels” may be used, working as a sort of “wavelet” tool on luminance, and if needed on chrominance. In such cases: a) place the RT-spot on one of the stronger defects (adjust the size as needed); b) drag the handles so as to cover most of the affected area; c) set “Transition” to higher value; d) activate “Contrast by detail levels” and decrease the contrast of levels 3 and 4 (or lower); you can adjust the “Chroma” slider if needed.

==Settings in the Preferences dialog==
Below is a list of the settings (already mentioned above in several places) which can be accessed from the “Preferences” dialog:
* In “Preferences” > “General” tab > “Local adjustments”, by checking the “Show spot delimiters” checkbox, an approximate zone delimitation is drawn which helps viewing the area affected by the RT-spot and its settings.
* If your images generally have low noise, you can set the default for “Global quality” to “Standard”, and get a significant speedup in processing time. This setting is found under “Preferences” > “Performance & Quality” tab > “Local adjustments”. The three choices for quality are selected from the “Local adjustments Quality method” combobox. Default is “Enhanced + chroma denoise”.
* Regarding “mip” files:
** the choice for “mip” files destination folder is set from “Preferences” > “Image processing” tab > “Mip Profiles”;
** in order to clean the generated “mip” profiles, go to “Preferences” > “File Browser” tab > “Cache Options” and click on the “Clear mip” button and/or “Clear pp3” – this is valid in the case where you chose to store “mip” files in the cache, otherwise if you chose to let RT write the “mip” files next to the input file, you will have to delete them manually. Note that the presence of older versions of “mip” and “pp3” files may lead to instability or even crashes of RawTherapee.

==Processing time and memory use==
At image export time (output to JPG, TIFF…), for the “normal” mode, the algorithms compute the data only for in the RT-spot delimited areas, not for the whole image. Thus, processing time and memory stay reasonable. Note that of course, this will depend on the number of RT-spots, their size, and the type(s) of treatment done in these RT-spots.

Excluding “Denoise” and “Sharpen”, processing time is in the order of a few tenths of a second per RT-spot, and memory use of a few hundred MB.

Two settings have a strong influence on resource use:
• “Denoise” which adds around 1 sec. of processing time, and 1 MB of memory use;
• “Global quality: Enhanced + chroma denoise” which adds around 0.5 sec. And 0.6 MB.
These figures depend on the size of the RT-spot.

==Future evolution==
Besides usual tweaking, bug corrections, improvements (settings, user interface)… it would be desirable to improve the GUI with regards to the creation/selection/modification of individual RT-spots.

From a programming point of view, it should be possible to improve code readability and maintainability, and to integrate all the “mip” files code parts (as done in “rgbproc.cc”) which currently are linearly integrated to void procedures in “improccoordinator.cc”, “dcrop.cc” and “simpleprocess.cc”.

Local Adjustments/fr

2017-11-10T13:47:57Z

Sguyader:

== Quel type de contrôle local? ==
Lorsqu'on observe les différents logiciels du marché on trouve plusieurs types de contrôles locaux
# les contrôles de type "lasso", associés à des calques et masques de fusion, comme par exemple dans Photoshop (c). Ce type de contrôle est majoritaire dans les logiciels (Photoshop, Gimp, Darktable...) et l'avis des utilisateurs est obligatoirement orienté vers ceux-ci au détriment du point 3) ci-dessous moins connu!
# les dispositifs de suppression de "yeux rouges", ou de "spot" liés aux imperfections du capteur
# les contrôles de type U-points, utilisés jusque récemment dans Nikon Capture NX2 (c), ou comme complément à d'autres logiciels comme Nik Software (c). Pour qui a tâté de ces dispositifs (rares maintenant) il n'est pas question de revenir aux calques et masques de fusion! Ce type de contrôle nécessite un apprentissage différent de ceux de type lasso-calque et un désapprentissage cognitif de ceux-ci. De mon point de vue, ils sont globalement plus performants.

Dans la version présente de Rawtherapee, l’algorithme développé est proche dans le principe du point 3) ci-dessus, les U-points. Bien sûr, le code de Nik Software est inconnu, mais il y a quelques années j'ai été séduit par la facilité d'utilisation et les performances des U-points, et j'ai entrepris de développer un produit qui ne ferait pas appel, ni au lasso, ni aux calques, ni aux masques de fusion.

Bien sûr rien n'interdit d'avoir les 3 possibilités (Lasso-calque, retouches spot, U-points) !

La version actuelle est très certainement perfectible, au niveau de l'interface graphique - GUI - notamment:
* pour le suivi et repérage des RT-spot (spot de contrôle) à l'écran
* pour les réglages des différents curseurs qui gagneraient à être intégrés au spot de contrôle, comme le fait Nik Software (c).
Cependant, ces deux points n'affectent pas ni l’utilisation courante, ni la portabilité.

J'ai ajouté, pour faciliter l'utilisation et éviter les menus trop longs en mode écran, une interface GUI similaire à celle de Wavelet, avec des "expanders".
Vous avez ainsi la possibilité pour chaque famille d'action (color and light, Blur, Retinex, etc.):
# faire apparaître ou non le détail des commandes : curseurs, méthodes, courbes,..
# activer ou non l'ensemble des fonctions de la famille d'action.
Attention, le choix - 2 - active ou annule l'ensemble des RT-spot ( spot de contrôle); il est théoriquement possible d'associer cette possibilité à chaque RT-spot, mais quel intérêt ?

===Contrôles locaux Lab et RGB===
* Les premiers algorithmes sont écrits en mode L*a*b* avec les contrôles suivants : "Color and Light", "Blurr addnoise", "Retinex", "Tone mapping", "Sharpen", "CBDL", "Denoise"..Deux contrôles suivants ont été ajoutés : "Exposure", "Vibrance"...
* Voir ci-dessous le principe des algorithmes, mais un des points clefs à retenir pour la détection de forme et la prévention des artefacts est que le mode Lab préserve la teinte "hue", qui joue un rôle déterminant.
* L'idée d'un module "RGB" vient évidemment à l'esprit, avec ''a minima'' un module :
** White Balance : qui permettrait une retouche de la balance des blancs par exemple pour "réchauffer les parties à l'ombre", ou permettre le mélange de deux éclairages par exemple "lumière du jour" et "Tungsten". Ce module doit être placé juste après "demosaic".

====White balance auto====
Le module "white balance" (branche "autowblocal") vise deux objectifs :
* permettre la retouche locale de la Balance des blancs (évident!)
* tester de nouveaux algorithmes de Balance des blancs automatique :
** en usage général (full image), afin d'obtenir de meilleurs résultats que l'algorithme actuel. Bien sûr on va me rétorquer qu'il faudrait une branche spécifique "White balance", mais j'essaie de faire d'une pierre deux coups.

Pour mémoire en 2012 et 2013, il m'avait été demandé, de mettre en place la balance des blancs itérative "Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]". A l'époque avec un autre développeur nous avons passé beaucoup de temps pour un résultat assez peu satisfaisant... d'où l'abandon. Depuis, fort de cette expérience j'ai repris le travail mais à l'envers ! Maintenant - si je ne me suis pas trompé - l'algorithme fonctionne.
J'ai profité de cette possibilité (actuellement uniquement pour des images RAW), pour rechercher dans la littérature universitaire, d'autres algorithmes auto. J'ai trouvé et mis au point deux nouveaux algorithmes :
* "auto edge[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]" : l'idée ici est de créer un masque d’accentuation pour permettre de renforcer les parties de l'images où il y a des détails par rapport aux aplats.
* "auto standard deviation[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]" : l'image (ou la partie d'image pour le mode local) est divisée en 12 zones. Pour chacune on calcule moyenne et écarts type, puis on assemble le résultat.
Un troisième algorithme semble prometteur "Color by correlation[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf]", mais je me heurte à quelques difficultés...Après beaucoup de tests en tous genres, les résultats sont erratiques...

J'ai ajouté la notion de gamma:
* les mêmes principes concernant la répartition de la luminance - gamma sRGB - utilisé dans le code de Rawtherapee

A titre de rappel, la balance des blancs automatique est un problème mathématique totalement indéterminé. Il est possible d'avoir des algorithmes plus ou moins performants (et aussi plus ou moins rapides ou lents), mais en aucun cas le résultat sera parfait ! Pourquoi est-ce impossible ? Si on se réfère aux principes de la gestion des couleurs [[http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]], il est nécessaire de connaitre à la fois l'objet coloré, l'illuminant et l'observateur. Il y a au moins 2 familles d'inconnues. De plus l'environnement de prise de vue n'est pas connu et influe sur la perception (CIECAM) ainsi que l'environnement de traitement et de visualisation. Donc, mission quasi impossible !

L'objectif du module '''"White balance" est de tester les algorithmes''', au total il y en a 7 et le double (au moins) si on prend en compte le "gamma sRGB". En effet pour contourner les obstacles d'il y a 5 ans, j'ai utilisé au lieu de l'image avant demosaic, l'image juste après demosaic, sur laquelle on peut ou non appliquer le "gamma sRGB", pour se retrouver dans les mêmes conditions qu'en usage normal (sinon bien sûr sans "White Balance" et sans profil "ICC ou DCP").

L'idéal est de tester sur de nombreuses images les divers algorithmes "auto" avec un objectif : quel(s) algorithme(s) retenir et implanter en mode "full image" (peut être 1 ou 2 en plus de l'actuel qu'il faut garder pour compatibilité).

====White balance contrôle local====
Le contrôle local est actuellement limité à 1 spot, mais pas de difficultés si les utilisateurs le souhaitent d’accroitre...En attendant les évolutions de "locallab".

Bien sûr il me sera dit "cela ne fonctionne pas", ou "on ne se raccorde pas avec le 'preview'". Cela fonctionne ! Et il est plus qu'évident que atteindre le preview est par définition quasi impossible... (différences ombres , soleil, illuminants différents, etc.) en dehors de la pertinence de l'algorithme.

Vous disposez de 3 sliders : temperature, tint, blue/red equalizer

== Quels défis à résoudre? ==
Plusieurs problèmes généraux sont à résoudre afin d'obtenir un fonctionnement fluide :
* permettre un nombre quasi illimité de RT-spot (spot de contrôles);
* adapter les algorithmes locaux aux problèmes d'échelle, car beaucoup d'algorithmes tiennent compte de la taille de l'image - donc de la zone traitée. Cet aspect est fondamental, notamment avec les courbes qui agissent sur toute l'image;
* minimiser l'occupation mémoire et les temps de traitement en sortie JPG et TIF;
* permettre des mises à jour logicielles faciles en cas d’évolution des algorithmes ou d'évolution du nombre de méthodes ;
* optimiser les écarts entre "preview" et sortie JPG / TIF;
* etc.

Pour chaque RT-spot :
* permettre selon le cas, une action dans la zone sélectionnée ou à l'extérieur de la zone sélectionnée;
* permettre selon le cas une détection de forme pour délimiter l'action;
* assurer une transition entre le cœur de la zone traitée et le reste de l'image;
* etc.

Actuellement, les RT-spot (spot de contrôles) sont opérationnels, pour le mode Lab, et pour les méthodes suivantes:
# Color and light : lightness, chrominance, contraste en mode normal avec quatre courbes L=f(L), L=f(H), C=f(C), H=f(H) et inverse ;
# Exposure : en mode normal
# Vibrance : en mode normal
# Blur and Noise : en mode normal et inverse;
# Retinex : en mode normal et inverse, maintenant avec gestion de la courbe "transmission gain";
# Sharpening : en mode normal et inverse;
# Contrast By Detail Levels : en mode normal;
# Denoise : en mode normal.

== Principes généraux ==
===L'Objet RT-spot===
Comme je l'ai évoqué, le système utilisé est proche de celui mis au point par Nik Software, avec de grandes différences :
* chaque RT-spot, peut être considéré comme un objet qui comporte plusieurs champ - à ce jour environ 70, constitués de curseurs, courbes;
* chaque champ, regroupé en paquets peut être ou non activé, et peut avoir des valeurs variables selon sa nature ;
* les paquets sont des ensembles cohérents pour l'utilisateur : color & light, exposure, contrast, vibrance, blurr, retinex, sharpening, tone-mapping, contrast by detail level, denoise ;
* le nombre de "RT-spots objets" peut varier de 2 à 500 ;
* les données des "RT-spots objets" sont stockées dans un fichier texte "mip";
* les "RT-spots objets" sont gérés - création, modification, suivi - dans une boucle "for";
* il n'y a pas de duplication de code.

===Le découpage en quatre zones - l’aperçu de la zone RT-spot===
Lorsque l’utilisateur sélectionne un RT-spot (spot de contrôle),l’image à l’écran montre:
* un centre, constitué d'un cercle dont on peut faire varier : a) le diamètre, b) la position avec la souris ou les curseurs;
* quatre lignes horizontales ou verticales dont on peut faire varier les positions avec la souris ou les curseurs.
* si vous sélectionnez en "Preferences" / "General" / "Local adjustements", en cochant la case "Show spot delimiters", vous obtiendrez une approximation de la zone concernée par le spot et ses réglages. Attention, je ne suis pas arrivé à un travail propre avec la fonction "arc / ellipse / scale" de la bibliothèque graphique Cairo; j'ai donc opté pour chaque "quart" à une pseudo ellipse obtenue par 3 courbes de Bézier se raccordant entre elles. Dans la majorité des cas l'approximation est satisfaisante...Pour permettre une sélection plus facile j'ai été amené à accroître la taille des 4 lignes horizontales et verticales qui sélectionnent la taille du spot (les courbes de Bézier sont inactives!).

On aboutit à 4 zones, dont on ne peut faire varier l'orientation (angle d'inclinaison obligatoirement à zéro).
Ces 4 zones ont chacun de leurs sommets reliés par une ellipse imaginaire.

Il est possible de pointer les limites des zones en dehors de la zone "preview".

A terme, il doit être possible, même si l'utilité me semble discutable du fait de l'algorithme de détection de forme, de remplacer l'ellipse, par une courbe tracée à l'aide de la souris, à condition que la transformée homothétique de la courbe n'ait pas d'intersection avec la courbe originale. Cette "amélioration" intellectuellement satisfaisante, ne devrait être que d'un apport négligeable - dans le cas des U-points. Néanmoins il sera toujours possible de faire coexister les actuels U-points avec des contrôles par"lasso" de type Photoshop (c).

===Les 2 types de RT-spot===
Deux types de RT-spot sont proposés:
* Normal: chaque nouveau spot prend en compte les réglages des précédents - si bien sûr ils sont dans la zone d'action commune - on peut parler d'action récursive.
* Excluding : chaque nouveau spot réinitialise, l'image à partir des données originales, mais garde pour les calculs les références de l'image modifiée par les autres RT-spots.

Dans les deux cas, vous avez accès à la quasi totalité des réglages : Color and Light, CBDL, Blur, etc.

====Commentaires sur le "Excluding spot":====
* il est dans le principe assez similaire au "Contre point" de Capture NX2(c) et permet de défaire des actions trop invasives par exemple une "bavure" non désirée. Ce défaut est lié - lorsqu'il se produit - à la trop grande proximité des teintes entre les zones - celle où on désire l'action et celle où on ne le souhaite pas.
* l'algorithme que j'ai utilisé est très proche de ceux présents jusqu'ici dans "locallab", il est fondé sur les différences de couleurs. Il n'est pas "parfait" mais devrait satisfaire 70% des cas.
* j'ai préparé - sans garantie que cela fonctionne un jour - un complément pour mieux discriminer les zones, en s'appuyant sur la transformée de Sobel-Canny. La transformée est en place - non accessible à l'utilisateur - mais j'essaie de mettre en place un algorithme pas trop gourmand en temps de traitement... et bien sûr efficace.

====Comment se servir de "Excluding spot" - limitations :====
# il suffit de placer le nouveau spot sur la zone à exclure
# choisir dans le menu "Settings", Spot method = "Excluding spot"
# Puis régler "Scope", "Transition" et "Spot size" ainsi bien sûr que 4 limiteurs de zone, pour obtenir les effets désirés. Vous pouvez utiliser des réglages complémentaires comme par exemple "Color and Light"...
Le système s’appuie sur l'image en cours et calcule les "références" (hue, chroma, luma) à partir de cette image (voir ci-après). En conséquences, si le fond est noir aucune retouche sera possible (ceci est possible en mode inverse "Color and light" lorsqu'on cherche à créer un cadre noir).
Dans quelque cas, en mode "inverse" le fonctionnement pourra être capricieux et amener des différences entre "preview" et sortie TIFF JPG. Dans ce cas accroitre "Scope" pour le "Excluding spot"

===Les références teinte, chroma, luminance et le principe de l'algorithme en mode "normal"===
Afin de mettre en œuvre un algorithme performant de détection de forme :
* la zone du cercle central, sert de référence. En fonction du diamètre choisi par l'utilisateur, le système calcule, la moyenne de la teinte (hue), de la chroma, et de la luminance.
* le choix du diamètre de la zone centrale dépend de l'usage. Par exemple pour un feuillage, l'utilisateur aura intérêt à choisir une valeur faible afin de ne sélectionner que le vert du feuillage; à l'inverse pour la peau l'utilisateur aura intérêt à accroître le diamètre afin d'éviter les prises en compte de données parasites (bruit, cils, etc.).
* pour chaque quart, et en fonction du curseur "scope", le système prend en compte :
# en premier lieu de l'écart de teinte entre la zone centrale et le pixel courant ;
# puis, un algorithme complexe, s'appuyant sur la notion de deltaE (différence perçue entre 2 couleurs prenant en compte, la teinte, la chroma et la luminance), atténue l'action en fonction de l'écart entre la zone centrale et le pixel courant.
# la modification d'action utilise soit une loi linéaire, soit une loi parabolique selon le cas.

Ceci va permettre de différencier l'action selon les critères énoncés ci-dessus, comme par exemple, si le cercle central se trouve dans un feuillage, de limiter l'action à l'ensemble du feuillage sans toucher à l'arrière plan (ce qui est impossible avec un lasso). De plus si un autre feuillage se situe dans la zone couverte, celui-ci sera également concernés par la modification.

* l'action sur le curseur transition va permettre de faire varier l'action : si le curseur est réglé sur 50, la moitié (linéaire) de la zone concernée verra une application à 100% de l'effet, puis une transition agira régressivement jusqu'aux limites de la zone.
* si on accroît la valeur de "scope", progressivement l’ensemble de la zone sélectionnée est prise en compte quelque soit la couleur, la chroma et la luminance.
* si on réduit la valeur de "scope",l'action se limitera aux pixels très proches (en termes de deltaE) de la zone de référence.

L'algorithme de détection de forme est opérationnel en mode "normal" sauf pour certains modules (denoise) - son implantation en mode inverse n'a pas de sens.

Cet algorithme va avoir ses performances accrues, si l'utilisateur choisit : "Quality Enhanced" ou "Qualty enhanced + chroma denoise". Ce second choix apporte une très légère réduction du bruit de chroma afin de supprimer les artefacts possibles liés à l'utilisation de "enhanced" (à noter dans le cas + chroma denoise, un accroissement des besoins en mémoire et du temps de traitement).

L'algorithme utilise toutes ses capacités, si les valeurs de "scope" sont inférieures à 20.

===Pourquoi pas d'autres algorithmes? ===
Remarque : il doit être possible de programmer d'autres algorithmes de détection de forme que celui ci-dessus fondé sur les différences de deltaE.

* Par exemple les algorithmes de détection de bords (edge) tels que "Canny" ou "Sobel";
* Ou encore le principe de décomposition en ondelettes.
Mais dans ces 2 cas tout reste à faire !

===Le fonctionnement en mode inverse===
Lorsqu'il est proposé, le fonctionnement en mode inverse est extrêmement simplifié, seul le curseur "transition" permet de moduler l'action.

A partir de fin octobre 2017, j'ai mis au point une autre manière de concevoir le mode "inverse". Cette manière est limitée à l'outil "Blur and Noise" (voir ce paragraphe)

===Nombre maximum de RT-spot (spot de contrôle)===
Par défaut le nombre de RT-spot est de 8.
Vous pouvez choisir n'importe quelle valeur entre 2 et 499. Pour cela il suffit de changer la variable Nspot dans le fichier "option"; par exemple Nspot=12.
Il est indispensable de relancer Rawtherapee après cette modification.

===L'algorithme 'super'===
La clef du "succès" (si on peut utiliser ce terme) tient à l'algorithme présent depuis fin janvier 2017. je vais l'expliciter de manière simplifiée :
# pour la partie des données concernées par la zone sélectionnée, on applique une fonction courbe "traditionnelle" ou un curseur classique, ou la fonction de transfert normale (Retinex, Tone mapping, CBDL, Vibrance, ...);
# puis on réalise une conversion de la LUT ou de la fonction de transfert , en un équivalent "slider", en séparant les valeurs positives et négatives, afin d'avoir une représentation de la fonction comme une multitude de "sliders" (autant qu'il y a de pixels concernés) dans l'intervalle -100, 0, +100
# on passe ces données à la fonction de reconnaissance de forme - celle des 4 zones. On détecte pour chaque pixel l'écart de teinte, chroma et luma par rapport à la référence. On établit des équations de variations linéaire selon le cas de la luminance (L = f(L)) ou de la chroma (C=f(C) ou des fonctions de transfert).
# puis on applique diverses corrections pour tenir compte de l'environnement, ciel, peau,...
# enfin, on applique une correction (avec seuil et itérations)pour ne pas corriger (ou le faire faiblement selon le choix de l'utilisateur), les tons gris ou neutres qui sont dans la même teinte que la référence (mais avec une chroma faible).
# ces paramètres sont ensuite pondérés en fonction, de la forme (ellipse) et de la zone de transition.
# bien sûr les réglages des paramètres qualité "Global quality", ont leur importance, notamment dans les images légèrement bruitées - le bruit chromatique est considéré par l'algorithme comme de la même couleur que le spot. Il faut donc avoir la possibilité de le supprimer, d'où la sélection "enhanced + chroma denoise" (il est possible que ce réglage soit insuffisant, agir en conséquence sur "Denoise local" si nécessaire).

Cet algorithme nouveau ('super') semble généralement fonctionner, mais dans le cas où le spot est sur une zone gris - neutre ou l'action sur des zones à faible gradient, l'algorithme peut être pris en défaut, dans ce cas utiliser l'ancien (quand c'est possible !!), car pour Retinex, Tone Mapping, CBDL je n'ai pas offert ce choix par souci de simplification)

===Réduction des artefacts et l'algorithme "Global quality"===
Par défaut, "Global quality" est à "Enhanced + chroma denoise". Certes cela augmente les temps de traitements, mais globalement c'est préférable. Vous pouvez, si vous trouvez les temps de rafraichissement long, choisir "enhance" ou "standard" et examiner l'image...
* 2 curseurs permettent de réduire les artefacts et améliorer le rendu de l'algorithme. Ils agissent en fonction de la chroma, dans les tons gris neutres. Pour désactiver complètement l'effet il suffit de mettre "iterations = 0". Ces curseurs permettent, d'une part de réduire les artefacts et, d'autre part d'agir sur le rendu de l'image. L'action est possible pour "Color Light", "Exposure", "Retinex", "Vibrance", "Tone Mapping" et "Contrast by details levels".
* lorsque les images sont bruitées, même légèrement (beaucoup d’images sont bruitées sans que cela soit gênant par exemple les ciels, les nuages,...), les algorithmes sont "trompés", ne pas hésiter à laisser activé "Global quality = enhanced + chroma denoise" et (quelquefois) activer "denoise local" et agir très légèrement sur les curseurs (y compris luminance).
* dans certaines circonstances, par exemple avec Tone-mapping, le système de réduction d'artefacts peut générer des artefacts. Dans ce cas, mettre le slider "iterations" à 0.

Vous pouvez choisir la valeur par défaut de "Global Quality", par exemple si vos images sont très peu bruitées, et ainsi réduire notablement les temps de traitement.
Pour cela, aller dans "Preferences", "Performance and Quality", "Local adjustements" et choisir entre Les 3 propositions. C'est ce choix qui sera proposé par défaut à l'utilisateur pour chaque nouveau "Spot", bien sûr il est possible ensuite de modifier ce choix, en sélectionnant la combo-box "Global Quality"

===Avoid color shift===
Cette case à cocher vise deux objectifs :
* mettre les couleurs dans le gamut de l'espace de travail courant (working profile) en utilisant une colorimétrie relative ;
* ajuster les couleurs à l'aide d'une correction "Munsell" - notamment les rouges-orangés et les bleus-pourpres, lorsque la saturation dans le domaine L*a*b* a évolué notablement.

===Les fichiers *.mip - les principes de l’algorithme multipoints===
Afin de permettre le fonctionnement - enregistrement des valeurs pour chaque spot de contrôle - un fichier de type texte, assez proche des fichiers pp3 est enregistré à deux endroits possibles :
* à côté du fichier à traiter. Si par exemple vous traitez le fichier ASC4509.NEF, un fichier ASC4509.NEF.mip sera enregistré dans le même dossier. Si vous choisissez cet emplacement, vous pourrez ouvrir plusieurs sessions pour un même fichier image, si celui-ci est présent dans des dossiers différents. Par contre, le nom des dossiers et du "path" doit obligatoirement n'avoir que des caractères ASCII...sinon plantage.
* dans le dossier "mip", à l'intérieur du dossier "cache" (via un "hash number MD5" qui identifie le fichier). Valeur par défaut. Si vous choisissez cet emplacement, si le fichier image est présent dans plusieurs dossiers, il y aura plusieurs fichiers mip. Cette option permet d'utiliser des dossiers et "path" avec des caractères NON ASCII.
* le choix entre ces emplacements est possible à partir de : Preferences / Image processing / Mip Profiles

Ce fichier mip contient les données qui seront ensuite passées au programme, via d'une part les processus de type "procparams" et d'autre part des LUT qui permettent le fonctionnement en mode zoom.
Lors de la mise à jour d'une nouvelle version, il pourra dans certains cas être demandé d'effacer les fichiers *.mip (voire le cache) afin d'éviter un crash. Pour cela vous pouvez aller dans "Preferences" / "Files browser", puis "Clear mip" et / ou "clear pp3" - si bien sûr vous avez positionné "mip" et "pp3" dans le cache, sinon il faudra exécuter cette opération manuellement dans le dossier courant. La présence d'anciennes versions de fichiers "mip" ou de "pp3" peut amener de l'instabilité voire un crash du système.

====Architecture du système====
Lorsque je me suis "aventuré" vers la possibilité d'un système multipoints sans calques, sans masques,...il était obligatoire de refuser de dupliquer le code. Comment envisager par exemple pour 10 spot de contrôles, 10 codes GUI, et autant de code dans Rtengine.
Après réflexion, l’idée est venue d'avoir un fichier mis à jour en temps réel - c'est à dire qui suit les modifications faites par l'utilisateur - de l’historique des actions / modifications.

Bien sûr, les variables utilisées par Rawtherapee, au niveau de l'interface GUI, et par la suite dans l'ensemble du code via "params", sont de type divers:
* numériques : entier, float, double,...
* booléenne
* choix (menus pour "méthodes") de type string
* courbes via des "vectors" de type double a dimension dynamique.
* ...

====Conversion des données====
La première étape - afin de simplifier ensuite la gestion des données - est de convertir toutes ces données en entiers. Dans quelques cas cela peut aboutir à une très légère perte de précision, qui de mon point de vue est tout à fait négligeable.
*Cette opération est très simple pour les valeurs numériques, même si elle peut aboutir dans certains cas (la teinte - Hue - s'exprime en radians dans l’intervalle -Pi + Pi) par une double transformation "float * 100 et / 100" pour garder la précision.
*Elle est logique pour les opérations booléennes et les méthodes.
*Par contre elle s'est avérée complexe pour les courbes. Les valeurs à stocker dans le fichier texte sont de type vector<double> soit un tableau dynamique de valeurs numériques. Probablement il doit y avoir un moyen "plus simple" en utilisant les fonctions qui sont utilisées dans "Procparams", mais je ne suis pas arrivé à les mettre en œuvre. J'ai contourné l'obstacle en :
#transformant les valeurs doubles en entier avec 3 chiffres significatifs - ce qui est largement suffisant
#puis en convertissant le "vector" en une chaine de caractère de longueur variable
#la lecture et l'écriture de cette chaine et sa conversion en "vector" se faisant dynamiquement par une fonction appropriée ("strcurv_data"). A noter que cette fonction permet de modifier des courbes jusqu'à une limite de 16 points d'inflexion (Courbe de Beziers) pour la courbe plate, et 32 pour la diagonale, ce qui devrait être suffisant. Si c'était insuffisant (??) il est possible (via une perte de compatibilité) d'accroître ce nombre.

====Quelques éléments sur les courbes====
L'implémentation des courbes a été complexe, au delà de ce qui est écrit ci-dessus, notamment :
# chaque courbe doit obligatoirement avoir une fonction reset - resize() à chaque itération;
# ce qui implique des curiosités au niveau de leur description, par exemple la courbe diagonale est initialisée avec plusieurs points, alors qu'elle a l'air "vide". C'est indispensable au bon fonctionnement. Mais ceci a pour conséquence que cette courbe est toujours ouverte / active. Donc cela implique si on veut éviter des consommations de temps en mode "preview" que l'utilisateur "active" la courbe en activant la combobox "curves". Cette même activation est aussi nécessaire pour les courbes L=f(H) et C=f(C). Bien sûr, on se serait tenté de penser qu'il suffit d'activer le mode "enabled" de la fonction "courbes" (linéaire), mais après de nombreux essais cette démarche est infructueuse!
# tout au long des procédures, il est obligatoire de mettre "clear" chaque valeur de "params" pour les courbes, chaque LUT, pour chaque itération et ensuite via "vector" de réattribuer les bonnes valeurs courantes à "params courbe".

====Stockage et utilisation dynamique des données====
Une fois les données converties :
* elles sont stockées dans un fichier texte
* chacune est référencée dans un tableau dynamique à deux dimensions :
# dataspot[x][y], pour les valeurs numériques, booléenne et les méthodes, où 'x' représente l'indice représentatif de la variable, par exemple '9' correspond à 'Lightness', et 'y' représente le RT-spot (spot de contrôle) courant. La valeur '0' représente la valeur courante en cours d'utilisation (celle stockée dans 'params").
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] pour les variables de type "curve" (aujourd'hui il n'y a que 8 variables celle utilisée dans "Retinex" local, et celles dans "Color and light" (L=f(L), C=f(C), L=f(H), H=F(H))et "vibrance" et "exposure", mais il est assez facile d'en ajouter), avec 'y' comme ci-dessus.

Ce stockage et utilisation - nous reviendrons plus loin sur l'algorithme lecture / écriture dynamique - convient aisément pour le fichier Improccoordinator.cc (support de la gestion courante - Preview) et Simpleprocess.cc (sortie TIF / JPG), mais ne peut convenir, pour Dcrop.cc et la vision partielle de l'image (les fameux pipeline de Rawtherapee).

Pour ce cas (zoom - Preview) il a fallu imaginer autre chose, qui assure en temps réel la synchronisation des modifications. J'ai utilisé des LUT, dans le cas actuel, à chaque donnée référencée dans les tableaux ci dessus est associé une LUTi(z), avec z=500 entrées possibles (500 correspond à la limite informatique du nombre de RT-spot (spots de contrôles)...qu'on peut très facilement accroitre ou réduire). 'z' pour les LUTi correspond à 'y' pour dataspot. Une LUTi avec 25000 (arbitraire) entrées est utilisée pour "retistr", "llstr", "lhstr", "ccstr", "hhstr", "skinstr", "pthstr", "exstr" pour garder en mémoire (sous forme d'un entier) chaque valeur du 'Vector' de la courbe (il peut y en avoir jusque 69).

Au cours du traitement, des échanges sont réalisés entre: params, les tableaux dynamiques et les LUTi. Les valeurs utilisées par Dcrop.cc sont liées dynamiquement aux tableaux dynamiques par parent->.

====Processus d'échanges et stockage des données dynamiques ====
Sans entrer dans une description fastidieuse, je resterais aux principes généraux :
# lecture du fichier "mip" pour lire la version et orienter les mises à jour
# première écriture du fichier "mip" s'il n'existe pas
# stockage des données dans les LUTi et les tableaux dynamiques à partir des valeurs stockées dans "Params" (valeurs index 0)
# première mise à jour interactive avec le GUI via une fonction de transfert entre Rtengine et locallab.cc (aloListener->localretChanged). Cette fonction fait partie des 3 nécessaires pour obtenir un fonctionnement correct.
# lecture du fichier texte "mip" et stockage des données dans les tableaux dynamiques (valeurs index ==> y) - selon le nombre de RT-spot (spots de contrôle)
# Création d'une boucle - selon le nombre de RT-spot (spots de contrôle)- où à partir des valeurs stockées dans les variables tableaux dynamique, les LUTi (nécessaires à Dcrop) et les valeurs de Params sont actualisées.
# Appel de la fonction "Lab_local" qui contient les algorithmes de contrôle de chaque RT-spot (luminance, Sharp, retinex, denoise, etc.)
# deuxième mise à jour interactive avec le GUI via une autre fonction de transfert entre Rtengine et locallab.cc
# puis traitement du RT-spot (spot de contrôle) courant, en récupérant les valeurs index (0) des tableaux dynamiques. Ces valeurs sont attribuées à : 1) params, 2) LUTi, 3) valeurs index en cours
# Appel de la fonction "Lab_local" pour le RT-spot courant.
# sauvegarde du fichier "mip"

A noter que si l'utilisateur, modifie une courbe, amplitude ou nombre de points d'inflexion, une troisième mise à jour interactive est réalisée pour mettre en conformité l’ensemble des données en fonction des événements.

====Quelques fantaisies incontournables====
Bien sûr, tout à l'air simple, mais le système ne fonctionne que, si et seulement si, toutes les données sont dynamiquement mises à jour.

J'ai beaucoup essayé, tâtonné, pour aboutir à une solution qui fonctionne...certes curieuse; il y a probablement un moyen plus "informatique" de traiter cela, mais à ce stade, j'ai fait comme décrit ci-dessus et ci-après.

Les 3 échanges entre Rtengine et le GUI se font notamment avec 3 variables qui ne servent à rien dans le programme - sinon à mettre à jour:
# "anbspot" qui prend les valeurs forcées 0 ou 1
# "cTgainshaperab" (curve), dont je fais osciller une valeur entre 0.70 et 0.90
# "retrab" qui oscille autour de 500.

J'ai ajouté 3 variables (sous forme de "sliders") - hueref, chromaref, lumaref, totalement invisibles à l'utilisateur, mais qui servent à rafraichir le système en temps réel, pour permettre la bonne prise en compte des valeurs "spot" de référence.

Les appels aux changements de ces 3 variables amènent la stabilité au système et une mise à jour en temps réel.
Il ne devrait pas être nécessaire d’accroitre le nombre de ces variables "fantaisistes"

De plus j'ai été amené à empiriquement mettre des temporisations, pour laisser le temps au temps... C'est notamment le cas pour la modification de la courbe par l’utilisateur (amplitude, nombre de points d'inflexion).

Bien sûr ces variables sont invisibles pour l'utilisateur, sinon dans l'historique !

==Quelques particularités du mode local (par rapport à Lab adjustements)==

Voici quelques informations qui peuvent intéresser l'utilisateur. Ces informations sont souvent des particularités du mode local

===Color and Light===
*Les algorithmes utilisés pour la luminance et le contraste sont différents de ceux utilisés par "Lab adjustements", ce qui peut amener quelques différences de rendu.
*L'algorithme de luminance est réalisé de telle manière que en dessous de -90 et jusque -100 pour "lightness", il est possible d'accroître la "darkness" de l'image, pratiquement jusqu'à obtenir une valeur de luminance proche de 0. Si vous souhaitez accentuer cet effet, réduisez également la chominance et accroissez "scope".
*Le mode inverse, peut servir pour l'essentiel, à réaliser des cadres dégradés. Dans ce cas, si vous sélectionnez -100 pour "lightness", et réduisez la chrominance, la "bordure" sera noire.
* pour la luminance et le contraste (curseur), vous avez le choix entre 2 algorithmes : le premier (par défaut) est très proche de ce qui était présent jusque là, le second activé par "Lightness Contrast super" est proche de celui utilisé pour les courbes "super"
* ne pas hésiter selon le cas, à activer "Global quality" = enhanced et (défaut) enhanced + chroma denoise"
====Courbes====
*Une courbe L=f(L) et une C=f(C) permet de moduler la luminance ou la chrominance pour chaque RT-spot (spot de contrôle) en fonction de la luminance ou de la chrominance.
*Une courbe L=f(H) permet de moduler la luminance pour chaque RT-spot en fonction de la teinte.
*Une courbe H=f(H) permet de moduler la teinte pour chaque RT-spot en fonction de la teinte.
Pour les rendre actives, il est nécessaire d'activer la combobox "Curves type".
* deux choix sont offerts :
** a) Normal : les courbes - notamment la plus complexe à gérer L=f(L) utilise un algorithme proche de celui utilisé avec les curseurs (mode Normal);
** b) Super : utilise un nouvel algorithme que je pense très performant (le résultat m'a même surpris à la première utilisation).

Attention, lorsque le spot est située dans une zone grise, ou des zones assez uniformes, les artefacts avec le nouvel algorithme (L=F(L) super, et Lightness Contrast super) peuvent être impossible à supprimer, dans ce cas privilégier l’algorithme "normal".

===Exposure===
Ce module "ressemble" à celui en mode global RGB, mais :
* il fonctionne entièrement en mode L*a*b*, d'où des différences de rendu;
* il n'a pas les curseurs "lightness, chroma et contraste" dont les fonctions sont déjà présentes dans "Color and Light"
* il y a une seule courbe "contraste", similaire à celle de L=F(L) présente dans "Color and Light". Il est évident que le rendu de cette courbe est différent de "Tonecurve" qui agit en mode RGB. Vous pouvez si vous le souhaitez activer les 2 courbes L=f(L) dans "Color and Light" et "Exposure"

===Vibrance===
Module similaire à celui du menu principal.

===Blur and Noise===
Blur n'est actif que si Radius supérieur ou égal à 2.

En réduisant notablement la valeur par défaut de "scope" et en agissant éventuellement sur "Luminance only" il est possible d'obtenir des flous différenciés selon la teinte.

Vous disposez (octobre 2017), de 3 méthodes :
* "normal" : l'algorithme de détection de forme a été amélioré. Il se rapproche de celui utilisé dans les autres modules.
* "inverse" : algorithme simplifié, ne faisant pas intervenir "scope". L'inversion est grossière et ne permet pas une séparation fine des zones à traiter / conserver.
* "symmetric" : ce nouvel algorithme utilise les mêmes processus que "normal" et par l'utilisation de "scope" l'utilisateur peut cibler plus précisément l'action.

Attention:
* travailler en mode inverse, va flouter des zones importantes qui ne pourront pas être corrigées ensuite
* l'action de "scope" peut être déroutante dans certains cas : par exemple pour un portrait les yeux - différents de la peau - seront floutés si "scope" est trop faible.

===Tone mapping===
Attention aux artefacts lorsque les aplats (ciels, zones grises...) sont d'une teinte similaire au spot de contrôle. Dans le cas d'artefacts, mettre le curseur "iterations" de "Reduce artefacts - improve algorithm" à zéro.

===Retinex===
Le nombre de réglages est réduit, par rapport au mode standard. D'autre part, "Retinex local" agit en fin de processus contrairement au mode standard qui est au début du processus Raw.
Depuis la version mip 10002, la courbe "transmission gain" est spécifique à chaque RT-spot.

===Sharpening===
Seul le mode "RL deconvolution" est proposé.

===Contrast By Detail Levels===
* 5 niveaux au lieu de 6 pour le mode pleine image.
* pas de curseurs pour la gestion de la peau; le système utilisé par les RT-spot le remplace.
* ajout d'un curseur pour la chroma
* Attention aux artefacts lorsque les aplats (ciels, zones grises...) sont d'une teinte similaire au RT-spot. Dans le cas d'artefacts, mettre le curseur "iterations" de "Reduce artefacts - improve algorithm" à zéro.

===Denoise===
* par rapport au mode pleine image, seul l'outil wavelet est utilisé: donc pas de fonction de Fourier, ni de medians
* moins de curseurs et de courbes
* par contre, vous pouvez différencier l'action sur la luminance et la chrominance en fonction de la grosseur du bruit - fine ou coarse.

==Cas d'usage spécifique : réduction des défauts (capteur sale, yeux rouges, ...)==
Par conception "Locallab" n'a pas été conçu pour éliminer ces défauts. Néanmoins par effet de bord, certains défauts apparents et gênant en photographie peuvent être réduits voire supprimés. Ceci bien sûr n'est pas incompatible avec d'autres modules plus spécialisés incorporés ou non à "Locallab"...
Au moins 3 fonctions présentes, en adaptant l'usage, peuvent être utilisées, séparément ou ensemble :
* "Color and light" pour des défauts ponctuels ;
* "Contrast by detail level" pour des défauts répartis ;
* "Blur and Noise" en complément éventuel : attention cette action est assez destructrice - à utiliser avec modération.

Vous pouvez agir soit:
* directement, cas général, sur le fichier "raw", ou "TIF", etc.
* soit sur le fichier flat-field si vous en avez élaboré un.

===Utilisation avec le module "Color and Light"===
* Activez "Color and Light"
*Vous pouvez utiliser l'équivalent d'une fonction "yeux rouges" en choisissant un encadrement assez serré de l’œil - sélecteur circulaire centré sur le rouge, délimiteurs de spot proches de l’œil - une valeur de scope réduite, puis agir sur réduction "lightness" -100, et réduction chrominance -100.
*De la même manière vous pouvez réduire les défaut du capteur de type "Spot IR", en choisissant un encadrement assez serré du défaut - sélecteur circulaire centré sur le défaut, délimiteurs de spot proches du défaut - puis agir sur "chrominance" en réduisant la valeur, agir éventuellement sur "scope" pour réduire l'étendue de l'action.
*Vous pouvez dans des cas simples, réduire les défauts de type "capteur encrassé" notamment lorsque celui-ci est gras. Ceci se traduit par des taches qui apparaissent sur les fonds unis. Pour cela choisissez un encadrement assez serré du défaut - sélecteur circulaire centré sur le défaut (adaptez la taille du spot) , délimiteurs de spot pas trop proches du défaut pour permettre une transition peu visible. Puis: a) réduisez "Transition" à des valeurs faibles; b) cochez "Lightness contrast super"; c) agissez sur "luminance" et éventuellement sur "chrominance" pour approcher le rendu de la zone polluée à celui de la zone saine; d) agir modérément sur "scope" pour moduler l'action souhaitée.

===Utilisation avec le module "Contrast by detail levels"===
Dans le cas de capteur encrassé (de type "graisse"), et lorsque la zone est importante ou pour une série de petits défauts, Il peut être utile d'utiliser "Contrast by details levels" qui va agir comme un outil "wavelet" sur la luminance et aussi si nécessaire sur la chrominance. Dans ce cas: a) mettez le Spot de sélection sur un défaut prononcé (en adaptant sa taille si nécessaire); b) choisissez une zone de sélection large pour couvrir la majorité de la surface concernée par les défauts; c)Sélectionnez une valeur de transition assez importante; d) Activez "Contrast by detail levels" et agissez sur les niveaux 3 et 4 ou plus faibles en réduisant le contraste (valeurs inférieures à 100) et en agissant si nécessaire sur le curseur chroma.

== Temps de traitement et utilisation de la mémoire ==

Lorsqu'on utilise la sortie JPG ou TIF, et pour le mode "normal", l'algorithme n'effectue les calculs que pour la zone délimitée. En ce sens les temps de traitement et l'occupation mémoire sont réduits.
Bien sûr le temps de traitement va dépendre du nombre de spots de contrôles, de leur taille, et du type de traitement.

Si on exclue "Denoise" et "Sharp", les temps de traitement sont de l'ordre de quelques dixièmes de seconde par spot de contrôle, et le besoin en mémoire de l'ordre de quelques centaines de M.

Deux réglages agissent fortement sur les temps de traitement et le besoin en mémoire :
* denoise qui ajoute selon la taille du spot de contrôle de l'ordre de 1 seconde et 1 M de mémoire.
* quality enhanced and chroma denoise, qui ajoute environ selon le spot de contrôle de l'ordre de 0.5 secondes et 0.6 M.

==Onglet Preferences==
J'ai regroupé ici, les réglages (repris par ailleurs sur cette page) accessibles depuis "Preferences"
* si vous sélectionnez en "Preferences" / "General" / "Local adjustements", en cochant la case "Show spot delimiters", vous obtiendrez une approximation de la zone concernée par le spot et ses réglages
* Vous pouvez choisir la valeur par défaut de "Global Quality", par exemple si vos images sont très peu bruitées, et ainsi réduire notablement les temps de traitement.Pour cela, aller dans "Preferences", "Performance and Quality", "Local adjustements" et choisir entre Les 3 propositions. C'est ce choix qui sera proposé par défaut à l'utilisateur pour chaque nouveau "Spot", bien sûr il est possible ensuite de modifier ce choix, en sélectionnant la combo-box "Global Quality"
* Fichiers "mip":
**le choix de l'emplacement est possible à partir de : Preferences / Image processing / Mip Profiles
** effacement : aller dans "Preferences" / "Files browser", puis "Clear mip" et / ou "clear pp3" - si bien sûr vous avez positionné "mip" et "pp3" dans le cache, sinon il faudra exécuter cette opération manuellement dans le dossier courant. La présence d'anciennes versions de fichiers "mip" ou de "pp3" peut amener de l'instabilité voire un crash du système.

==Évolutions==
En dehors des habituelles mises aux points, bug, améliorations, réglages, interface, etc. Il serait souhaitable :
* d'améliorer le GUI, pour pouvoir créer / sélectionner / modifier chaque point de contrôle.

En termes "informatique", il devrait être possible pour accroître la lisibilité et la maintenance, d'intégrer l'ensemble du code fichiers *.mip qui actuellement sont linéairement intégrés à Improccoordinator.cc, dcrop.cc et simpleprocess.cc à des procédures "void", à l'exemple de rgbproc.cc

Local Adjustments/fr

2017-10-26T17:38:11Z

Sguyader: /* Réduction des défauts: capteur sale - yeux rouges - ... */

== Quel type de contrôle local? ==
Lorsqu'on observe les différents logiciels du marché on trouve plusieurs types de contrôles locaux
# les contrôles de type "lasso", associés à des calques et masques de fusion, comme par exemple dans Photoshop (c). Ce type de contrôle est majoritaire dans les logiciels (Photoshop, Gimp, Darktable...) et l'avis des utilisateurs est obligatoirement orienté vers ceux-ci au détriment du point 3) ci-dessous moins connu!
# les dispositifs de suppression de "yeux rouges", ou de "spot" liés aux imperfections du capteur
# les contrôles de type U-points, utilisés jusque récemment dans Nikon Capture NX2 (c), ou comme complément à d'autres logiciels comme Nik Software (c). Pour qui a tâté de ces dispositifs (rares maintenant) il n'est pas question de revenir aux calques et masques de fusion! Ce type de contrôle nécessite un apprentissage différent de ceux de type lasso-calque et un désapprentissage cognitif de ceux-ci. De mon point de vue, ils sont globalement plus performants.

Dans la version présente de Rawtherapee, l’algorithme développé est proche dans le principe du point 3) ci-dessus, les U-points. Bien sûr, le code de Nik Software est inconnu, mais il y a quelques années j'ai été séduit par la facilité d'utilisation et les performances des U-points, et j'ai entrepris de développer un produit qui ne ferait pas appel, ni au lasso, ni aux calques, ni aux masques de fusion.

Bien sûr rien n'interdit d'avoir les 3 possibilités (Lasso-calque, retouches spot, U-points) !

La version actuelle est très certainement perfectible, au niveau de l'interface graphique - GUI - notamment:
* pour le suivi et repérage des RT-spot (spot de contrôle) à l'écran
* pour les réglages des différents curseurs qui gagneraient à être intégrés au spot de contrôle, comme le fait Nik Software (c).
Cependant, ces deux points n'affectent pas ni l’utilisation courante, ni la portabilité.

J'ai ajouté, pour faciliter l'utilisation et éviter les menus trop longs en mode écran, une interface GUI similaire à celle de Wavelet, avec des "expanders".
Vous avez ainsi la possibilité pour chaque famille d'action (color and light, Blur, Retinex, etc.):
# faire apparaître ou non le détail des commandes : curseurs, méthodes, courbes,..
# activer ou non l'ensemble des fonctions de la famille d'action.
Attention, le choix - 2 - active ou annule l'ensemble des RT-spot ( spot de contrôle); il est théoriquement possible d'associer cette possibilité à chaque RT-spot, mais quel intérêt ?

===Contrôles locaux Lab et RGB===
* Les premiers algorithmes sont écrits en mode L*a*b* avec les contrôles suivants : "Color and Light", "Blurr addnoise", "Retinex", "Tone mapping", "Sharpen", "CBDL", "Denoise"..Deux contrôles suivants ont été ajoutés : "Exposure", "Vibrance"...
* Voir ci-dessous le principe des algorithmes, mais un des points clefs à retenir pour la détection de forme et la prévention des artefacts est que le mode Lab préserve la teinte "hue", qui joue un rôle déterminant.
* L'idée d'un module "RGB" vient évidemment à l'esprit, avec ''a minima'' un module :
** White Balance : qui permettrait une retouche de la balance des blancs par exemple pour "réchauffer les parties à l'ombre", ou permettre le mélange de deux éclairages par exemple "lumière du jour" et "Tungsten". Ce module doit être placé juste après "demosaic".

====White balance auto====
Le module "white balance" (branche "autowblocal") vise deux objectifs :
* permettre la retouche locale de la Balance des blancs (évident!)
* tester de nouveaux algorithmes de Balance des blancs automatique :
** en usage général (full image), afin d'obtenir de meilleurs résultats que l'algorithme actuel. Bien sûr on va me rétorquer qu'il faudrait une branche spécifique "White balance", mais j'essaie de faire d'une pierre deux coups.

Pour mémoire en 2012 et 2013, il m'avait été demandé, de mettre en place la balance des blancs itérative "Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]". A l'époque avec un autre développeur nous avons passé beaucoup de temps pour un résultat assez peu satisfaisant... d'où l'abandon. Depuis, fort de cette expérience j'ai repris le travail mais à l'envers ! Maintenant - si je ne me suis pas trompé - l'algorithme fonctionne.
J'ai profité de cette possibilité (actuellement uniquement pour des images RAW), pour rechercher dans la littérature universitaire, d'autres algorithmes auto. J'ai trouvé et mis au point deux nouveaux algorithmes :
* "auto edge[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]" : l'idée ici est de créer un masque d’accentuation pour permettre de renforcer les parties de l'images où il y a des détails par rapport aux aplats.
* "auto standard deviation[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]" : l'image (ou la partie d'image pour le mode local) est divisée en 12 zones. Pour chacune on calcule moyenne et écarts type, puis on assemble le résultat.
Un troisième algorithme semble prometteur "Color by correlation[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf]", mais je me heurte à quelques difficultés...Après beaucoup de tests en tous genres, les résultats sont erratiques...

J'ai ajouté la notion de gamma:
* les mêmes principes concernant la répartition de la luminance - gamma sRGB - utilisé dans le code de Rawtherapee

A titre de rappel, la balance des blancs automatique est un problème mathématique totalement indéterminé. Il est possible d'avoir des algorithmes plus ou moins performants (et aussi plus ou moins rapides ou lents), mais en aucun cas le résultat sera parfait ! Pourquoi est-ce impossible ? Si on se réfère aux principes de la gestion des couleurs [[http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]], il est nécessaire de connaitre à la fois l'objet coloré, l'illuminant et l'observateur. Il y a au moins 2 familles d'inconnues. De plus l'environnement de prise de vue n'est pas connu et influe sur la perception (CIECAM) ainsi que l'environnement de traitement et de visualisation. Donc, mission quasi impossible !

L'objectif du module '''"White balance" est de tester les algorithmes''', au total il y en a 7 et le double (au moins) si on prend en compte le "gamma sRGB". En effet pour contourner les obstacles d'il y a 5 ans, j'ai utilisé au lieu de l'image avant demosaic, l'image juste après demosaic, sur laquelle on peut ou non appliquer le "gamma sRGB", pour se retrouver dans les mêmes conditions qu'en usage normal (sinon bien sûr sans "White Balance" et sans profil "ICC ou DCP").

L'idéal est de tester sur de nombreuses images les divers algorithmes "auto" avec un objectif : quel(s) algorithme(s) retenir et implanter en mode "full image" (peut être 1 ou 2 en plus de l'actuel qu'il faut garder pour compatibilité).

====White balance contrôle local====
Le contrôle local est actuellement limité à 1 spot, mais pas de difficultés si les utilisateurs le souhaitent d’accroitre...En attendant les évolutions de "locallab".

Bien sûr il me sera dit "cela ne fonctionne pas", ou "on ne se raccorde pas avec le 'preview'". Cela fonctionne ! Et il est plus qu'évident que atteindre le preview est par définition quasi impossible... (différences ombres , soleil, illuminants différents, etc.) en dehors de la pertinence de l'algorithme.

Vous disposez de 3 sliders : temperature, tint, blue/red equalizer

== Quels défis à résoudre? ==
Plusieurs problèmes généraux sont à résoudre afin d'obtenir un fonctionnement fluide :
* permettre un nombre quasi illimité de RT-spot (spot de contrôles);
* adapter les algorithmes locaux aux problèmes d'échelle, car beaucoup d'algorithmes tiennent compte de la taille de l'image - donc de la zone traitée. Cet aspect est fondamental, notamment avec les courbes qui agissent sur toute l'image;
* minimiser l'occupation mémoire et les temps de traitement en sortie JPG et TIF;
* permettre des mises à jour logicielles faciles en cas d’évolution des algorithmes ou d'évolution du nombre de méthodes ;
* optimiser les écarts entre "preview" et sortie JPG / TIF;
* etc.

Pour chaque RT-spot :
* permettre selon le cas, une action dans la zone sélectionnée ou à l'extérieur de la zone sélectionnée;
* permettre selon le cas une détection de forme pour délimiter l'action;
* assurer une transition entre le cœur de la zone traitée et le reste de l'image;
* etc.

Actuellement, les RT-spot (spot de contrôles) sont opérationnels, pour le mode Lab, et pour les méthodes suivantes:
# Color and light : lightness, chrominance, contraste en mode normal avec quatre courbes L=f(L), L=f(H), C=f(C), H=f(H) et inverse ;
# Exposure : en mode normal
# Vibrance : en mode normal
# Blur and Noise : en mode normal et inverse;
# Retinex : en mode normal et inverse, maintenant avec gestion de la courbe "transmission gain";
# Sharpening : en mode normal et inverse;
# Contrast By Detail Levels : en mode normal;
# Denoise : en mode normal.

== Principes généraux ==
===L'Objet RT-spot===
Comme je l'ai évoqué, le système utilisé est proche de celui mis au point par Nik Software, avec de grandes différences :
* chaque RT-spot, peut être considéré comme un objet qui comporte plusieurs champ - à ce jour environ 70, constitués de curseurs, courbes;
* chaque champ, regroupé en paquets peut être ou non activé, et peut avoir des valeurs variables selon sa nature ;
* les paquets sont des ensembles cohérents pour l'utilisateur : color & light, exposure, contrast, vibrance, blurr, retinex, sharpening, tone-mapping, contrast by detail level, denoise ;
* le nombre de "RT-spots objets" peut varier de 2 à 500 ;
* les données des "RT-spots objets" sont stockées dans un fichier texte "mip";
* les "RT-spots objets" sont gérés - création, modification, suivi - dans une boucle "for";
* il n'y a pas de duplication de code.

===Le découpage en quatre zones - l’aperçu de la zone RT-spot===
Lorsque l’utilisateur sélectionne un RT-spot (spot de contrôle),l’image à l’écran montre:
* un centre, constitué d'un cercle dont on peut faire varier : a) le diamètre, b) la position avec la souris ou les curseurs;
* quatre lignes horizontales ou verticales dont on peut faire varier les positions avec la souris ou les curseurs.
* si vous sélectionnez en "Preferences" / "General" / "Local adjustements", en cochant la case "Show spot delimiters", vous obtiendrez une approximation de la zone concernée par le spot et ses réglages. Attention, je ne suis pas arrivé à un travail propre avec la fonction "arc / ellipse / scale" de la bibliothèque graphique Cairo; j'ai donc opté pour chaque "quart" à une pseudo ellipse obtenue par 3 courbes de Bézier se raccordant entre elles. Dans la majorité des cas l'approximation est satisfaisante...Pour permettre une sélection plus facile j'ai été amené à accroître la taille des 4 lignes horizontales et verticales qui sélectionnent la taille du spot (les courbes de Bézier sont inactives!).

On aboutit à 4 zones, dont on ne peut faire varier l'orientation (angle d'inclinaison obligatoirement à zéro).
Ces 4 zones ont chacun de leurs sommets reliés par une ellipse imaginaire.

Il est possible de pointer les limites des zones en dehors de la zone "preview".

A terme, il doit être possible, même si l'utilité me semble discutable du fait de l'algorithme de détection de forme, de remplacer l'ellipse, par une courbe tracée à l'aide de la souris, à condition que la transformée homothétique de la courbe n'ait pas d'intersection avec la courbe originale. Cette "amélioration" intellectuellement satisfaisante, ne devrait être que d'un apport négligeable - dans le cas des U-points. Néanmoins il sera toujours possible de faire coexister les actuels U-points avec des contrôles par"lasso" de type Photoshop (c).

===Les références teinte, chroma, luminance et le principe de l'algorithme en mode "normal"===
Afin de mettre en œuvre un algorithme performant de détection de forme :
* la zone du cercle central, sert de référence. En fonction du diamètre choisi par l'utilisateur, le système calcule, la moyenne de la teinte (hue), de la chroma, et de la luminance.
* le choix du diamètre de la zone centrale dépend de l'usage. Par exemple pour un feuillage, l'utilisateur aura intérêt à choisir une valeur faible afin de ne sélectionner que le vert du feuillage; à l'inverse pour la peau l'utilisateur aura intérêt à accroître le diamètre afin d'éviter les prises en compte de données parasites (bruit, cils, etc.).
* pour chaque quart, et en fonction du curseur "scope", le système prend en compte :
# en premier lieu de l'écart de teinte entre la zone centrale et le pixel courant ;
# puis, un algorithme complexe, s'appuyant sur la notion de deltaE (différence perçue entre 2 couleurs prenant en compte, la teinte, la chroma et la luminance), atténue l'action en fonction de l'écart entre la zone centrale et le pixel courant.
# la modification d'action utilise soit une loi linéaire, soit une loi parabolique selon le cas.

Ceci va permettre de différencier l'action selon les critères énoncés ci-dessus, comme par exemple, si le cercle central se trouve dans un feuillage, de limiter l'action à l'ensemble du feuillage sans toucher à l'arrière plan (ce qui est impossible avec un lasso). De plus si un autre feuillage se situe dans la zone couverte, celui-ci sera également concernés par la modification.

* l'action sur le curseur transition va permettre de faire varier l'action : si le curseur est réglé sur 50, la moitié (linéaire) de la zone concernée verra une application à 100% de l'effet, puis une transition agira régressivement jusqu'aux limites de la zone.
* si on accroît la valeur de "scope", progressivement l’ensemble de la zone sélectionnée est prise en compte quelque soit la couleur, la chroma et la luminance.
* si on réduit la valeur de "scope",l'action se limitera aux pixels très proches (en termes de deltaE) de la zone de référence.

L'algorithme de détection de forme est opérationnel en mode "normal" sauf pour certains modules (denoise) - son implantation en mode inverse n'a pas de sens.

Cet algorithme va avoir ses performances accrues, si l'utilisateur choisit : "Quality Enhanced" ou "Qualty enhanced + chroma denoise". Ce second choix apporte une très légère réduction du bruit de chroma afin de supprimer les artefacts possibles liés à l'utilisation de "enhanced" (à noter dans le cas + chroma denoise, un accroissement des besoins en mémoire et du temps de traitement).

L'algorithme utilise toutes ses capacités, si les valeurs de "scope" sont inférieures à 20.

===Pourquoi pas d'autres algorithmes? ===
Remarque : il doit être possible de programmer d'autres algorithmes de détection de forme que celui ci-dessus fondé sur les différences de deltaE.

* Par exemple les algorithmes de détection de bords (edge) tels que "Canny" ou "Sobel";
* Ou encore le principe de décomposition en ondelettes.
Mais dans ces 2 cas tout reste à faire !

===Le fonctionnement en mode inverse===
Lorsqu'il est proposé, le fonctionnement en mode inverse est extrêmement simplifié, seul le curseur "transition" permet de moduler l'action.

A partir de fin octobre 2017, j'ai mis au point une autre manière de concevoir le mode "inverse". Cette manière est limitée à l'outil "Blur and Noise" (voir ce paragraphe)

===Nombre maximum de RT-spot (spot de contrôle)===
Par défaut le nombre de RT-spot est de 8.
Vous pouvez choisir n'importe quelle valeur entre 2 et 499. Pour cela il suffit de changer la variable Nspot dans le fichier "option"; par exemple Nspot=12.
Il est indispensable de relancer Rawtherapee après cette modification.

===L'algorithme 'super'===
La clef du "succès" (si on peut utiliser ce terme) tient à l'algorithme présent depuis fin janvier 2017. je vais l'expliciter de manière simplifiée :
# pour la partie des données concernées par la zone sélectionnée, on applique une fonction courbe "traditionnelle" ou un curseur classique, ou la fonction de transfert normale (Retinex, Tone mapping, CBDL, Vibrance, ...);
# puis on réalise une conversion de la LUT ou de la fonction de transfert , en un équivalent "slider", en séparant les valeurs positives et négatives, afin d'avoir une représentation de la fonction comme une multitude de "sliders" (autant qu'il y a de pixels concernés) dans l'intervalle -100, 0, +100
# on passe ces données à la fonction de reconnaissance de forme - celle des 4 zones. On détecte pour chaque pixel l'écart de teinte, chroma et luma par rapport à la référence. On établit des équations de variations linéaire selon le cas de la luminance (L = f(L)) ou de la chroma (C=f(C) ou des fonctions de transfert).
# puis on applique diverses corrections pour tenir compte de l'environnement, ciel, peau,...
# enfin, on applique une correction (avec seuil et itérations)pour ne pas corriger (ou le faire faiblement selon le choix de l'utilisateur), les tons gris ou neutres qui sont dans la même teinte que la référence (mais avec une chroma faible).
# ces paramètres sont ensuite pondérés en fonction, de la forme (ellipse) et de la zone de transition.
# bien sûr les réglages des paramètres qualité "Global quality", ont leur importance, notamment dans les images légèrement bruitées - le bruit chromatique est considéré par l'algorithme comme de la même couleur que le spot. Il faut donc avoir la possibilité de le supprimer, d'où la sélection "enhanced + chroma denoise" (il est possible que ce réglage soit insuffisant, agir en conséquence sur "Denoise local" si nécessaire).

Cet algorithme nouveau ('super') semble généralement fonctionner, mais dans le cas où le spot est sur une zone gris - neutre ou l'action sur des zones à faible gradient, l'algorithme peut être pris en défaut, dans ce cas utiliser l'ancien (quand c'est possible !!), car pour Retinex, Tone Mapping, CBDL je n'ai pas offert ce choix par souci de simplification)

===Réduction des artefacts et l'algorithme "Global quality"===
Par défaut, "Global quality" est à "Enhanced + chroma denoise". Certes cela augmente les temps de traitements, mais globalement c'est préférable. Vous pouvez, si vous trouvez les temps de rafraichissement long, choisir "enhance" ou "standard" et examiner l'image...
* 2 curseurs permettent de réduire les artefacts et améliorer le rendu de l'algorithme. Ils agissent en fonction de la chroma, dans les tons gris neutres. Pour désactiver complètement l'effet il suffit de mettre "iterations = 0". Ces curseurs permettent, d'une part de réduire les artefacts et, d'autre part d'agir sur le rendu de l'image. L'action est possible pour "Color Light", "Exposure", "Retinex", "Vibrance", "Tone Mapping" et "Contrast by details levels".
* lorsque les images sont bruitées, même légèrement (beaucoup d’images sont bruitées sans que cela soit gênant par exemple les ciels, les nuages,...), les algorithmes sont "trompés", ne pas hésiter à laisser activé "Global quality = enhanced + chroma denoise" et (quelquefois) activer "denoise local" et agir très légèrement sur les curseurs (y compris luminance).
* dans certaines circonstances, par exemple avec Tone-mapping, le système de réduction d'artefacts peut générer des artefacts. Dans ce cas, mettre le slider "iterations" à 0.

Vous pouvez choisir la valeur par défaut de "Global Quality", par exemple si vos images sont très peu bruitées, et ainsi réduire notablement les temps de traitement.
Pour cela, aller dans "Preferences", "Performance and Quality", "Local adjustements" et choisir entre Les 3 propositions. C'est ce choix qui sera proposé par défaut à l'utilisateur pour chaque nouveau "Spot", bien sûr il est possible ensuite de modifier ce choix, en sélectionnant la combo-box "Global Quality"

===Avoid color shift===
Cette case à cocher vise deux objectifs :
* mettre les couleurs dans le gamut de l'espace de travail courant (working profile) en utilisant une colorimétrie relative ;
* ajuster les couleurs à l'aide d'une correction "Munsell" - notamment les rouges-orangés et les bleus-pourpres, lorsque la saturation dans le domaine L*a*b* a évolué notablement.

===Les fichiers *.mip - les principes de l’algorithme multipoints===
Afin de permettre le fonctionnement - enregistrement des valeurs pour chaque spot de contrôle - un fichier de type texte, assez proche des fichiers pp3 est enregistré à deux endroits possibles :
* à côté du fichier à traiter. Si par exemple vous traitez le fichier ASC4509.NEF, un fichier ASC4509.NEF.mip sera enregistré dans le même dossier. Si vous choisissez cet emplacement, vous pourrez ouvrir plusieurs sessions pour un même fichier image, si celui-ci est présent dans des dossiers différents. Par contre, le nom des dossiers et du "path" doit obligatoirement n'avoir que des caractères ASCII...sinon plantage.
* dans le dossier "mip", à l'intérieur du dossier "cache" (via un "hash number MD5" qui identifie le fichier). Valeur par défaut. Si vous choisissez cet emplacement, si le fichier image est présent dans plusieurs dossiers, il y aura plusieurs fichiers mip. Cette option permet d'utiliser des dossiers et "path" avec des caractères NON ASCII.
* le choix entre ces emplacements est possible à partir de : Preferences / Image processing / Mip Profiles

Ce fichier mip contient les données qui seront ensuite passées au programme, via d'une part les processus de type "procparams" et d'autre part des LUT qui permettent le fonctionnement en mode zoom.
Lors de la mise à jour d'une nouvelle version, il pourra dans certains cas être demandé d'effacer les fichiers *.mip (voire le cache) afin d'éviter un crash. Pour cela vous pouvez aller dans "Preferences" / "Files browser", puis "Clear mip" et / ou "clear pp3" - si bien sûr vous avez positionné "mip" et "pp3" dans le cache, sinon il faudra exécuter cette opération manuellement dans le dossier courant. La présence d'anciennes versions de fichiers "mip" ou de "pp3" peut amener de l'instabilité voire un crash du système.

====Architecture du système====
Lorsque je me suis "aventuré" vers la possibilité d'un système multipoints sans calques, sans masques,...il était obligatoire de refuser de dupliquer le code. Comment envisager par exemple pour 10 spot de contrôles, 10 codes GUI, et autant de code dans Rtengine.
Après réflexion, l’idée est venue d'avoir un fichier mis à jour en temps réel - c'est à dire qui suit les modifications faites par l'utilisateur - de l’historique des actions / modifications.

Bien sûr, les variables utilisées par Rawtherapee, au niveau de l'interface GUI, et par la suite dans l'ensemble du code via "params", sont de type divers:
* numériques : entier, float, double,...
* booléenne
* choix (menus pour "méthodes") de type string
* courbes via des "vectors" de type double a dimension dynamique.
* ...

====Conversion des données====
La première étape - afin de simplifier ensuite la gestion des données - est de convertir toutes ces données en entiers. Dans quelques cas cela peut aboutir à une très légère perte de précision, qui de mon point de vue est tout à fait négligeable.
*Cette opération est très simple pour les valeurs numériques, même si elle peut aboutir dans certains cas (la teinte - Hue - s'exprime en radians dans l’intervalle -Pi + Pi) par une double transformation "float * 100 et / 100" pour garder la précision.
*Elle est logique pour les opérations booléennes et les méthodes.
*Par contre elle s'est avérée complexe pour les courbes. Les valeurs à stocker dans le fichier texte sont de type vector<double> soit un tableau dynamique de valeurs numériques. Probablement il doit y avoir un moyen "plus simple" en utilisant les fonctions qui sont utilisées dans "Procparams", mais je ne suis pas arrivé à les mettre en œuvre. J'ai contourné l'obstacle en :
#transformant les valeurs doubles en entier avec 3 chiffres significatifs - ce qui est largement suffisant
#puis en convertissant le "vector" en une chaine de caractère de longueur variable
#la lecture et l'écriture de cette chaine et sa conversion en "vector" se faisant dynamiquement par une fonction appropriée ("strcurv_data"). A noter que cette fonction permet de modifier des courbes jusqu'à une limite de 16 points d'inflexion (Courbe de Beziers) pour la courbe plate, et 32 pour la diagonale, ce qui devrait être suffisant. Si c'était insuffisant (??) il est possible (via une perte de compatibilité) d'accroître ce nombre.

====Quelques éléments sur les courbes====
L'implémentation des courbes a été complexe, au delà de ce qui est écrit ci-dessus, notamment :
# chaque courbe doit obligatoirement avoir une fonction reset - resize() à chaque itération;
# ce qui implique des curiosités au niveau de leur description, par exemple la courbe diagonale est initialisée avec plusieurs points, alors qu'elle a l'air "vide". C'est indispensable au bon fonctionnement. Mais ceci a pour conséquence que cette courbe est toujours ouverte / active. Donc cela implique si on veut éviter des consommations de temps en mode "preview" que l'utilisateur "active" la courbe en activant la combobox "curves". Cette même activation est aussi nécessaire pour les courbes L=f(H) et C=f(C). Bien sûr, on se serait tenté de penser qu'il suffit d'activer le mode "enabled" de la fonction "courbes" (linéaire), mais après de nombreux essais cette démarche est infructueuse!
# tout au long des procédures, il est obligatoire de mettre "clear" chaque valeur de "params" pour les courbes, chaque LUT, pour chaque itération et ensuite via "vector" de réattribuer les bonnes valeurs courantes à "params courbe".

====Stockage et utilisation dynamique des données====
Une fois les données converties :
* elles sont stockées dans un fichier texte
* chacune est référencée dans un tableau dynamique à deux dimensions :
# dataspot[x][y], pour les valeurs numériques, booléenne et les méthodes, où 'x' représente l'indice représentatif de la variable, par exemple '9' correspond à 'Lightness', et 'y' représente le RT-spot (spot de contrôle) courant. La valeur '0' représente la valeur courante en cours d'utilisation (celle stockée dans 'params").
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] pour les variables de type "curve" (aujourd'hui il n'y a que 8 variables celle utilisée dans "Retinex" local, et celles dans "Color and light" (L=f(L), C=f(C), L=f(H), H=F(H))et "vibrance" et "exposure", mais il est assez facile d'en ajouter), avec 'y' comme ci-dessus.

Ce stockage et utilisation - nous reviendrons plus loin sur l'algorithme lecture / écriture dynamique - convient aisément pour le fichier Improccoordinator.cc (support de la gestion courante - Preview) et Simpleprocess.cc (sortie TIF / JPG), mais ne peut convenir, pour Dcrop.cc et la vision partielle de l'image (les fameux pipeline de Rawtherapee).

Pour ce cas (zoom - Preview) il a fallu imaginer autre chose, qui assure en temps réel la synchronisation des modifications. J'ai utilisé des LUT, dans le cas actuel, à chaque donnée référencée dans les tableaux ci dessus est associé une LUTi(z), avec z=500 entrées possibles (500 correspond à la limite informatique du nombre de RT-spot (spots de contrôles)...qu'on peut très facilement accroitre ou réduire). 'z' pour les LUTi correspond à 'y' pour dataspot. Une LUTi avec 25000 (arbitraire) entrées est utilisée pour "retistr", "llstr", "lhstr", "ccstr", "hhstr", "skinstr", "pthstr", "exstr" pour garder en mémoire (sous forme d'un entier) chaque valeur du 'Vector' de la courbe (il peut y en avoir jusque 69).

Au cours du traitement, des échanges sont réalisés entre: params, les tableaux dynamiques et les LUTi. Les valeurs utilisées par Dcrop.cc sont liées dynamiquement aux tableaux dynamiques par parent->.

====Processus d'échanges et stockage des données dynamiques ====
Sans entrer dans une description fastidieuse, je resterais aux principes généraux :
# lecture du fichier "mip" pour lire la version et orienter les mises à jour
# première écriture du fichier "mip" s'il n'existe pas
# stockage des données dans les LUTi et les tableaux dynamiques à partir des valeurs stockées dans "Params" (valeurs index 0)
# première mise à jour interactive avec le GUI via une fonction de transfert entre Rtengine et locallab.cc (aloListener->localretChanged). Cette fonction fait partie des 3 nécessaires pour obtenir un fonctionnement correct.
# lecture du fichier texte "mip" et stockage des données dans les tableaux dynamiques (valeurs index ==> y) - selon le nombre de RT-spot (spots de contrôle)
# Création d'une boucle - selon le nombre de RT-spot (spots de contrôle)- où à partir des valeurs stockées dans les variables tableaux dynamique, les LUTi (nécessaires à Dcrop) et les valeurs de Params sont actualisées.
# Appel de la fonction "Lab_local" qui contient les algorithmes de contrôle de chaque RT-spot (luminance, Sharp, retinex, denoise, etc.)
# deuxième mise à jour interactive avec le GUI via une autre fonction de transfert entre Rtengine et locallab.cc
# puis traitement du RT-spot (spot de contrôle) courant, en récupérant les valeurs index (0) des tableaux dynamiques. Ces valeurs sont attribuées à : 1) params, 2) LUTi, 3) valeurs index en cours
# Appel de la fonction "Lab_local" pour le RT-spot courant.
# sauvegarde du fichier "mip"

A noter que si l'utilisateur, modifie une courbe, amplitude ou nombre de points d'inflexion, une troisième mise à jour interactive est réalisée pour mettre en conformité l’ensemble des données en fonction des événements.

====Quelques fantaisies incontournables====
Bien sûr, tout à l'air simple, mais le système ne fonctionne que, si et seulement si, toutes les données sont dynamiquement mises à jour.

J'ai beaucoup essayé, tâtonné, pour aboutir à une solution qui fonctionne...certes curieuse; il y a probablement un moyen plus "informatique" de traiter cela, mais à ce stade, j'ai fait comme décrit ci-dessus et ci-après.

Les 3 échanges entre Rtengine et le GUI se font notamment avec 3 variables qui ne servent à rien dans le programme - sinon à mettre à jour:
# "anbspot" qui prend les valeurs forcées 0 ou 1
# "cTgainshaperab" (curve), dont je fais osciller une valeur entre 0.70 et 0.90
# "retrab" qui oscille autour de 500.

J'ai ajouté 3 variables (sous forme de "sliders") - hueref, chromaref, lumaref, totalement invisibles à l'utilisateur, mais qui servent à rafraichir le système en temps réel, pour permettre la bonne prise en compte des valeurs "spot" de référence.

Les appels aux changements de ces 3 variables amènent la stabilité au système et une mise à jour en temps réel.
Il ne devrait pas être nécessaire d’accroitre le nombre de ces variables "fantaisistes"

De plus j'ai été amené à empiriquement mettre des temporisations, pour laisser le temps au temps... C'est notamment le cas pour la modification de la courbe par l’utilisateur (amplitude, nombre de points d'inflexion).

Bien sûr ces variables sont invisibles pour l'utilisateur, sinon dans l'historique !

==Quelques particularités du mode local (par rapport à Lab adjustements)==

Voici quelques informations qui peuvent intéresser l'utilisateur. Ces informations sont souvent des particularités du mode local

===Color and Light===
*Les algorithmes utilisés pour la luminance et le contraste sont différents de ceux utilisés par "Lab adjustements", ce qui peut amener quelques différences de rendu.
*L'algorithme de luminance est réalisé de telle manière que en dessous de -90 et jusque -100 pour "lightness", il est possible d'accroître la "darkness" de l'image, pratiquement jusqu'à obtenir une valeur de luminance proche de 0. Si vous souhaitez accentuer cet effet, réduisez également la chominance et accroissez "scope".
*Le mode inverse, peut servir pour l'essentiel, à réaliser des cadres dégradés. Dans ce cas, si vous sélectionnez -100 pour "lightness", et réduisez la chrominance, la "bordure" sera noire.
* pour la luminance et le contraste (curseur), vous avez le choix entre 2 algorithmes : le premier (par défaut) est très proche de ce qui était présent jusque là, le second activé par "Lightness Contrast super" est proche de celui utilisé pour les courbes "super"
* ne pas hésiter selon le cas, à activer "Global quality" = enhanced et (défaut) enhanced + chroma denoise"
====Courbes====
*Une courbe L=f(L) et une C=f(C) permet de moduler la luminance ou la chrominance pour chaque RT-spot (spot de contrôle) en fonction de la luminance ou de la chrominance.
*Une courbe L=f(H) permet de moduler la luminance pour chaque RT-spot en fonction de la teinte.
*Une courbe H=f(H) permet de moduler la teinte pour chaque RT-spot en fonction de la teinte.
Pour les rendre actives, il est nécessaire d'activer la combobox "Curves type".
* deux choix sont offerts :
** a) Normal : les courbes - notamment la plus complexe à gérer L=f(L) utilise un algorithme proche de celui utilisé avec les curseurs (mode Normal);
** b) Super : utilise un nouvel algorithme que je pense très performant (le résultat m'a même surpris à la première utilisation).

Attention, lorsque le spot est située dans une zone grise, ou des zones assez uniformes, les artefacts avec le nouvel algorithme (L=F(L) super, et Lightness Contrast super) peuvent être impossible à supprimer, dans ce cas privilégier l’algorithme "normal".

===Exposure===
Ce module "ressemble" à celui en mode global RGB, mais :
* il fonctionne entièrement en mode L*a*b*, d'où des différences de rendu;
* il n'a pas les curseurs "lightness, chroma et contraste" dont les fonctions sont déjà présentes dans "Color and Light"
* il y a une seule courbe "contraste", similaire à celle de L=F(L) présente dans "Color and Light". Il est évident que le rendu de cette courbe est différent de "Tonecurve" qui agit en mode RGB. Vous pouvez si vous le souhaitez activer les 2 courbes L=f(L) dans "Color and Light" et "Exposure"

===Vibrance===
Module similaire à celui du menu principal.

===Blur and Noise===
Blur n'est actif que si Radius supérieur ou égal à 2.

En réduisant notablement la valeur par défaut de "scope" et en agissant éventuellement sur "Luminance only" il est possible d'obtenir des flous différenciés selon la teinte.

Vous disposez (octobre 2017), de 3 méthodes :
* "normal" : l'algorithme de détection de forme a été amélioré. Il se rapproche de celui utilisé dans les autres modules.
* "inverse" : algorithme simplifié, ne faisant pas intervenir "scope". L'inversion est grossière et ne permet pas une séparation fine des zones à traiter / conserver.
* "symmetric" : ce nouvel algorithme utilise les mêmes processus que "normal" et par l'utilisation de "scope" l'utilisateur peut cibler plus précisément l'action.

Attention:
* travailler en mode inverse, va flouter des zones importantes qui ne pourront pas être corrigées ensuite
* l'action de "scope" peut être déroutante dans certains cas : par exemple pour un portrait les yeux - différents de la peau - seront floutés si "scope" est trop faible.

===Tone mapping===
Attention aux artefacts lorsque les aplats (ciels, zones grises...) sont d'une teinte similaire au spot de contrôle. Dans le cas d'artefacts, mettre le curseur "iterations" de "Reduce artefacts - improve algorithm" à zéro.

===Retinex===
Le nombre de réglages est réduit, par rapport au mode standard. D'autre part, "Retinex local" agit en fin de processus contrairement au mode standard qui est au début du processus Raw.
Depuis la version mip 10002, la courbe "transmission gain" est spécifique à chaque RT-spot.

===Sharpening===
Seul le mode "RL deconvolution" est proposé.

===Contrast By Detail Levels===
* 5 niveaux au lieu de 6 pour le mode pleine image.
* pas de curseurs pour la gestion de la peau; le système utilisé par les RT-spot le remplace.
* ajout d'un curseur pour la chroma
* Attention aux artefacts lorsque les aplats (ciels, zones grises...) sont d'une teinte similaire au RT-spot. Dans le cas d'artefacts, mettre le curseur "iterations" de "Reduce artefacts - improve algorithm" à zéro.

===Denoise===
* par rapport au mode pleine image, seul l'outil wavelet est utilisé: donc pas de fonction de Fourier, ni de medians
* moins de curseurs et de courbes
* par contre, vous pouvez différencier l'action sur la luminance et la chrominance en fonction de la grosseur du bruit - fine ou coarse.

==Cas d'usage spécifique : réduction des défauts (capteur sale, yeux rouges, ...)==
Par conception "Locallab" n'a pas été conçu pour éliminer ces défauts. Néanmoins par effet de bord, certains défauts apparents et gênant en photographie peuvent être réduits voire supprimés. Ceci bien sûr n'est pas incompatible avec d'autres modules plus spécialisés incorporés ou non à "Locallab"...
Au moins 3 fonctions présentes, en adaptant l'usage, peuvent être utilisées, séparément ou ensemble :
* "Color and light" pour des défauts ponctuels ;
* "Contrast by detail level" pour des défauts répartis ;
* "Blur and Noise" en complément éventuel : attention cette action est assez destructrice - à utiliser avec modération.

Vous pouvez agir soit:
* directement, cas général, sur le fichier "raw", ou "TIF", etc.
* soit sur le fichier flat-field si vous en avez élaboré un.

===Utilisation avec le module "Color and Light"===
* Activez "Color and Light"
*Vous pouvez utiliser l'équivalent d'une fonction "yeux rouges" en choisissant un encadrement assez serré de l’œil - sélecteur circulaire centré sur le rouge, délimiteurs de spot proches de l’œil - une valeur de scope réduite, puis agir sur réduction "lightness" -100, et réduction chrominance -100.
*De la même manière vous pouvez réduire les défaut du capteur de type "Spot IR", en choisissant un encadrement assez serré du défaut - sélecteur circulaire centré sur le défaut, délimiteurs de spot proches du défaut - puis agir sur "chrominance" en réduisant la valeur, agir éventuellement sur "scope" pour réduire l'étendue de l'action.
*Vous pouvez dans des cas simples, réduire les défauts de type "capteur encrassé" notamment lorsque celui-ci est gras. Ceci se traduit par des taches qui apparaissent sur les fonds unis. Pour cela choisissez un encadrement assez serré du défaut - sélecteur circulaire centré sur le défaut (adaptez la taille du spot) , délimiteurs de spot pas trop proches du défaut pour permettre une transition peu visible. Puis: a) réduisez "Transition" à des valeurs faibles; b) cochez "Lightness contrast super"; c) agissez sur "luminance" et éventuellement sur "chrominance" pour approcher le rendu de la zone polluée à celui de la zone saine; d) agir modérément sur "scope" pour moduler l'action souhaitée.

===Utilisation avec le module "Contrast by detail levels"===
Dans le cas de capteur encrassé (de type "graisse"), et lorsque la zone est importante ou pour une série de petits défauts, Il peut être utile d'utiliser "Contrast by details levels" qui va agir comme un outil "wavelet" sur la luminance et aussi si nécessaire sur la chrominance. Dans ce cas: a) mettez le Spot de sélection sur un défaut prononcé (en adaptant sa taille si nécessaire); b) choisissez une zone de sélection large pour couvrir la majorité de la surface concernée par les défauts; c)Sélectionnez une valeur de transition assez importante; d) Activez "Contrast by detail levels" et agissez sur les niveaux 3 et 4 ou plus faibles en réduisant le contraste (valeurs inférieures à 100) et en agissant si nécessaire sur le curseur chroma.

== Temps de traitement et utilisation de la mémoire ==

Lorsqu'on utilise la sortie JPG ou TIF, et pour le mode "normal", l'algorithme n'effectue les calculs que pour la zone délimitée. En ce sens les temps de traitement et l'occupation mémoire sont réduits.
Bien sûr le temps de traitement va dépendre du nombre de spots de contrôles, de leur taille, et du type de traitement.

Si on exclue "Denoise" et "Sharp", les temps de traitement sont de l'ordre de quelques dixièmes de seconde par spot de contrôle, et le besoin en mémoire de l'ordre de quelques centaines de M.

Deux réglages agissent fortement sur les temps de traitement et le besoin en mémoire :
* denoise qui ajoute selon la taille du spot de contrôle de l'ordre de 1 seconde et 1 M de mémoire.
* quality enhanced and chroma denoise, qui ajoute environ selon le spot de contrôle de l'ordre de 0.5 secondes et 0.6 M.

==Onglet Preferences==
J'ai regroupé ici, les réglages (repris par ailleurs sur cette page) accessibles depuis "Preferences"
* si vous sélectionnez en "Preferences" / "General" / "Local adjustements", en cochant la case "Show spot delimiters", vous obtiendrez une approximation de la zone concernée par le spot et ses réglages
* Vous pouvez choisir la valeur par défaut de "Global Quality", par exemple si vos images sont très peu bruitées, et ainsi réduire notablement les temps de traitement.Pour cela, aller dans "Preferences", "Performance and Quality", "Local adjustements" et choisir entre Les 3 propositions. C'est ce choix qui sera proposé par défaut à l'utilisateur pour chaque nouveau "Spot", bien sûr il est possible ensuite de modifier ce choix, en sélectionnant la combo-box "Global Quality"
* Fichiers "mip":
**le choix de l'emplacement est possible à partir de : Preferences / Image processing / Mip Profiles
** effacement : aller dans "Preferences" / "Files browser", puis "Clear mip" et / ou "clear pp3" - si bien sûr vous avez positionné "mip" et "pp3" dans le cache, sinon il faudra exécuter cette opération manuellement dans le dossier courant. La présence d'anciennes versions de fichiers "mip" ou de "pp3" peut amener de l'instabilité voire un crash du système.

==Évolutions==
En dehors des habituelles mises aux points, bug, améliorations, réglages, interface, etc. Il serait souhaitable :
* d'améliorer le GUI, pour pouvoir créer / sélectionner / modifier chaque point de contrôle.

En termes "informatique", il devrait être possible pour accroître la lisibilité et la maintenance, d'intégrer l'ensemble du code fichiers *.mip qui actuellement sont linéairement intégrés à Improccoordinator.cc, dcrop.cc et simpleprocess.cc à des procédures "void", à l'exemple de rgbproc.cc

Local Lab Controls

2017-10-26T17:36:30Z

Sguyader:

==What kind of local control?==

Several types of local control exist in mainstream applications :
# “lasso”, associated with layers and fusion masks (e.g. Photoshop©). This kind of control is widespread (Photoshop, Gimp, Darktable…) and users tend to favor those, at the expense of the type desciribed in 3. below, which is less well known;
# dedicated tools for the removal of image defects such as “red eyes”, or “spots” associated with sensor imperfections or dirt;
# “U-points” controls, used until recently in Nikon Capture NX2©, or as an add-on to other software such as Nik Software©. For those (rare now) who tried such programs, there’s no way turning back to layers and fusion masks! This type of local control requires learning something different, and a cognitive “reprogramming”. In my opinion, this kind of local control is globally more efficient.

The algorithm developed in the current version of RawTherapee is close in its principle to the U-points described above. Of course, the code used in Nik Software is not disclosed, but several years ago I was attracted by the simplicity of use and the efficiency of U-points, and I started developing a product which would use neither lassos, nor layers or fusion masks. Of course, nothing prevents us from having all 3 types of local control in the same program.

The current version of the filter is perfectible, particularly regarding the user interface (GUI):
* for managing and viewing the RT-spots (control spots) on screen,
* for manipulating the different sliders, which would ideally be better if integrated to the actual control points, as done in Nik Software.

However, those two aspects don’t harm everyday use, nor code portability.

In order to improve manipulation and avoid long menus on screen, I added a GUI interface which is similar to the one used in the Wavelet tab, with “expanders”. Thus for each module (“Color and Light”, “Blur”, “Retinex”, …) you can choose to:
# display (or not) the full list of commands: sliders methods, curves…
# activate (or not) the all the functions of the module.

Warning: choice 2. activates or cancels all the RT-spots; it would be possible in theory to add this capability to every single RT-spot, but for what purpose?

===Lab and RGB local controls===
* The first algorithms are coded in L*a*b* mode with the following modules: “Color and Light”, “Blur / Add noise”, “Retinex”, “Tone mapping”, “Sharpen”, “Contrast by Detail Levels”, “Denoise”. Two additional modules have been added: “Exposure” and “Vibrance”.
* See below for the principles of the different algorithms, but one key point to remember for shape detection and artifacts avoidance, is that the Lab mode preserves the “hue” tint, which is crucial.
* The idea of an “RGB” module comes to one’s mind, with ''a minima'':
** a “White balance” module, which would allow to locally adjust the white balance, for example to warm up shadows, or to deal with mixed scene lighting such as “daylight” and “tungsten”. This module needs to be inserted just after “demosaic”.

====Auto White balance====
The “White balance” module (in the “autowblocal” branch) serves two purposes:
* allowing a local adjustment of the white balance (of course)
* testing new algorithms for automatic white balance adjustment:
** in general use (full image), in order to achieve better results than with the current algorithm. Of course one will tell me that I should create a specific branch for “White balance”, but here I’m trying to hit two targets with one bullet.

As a reminder, I’ve been asked in 2012 and 2013 to develop an iterative white balance “Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]”. At that time, another developer and I had spent a lot of time on this for an unsatisfactory result, so we gave up. Since then, benefiting from this experience, I resumed this work but in the reverse way! Now, if I’m correct, the algorithm works. I took advantage of this new capability (currently working on raw images only) to search in the academic literature for other auto WB algorithms. I found, and developed two new algorithms:
* “auto edge”[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]: the idea is to create an accentuation mask allowing to reinforce parts of the image where details are more prevalent, compared to flatter regions.
* “auto standard deviation”[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]: here, the image (or part of it for the local control) is divided in 12 zones, for each of which mean and standard deviation are computed, and the result assembled.
A third algorithm, “Color by correlation”[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf], looks promising but I’m facing several difficulties. After many trials of many types, the results are just too erratic…

I also added the notion of gamma:
* the same principles which deal with luminance distribution – gamma sRGB – used in the main RawTherapee code.

Bear in mind that the automatic white balancing is a totally non deterministic mathematical problem. The algorithms may perform more or less well (and faster or slower), but a perfect result can’t exist! Why is it so? If one is referring to the principles of color management ([http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]), it is necessary to have knowledge of the three of: the coloured object, the illuminant and the observer. At least two of those are unknown in practice. In addition, the environment in which an image is shot is not known while it has an effect on the perception (CIECAM), and the same is true during both image editing and viewing. The mission is thus almost impossible!

The aim of the “White balance” module is '''for testing the algorithms''', there are 7 of them at least, and twice that number if “gamma sRGB” is considered. Indeed, in order to circumvent the obstacles encountered five years ago, instead of the using the image before demosaicing, I used the image just after demosaicing, allowing to apply (or not) “gamma sRGB”, ending in the same conditions as in normal use (but without normal “White balance” and “ICC or DCP” profile).

Ideally, we should test the algorithms on many images, as well: which algorithm(s) to keep and implement in normal – global RGB – mode (maybe one or two, in addition to the current algorithm which we should keep for compatibility).

====Local control of White balance====
The local control is currently limited to 1 spot only, but there’s no difficulty to increase this if users want so… while waiting for the evolution of “locallab”.

Of course, I hear voices say “it doesn’t work”, or “the output doesn’t match with the preview”. But it does work! And it is more than evident that matching exactly the preview is by definition almost impossible… (differences between shadows, sun light, different illuminants, etc…) whatever the relevance of the algorithm.

==What are the challenges we need to solve?==
Several general issues need to be solved so as to achieve smoothness in use:
* allow an (almost) unlimited number of RT-spots (the name we chose for the control spots in RawTherapee);
* adapt the local algorithms to be aware of scale, because many of them take the image size – the treated area – into account. This aspect is fundamental, particularly with curves which act on the whole image;
* minimise memory use and computation time for JPG and TIFF output;
* allow easy updates in case of evolution of either the algorithms or the number of methods/modules;
* optimise (minimise) the differences between the preview and the output.
* etc…

For each RT-spot:
* allow for the action to occur, on user choice, either inside or outside (“Inverse” mode) of the selection area;
* allow shape detection, on user choice, in order to limit the action based on features/shapes;
* take care of the transition between the center of the treated area and the other parts of the image;
* etc…

Currently, RT-spots are operational in Lab mode with the following modules and methods:
# “Colour and Light”: “Lightness”, “Chrominance”, “Contrast” in normal mode with 4 curves L=f(L), L=f(H), C=f(C), H=f(H), and in “inverse” mode;
# “Exposure”: normal mode only;
# “Vibrance:” normal mode only;
# “Blur & noise”: normal and “inverse” modes;
# “Retinex”: normal and “inverse” modes, now also with “transmission gain” curve;
# “Sharpening”: normal and “inverse” modes;
# “Contrast by detail levels” (CBDL): normal mode only;
# “Denoise”: normal mode only.

==General principles==
===The RT-spot object===
As I mentioned earlier, the system used in RT is similar to the one developed in Nik Software, but with some significant differences:
* each RT-spot can be viewed as an object with a number of fields (about 70 as of today), made of sliders, curves, control points, etc…;
* each field, grouped in modules, can be activated or not, and have different parameter values according to their nature;
* the modules are made to be coherent for the user: “Color and Light”, “Exposure”, “Contrast”, “Vibrance”, “Blur”, “Retinex”, “Sharpening”, “Tone Mapping”, “Contrast by detail levels”, “Denoise”;
* the number of RT-spot objects can vary from 2 up to 500;
* data describing the RT-spot objects are stored in text files with .mip extension;
* creating, modifying and tracking of the RT-spot objects are done in a “for” loop;
* there’s no code duplication.

===Partitioning into 4 zones – previewing the RT-spot area===
When the user selects an RT-spot, the screen preview shows:
* a centre, made of a circle whose diameter and position can be adjusted directly using the mouse or the sliders;
* two horizontal and two vertical handles, whose position can be modified directly using the mouse or the provided sliders, controlling the extent of the area affected by the RT-spot;
* if "Show spot delimiters" is checked in "Preferences" > "General" tab > "Local adjustments", one can visualise approximately the area affected by the spot. Because I couldn’t work cleanly with the « arc/ellipse/scale » function in the Cairo graphics library, I made each quadrant defined by a pseudo-ellipse made of 3 Bézier curves joining each other. In most cases the approximation is satisfying… To help grabbing the 4 handles, I made them longer (the Bézier curves are inactive!).

We obtain 4 zones, whose orientation can be modified (the default rotation angle is set to zero). Those 4 zones have each of their vertices connected by imaginary ellipses.

It is possible to drag the handles outside the image preview area.

It should be possible to replace the ellipse with a hand drawn curve (even if I think its usefulness is debatable because of the existence of the shape detection algorithm), as long as the homothetic transform of the curve doesn’t intersect with the original curve. Although the benefits from this intellectually satisfying “improvement” should negligible in the case of the RT-spots, it will be possible to make the current RT-spots and lasso type of controls coexist eventually.

===Tint, chroma, luminance references and the algorithm principle in “normal” mode===
In order to develop an efficient shape detection algorithm:
* The central circle zone is used as the reference. Based on the diameter value chosen by the user, the algorithm computes the tint (hue), chroma and luminance averages.
* The choice of the central zone diameter depends on the use intent. For example, if working on a foliage area the user would benefit from choosing a smaller diameter value in order to select only the foliage green; in contrast, for skin tones the user should increase the diameter to avoid the detection of parasites (noise, eye lashes…).
* For each quadrant, depending on the the value of the “Scope” slider, the algorithm does:
# take into account the tint difference between the zone centre and the affected pixel;
# through a complex algorithm based on the deltaE notion (perceived difference between two colours, taking tint, chroma and luminance into account), decrease the amount of applied effect as a function of the difference between the central zone and the affected pixel;
# follow either a linear or a parabolic law to adjust the amount of applied effect, based on the specific the case.

This allows adapting the amount of effect according to the above-mentioned criteria. For example, if the central circle is located on foliage, the action will be limited to the leaves, without touching the background (which would be impossible to obtain with the lasso type of controls). Additionally, if some other foliage resides within the area covered by the RT-spot, it will also be affected.
* Adjusting the value of the “Transition” slider modifies the transition of the effect (from the centre to the edge): on 50, the inner (linear) half will get the full 100% action/effect, while the effect in the outer half will gradually transition from 100% to 0% towards the edge;
* By increasing the value of “Scope”, progressively more of the selected area is taken into account, whatever the tint, chroma and luminance;
* Conversely, by decreasing the “Scope” value the effect will get limited to the pixels which are more similar (in terms of deltaE) to the reference zone.

The shape detection algorithm works in “Normal” mode except for some modules (“Denoise”). It’s not implemented in “Inverse” mode, doing so would not make sense.

The algorithm will see its performance increase when the user chooses “Enhanced” or “Enhanced + chroma denoise” in the “Global quality:” combobox. The second choice additionally applies a low amount of chroma noise reduction in order to get rid of artefacts which could be brought up by the “Enhanced” algorithm (note that the chroma denoise step increases memory use and computing time).

The algorithm is used in full capacity for “scope” < 20.

===Why no alternative algorithms?===
It should be possible to implement other shape detection algorithms than the deltaE-based one used currently, for example:
* edge detection algorithms such as “Canny” or “Sobel”;
* wavelet decomposition.

But in both cases, everything would have to be done!

===Functioning in “inverse” mode===
When it is available, the “Inverse” mode is extremely simplified: only the “Transition” slider can be used to apply the effect.
As of late October 2017, I devised a new method for “Inverse” mode. It is limited to the “Blur & Noise” module (see the corresponding section below).

===Maximum number of RT-spots===
By default the number of available RT-spots is 8. You can choose any number between 2 and 499. For this you only need to change the parameter “Nspot” in the “options” file (for example: Nspot=12). Restart RawTherapee for the modification to be taken into account.

===The “super” algorithm===
The key to “success” was the algorithm implemented in late January 2017, which works this way:
# on the pixel data which are within the area covered by the RT-spot, the algorithm applies either a “traditional” curve, a slider, or a normal transfer function (“Retinex”, “Tone Mapping”, “Contrast by detail levels”, “Vibrance”, …);
# the LUT or the transfer function is converted into an equivalent of a slider, separating negative and positive values so that the function can be viewed as multiple sliders (as many sliders as there are pixels) in the -100, 0, +100 interval;
# the data are passed to the shape detection function – the 4 quadrants. For every pixel, the difference in terms of tint, chroma and luma is computed with regards to the central reference. The linear variation equations are estimated for luminance (L=f(L)), chroma (C=f(C)) or transfer functions;
# different corrections are applied to account for the environment (sky, skin tones…)
# a correction is made (with threshold and iterations) in order to avoid correcting (or only slightly, based on the user’s choice) the grey or neutral tones which are in the same tint as the reference (but with a low chroma value);
# the parameters are weighted based on the shape of the RT-spot (ellipses) and the transition zone;
# the values of the “Global quality:” parameters are important, particularly so for images with a low amount of noise – chroma noise is interpreted by the algorithm being of the same colour as the spot. It is thus necessary to suppress this noise, that is the purpose of “Enhanced + chroma denoise” (this algorithm may not be sufficient, though – in this case using the local “Denoise” module may be useful).

This new (“super”) algorithm seems to perform generally well, but in the event when the RT-spot is located in a grey/neutral or flat area, the algorithm may fail. In such cases, using the old algorithm is recommended (except for “Retinex”, “Tone Mapping” and “Contrast by detail levels” for which it is made unavailable for the sake of code simplicity).

===Artefact reduction and the “Global quality” algorithms===
By default, “Global quality:” is set to “Enhanced + chroma denoise”. Whereas it increases computation time, it is still generally preferable. In case one wants a more responsive preview, “Enhance” or “Standard” can be chosen (good for exploring the image).
* two sliders allow reducing artefacts and improving the algorithm’s rendering. They work based on chroma, in neutral/gray tones. To completely remove its effect, one can simply set “iterations=0”. These sliders may be used for "Color light", "Exposure", "Retinex", "Vibrance", "Tone mapping" and "Contrast by detail levels";
* for (even slightly) noisy images, the algorithms may be misled. In this case it is recommended to keep "Global quality:” set to “Enhanced + chroma denoise", and (sometimes) activate the local “Denoise” module and adjust the sliders very gently (including “Luminance”);
* under some circumstances, with “Tone Mapping” for example, the artefact reduction algorithm may actually generate more artefacts. When it happens, set “iterations=0”.

If your images are generally clean (no or very low noise), you can choose to have “Standard” as the default for “Global quality:” – this will speed up the image processing. To do so, go to “Preferences” > “Performance and quality” tab > “Local adjustments” and choose the “Standard” algorithm among the 3 options. This will become the new default when new RT-spots are created, but of course the algorithm can still be changed on the fly by choosing from the “Global quality” combo box.

===Avoid color shift===
The “Avoid color shift” checkbox serves two purposes:
* put the colours within the current working profile gamut, using a relative colorimetry;
* adjust colours using a “Munsell” correction – particularly for red-orange and blue-purple colours, when saturation in the L*a*b* space has changed significantly.

===“mip” files – Principles of the multi-point algorithm===
For the local control system to work and keep track of RT-spot objects, a text file – similar to a pp3 – is written in 2 possible places:
* next to the edited image file. If, for example, you edit an image named ASC4509.NEF, a new file named ASC4509.NEF.mip will be generated in the same folder. In this case, several sessions can be open for the same image, as long as copies of the image are stored in different folders. However, the folder names in the path have to contain ASCII characters only, otherwise it will make the program crash;
* in the dedicated “mip” folder, within the “cache” directory (through an MD5 hash number which identifies the file). This is the default. If chosen, when multiple copies of the same file exist in distinct folders, editing them creates as many “mip” files. This option allows the use of non ASCII characters in the folder names and path.

The choice between these two behaviours is made in “Preferences” > “Image processing” tab > “Mip profiles”.

The “mip” files contain the data which are passed to RawTherapee through processes of the “procparams” type, and LUTs which allow editing in zoom mode. When updating RawTherapee to a new version, it may be required to delete the “mip” files (or the whole cache) to avoid a potential crash of the application. This can be achieved by going to “Preferences” > “File browser” tab, then choosing “Clear mip” and/or “Clear pp3” – all this is valid only if “mip” and “pp3” files have been set to be saved to the cache folder, otherwise they will have to be manually deleted from the working folder. Keeping older “mip” and “pp3” files may lead to instability or crashes of the application.

====Architecture of the filter====
When I “ventured” into a multi-point, no-layer and no-mask system, code duplication had to be avoided. Indeed, it is unthinkable to consider, for 10 RT-spots, generating 10 GUI code blocks, and just as many code blocks in “rtengine”. After careful consideration, the idea was to have a file updating and tracking in real time – i.e. a file which would follow each modification made by the user – the actions/modifications history.

Of course, the parameters used by RawTherapee for the GUI and for the main code through “params” are of different types:
* numeric: integer, float, double,…
* Boolean
* string (in choice menus for the different modules)
* curves, through “vectors” of type double with dynamic dimension
* …

====Data conversion====
In order to simplify data management, the first step is to convert all data to integers. Sometimes this can lead to a slight precision loss, which I think is negligible.
* This operation is very simple for numeric values, even though in some cases (such as hue, which is expressed in radian in the interval [-Pi, +Pi]) it needs a double “float*100 and /100 conversion to keep precision.
* It is logical for Boolean operations and methods.
* However, it is a complex matter regarding curves. The values to be recorded in the “mip” file are of type vector<double>, in a dynamic table of numeric values. There may be a simpler way, by using existing functions from “procparams”, but I didn’t succeed.
Nevertheless, I could get around this by:
# converting doubles to integers with 3 significant figures – which is largely enough,
# then converting the “vector” to a variable length character string,
# the writing and reading of this character string and converting to a vector dynamically using an appropriate function (”strcurv_data”). Note that this function allows adjusting the curves within the limit of 16 inflection points (Bézier curve) for the flat curve, and 32 points for the diagonal, which should be enough. Whether this would not be enough, it should be possible to increase that number, though compatibility would be compromised.

====Some elements about curves====
The implementation of curves has been a complex task, particularly since:
# each curve needs its own reset function – resize() at each iteration,
# which implies oddities regarding their description, for example the diagonal curve gets initialised with several points, despite it looks being “empty”. This is mandatory for correct functioning, but this means that the curve is always open/active. Consequently, to avoid some unwanted loss of computation time in “preview” mode, the user has to activate the curve by clicking on the “curves” combobox. The same activation is necessary for L=f(H) and C=f(C) curves. While clicking enabling the “curves” (linear) would seem to be a better solution, it didn’t work despite many trials.
# during all the procedure, we need to set each "params" value to "clear" for curves, for each LUT, at each iteration and then through a "vector" to reassign the good, updated values to "curve params".

====Data storing and dynamic use====
Once data have been converted:
* they are stored in a text (mip) file,
* each one is referenced inside a 2-dimension dynamical table:
# dataspot[x][y] for numeric and boolean values and methods, where “x” is the representative index of the parameter (e.g. “9” is for “lightness”) and “y” represents the current RT-spot (control spot). Value “0” represents the current in-use value (the one stores in “params”).
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] for parameters of type “curve”. Currently there are only 8 parameters, used for local “Retinex”, “Color and light” (L=f(L), C=f(C), L=f(H), H=F(H)), “Vibrance” and “Exposure”, but it is easy to add more. “y” is used as above in 1.

The way data are stored and used fits well with improccoordinator.cc (current management / preview) and simpleprocess.cc (TIFF / JPG output) files, but not so with dcrop.cc and the partial display of the image (RawTherapee’s pipeline).

In this case (zoom / preview) another solution had to be found in order to synchronise the modifications in real time. I made use of LUTs, so that to each entry referenced in the table described above a LUTi(z) is associated, with z=500 possible entries (500 corresponds to the current maximum number of RT-spots, but this limit can be decreased or increased). The LUTi “z” corresponds to the dataspot “y”. A 25,000 entries LUTi (arbitrary number) is used for “retistr”, “llstr”, “lhstr”, “ccstr”, “hhstr”, “skinstr”, “pthstr”, “exstr” for storing each “vector” curve value in memory (up to 69 values stored as integers).

During data processing, exchanges occur between: params, dynamic tables and LUTi. The values used by dcrop.cc are dynamically linked to dynamical tables by parent→.

====Exchange processes and dynamic data storing====
# reading of the “mip” file to check the version number and guide the updates
# creating the “mip” file if it doesn’t exist
# storing the data in LUTi and dynamic tables from the values stored in “params” (index 0 values)
# first interactive update with the GUI through a transfer function between “rtengine” and locallab.cc (aloListener → localretChanged). This is one of the 3 functions required for the process to work correctly
# reading of the “mip” file and data storing in dynamic tables (index values ==> y) according to the number of RT-spots
# creating a loop – according to the number of RT-spots – which updates LUTi (required by “dcrop”) and “params” values from values stored in the dynamic tables
# call to the “Lab_local” function which contains the algorithms controlling each RT-spot (luminance, sharpness, retinex, denoise, …)
# second interactive update with the GUI through another transfer function between “rtengine” and “locallab.cc”
# treatment of the current RT-spot by using the index (0) values from the dynamic tables. These values are attributed to 1) “params”, 2) LUTi and 3) current index values
# call to the “Lab_local” function for the current RT-spots
# saving to the “mip” file.

Note that if the user modifies the curve (amplitude, number of inflection points) a third interactive update is made in order to conform all of the data according to events.

====A few unavoidable “fantasies”====
Of course everything looks simple, the process works if, and only if, all the data are dynamically updated. I’ve tried a lot, went groping, and finally found a working solution… but an uncanny one. There’s probably a more “informatically” correct way to do it, but at this point I’ve done as explained above and hereafter.

The 3 exchanges between “rtengine” and the GUI occur with 3 parameters which actually do nothing in the program except doing the update process:
# “anbspot” which takes values of 0 or 1
# “cTgainshaperab” (curve) which takes any value bewteen 0.70 and 0.90
# “retrab” which varies around 500.
I have added 3 more parameters (in the form of sliders) – hueref, chromaref and lumaref – hidden from the user but which are used to update the system in real time, to correctly take into account the reference “spot” values. Allowing those 3 parameters to vary brings stability and allows real time updates. Increasing the number of those “fantasy” parameters should not be necessary. These extra parameters are hidden to the user, and are only visible in the history.

In addition, I had to add some empirical time delays, giving time to time… Time delay is used for example when the user modifies the curve (amplitude, number of inflection points).

==Specificity of the local mode (as compared to “Lab adjustments”)==
Hereafter is some useful information for the user, often specific to the local mode.

===Color and Light===
* The algorithms used for luminance and contrast in local mode differ from the ones used in “Lab adjustments”, which may lead to differences in rendering.
* The luminance algorithm is made such that below -90 and down to -100 for “Lightness”, it is possible to increase the image's “darkness”, almost to the point of getting a luminance value close to 0. To accentuate this effect, “Chrominance” can be decreased and “Scope” increased.
* The inverse mode can be used for creating graduated frames. If “Ligthness” is set to -100 and "Chrominance" is reduced, the “frame border” will be black.
* For the “Lightness” and “Contrast” sliders, the user can choose among 2 algorithms: the first one (default) is close to that in “Lab adjustments” while the second one, activated through “Lightness - Contrast ‘Super’” is close to the algorithm used for the L=f(L) “Super” curve.
* Do not hesitate, when needed, to activate “Enhanced” or “Enhanced + chroma denoise” in the “Global Quality:” combobox.

====Curves====
* An L=f(L) or C=f(C) curves allow controlling the luminance and chrominance for each RT-spot as a function of luminance or chrominance.
* An L=f(H) curve allows controlling the luminance for each RT-spot as a function of tint.
* An H=f(H) curve allows controlling the tint for each RT-spot as a function of tint.
The curves are activated by selecting one of the two algorithms from the “Curves types” combobox:
* “Normal”: the curves – particularly the one that is the most difficult to manage, L=f(L) – use an algorithm close to the one used with the sliders (Normal mode),
* “Super”: using a new algorithm, which I think performs very well (it even surprised me the first time I used it).

Caution: when the RT-spot resides in an area which is neutral, grey or very uniform, the artefacts introduced by the new algorithm (“Super” algorithm for the curve or the slider) may be impossible to get rid of. Use one of the 2 older algorithms to avoid that.

===Exposure===
The “Exposure” module may look like the the one in global RGB mode, but:
* it works entirely in L*a*b* mode, hence the differences in rendering;
* there’s no “Lightness”, “Chroma” or “Contrast” slider, whose functions are already fulfilled in the “Color and Light” module;
* there’s only one “Contrast” curve, similar to the L=f(L) firm “Color and Light”. Of course its effect is different from “Tone curve” which works in RGB mode. If needed, two L=f(L) curves can be activated, one under “Color and Light” and the other under “Exposure”.

===Vibrance===
This module is similar to the main one (from RawTherapee's "Exposure" tab).

===Blur & Noise===
“Blur” is activated only when “Radius” =< 2.
By significantly lowering the default value of “Scope” and possibly checking “Blur luminance only”, it is possible to get a different amount of blur for the different tints.
Since October 2017, 3 methods are proposed:
* “Normal”: the shape detection algorithm has been improved, it is now closer to shape detection algorithm proposed in the other modules;
* “Inverse”: a simplified algorithm, which doesn’t make use of “Scope”. The inversion is coarse and doesn’t allow a fine separation between the affected and unaffected areas;
* “Symmetric”: this new algorithm uses the same processes as “Normal”, and adjusting “Scope” the user can target the process with more precision.
Caution:
* Using the “Inverse” mode will blur large portions of the image, which can not be corrected later on.
* The action of “Scope” may sometimes appear puzzling: for instance, in a portrait, the eyes (which of course differ from the skin) may be blurred if the value of “Scope” is too low.

===Tone Mapping===
Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Retinex===
Compared to the standard “Retinex” module, the local “Retinex module has simplified controls, and is applied at the end of the pipeline instead of the beginning. Since “mip” version 10002, the “Transmission gain” is specific to each RT-spot.

===Sharpening===
Only the “RL Deconvolution” algorithm is provided here.

===Contrast by detail levels===
Compared to the main RGB mode module, this one has:
* 5 levels instead of 6,
* no slider for “skin tone” protection (not needed since the algorithm works locally on the RT-spot area),
* an additional “Chroma” slider.

Caution when uniformly coloured areas (sky, grey/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artefacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artefacts – Improve algorithm”.

===Denoise===
Compared to the main RGB mode module, this one has:
* only the wavelet tool working (no Fourier function, nor medians),
* less sliders and curves,
* the possibility to work differentially on fine or coarse noise for both luminance and chrominance noise.

==A specific use case : reduction of image defects (dirty sensor, red eyes, …)==
“Locallab” had not been thought with the idea of correcting small image defects. However, some visible, “photographically disturbing” defects may actually be tamed or even removed. Of course, this is not incompatible with other more specialised modules which could be introduced (or not) into “Locallab”… At least 3 existing modules can serve this purpose, alone or in combination, by adapting their use:
* “Color and Light” for spot-like defects;
* “Contrast by detail levels” for spread out defects;
* “Blur and Noise” as an optional complement (caution, this is a destructive action, use moderately).

These modules can be used either on the main image (raw, TIFF, …) or on a flat-field image.

===Using the “Color and Light” module===
* Activate “Color and Light”
* A red eye removal tool equivalent can be obtained by framing closely around the eye – central circle zone centered on the eye’s red, spot handles close to the eye – low “Scope” value, then lowering “Lightness” and “Chrominance” to -100.
* The same idea allows reducing the “IR spot” kind of defect by framing closely around the defect – central circle zone centred on the defect, spot handles close to the defect area – then lowering “Chrominance” to taste, and if needed lowering the “scope” value.
* In some (simple) situations, a “dirty sensor” defect can be reduced, in particular in the case of “sensor grease”. It can be seen as stains or spots on a uniform background. To attenuate this, choose a tight framing of around the defect – central circle on the centre of the defect (adapt the size of the RT-spot), drag the handles so that they are not too close to the border of the defect (this will make the transition less noticeable). Then: a) decrease “Transition” towards lower values; b) check “Lightness - Contrast “Super”; c) adjust “Lightness” and “Chrominance” as needed to bring the defect area closer to the unaffected area; d) if needed adjust slightly “Scope” to achieve the best result.

===Using the “Contrast by detail levels” module===
When the sensor is dirty (grease), and when the affected area is large or if there are multiple small defects, “Contrast by detail levels” may be used, working as a sort of “wavelet” tool on luminance, and if needed on chrominance. In such cases: a) place the RT-spot on one of the stronger defects (adjust the size as needed); b) drag the handles so as to cover most of the affected area; c) set “Transition” to higher value; d) activate “Contrast by detail levels” and decrease the contrast of levels 3 and 4 (or lower); you can adjust the “Chroma” slider if needed.

==Settings in the Preferences dialog==
Below is a list of the settings (already mentioned above in several places) which can be accessed from the “Preferences” dialog:
* In “Preferences” > “General” tab > “Local adjustments”, by checking the “Show spot delimiters” checkbox, an approximate zone delimitation is drawn which helps viewing the area affected by the RT-spot and its settings.
* If your images generally have low noise, you can set the default for “Global quality” to “Standard”, and get a significant speedup in processing time. This setting is found under “Preferences” > “Performance & Quality” tab > “Local adjustments”. The three choices for quality are selected from the “Local adjustments Quality method” combobox. Default is “Enhanced + chroma denoise”.
* Regarding “mip” files:
** the choice for “mip” files destination folder is set from “Preferences” > “Image processing” tab > “Mip Profiles”;
** in order to clean the generated “mip” profiles, go to “Preferences” > “File Browser” tab > “Cache Options” and click on the “Clear mip” button and/or “Clear pp3” – this is valid in the case where you chose to store “mip” files in the cache, otherwise if you chose to let RT write the “mip” files next to the input file, you will have to delete them manually. Note that the presence of older versions of “mip” and “pp3” files may lead to instability or even crashes of RawTherapee.

==Processing time and memory use==
At image export time (output to JPG, TIFF…), for the “normal” mode, the algorithms compute the data only for in the RT-spot delimited areas, not for the whole image. Thus, processing time and memory stay reasonable. Note that of course, this will depend on the number of RT-spots, their size, and the type(s) of treatment done in these RT-spots.

Excluding “Denoise” and “Sharpen”, processing time is in the order of a few tenths of a second per RT-spot, and memory use of a few hundred MB.

Two settings have a strong influence on resource use:
• “Denoise” which adds around 1 sec. of processing time, and 1 MB of memory use;
• “Global quality: Enhanced + chroma denoise” which adds around 0.5 sec. And 0.6 MB.
These figures depend on the size of the RT-spot.

==Future evolution==
Besides usual tweaking, bug corrections, improvements (settings, user interface)… it would be desirable to improve the GUI with regards to the creation/selection/modification of individual RT-spots.

From a programming point of view, it should be possible to improve code readability and maintainability, and to integrate all the “mip” files code parts (as done in “rgbproc.cc”) which currently are linearly integrated to void procedures in “improccoordinator.cc”, “dcrop.cc” and “simpleprocess.cc”.

Local Adjustments/fr

2017-10-26T17:13:04Z

Sguyader:

== Quel type de contrôle local? ==
Lorsqu'on observe les différents logiciels du marché on trouve plusieurs types de contrôles locaux
# les contrôles de type "lasso", associés à des calques et masques de fusion, comme par exemple dans Photoshop (c). Ce type de contrôle est majoritaire dans les logiciels (Photoshop, Gimp, Darktable...) et l'avis des utilisateurs est obligatoirement orienté vers ceux-ci au détriment du point 3) ci-dessous moins connu!
# les dispositifs de suppression de "yeux rouges", ou de "spot" liés aux imperfections du capteur
# les contrôles de type U-points, utilisés jusque récemment dans Nikon Capture NX2 (c), ou comme complément à d'autres logiciels comme Nik Software (c). Pour qui a tâté de ces dispositifs (rares maintenant) il n'est pas question de revenir aux calques et masques de fusion! Ce type de contrôle nécessite un apprentissage différent de ceux de type lasso-calque et un désapprentissage cognitif de ceux-ci. De mon point de vue, ils sont globalement plus performants.

Dans la version présente de Rawtherapee, l’algorithme développé est proche dans le principe du point 3) ci-dessus, les U-points. Bien sûr, le code de Nik Software est inconnu, mais il y a quelques années j'ai été séduit par la facilité d'utilisation et les performances des U-points, et j'ai entrepris de développer un produit qui ne ferait pas appel, ni au lasso, ni aux calques, ni aux masques de fusion.

Bien sûr rien n'interdit d'avoir les 3 possibilités (Lasso-calque, retouches spot, U-points) !

La version actuelle est très certainement perfectible, au niveau de l'interface graphique - GUI - notamment:
* pour le suivi et repérage des RT-spot (spot de contrôle) à l'écran
* pour les réglages des différents curseurs qui gagneraient à être intégrés au spot de contrôle, comme le fait Nik Software (c).
Cependant, ces deux points n'affectent pas ni l’utilisation courante, ni la portabilité.

J'ai ajouté, pour faciliter l'utilisation et éviter les menus trop longs en mode écran, une interface GUI similaire à celle de Wavelet, avec des "expanders".
Vous avez ainsi la possibilité pour chaque famille d'action (color and light, Blur, Retinex, etc.):
# faire apparaître ou non le détail des commandes : curseurs, méthodes, courbes,..
# activer ou non l'ensemble des fonctions de la famille d'action.
Attention, le choix - 2 - active ou annule l'ensemble des RT-spot ( spot de contrôle); il est théoriquement possible d'associer cette possibilité à chaque RT-spot, mais quel intérêt ?

===Contrôles locaux Lab et RGB===
* Les premiers algorithmes sont écrits en mode L*a*b* avec les contrôles suivants : "Color and Light", "Blurr addnoise", "Retinex", "Tone mapping", "Sharpen", "CBDL", "Denoise"..Deux contrôles suivants ont été ajoutés : "Exposure", "Vibrance"...
* Voir ci-dessous le principe des algorithmes, mais un des points clefs à retenir pour la détection de forme et la prévention des artefacts est que le mode Lab préserve la teinte "hue", qui joue un rôle déterminant.
* L'idée d'un module "RGB" vient évidemment à l'esprit, avec ''a minima'' un module :
** White Balance : qui permettrait une retouche de la balance des blancs par exemple pour "réchauffer les parties à l'ombre", ou permettre le mélange de deux éclairages par exemple "lumière du jour" et "Tungsten". Ce module doit être placé juste après "demosaic".

====White balance auto====
Le module "white balance" (branche "autowblocal") vise deux objectifs :
* permettre la retouche locale de la Balance des blancs (évident!)
* tester de nouveaux algorithmes de Balance des blancs automatique :
** en usage général (full image), afin d'obtenir de meilleurs résultats que l'algorithme actuel. Bien sûr on va me rétorquer qu'il faudrait une branche spécifique "White balance", mais j'essaie de faire d'une pierre deux coups.

Pour mémoire en 2012 et 2013, il m'avait été demandé, de mettre en place la balance des blancs itérative "Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]". A l'époque avec un autre développeur nous avons passé beaucoup de temps pour un résultat assez peu satisfaisant... d'où l'abandon. Depuis, fort de cette expérience j'ai repris le travail mais à l'envers ! Maintenant - si je ne me suis pas trompé - l'algorithme fonctionne.
J'ai profité de cette possibilité (actuellement uniquement pour des images RAW), pour rechercher dans la littérature universitaire, d'autres algorithmes auto. J'ai trouvé et mis au point deux nouveaux algorithmes :
* "auto edge[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]" : l'idée ici est de créer un masque d’accentuation pour permettre de renforcer les parties de l'images où il y a des détails par rapport aux aplats.
* "auto standard deviation[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]" : l'image (ou la partie d'image pour le mode local) est divisée en 12 zones. Pour chacune on calcule moyenne et écarts type, puis on assemble le résultat.
Un troisième algorithme semble prometteur "Color by correlation[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf]", mais je me heurte à quelques difficultés...Après beaucoup de tests en tous genres, les résultats sont erratiques...

J'ai ajouté la notion de gamma:
* les mêmes principes concernant la répartition de la luminance - gamma sRGB - utilisé dans le code de Rawtherapee

A titre de rappel, la balance des blancs automatique est un problème mathématique totalement indéterminé. Il est possible d'avoir des algorithmes plus ou moins performants (et aussi plus ou moins rapides ou lents), mais en aucun cas le résultat sera parfait ! Pourquoi est-ce impossible ? Si on se réfère aux principes de la gestion des couleurs [[http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]], il est nécessaire de connaitre à la fois l'objet coloré, l'illuminant et l'observateur. Il y a au moins 2 familles d'inconnues. De plus l'environnement de prise de vue n'est pas connu et influe sur la perception (CIECAM) ainsi que l'environnement de traitement et de visualisation. Donc, mission quasi impossible !

L'objectif du module '''"White balance" est de tester les algorithmes''', au total il y en a 7 et le double (au moins) si on prend en compte le "gamma sRGB". En effet pour contourner les obstacles d'il y a 5 ans, j'ai utilisé au lieu de l'image avant demosaic, l'image juste après demosaic, sur laquelle on peut ou non appliquer le "gamma sRGB", pour se retrouver dans les mêmes conditions qu'en usage normal (sinon bien sûr sans "White Balance" et sans profil "ICC ou DCP").

L'idéal est de tester sur de nombreuses images les divers algorithmes "auto" avec un objectif : quel(s) algorithme(s) retenir et implanter en mode "full image" (peut être 1 ou 2 en plus de l'actuel qu'il faut garder pour compatibilité).

====White balance contrôle local====
Le contrôle local est actuellement limité à 1 spot, mais pas de difficultés si les utilisateurs le souhaitent d’accroitre...En attendant les évolutions de "locallab".

Bien sûr il me sera dit "cela ne fonctionne pas", ou "on ne se raccorde pas avec le 'preview'". Cela fonctionne ! Et il est plus qu'évident que atteindre le preview est par définition quasi impossible... (différences ombres , soleil, illuminants différents, etc.) en dehors de la pertinence de l'algorithme.

Vous disposez de 3 sliders : temperature, tint, blue/red equalizer

== Quels défis à résoudre? ==
Plusieurs problèmes généraux sont à résoudre afin d'obtenir un fonctionnement fluide :
* permettre un nombre quasi illimité de RT-spot (spot de contrôles);
* adapter les algorithmes locaux aux problèmes d'échelle, car beaucoup d'algorithmes tiennent compte de la taille de l'image - donc de la zone traitée. Cet aspect est fondamental, notamment avec les courbes qui agissent sur toute l'image;
* minimiser l'occupation mémoire et les temps de traitement en sortie JPG et TIF;
* permettre des mises à jour logicielles faciles en cas d’évolution des algorithmes ou d'évolution du nombre de méthodes ;
* optimiser les écarts entre "preview" et sortie JPG / TIF;
* etc.

Pour chaque RT-spot :
* permettre selon le cas, une action dans la zone sélectionnée ou à l'extérieur de la zone sélectionnée;
* permettre selon le cas une détection de forme pour délimiter l'action;
* assurer une transition entre le cœur de la zone traitée et le reste de l'image;
* etc.

Actuellement, les RT-spot (spot de contrôles) sont opérationnels, pour le mode Lab, et pour les méthodes suivantes:
# Color and light : lightness, chrominance, contraste en mode normal avec quatre courbes L=f(L), L=f(H), C=f(C), H=f(H) et inverse ;
# Exposure : en mode normal
# Vibrance : en mode normal
# Blur and Noise : en mode normal et inverse;
# Retinex : en mode normal et inverse, maintenant avec gestion de la courbe "transmission gain";
# Sharpening : en mode normal et inverse;
# Contrast By Detail Levels : en mode normal;
# Denoise : en mode normal.

== Principes généraux ==
===L'Objet RT-spot===
Comme je l'ai évoqué, le système utilisé est proche de celui mis au point par Nik Software, avec de grandes différences :
* chaque RT-spot, peut être considéré comme un objet qui comporte plusieurs champ - à ce jour environ 70, constitués de curseurs, courbes;
* chaque champ, regroupé en paquets peut être ou non activé, et peut avoir des valeurs variables selon sa nature ;
* les paquets sont des ensembles cohérents pour l'utilisateur : color & light, exposure, contrast, vibrance, blurr, retinex, sharpening, tone-mapping, contrast by detail level, denoise ;
* le nombre de "RT-spots objets" peut varier de 2 à 500 ;
* les données des "RT-spots objets" sont stockées dans un fichier texte "mip";
* les "RT-spots objets" sont gérés - création, modification, suivi - dans une boucle "for";
* il n'y a pas de duplication de code.

===Le découpage en quatre zones - l’aperçu de la zone RT-spot===
Lorsque l’utilisateur sélectionne un RT-spot (spot de contrôle),l’image à l’écran montre:
* un centre, constitué d'un cercle dont on peut faire varier : a) le diamètre, b) la position avec la souris ou les curseurs;
* quatre lignes horizontales ou verticales dont on peut faire varier les positions avec la souris ou les curseurs.
* si vous sélectionnez en "Preferences" / "General" / "Local adjustements", en cochant la case "Show spot delimiters", vous obtiendrez une approximation de la zone concernée par le spot et ses réglages. Attention, je ne suis pas arrivé à un travail propre avec la fonction "arc / ellipse / scale" de la bibliothèque graphique Cairo; j'ai donc opté pour chaque "quart" à une pseudo ellipse obtenue par 3 courbes de Bézier se raccordant entre elles. Dans la majorité des cas l'approximation est satisfaisante...Pour permettre une sélection plus facile j'ai été amené à accroître la taille des 4 lignes horizontales et verticales qui sélectionnent la taille du spot (les courbes de Bézier sont inactives!).

On aboutit à 4 zones, dont on ne peut faire varier l'orientation (angle d'inclinaison obligatoirement à zéro).
Ces 4 zones ont chacun de leurs sommets reliés par une ellipse imaginaire.

Il est possible de pointer les limites des zones en dehors de la zone "preview".

A terme, il doit être possible, même si l'utilité me semble discutable du fait de l'algorithme de détection de forme, de remplacer l'ellipse, par une courbe tracée à l'aide de la souris, à condition que la transformée homothétique de la courbe n'ait pas d'intersection avec la courbe originale. Cette "amélioration" intellectuellement satisfaisante, ne devrait être que d'un apport négligeable - dans le cas des U-points. Néanmoins il sera toujours possible de faire coexister les actuels U-points avec des contrôles par"lasso" de type Photoshop (c).

===Les références teinte, chroma, luminance et le principe de l'algorithme en mode "normal"===
Afin de mettre en œuvre un algorithme performant de détection de forme :
* la zone du cercle central, sert de référence. En fonction du diamètre choisi par l'utilisateur, le système calcule, la moyenne de la teinte (hue), de la chroma, et de la luminance.
* le choix du diamètre de la zone centrale dépend de l'usage. Par exemple pour un feuillage, l'utilisateur aura intérêt à choisir une valeur faible afin de ne sélectionner que le vert du feuillage; à l'inverse pour la peau l'utilisateur aura intérêt à accroître le diamètre afin d'éviter les prises en compte de données parasites (bruit, cils, etc.).
* pour chaque quart, et en fonction du curseur "scope", le système prend en compte :
# en premier lieu de l'écart de teinte entre la zone centrale et le pixel courant ;
# puis, un algorithme complexe, s'appuyant sur la notion de deltaE (différence perçue entre 2 couleurs prenant en compte, la teinte, la chroma et la luminance), atténue l'action en fonction de l'écart entre la zone centrale et le pixel courant.
# la modification d'action utilise soit une loi linéaire, soit une loi parabolique selon le cas.

Ceci va permettre de différencier l'action selon les critères énoncés ci-dessus, comme par exemple, si le cercle central se trouve dans un feuillage, de limiter l'action à l'ensemble du feuillage sans toucher à l'arrière plan (ce qui est impossible avec un lasso). De plus si un autre feuillage se situe dans la zone couverte, celui-ci sera également concernés par la modification.

* l'action sur le curseur transition va permettre de faire varier l'action : si le curseur est réglé sur 50, la moitié (linéaire) de la zone concernée verra une application à 100% de l'effet, puis une transition agira régressivement jusqu'aux limites de la zone.
* si on accroît la valeur de "scope", progressivement l’ensemble de la zone sélectionnée est prise en compte quelque soit la couleur, la chroma et la luminance.
* si on réduit la valeur de "scope",l'action se limitera aux pixels très proches (en termes de deltaE) de la zone de référence.

L'algorithme de détection de forme est opérationnel en mode "normal" sauf pour certains modules (denoise) - son implantation en mode inverse n'a pas de sens.

Cet algorithme va avoir ses performances accrues, si l'utilisateur choisit : "Quality Enhanced" ou "Qualty enhanced + chroma denoise". Ce second choix apporte une très légère réduction du bruit de chroma afin de supprimer les artefacts possibles liés à l'utilisation de "enhanced" (à noter dans le cas + chroma denoise, un accroissement des besoins en mémoire et du temps de traitement).

L'algorithme utilise toutes ses capacités, si les valeurs de "scope" sont inférieures à 20.

===Pourquoi pas d'autres algorithmes? ===
Remarque : il doit être possible de programmer d'autres algorithmes de détection de forme que celui ci-dessus fondé sur les différences de deltaE.

* Par exemple les algorithmes de détection de bords (edge) tels que "Canny" ou "Sobel";
* Ou encore le principe de décomposition en ondelettes.
Mais dans ces 2 cas tout reste à faire !

===Le fonctionnement en mode inverse===
Lorsqu'il est proposé, le fonctionnement en mode inverse est extrêmement simplifié, seul le curseur "transition" permet de moduler l'action.

A partir de fin octobre 2017, j'ai mis au point une autre manière de concevoir le mode "inverse". Cette manière est limitée à l'outil "Blur and Noise" (voir ce paragraphe)

===Nombre maximum de RT-spot (spot de contrôle)===
Par défaut le nombre de RT-spot est de 8.
Vous pouvez choisir n'importe quelle valeur entre 2 et 499. Pour cela il suffit de changer la variable Nspot dans le fichier "option"; par exemple Nspot=12.
Il est indispensable de relancer Rawtherapee après cette modification.

===L'algorithme 'super'===
La clef du "succès" (si on peut utiliser ce terme) tient à l'algorithme présent depuis fin janvier 2017. je vais l'expliciter de manière simplifiée :
# pour la partie des données concernées par la zone sélectionnée, on applique une fonction courbe "traditionnelle" ou un curseur classique, ou la fonction de transfert normale (Retinex, Tone mapping, CBDL, Vibrance, ...);
# puis on réalise une conversion de la LUT ou de la fonction de transfert , en un équivalent "slider", en séparant les valeurs positives et négatives, afin d'avoir une représentation de la fonction comme une multitude de "sliders" (autant qu'il y a de pixels concernés) dans l'intervalle -100, 0, +100
# on passe ces données à la fonction de reconnaissance de forme - celle des 4 zones. On détecte pour chaque pixel l'écart de teinte, chroma et luma par rapport à la référence. On établit des équations de variations linéaire selon le cas de la luminance (L = f(L)) ou de la chroma (C=f(C) ou des fonctions de transfert).
# puis on applique diverses corrections pour tenir compte de l'environnement, ciel, peau,...
# enfin, on applique une correction (avec seuil et itérations)pour ne pas corriger (ou le faire faiblement selon le choix de l'utilisateur), les tons gris ou neutres qui sont dans la même teinte que la référence (mais avec une chroma faible).
# ces paramètres sont ensuite pondérés en fonction, de la forme (ellipse) et de la zone de transition.
# bien sûr les réglages des paramètres qualité "Global quality", ont leur importance, notamment dans les images légèrement bruitées - le bruit chromatique est considéré par l'algorithme comme de la même couleur que le spot. Il faut donc avoir la possibilité de le supprimer, d'où la sélection "enhanced + chroma denoise" (il est possible que ce réglage soit insuffisant, agir en conséquence sur "Denoise local" si nécessaire).

Cet algorithme nouveau ('super') semble généralement fonctionner, mais dans le cas où le spot est sur une zone gris - neutre ou l'action sur des zones à faible gradient, l'algorithme peut être pris en défaut, dans ce cas utiliser l'ancien (quand c'est possible !!), car pour Retinex, Tone Mapping, CBDL je n'ai pas offert ce choix par souci de simplification)

===Réduction des artefacts et l'algorithme "Global quality"===
Par défaut, "Global quality" est à "Enhanced + chroma denoise". Certes cela augmente les temps de traitements, mais globalement c'est préférable. Vous pouvez, si vous trouvez les temps de rafraichissement long, choisir "enhance" ou "standard" et examiner l'image...
* 2 curseurs permettent de réduire les artefacts et améliorer le rendu de l'algorithme. Ils agissent en fonction de la chroma, dans les tons gris neutres. Pour désactiver complètement l'effet il suffit de mettre "iterations = 0". Ces curseurs permettent, d'une part de réduire les artefacts et, d'autre part d'agir sur le rendu de l'image. L'action est possible pour "Color Light", "Exposure", "Retinex", "Vibrance", "Tone Mapping" et "Contrast by details levels".
* lorsque les images sont bruitées, même légèrement (beaucoup d’images sont bruitées sans que cela soit gênant par exemple les ciels, les nuages,...), les algorithmes sont "trompés", ne pas hésiter à laisser activé "Global quality = enhanced + chroma denoise" et (quelquefois) activer "denoise local" et agir très légèrement sur les curseurs (y compris luminance).
* dans certaines circonstances, par exemple avec Tone-mapping, le système de réduction d'artefacts peut générer des artefacts. Dans ce cas, mettre le slider "iterations" à 0.

Vous pouvez choisir la valeur par défaut de "Global Quality", par exemple si vos images sont très peu bruitées, et ainsi réduire notablement les temps de traitement.
Pour cela, aller dans "Preferences", "Performance and Quality", "Local adjustements" et choisir entre Les 3 propositions. C'est ce choix qui sera proposé par défaut à l'utilisateur pour chaque nouveau "Spot", bien sûr il est possible ensuite de modifier ce choix, en sélectionnant la combo-box "Global Quality"

===Avoid color shift===
Cette case à cocher vise deux objectifs :
* mettre les couleurs dans le gamut de l'espace de travail courant (working profile) en utilisant une colorimétrie relative ;
* ajuster les couleurs à l'aide d'une correction "Munsell" - notamment les rouges-orangés et les bleus-pourpres, lorsque la saturation dans le domaine L*a*b* a évolué notablement.

===Les fichiers *.mip - les principes de l’algorithme multipoints===
Afin de permettre le fonctionnement - enregistrement des valeurs pour chaque spot de contrôle - un fichier de type texte, assez proche des fichiers pp3 est enregistré à deux endroits possibles :
* à côté du fichier à traiter. Si par exemple vous traitez le fichier ASC4509.NEF, un fichier ASC4509.NEF.mip sera enregistré dans le même dossier. Si vous choisissez cet emplacement, vous pourrez ouvrir plusieurs sessions pour un même fichier image, si celui-ci est présent dans des dossiers différents. Par contre, le nom des dossiers et du "path" doit obligatoirement n'avoir que des caractères ASCII...sinon plantage.
* dans le dossier "mip", à l'intérieur du dossier "cache" (via un "hash number MD5" qui identifie le fichier). Valeur par défaut. Si vous choisissez cet emplacement, si le fichier image est présent dans plusieurs dossiers, il y aura plusieurs fichiers mip. Cette option permet d'utiliser des dossiers et "path" avec des caractères NON ASCII.
* le choix entre ces emplacements est possible à partir de : Preferences / Image processing / Mip Profiles

Ce fichier mip contient les données qui seront ensuite passées au programme, via d'une part les processus de type "procparams" et d'autre part des LUT qui permettent le fonctionnement en mode zoom.
Lors de la mise à jour d'une nouvelle version, il pourra dans certains cas être demandé d'effacer les fichiers *.mip (voire le cache) afin d'éviter un crash. Pour cela vous pouvez aller dans "Preferences" / "Files browser", puis "Clear mip" et / ou "clear pp3" - si bien sûr vous avez positionné "mip" et "pp3" dans le cache, sinon il faudra exécuter cette opération manuellement dans le dossier courant. La présence d'anciennes versions de fichiers "mip" ou de "pp3" peut amener de l'instabilité voire un crash du système.

====Architecture du système====
Lorsque je me suis "aventuré" vers la possibilité d'un système multipoints sans calques, sans masques,...il était obligatoire de refuser de dupliquer le code. Comment envisager par exemple pour 10 spot de contrôles, 10 codes GUI, et autant de code dans Rtengine.
Après réflexion, l’idée est venue d'avoir un fichier mis à jour en temps réel - c'est à dire qui suit les modifications faites par l'utilisateur - de l’historique des actions / modifications.

Bien sûr, les variables utilisées par Rawtherapee, au niveau de l'interface GUI, et par la suite dans l'ensemble du code via "params", sont de type divers:
* numériques : entier, float, double,...
* booléenne
* choix (menus pour "méthodes") de type string
* courbes via des "vectors" de type double a dimension dynamique.
* ...

====Conversion des données====
La première étape - afin de simplifier ensuite la gestion des données - est de convertir toutes ces données en entiers. Dans quelques cas cela peut aboutir à une très légère perte de précision, qui de mon point de vue est tout à fait négligeable.
*Cette opération est très simple pour les valeurs numériques, même si elle peut aboutir dans certains cas (la teinte - Hue - s'exprime en radians dans l’intervalle -Pi + Pi) par une double transformation "float * 100 et / 100" pour garder la précision.
*Elle est logique pour les opérations booléennes et les méthodes.
*Par contre elle s'est avérée complexe pour les courbes. Les valeurs à stocker dans le fichier texte sont de type vector<double> soit un tableau dynamique de valeurs numériques. Probablement il doit y avoir un moyen "plus simple" en utilisant les fonctions qui sont utilisées dans "Procparams", mais je ne suis pas arrivé à les mettre en œuvre. J'ai contourné l'obstacle en :
#transformant les valeurs doubles en entier avec 3 chiffres significatifs - ce qui est largement suffisant
#puis en convertissant le "vector" en une chaine de caractère de longueur variable
#la lecture et l'écriture de cette chaine et sa conversion en "vector" se faisant dynamiquement par une fonction appropriée ("strcurv_data"). A noter que cette fonction permet de modifier des courbes jusqu'à une limite de 16 points d'inflexion (Courbe de Beziers) pour la courbe plate, et 32 pour la diagonale, ce qui devrait être suffisant. Si c'était insuffisant (??) il est possible (via une perte de compatibilité) d'accroître ce nombre.

====Quelques éléments sur les courbes====
L'implémentation des courbes a été complexe, au delà de ce qui est écrit ci-dessus, notamment :
# chaque courbe doit obligatoirement avoir une fonction reset - resize() à chaque itération;
# ce qui implique des curiosités au niveau de leur description, par exemple la courbe diagonale est initialisée avec plusieurs points, alors qu'elle a l'air "vide". C'est indispensable au bon fonctionnement. Mais ceci a pour conséquence que cette courbe est toujours ouverte / active. Donc cela implique si on veut éviter des consommations de temps en mode "preview" que l'utilisateur "active" la courbe en activant la combobox "curves". Cette même activation est aussi nécessaire pour les courbes L=f(H) et C=f(C). Bien sûr, on se serait tenté de penser qu'il suffit d'activer le mode "enabled" de la fonction "courbes" (linéaire), mais après de nombreux essais cette démarche est infructueuse!
# tout au long des procédures, il est obligatoire de mettre "clear" chaque valeur de "params" pour les courbes, chaque LUT, pour chaque itération et ensuite via "vector" de réattribuer les bonnes valeurs courantes à "params courbe".

====Stockage et utilisation dynamique des données====
Une fois les données converties :
* elles sont stockées dans un fichier texte
* chacune est référencée dans un tableau dynamique à deux dimensions :
# dataspot[x][y], pour les valeurs numériques, booléenne et les méthodes, où 'x' représente l'indice représentatif de la variable, par exemple '9' correspond à 'Lightness', et 'y' représente le RT-spot (spot de contrôle) courant. La valeur '0' représente la valeur courante en cours d'utilisation (celle stockée dans 'params").
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] pour les variables de type "curve" (aujourd'hui il n'y a que 8 variables celle utilisée dans "Retinex" local, et celles dans "Color and light" (L=f(L), C=f(C), L=f(H), H=F(H))et "vibrance" et "exposure", mais il est assez facile d'en ajouter), avec 'y' comme ci-dessus.

Ce stockage et utilisation - nous reviendrons plus loin sur l'algorithme lecture / écriture dynamique - convient aisément pour le fichier Improccoordinator.cc (support de la gestion courante - Preview) et Simpleprocess.cc (sortie TIF / JPG), mais ne peut convenir, pour Dcrop.cc et la vision partielle de l'image (les fameux pipeline de Rawtherapee).

Pour ce cas (zoom - Preview) il a fallu imaginer autre chose, qui assure en temps réel la synchronisation des modifications. J'ai utilisé des LUT, dans le cas actuel, à chaque donnée référencée dans les tableaux ci dessus est associé une LUTi(z), avec z=500 entrées possibles (500 correspond à la limite informatique du nombre de RT-spot (spots de contrôles)...qu'on peut très facilement accroitre ou réduire). 'z' pour les LUTi correspond à 'y' pour dataspot. Une LUTi avec 25000 (arbitraire) entrées est utilisée pour "retistr", "llstr", "lhstr", "ccstr", "hhstr", "skinstr", "pthstr", "exstr" pour garder en mémoire (sous forme d'un entier) chaque valeur du 'Vector' de la courbe (il peut y en avoir jusque 69).

Au cours du traitement, des échanges sont réalisés entre: params, les tableaux dynamiques et les LUTi. Les valeurs utilisées par Dcrop.cc sont liées dynamiquement aux tableaux dynamiques par parent->.

====Processus d'échanges et stockage des données dynamiques ====
Sans entrer dans une description fastidieuse, je resterais aux principes généraux :
# lecture du fichier "mip" pour lire la version et orienter les mises à jour
# première écriture du fichier "mip" s'il n'existe pas
# stockage des données dans les LUTi et les tableaux dynamiques à partir des valeurs stockées dans "Params" (valeurs index 0)
# première mise à jour interactive avec le GUI via une fonction de transfert entre Rtengine et locallab.cc (aloListener->localretChanged). Cette fonction fait partie des 3 nécessaires pour obtenir un fonctionnement correct.
# lecture du fichier texte "mip" et stockage des données dans les tableaux dynamiques (valeurs index ==> y) - selon le nombre de RT-spot (spots de contrôle)
# Création d'une boucle - selon le nombre de RT-spot (spots de contrôle)- où à partir des valeurs stockées dans les variables tableaux dynamique, les LUTi (nécessaires à Dcrop) et les valeurs de Params sont actualisées.
# Appel de la fonction "Lab_local" qui contient les algorithmes de contrôle de chaque RT-spot (luminance, Sharp, retinex, denoise, etc.)
# deuxième mise à jour interactive avec le GUI via une autre fonction de transfert entre Rtengine et locallab.cc
# puis traitement du RT-spot (spot de contrôle) courant, en récupérant les valeurs index (0) des tableaux dynamiques. Ces valeurs sont attribuées à : 1) params, 2) LUTi, 3) valeurs index en cours
# Appel de la fonction "Lab_local" pour le RT-spot courant.
# sauvegarde du fichier "mip"

A noter que si l'utilisateur, modifie une courbe, amplitude ou nombre de points d'inflexion, une troisième mise à jour interactive est réalisée pour mettre en conformité l’ensemble des données en fonction des événements.

====Quelques fantaisies incontournables====
Bien sûr, tout à l'air simple, mais le système ne fonctionne que, si et seulement si, toutes les données sont dynamiquement mises à jour.

J'ai beaucoup essayé, tâtonné, pour aboutir à une solution qui fonctionne...certes curieuse; il y a probablement un moyen plus "informatique" de traiter cela, mais à ce stade, j'ai fait comme décrit ci-dessus et ci-après.

Les 3 échanges entre Rtengine et le GUI se font notamment avec 3 variables qui ne servent à rien dans le programme - sinon à mettre à jour:
# "anbspot" qui prend les valeurs forcées 0 ou 1
# "cTgainshaperab" (curve), dont je fais osciller une valeur entre 0.70 et 0.90
# "retrab" qui oscille autour de 500.

J'ai ajouté 3 variables (sous forme de "sliders") - hueref, chromaref, lumaref, totalement invisibles à l'utilisateur, mais qui servent à rafraichir le système en temps réel, pour permettre la bonne prise en compte des valeurs "spot" de référence.

Les appels aux changements de ces 3 variables amènent la stabilité au système et une mise à jour en temps réel.
Il ne devrait pas être nécessaire d’accroitre le nombre de ces variables "fantaisistes"

De plus j'ai été amené à empiriquement mettre des temporisations, pour laisser le temps au temps... C'est notamment le cas pour la modification de la courbe par l’utilisateur (amplitude, nombre de points d'inflexion).

Bien sûr ces variables sont invisibles pour l'utilisateur, sinon dans l'historique !

==Quelques particularités du mode local (par rapport à Lab adjustements)==

Voici quelques informations qui peuvent intéresser l'utilisateur. Ces informations sont souvent des particularités du mode local

===Color and Light===
*Les algorithmes utilisés pour la luminance et le contraste sont différents de ceux utilisés par "Lab adjustements", ce qui peut amener quelques différences de rendu.
*L'algorithme de luminance est réalisé de telle manière que en dessous de -90 et jusque -100 pour "lightness", il est possible d'accroître la "darkness" de l'image, pratiquement jusqu'à obtenir une valeur de luminance proche de 0. Si vous souhaitez accentuer cet effet, réduisez également la chominance et accroissez "scope".
*Le mode inverse, peut servir pour l'essentiel, à réaliser des cadres dégradés. Dans ce cas, si vous sélectionnez -100 pour "lightness", et réduisez la chrominance, la "bordure" sera noire.
* pour la luminance et le contraste (curseur), vous avez le choix entre 2 algorithmes : le premier (par défaut) est très proche de ce qui était présent jusque là, le second activé par "Lightness Contrast super" est proche de celui utilisé pour les courbes "super"
* ne pas hésiter selon le cas, à activer "Global quality" = enhanced et (défaut) enhanced + chroma denoise"
====Courbes====
*Une courbe L=f(L) et une C=f(C) permet de moduler la luminance ou la chrominance pour chaque RT-spot (spot de contrôle) en fonction de la luminance ou de la chrominance.
*Une courbe L=f(H) permet de moduler la luminance pour chaque RT-spot en fonction de la teinte.
*Une courbe H=f(H) permet de moduler la teinte pour chaque RT-spot en fonction de la teinte.
Pour les rendre actives, il est nécessaire d'activer la combobox "Curves type".
* deux choix sont offerts :
** a) Normal : les courbes - notamment la plus complexe à gérer L=f(L) utilise un algorithme proche de celui utilisé avec les curseurs (mode Normal);
** b) Super : utilise un nouvel algorithme que je pense très performant (le résultat m'a même surpris à la première utilisation).

Attention, lorsque le spot est située dans une zone grise, ou des zones assez uniformes, les artefacts avec le nouvel algorithme (L=F(L) super, et Lightness Contrast super) peuvent être impossible à supprimer, dans ce cas privilégier l’algorithme "normal".

===Exposure===
Ce module "ressemble" à celui en mode global RGB, mais :
* il fonctionne entièrement en mode L*a*b*, d'où des différences de rendu;
* il n'a pas les curseurs "lightness, chroma et contraste" dont les fonctions sont déjà présentes dans "Color and Light"
* il y a une seule courbe "contraste", similaire à celle de L=F(L) présente dans "Color and Light". Il est évident que le rendu de cette courbe est différent de "Tonecurve" qui agit en mode RGB. Vous pouvez si vous le souhaitez activer les 2 courbes L=f(L) dans "Color and Light" et "Exposure"

===Vibrance===
Module similaire à celui du menu principal.

===Blur and Noise===
Blur n'est actif que si Radius supérieur ou égal à 2.

En réduisant notablement la valeur par défaut de "scope" et en agissant éventuellement sur "Luminance only" il est possible d'obtenir des flous différenciés selon la teinte.

Vous disposez (octobre 2017), de 3 méthodes :
* "normal" : l'algorithme de détection de forme a été amélioré. Il se rapproche de celui utilisé dans les autres modules.
* "inverse" : algorithme simplifié, ne faisant pas intervenir "scope". L'inversion est grossière et ne permet pas une séparation fine des zones à traiter / conserver.
* "symmetric" : ce nouvel algorithme utilise les mêmes processus que "normal" et par l'utilisation de "scope" l'utilisateur peut cibler plus précisément l'action.

Attention:
* travailler en mode inverse, va flouter des zones importantes qui ne pourront pas être corrigées ensuite
* l'action de "scope" peut être déroutante dans certains cas : par exemple pour un portrait les yeux - différents de la peau - seront floutés si "scope" est trop faible.

===Tone mapping===
Attention aux artefacts lorsque les aplats (ciels, zones grises...) sont d'une teinte similaire au spot de contrôle. Dans le cas d'artefacts, mettre le curseur "iterations" de "Reduce artefacts - improve algorithm" à zéro.

===Retinex===
Le nombre de réglages est réduit, par rapport au mode standard. D'autre part, "Retinex local" agit en fin de processus contrairement au mode standard qui est au début du processus Raw.
Depuis la version mip 10002, la courbe "transmission gain" est spécifique à chaque RT-spot.

===Sharpening===
Seul le mode "RL deconvolution" est proposé.

===Contrast By Detail Levels===
* 5 niveaux au lieu de 6 pour le mode pleine image.
* pas de curseurs pour la gestion de la peau; le système utilisé par les RT-spot le remplace.
* ajout d'un curseur pour la chroma
* Attention aux artefacts lorsque les aplats (ciels, zones grises...) sont d'une teinte similaire au RT-spot. Dans le cas d'artefacts, mettre le curseur "iterations" de "Reduce artefacts - improve algorithm" à zéro.

===Denoise===
* par rapport au mode pleine image, seul l'outil wavelet est utilisé: donc pas de fonction de Fourier, ni de medians
* moins de curseurs et de courbes
* par contre, vous pouvez différencier l'action sur la luminance et la chrominance en fonction de la grosseur du bruit - fine ou coarse.

==Réduction des défauts: capteur sale - yeux rouges - ...==
Par conception "Locallab" n'a pas été conçu pour éliminer ces défauts. Néanmoins par effet de bord, certains défauts apparents et gênant en photographie peuvent être réduits voire supprimés. Ceci bien sûr n'est pas incompatible avec d'autres modules plus spécialisés incorporés ou non à "Locallab"...
Au moins 3 fonctions présentes, en adaptant l'usage, peuvent être utilisées, séparément ou ensemble :
* "Color and light" pour des défauts ponctuels ;
* "Contrast by detail level" pour des défauts répartis ;
* "Blur and Noise" en complément éventuel : attention cette action est assez destructrice - à utiliser avec modération.

Vous pouvez agir soit:
* directement, cas général, sur le fichier "raw", ou "TIF", etc.
* soit sur le fichier flat-field si vous en avez élaboré un.

===Utilisation avec le module "Color and Light"===
* Activez "Color and Light"
*Vous pouvez utiliser l'équivalent d'une fonction "yeux rouges" en choisissant un encadrement assez serré de l’œil - sélecteur circulaire centré sur le rouge, délimiteurs de spot proches de l’œil - une valeur de scope réduite, puis agir sur réduction "lightness" -100, et réduction chrominance -100.
*De la même manière vous pouvez réduire les défaut du capteur de type "Spot IR", en choisissant un encadrement assez serré du défaut - sélecteur circulaire centré sur le défaut, délimiteurs de spot proches du défaut - puis agir sur "chrominance" en réduisant la valeur, agir éventuellement sur "scope" pour réduire l'étendue de l'action.
*Vous pouvez dans des cas simples, réduire les défauts de type "capteur encrassé" notamment lorsque celui-ci est gras. Ceci se traduit par des taches qui apparaissent sur les fonds unis. Pour cela choisissez un encadrement assez serré du défaut - sélecteur circulaire centré sur le défaut (adaptez la taille du spot) , délimiteurs de spot pas trop proches du défaut pour permettre une transition peu visible. Puis: a) réduisez "Transition" à des valeurs faibles; b) cochez "Lightness contrast super"; c) agissez sur "luminance" et éventuellement sur "chrominance" pour approcher le rendu de la zone polluée à celui de la zone saine; d) agir modérément sur "scope" pour moduler l'action souhaitée.

===Utilisation avec le module "Contrast by detail levels"===
Dans le cas de capteur encrassé (de type "graisse"), et lorsque la zone est importante ou pour une série de petits défauts, Il peut être utile d'utiliser "Contrast by details levels" qui va agir comme un outil "wavelet" sur la luminance et aussi si nécessaire sur la chrominance. Dans ce cas: a) mettez le Spot de sélection sur un défaut prononcé (en adaptant sa taille si nécessaire); b) choisissez une zone de sélection large pour couvrir la majorité de la surface concernée par les défauts; c)Sélectionnez une valeur de transition assez importante; d) Activez "Contrast by detail levels" et agissez sur les niveaux 3 et 4 ou plus faibles en réduisant le contraste (valeurs inférieures à 100) et en agissant si nécessaire sur le curseur chroma.

== Temps de traitement et utilisation de la mémoire ==

Lorsqu'on utilise la sortie JPG ou TIF, et pour le mode "normal", l'algorithme n'effectue les calculs que pour la zone délimitée. En ce sens les temps de traitement et l'occupation mémoire sont réduits.
Bien sûr le temps de traitement va dépendre du nombre de spots de contrôles, de leur taille, et du type de traitement.

Si on exclue "Denoise" et "Sharp", les temps de traitement sont de l'ordre de quelques dixièmes de seconde par spot de contrôle, et le besoin en mémoire de l'ordre de quelques centaines de M.

Deux réglages agissent fortement sur les temps de traitement et le besoin en mémoire :
* denoise qui ajoute selon la taille du spot de contrôle de l'ordre de 1 seconde et 1 M de mémoire.
* quality enhanced and chroma denoise, qui ajoute environ selon le spot de contrôle de l'ordre de 0.5 secondes et 0.6 M.

==Onglet Preferences==
J'ai regroupé ici, les réglages (repris par ailleurs sur cette page) accessibles depuis "Preferences"
* si vous sélectionnez en "Preferences" / "General" / "Local adjustements", en cochant la case "Show spot delimiters", vous obtiendrez une approximation de la zone concernée par le spot et ses réglages
* Vous pouvez choisir la valeur par défaut de "Global Quality", par exemple si vos images sont très peu bruitées, et ainsi réduire notablement les temps de traitement.Pour cela, aller dans "Preferences", "Performance and Quality", "Local adjustements" et choisir entre Les 3 propositions. C'est ce choix qui sera proposé par défaut à l'utilisateur pour chaque nouveau "Spot", bien sûr il est possible ensuite de modifier ce choix, en sélectionnant la combo-box "Global Quality"
* Fichiers "mip":
**le choix de l'emplacement est possible à partir de : Preferences / Image processing / Mip Profiles
** effacement : aller dans "Preferences" / "Files browser", puis "Clear mip" et / ou "clear pp3" - si bien sûr vous avez positionné "mip" et "pp3" dans le cache, sinon il faudra exécuter cette opération manuellement dans le dossier courant. La présence d'anciennes versions de fichiers "mip" ou de "pp3" peut amener de l'instabilité voire un crash du système.

==Évolutions==
En dehors des habituelles mises aux points, bug, améliorations, réglages, interface, etc. Il serait souhaitable :
* d'améliorer le GUI, pour pouvoir créer / sélectionner / modifier chaque point de contrôle.

En termes "informatique", il devrait être possible pour accroître la lisibilité et la maintenance, d'intégrer l'ensemble du code fichiers *.mip qui actuellement sont linéairement intégrés à Improccoordinator.cc, dcrop.cc et simpleprocess.cc à des procédures "void", à l'exemple de rgbproc.cc

Local Lab Controls

2017-10-26T17:09:49Z

Sguyader: Created page with "==What kind of local control?== Several types of local control exist in mainstream applications : # “lasso”, associated with layers and fusion masks (e.g. Photoshop©)...."

==What kind of local control?==

Several types of local control exist in mainstream applications :
# “lasso”, associated with layers and fusion masks (e.g. Photoshop©). This kind of control is widespread (Photoshop, Gimp, Darktable…) and users tend to favor those, at the expense of the type desciribed in 3. below, which is less well known;
# dedicated tools for the removal of image defects such as « red eyes », or « spots » associated with sensor imperfections or dirt;
# “U-points” controls, used until recently in Nikon Capture NX2©, or as an add-on to other software such as Nik Software©. For those (rare now) who tried such programs, there’s no way turning back to layers and fusion masks! This type of local control requires learning something different, and a cognitive “unprogramming”. In my opinion, this kind of local control is globally more efficient.

The algorithm developed in the current version of RawTherapee is close in its principle to the U-points described above. Of course, the code used in Nik Software is not disclosed, but several years ago I was attracted by the simplicity of use and the efficiency of U-points, and I started developing a product which would use neither lassos, nor layers or fusion masks. Of course, nothing prevents us from having all 3 types of local control in the same program.

The current version of the filter is perfectible, particularly regarding the user interface (GUI):
* for managing and viewing the RT-spots (control spots) on screen,
* for manipulating the different sliders, which would ideally be better if integrated to the actual control points, as done in Nik Software.

However, those two aspects don’t harm everyday use, nor code portability.

In order to improve manipulation and avoid long menus on screen, I added a GUI interface which is similar to the one used in the Wavelet tab, with “expanders”. Thus for each module (“Color and Light”, “Blur”, “Retinex”, …) you can choose to:
# display (or not) the full list of commands: sliders methods, curves…
# activate (or not) the all the functions of the module.

Warning: choice 2. activates or cancels all the RT-spots; it would be possible in theory to add this capability to every single RT-spot, but for what purpose?

===Lab and RGB local controls===
* The first algorithms are coded in L*a*b* mode with the following modules: “Color and Light”, “Blur / Add noise”, “Retinex”, “Tone mapping”, “Sharpen”, “Contrast by Detail Levels”, “Denoise”. Two additional modules have been added: “Exposure” and “Vibrance”.
* See below for the principles of the different algorithms, but one key point to remember for shape detection and artifacts avoidance, is that the Lab mode preserves the “hue” tint, which is crucial.
* The idea of an “RGB” module comes to one’s mind, with a minima:
** a “White balance” module, which would allow to locally adjust the white balance, for example to warm up shadows, or to deal with mixed scene lighting such as “daylight” and “tungsten”. This module needs to be inserted just after “demosaic”.

====Auto White balance====
The “White balance” module (in the “autowblocal” branch) serves two purposes:
* allowing a local adjustment of the white balance (of course)
* testing new algorithms for automatic white balance adjustment:
** in general use (full image), in order to achieve better results than with the current algorithm. Of course one will tell me that I should create a specific branch for “White balance”, but here I’m trying to hit two targets with one bullet.

As a reminder, I’ve been asked in 2012 and 2013 to develop an iterative white balance “Auto Robust WB[http://ieeexplore.ieee.org/document/1649677/]”. At that time, another developer and I had spent a lot of time on this for an unsatisfactory result, so we gave up. Since then, benefiting from this experience, I resumed this work but in the reverse way! Now, if I’m correct, the algorithm works. I took advantage of this new capability (currently working on raw images only) to search in the academic literature for other auto WB algorithms. I found, and developed two new algorithms:
* “auto edge”[https://www.researchgate.net/publication/301419990_A_Method_to_Improve_Robustness_of_the_Gray_World_Algorithm]: the idea is to create an accentuation mask allowing to reinforce parts of the image where details are more prevalent, compared to flatter regions.
* “auto standard deviation”[http://www.acad.bg/rismim/itc/sub/archiv/Paper3_1_2012.pdf]: here, the image (or part of it for the local control) is divided in 12 zones, for each of which mean and standard deviation are computed, and the result assembled.
A third algorithm, “Color by correlation”[https://courses.cs.washington.edu/courses/cse467/08au/labs/l5/whiteBalance.pdf], looks promising but I’m facing several difficulties. After many trials of many types, the results are just too erratic…

I also added the notion of gamma:
* the same principles which deal with luminance distribution – gamma sRGB – used in the main RawTherapee code.

As a reminder, the automatic white balancing is a totally non deterministic mathematical problem. The algorithms may perform more or less well (and faster or slower), but a perfect result can’t exist! Why is it so? If one is referring to the principles of color management ([http://rawpedia.rawtherapee.com/Color_Management_addon/fr#Balance_des_blancs]), it is necessary to have knowledge of the three of: the colored object, the illuminant and the observer. At least two of those are unknown in practice. In addition, the environment in which an image is shot is not known while it has an effect on the perception (CIECAM), and the same is true during both image editing and viewing. The mission is thus almost impossible!

The aim of the “White balance” module is '''for testing the algorithms''', there are 7 of them at least, and twice that number if “gamma sRGB” is considered. Indeed, in order to circumvent the obstacles encountered five years ago, instead of the using the image before demosaicing, I used the image just after demosaicing, allowing to apply (or not) “gamma sRGB”, ending in the same conditions as in normal use (but without normal “White balance” and “ICC or DCP” profile).

Ideally, we should test the algorithms on many images, as well: which algorithm(s) to keep and implement in normal – global RGB – mode (maybe one or two, in addition to the current algorithm which we should keep for compatibility).

====Local control of White balance====
The local control is currently limited to 1 spot only, but there’s no difficulty to increase this if users want so… while waiting for the evolution of “locallab”.

Of course, I hear voices say “it doesn’t work”, or “the output doesn’t match with the preview”. But it does work! And it is more than evident that matching exactly the preview is by definition almost impossible… (differences between shadows, sun light, different illuminants, etc…) whatever the relevance of the algorithm.

==What are the challenges to be solved?==
Several general issues need to be solved so as to achieve smoothness in use:
* allow an (almost) unlimited number of RT-spots (the name we chose for the control spots in RawTherapee);
* adapt the local algorithms to be aware of scale, because many of them take the image size – the treated area – into account. This aspect is fundamental, particularly with curves which act on the whole image;
* minimize memory use and computation time for JPG and TIFF output;
* allow easy updates in case of evolution of either the algorithms or the number of methods/modules;
* optimize (minimize) the differences between the preview and the output.
* etc…

For each RT-spot:
* allow for the action to occur, on user choice, either inside or outside (“Inverse” mode) of the selection area;
* allow shape detection, on user choice, in order to limit the action based on features/shapes;
* take care of the transition between the center of the treated area and the other parts of the image;
* etc…

Currently, RT-spots are operational in Lab mode with the following modules and methods:
# “Color and Light”: “Lightness”, “Chrominance”, “Contrast” in normal mode with 4 curves L=f(L), L=f(H), C=f(C), H=f(H), and in “inverse” mode;
# “Exposure”: normal mode only;
# “Vibrance:” normal mode only;
# “Blur & noise”: normal and “inverse” modes;
# “Retinex”: normal and “inverse” modes, now also with “transmission gain” curve;
# “Sharpening”: normal and “inverse” modes;
# “Contrast by detail levels” (CBDL): normal mode only;
# “Denoise”: normal mode only.

==General principles==
===The RT-spot object===
As I mentioned earlier, the system used in RT is similar to the one developed in Nik Software, but with some significant differences:
* each RT-spot can be viewed as an object with a number of fields (about 70 as of today), made of sliders, curves, control points, etc…;
* each field, grouped in modules, can be activated or not, and have different parameter values according to their nature;
* the modules are made to be coherent for the user: “Color and Light”, “Exposure”, “Contrast”, “Vibrance”, “Blur”, “Retinex”, “Sharpening”, “Tone Mapping”, “Contrast by detail levels”, “Denoise” ;
* the number of RT-spot objects can vary from 2 up to 500 ;
* data describing the RT-spot objects are stored in text files with .mip extension ;
* creating, modifying and tracking of the RT-spot objects are done in a “for” loop;
* there’s no code duplication.

===Partitioning into 4 zones – previewing the RT-spot area===
When the user selects an RT-spot, the screen preview shows:
* a center, made of a circle whose diameter and position can be adjusted directly using the mouse or the sliders;
* two horizontal and two vertical handles, whose position can be modified directly using the mouse or the provided sliders, controlling the extent of the area affected by the RT-spot;
* if "Show spot delimiters" is checked in "Preferences" > "General" tab > "Local adjustments", one can visualize approximately the area affected by the spot. Because I couldn’t work cleanly with the « arc/ellipse/scale » function in the Cairo graphics library, I made each quadrant defined by a pseudo-ellipse made of 3 Bézier curves joining each other. In most cases the approximation is satisfying… To help grabing the 4 handles, I made them longer (the Bézier curves are inactive!).

We obtain 4 zones, whose orientation can be modified (the default rotation angle is set to zero). Those 4 zones have each of their vertices connected by imaginary ellipses.

It is possible to drag the handles outside the image preview area.

It should be possible to replace the ellipse with a hand drawn curve (even if I think its usefulness is debatable because of the existence of the shape detection algorithm), as long as the homothetic transform of the curve doesn’t intersect with the original curve. Although the benefits from this intellectually satisfying “improvement” should negligible in the case of the RT-spots, it will be possible to make the current RT-spots and lasso type of controls coexist eventually.

===Tint, chroma, luminance references and the algorithm principle in “normal” mode===
In order to develop an efficient shape detection algorithm:
* The central circle zone is used as the reference. Based on the diameter value chosen by the user, the algorithm computes the tint (hue), chroma and luminance averages.
* The choice of the central zone diameter depends on the use intent. For example, if working on a foliage area the user would benefit from choosing a smaller diameter value in order to select only the foliage green; in contrast, for skin tones the user should increase the diameter to avoid the detection of parasites (noise, eye lashes…).
* For each quadrant, depending on the the value of the “Scope” slider, the algorithm does:
# take into account the tint difference between the zone center and the affected pixel;
# through a complex algorithm based on the deltaE notion (perceived difference between two colors, taking tint, chroma and luminance into account), decrease the amount of applied effect as a function of the difference between the central zone and the affected pixel;
# follow either a linear or a parabolic law to adjust the amount of applied effect, based on the specific the case.

This allows adapting the amount of effect according to the above-mentioned criteria. For example, if the central circle is located on foliage, the action will be limited to the leaves, without touching the background (which would be impossible to obtain with the lasso type of controls). Additionally, if some other foliage resides within the area covered by the RT-spot, it will also be affected.
* Adjusting the value of the “Transition” slider modifies the transition of the effect (from the center to the edge): on 50, the inner (linear) half will get the full 100% action/effect, while the effect in the outer half will gradually transition from 100% to 0% towards the edge;
* By increasing the value of “Scope”, progressively more of the selected area is taken into account, whatever the tint, chroma and luminance;
* Conversely, by decreasing the “Scope” value the effect will get limited to the pixels which are more similar (in terms of deltaE) to the reference zone.

The shape detection algorithm works in “Normal” mode except for some modules (“Denoise”). It’s not implemented in “Inverse” mode, doing so would not make sense.

The algorithm will see its performance increase when the user chooses “Enhanced” or “Enhanced + chroma denoise” in the “Global quality:” combobox. The second choice additionally applies a low amount of chroma noise reduction in order to get rid of artifacts which could be brought up by the “Enhanced” algorithm (note that the chroma denoise step increases memory use and computing time).

The algorithm is used in full capacity for “scope” < 20.

===Why no alternative algorithms?===
It should be possible to implement other shape detection algorithms than the deltaE-based one used currently, for example:
* edge detection algorithms such as “Canny” or “Sobel”;
* wavelet decomposition.

But in both cases, everything would have to be done!

===Functioning in “inverse” mode===
When it is available, the “Inverse” mode is extremely simplified: only the “Transition” slider can be used to apply the effect.
As of late October 2017, I devised a new method for “Inverse” mode. It is limited to the “Blur & Noise” module (see the corresponding section below).

===Maximum number of RT-spots===
By default the number of available RT-spots is 8. You can choose any number between 2 and 499. For this you only need to change the parameter “Nspot” in the “options” file (for example: Nspot=12). Restart RawTherapee for the modification to be taken into account.

===The “super” algorithm===
The key to “success” was the algorithm implemented in late January 2017, which works this way:
# on the pixel data which are within the area covered by the RT-spot, the algorithm applies either a “traditional” curve, a slider, or a normal transfer function (“Retinex”, “Tone Mapping”, “Contrast by detail levels”, “Vibrance”, …);
# the LUT or the transfer function is converted into an equivalent of a slider, separating negative and positive values so that the function can be viewed as multiple sliders (as many sliders as there are pixels) in the -100, 0, +100 interval;
# the data are passed to the shape detection function – the 4 quadrants. For every pixel, the difference in terms of tint, chroma and luma is computed with regards to the central reference. The linear variation equations are estimated for luminance (L=f(L)), chroma (C=f(C)) or transfer functions;
# different corrections are applied to account for the environment (sky, skin tones…)
# a correction is made (with threshold and iterations) in order to avoid correcting (or only slightly, based on the user’s choice) the gray or neutral tones which are in the same tint as the reference (but with a low chroma value);
# the parameters are weighted based on the shape of the RT-spot (ellipses) and the transition zone;
# the values of the “Global quality:” parameters are important, particularly so for images with a low amount of noise – chroma noise is interpreted by the algorithm being of the same color as the spot. It is thus necessary to suppress this noise, that is the purpose of “Enhanced + chroma denoise” (this algorithm may not be sufficient, though – in this case using the local “Denoise” module may be useful).

This new (“super”) algorithm seems to perform generally well, but in the event when the RT-spot is located in a gray/neutral or flat area, the algorithm may fail. In such cases, using the old algorithm is recommended (except for “Retinex”, “Tone Mapping” and “Contrast by detail levels” for which it is made unavailable for the sake of code simplicity).

===Artifact reduction and the “Global quality” algorithms===
By default, “Global quality:” is set to “Enhanced + chroma denoise”. Whereas it increases computation time, it is still generally preferable. In case one wants a more responsive preview, “Enhance” or “Standard” can be chosen (good for exploring the image).
* two sliders allow reducing artifacts and improving the algorithm’s rendering. They work based on chroma, in neutral/gray tones. To completely remove its effect, one can simply set “iterations=0”. These sliders may be used for "Color light", "Exposure", "Retinex", "Vibrance", "Tone mapping" and "Contrast by detail levels";
* for (even slightly) noisy images, the algorithms may be misled. In this case it is recommended to keep "Global quality:” set to “Enhanced + chroma denoise", and (sometimes) activate the local “Denoise” module and adjust the sliders very gently (including “Luminance”);
* under some circumstances, with “Tone Mapping” for example, the artifact reduction algorithm may actually generate more artifacts. When it happens, set “iterations=0”.

If your images are generally clean (no or very low noise), you can choose to have “Standard” as the default for “Global quality:” – this will speed up the image processing. To do so, go to “Preferences” > “Performance and quality” tab > “Local adjustments” and choose the “Standard” algorithm among the 3 options. This will become the new default when new RT-spots are created, but of course the algorithm can still be changed on the fly by choosing from the “Global quality” combo box.

===Avoid color shift===
The “Avoid color shift” checkbox serves two purposes:
* put the colors within the current working profile gamut, using a relative colorimetry;
* adjust colors using a “Munsell” correction – particularly for red-orange and blue-purple colors, when saturation in the L*a*b* space has changed significantly.

===“mip” files – Principles of the multi-point algorithm===
For the local control system to work and keep track of RT-spot objects, a text file – similar to a pp3 – is written in 2 possible places:
* next to the edited image file. If, for example, you edit an image named ASC4509.NEF, a new file named ASC4509.NEF.mip will be generated in the same folder. In this case, several sessions can be open for the same image, as long as copies of the image are stored in different folders. However, the folder names in the path have to contain ASCII characters only, otherwise it will make the program crash;
* in the dedicated “mip” folder, within the “cache” directory (through an MD5 hash number which identifies the file). This is the default. If chosen, when multiple copies of the same file exist in distinct folders, editing them creates as many “mip” files. This option allows the use of non ASCII characters in the folder names and path.

The choice between these two behaviors is made in “Preferences” > “Image processing” tab > “Mip profiles”.

The “mip” files contain the data which are passed to RawTherapee through processes of the “procparams” type, and LUTs which allow editing in zoom mode. When updating RawTherapee to a new version, it may be required to delete the “mip” files (or the whole cache) to avoid a potential crash of the application. This can be achieved by going to “Preferences” > “File browser” tab, then choosing “Clear mip” and/or “Clear pp3” – all this is valid only if “mip” and “pp3” files have been set to be saved to the cache folder, otherwise they will have to be manually deleted from the working folder. Keeping older “mip” and “pp3” files may lead to instability or crashes of the application.

====Architecture of the filter====
When I “ventured” into a multi-point, no-layer and no-mask system, code duplication had to be avoided. Indeed, it is unthinkable to consider, for 10 RT-spots, generating 10 GUI code blocks, and just as many code blocks in “rtengine”. After careful consideration, the idea was to have a file updating and tracking in real time – i.e. a file which would follow each modification made by the user – the actions/modifications history.

Of course, the parameters used by RawTherapee for the GUI and for the main code through “params” are of different types:
* numeric: integer, float, double,…
* boolean
* string (in choice menus for the different modules)
* curves, through “vectors” of type double with dynamic dimension
* …

====Data conversion====
In order to simplify data management, the first step is to convert all data to integers. Sometimes this can lead to a slight precision loss, which I think is negligible.
* This operation is very simple for numeric values, even though in some cases (such as hue, which is expressed in radians in the interval [-Pi, +Pi]) it needs a double “float*100 and /100 conversion to keep precision.
* It is logical for boolean operations and methods.
* However, it is a complex matter regarding curves. The values to be recorded in the “mip” file are of type vector<double>, in a dynamic table of numeric values. There may be a simpler way, by using existing functions from “procparams”, but I didn’t suceed.
Nevertheless, I could get around this by:
# converting doubles to integers with 3 significant figures – which is largely enough,
# then converting the “vector” to a variable length character string,
# the writing and reading of this character string and converting to a vector dynamically using an appropriate function (”strcurv_data”). Note that this function allows adjusting the curves within the limit of 16 inflection points (Bézier curve) for the flat curve, and 32 points for the diagonal, which should be enough. Whether this would not be enough, it should be possible to increase that number, though compatibility would be compromised.

====Some elements about curves====
The implementation of curves has been a complex task, particularly since:
# each curve needs its own reset function – resize() at each iteration,
# which implies oddities regarding their description, for example the diagonal curve gets initialized with several points, despite it looks being “empty”. This is mandatory for correct functioning, but this means that the curve is always open/active. Consequently, to avoid some unwanted loss of computation time in “preview” mode, the user has to activate the curve by clicking on the “curves” combobox. The same activation is necessary for L=f(H) and C=f(C) curves. While clicking enabling the “curves” (linear) would seem to be a better solution, it didn’t work despite many trials.
# during all the procedure, we need to set each "params" value to "clear" for curves, for each LUT, at each iteration and then through a "vector" to reassign the good, updated values to "curve params".

====Data storing and dynamic use====
Once data have been converted:
* they are stored in a text (mip) file,
* each one is referenced inside a 2-dimension dynamical table:
# dataspot[x][y] for numeric and boolean values and methods, where “x” is the representative index of the parameter (e.g. “9” is for “lightness”) and “y” represents the current RT-spot (control spot). Value “0” represents the current in-use value (the one stores in “params”).
# retistr[y], llstr[y], lhstr[y], ccstr[y], hhstr[y], skinstr[y], pthstr[y], exstr[y] for parameters of type “curve”. Currently there are only 8 parameters, used for local “Retinex”, “Color and light” (L=f(L), C=f(C), L=f(H), H=F(H)), “Vibrance” and “Exposure”, but it is easy to add more. “y” is used as above in 1.

The way data are stored and used fits well with improccoordinator.cc (current management / preview) and simpleprocess.cc (TIFF / JPG output) files, but not so with dcrop.cc and the partial display of the image (RawTherapee’s pipeline).

In this case (zoom / preview) another solution had to be found in order to synchronize the modifications in real time. I made use of LUTs, so that to each entry referenced in the table described above a LUTi(z) is associated, with z=500 possible entries (500 corresponds to the current maximum number of RT-spots, but this limit can be decreased or increased). The LUTi “z” corresponds to the dataspot “y”. A 25,000 entries LUTi (arbitrary number) is used for “retistr”, “llstr”, “lhstr”, “ccstr”, “hhstr”, “skinstr”, “pthstr”, “exstr” for storing each “vector” curve value in memory (up to 69 values stored as integers).

During data processing, exchanges occur between: params, dynamic tables and LUTi. The values used by dcrop.cc are dynamically linked to dynamical tables by parent→.

====Exchange processes and dynamic data storing====
# reading of the “mip” file to check the version number and guide the updates
# creating the “mip” file if it doesn’t exist
# storing the data in LUTi and dynamic tables from the values stored in “params” (index 0 values)
# first interactive update with the GUI through a transfer function between “rtengine” and locallab.cc (aloListener → localretChanged). This is one of the 3 functions required for the process to work correctly
# reading of the “mip” file and data storing in dynamic tables (index values ==> y) according to the number of RT-spots
# creating a loop – according to the number of RT-spots – which updates LUTi (required by “dcrop”) and “params” values from values stored in the dynamic tables
# call to the “Lab_local” function which contains the algorithms controlling each RT-spot (luminance, sharpness, retinex, denoise, …)
# second interactive update with the GUI through another transfer function between “rtengine” and “locallab.cc”
# treatment of the current RT-spot by using the index (0) values from the dynamic tables. These values are attributed to 1) “params”, 2) LUTi and 3) current index values
# call to the “Lab_local” function for the current RT-spots
# saving to the “mip” file.

Note that if the user modifies the curve (amplitude, number of inflection points) a third interactive update is made in order to conform all of the data according to events.

====A few unavoidable “fantasies”====
Of course everything looks simple, the process works if, and only if, all the data are dynamically updated. I’ve tried a lot, went groping, and finally found a working solution… but an uncanny one. There’s probably a more “informatically” correct way to do it, but at this point I’ve done as explained above and hereafter.

The 3 exchanges between “rtengine” and the GUI occur with 3 parameters which actually do nothing in the program except doing the update process:
# “anbspot” which takes values of 0 or 1
# “cTgainshaperab” (curve) which takes any value bewteen 0.70 and 0.90
# “retrab” which varies around 500.
I have added 3 more parameters (in the form of sliders) – hueref, chromaref and lumaref – hidden from the user but which are used to update the system in real time, to correctly take into account the reference “spot” values. Allowing those 3 parameters to vary brings stability and allows real time updates. Increasing the number of those “fantasy” parameters should not be necessary. These extra parameters are hidden to the user, and are only visible in the history.

In addition, I had to add some empirical time delays, giving time to time… Time delay is used for example when the user modifies the curve (amplitude, number of inflection points).

==Some specificities of the local mode (as compared to “Lab adjustments”)==
Hereafter are some useful informations for the user, often specific to the local mode.

===Color and Light===
* The algorithms used for luminance and contrast in local mode differ from the ones used in “Lab adjustments”, which may lead to differences in rendering.
* The luminance algorithm is made such that below -90 and down to -100 for “lightness”, it is possible to increase the image “darkness”, almost to the point of getting a luminance value close to 0. To accentuate this effect, “chrominance” can be decreased and “scope” increased.
* The inverse mode can be used for creating graduated frames. If “ligthness” is set to -100 and chrominance is reduced, the “frame border” will be black.
* For “luminance” and “contrast” (slider), there’s a choice among 2 algorithms: the first (default) one is close to the one in “Lab adjustments” while the second one, activated through “Lightness - Contrast ‘Super’” is close to the algorithm used for the L=f(L) “super” curve.
* Do not hesitate, as the case might be, to activate “Enhanced” or “Enhanced + chroma denoise” for in the “Global Quality:” combobox.

====Curves====
* An L=f(L) or C=f(C) curves allow controlling the luminance and chrominance for each RT-spot as a function of luminance or chrominance.
* An L=f(H) curve allows controlling the luminance for each RT-spot as a function of tint.
* An H=f(H) curve allows controlling the tint for each RT-spot as a function of tint.
The curves are activated by selecting one of the two algorithms from the “Curves types” combobox:
* “Normal”: the curves – particularly the one that is the most difficult to manage, L=f(L) – use an algorithm close to the one used with the sliders (Normal mode),
* “Super”: using a new algorithm, which I think performs very well (it even surprised me the first time I used it).

Caution: when the RT-spot resides in an area which is neutral, gray or very uniform, the artifacts introduced by the new algorithm (“Super” algorithm for the curve or the slider) may be impossible to get rid of. Use one of the 2 older algorithms to avoid that.

===Exposure===
The “Exposure” module may look like the the one in global RGB mode, but:
* it works entirely in L*a*b* mode, hence the differences in rendering;
* there’s no “Lightness”, “Chroma” or “Contrast” slider, whose functions are already fullfilled in the “Color and Light” module;
* there’s only one “Contrast” curve, similar to the L=f(L) firm “Color and Light”. Of course its effect is different from “Tone curve” which works in RGB mode. If needed, 2 L=f(L) curveds can be activated, one in “Color and Light” and the other in “Exposure”.

===Vibrance===
This module is similar to the main one (from Exposure tab).

===Blur & Noise===
“Blur” is activated only when “Radius” =< 2.
By significantly lowering the default value of “Scope” and possibly checking “Blur luminance only”, it is possible to get a different amount of blur for the different tints.
Since October 2017, 3 methods are proposed:
* “Normal”: the shape detection algorithm has been improved, it is now closer to shape detection algorithm proposed in the other modules;
* “Inverse”: a simplified algorithm, which doesn’t make use of “Scope”. The inversion is coarse and doesn’t allow a fine separation between the affected and unaffected areas;
* “Symmetric”: this new algorithm uses the same processes as “Normal”, and adjusting “Scope” the user can target the process with more precison.
Caution:
* Using the “Inverse” mode will blur large portions of the image, which can not be corrected later on.
* The action of “Scope” may sometimes appear puzzling: for instance, in a portrait, the eyes (which of course differ from the skin) may be blurred if the value of “Scope” is too low.

===Tone Mapping===
Caution when uniformly colored areas (sky, gray/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artifacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artifacts – Improve algorithm”.

===Retinex===
Compared to the standard “Retinex” module, the local “Retinex module has simplified controls, and is applied at the end of the pipeline instead of the beginning. Since mip version 10002, the “Transmission gain” is specific to each RT-spot.

===Sharpening===
Only the “RL Deconvolution” algorithm is provided here.

===Contrast by detail levels===
Compared to the main RGB mode module, this one has:
* 5 levels instead of 6,
* no slider for “skin tone” protection (not needed since the algorithm works locally on the RT-spot area),
* an additional “Chroma” slider.

Caution when uniformly colored areas (sky, gray/neutral zones) have a similar tint to the area on which the RT-spot is placed. In cases where this leads to artifacts, set the “Iterations” slider to 0 in “Settings” > “Reduce artifacts – Improve algorithm”.

===Denoise===
Compared to the main RGB mode module, this one has:
* only the wavelet tool working (no Fourier function, nor medians),
* less sliders and curves,
* the possibility to work differentially on fine or coarse noise for both luminance and chrominance noise.

==Specific case : reduction of image defects (dirty sensor, red eyes, …)==
“Locallab” had not been thought with the idea of correcting small image defects. However, some visible, “photographically disturbing” defects may actually be tamed or even removed. Of course, this is not incompatible with other more specialized modules which could be introduced (or not) into “Locallab”… At least 3 existing modules can serve this purpose, alone or in combination, by adapting their use:
* “Color and Light” for spot-like defects;
* “Contrast by detail levels” for spread out defects;
* “Blur and Noise” as an optional complement (caution, this is a destructive action, use moderately).

These modules can be used either on the main image (raw, TIFF, …) or on a flat-field image.

===Using the “Color and Light” module===
* Activate “Color and Light”
* A red eye removal tool equivalent can be obtained by framing closely around the eye – central circle zone centered on the eye’s red, spot handles close to the eye – low “Scope” value, then lowering “Lightness” and “Chrominance” to -100.
* The same idea allows reducing the “IR spot” kind of defect by framing closely around the defect – central circle zone centered on the defect, spot handles close to the defect area – then lowering “Chrominance” to taste, and if needed lowering the “scope” value.
* In some (simple) situations, a “dirty sensor” defect can be reduced, in particular in the case of “sensor grease”. It can be seen as stains or spots on a uniform background. To attenuate this, choose a tight framing of around the defect – central circle on the center of the defect (adapt the size of the RT-spot), drag the handles so that they are not too close to the border of the defect (this will make the transition less noticeable). Then: a) decrease “Transition” towards lower values; b) check “Lightness - Contrast “Super”; c) adjust “Lightness” and “Chrominance” as needed to bring the defect area closer to the unaffected area; d) if needed adjust slightly “Scope” to achieve the best result.

===Using the “Contrast by detail levels” module===
When the sensor is dirty (grease), and when the affected area is large or if there are multiple small defects, “Contrast by detail levels” may be used, working as a sort of “wavelet” tool on luminance, and if needed on chrominance. In such cases: a) place the RT-spot on one of the stronger defects (adjust the size as needed); b) drag the handles so as to cover most of the affected area; c) set “Transition” to higher value; d) activate “Contrast by detail levels” and decrease the contrast of levels 3 and 4 (or lower); you can adjust the “Chroma” slider if needed.

==Preferences options and settings==
Below is a list of the settings (already mentioned above in several places) which can be accessed from the “Preferences” dialog:
* In “Preferences” > “General” tab > “Local adjustments”, by checking the “Show spot delimiters” checkbox, an approximate zone delimitation is drawn which helps viewing the area affected by the RT-spot and its settings.
* If your images generally have low noise, you can set the default for “Global quality” to “Standard”, and get a significant speedup in processing time. This setting is found under “Preferences” > “Performance & Quality” tab > “Local adjustments”. The three choices for quality are selected from the “Local adjustments Quality method” combobox. Default is “Enhanced + chroma denoise”.
* Regarding “mip” files:
** the choice for “mip” files destination folder is set from “Preferences” > “Image processing” tab > “Mip Profiles”;
** in order to clean the generated “mip” profiles, go to “Preferences” > “File Browser” tab > “Cache Options” and click on the “Clear mip” button and/or “Clear pp3” – this is valid in the case where you chose to store “mip” files in the cache, otherwise if you chose to let RT write the “mip” files next to the input file, you will have to delete them manually. Note that the presence of older versions of “mip” and “pp3” files may lead to instability or even crashes of RawTherapee.

==Processing time and memory use==
At image export time (output to JPG, TIFF…), for the “normal” mode, the algorithms compute the data only for in the RT-spot delimited areas, not for the whole image. Thus, processing time and memory stay reasonable. Note that of course, this will depend on the number of RT-spots, their size, and the type(s) of treatment done in these RT-spots.

Excluding “Denoise” and “Sharpen”, processing time is in the order of a few tenths of a second per RT-spot, and memory use of a few hundred MB.

Two settings have a strong influence on resource use:
• “Denoise” which adds around 1 sec. of processing time, and 1 MB of memory use;
• “Global quality: Enhanced + chroma denoise” which adds around 0.5 sec. And 0.6 MB.
These figures depend on the size of the RT-spot.

==Future evolutions==
Besides usual tweaking, bug corrections, improvements (settings, user interface)… it would be desirable to improve the GUI with regards to the creation/selection/modification of individual RT-spots.

From a programming point of view, it should be possible to improve code readability and maintainability, and to integrate all the “mip” files code parts (as done in “rgbproc.cc”) which currently are linearly integrated to void procedures in “improccoordinator.cc”, “dcrop.cc” and “simpleprocess.cc”.