RawPedia - User contributions [en]

Linux

2022-11-05T09:19:26Z

Thanatomanic: Added CentOS 8 update

<div class="pagetitle">Linux</div>

This page details instructions for compiling RawTherapee on '''GNU/Linux''' systems. There are also instructions for compiling on [[Windows]] and [[macOS]].

When in doubt, [[IRC|join us on IRC]] or in the [[Forum]] and ask a human!

== Dependencies ==

To compile RawTherapee your system will need a set of tools and code libraries from other programs. These are called dependencies, and here is a list of them for the latest version of RawTherapee:

{| class="wikitable sortable"
|+ Build-time dependencies for RawTherapee:
! Package !! Version !! URL
|-
| CMake || cmake>=3.5 || https://cmake.org/
|-
| EXIV2 || exiv2>=0.19 || http://www.exiv2.org/
|-
| EXPAT || expat>=2.1.0 || https://libexpat.github.io/
|-
| FFTW3 || fftw>=3.2.2 || http://fftw.org/
|-
| GCC || gcc>=4.9 || https://gcc.gnu.org/
|-
| GLIB2 || glib-2.0>=2.24 || https://www.gtk.org/
|-
| GLIBMM || glibmm-2.4>=2.24 || https://www.gtkmm.org/
|-
| GTK+ || gtk+-3.16 < 3.24.0 || https://www.gtk.org/
|-
| GTKMM || gtkmm-3.16 || https://www.gtkmm.org/
|-
| JPEG || libjpeg>=6b || https://libjpeg-turbo.org/ https://jpegclub.org/ https://www.ijg.org/
|-
| LCMS2 || lcms>=2.6 || https://www.littlecms.com/
|-
| LENSFUN || lensfun>=0.2 || https://github.com/lensfun/lensfun
|-
| LIBCANBERRA || libcanberra>=0.29 || http://0pointer.de/lennart/projects/libcanberra/ (Linux only)
|-
| LIBIPTCDATA || libiptcdata>=1.0.2 || http://libiptcdata.sourceforge.net
|-
| PNG || libpng>=1.2.44 || http://www.libpng.org/
|-
| librsvg || librsvg>=2.40 || https://github.com/GNOME/librsvg
|-
| SIGC || sigc++-2.0 || https://github.com/libsigcplusplus/libsigcplusplus
|-
| TIFF || libtiff>=4.0.4 || http://libtiff.org/
|-
| ZLIB || zlib>=1.2.3 || http://www.zlib.net/
|}

In order to install all these dependencies, you will need to open a console and paste the code from the appropriate section into the console.

The code snippets below list dependencies for the latest RawTherapee code which requires GTK3. We dropped support for GTK2 with release "5.0-r1-gtk2" in February 2017. If you use a modern distribution, just copy and paste the code snippets as they are. If you're on an old distribution without the required GTK3 support, then refer to the archived [[Linux_GTK2|GTK2]] article, then checkout and compile the obsolete <code>5.0-r1-gtk2</code> tag.

=== Arch/Manjaro ===

Current versions of Arch and Manjaro work well out of the box. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 17.1.12.

<pre style="white-space: pre-wrap">sudo pacman -S cmake ninja exiv2 expat fftw glib2 glibmm gtk3 gtkmm3 lcms2 lensfun libcanberra libiptcdata libjpeg-turbo libpng librsvg libsigc++ libtiff zlib</pre>

For Manjaro, you may need to additionally install the <code>pkg-config</code> package.

Proceed to [[#Compilation|Compilation]].

=== CentOS ===

CentOS 8 and newer, lack the <code>libiptcdata</code> library. Manual compilation is required - any suggestions on how to proceed are welcome.

CentOS 7 has very outdated packages and requires extra steps to install a recent GCC, git, lensfun and libtiff. The steps below were verified to work in CentOS 7.4.1708, but proceed at your own risk.

GCC >=4.9.3:
<pre style="white-space: pre-wrap">sudo yum update
sudo yum install cmake git
sudo yum install centos-release-scl
sudo yum install devtoolset-7-gcc*
scl enable devtoolset-7 bash
source /opt/rh/devtoolset-7/enable</pre>

git >=2.7:
<pre style="white-space: pre-wrap">sudo yum install http://opensource.wandisco.com/centos/7/git/x86_64/wandisco-git-release-7-2.noarch.rpm</pre>

lensfun:
<pre style="white-space: pre-wrap">
wget http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -ivh epel-release-latest-7.noarch.rpm</pre>

libtiff >=4.0.4:
<pre style="white-space: pre-wrap">sudo yum install ninja-build
mkdir ~/programs && cd ~/programs
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
mkdir tiff-4.0.9/libtiff-build && cd tiff-4.0.9/libtiff-build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

Install the other dependencies:
<pre style="white-space: pre-wrap">sudo yum install curl expat-devel fftw-devel gtk3-devel gtkmm30-devel lcms2-devel lensfun-devel libcanberra-devel libiptcdata-devel libjpeg-turbo-devel libpng-devel librsvg2-devel zlib-devel</pre>

Symlink libatomic:
<pre style="white-space: pre-wrap">sudo ln -s /usr/lib64/libatomic.so.1 /usr/lib64/libatomic.so</pre>

As you proceed to the next step - compilation - you will need to edit the <code>build-rawtherapee</code> script and add these three lines to the CMake section near the end of the file, for example after the "-DWITH_BENCHMARK" line before the "$HOME" line:
<pre style="white-space: pre-wrap"> -DTIFF_INCLUDE_DIR="$HOME/programs/tiff-4.0.9/libtiff" \
-DTIFF_LIBRARY="$HOME/programs/tiff-4.0.9/libtiff-build/libtiff/libtiff.so" \
-DCMAKE_CXX_FLAGS="-Wno-deprecated -Wno-parentheses" \
</pre>

Proceed to [[#Compilation|Compilation]].

=== Debian/Ubuntu/Mint/elementary OS ===

Current versions of these distributions work well out of the box (Debian >=9, Ubuntu >=18.04 LTS, Linux Mint >=19, elementary OS >=5). Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo apt install git build-essential cmake curl pkg-config libgtk-3-dev libgtkmm-3.0-dev liblensfun-dev librsvg2-dev liblcms2-dev libfftw3-dev libiptcdata0-dev libtiff5-dev libcanberra-gtk3-dev</pre>

==== Ubuntu 16.04 LTS (Xenial) ====
RawTherapee 5.8 (release) is the latest version supported for Xenial-based distributions. See [https://github.com/Beep6581/RawTherapee/issues/5943 here] for details. When compiling, follow the manual steps and use git to checkout the <code>5.8</code> branch.

==== Ubuntu <=14.04 LTS (Trusty), Debian <=8 (Jessie) ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Ubuntu. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Fedora ===

Current versions of Fedora work well out of the box. Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo dnf install git make cmake curl gcc gcc-c++ gtk3-devel gtkmm30-devel lensfun-devel librsvg2-devel lcms2-devel fftw-devel expat-devel libiptcdata-devel libtiff-devel libjpeg-turbo-devel libcanberra-devel libatomic</pre>

==== Fedora <=23 ====
RawTherapee 5.6 (release) is the latest version supported for this distribution because of a higher CMake version requirement (see [https://github.com/Beep6581/RawTherapee/issues/5302 here]). When compiling, follow the manual steps and use git to checkout the <code>5.6</code> branch.

==== Fedora 22 ====
In addition to the above notices and requirements, an updated version of <code>libtiff</code> needs to be compiled manually.

<pre style="white-space: pre-wrap">sudo yum install ninja-build
cd ~
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
cd tiff-4.0.9.tar.gz
mkdir build && cd build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

==== Fedora <=21 ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Fedora. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Gentoo/Sabayon ===

Sabayon users should use the same dependencies as for Gentoo, but instead of <code>sudo emerge -uva</code> use <code>sudo equo install sys-devel/gcc dev-vcs/git</code>.

<pre style="white-space: pre-wrap">sudo emerge -uva dev-cpp/gtkmm:3.0 dev-libs/expat dev-util/cmake media-gfx/exiv2 media-libs/lcms media-libs/lensfun media-libs/libcanberra media-libs/libiptcdata media-libs/libjpeg-turbo media-libs/libpng gnome-base/librsvg media-libs/tiff net-misc/curl sci-libs/fftw sys-libs/zlib x11-libs/gtk+:3</pre>

Proceed to [[#Compilation|Compilation]].

=== openSUSE ===

openSUSE Leap 15 and Tumbleweed should work well out of the box. Serious compilation issues can be expected with other versions. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 42.1.

<pre style="white-space: pre-wrap">sudo zypper install git cmake gcc gcc-c++ gtk3-devel gtkmm3-devel liblcms2-devel fftw3-devel libiptcdata-devel librsvg-devel libtiff-devel libjpeg8-devel libcanberra-gtk3-devel</pre>

For openSUSE 15.1 and newer, the <code>lensfun</code> library needs to be installed as follows:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-data liblensfun1</pre>

For openSUSE Tumbleweed, the package is slightly different:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-devel</pre>

For other versions of openSUSE <code>lensfun</code> has to be installed manually:

<pre>wget https://sourceforge.net/projects/lensfun/files/0.3.2/lensfun-0.3.2.tar.gz
tar xvf lensfun-0.3.2.tar.gz
cd lensfun-0.3.2.tar.gz
mkdir build
cd build
cmake ../
make
sudo make install</pre>

Proceed to [[#Compilation|Compilation]].

== Compilation ==

There are two general ways you can compile RawTherapee: either use the [[#The_Automatic_Way|automatic]] Bash script which compiles RawTherapee for you (recommended), or do so [[#The_Manual_Way|manually]].

=== The Automatic Way ===

This is the recommended way of compiling RawTherapee as it is fast, simple and fool-proof. It relies on a Bash script which downloads the latest RawTherapee source code and compiles it in a way which is optimized for your CPU. The compiled builds are ready for use. The script does not check for build-time dependencies, so be sure to read the [[#Dependencies|Dependencies]] section before using the script. The compiled builds are standalone, meaning that you can keep several versions of RawTherapee at the same time simply by renaming the build folders so that creating a new build does not overwrite the previous build, which happens by default.

Run the script as a normal user, not as root!

Open a terminal, get the script, make it executable, and run it:
<pre style="white-space: pre-wrap">cd ~
wget https://raw.githubusercontent.com/Beep6581/RawTherapee/dev/tools/build-rawtherapee -O build-rawtherapee
chmod +x build-rawtherapee
./build-rawtherapee</pre>

If everything goes well, the script will terminate with the message, "To run rawtherapee type: ...".

To update RawTherapee if you previously compiled it using this script, just re-run the script. That's it.

The <code>build-rawtherapee</code> script is included in RawTherapee's source code. Since running the script updates the source code, after you compiled your first build you can delete the script you downloaded manually above using wget, and instead use <code>~/programs/code-rawtherapee/tools/build-rawtherapee</code> which will always update itself.

The script compiles the current branch, which by default is <code>dev</code> where most of the development happens. To compile a different branch, check it out using standard git commands before running the script. Read more about RawTherapee's branches below in the [[Linux#Choose_a_branch|Choose a Branch]] section.

For more information, see <code>./build-rawtherapee --help</code>

You have finished, RawTherapee is ready for use. You can skip the "Manual Way" section.

=== The Manual Way ===

The recommended way of compiling RawTherapee is by using the automatic script - see [[#The_Automatic_Way|Compilation: The Automatic Way]]. If you want to learn how to compile manually, read on.

In order to keep your "home" folder clean when manually compiling multiple programs (i.e. when not using your distribution's package manager) and for this manual compilation tutorial to maintain compatibility with the automatic compilation script, you will create the folder <code>~/programs/</code> which will contain all RawTherapee-related source code in the <code>~/programs/code-rawtherapee</code> folder, and the compiled build in the <code>~/programs/rawtherapee</code> folder. You can use the same scheme when compiling other programs.

==== Clone the source ====

First, you need to clone RawTherapee's source code repository. Bring up your console and run this:

<pre style="white-space: pre-wrap">mkdir -p ~/programs
git clone https://github.com/Beep6581/RawTherapee ~/programs/code-rawtherapee
cd ~/programs/code-rawtherapee</pre>

==== Choose a branch ====

* Features are developed on their own feature branches.
* Development happens in the <code>dev</code> branch. Feature branches are merged into the <code>dev</code> branch when they're ready. The <code>dev</code> branch is unstable.
* Releases are tagged in the <code>releases</code> branch.

Checkout the latest tag if you want the most stable code. To see all available tags, type:
<pre style="white-space: pre-wrap">git tag</pre>

Checkout the <code>dev</code> branch or some other feature branch if you want to test the latest bleeding-edge code. To see all available branches, type:
<pre style="white-space: pre-wrap">git branch -a</pre>

Checking out is done via the "git checkout" command. To checkout a tag or a branch, type:
<pre style="white-space: pre-wrap">git checkout <tag or branch></pre>

RawTherapee uses GTK+ for the user interface and requires GTK+ version 3.16 or newer. If your system does not support version 3.16 or newer then you must checkout the <code>5.0-r1-gtk2</code> tag. Our GTK2 support has officially ended on 2 February 2017 - refer to the archived [[Linux_GTK2|GTK2]] article, and update your system.

Compiling old versions of RawTherapee will fail on a modern system, as you will be missing the old dependencies.

==== Compile RawTherapee ====

Now you will make an out-of-source compilation of RawTherapee, it will be built into the <code>~/programs/code-rawtherapee/build/release</code> folder, and then you will move this folder to <code>~/programs/rawtherapee</code>

===== CMake =====

There are a few compilation settings you need to be aware of, you will pass these to CMake using the <code>-D</code> option as described below:

; CMAKE_BUILD_TYPE
: One of: <code>release</code> (default), <code>relwithdebinfo</code> or <code>debug</code>.
: This controls whether the build will favor faster execution time or more verbose debugging output.
: The "debug" and "relwithdebinfo" builds will let you [[How_to_write_useful_bug_reports|get a useful stack-backtrace]] if RawTherapee crashes while running through GDB which you can then submit to us so we can find the problem and fix it. The "debug" build is the slowest but generates the most detailed information. The "relwithdebinfo" build is almost as fast as a "release" build and generates often sufficient information, though not as detailed as a "debug" build. The "release" build will not provide any useful information when it crashes, but does contain many speed optimizations resulting in a program that works several times faster than the "debug" build would. For normal use, make a "release" or "relwithdebinfo" build. If you find a reproducible bug, then make a "debug" build and send us a stack-backtrace (or fix it yourself and send us the patch!). We prefer stack backtraces from debug builds than from relwithdebinfo ones.
:: To make a "release" type build, set: <code>-DCMAKE_BUILD_TYPE="release"</code>

; USE_OLD_CXX_ABI
: <code>ON</code> or <code>OFF</code> (default).
: When compiling a program, one must use the same conventions as those used by the libraries which that program relies upon, otherwise compilation (linking) will fail. Generally one does not need to concern oneself with this, but we are now at a time when GCC4 is being phased out by GCC5, each by default using a convention incompatible with the other, and so this issue is relevant. If the libraries on your system have been compiled using GCC5, they probably use a standard called C++11. This means that your RawTherapee build must use the same standard, which is the case by default. However, if despite using GCC5 your libraries were built using the older C++03 standard, then RawTherapee must be set to use the same, and this is when you would set "USE_OLD_CXX_ABI" to "ON".
:: To enable USE_OLD_CXX_ABI, set: <code>-DUSE_OLD_CXX_ABI="ON"</code>

; CACHE_NAME_SUFFIX
: The CACHE_NAME_SUFFIX options sets the suffix of the cache and config folder names the compiled RawTherapee build will use. See the [[File Paths]] article for an explanation of what those are.
: For stable releases (if you checkout the "releases" branch) use <code>-DCACHE_NAME_SUFFIX=""</code>
: For development builds (if you checkout the "dev" branch or any branch other than "releases") use <code>-DCACHE_NAME_SUFFIX="5-dev"</code>

; PROC_TARGET_NUMBER
: From <code>0</code> (default) to <code>9</code>.
: The PROC_TARGET_NUMBER option sets which CPU type to optimize for.
: If building for yourself, use "2". It means "native", so the optimizations will be automatically detected for your CPU and RawTherapee will perform as fast as possible on your CPU. It might not run at all on older or other CPU architectures.
: If building for distribution (for other people), use "1". It means "generic", so only optimizations supported by most CPUs will be used, meaning the build can be downloaded and used by anyone, though it won't benefit from the best optimizations possible for the user's CPU.
: For more info, see the file "ProcessorTargets.cmake" in the cloned repository.
:: To make a build using "native" optimizations, set: <code>-DPROC_TARGET_NUMBER="2"</code>

; BUILD_BUNDLE
: <code>ON</code> or <code>OFF</code>.
: Forced to "ON" for Windows and macOS. Optional in Linux where it is "OFF" by default.
: If set to ON, the program will be built into the <code>DATADIR</code> folder, otherwise it will be installed relative to <code>CMAKE_INSTALL_PREFIX</code> which would typically be system-wide.

; BUNDLE_BASE_INSTALL_DIR
: Use an absolute path.
: The program will be built into this folder.
: For example, set it to: <code>-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee"</code>
: If it is not set, the default is to use <code>${CMAKE_BINARY_DIR}/${CMAKE_BUILD_TYPE}</code>

; LENSFUNDBDIR
: Unset by default.
: The <code>LENSFUNDBDIR</code> option permits to locate the lensfun database in the specified directory. It can be unset, absolute or relative.
: When unset, Lensfun uses its own logic to find the database. This is the recommended option if you have Lensfun installed system-wide and want to use it.
: You can set it to a relative or absolute path if you want to use a custom lensfun database.
: If building a bundle, it is relative to the bundle's root folder, otherwise it is relative to <code>DATADIR</code>, i.e. <code>${CMAKE_INSTALL_PREFIX}/share/rawtherapee</code>

; OPTION_OMP
: <code>ON</code> (default) or <code>OFF</code>.
: Build with OpenMP support when enabled, which enables multithreading and makes RawTherapee much faster.

; WITH_LTO
: <code>ON</code> or <code>OFF</code> (default).
: Build with link-time optimizations when enabled, which may make RawTherapee run a little faster.

; WITH_PROF
: <code>ON</code> or <code>OFF</code> (default).
: For debugging purposes. Generate extra code to write profile information suitable for the analysis program gprof.

; WITH_SAN
: <code>OFF</code> (default) or one of various other options.
: For debugging purposes. Allows enabling various sanitizers to help detect program issues.
: See GCC manual's [https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html Program Instrumentation Options] chapter for more information.

; WITH_SYSTEM_KLT
: <code>ON</code> or <code>OFF</code> (default).
: Build using system KLT library when ON, otherwise use KLT files bundled with RawTherapee.
: The Kanade–Lucas–Tomasi (KLT) feature tracker is used by the [[Lens/Geometry#Distortion_Correction|Auto Distortion Correction]] tool.

; WITH_BENCHMARK
: <code>ON</code> or <code>OFF</code> (default).
: Build with timing functions enabled to benchmark performance.

; ENABLE_TCMALLOC
: <code>ON</code> or <code>OFF</code> (default).
: In some cases the operating system has trouble handling memory allocation and deallocation required by RawTherapee (see [https://github.com/Beep6581/RawTherapee/issues/5459 here] for more information). Linking against [https://gperftools.github.io/gperftools/tcmalloc.html TCMalloc] may alleviate these problems. This library may not be available on all platforms or distributions.

===== Make =====

Find out how many threads your CPU supports. This only influences the compilation speed, it has no influence over how fast the compiled RawTherapee build runs. To find out how many threads your CPU supports, run this in a terminal:
<pre style="white-space: pre-wrap">nproc --all</pre>
It will return a number. Use this number for the <code>--jobs</code> parameter below.

Compile:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
mkdir build
cd build

cmake \
-DCMAKE_BUILD_TYPE="release" \
-DCACHE_NAME_SUFFIX="5-dev" \
-DPROC_TARGET_NUMBER="2" \
-DBUILD_BUNDLE="ON" \
-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee" \
-DOPTION_OMP="ON" \
-DWITH_LTO="OFF" \
-DWITH_PROF="OFF" \
-DWITH_SAN="OFF" \
-DWITH_SYSTEM_KLT="OFF" \
..

make --jobs=4
make install
</pre>

==== Run RawTherapee ====

To run RawTherapee:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee</pre>
Or to run the CLI version:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee-cli</pre>

The source code repository is in <code>~/programs/code-rawtherapee</code> and the compiled program is in <code>~/programs/rawtherapee</code>

You can safely delete <code>~/programs/code-rawtherapee</code> if you so wish. The compiled program will still work, but then you will have to redo all the above steps if you want to update. Rather, leave the repository intact so that you can do the next step in a week or a month's time when you want to update.

==== Update RawTherapee ====

Every time you want to update RawTherapee to the latest code available, just do the following:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
git pull</pre>

Then repeat the [[#Make|Make]] step above.

When updating, you can re-use the <code>build</code> folder from last time to avoid having to recompile things which have not changed, to make the whole process faster. CMake should automatically detect changes. However, there are situations when compilation may fail when re-using an old <code>build</code> folder - typically that might happen when hopping between very different branches. If that happens, just delete the <code>build</code> folder, then proceed with the steps in the "Make" section.

Linux

2022-11-05T07:54:10Z

Thanatomanic: Minor change

<div class="pagetitle">Linux</div>

This page details instructions for compiling RawTherapee on '''GNU/Linux''' systems. There are also instructions for compiling on [[Windows]] and [[macOS]].

When in doubt, [[IRC|join us on IRC]] or in the [[Forum]] and ask a human!

== Dependencies ==

To compile RawTherapee your system will need a set of tools and code libraries from other programs. These are called dependencies, and here is a list of them for the latest version of RawTherapee:

{| class="wikitable sortable"
|+ Build-time dependencies for RawTherapee:
! Package !! Version !! URL
|-
| CMake || cmake>=3.5 || https://cmake.org/
|-
| EXIV2 || exiv2>=0.19 || http://www.exiv2.org/
|-
| EXPAT || expat>=2.1.0 || https://libexpat.github.io/
|-
| FFTW3 || fftw>=3.2.2 || http://fftw.org/
|-
| GCC || gcc>=4.9 || https://gcc.gnu.org/
|-
| GLIB2 || glib-2.0>=2.24 || https://www.gtk.org/
|-
| GLIBMM || glibmm-2.4>=2.24 || https://www.gtkmm.org/
|-
| GTK+ || gtk+-3.16 < 3.24.0 || https://www.gtk.org/
|-
| GTKMM || gtkmm-3.16 || https://www.gtkmm.org/
|-
| JPEG || libjpeg>=6b || https://libjpeg-turbo.org/ https://jpegclub.org/ https://www.ijg.org/
|-
| LCMS2 || lcms>=2.6 || https://www.littlecms.com/
|-
| LENSFUN || lensfun>=0.2 || https://github.com/lensfun/lensfun
|-
| LIBCANBERRA || libcanberra>=0.29 || http://0pointer.de/lennart/projects/libcanberra/ (Linux only)
|-
| LIBIPTCDATA || libiptcdata>=1.0.2 || http://libiptcdata.sourceforge.net
|-
| PNG || libpng>=1.2.44 || http://www.libpng.org/
|-
| librsvg || librsvg>=2.40 || https://github.com/GNOME/librsvg
|-
| SIGC || sigc++-2.0 || https://github.com/libsigcplusplus/libsigcplusplus
|-
| TIFF || libtiff>=4.0.4 || http://libtiff.org/
|-
| ZLIB || zlib>=1.2.3 || http://www.zlib.net/
|}

In order to install all these dependencies, you will need to open a console and paste the code from the appropriate section into the console.

The code snippets below list dependencies for the latest RawTherapee code which requires GTK3. We dropped support for GTK2 with release "5.0-r1-gtk2" in February 2017. If you use a modern distribution, just copy and paste the code snippets as they are. If you're on an old distribution without the required GTK3 support, then refer to the archived [[Linux_GTK2|GTK2]] article, then checkout and compile the obsolete <code>5.0-r1-gtk2</code> tag.

=== Arch/Manjaro ===

Current versions of Arch and Manjaro work well out of the box. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 17.1.12.

<pre style="white-space: pre-wrap">sudo pacman -S cmake ninja exiv2 expat fftw glib2 glibmm gtk3 gtkmm3 lcms2 lensfun libcanberra libiptcdata libjpeg-turbo libpng librsvg libsigc++ libtiff zlib</pre>

For Manjaro, you may need to additionally install the <code>pkg-config</code> package.

Proceed to [[#Compilation|Compilation]].

=== CentOS ===

CentOS 7 has very outdated packages and requires extra steps to install a recent GCC, git, lensfun and libtiff. The steps below were verified to work in CentOS 7.4.1708, but proceed at your own risk.

GCC >=4.9.3:
<pre style="white-space: pre-wrap">sudo yum update
sudo yum install cmake git
sudo yum install centos-release-scl
sudo yum install devtoolset-7-gcc*
scl enable devtoolset-7 bash
source /opt/rh/devtoolset-7/enable</pre>

git >=2.7:
<pre style="white-space: pre-wrap">sudo yum install http://opensource.wandisco.com/centos/7/git/x86_64/wandisco-git-release-7-2.noarch.rpm</pre>

lensfun:
<pre style="white-space: pre-wrap">
wget http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -ivh epel-release-latest-7.noarch.rpm</pre>

libtiff >=4.0.4:
<pre style="white-space: pre-wrap">sudo yum install ninja-build
mkdir ~/programs && cd ~/programs
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
mkdir tiff-4.0.9/libtiff-build && cd tiff-4.0.9/libtiff-build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

Install the other dependencies:
<pre style="white-space: pre-wrap">sudo yum install curl expat-devel fftw-devel gtk3-devel gtkmm30-devel lcms2-devel lensfun-devel libcanberra-devel libiptcdata-devel libjpeg-turbo-devel libpng-devel librsvg2-devel zlib-devel</pre>

Symlink libatomic:
<pre style="white-space: pre-wrap">sudo ln -s /usr/lib64/libatomic.so.1 /usr/lib64/libatomic.so</pre>

As you proceed to the next step - compilation - you will need to edit the <code>build-rawtherapee</code> script and add these three lines to the CMake section near the end of the file, for example after the "-DWITH_BENCHMARK" line before the "$HOME" line:
<pre style="white-space: pre-wrap"> -DTIFF_INCLUDE_DIR="$HOME/programs/tiff-4.0.9/libtiff" \
-DTIFF_LIBRARY="$HOME/programs/tiff-4.0.9/libtiff-build/libtiff/libtiff.so" \
-DCMAKE_CXX_FLAGS="-Wno-deprecated -Wno-parentheses" \
</pre>

Proceed to [[#Compilation|Compilation]].

=== Debian/Ubuntu/Mint/elementary OS ===

Current versions of these distributions work well out of the box (Debian >=9, Ubuntu >=18.04 LTS, Linux Mint >=19, elementary OS >=5). Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo apt install git build-essential cmake curl pkg-config libgtk-3-dev libgtkmm-3.0-dev liblensfun-dev librsvg2-dev liblcms2-dev libfftw3-dev libiptcdata0-dev libtiff5-dev libcanberra-gtk3-dev</pre>

==== Ubuntu 16.04 LTS (Xenial) ====
RawTherapee 5.8 (release) is the latest version supported for Xenial-based distributions. See [https://github.com/Beep6581/RawTherapee/issues/5943 here] for details. When compiling, follow the manual steps and use git to checkout the <code>5.8</code> branch.

==== Ubuntu <=14.04 LTS (Trusty), Debian <=8 (Jessie) ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Ubuntu. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Fedora ===

Current versions of Fedora work well out of the box. Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo dnf install git make cmake curl gcc gcc-c++ gtk3-devel gtkmm30-devel lensfun-devel librsvg2-devel lcms2-devel fftw-devel expat-devel libiptcdata-devel libtiff-devel libjpeg-turbo-devel libcanberra-devel libatomic</pre>

==== Fedora <=23 ====
RawTherapee 5.6 (release) is the latest version supported for this distribution because of a higher CMake version requirement (see [https://github.com/Beep6581/RawTherapee/issues/5302 here]). When compiling, follow the manual steps and use git to checkout the <code>5.6</code> branch.

==== Fedora 22 ====
In addition to the above notices and requirements, an updated version of <code>libtiff</code> needs to be compiled manually.

<pre style="white-space: pre-wrap">sudo yum install ninja-build
cd ~
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
cd tiff-4.0.9.tar.gz
mkdir build && cd build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

==== Fedora <=21 ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Fedora. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Gentoo/Sabayon ===

Sabayon users should use the same dependencies as for Gentoo, but instead of <code>sudo emerge -uva</code> use <code>sudo equo install sys-devel/gcc dev-vcs/git</code>.

<pre style="white-space: pre-wrap">sudo emerge -uva dev-cpp/gtkmm:3.0 dev-libs/expat dev-util/cmake media-gfx/exiv2 media-libs/lcms media-libs/lensfun media-libs/libcanberra media-libs/libiptcdata media-libs/libjpeg-turbo media-libs/libpng gnome-base/librsvg media-libs/tiff net-misc/curl sci-libs/fftw sys-libs/zlib x11-libs/gtk+:3</pre>

Proceed to [[#Compilation|Compilation]].

=== openSUSE ===

openSUSE Leap 15 and Tumbleweed should work well out of the box. Serious compilation issues can be expected with other versions. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 42.1.

<pre style="white-space: pre-wrap">sudo zypper install git cmake gcc gcc-c++ gtk3-devel gtkmm3-devel liblcms2-devel fftw3-devel libiptcdata-devel librsvg-devel libtiff-devel libjpeg8-devel libcanberra-gtk3-devel</pre>

For openSUSE 15.1 and newer, the <code>lensfun</code> library needs to be installed as follows:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-data liblensfun1</pre>

For openSUSE Tumbleweed, the package is slightly different:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-devel</pre>

For other versions of openSUSE <code>lensfun</code> has to be installed manually:

<pre>wget https://sourceforge.net/projects/lensfun/files/0.3.2/lensfun-0.3.2.tar.gz
tar xvf lensfun-0.3.2.tar.gz
cd lensfun-0.3.2.tar.gz
mkdir build
cd build
cmake ../
make
sudo make install</pre>

Proceed to [[#Compilation|Compilation]].

== Compilation ==

There are two general ways you can compile RawTherapee: either use the [[#The_Automatic_Way|automatic]] Bash script which compiles RawTherapee for you (recommended), or do so [[#The_Manual_Way|manually]].

=== The Automatic Way ===

This is the recommended way of compiling RawTherapee as it is fast, simple and fool-proof. It relies on a Bash script which downloads the latest RawTherapee source code and compiles it in a way which is optimized for your CPU. The compiled builds are ready for use. The script does not check for build-time dependencies, so be sure to read the [[#Dependencies|Dependencies]] section before using the script. The compiled builds are standalone, meaning that you can keep several versions of RawTherapee at the same time simply by renaming the build folders so that creating a new build does not overwrite the previous build, which happens by default.

Run the script as a normal user, not as root!

Open a terminal, get the script, make it executable, and run it:
<pre style="white-space: pre-wrap">cd ~
wget https://raw.githubusercontent.com/Beep6581/RawTherapee/dev/tools/build-rawtherapee -O build-rawtherapee
chmod +x build-rawtherapee
./build-rawtherapee</pre>

If everything goes well, the script will terminate with the message, "To run rawtherapee type: ...".

To update RawTherapee if you previously compiled it using this script, just re-run the script. That's it.

The <code>build-rawtherapee</code> script is included in RawTherapee's source code. Since running the script updates the source code, after you compiled your first build you can delete the script you downloaded manually above using wget, and instead use <code>~/programs/code-rawtherapee/tools/build-rawtherapee</code> which will always update itself.

The script compiles the current branch, which by default is <code>dev</code> where most of the development happens. To compile a different branch, check it out using standard git commands before running the script. Read more about RawTherapee's branches below in the [[Linux#Choose_a_branch|Choose a Branch]] section.

For more information, see <code>./build-rawtherapee --help</code>

You have finished, RawTherapee is ready for use. You can skip the "Manual Way" section.

=== The Manual Way ===

The recommended way of compiling RawTherapee is by using the automatic script - see [[#The_Automatic_Way|Compilation: The Automatic Way]]. If you want to learn how to compile manually, read on.

In order to keep your "home" folder clean when manually compiling multiple programs (i.e. when not using your distribution's package manager) and for this manual compilation tutorial to maintain compatibility with the automatic compilation script, you will create the folder <code>~/programs/</code> which will contain all RawTherapee-related source code in the <code>~/programs/code-rawtherapee</code> folder, and the compiled build in the <code>~/programs/rawtherapee</code> folder. You can use the same scheme when compiling other programs.

==== Clone the source ====

First, you need to clone RawTherapee's source code repository. Bring up your console and run this:

<pre style="white-space: pre-wrap">mkdir -p ~/programs
git clone https://github.com/Beep6581/RawTherapee ~/programs/code-rawtherapee
cd ~/programs/code-rawtherapee</pre>

==== Choose a branch ====

* Features are developed on their own feature branches.
* Development happens in the <code>dev</code> branch. Feature branches are merged into the <code>dev</code> branch when they're ready. The <code>dev</code> branch is unstable.
* Releases are tagged in the <code>releases</code> branch.

Checkout the latest tag if you want the most stable code. To see all available tags, type:
<pre style="white-space: pre-wrap">git tag</pre>

Checkout the <code>dev</code> branch or some other feature branch if you want to test the latest bleeding-edge code. To see all available branches, type:
<pre style="white-space: pre-wrap">git branch -a</pre>

Checking out is done via the "git checkout" command. To checkout a tag or a branch, type:
<pre style="white-space: pre-wrap">git checkout <tag or branch></pre>

RawTherapee uses GTK+ for the user interface and requires GTK+ version 3.16 or newer. If your system does not support version 3.16 or newer then you must checkout the <code>5.0-r1-gtk2</code> tag. Our GTK2 support has officially ended on 2 February 2017 - refer to the archived [[Linux_GTK2|GTK2]] article, and update your system.

Compiling old versions of RawTherapee will fail on a modern system, as you will be missing the old dependencies.

==== Compile RawTherapee ====

Now you will make an out-of-source compilation of RawTherapee, it will be built into the <code>~/programs/code-rawtherapee/build/release</code> folder, and then you will move this folder to <code>~/programs/rawtherapee</code>

===== CMake =====

There are a few compilation settings you need to be aware of, you will pass these to CMake using the <code>-D</code> option as described below:

; CMAKE_BUILD_TYPE
: One of: <code>release</code> (default), <code>relwithdebinfo</code> or <code>debug</code>.
: This controls whether the build will favor faster execution time or more verbose debugging output.
: The "debug" and "relwithdebinfo" builds will let you [[How_to_write_useful_bug_reports|get a useful stack-backtrace]] if RawTherapee crashes while running through GDB which you can then submit to us so we can find the problem and fix it. The "debug" build is the slowest but generates the most detailed information. The "relwithdebinfo" build is almost as fast as a "release" build and generates often sufficient information, though not as detailed as a "debug" build. The "release" build will not provide any useful information when it crashes, but does contain many speed optimizations resulting in a program that works several times faster than the "debug" build would. For normal use, make a "release" or "relwithdebinfo" build. If you find a reproducible bug, then make a "debug" build and send us a stack-backtrace (or fix it yourself and send us the patch!). We prefer stack backtraces from debug builds than from relwithdebinfo ones.
:: To make a "release" type build, set: <code>-DCMAKE_BUILD_TYPE="release"</code>

; USE_OLD_CXX_ABI
: <code>ON</code> or <code>OFF</code> (default).
: When compiling a program, one must use the same conventions as those used by the libraries which that program relies upon, otherwise compilation (linking) will fail. Generally one does not need to concern oneself with this, but we are now at a time when GCC4 is being phased out by GCC5, each by default using a convention incompatible with the other, and so this issue is relevant. If the libraries on your system have been compiled using GCC5, they probably use a standard called C++11. This means that your RawTherapee build must use the same standard, which is the case by default. However, if despite using GCC5 your libraries were built using the older C++03 standard, then RawTherapee must be set to use the same, and this is when you would set "USE_OLD_CXX_ABI" to "ON".
:: To enable USE_OLD_CXX_ABI, set: <code>-DUSE_OLD_CXX_ABI="ON"</code>

; CACHE_NAME_SUFFIX
: The CACHE_NAME_SUFFIX options sets the suffix of the cache and config folder names the compiled RawTherapee build will use. See the [[File Paths]] article for an explanation of what those are.
: For stable releases (if you checkout the "releases" branch) use <code>-DCACHE_NAME_SUFFIX=""</code>
: For development builds (if you checkout the "dev" branch or any branch other than "releases") use <code>-DCACHE_NAME_SUFFIX="5-dev"</code>

; PROC_TARGET_NUMBER
: From <code>0</code> (default) to <code>9</code>.
: The PROC_TARGET_NUMBER option sets which CPU type to optimize for.
: If building for yourself, use "2". It means "native", so the optimizations will be automatically detected for your CPU and RawTherapee will perform as fast as possible on your CPU. It might not run at all on older or other CPU architectures.
: If building for distribution (for other people), use "1". It means "generic", so only optimizations supported by most CPUs will be used, meaning the build can be downloaded and used by anyone, though it won't benefit from the best optimizations possible for the user's CPU.
: For more info, see the file "ProcessorTargets.cmake" in the cloned repository.
:: To make a build using "native" optimizations, set: <code>-DPROC_TARGET_NUMBER="2"</code>

; BUILD_BUNDLE
: <code>ON</code> or <code>OFF</code>.
: Forced to "ON" for Windows and macOS. Optional in Linux where it is "OFF" by default.
: If set to ON, the program will be built into the <code>DATADIR</code> folder, otherwise it will be installed relative to <code>CMAKE_INSTALL_PREFIX</code> which would typically be system-wide.

; BUNDLE_BASE_INSTALL_DIR
: Use an absolute path.
: The program will be built into this folder.
: For example, set it to: <code>-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee"</code>
: If it is not set, the default is to use <code>${CMAKE_BINARY_DIR}/${CMAKE_BUILD_TYPE}</code>

; LENSFUNDBDIR
: Unset by default.
: The <code>LENSFUNDBDIR</code> option permits to locate the lensfun database in the specified directory. It can be unset, absolute or relative.
: When unset, Lensfun uses its own logic to find the database. This is the recommended option if you have Lensfun installed system-wide and want to use it.
: You can set it to a relative or absolute path if you want to use a custom lensfun database.
: If building a bundle, it is relative to the bundle's root folder, otherwise it is relative to <code>DATADIR</code>, i.e. <code>${CMAKE_INSTALL_PREFIX}/share/rawtherapee</code>

; OPTION_OMP
: <code>ON</code> (default) or <code>OFF</code>.
: Build with OpenMP support when enabled, which enables multithreading and makes RawTherapee much faster.

; WITH_LTO
: <code>ON</code> or <code>OFF</code> (default).
: Build with link-time optimizations when enabled, which may make RawTherapee run a little faster.

; WITH_PROF
: <code>ON</code> or <code>OFF</code> (default).
: For debugging purposes. Generate extra code to write profile information suitable for the analysis program gprof.

; WITH_SAN
: <code>OFF</code> (default) or one of various other options.
: For debugging purposes. Allows enabling various sanitizers to help detect program issues.
: See GCC manual's [https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html Program Instrumentation Options] chapter for more information.

; WITH_SYSTEM_KLT
: <code>ON</code> or <code>OFF</code> (default).
: Build using system KLT library when ON, otherwise use KLT files bundled with RawTherapee.
: The Kanade–Lucas–Tomasi (KLT) feature tracker is used by the [[Lens/Geometry#Distortion_Correction|Auto Distortion Correction]] tool.

; WITH_BENCHMARK
: <code>ON</code> or <code>OFF</code> (default).
: Build with timing functions enabled to benchmark performance.

; ENABLE_TCMALLOC
: <code>ON</code> or <code>OFF</code> (default).
: In some cases the operating system has trouble handling memory allocation and deallocation required by RawTherapee (see [https://github.com/Beep6581/RawTherapee/issues/5459 here] for more information). Linking against [https://gperftools.github.io/gperftools/tcmalloc.html TCMalloc] may alleviate these problems. This library may not be available on all platforms or distributions.

===== Make =====

Find out how many threads your CPU supports. This only influences the compilation speed, it has no influence over how fast the compiled RawTherapee build runs. To find out how many threads your CPU supports, run this in a terminal:
<pre style="white-space: pre-wrap">nproc --all</pre>
It will return a number. Use this number for the <code>--jobs</code> parameter below.

Compile:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
mkdir build
cd build

cmake \
-DCMAKE_BUILD_TYPE="release" \
-DCACHE_NAME_SUFFIX="5-dev" \
-DPROC_TARGET_NUMBER="2" \
-DBUILD_BUNDLE="ON" \
-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee" \
-DOPTION_OMP="ON" \
-DWITH_LTO="OFF" \
-DWITH_PROF="OFF" \
-DWITH_SAN="OFF" \
-DWITH_SYSTEM_KLT="OFF" \
..

make --jobs=4
make install
</pre>

==== Run RawTherapee ====

To run RawTherapee:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee</pre>
Or to run the CLI version:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee-cli</pre>

The source code repository is in <code>~/programs/code-rawtherapee</code> and the compiled program is in <code>~/programs/rawtherapee</code>

You can safely delete <code>~/programs/code-rawtherapee</code> if you so wish. The compiled program will still work, but then you will have to redo all the above steps if you want to update. Rather, leave the repository intact so that you can do the next step in a week or a month's time when you want to update.

==== Update RawTherapee ====

Every time you want to update RawTherapee to the latest code available, just do the following:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
git pull</pre>

Then repeat the [[#Make|Make]] step above.

When updating, you can re-use the <code>build</code> folder from last time to avoid having to recompile things which have not changed, to make the whole process faster. CMake should automatically detect changes. However, there are situations when compilation may fail when re-using an old <code>build</code> folder - typically that might happen when hopping between very different branches. If that happens, just delete the <code>build</code> folder, then proceed with the steps in the "Make" section.

Linux

2022-11-05T07:52:03Z

Thanatomanic: Update Manjaro to include pkg-config; include ninja for easier building

<div class="pagetitle">Linux</div>

This page details instructions for compiling RawTherapee on '''GNU/Linux''' systems. There are also instructions for compiling on [[Windows]] and [[macOS]].

When in doubt, [[IRC|join us on IRC]] or in the [[Forum]] and ask a human!

== Dependencies ==

To compile RawTherapee your system will need a set of tools and code libraries from other programs. These are called dependencies, and here is a list of them for the latest version of RawTherapee:

{| class="wikitable sortable"
|+ Build-time dependencies for RawTherapee:
! Package !! Version !! URL
|-
| CMake || cmake>=3.5 || https://cmake.org/
|-
| EXIV2 || exiv2>=0.19 || http://www.exiv2.org/
|-
| EXPAT || expat>=2.1.0 || https://libexpat.github.io/
|-
| FFTW3 || fftw>=3.2.2 || http://fftw.org/
|-
| GCC || gcc>=4.9 || https://gcc.gnu.org/
|-
| GLIB2 || glib-2.0>=2.24 || https://www.gtk.org/
|-
| GLIBMM || glibmm-2.4>=2.24 || https://www.gtkmm.org/
|-
| GTK+ || gtk+-3.16 < 3.24.0 || https://www.gtk.org/
|-
| GTKMM || gtkmm-3.16 || https://www.gtkmm.org/
|-
| JPEG || libjpeg>=6b || https://libjpeg-turbo.org/ https://jpegclub.org/ https://www.ijg.org/
|-
| LCMS2 || lcms>=2.6 || https://www.littlecms.com/
|-
| LENSFUN || lensfun>=0.2 || https://github.com/lensfun/lensfun
|-
| LIBCANBERRA || libcanberra>=0.29 || http://0pointer.de/lennart/projects/libcanberra/ (Linux only)
|-
| LIBIPTCDATA || libiptcdata>=1.0.2 || http://libiptcdata.sourceforge.net
|-
| PNG || libpng>=1.2.44 || http://www.libpng.org/
|-
| librsvg || librsvg>=2.40 || https://github.com/GNOME/librsvg
|-
| SIGC || sigc++-2.0 || https://github.com/libsigcplusplus/libsigcplusplus
|-
| TIFF || libtiff>=4.0.4 || http://libtiff.org/
|-
| ZLIB || zlib>=1.2.3 || http://www.zlib.net/
|}

In order to install all these dependencies, you will need to open a console and paste the code from the appropriate section into the console.

The code snippets below list dependencies for the latest RawTherapee code which requires GTK3. We dropped support for GTK2 with release "5.0-r1-gtk2" in February 2017. If you use a modern distribution, just copy and paste the code snippets as they are. If you're on an old distribution without the required GTK3 support, then refer to the archived [[Linux_GTK2|GTK2]] article, then checkout and compile the obsolete <code>5.0-r1-gtk2</code> tag.

=== Arch/Manjaro ===

Current versions of Arch and Manjaro work well out of the box. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 17.1.12.

<pre style="white-space: pre-wrap">sudo pacman -S --needed cmake ninja exiv2 expat fftw glib2 glibmm gtk3 gtkmm3 lcms2 lensfun libcanberra libiptcdata libjpeg-turbo libpng librsvg libsigc++ libtiff zlib</pre>

For Manjaro, you may need to additionally install the <pre>pkg-config</pre> package.

Proceed to [[#Compilation|Compilation]].

=== CentOS ===

CentOS 7 has very outdated packages and requires extra steps to install a recent GCC, git, lensfun and libtiff. The steps below were verified to work in CentOS 7.4.1708, but proceed at your own risk.

GCC >=4.9.3:
<pre style="white-space: pre-wrap">sudo yum update
sudo yum install cmake git
sudo yum install centos-release-scl
sudo yum install devtoolset-7-gcc*
scl enable devtoolset-7 bash
source /opt/rh/devtoolset-7/enable</pre>

git >=2.7:
<pre style="white-space: pre-wrap">sudo yum install http://opensource.wandisco.com/centos/7/git/x86_64/wandisco-git-release-7-2.noarch.rpm</pre>

lensfun:
<pre style="white-space: pre-wrap">
wget http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -ivh epel-release-latest-7.noarch.rpm</pre>

libtiff >=4.0.4:
<pre style="white-space: pre-wrap">sudo yum install ninja-build
mkdir ~/programs && cd ~/programs
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
mkdir tiff-4.0.9/libtiff-build && cd tiff-4.0.9/libtiff-build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

Install the other dependencies:
<pre style="white-space: pre-wrap">sudo yum install curl expat-devel fftw-devel gtk3-devel gtkmm30-devel lcms2-devel lensfun-devel libcanberra-devel libiptcdata-devel libjpeg-turbo-devel libpng-devel librsvg2-devel zlib-devel</pre>

Symlink libatomic:
<pre style="white-space: pre-wrap">sudo ln -s /usr/lib64/libatomic.so.1 /usr/lib64/libatomic.so</pre>

As you proceed to the next step - compilation - you will need to edit the <code>build-rawtherapee</code> script and add these three lines to the CMake section near the end of the file, for example after the "-DWITH_BENCHMARK" line before the "$HOME" line:
<pre style="white-space: pre-wrap"> -DTIFF_INCLUDE_DIR="$HOME/programs/tiff-4.0.9/libtiff" \
-DTIFF_LIBRARY="$HOME/programs/tiff-4.0.9/libtiff-build/libtiff/libtiff.so" \
-DCMAKE_CXX_FLAGS="-Wno-deprecated -Wno-parentheses" \
</pre>

Proceed to [[#Compilation|Compilation]].

=== Debian/Ubuntu/Mint/elementary OS ===

Current versions of these distributions work well out of the box (Debian >=9, Ubuntu >=18.04 LTS, Linux Mint >=19, elementary OS >=5). Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo apt install git build-essential cmake curl pkg-config libgtk-3-dev libgtkmm-3.0-dev liblensfun-dev librsvg2-dev liblcms2-dev libfftw3-dev libiptcdata0-dev libtiff5-dev libcanberra-gtk3-dev</pre>

==== Ubuntu 16.04 LTS (Xenial) ====
RawTherapee 5.8 (release) is the latest version supported for Xenial-based distributions. See [https://github.com/Beep6581/RawTherapee/issues/5943 here] for details. When compiling, follow the manual steps and use git to checkout the <code>5.8</code> branch.

==== Ubuntu <=14.04 LTS (Trusty), Debian <=8 (Jessie) ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Ubuntu. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Fedora ===

Current versions of Fedora work well out of the box. Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo dnf install git make cmake curl gcc gcc-c++ gtk3-devel gtkmm30-devel lensfun-devel librsvg2-devel lcms2-devel fftw-devel expat-devel libiptcdata-devel libtiff-devel libjpeg-turbo-devel libcanberra-devel libatomic</pre>

==== Fedora <=23 ====
RawTherapee 5.6 (release) is the latest version supported for this distribution because of a higher CMake version requirement (see [https://github.com/Beep6581/RawTherapee/issues/5302 here]). When compiling, follow the manual steps and use git to checkout the <code>5.6</code> branch.

==== Fedora 22 ====
In addition to the above notices and requirements, an updated version of <code>libtiff</code> needs to be compiled manually.

<pre style="white-space: pre-wrap">sudo yum install ninja-build
cd ~
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
cd tiff-4.0.9.tar.gz
mkdir build && cd build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

==== Fedora <=21 ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Fedora. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Gentoo/Sabayon ===

Sabayon users should use the same dependencies as for Gentoo, but instead of <code>sudo emerge -uva</code> use <code>sudo equo install sys-devel/gcc dev-vcs/git</code>.

<pre style="white-space: pre-wrap">sudo emerge -uva dev-cpp/gtkmm:3.0 dev-libs/expat dev-util/cmake media-gfx/exiv2 media-libs/lcms media-libs/lensfun media-libs/libcanberra media-libs/libiptcdata media-libs/libjpeg-turbo media-libs/libpng gnome-base/librsvg media-libs/tiff net-misc/curl sci-libs/fftw sys-libs/zlib x11-libs/gtk+:3</pre>

Proceed to [[#Compilation|Compilation]].

=== openSUSE ===

openSUSE Leap 15 and Tumbleweed should work well out of the box. Serious compilation issues can be expected with other versions. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 42.1.

<pre style="white-space: pre-wrap">sudo zypper install git cmake gcc gcc-c++ gtk3-devel gtkmm3-devel liblcms2-devel fftw3-devel libiptcdata-devel librsvg-devel libtiff-devel libjpeg8-devel libcanberra-gtk3-devel</pre>

For openSUSE 15.1 and newer, the <code>lensfun</code> library needs to be installed as follows:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-data liblensfun1</pre>

For openSUSE Tumbleweed, the package is slightly different:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-devel</pre>

For other versions of openSUSE <code>lensfun</code> has to be installed manually:

<pre>wget https://sourceforge.net/projects/lensfun/files/0.3.2/lensfun-0.3.2.tar.gz
tar xvf lensfun-0.3.2.tar.gz
cd lensfun-0.3.2.tar.gz
mkdir build
cd build
cmake ../
make
sudo make install</pre>

Proceed to [[#Compilation|Compilation]].

== Compilation ==

There are two general ways you can compile RawTherapee: either use the [[#The_Automatic_Way|automatic]] Bash script which compiles RawTherapee for you (recommended), or do so [[#The_Manual_Way|manually]].

=== The Automatic Way ===

This is the recommended way of compiling RawTherapee as it is fast, simple and fool-proof. It relies on a Bash script which downloads the latest RawTherapee source code and compiles it in a way which is optimized for your CPU. The compiled builds are ready for use. The script does not check for build-time dependencies, so be sure to read the [[#Dependencies|Dependencies]] section before using the script. The compiled builds are standalone, meaning that you can keep several versions of RawTherapee at the same time simply by renaming the build folders so that creating a new build does not overwrite the previous build, which happens by default.

Run the script as a normal user, not as root!

Open a terminal, get the script, make it executable, and run it:
<pre style="white-space: pre-wrap">cd ~
wget https://raw.githubusercontent.com/Beep6581/RawTherapee/dev/tools/build-rawtherapee -O build-rawtherapee
chmod +x build-rawtherapee
./build-rawtherapee</pre>

If everything goes well, the script will terminate with the message, "To run rawtherapee type: ...".

To update RawTherapee if you previously compiled it using this script, just re-run the script. That's it.

The <code>build-rawtherapee</code> script is included in RawTherapee's source code. Since running the script updates the source code, after you compiled your first build you can delete the script you downloaded manually above using wget, and instead use <code>~/programs/code-rawtherapee/tools/build-rawtherapee</code> which will always update itself.

The script compiles the current branch, which by default is <code>dev</code> where most of the development happens. To compile a different branch, check it out using standard git commands before running the script. Read more about RawTherapee's branches below in the [[Linux#Choose_a_branch|Choose a Branch]] section.

For more information, see <code>./build-rawtherapee --help</code>

You have finished, RawTherapee is ready for use. You can skip the "Manual Way" section.

=== The Manual Way ===

The recommended way of compiling RawTherapee is by using the automatic script - see [[#The_Automatic_Way|Compilation: The Automatic Way]]. If you want to learn how to compile manually, read on.

In order to keep your "home" folder clean when manually compiling multiple programs (i.e. when not using your distribution's package manager) and for this manual compilation tutorial to maintain compatibility with the automatic compilation script, you will create the folder <code>~/programs/</code> which will contain all RawTherapee-related source code in the <code>~/programs/code-rawtherapee</code> folder, and the compiled build in the <code>~/programs/rawtherapee</code> folder. You can use the same scheme when compiling other programs.

==== Clone the source ====

First, you need to clone RawTherapee's source code repository. Bring up your console and run this:

<pre style="white-space: pre-wrap">mkdir -p ~/programs
git clone https://github.com/Beep6581/RawTherapee ~/programs/code-rawtherapee
cd ~/programs/code-rawtherapee</pre>

==== Choose a branch ====

* Features are developed on their own feature branches.
* Development happens in the <code>dev</code> branch. Feature branches are merged into the <code>dev</code> branch when they're ready. The <code>dev</code> branch is unstable.
* Releases are tagged in the <code>releases</code> branch.

Checkout the latest tag if you want the most stable code. To see all available tags, type:
<pre style="white-space: pre-wrap">git tag</pre>

Checkout the <code>dev</code> branch or some other feature branch if you want to test the latest bleeding-edge code. To see all available branches, type:
<pre style="white-space: pre-wrap">git branch -a</pre>

Checking out is done via the "git checkout" command. To checkout a tag or a branch, type:
<pre style="white-space: pre-wrap">git checkout <tag or branch></pre>

RawTherapee uses GTK+ for the user interface and requires GTK+ version 3.16 or newer. If your system does not support version 3.16 or newer then you must checkout the <code>5.0-r1-gtk2</code> tag. Our GTK2 support has officially ended on 2 February 2017 - refer to the archived [[Linux_GTK2|GTK2]] article, and update your system.

Compiling old versions of RawTherapee will fail on a modern system, as you will be missing the old dependencies.

==== Compile RawTherapee ====

Now you will make an out-of-source compilation of RawTherapee, it will be built into the <code>~/programs/code-rawtherapee/build/release</code> folder, and then you will move this folder to <code>~/programs/rawtherapee</code>

===== CMake =====

There are a few compilation settings you need to be aware of, you will pass these to CMake using the <code>-D</code> option as described below:

; CMAKE_BUILD_TYPE
: One of: <code>release</code> (default), <code>relwithdebinfo</code> or <code>debug</code>.
: This controls whether the build will favor faster execution time or more verbose debugging output.
: The "debug" and "relwithdebinfo" builds will let you [[How_to_write_useful_bug_reports|get a useful stack-backtrace]] if RawTherapee crashes while running through GDB which you can then submit to us so we can find the problem and fix it. The "debug" build is the slowest but generates the most detailed information. The "relwithdebinfo" build is almost as fast as a "release" build and generates often sufficient information, though not as detailed as a "debug" build. The "release" build will not provide any useful information when it crashes, but does contain many speed optimizations resulting in a program that works several times faster than the "debug" build would. For normal use, make a "release" or "relwithdebinfo" build. If you find a reproducible bug, then make a "debug" build and send us a stack-backtrace (or fix it yourself and send us the patch!). We prefer stack backtraces from debug builds than from relwithdebinfo ones.
:: To make a "release" type build, set: <code>-DCMAKE_BUILD_TYPE="release"</code>

; USE_OLD_CXX_ABI
: <code>ON</code> or <code>OFF</code> (default).
: When compiling a program, one must use the same conventions as those used by the libraries which that program relies upon, otherwise compilation (linking) will fail. Generally one does not need to concern oneself with this, but we are now at a time when GCC4 is being phased out by GCC5, each by default using a convention incompatible with the other, and so this issue is relevant. If the libraries on your system have been compiled using GCC5, they probably use a standard called C++11. This means that your RawTherapee build must use the same standard, which is the case by default. However, if despite using GCC5 your libraries were built using the older C++03 standard, then RawTherapee must be set to use the same, and this is when you would set "USE_OLD_CXX_ABI" to "ON".
:: To enable USE_OLD_CXX_ABI, set: <code>-DUSE_OLD_CXX_ABI="ON"</code>

; CACHE_NAME_SUFFIX
: The CACHE_NAME_SUFFIX options sets the suffix of the cache and config folder names the compiled RawTherapee build will use. See the [[File Paths]] article for an explanation of what those are.
: For stable releases (if you checkout the "releases" branch) use <code>-DCACHE_NAME_SUFFIX=""</code>
: For development builds (if you checkout the "dev" branch or any branch other than "releases") use <code>-DCACHE_NAME_SUFFIX="5-dev"</code>

; PROC_TARGET_NUMBER
: From <code>0</code> (default) to <code>9</code>.
: The PROC_TARGET_NUMBER option sets which CPU type to optimize for.
: If building for yourself, use "2". It means "native", so the optimizations will be automatically detected for your CPU and RawTherapee will perform as fast as possible on your CPU. It might not run at all on older or other CPU architectures.
: If building for distribution (for other people), use "1". It means "generic", so only optimizations supported by most CPUs will be used, meaning the build can be downloaded and used by anyone, though it won't benefit from the best optimizations possible for the user's CPU.
: For more info, see the file "ProcessorTargets.cmake" in the cloned repository.
:: To make a build using "native" optimizations, set: <code>-DPROC_TARGET_NUMBER="2"</code>

; BUILD_BUNDLE
: <code>ON</code> or <code>OFF</code>.
: Forced to "ON" for Windows and macOS. Optional in Linux where it is "OFF" by default.
: If set to ON, the program will be built into the <code>DATADIR</code> folder, otherwise it will be installed relative to <code>CMAKE_INSTALL_PREFIX</code> which would typically be system-wide.

; BUNDLE_BASE_INSTALL_DIR
: Use an absolute path.
: The program will be built into this folder.
: For example, set it to: <code>-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee"</code>
: If it is not set, the default is to use <code>${CMAKE_BINARY_DIR}/${CMAKE_BUILD_TYPE}</code>

; LENSFUNDBDIR
: Unset by default.
: The <code>LENSFUNDBDIR</code> option permits to locate the lensfun database in the specified directory. It can be unset, absolute or relative.
: When unset, Lensfun uses its own logic to find the database. This is the recommended option if you have Lensfun installed system-wide and want to use it.
: You can set it to a relative or absolute path if you want to use a custom lensfun database.
: If building a bundle, it is relative to the bundle's root folder, otherwise it is relative to <code>DATADIR</code>, i.e. <code>${CMAKE_INSTALL_PREFIX}/share/rawtherapee</code>

; OPTION_OMP
: <code>ON</code> (default) or <code>OFF</code>.
: Build with OpenMP support when enabled, which enables multithreading and makes RawTherapee much faster.

; WITH_LTO
: <code>ON</code> or <code>OFF</code> (default).
: Build with link-time optimizations when enabled, which may make RawTherapee run a little faster.

; WITH_PROF
: <code>ON</code> or <code>OFF</code> (default).
: For debugging purposes. Generate extra code to write profile information suitable for the analysis program gprof.

; WITH_SAN
: <code>OFF</code> (default) or one of various other options.
: For debugging purposes. Allows enabling various sanitizers to help detect program issues.
: See GCC manual's [https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html Program Instrumentation Options] chapter for more information.

; WITH_SYSTEM_KLT
: <code>ON</code> or <code>OFF</code> (default).
: Build using system KLT library when ON, otherwise use KLT files bundled with RawTherapee.
: The Kanade–Lucas–Tomasi (KLT) feature tracker is used by the [[Lens/Geometry#Distortion_Correction|Auto Distortion Correction]] tool.

; WITH_BENCHMARK
: <code>ON</code> or <code>OFF</code> (default).
: Build with timing functions enabled to benchmark performance.

; ENABLE_TCMALLOC
: <code>ON</code> or <code>OFF</code> (default).
: In some cases the operating system has trouble handling memory allocation and deallocation required by RawTherapee (see [https://github.com/Beep6581/RawTherapee/issues/5459 here] for more information). Linking against [https://gperftools.github.io/gperftools/tcmalloc.html TCMalloc] may alleviate these problems. This library may not be available on all platforms or distributions.

===== Make =====

Find out how many threads your CPU supports. This only influences the compilation speed, it has no influence over how fast the compiled RawTherapee build runs. To find out how many threads your CPU supports, run this in a terminal:
<pre style="white-space: pre-wrap">nproc --all</pre>
It will return a number. Use this number for the <code>--jobs</code> parameter below.

Compile:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
mkdir build
cd build

cmake \
-DCMAKE_BUILD_TYPE="release" \
-DCACHE_NAME_SUFFIX="5-dev" \
-DPROC_TARGET_NUMBER="2" \
-DBUILD_BUNDLE="ON" \
-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee" \
-DOPTION_OMP="ON" \
-DWITH_LTO="OFF" \
-DWITH_PROF="OFF" \
-DWITH_SAN="OFF" \
-DWITH_SYSTEM_KLT="OFF" \
..

make --jobs=4
make install
</pre>

==== Run RawTherapee ====

To run RawTherapee:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee</pre>
Or to run the CLI version:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee-cli</pre>

The source code repository is in <code>~/programs/code-rawtherapee</code> and the compiled program is in <code>~/programs/rawtherapee</code>

You can safely delete <code>~/programs/code-rawtherapee</code> if you so wish. The compiled program will still work, but then you will have to redo all the above steps if you want to update. Rather, leave the repository intact so that you can do the next step in a week or a month's time when you want to update.

==== Update RawTherapee ====

Every time you want to update RawTherapee to the latest code available, just do the following:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
git pull</pre>

Then repeat the [[#Make|Make]] step above.

When updating, you can re-use the <code>build</code> folder from last time to avoid having to recompile things which have not changed, to make the whole process faster. CMake should automatically detect changes. However, there are situations when compilation may fail when re-using an old <code>build</code> folder - typically that might happen when hopping between very different branches. If that happens, just delete the <code>build</code> folder, then proceed with the steps in the "Make" section.

Download

2022-02-14T04:47:58Z

Thanatomanic: Updated link to new automated builds, rephrased some text to accurately reflect reality.

<div class="pagetitle">Download</div>

== Stable Releases ==

{{Template:Download_stable}}

== Development Builds ==

Use a development build if you want to test the newest features and latest changes, and if you are willing to risk potential buggy behavior and do not care that functionality may change between versions.

Development builds can be downloaded from several locations:

* The [https://github.com/Beep6581/RawTherapee/releases/tag/nightly-github-actions official GitHub repository].
* The [https://keybase.pub/gaaned92/RTW64NightlyBuilds/ unofficial builds] by André Gauthier.
* The [https://keybase.pub/kd6kxr/ unofficial macOS builds] by Richard Barber.

Official automated development builds are generated after each new commit to our [https://github.com/Beep6581/RawTherapee GitHub repository]. This gives you a ''bleeding edge'' version of RawTherapee with all the latest bug fixes, features and camera support. These builds are generally stable enough to be crash-free and the developers take care not to accidentally introduce bugs. Even though issues can never be avoided completely, many users use development builds for their everyday editing without problems.

However, if stability is key for you, we always recommend that you use the [http://www.rawtherapee.com/downloads/ latest stable release]. It is important to understand that while we try to maintain [https://en.wikipedia.org/wiki/Backward_compatibility backward compatibility] between stable releases (i.e. images edited in RawTherapee 5.7 should look the same when opened in RawTherapee 5.8), this is certainly ''not'' the case between development versions.

Development build filenames roughly follow this structure:

<code>RawTherapee_branch_win64_type.extension</code>

* Each commit happens on a "branch". The main branch is called <code>dev</code>. New features are developed on their own branches, and then merged into <code>dev</code> when ready.
* The "type" is either <code>release</code> or <code>debug</code>. Most users will want to use the release-version. The debug-version is generally slower and only helpful when [https://rawpedia.rawtherapee.com/How_to_write_useful_bug_reports tracking down bugs or crashes].

Windows

2022-02-14T04:09:04Z

Thanatomanic: Minor updates to naming scheme

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

Since December 2020 the <code>libiptcdata</code> library is provided by MSYS2 and no longer requires manual compilation. <i>Only if you experience problems using this library</i>, follow the instructions below to manually build it. Otherwise, continue to the next section.
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
libatk-1.0-0.dll
libatkmm-1.6-1.dll
libbz2-1.dll
libbrotlicommon.dll
libbrotlidec.dll
libcairo-2.dll
libcairo-gobject-2.dll
libcairomm-1.0-1.dll
libdatrie-1.dll
libdeflate.dll
libepoxy-0.dll
libexpat-1.dll
libffi-7.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libjbig-0.dll
libjpeg-8.dll
liblcms2-2.dll
liblensfun.dll
liblerc.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwebp-7.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_win64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_win64_<buildtype>.zip</code>

* "win64" means it can run on 64-bit Windows (in effect, only Windows 7 and newer is officially supported).
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Windows

2022-02-02T06:40:02Z

Thanatomanic: Updated dependencies (as per https://github.com/Beep6581/RawTherapee/pull/6413)

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

Since December 2020 the <code>libiptcdata</code> library is provided by MSYS2 and no longer requires manual compilation. <i>Only if you experience problems using this library</i>, follow the instructions below to manually build it. Otherwise, continue to the next section.
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
libatk-1.0-0.dll
libatkmm-1.6-1.dll
libbz2-1.dll
libbrotlicommon.dll
libbrotlidec.dll
libcairo-2.dll
libcairo-gobject-2.dll
libcairomm-1.0-1.dll
libdatrie-1.dll
libdeflate.dll
libepoxy-0.dll
libexpat-1.dll
libffi-7.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libjbig-0.dll
libjpeg-8.dll
liblcms2-2.dll
liblensfun.dll
liblerc.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwebp-7.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Linux

2021-07-30T19:25:31Z

Thanatomanic: Add expat-devel to Fedora build instructions

<div class="pagetitle">Linux</div>

This page details instructions for compiling RawTherapee on '''GNU/Linux''' systems. There are also instructions for compiling on [[Windows]] and [[macOS]].

When in doubt, [[IRC|join us on IRC]] or in the [[Forum]] and ask a human!

== Dependencies ==

To compile RawTherapee your system will need a set of tools and code libraries from other programs. These are called dependencies, and here is a list of them for the latest version of RawTherapee:

{| class="wikitable sortable"
|+ Build-time dependencies for RawTherapee:
! Package !! Version !! URL
|-
| CMake || cmake>=3.5 || https://cmake.org/
|-
| EXIV2 || exiv2>=0.19 || http://www.exiv2.org/
|-
| EXPAT || expat>=2.1.0 || https://libexpat.github.io/
|-
| FFTW3 || fftw>=3.2.2 || http://fftw.org/
|-
| GCC || gcc>=4.9 || https://gcc.gnu.org/
|-
| GLIB2 || glib-2.0>=2.24 || https://www.gtk.org/
|-
| GLIBMM || glibmm-2.4>=2.24 || https://www.gtkmm.org/
|-
| GTK+ || gtk+-3.16 < 3.24.0 || https://www.gtk.org/
|-
| GTKMM || gtkmm-3.16 || https://www.gtkmm.org/
|-
| JPEG || libjpeg>=6b || https://libjpeg-turbo.org/ https://jpegclub.org/ https://www.ijg.org/
|-
| LCMS2 || lcms>=2.6 || https://www.littlecms.com/
|-
| LENSFUN || lensfun>=0.2 || https://github.com/lensfun/lensfun
|-
| LIBCANBERRA || libcanberra>=0.29 || http://0pointer.de/lennart/projects/libcanberra/ (Linux only)
|-
| LIBIPTCDATA || libiptcdata>=1.0.2 || http://libiptcdata.sourceforge.net
|-
| PNG || libpng>=1.2.44 || http://www.libpng.org/
|-
| librsvg || librsvg>=2.40 || https://github.com/GNOME/librsvg
|-
| SIGC || sigc++-2.0 || https://github.com/libsigcplusplus/libsigcplusplus
|-
| TIFF || libtiff>=4.0.4 || http://libtiff.org/
|-
| ZLIB || zlib>=1.2.3 || http://www.zlib.net/
|}

In order to install all these dependencies, you will need to open a console and paste the code from the appropriate section into the console.

The code snippets below list dependencies for the latest RawTherapee code which requires GTK3. We dropped support for GTK2 with release "5.0-r1-gtk2" in February 2017. If you use a modern distribution, just copy and paste the code snippets as they are. If you're on an old distribution without the required GTK3 support, then refer to the archived [[Linux_GTK2|GTK2]] article, then checkout and compile the obsolete <code>5.0-r1-gtk2</code> tag.

=== Arch/Manjaro ===

Current versions of Arch and Manjaro work well out of the box. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 17.1.12.

<pre style="white-space: pre-wrap">sudo pacman -S --needed cmake exiv2 expat fftw glib2 glibmm gtk3 gtkmm3 lcms2 lensfun libcanberra libiptcdata libjpeg-turbo libpng librsvg libsigc++ libtiff zlib</pre>

Proceed to [[#Compilation|Compilation]].

=== CentOS ===

CentOS 7 has very outdated packages and requires extra steps to install a recent GCC, git, lensfun and libtiff. The steps below were verified to work in CentOS 7.4.1708, but proceed at your own risk.

GCC >=4.9.3:
<pre style="white-space: pre-wrap">sudo yum update
sudo yum install cmake git
sudo yum install centos-release-scl
sudo yum install devtoolset-7-gcc*
scl enable devtoolset-7 bash
source /opt/rh/devtoolset-7/enable</pre>

git >=2.7:
<pre style="white-space: pre-wrap">sudo yum install http://opensource.wandisco.com/centos/7/git/x86_64/wandisco-git-release-7-2.noarch.rpm</pre>

lensfun:
<pre style="white-space: pre-wrap">
wget http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -ivh epel-release-latest-7.noarch.rpm</pre>

libtiff >=4.0.4:
<pre style="white-space: pre-wrap">sudo yum install ninja-build
mkdir ~/programs && cd ~/programs
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
mkdir tiff-4.0.9/libtiff-build && cd tiff-4.0.9/libtiff-build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

Install the other dependencies:
<pre style="white-space: pre-wrap">sudo yum install curl expat-devel fftw-devel gtk3-devel gtkmm30-devel lcms2-devel lensfun-devel libcanberra-devel libiptcdata-devel libjpeg-turbo-devel libpng-devel librsvg2-devel zlib-devel</pre>

Symlink libatomic:
<pre style="white-space: pre-wrap">sudo ln -s /usr/lib64/libatomic.so.1 /usr/lib64/libatomic.so</pre>

As you proceed to the next step - compilation - you will need to edit the <code>build-rawtherapee</code> script and add these three lines to the CMake section near the end of the file, for example after the "-DWITH_BENCHMARK" line before the "$HOME" line:
<pre style="white-space: pre-wrap"> -DTIFF_INCLUDE_DIR="$HOME/programs/tiff-4.0.9/libtiff" \
-DTIFF_LIBRARY="$HOME/programs/tiff-4.0.9/libtiff-build/libtiff/libtiff.so" \
-DCMAKE_CXX_FLAGS="-Wno-deprecated -Wno-parentheses" \
</pre>

Proceed to [[#Compilation|Compilation]].

=== Debian/Ubuntu/Mint/elementary OS ===

Current versions of these distributions work well out of the box (Debian >=9, Ubuntu >=18.04 LTS, Linux Mint >=19, elementary OS >=5). Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo apt install git build-essential cmake curl pkg-config libgtk-3-dev libgtkmm-3.0-dev liblensfun-dev librsvg2-dev liblcms2-dev libfftw3-dev libiptcdata0-dev libtiff5-dev libcanberra-gtk3-dev</pre>

==== Ubuntu 16.04 LTS (Xenial) ====
RawTherapee 5.8 (release) is the latest version supported for Xenial-based distributions. See [https://github.com/Beep6581/RawTherapee/issues/5943 here] for details. When compiling, follow the manual steps and use git to checkout the <code>5.8</code> branch.

==== Ubuntu <=14.04 LTS (Trusty), Debian <=8 (Jessie) ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Ubuntu. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Fedora ===

Current versions of Fedora work well out of the box. Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo dnf install git make cmake curl gcc gcc-c++ gtk3-devel gtkmm30-devel lensfun-devel librsvg2-devel lcms2-devel fftw-devel expat-devel libiptcdata-devel libtiff-devel libjpeg-turbo-devel libcanberra-devel libatomic</pre>

==== Fedora <=23 ====
RawTherapee 5.6 (release) is the latest version supported for this distribution because of a higher CMake version requirement (see [https://github.com/Beep6581/RawTherapee/issues/5302 here]). When compiling, follow the manual steps and use git to checkout the <code>5.6</code> branch.

==== Fedora 22 ====
In addition to the above notices and requirements, an updated version of <code>libtiff</code> needs to be compiled manually.

<pre style="white-space: pre-wrap">sudo yum install ninja-build
cd ~
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
cd tiff-4.0.9.tar.gz
mkdir build && cd build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

==== Fedora <=21 ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Fedora. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Gentoo/Sabayon ===

Sabayon users should use the same dependencies as for Gentoo, but instead of <code>sudo emerge -uva</code> use <code>sudo equo install sys-devel/gcc dev-vcs/git</code>.

<pre style="white-space: pre-wrap">sudo emerge -uva dev-cpp/gtkmm:3.0 dev-libs/expat dev-util/cmake media-gfx/exiv2 media-libs/lcms media-libs/lensfun media-libs/libcanberra media-libs/libiptcdata media-libs/libjpeg-turbo media-libs/libpng gnome-base/librsvg media-libs/tiff net-misc/curl sci-libs/fftw sys-libs/zlib x11-libs/gtk+:3</pre>

Proceed to [[#Compilation|Compilation]].

=== openSUSE ===

openSUSE Leap 15 and Tumbleweed should work well out of the box. Serious compilation issues can be expected with other versions. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 42.1.

<pre style="white-space: pre-wrap">sudo zypper install git cmake gcc gcc-c++ gtk3-devel gtkmm3-devel liblcms2-devel fftw3-devel libitpcdata-devel librsvg-devel libtiff-devel libjpeg8-devel libcanberra-gtk3-devel</pre>

For openSUSE 15.1 and newer, the <code>lensfun</code> library needs to be installed as follows:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-data liblensfun1</pre>

For openSUSE Tumbleweed, the package is slightly different:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-devel</pre>

For other versions of openSUSE <code>lensfun</code> has to be installed manually:

<pre>wget https://sourceforge.net/projects/lensfun/files/0.3.2/lensfun-0.3.2.tar.gz
tar xvf lensfun-0.3.2.tar.gz
cd lensfun-0.3.2.tar.gz
mkdir build
cd build
cmake ../
make
sudo make install</pre>

Proceed to [[#Compilation|Compilation]].

== Compilation ==

There are two general ways you can compile RawTherapee: either use the [[#The_Automatic_Way|automatic]] Bash script which compiles RawTherapee for you (recommended), or do so [[#The_Manual_Way|manually]].

=== The Automatic Way ===

This is the recommended way of compiling RawTherapee as it is fast, simple and fool-proof. It relies on a Bash script which downloads the latest RawTherapee source code and compiles it in a way which is optimized for your CPU. The compiled builds are ready for use. The script does not check for build-time dependencies, so be sure to read the [[#Dependencies|Dependencies]] section before using the script. The compiled builds are standalone, meaning that you can keep several versions of RawTherapee at the same time simply by renaming the build folders so that creating a new build does not overwrite the previous build, which happens by default.

Run the script as a normal user, not as root!

Open a terminal, get the script, make it executable, and run it:
<pre style="white-space: pre-wrap">cd ~
wget https://raw.githubusercontent.com/Beep6581/RawTherapee/dev/tools/build-rawtherapee -O build-rawtherapee
chmod +x build-rawtherapee
./build-rawtherapee</pre>

If everything goes well, the script will terminate with the message, "To run rawtherapee type: ...".

To update RawTherapee if you previously compiled it using this script, just re-run the script. That's it.

The <code>build-rawtherapee</code> script is included in RawTherapee's source code. Since running the script updates the source code, after you compiled your first build you can delete the script you downloaded manually above using wget, and instead use <code>~/programs/code-rawtherapee/tools/build-rawtherapee</code> which will always update itself.

The script compiles the current branch, which by default is <code>dev</code> where most of the development happens. To compile a different branch, check it out using standard git commands before running the script. Read more about RawTherapee's branches below in the [[Linux#Choose_a_branch|Choose a Branch]] section.

For more information, see <code>./build-rawtherapee --help</code>

You have finished, RawTherapee is ready for use. You can skip the "Manual Way" section.

=== The Manual Way ===

The recommended way of compiling RawTherapee is by using the automatic script - see [[#The_Automatic_Way|Compilation: The Automatic Way]]. If you want to learn how to compile manually, read on.

In order to keep your "home" folder clean when manually compiling multiple programs (i.e. when not using your distribution's package manager) and for this manual compilation tutorial to maintain compatibility with the automatic compilation script, you will create the folder <code>~/programs/</code> which will contain all RawTherapee-related source code in the <code>~/programs/code-rawtherapee</code> folder, and the compiled build in the <code>~/programs/rawtherapee</code> folder. You can use the same scheme when compiling other programs.

==== Clone the source ====

First, you need to clone RawTherapee's source code repository. Bring up your console and run this:

<pre style="white-space: pre-wrap">mkdir -p ~/programs
git clone https://github.com/Beep6581/RawTherapee ~/programs/code-rawtherapee
cd ~/programs/code-rawtherapee</pre>

==== Choose a branch ====

* Features are developed on their own feature branches.
* Development happens in the <code>dev</code> branch. Feature branches are merged into the <code>dev</code> branch when they're ready. The <code>dev</code> branch is unstable.
* Releases are tagged in the <code>releases</code> branch.

Checkout the latest tag if you want the most stable code. To see all available tags, type:
<pre style="white-space: pre-wrap">git tag</pre>

Checkout the <code>dev</code> branch or some other feature branch if you want to test the latest bleeding-edge code. To see all available branches, type:
<pre style="white-space: pre-wrap">git branch -a</pre>

Checking out is done via the "git checkout" command. To checkout a tag or a branch, type:
<pre style="white-space: pre-wrap">git checkout <tag or branch></pre>

RawTherapee uses GTK+ for the user interface and requires GTK+ version 3.16 or newer. If your system does not support version 3.16 or newer then you must checkout the <code>5.0-r1-gtk2</code> tag. Our GTK2 support has officially ended on 2 February 2017 - refer to the archived [[Linux_GTK2|GTK2]] article, and update your system.

Compiling old versions of RawTherapee will fail on a modern system, as you will be missing the old dependencies.

==== Compile RawTherapee ====

Now you will make an out-of-source compilation of RawTherapee, it will be built into the <code>~/programs/code-rawtherapee/build/release</code> folder, and then you will move this folder to <code>~/programs/rawtherapee</code>

===== CMake =====

There are a few compilation settings you need to be aware of, you will pass these to CMake using the <code>-D</code> option as described below:

; CMAKE_BUILD_TYPE
: One of: <code>release</code> (default), <code>relwithdebinfo</code> or <code>debug</code>.
: This controls whether the build will favor faster execution time or more verbose debugging output.
: The "debug" and "relwithdebinfo" builds will let you [[How_to_write_useful_bug_reports|get a useful stack-backtrace]] if RawTherapee crashes while running through GDB which you can then submit to us so we can find the problem and fix it. The "debug" build is the slowest but generates the most detailed information. The "relwithdebinfo" build is almost as fast as a "release" build and generates often sufficient information, though not as detailed as a "debug" build. The "release" build will not provide any useful information when it crashes, but does contain many speed optimizations resulting in a program that works several times faster than the "debug" build would. For normal use, make a "release" or "relwithdebinfo" build. If you find a reproducible bug, then make a "debug" build and send us a stack-backtrace (or fix it yourself and send us the patch!). We prefer stack backtraces from debug builds than from relwithdebinfo ones.
:: To make a "release" type build, set: <code>-DCMAKE_BUILD_TYPE="release"</code>

; USE_OLD_CXX_ABI
: <code>ON</code> or <code>OFF</code> (default).
: When compiling a program, one must use the same conventions as those used by the libraries which that program relies upon, otherwise compilation (linking) will fail. Generally one does not need to concern oneself with this, but we are now at a time when GCC4 is being phased out by GCC5, each by default using a convention incompatible with the other, and so this issue is relevant. If the libraries on your system have been compiled using GCC5, they probably use a standard called C++11. This means that your RawTherapee build must use the same standard, which is the case by default. However, if despite using GCC5 your libraries were built using the older C++03 standard, then RawTherapee must be set to use the same, and this is when you would set "USE_OLD_CXX_ABI" to "ON".
:: To enable USE_OLD_CXX_ABI, set: <code>-DUSE_OLD_CXX_ABI="ON"</code>

; CACHE_NAME_SUFFIX
: The CACHE_NAME_SUFFIX options sets the suffix of the cache and config folder names the compiled RawTherapee build will use. See the [[File Paths]] article for an explanation of what those are.
: For stable releases (if you checkout the "releases" branch) use <code>-DCACHE_NAME_SUFFIX=""</code>
: For development builds (if you checkout the "dev" branch or any branch other than "releases") use <code>-DCACHE_NAME_SUFFIX="5-dev"</code>

; PROC_TARGET_NUMBER
: From <code>0</code> (default) to <code>9</code>.
: The PROC_TARGET_NUMBER option sets which CPU type to optimize for.
: If building for yourself, use "2". It means "native", so the optimizations will be automatically detected for your CPU and RawTherapee will perform as fast as possible on your CPU. It might not run at all on older or other CPU architectures.
: If building for distribution (for other people), use "1". It means "generic", so only optimizations supported by most CPUs will be used, meaning the build can be downloaded and used by anyone, though it won't benefit from the best optimizations possible for the user's CPU.
: For more info, see the file "ProcessorTargets.cmake" in the cloned repository.
:: To make a build using "native" optimizations, set: <code>-DPROC_TARGET_NUMBER="2"</code>

; BUILD_BUNDLE
: <code>ON</code> or <code>OFF</code>.
: Forced to "ON" for Windows and macOS. Optional in Linux where it is "OFF" by default.
: If set to ON, the program will be built into the <code>DATADIR</code> folder, otherwise it will be installed relative to <code>CMAKE_INSTALL_PREFIX</code> which would typically be system-wide.

; BUNDLE_BASE_INSTALL_DIR
: Use an absolute path.
: The program will be built into this folder.
: For example, set it to: <code>-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee"</code>
: If it is not set, the default is to use <code>${CMAKE_BINARY_DIR}/${CMAKE_BUILD_TYPE}</code>

; LENSFUNDBDIR
: Unset by default.
: The <code>LENSFUNDBDIR</code> option permits to locate the lensfun database in the specified directory. It can be unset, absolute or relative.
: When unset, Lensfun uses its own logic to find the database. This is the recommended option if you have Lensfun installed system-wide and want to use it.
: You can set it to a relative or absolute path if you want to use a custom lensfun database.
: If building a bundle, it is relative to the bundle's root folder, otherwise it is relative to <code>DATADIR</code>, i.e. <code>${CMAKE_INSTALL_PREFIX}/share/rawtherapee</code>

; OPTION_OMP
: <code>ON</code> (default) or <code>OFF</code>.
: Build with OpenMP support when enabled, which enables multithreading and makes RawTherapee much faster.

; WITH_LTO
: <code>ON</code> or <code>OFF</code> (default).
: Build with link-time optimizations when enabled, which may make RawTherapee run a little faster.

; WITH_PROF
: <code>ON</code> or <code>OFF</code> (default).
: For debugging purposes. Generate extra code to write profile information suitable for the analysis program gprof.

; WITH_SAN
: <code>OFF</code> (default) or one of various other options.
: For debugging purposes. Allows enabling various sanitizers to help detect program issues.
: See GCC manual's [https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html Program Instrumentation Options] chapter for more information.

; WITH_SYSTEM_KLT
: <code>ON</code> or <code>OFF</code> (default).
: Build using system KLT library when ON, otherwise use KLT files bundled with RawTherapee.
: The Kanade–Lucas–Tomasi (KLT) feature tracker is used by the [[Lens/Geometry#Distortion_Correction|Auto Distortion Correction]] tool.

; WITH_BENCHMARK
: <code>ON</code> or <code>OFF</code> (default).
: Build with timing functions enabled to benchmark performance.

; ENABLE_TCMALLOC
: <code>ON</code> or <code>OFF</code> (default).
: In some cases the operating system has trouble handling memory allocation and deallocation required by RawTherapee (see [https://github.com/Beep6581/RawTherapee/issues/5459 here] for more information). Linking against [https://gperftools.github.io/gperftools/tcmalloc.html TCMalloc] may alleviate these problems. This library may not be available on all platforms or distributions.

===== Make =====

Find out how many threads your CPU supports. This only influences the compilation speed, it has no influence over how fast the compiled RawTherapee build runs. To find out how many threads your CPU supports, run this in a terminal:
<pre style="white-space: pre-wrap">nproc --all</pre>
It will return a number. Use this number for the <code>--jobs</code> parameter below.

Compile:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
mkdir build
cd build

cmake \
-DCMAKE_BUILD_TYPE="release" \
-DCACHE_NAME_SUFFIX="5-dev" \
-DPROC_TARGET_NUMBER="2" \
-DBUILD_BUNDLE="ON" \
-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee" \
-DOPTION_OMP="ON" \
-DWITH_LTO="OFF" \
-DWITH_PROF="OFF" \
-DWITH_SAN="OFF" \
-DWITH_SYSTEM_KLT="OFF" \
..

make --jobs=4
make install
</pre>

==== Run RawTherapee ====

To run RawTherapee:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee</pre>
Or to run the CLI version:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee-cli</pre>

The source code repository is in <code>~/programs/code-rawtherapee</code> and the compiled program is in <code>~/programs/rawtherapee</code>

You can safely delete <code>~/programs/code-rawtherapee</code> if you so wish. The compiled program will still work, but then you will have to redo all the above steps if you want to update. Rather, leave the repository intact so that you can do the next step in a week or a month's time when you want to update.

==== Update RawTherapee ====

Every time you want to update RawTherapee to the latest code available, just do the following:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
git pull</pre>

Then repeat the [[#Make|Make]] step above.

When updating, you can re-use the <code>build</code> folder from last time to avoid having to recompile things which have not changed, to make the whole process faster. CMake should automatically detect changes. However, there are situations when compilation may fail when re-using an old <code>build</code> folder - typically that might happen when hopping between very different branches. If that happens, just delete the <code>build</code> folder, then proceed with the steps in the "Make" section.

Getting Started

2021-07-21T14:15:02Z

Thanatomanic: Modified welcome

<div class="pagetitle">Getting Started</div>

== Scope ==

RawTherapee is a powerful cross-platform raw image processing program, released under the GNU General Public License Version 3. Started in 2005 by Gábor Horváth, it was released as open-source software in 2010 and has been under development by an international team ever since. RawTherapee has an extensive set of tools specifically aimed at processing photographs. It works very well in conjunction with raster graphics editors, such as Photoshop or GIMP, and a digital asset manager, such as digiKam.

== Get RawTherapee ==

{{Template:Download_stable}}

== Start RawTherapee==

[[File:Rt setm fb.png|thumb|RawTherapee in Single Editor Tab Mode - Vertical Tabs, showing: 1- Main sections: [[File Browser]] (currently opened), Queue, Editor and Preferences. 2- Panels used for navigating to files and folders. 3- Thumbnails of the currently opened folder. 4- Filters to limit the thumbnails shown to only those which match some metadata or state. 5- Thumbnail zooming and info. 6- Quick image operations. 7- Sub-tabs of the File Browser: Filter (currently opened), Inspect (to see a full-sized embedded JPEG preview), Batch Edit (to apply some setting to all selected images) and Fast Export (low quality and bypasses some tools but fast saving - don't use this for typical saving!). 8- Right-click context menu (you will typically use this to apply some processing profile to all selected files).]]

When you start RawTherapee you will land in the [[File Browser]] tab, and it might be empty. You need to point RawTherapee to where your raw photos are stored. Use the folder tree browser on the left of the ''File Browser'' tab to navigate to your raw photo repository and double-click on the folder to open it. Then double-click on a raw photo to start editing it.

== Edit your first image ==

First, a little background. A raw photo contains a dump of sensor data, which makes up the bulk of the raw file. This sensor data does not look like a pretty image, in fact it does not look like anything - it is "raw" data, ergo the name. It must be "cooked" to look like the image you saw through the viewfinder. Your camera cooks the raw data into a pretty image, which it stores as a JPEG file inside the raw file (yes, even when you're shooting in only "RAW" mode as opposed to "RAW+JPEG" mode). Due to this fundamental fact of the data being "raw", there is no one correct way for a raw photo to look - the way your camera makes it look is not "the right way", nor is it the only way. However, many photographers would like to use the "camera look" as a starting point for further adjustments, and RawTherapee makes this possible.

When displaying a raw photo in the [[File Browser]] which has never been edited in RawTherapee before, the photo's thumbnail is based on the JPEG image embedded inside that raw file -- the exact same image you see when viewing that photo on your camera or in most other software. Once you open that photo in the [[Editor]], RawTherapee creates a new thumbnail based on the actual raw data. Since creating an image from raw data requires "cooking" it, and since you have not manually edited that image yet, RawTherapee uses parameters from the [[Preferences#Default_Processing_Profile|default processing profile for raw photos]] to process it. From that moment on, the photo's thumbnail is no longer based on the embedded JPEG but on the actual raw data. When you make adjustments to the image in the Editor, the thumbnail is updated to reflect your changes.

Editing is done in the [[Editor]]. This is where you work with RawTherapee to create stunning works of art - or perhaps just apply first aid to your snapshots. When you open a raw photo in the Editor for the first time, the [[Preferences#Default_Processing_Profile|default processing profile for raw photos]] is applied, which as of RawTherapee 5.4 is set to "Auto-Matched Curve - ISO Low" (unless you changed it in Preferences), and it automatically adjusts your raw photo to look like the out-of-camera JPEG. It does so by analyzing the JPEG image which was created by your camera and is stored within the raw file, and adjusting the tone curve so as to match it. In most cases this match is very close to the "camera look". In rare cases it may fail. See the [[Auto-Matched Curve]] article for more information.

[[File:Rt setm editor.png|thumb|The Editor.]]

Take a moment to look around this Editor tab.
Notice that there are tabs within this tab - on the right of screen towards the top. These tabs and the controls under them are the Toolbox. You probably have the first tab open and, if you hover your mouse over it, you'll find that it's called the Exposure tab. Below the choice of tabs are the tools the chosen tab contains – Exposure, Shadows/Highlights, Tone Mapping etc. If you click on one of them it will expand so that you can see its contents. Click again and it will collapse. Right-click on one and that one will expand while all others will collapse - a time-saving shortcut. To the left of each tool's label is a power button ([[File:Power-on-small.png]] on / [[File:Power-off-small.png]] off) which lets you turn it on or off, or in some cases instead of a power button there is a triangular expander [[File:Expander-closed-small.png]]. Read the [[General_Comments_About_Some_Toolbox_Widgets#Tools|Tools section of the General Comments About Some Toolbox Widgets]] article for a detailed explanation.
Browse through the tabs and panels until you feel totally overwhelmed by all that's available.

Before you start working on an image, here is some important advice – '''Don't Panic!''' You are in no danger of destroying any of your prized images if you make a mistake. RawTherapee has some features which help you protect your images:
* RawTherapee does non-destructive editing of your raw files. This means that RawTherapee will never, ever change the raw file itself. All changes are stored in sidecar files. You can find out more about them in the [[Sidecar Files - Processing Profiles]] article.
* When using the Editor, you'll see the [[Editor#History|History]] panel on the left. This panel shows a history stack of every change you have made to your image. To go back to any step (including when the image was first loaded), just click on the relevant line in the History panel.
* Under the History panel you'll see a [[Editor#Snapshots|Snapshots]] panel. You can skip it for now, but you'll find it handy when you gain experience with RawTherapee. This panel stores the state of all the tools as a "snapshot". This allows you to easily, for example, tweak your photo to a nice and colorful look and take a snapshot, then tweak it again to a lovely black-and-white look and take a snapshot, and then compare the two just by clicking on either snapshot. (Note: RawTherapee does not save snapshots to the PP3 file yet, it will do so in the future. If you have three snapshots which you want to retain, you will need to click through them and save a PP3 file each time under a unique name).
* As you might expect, Control-z will undo the previous change.

=== Basics ===

# Open the raw photo. RawTherapee automatically makes it look like your camera's output. If you're happy with the result, you're done. Else read on.
# Click on the [[File:Color-circles.png]] Color tab and expanding the [[White Balance]] tool by right-clicking on it (or use the {{k|w}} [[Keyboard Shortcuts|keyboard shortcut]]). RawTherapee will start with the white balance used by your camera. Most white balance adjustments involve moving the Temperature and Tint sliders, or using the [[File:Color-picker.png]] Spot White-Balance Picker on a colorless (neutral gray) patch. Adjust to taste.
# Next, fix the exposure by going to the [[File:Exposure.png]] Exposure tab, expanding the [[Exposure]] tool and adjusting it to taste. For now, just use the Exposure Compensation and Saturation sliders.
# If your image is noisy, switch to the [[File:Detail.png]] Detail tab, zoom to 100% either using the [[File:Magnifier-1to1.png]] button or using the {{k|z}} keyboard shortcut, because the effects of the tools in this tab are only visible in the zoomed-to-100% preview (and of course in the saved image), and enable the [[Noise Reduction]] tool by clicking on the power button [[File:Power-on-small.png]] leaving the settings at their default values for now. RawTherapee has automatically removed color (chrominance) noise. Luminance noise is removed [[Noise_Reduction#Usage|manually]], though leave it for now as luminance noise generally lends a pleasing, grainy, film-like look. As a general rule, when using noise reduction don't use sharpening. Zoom back out to see the whole image either using the [[File:Magnifier-fit.png]] button or using the {{k|f}} keyboard shortcut key.
# Now you decided you want to fix the [[Lens/Geometry|geometry]] and composition of your photo.
#* First make the horizon level, or correct the things which should be vertical such as street lamps or building edges. To easily do this, press the "s" key on your keyboard (the same as clicking the [[File:Rotate-straighten.png]] button), and click-and-drag a line along the horizon or along the edge of a building over the preview. Your image will rotate accordingly and you will automatically be taken into the [[File:Transform.png]] Transform tab.
#* To crop the photo, press the {{k|c}} shortcut key on your keyboard (or use the [[File:Crop.png]] button) and click-and-drag a crop over the preview; you will notice that the [[Crop]] tool becomes automatically enabled. There is no need to "apply" a crop - it takes effect the moment you draw it. You can zoom to fit the crop area by using the {{k|f}} keyboard shortcut, or {{k|alt}}+{{k|f}} if you want to fit the whole image. You may want to set the Crop "Guide type" to "none" if it's a problem.
#* Finally, you want to downscale the photo, because who wants to upload a 10MB JPEG to your social network. Enable the [[Resize]] tool and the [[Resize#Post-Resize_Sharpening|Post-Resize Sharpening]] sub-tool, and leave them at the default settings. The resizing effect is only applied to the saved image, not to the preview, so you won't see any change in the preview as you enable these tools.
# You're all set, let's [[Saving|save]] it straight away. Click the [[File:save.png]] Save Current Image button (located below the lower left corner of the preview area), or use the {{k|Ctrl}}+{{k|s}} keyboard shortcut. Save it as a JPG file using default settings (quality at "92", subsampling at "balanced"). These are good all-round settings. Choose a folder where you want it saved to, and after a few seconds your file will be ready in the folder you selected. If you close RawTherapee, the settings you used will be stored in a [[Sidecar_Files_-_Processing_Profiles|PP3 sidecar file]] next to the raw file, so that you can re-open the raw photo in the future and retain the tool settings you used.

Now that you went through basic photo adjustment and are familiar with the steps, let's recap the steps but with more advanced details.

=== Advanced ===

Always read each tool's article here on RawPedia before using it, to get a firm understanding of what it does. The articles explain how the tools work in RawTherapee, while the general concepts unspecific to RawTherapee are left to the user to find on Wikipedia or elsewhere.

Be sure to see the [[Keyboard Shortcuts]].

The order of the tools inside RawTherapee's engine pipeline is hard-coded, so from that point of view it does not matter when you enable or disable a tool. However some tools can make a large impact on other tools, e.g. changing exposure may require you to re-adjust color toning, and some tools may require plenty of CPU power to calculate the preview making updates of the preview from then on slow, so it is for this reason we suggest you stick to this general order of operations:
# Start off by making sure that RawTherapee's environment is set up correctly, meaning:
#* Make sure that RawTherapee is using your monitor's color profile if you use a color-managed workflow. Check Preferences > Color Management. You may also need to load the appropriate calibration curves into your graphics card if you built your monitor color profile on top of them, though how you do that is outside the scope of RawTherapee.
#* Make sure that the Color Management tool is configured correctly. Usually the defaults are best. Read the [[Color Management]] and [[Color Management addon]] articles. If instead of using the color matrix or DCP or ICC profiles shipped with RawTherapee you decide to use an external one, for example a self-made DCP or one from Adobe, load it as the first thing you do, otherwise you may need to re-adjust some of the color tools. Always use an output profile - in most cases the default one, RT_sRGB. If you think you're being smart by selecting "No ICM: sRGB Output", you're mistaken.
# If you want to use a [[Flat Field|Flat-Field]] and/or [[Dark Frame|Dark-Frame]] image, do so now, to avoid re-adjustment.
# Now set the correct [[White Balance]]. You may fix the exposure first if the image is too dark (or too bright) to see white balance changes.
# Next, adjust the [[Exposure]], using the Exposure Compensation and Black sliders to get the image into the right ballpark. Once in the right ballpark, continue with using both tone curves. Be sure to read the [[Exposure#Tone_Curves|Tone Curve section]] in the Exposure article to learn why there are two of them and how best to use them - they are a very powerful tool!
# In the Basics section above we suggested that you use the [[Exposure#Saturation|Saturation]] slider (in the Exposure tool). Now that you've learned the basics and are exploring more advanced techniques, we suggest you not use the Saturation slider anymore, and instead use the more powerful [[Lab_Adjustments#CC_Curve|CC curve]] in the [[Lab Adjustments]] tool, as it gives you finer control.
# The order of the rest gets fuzzy. Some tools will unavoidably influence others. Carry on with the [[Lab Adjustments]] tool and then the rest of the tools in the Exposure tab.
# Then use the tools in the [[File:Color-circles.png]] Color tab.
# Then zoom to 100% and use the tools in the [[File:Detail.png]] Detail tab. Generally, don't sharpen if you're using noise reduction.
# Finally, zoom out again and use the tools in the [[File:Transform.png]] Transform tab. The reason you left these for last is that they may make the preview image appear a bit blurry, because in order for the preview to be responsive, RawTherapee uses that very preview image you see at the very resolution you see - small - to show what the tools do, and when you rotate or otherwise change the geometry of a small image, there is a clear softening. This is not a problem when saving as by that point RawTherapee does its processing on the full-sized image, which is slow but of high quality.
# You can edit metadata in the [[File:Metadata.png]] [[Metadata_Copy_Mode|Meta]] tab at any time before saving.
# Save, either directly [[file:save.png]] when you want to save a single photo, or via the [[file:gears.png]] [[The_Batch_Queue|Batch Queue]] when you want to process many photos. See the [[Saving Images]] article.

Editor

2021-07-08T19:12:05Z

Thanatomanic: Fixes errant bold-tags

<div class="pagetitle">The Editor</div>

[[File:Rt 55 trains.png|none|frame|link=|class=heroed|The Image Editor tab in RawTherapee 5.5.]]

== Introduction ==

The Image Editor tab is where you tweak your photos. By default RawTherapee is in "''Single Editor Tab Mode, Vertical Tabs''" (SETM) which is more memory-efficient and lets you use the ''Filmstrip'' (described below). You can switch to "''Multiple Editor Tabs Mode''" (METM) by going to "''Preferences > General > Layout''", however each Editor tab will require a specific amount of RAM relative to the image size and the tools you use, and also the ''Filmstrip'' is hidden in this mode, so we recommend you first give SETM a try.

== The Preview Panel ==

The central panel holds a preview of your photo. This preview is generated from the actual raw data by processing it according to the settings either you manually set, or those that are stored in the [[Sidecar_Files_-_Processing_Profiles | processing profile]] used when opening that photo, as specified in "''Preferences > Image Processing > Default Processing Profile''". The preview will show you the effect of all the adjustments you make. Note that the effects of some tools are only accurately visible when you are zoomed in to 1:1 (100%) or more. These tools are marked in the interface with a "1:1" icon [[File:One-to-one-small.png|Zoom 1:1]] next to the tool's name.

The image you see in the preview is taken from the working profile's color space and converted into the monitor profile's color space, if a monitor profile is loaded, or into sRGB if one is not. It does not take into account the "[[Color_Management#Output_Profile|Output Profile]]" section of the "[[Color_Management|Color Management]]" tool.

=== Eek! My Raw Photo Looks Different than the Camera JPEG ===

After opening a raw photo you will notice that it looks different, often worse - darker, less sharp, more dull, lacking contrast, more noisy - than your camera's JPEG, or than the same raw photo when viewed in other software. What gives? Witches, aliens, possums, or by design?

There are three things you must know first to understand what is happening here:
# Your camera does not show you the real raw data when you shoot raw photos. It processes the raw image in many ways before presenting you with the histogram and the preview on your camera's digital display. Even if you set all the processing features your camera's firmware allows you to tweak to their neutral, "0" positions, what you see is still not an unprocessed image. Exactly what gets applied depends on the choices your camera's engineers and management made, but usually this includes a custom tone curve, saturation boost, sharpening and noise reduction. Some cameras, particularly low-end ones and [http://en.wikipedia.org/wiki/Micro_Four_Thirds_system Micro Four-Thirds system], may also apply lens distortion correction to not only fix [http://en.wikipedia.org/wiki/Distortion_(optics)#Radial_distortion barrel and pincushion distortion] but also to hide severe [http://en.wikipedia.org/wiki/Vignetting vignetting] problems. Most cameras also underexpose every photo you take by anywhere from -0.3EV to even -1.3EV or more, in order to gain headroom in the highlights. When your camera (or other software) processes the raw file it increases exposure compensation by the same amount, making the brightness appear correct and hoping to recover some highlights in the process. RawTherapee shows you the real raw data which may mean your photos appear dark, so it is up to you whether you apply the required exposure increase and how you go about doing so, whether by using the Exposure Compensation slider or one of the various tone curves. Increasing exposure compensation makes noise more apparent regardless whether it is your camera or RawTherapee which does it, but other than this '''RawTherapee does not "add noise"!''' Many cameras apply noise reduction to the JPEGs (behind your back) to lower the noise level after increasing the exposure compensation, so you should expect there to be a difference between your out-of-camera JPEG and RawTherapee's image if noise reduction in RawTherapee is not enabled.
# Every DSLR raw file contains a processed JPEG image. Most raw files contain a JPEG image of the same full resolution as your camera can shoot, and some raw files contain as many as three JPEG images differing only in resolution. When you open raw files in other software, what you are usually seeing is '''not''' the raw data, but the embedded, processed JPEG image. Examples of software which are either incapable of or which in their default settings do not show you the real raw data: [http://en.wikipedia.org/wiki/IrfanView IrfanView], [http://en.wikipedia.org/wiki/XnView XnView], [http://en.wikipedia.org/wiki/Gwenview Gwenview], [http://en.wikipedia.org/wiki/Geeqie Geeqie], [http://en.wikipedia.org/wiki/Eye_of_GNOME Eye of GNOME], [http://en.wikipedia.org/wiki/F-Spot F-Spot], [http://en.wikipedia.org/wiki/Shotwell_(software) Shotwell], [http://en.wikipedia.org/wiki/GThumb gThumb], etc. It is worth mentioning at this point that if you shoot in "RAW+JPEG" mode, you are in fact wasting disk space and gaining nothing for it, as your raw files already contain the embedded JPEG files which you can view using the listed programs. The embedded JPEG may differ from an 'external' one as saved using "RAW+JPEG" mode in compression.
# Most raw development programs (programs which do read the real raw data instead of just reading the embedded JPEG) apply some processing to it, such as a base tone curve, even at their most neutral settings, thereby making it impossible for users to see the real, untouched contents of their raw photos. Adobe Lightroom is an example. Comparing RawTherapee's real neutral image to a quasi-neutral one from these other programs will expose the differences.

RawTherapee, on the other hand, is designed to show you the real raw image in the main preview, leaving the way you want this data processed up to you. When you use the "Neutral" processing profile you will see the demosaiced image with camera white balance in your working color space with no other modifications. You can even see the non-demosaiced image by setting the [[demosaicing]] option to "None". To provide you with a more aesthetically pleasing starting point, we do ship a collection of processing profiles with RawTherapee. After installing RawTherapee, the default profile for processing raw photos is eponymously called "Default". We also ship the "Default ISO Medium" and "Default ISO High" profiles which are designed to give a good starting point to moderately noisy and very noisy images, respectively.

None of the shipped profiles (at least none of the ones shipped in RawTherapee 5.0) are designed to imitate your camera's look. Why not? Every camera is different. My camera's image quality at ISO1600 could be far noisier than your camera's. My camera's response to colors differs from yours. Even the same camera can behave differently at various settings. To provide such profiles, we would need access to raw files for every supported camera model, often multiple raw files in various shooting modes for a single camera, and countless [http://en.wikipedia.org/wiki/Man-hour person-hours]. This may be possible as a community effort, but it is not a job for a small team. Even then, of what purpose would RawTherapee be if you ended up with a camera JPEG look?

It is far more reasonable that you learn how to use the powerful tools that RawTherapee provides to get the most out of your raws, to surpass the camera look.

As of September 2015 we are starting to ship DCP input profiles made using [https://torger.se/anders/dcamprof.html DCamProf] which include an [https://torger.se/anders/dcamprof.html#dcp_tone optional tone curve]. This curve is modeled after Adobe Camera Raw's default film curve and renders a result similar to your "camera look". The reason we include the curve in new DCP profiles is because it makes for a good vibrant starting point (as opposed to the flat look of using the "Neutral" processing profile) without having to use [[Exposure#Auto_Levels|Auto Levels]] and without having to touch any of the other tools, and it is entirely optional. Do read the article on [[Color_Management#Input_Profile|input profiles]]. If we ship a DCP for your camera model which includes the tone curve, the "Tone curve" checkbox in Color Management > Input Profile > DCP will be clickable. Applying the (Neutral) processing profile will disable the tone curve.
While the input color profile is applied at the first stages of the [[Toolchain_Pipeline|toolchain pipeline]], the DCP tone curve is applied later in the pipeline at some point after the Exposure tool.

You can create a processing profile ideally tailored to your camera and lens combination, and set RawTherapee to use it by default on your raw photos. See the [[Creating processing profiles for general use]] article to learn how.

=== Scrollable Toolbars ===

The toolbars above and below the main preview hold a certain number of buttons and other widgets which might not fit on lower resolution screens. {{:Scrollable Toolbar}}

=== Preview Modes ===

In addition to the normal preview, RawTherapee supports a number of other preview modes to help you tweak your photos. Preview modes are controlled via buttons in the ''Editor'' toolbar or via [[Keyboard_Shortcuts | keyboard shortcuts]]. Only one preview mode can be engaged at a time.

<div style="margin-left: 16px; margin-top: -1em;">
{| class="RPwt-table"
|+ align="bottom" | <nowiki>*</nowiki> The preview is returned to normal by deselecting any other mode.
! Preview Mode
! Shortcut
! Button
|-
| style="padding:10px;" | Regular* || || [[Image:preview mode 1 regular.png]]
|-
| style="padding:10px;" | Red channel || align="center" | r || [[Image:preview mode 2 red.png]]
|-
| style="padding:10px;" | Green channel || align="center" | g || [[Image:preview mode 3 green.png]]
|-
| style="padding:10px;" | Blue channel || align="center" | b || [[Image:preview mode 4 blue.png]]
|-
| style="padding:10px;" | Luminance channel || align="center" | v || [[Image:preview mode 5 luminance.png]]
|-
| style="padding:10px;" | Focus Mask || align="center" | Shift+f || [[Image:preview mode 6 focus.png]]
|}
</div>
The following preview modes are currently supported:
* Red channel,
* Green channel,
* Blue channel,
* Luminosity, which is calculated as 0.299*R + 0.587*G + 0.114*B,
* Focus mask, to see which areas are in focus

<gallery mode="packed" caption="Preview modes" style="clear: both">
Image:Preview_1_regular.jpg|Regular
Image:Preview_2_red.jpg|Red
Image:Preview_3_green.jpg|Green
Image:Preview_4_blue.jpg|Blue
Image:Preview_5_luminosity.jpg|Luminosity
Image:Preview_6_focus.jpg|Focus Mask
</gallery>

==== Red, Green, Blue and Luminosity Preview Modes ====

{{:Clipping_Indication}}

Preview of individual channels may be helpful when editing RGB curves, planning black/white conversion using the channel mixer, evaluating image noise, etc. Luminosity preview is helpful to instantly view the image in black and white without altering development parameters, to see which channel might be clipping or for aesthetic reasons.

==== Focus Mask ====

[[Image:Preview_6_focus_2.jpg|Focus mask indicating the focusing plane|thumb]]
The focus mask is designed to highlight areas of the image which are in focus. Naturally, focused areas are sharper, so the sharp areas are being highlighted. The focus mask is more accurate on images with a shallow depth of field, low noise and at higher zoom levels.To improve detection accuracy for noisy images evaluate at smaller zoom, around the 10-30% range. Note that the preview is rendered more slowly when the focus mask is enabled.

The current implementation analyzes the preview image which is rescaled from the original captured size. This process of rescaling reduces the noise and is helpful to identify truly sharper details rather than noise itself which may also contain micro texture. At the same time, rescaling of the original image to the preview size compresses larger scale details into a smaller size, and it may introduce aliasing artifacts, both of which could lead to false positives. You can increase your confidence by viewing the mask at various zoom levels. It is not always fault proof, but can be helpful in many cases.

'''Warning''': Be sure to double-check your images if you decide to delete them based on the focus mask.

=== Background color of the preview ===

The background color of the preview panel surrounding the image area may be changed to ease image preview during editing and to better visualize image cropping. A vertical stack of three thin buttons in the preview modes toolbar above the image preview panel allows to set the background color of the area around the photo preview.

<div style="margin-left: 16px; margin-top: -1em;">
{| class="RPwt-table"
! Preview<br />Background
! Shortcut
! Button
! Preview Background<br />and Crop Visualization
! Description
|-
| Theme-based || align="center" | 8 || [[Image:Previewback_7_theme.png]] || [[Image:Previewback_flower_theme.png|180px]] || The cropped area of the image is masked with a theme-based color. The cropped area visibility is based on the crop mask color and transparency as set in "''Preferences > Default Theme > Crop mask color/transparency''".
|-
| Black || align="center" | 9 || [[Image:Previewback_8_black.png]] || [[Image:Previewback_flower_white.png|frameless]] || The cropped area of the image is masked with black.
|-
| White || align="center" | 0 || [[Image:Previewback_9_white.png]] || [[Image:Previewback_flower_black.png|frameless]] || The cropped area of the image is masked with white.
|}
</div>

=== Detail Window ===

The "New detail window" button [[File:Window-add.png]], situated below the main preview next to the zoom buttons, opens a new viewport over the main preview of an adjustable size and of adjustable zoom. This lets you work on the photo zoomed-to-fit while examining several areas of interest at a 100% zoom (or even more). The benefit of using this feature is particularly important to users with slower machines, though not only them, as the zoomed-out main preview takes a shorter amount of time to update than if you were to zoom it to 100% because working at a zoom level less than 100% excludes certain slow tools, such as Noise Reduction, while the little detail windows zoomed to 100% do include all tools and are fast to update because of their small size. This allows you can use the main preview for your general exposure tweaks where it is necessary to see the whole image, and one or more detail windows to get sharpening and/or noise reduction just right.

=== Preview refresh delay ===

Changing any tool's parameters sends a signal for the preview image to be updated accordingly. Imagine what would happen if there was no "delay period", and you dragged, for example, the exposure compensation slider from 0.00 to +0.60. A signal would be sent to update the preview for every single change of that value - for +0.01, +0.02, ... +0.59, +0.60. Updating the preview 60 times would be completely unnecessary and actually take longer than it takes you to move the slider. This is especially true for more complicated tools, such as noise reduction, where a preview update can take even a second (depending on your CPU and preview size). The solution is for RawTherapee to wait for a very short period from the moment you stop moving a slider (you don't have to let go of it, pausing movement is enough) until the moment it sends a signal for the preview to be refreshed.

We have introduced two parameters which control the length of this waiting period:
; AdjusterMinDelay
: Default value = 100ms.
: This is used for tools with a very fast response time, for example the exposure compensation slider.
; AdjusterMaxDelay
: Default value = 200ms.
: This is used for tools with a slow response time, for example the CIECAM02 sliders.

You can adjust both of these values in the options file in the [[File_Paths|config folder]].

== The Left Panel ==

To the left is a panel which optionally shows the main histogram ("''Preferences > General > Layout > Histogram in left panel''"), and always shows the ''Navigator'', ''History'' and ''Snapshots''.
You can hide this panel using the [[Image:panel-to-left.png|Hide left panel icon]] hide icon, or its [[Keyboard Shortcuts|keyboard shortcut]].

=== Main Histogram ===

[[File:Rt57 histogram wide labeled.png|none|frame|class=heroed|Histogram showing all 3 channels and luminosity.]]

[[File:RT57 histogram ani.gif|frame|The histogram in RawTherapee 5.7, showing a histogram of the raw data in all three modes - linear-linear, linear-log and log-log. We can see that the raw file is not clipped.]]

[[File:Rt histogram rgbindicator.png|frame|The RGB indicator shows the position in the histogram of the R, G, B and L values of the pixel your cursor is hovering over.]]

A histogram in photography is a graphical representation of the number of pixels of a given value. Typically the horizontal axis represents the range of possible values while the vertical axis represents the count of pixels with that value. The axes need not be linear - RawTherapee can also scale the histogram logarithmically.

Regardless of the photo's bit depth, the histogram itself has a precision of 256 sampling bins. To understand this, let us look at the example of a 16-bit image using integer precision. Its range of possible values spans from 0 to 65535 (2^16 = 65536 possible values, and since 0 is a possible minimum value then the maximum value is 65535). Drawing a histogram using 16-bit precision would mean that it would need to be 65535 pixels wide to faithfully represent the data, and no screen today is anywhere near that wide. Instead, all pixels with values from 0 to 255 (65535/256*1) are grouped into the first "bin". The second bin consists of a count of all pixels with values from 256 to 511 (65535/256*2). The third bin represents values 512 to 767 (65535/256*3). And so on until bin 256. This happens regardless of the input image's bit depth - and RawTherapee's engine uses 32-bit floating-point precision anyway.

The main histogram can simultaneously show one or more of the following:
* [[File:Histogram-red-on-small.svg]] the red channel,
* [[File:Histogram-green-on-small.svg]] the green channel,
* [[File:Histogram-blue-on-small.svg]] the blue channel,
* [[File:Histogram-silver-on-small.svg]] CIELab luminance,
* [[File:Histogram-gold-on-small.svg]] [http://en.wikipedia.org/wiki/Chromaticity chromaticity].
* [[File:Histogram-bayer-on-small.svg]] red, green and blue channels of the source raw image before demosaicing.

The histogram shows the channels listed above using the gamma-corrected output profile when the gamut button [[File:Gamut-hist.png]] is disabled (default), or using the working profile when the button is enabled. The status of this button also affects the values shown in the Navigator panel, as well as the clipped shadow [[File:Warning-shadows.png]] and [[File:Warning-highlights.png]] highlight indicators. It does not affect the raw histogram.

Like water in a pipeline, image data flows through RawTherapee from the input file through various stages, most of which the user can control, to the output. The output could be the image saved in a file, or the image displayed on your screen. Each stage affects the color data. The histogram allows you to visualize this data at several stages. By default, the histogram shows color data as it will appear if you save the output image, including processing done at all intermediate stages. By enabling the gamut button [[File:Gamut-hist.png]] you can peak at the data at the early stage where it gets converted into the working space. You can even look at the raw data before any transformations or demosaicing are applied.

Let's examine the large histogram example above. Though it actually shows four histograms (red, green, blue and luminance), focus on one histogram at a time. The horizontal axis represents the possible values of the histogram, where "A" are the darkest values possible, "C" the mid-tones, and "E" the brightest possible values. The position of the histogram line on the vertical axis represents how many pixels have that value. We can see that there are zero pixels in the red channel with values around "A" (from zero to very dark), because the histogram line lies right along the bottom. There is a significant number of pixels where the red channel is dark (between A and B), and a significant number where it is light (around D). Then, importantly, there is a spike at the right end of the histogram, at E - it tells us that a large number of pixels have maximal red values - they are clipped.

Generally speaking, you should care when clipping occurs on skin, and not care when it's due to [https://en.wikipedia.org/wiki/Specular_highlight specular highlights]. If a histogram shows clipping, and if you care about the clipped regions, you should start by establishing where the clipping occurs. Check the raw histogram - are any channels clipped? If yes, then maybe [[Exposure#Highlight_Reconstruction|highlight reconstruction]] can help. If the raw histograms are not clipped, then all the required information is intact, and it is some stage downstream in the pipeline which causes clipping. Ensure your working profile's gamut is large enough by enabling the gamut button [[File:Gamut-hist.png]] to see histograms at the working profile stage of the pipeline. You might want to temporarily apply the [[Neutral]] profile to disable all the tools while checking, then revert. If your working space is not causing clipping (the default working space is ProPhoto and it's huge), then it's likely your adjustments which are causing clipping. Reduce exposure, go easy on the curves, use dynamic range compression if necessary.

Knowing how to read a histogram is a basic and very useful skill, as it can point out issues with your image regardless of how dim or miscalibrated your monitor may be.

To help you visualize the data, the histogram (as of RawTherapee 5.5) has three modes which scale the data in the x and y axes differently:
* [[File:Histogram-mode-linear-small.png]] Linear-linear mode. You find gridlines at halves, quarters, eighths and sixteenths, depending on the size of the histogram.
* [[File:Histogram-mode-logx-small.png]] Linear-log mode. The x-axis is linear, the y-axis and the horizontal gridlines are scaled logarithmically. The position of the gridlines still corresponds to the halves, quarters, etc.
* [[File:Histogram-mode-logxy-small.png]] Log-log mode. Both the x- and y-axes are scaled logarithmically. The gridlines are not scaled logarithmically, but correspond to [https://en.wikipedia.org/wiki/Exposure_value stops] - with every gridline the value doubles, so there are lines for the values 1, 3, 7, 15, 31, 63, and 127 (<code>pow(2.0,i) - 1)</code>).

When there is a disproportionately bright area relative to the rest of the image, it will show up as a spike in the histogram. If you want to show this on a histogram with a linear y axis, the spike may push the lesser values down the y-axis, making them difficult to see. Switch to one of the log modes to scale the data and help you get a better overview of all values.

The histogram can be moved to the left/right panel from "''Preferences > General > Layout > Histogram in left panel''".

==== Raw Histograms ====

Raw files contain a dump of data captured by the sensor and quantified by the analog-to-digital converter. The raw file as a container has a bit depth of its own, typically 16-bit, while the data it contains could have a lower bit depth - typically it is 12-bit (0-4096) or 14-bit (0-16384). To display the data from a raw file as an image, one of the several key bits of information required to process the data correctly are the black and white levels. The black level is not necessarily 0, as the sensor and camera electronics produce digital noise, so the noise floor may lie for instance at 512. The white level is also not necessarily 16384; it depends on various things, and may lie for instance at 16300. For more information, see the articles [[Demosaicing]] and [[Adding Support for New Raw Formats]] (especially the header of the <code>camconst.json</code> file). The black and white level values used by RawTherapee are hierarchically set by looking in several places: in <code>dcraw.c</code>, inside the raw file's metadata, and in <code>camconst.json</code> (latter takes precedence). Furthermore, the user can tweak the raw [[Raw Black Points|black]] and [[Raw White Points|white]] levels from within RawTherapee.

The raw histograms show data after black level subtraction. The right end of the histogram is anchored on the white level. The raw histograms are affected by the detected black and white levels as well as by the black and white level adjustments made by the user in RawTherapee.

When examining the raw histogram, you may also want to set the demosaicing method to "none". This will reveal the sensor pattern in the preview, and also cause the [[Editor#Navigator|Navigator]] panel to show the raw RGB values of the pixel currently being hovered over. These values are affected by the detected black and white levels as well as by the black level adjustments made by the user in RawTherapee, but they are not affected by the white level adjustments ("white-point correction") made by the user in RawTherapee.

=== Navigator ===

The ''Navigator'' panel shows a thumbnail of the currently opened image, and RGB, HSV and Lab values of the pixel your cursor is currently hovering over.

The values shown in the main histogram and Navigator panel are either those of the working profile or of the gamma-corrected output profile, depending on the state of the gamut button [[File:Gamut-hist.png]] located in the toolbar above the main preview. When the gamut button is enabled the working profile is used, otherwise the gamma-corrected output profile is used.

By clicking on the values in the Navigator you can cycle between these three formats:
* [0-255]
* [0-1]
* [%]

RawTherapee 5.1 onward can show the real raw photosite values. To see them, set the Navigator to use the [0-255] range, apply the [[Neutral]] [[Sidecar_Files_-_Processing_Profiles|processing profile]], then set the [[Demosaicing]] method to "None". The Navigator will show the real raw photosite values after black level subtraction within the range of the original raw data.

=== History ===

The History panel contains a stack of entries which reflect each of your image editing actions. By clicking on the entries you can step back and forth through the different stages of your work.

An entry is added each time you adjust a ''different'' widget - multiple edits to the same widget are stored as one entry. For example, adjusting the exposure compensation slider from "0" to "0.3" and then to "0.6" will result in one entry being stored with a final value of "0.6". Likewise, when adjusting a curve, all individual control point adjustments are grouped into one history entry. Should you wish to store the adjustments as two (or more) history entries, you will have to split them by adjusting some other widget. For example, assuming a curve is in "Film-like" mode and you want to keep to that way: adjust several control points on the curve, then toggle the curve mode from "Film-like" to "Standard" and then back to "Film-like" to create a new history entry, and then continue adjusting the curve.

The history stack is not saved - it is lost as soon as you close the Editor tab. None of your adjustments are lost though, as the final state of all tools is saved in the [[Sidecar Files - Processing Profiles|sidecar file]], ready to be used the next time you open that image.

=== Snapshots ===

Under the ''History'' panel is a panel called ''Snapshots''. Its use is in that you can save a snapshot of the photo with all the adjustments up to that point in time, and then proceed to further modify your photo to give it a different appearance, saving new snapshots at every moment you feel you might have reached a version of your photo worth saving. Once you have two or more snapshots, you can just click on them to flip through the different versions and stick with whichever one you like best. In the future, the snapshots will be saved to the PP3 sidecar file. For now, the history and snapshots are lost when you load a new photo in the ''Image Editor'' or close RawTherapee.

== The Right Panel ==

To the right is a panel which optionally shows the main histogram and ''Processing Profiles'' selector ("''Preferences > General > Layout > Histogram in left panel''"), and always shows the [[Toolbox]].
You can hide this panel using the [[Image:panel-to-right.png|Hide right panel icon]] hide icon, or its [[Keyboard Shortcuts|keyboard shortcut]].

=== Processing Profile Selector ===

In the top right corner you find options to apply and store specific processing profiles:

[[File:Processing-profiles-selector.png|center|frame]]

Read the page on [[Sidecar_Files_-_Processing_Profiles | processing profiles]] for more information.

=== Toolbox ===

The ''Toolbox'', in the right panel, contains all the tools you use to tweak your photos. Each tool has its own RawPedia article.

== Editor Tab Modes ==

RawTherapee allows you to work on photos in two modes:
* ''Single Editor Tab Mode'' (SETM), where you work only on one photo at a time, and each photo is opened in the same ''Editor'' tab. There is a horizontal panel called the ''[[The_Image_Editor_Tab#The_Filmstrip | Filmstrip]]'' at the top of the ''[[The_Image_Editor_Tab#The_Filmstrip | Editor]]'' tab showing the rest of the photos in that folder for easy access. There are ''Previous Image'' and ''Next Image'' [[File:Nav-prev.png]] [[File:Nav-next.png]] buttons in the bottom toolbar (and [[Keyboard Shortcuts | keyboard shortcuts]] for them) to switch to the previous/next image.
* ''Multiple Editor Tabs Mode'' (METM), where each photo is opened in its own ''[[The_Image_Editor_Tab#The_Filmstrip | Editor]]'' tab. The ''[[The_Image_Editor_Tab#The_Filmstrip | Filmstrip]]'' is hidden in this mode and there are no previous/next buttons. Having multiple photos opened at the same time requires more RAM.

Try both modes and see which one suits you best. To do that, click on the ''Preferences'' icon [[image:preferences.png|Preferences icon]] in the bottom-left or top-right corner of the RT window, choose "''General > Layout''" and set ''Editor Layout'' to your preferred choice.

Use this ''Preferences'' window to select a different language for the user interface, to choose a different color theme, change the font size, etc.

It is also possible to start RawTherapee in no-File-Browser-mode (without the ''File Browser'' tab) by specifying RawTherapee to open an image from your operating system's file browser (in other words, right-click on a photo and select "''Open With > RawTherapee''"), or by using the image filename as an argument when starting RawTherapee from the command line (<code>rawtherapee /path/to/some/photo.raw</code>). This mode was introduced for people with little RAM as not having a ''File Browser'' tab means RawTherapee uses a little less memory, however in practice the amount of memory saved is little and the usability cost outweighs the little benefit, so it is likely to be removed in the future (see [https://code.google.com/p/rawtherapee/issues/detail?id=2254 issue 2254]).

== The Filmstrip ==

[[File:Rt filmstrip 21 toolbar-visible.jpg|none|frame|class=heroed|RawTherapee-4.2 showing the Filmstrip with the toolbar visible, which takes up more screen space but lets you easily label, rate and filter the visible thumbnails.]]
[[File:Rt filmstrip 21 toolbar-hidden.jpg|none|frame|class=heroed|RawTherapee-4.2 showing the Filmstrip with the toolbar hidden, which makes it less high and provides more screen space for the main preview (partially visible at the bottom).]]

If you use ''Single Editor Tab Mode'' ("''Preferences > General > Layout''") you can display a horizontal panel above the preview, this is called the ''Filmstrip''. It contains thumbnails of all images in the currently opened album, and is synchronized with the currently opened image so that you can use [[Keyboard Shortcuts|keyboard shortcuts]] or the previous [[Image:nav-prev.png|Open previous image icon]] and next [[Image:nav-next.png|Open next image icon]] image buttons to open the previous/next image without needing to go back to the ''[[The File Browser Tab|File Browser]]'' tab.

As of RawTherapee version 4.2.10, you can hide the Filmstrip's toolbar to save screen space. There are two ways of doing this: one way just toggles the toolbar on/off without resizing the filmstrip to the new height, and the other way does the same but also automatically resizes the filmstrip's height. Both are invoked via [[Keyboard Shortcuts|keyboard shortcuts]] only. As resizing the filmstrip's height will trigger a refresh of the image preview and this might take a while if using CPU-hungry tools like noise reduction while zoomed in at 100%, the mode that doesn't resize has been implemented for users with slow machines. Users with fast machines will find the auto-resizing mode more helpful.

== Monitor Profile and Soft-Proofing ==

The widgets under the main preview in RawTherapee 5 allow you to apply a monitor color profile to the preview image. This enables users who have calibrated and profiled their monitors to get an instant and accurate preview of their work, whether you're staying in sRGB or working in a wide gamut. Note: OS X users are limited to sRGB and will not get an accurate preview otherwise ([https://discuss.pixls.us/t/wide-gamut-preview-in-os-x/2481 see discussion]), while users of Linux and Windows will get a correct wide-gamut preview.

Go to Preferences > [[Preferences#Color_Management_Tab|Color Management]] and point the "Directory containing color profiles" to the folder into which you saved your monitor and printer ICC profile. Restart RawTherapee for the changes to take effect. Now you will be able to select your monitor's color profile in the combo-box under the preview. Use the "Relative Colorimetric" rendering intent unless you have a good reason otherwise.

One can also enable soft-proofing of the preview. This will show you what your image will look like once it gets transformed by the printer profile set in Preferences > [[Preferences#Color_Management_Tab|Color Management]]. If you want to adjust an image for printing and you have an ICC profile for your printer-paper combination you could set that as your output profile, enable "Black point compensation" in Preferences so that the blackest black in your image will match the blackest black your printer-paper combination is capable of reproducing, then enable soft-proofing. You will see what your image will look like if you print it. This allows you to make adjustments and get an instant preview of the result, saving you time and ink on test prints.

The icon with exclamation mark next to the soft-proofing button will gray out areas that cannot be reproduced by your printer, i.e. areas where you will loose details.

You should have a calibrated and profiled monitor in order for the soft-proofing preview to be accurate.

The items you see in the monitor profile combo-box (under the main preview) and in the printer profile combobox (in Preferences > [[Preferences#Color_Management_Tab|Color Management]]) are ICC files located in a folder which you can point RawTherapee to by going to "[[Preferences]] > [[Preferences#Color_Management_Tab|Color Management]] > Directory containing color profiles".

Queue

2021-07-08T19:11:01Z

Thanatomanic: Typo fixed GitHub issue #6300

<div class="pagetitle">The Queue</div>

== Introduction ==

[[Saving Images|Saving images]] from RawTherapee can be done in several ways, the two most common of which are either saving the image immediately [[File:Save.png]] from the Editor tab, or adding it to the batch processing queue [[File:Gears.png]] which resides in the Queue tab.

Using the "Save immediately" feature will put your CPU immediately to work, and as a result, opening and tweaking other images in the Editor will be somewhat slow while the image is being saved. The queue mechanism allows you to put edited images which are ready to be saved to a virtual queue which you can start processing at a later time. Adding them to the queue is instant, so you can continue editing other images and making the most of your CPU for editing. Once you are done editing and putting images to the queue, you can flip the large "On" switch and go off to brew yourself a coffee while RawTherapee grinds away at all the images in the queue.

The queue is persistent - you can exit RawTherapee and restart it later; the queued images will still be there. The queue can even survive a crash.

== Adding Images to the Queue ==

There are several ways of adding an image to the queue:
# When you are done tweaking an image in the Editor, click the "Put current image to processing queue" button [[File:Gears.png]].
# Also in the Editor tab, click the "Save current image" button [[File:Save.png]] and select "Put to the head/tail of the processing queue".
# Right-click on a thumbnail in the [[File Browser]] or the [[Editor#The_Filmstrip|Filmstrip]] and select "Put to queue".

Regardless which method you use, when you go to the ''Queue'' tab you will see your photos lined up, ready for processing (if you had the queue set to "Auto-start", it may have finished processing before you viewed it).

== Queue Settings ==

[[File:Save window.png|thumb|500px|right|The "Save current image" window. Notice the "Force saving options" checkbox, which is disabled in the screenshot because neither of the "Put to the head/tail of the processing queue" options are enabled.]]

The Queue has several settings, such as the output file format and destination. These settings take effect in all cases except when you use the "Save current image" button [[File:Save.png]], select "Put to the head/tail of the processing queue" and enable the "Force saving options" checkbox. In this case, the settings seen in the "Save" window will be used, and the ones from the Queue tab ignored. In all other cases, the settings from the Queue tab will be used.

The settings speak for themselves. Two things worth pointing out:
# "Save processing parameters with image" will save a sidecar file alongside the output file, with the same filename as the output image but with a ".pp3" extension. This is useful when you want to save multiple copies of the same photo, each one tweaked a bit differently.
# The destination folder can be set by selecting "Save to folder", but if you need to dynamically customize the destination folder and filename then select "Use template" instead. Hover your mouse over the ''Use template'' input box and a tooltip with an explanation will pop up:

Specify the output location based on the source photo's location, rank, trash status or position in the queue.

Using the following pathname as an example:
<b>/home/tom/photos/2010-10-31/photo1.raw</b>
the meaning of the formatting strings follows:
<b>%d4</b> = <i>home</i>
<b>%d3</b> = <i>tom</i>
<b>%d2</b> = <i>photos</i>
<b>%d1</b> = <i>2010-10-31</i>
<b>%f</b> = <i>photo1</i>
<b>%p1</b> = <i>/home/tom/photos/2010-10-31/</i>
<b>%p2</b> = <i>/home/tom/photos/</i>
<b>%p3</b> = <i>/home/tom/</i>
<b>%p4</b> = <i>/home/</i>

<b>%r</b> will be replaced by the photo's rank. If the photo is unranked, '<i>0</i>' is used. If the photo is in the trash, '<i>x</i>' is used.

<b>%s1</b>, ..., <b>%s9</b> will be replaced by the photo's initial position in the queue at the time the queue is started. The number specifies the padding, e.g. <b>%s3</b> results in '<i>001</i>'.

If you want to save the output image alongside the source image, write:
<b>%p1/%f</b>

If you want to save the output image in a folder named '<i>converted</i>' located in the source photo's folder, write:
<b>%p1/converted/%f</b>

If you want to save the output image in
'<i>/home/tom/photos/converted/2010-10-31</i>', write:
<b>%p2/converted/%d1/%f</b>

== Running the Queue ==

In the top-left corner of the Queue tab you will find an "On/Off" switch, and an "Auto-start" checkbox.
# If "Auto-start" is enabled, processing will start as soon as an image is sent to the queue. Usually you will not want this, as this will use your CPU for processing the photos in the queue leaving very little CPU time for allowing RawTherapee to be responsive while you tweak other photos.
# If "Auto-start" is not checked, you will have to activate the queue manually by hitting the "On/Off" switch.

You can pause the queue by hitting the "On/Off" switch - RawTherapee will first finish processing the current photo.

== Clearing the Queue ==

You can remove a specific image from the queue by clicking the small "Cancel job" [[File:Cancel-small.png]] button in the corner of each thumbnail.

You can clear the whole queue right-clicking on a thumbnail and clicking "Select all" and "Cancel job", or by using the {{k|Ctrl}} + {{k|a}} keyboard shortcut to select all thumbnails and then hitting the {{k|Delete}} key on the keyboard.

Queue

2021-07-08T19:10:26Z

Thanatomanic: Typo fixed GitHub issue #6300

<div class="pagetitle">The Queue</div>

== Introduction ==

[[Saving Images|Saving images]] from RawTherapee can be done in several ways, the two most common of which are either saving the image immediately [[File:Save.png]] from the Editor tab, or adding it to the batch processing queue [[File:Gears.png]] which resides in the Queue tab.

Using the "Save immediately" feature will put your CPU immediately to work, and as a result, opening and tweaking other images in the Editor will be somewhat slow while the image is being saved. The queue mechanism allows you to put edited images which are ready to be saved to a virtual queue which you can start processing at a later time. Adding them to the queue is instant, so you can continue editing other images and making the most of your CPU for editing. Once you are done editing and putting images to the queue, you can flip the large "On" switch and go off to brew yourself a coffee while RawTherapee grinds away at all the images in the queue.

The queue is persistent - you can exit RawTherapee and restart it later; the queued images will still be there. The queue can even survive a crash.

== Adding Images to the Queue ==

There are several ways of adding an image to the queue:
# When you are done tweaking an image in the Editor, click the "Put current image to processing queue" button [[File:Gears.png]].
# Also in the Editor tab, click the "Save current image" button [[File:Save.png]] and select "Put to the head/tail of the processing queue".
# Right-click on a thumbnail in the [[File Browser]] or the [[Editor#The_Filmstrip|Filmstrip]] and select "Put to queue".

Regardless which method you use, when you go to the ''Queue'' tab you will see your photos lined up, ready for processing (if you had the queue set to "Auto-start", it may have finished processing before you viewed it).

== Queue Settings ==

[[File:Save window.png|thumb|500px|right|The "Save current image" window. Notice the "Force saving options" checkbox, which is disabled in the screenshot because neither of the "Put to the head/tail of the processing queue" options are enabled.]]

The Queue has several settings, such as the output file format and destination. These settings take effect in all cases except when you use the "Save current image" button [[File:Save.png]], select "Put the the head/tail of the processing queue" and enable the "Force saving options" checkbox. In this case, the settings seen in the "Save" window will be used, and the ones from the Queue tab ignored. In all other cases, the settings from the Queue tab will be used.

The settings speak for themselves. Two things worth pointing out:
# "Save processing parameters with image" will save a sidecar file alongside the output file, with the same filename as the output image but with a ".pp3" extension. This is useful when you want to save multiple copies of the same photo, each one tweaked a bit differently.
# The destination folder can be set by selecting "Save to folder", but if you need to dynamically customize the destination folder and filename then select "Use template" instead. Hover your mouse over the ''Use template'' input box and a tooltip with an explanation will pop up:

Specify the output location based on the source photo's location, rank, trash status or position in the queue.

Using the following pathname as an example:
<b>/home/tom/photos/2010-10-31/photo1.raw</b>
the meaning of the formatting strings follows:
<b>%d4</b> = <i>home</i>
<b>%d3</b> = <i>tom</i>
<b>%d2</b> = <i>photos</i>
<b>%d1</b> = <i>2010-10-31</i>
<b>%f</b> = <i>photo1</i>
<b>%p1</b> = <i>/home/tom/photos/2010-10-31/</i>
<b>%p2</b> = <i>/home/tom/photos/</i>
<b>%p3</b> = <i>/home/tom/</i>
<b>%p4</b> = <i>/home/</i>

<b>%r</b> will be replaced by the photo's rank. If the photo is unranked, '<i>0</i>' is used. If the photo is in the trash, '<i>x</i>' is used.

<b>%s1</b>, ..., <b>%s9</b> will be replaced by the photo's initial position in the queue at the time the queue is started. The number specifies the padding, e.g. <b>%s3</b> results in '<i>001</i>'.

If you want to save the output image alongside the source image, write:
<b>%p1/%f</b>

If you want to save the output image in a folder named '<i>converted</i>' located in the source photo's folder, write:
<b>%p1/converted/%f</b>

If you want to save the output image in
'<i>/home/tom/photos/converted/2010-10-31</i>', write:
<b>%p2/converted/%d1/%f</b>

== Running the Queue ==

In the top-left corner of the Queue tab you will find an "On/Off" switch, and an "Auto-start" checkbox.
# If "Auto-start" is enabled, processing will start as soon as an image is sent to the queue. Usually you will not want this, as this will use your CPU for processing the photos in the queue leaving very little CPU time for allowing RawTherapee to be responsive while you tweak other photos.
# If "Auto-start" is not checked, you will have to activate the queue manually by hitting the "On/Off" switch.

You can pause the queue by hitting the "On/Off" switch - RawTherapee will first finish processing the current photo.

== Clearing the Queue ==

You can remove a specific image from the queue by clicking the small "Cancel job" [[File:Cancel-small.png]] button in the corner of each thumbnail.

You can clear the whole queue right-clicking on a thumbnail and clicking "Select all" and "Cancel job", or by using the {{k|Ctrl}} + {{k|a}} keyboard shortcut to select all thumbnails and then hitting the {{k|Delete}} key on the keyboard.

Color Management

2021-06-19T10:24:02Z

Thanatomanic: Added GUI figure

<div class="pagetitle">Color Management</div>

Color management comprises all tasks to ensure a faithful representation of colors from scene to intermediate formats, editors and various output media. This is an often complicated and technical matter that RawTherapee tries to handle as correctly as possible behind the scenes. More can be read about it [http://rawpedia.rawtherapee.com/Color_Management_addon here]. The various options of the Color Management tool are explained below.

== Input Profile ==

An essential first step in raw processing is the faithful conversion of the [[Demosaicing#Introduction|camera sensor data]] to an internal RGB color space. This conversion requires an input profile made specifically for the camera. Such a profile is the result of the analysis of how specific colors and tones are captured, processed and represented as raw data by the camera (for more details, see e.g. [https://ninedegreesbelow.com/photography/articles.html#profile-digital-camera Elle Stone's article], [https://torger.se/anders/dcamprof.html DCamProf's documentation] or [[How to create DCP color profiles]]. Without a camera-specific input profile, accurate color representation is impossible.

The input profile is applied to the image data at the beginning of RawTherapee's [[Toolchain_Pipeline|processing pipeline]] because most tools depend on it. There are several ways to apply an input profile.

[[File:ColorManagement-InputProfile-GUI.jpg|right|frame|RawTherapee's interface for choosing the input profile]]

==== No Profile ====

No color conversion will take place and a unit transform of the image data is applied. '''Do not use this for regular editing.''' Applying no input profile is generally only useful for analytical purposes to show images in the camera's native RGB color space, or in extreme cases to prevent clipping of channels when the camera has recorded colors outside of conventional gamuts.

Note that selecting 'No Profile' for non-raw files bypasses the embedded color profile and the working profile will be assigned. This means that gamma-encoded files (e.g. sRGB) will be assumed linear, making them look brighter.

==== Use embedded, if possible ====

Only available for non-raw files. The embedded color profile is used. Which profile is embedded can be checked with GIMP for example.

==== Camera Standard ====

A conversion takes place based on profiled information from either of three sources, in decreasing priority:
* The <code>dcraw_matrix</code> field in the <code>camconst.json</code> data file available in RawTherapee's installation directory;
* Hard-coded values provided by the <code>dcraw</code> library embedded within RawTherapee;
* The raw file itself.

There is one exception: when a DNG raw file has a <code>ColorMatrix2</code> Exif tag and was not generated by the Adobe DNG Converter, the matrix from the Exif data is prioritized above all others.

Applying an input profile is nothing more than a linear algebra operation on the image data. The input profile consists of a square matrix (3×3 for RGB based sensors) that is multiplied with the pixel vectors of camera-native RGB values. These matrices are specifically calibrated for a specific illuminant ([https://en.wikipedia.org/wiki/Illuminant_D65 D65], i.e. 6500K) and provide the most accurate color reproduction if the scene illuminant matches the calibration illuminant. However, the color accuracy is usually still good enough for very different light sources and white balances.

The benefit of a matrix profile over other profiles (e.g. table-based DCP or ICC profiles) is its linearity. Because no non-linear functions are applied to the data, the scene-referred linearity of the light intensities is kept intact. This is important for several image processing operations and for example when exporting for further editing (e.g. HDR applications usually require a predictable linear color response).

==== Auto-Matched Camera Profile ====

RawTherapee allows you to use custom '''DCP''' (Adobe DNG Camera Profile) or '''ICC''' (International Color Consortium) color input profiles. These can be tailor-made to specific scene conditions to provide the most accurate color rendition, or to generally improve upon the standard matrix profiles available.

RawTherapee ships multiple high-quality, custom-made, general-purpose DCP profiles that can be automatically matched when an image from a supported camera is opened. The available profiles are found in the <code>dcpprofiles</code> folder in your installation directory. It is possible to add your own DCP or ICC profiles to this folder. Matching only works on the exact name of the camera (case-sensitive) as is present in the image metadata.

Most provided DCP profiles are dual-illuminant (see [[Color_Management#DCP_Illuminant|below]]) and some provide tone curves and looks as well. New profiles are added exclusively based on user submission. Please read [[How to create DCP color profiles]] for further instructions in case you want to contribute.

==== Custom ====

Specify a custom DCP or ICC camera input profile when an automatic match is not available, or if you want to override the standard or matched profile. DCP profiles for your camera may be available through the Adobe DNG Converter. Read [[How to get LCP and DCP profiles]] for further information.

Be aware that when you load a custom ICC profile that it is an ''input'' profile. ICC profiles can be created for a multitude of purposes (printers, displays, etc.) and not all profiles are suited as a camera input profile. Your results may vary.

=== DCP ===

==== DCP Illuminant ====

Some of RawTherapee's profiles are single-illuminant (Daylight/D50), while others are double-illuminant (Daylight/D50 and Tungsten/StdA). If a dual-illuminant profile is loaded the "DCP Illuminant" setting will be enabled and you can choose which illuminant to use. The actual DCP standard (part of the DNG standard) does not provide this choice, but instead an interpolation between the two illuminants is calculated based on the chosen white balance (there will only be an interpolation if the white balance is in-between both illuminants, otherwise the closest is picked). This "interpolated" mode is the default setting of "DCP Illuminant" and for any normal use you do not need to change this.

You can however choose to base the color rendering on one of the specific illuminants. In some cases this might produce more pleasing color. It can also be interesting for diagnostic purposes to see how large (or small) a difference there is in color rendering between the illuminants, but, as said, for general use this setting should be untouched.

==== DCP Tone Curve ====

Some DCPs contain a tone curve which may be used to add contrast and brightness to provide a film-like look. This is mainly used for profiles simulating camera maker settings. The tone curve checkbox will be disabled for profiles which do not contain a tone curve.

The curve mode used by the DCP tone curve is the same as the Exposure tool's "[[Exposure#Film-Like|film-like]]" mode, meaning you can reproduce the effect using the Exposure tool's tone curves in film-like mode. When contrast is applied with a film-like curve the appearance of the colors will change and overall saturation is increased, except for bright colors which instead are de-saturated. Some profiles which have curves embedded are pre-corrected for this color appearance change and will thus not provide the intended look without the curve applied. Most will however work well without the tone curve applied especially if you add a similar curve yourself using the Exposure tool's curves, but if you want to see exactly how the profile designer intended the colors to look you should enable the tone curve.

While the input color profile is applied at the first stages of the [[Toolchain_Pipeline|toolchain pipeline]], the DCP tone curve is applied later in the pipeline at some point after the Exposure tool.

{{acrrtc}}

If the DCP profile has a copyright tag with the value "Adobe Systems", regardless whether it contains a tone curve or not, RawTherapee will automatically create a tone curve shaped identically to the Adobe Camera Raw curve. The reason for this is so that using the DCP in RawTherapee can match the results of using that DCP in Lightroom. This is why the "Tone curve" checkbox will not be grayed-out when using a DCP profile which has no embedded tone curve, as long as it has the copyright tag set as described.

==== DCP Base Table ====

This enables the DCP "HueSatMap" lookup table which is used to add non-linear corrections on top of the basic matrix. This is an advanced user setting and unless you want only the pure matrix result should leave it on. It's grayed out if the loaded profile lacks a HueSatMap table.

==== DCP Look Table ====

This enables the DCP "LookTable" lookup table which is intended to add a subjective look on top generally together with an embedded tone curve. That is if you disable the DCP curve and looktable you may get a neutral "colorimetric" profile, if the DCP was designed that way which is not always the case (if the DCP has both a look table and a base table it's likely that it is, but if it only has a look table it will probably not work well with it disabled). Disabling individual DCP elements are considered advanced user settings, normally you would leave this on.

==== DCP Baseline Exposure ====

The DCP may indicate an exposure offset that corresponds to an offset of the exposure slider. The purpose of this is typically to make the brightness of the image match the brightness of the camera's own JPEGs, which can be useful if you're shooting with auto-exposure. Currently this offset is applied "under the surface" so you don't see it on the exposure slider.

Note that if you are using Adobe's proprietary profiles those are expecting that the DNG's "baseline exposure" tag is applied too (the profile's offset is added on top). Currently there is no support for the DNG tag so you need to find that out on your own (using exiftool for example) and then set that offset using the exposure slider if you want to get the exact same brightness as in Adobe Camera Raw.

=== Implementation Notes ===

==== Third-Party DCP Support ====

The DNG Camera Profile, DCP, is the preferred camera input profile format for RawTherapee. All elements of the 1.4 DNG specification are supported, with the exception of the black render tag (see below). A DCP can be a pure matrix profile, it can have a LUT (typically 2.5D) to improve the colorimetric accuracy, and then it can have an embedded curve and a separate "look table" on top. It may also add an exposure offset. All these elements can be toggled on/off via checkboxes. However, you should be aware that a profile will produce the most accurate colors when all the elements it was designed to include are enabled. For example, using a tone curve changes the color ''appearance'', so if you disable an embedded tone curve to get a linear profile you can't count on the colors being absolutely accurate. Nonetheless, most photographers rely on an aesthetically-pleasing appearance, and not on absolute accuracy, so this should not be a concern unless absolute accuracy is crucial. Typically, third-party profiles would come from Adobe Camera Raw/Lightroom/DNG Converter, and RawTherapee supports them. Many of Adobe's profiles lack a tone curve, but in Adobe's world that does not mean that no tone curve should be applied, but that Adobe's default curve should be applied. RawTherapee will therefore identify Adobe profiles (from the copyright string) and add the default curve to those (which you can toggle with the tone curve checkbox).

Adobe DNG Converter may add a "baseline exposure" to the DNG file. Some of Adobe's DCPs are designed to work with that baseline exposure and then produce a default output which is about the same brightness and contrast as the out-of-camera JPEG. RawTherapee can honor this baseline exposure if the DCP contains one.

The DCP format also has a black render tag. This indicates if the raw converter should do "automatic" black subtraction or not. RawTherapee ignores this tag - you can perform manual black subtraction with the [[Raw Black Points]] tool or with the [[Exposure#Black|black]] slider in the Exposure tool. As many of Adobe's profiles indicate auto black subtraction and Adobe Camera Raw/Lightroom does it, in those cases RawTherapee will render slightly lower contrast and brighter shadows.

==== Third-Party ICC Support ====

RawTherapee has specific support for ICC profiles bundled with Capture One and Nikon NX2, so those should work well. Older ICC profiles are not likely to work well though (typically the image becomes extremely dark with unsupported ICC profiles).

Some ICC profiles apply a tone-curve and desaturate bright highlights for a more film-like look. Those profiles may not work well together with [[Exposure#Highlight_Reconstruction|Highlight Reconstruction]]. If you see a radical change in contrast when you apply your ICC profile, it has applied a tone-curve and then you should not use it together with [[Exposure#Highlight_Reconstruction|Highlight Reconstruction]].

Unlike DCP profiles, ICC profile processing may cause clipping of extremely saturated colors during conversion. In practice this is rarely a problem, but still DCP should be considered the primary choice if available.

Note on using Capture One ICC profiles: RawTherapee applies the ICC before exposure adjustments, as the intention is that input profiles should only be used to make the colors more accurate, and not to apply a look - you design the look using the tools instead. Phase One's ICC profiles contain a subjective look though, which means that they typically contain "hue twists", for example saturation in the shadows is increased. This means that if you have an underexposed file and push it a few stops, those hue twists have been applied to the dark image before the exposure adjustment and will thus be in the wrong place after adjustment; that is you don't get the same look as in Phase One's Capture One. Therefore it is recommended to have the right exposure out of the camera when using Phase One ICC profiles. You should also apply a suitable RGB [[Exposure#Film-Like|film-like]] curve, as those ICC profiles are designed to be used together with that.

We are aware that LUT ICCs should typically be applied after exposure (just as DCP LookTables are applied), and that would support for example Capture One profiles better. This may be fixed in a future version.

=== Save Reference Image ===

Clicking the "Save Reference Image" button saves a linear TIFF image before the input profile is applied. This file can then be used for profiling, i.e. creating a camera input profile. You can use the open-source ArgyllCMS program to create ICC profiles, and DCamProf to create ICC or DCP profiles.

Cropping, resizing and transformations (rotation) will be applied, allowing you to make the output image more manageable by the receiving software. ArgyllCMS is very picky for instance, and requires that only the test target is visible in the image.

You can also choose if you want to export with white balance applied or not. For ICC profiles you should export with white balance applied, but if you intend to make a DNG profile or a dcraw-style color matrix you should export without applying white balance.

== Working Profile ==

The default working profile is ProPhoto and should not be changed for normal use.

The working profile specifies the working color space, which is the color space used for internal calculations, for instance for calculating saturation, RGB brightness/contrast and tone curve adjustments, chrominance, etc.

When RawTherapee was based on integer math it was wise to not use working space larger than absolutely needed to get the best precision in the calculations. However, RawTherapee had switched to floating-point processing in 2011, and since version 4.0.12 the default working profile is ProPhoto, which has a very large gamut.

The choice of working profile has an influence on the effect of the curves in all modes except for perceptual - in that mode, changing the working profile will not alter the effect of the curve. If you have trouble fitting colors within the output gamut you can experiment with changing the working profile when using curves in any mode but perceptual.

Note that the working profile will only specify the red, green and blue primaries, gamma will not change as RawTherapee's processing pipeline is floating point with no gamma encoding (that is gamma = 1.0). Some tools (like curves and histograms) will still display with a gamma (usually sRGB gamma) which is hard-coded for the tool and stays the same regardless of working profile.

=== Adding Custom Working Profiles ===

RawTherapee 5.5 allows you to specify custom working profiles through a [https://en.wikipedia.org/wiki/JSON JSON] file. The file should be named <code>workingspaces.json</code> and it can reside in:
* the ICC profile folder as set in [[Preferences#Color_Management_Tab|Preferences > Color Management > Directory containing color profiles]],
* or in RawTherapee's own ICC profile folder:
** Windows: <code><rt-install-folder>\iccprofiles</code>
** Linux:
*** When installed using your package manager or self-compiled with <code>BUILD_BUNDLE=OFF</code>: <code>/usr/share/rawtherapee/iccprofiles</code>
*** When self-compiled with <code>BUILD_BUNDLE=ON</code>: <code><rt-install-folder>/iccprofiles</code>
** macOS: <code>/library/ColorSync/Profiles/Displays</code>

The format of <code>workingspaces.json</code> is as follows:
<pre style="white-space: pre-wrap">
{"working_spaces": [
{
"name" : "ACES",
"file" : "/path/to/ACES.icc"
},
{
"name" : "ACEScg",
"matrix" : [0.7184354, 0.16578523, 0.09882643, 0.29728935, 0.66958117, 0.03571544, -0.00647622, 0.01469771, 0.66732561]
}
]}
</pre>

If "matrix" is present, "file" is ignored. If only "file" is present, the matrix is extracted from the ICC profile. For this, RawTherapee looks only at the R, G, and B matrix columns and the white point set in the profile. Bradford adaptation is used to convert the matrix to D50. Anything else in the profile (LUT, TRC, etc.) is ignored.

It is the user's responsibility to ensure that the profile is suitable to be used as a working space.

==Abstract Profiles==

===What is an Abstract profile?===

* According to the International Color Consortium (ICC), Abstract profiles allow you to perform custom image effects, such as applying a particular “look” to a series of images. Such a profile allows you to define CIELAB (or CIEXYZ) values as both Input and Output. This means you can algorithmically define whatever color changes you like and produce the corresponding LUT. A small number of color management applications support the creation and/or use of Abstract profiles.
* In the case of RawTherapee this is achieved using the Virtual profiles in LCMS, which allow you to modify the data using the same algorithms and principles as those used for Input profiles or Output profiles i.e. by acting on one or more of the 3 ICC profile components i.e. Tonal response curve (TRC), Illuminant (white point) and Primaries.
* Is an Abstract profile part of color management? This is debatable but it is certainly more so than the Working profile, which is simply a transformation in C++ code that converts RGB data into XYZ. If we use the ICC and LCMS (virtual profile) definitions, the answer is definitely yes.
* Note that Abstract Profile only works with the provided working profile package: ACESp0, ACESp1, Adobe RGB, Best RGB, BetaRGB, BruceRGB, ProPhoto, Rec2020, sRGB, WideGamut. The use of "Adding Custom Working Profiles through a JSON file" is not possible.

===The CIE xy diagram===

The LCMS virtual profile modifies the "x" & "y" data, which is one of the possible representations of the colorimetry. This representation makes it possible to easily see:
* The limits of human vision in terms of visible frequencies from 380nm to 770nm.
[[File:ciexy-color.jpg|600px|thumb|center|Limits of human vision]]
* A triangular color-space model based on the primaries.
[[File:ciexy-3space.jpg|600px|thumb|center|Colorimetric spaces]]
* The curve showing the evolution of the white point (one of the bases of the illuminants D50, D65, Std A, ).
[[File:ciexy-wp.jpg|600px|thumb|center|White point]]
* Note that this representation must be interpreted with care, because it is a vertical projection of the gamut. A color that is outside the gamut triangle is necessarily out of gamut, but a color inside the triangle can also be out of gamut, because this projection ignores the luminance component.

====Some Primary values====

* sRGB - Red x=0.64 y=0.33 - Green x=0.30 y=0.60 - Blue x=0.15 y=0.06
* Rec2020 - Red x=0.708 y=0.292 - Green x=0.17 y=0.797 - Blue x=0.131 y=0.046
* ProPhoto - Red x=0.7347 y=0.2653 - Green x=0.1596 y=0.8404 - Blue x=0.0366 y=0.0001
* ACESp0 - Red x=0.7347 y=0.2653 - Green x=0 y=1.0 - Blue x=0.0001 y=-0.077

When one of the primaries is outside the limits of human vision we speak of imaginary colors.

===Use of data from the "CIE xy" diagram in Abstract profiles.===

[[File:cie-abstract_graph3.jpg|600px|thumb|center|Abstract profiles]]

You can modify the 3 components of the virtual profile as you wish. The screen capture represents a configuration allowing you to improve the "calibration" of the Input profile.
* In this example, the Working profile is Prophoto, where the primaries have not been modified. When you choose "Destination primaries” > Custom the algorithm will by default choose this particular Working profile to build the Abstract or Virtual profile.
* If you change "Destination primaries" to any value other than those used for the Working profile you can create special effects similar to those produced in the more familiar Color Toning or Channel Mixer modules.
* You can change the D50 Illuminant to another value, either to create or amplify some special effect, or adapt the illuminant to a specific case.

If the first combobox in the Abstract Profile panel is set to Custom, the CIE xy diagram will display the default working-profile values. i.e:
* The 3 primaries: Red, Green & Blue.
* The white point.
If the first combobox in the Abstract Profile panel is set to Custom or some other option (e.g. BT709 etc.), the CIE xy diagram will display:
* The primaries and the white point of the profile selected in the "Destination primaries" combobox.

In addition to the profile options in the "Destination primaries" combobox there are also two custom options.
* Custom (sliders):
** The sliders Red (X, Y), Green (X, Y) & Blue (X, Y) will be active.
** The combobox Illuminant will be active.
** Any changes to the slider values will be shown in the CIE xy diagram. Note that the "Custom (sliders)" option does not allow you to make changes directly on the graph.

* Custom (CIE xy diagram):
** You can modify the primaries directly on the graph using the mouse and the changes will be made automatically to the Red, Green & Blue sliders. Note that in this case you can only modify the slider positions by moving the points on the graph.
** The illuminant cannot be changed.

Note:
If we take the example shown in the screen capture above (with the sliders set to the ProPhoto primary values):
* When you move the red primary vertically upwards, reds will move towards magenta.
* If you move it down the reds move towards orange.
Note that the color shifts move in the opposite direction to the red primary. This is because moving the primary upwards causes the colors to rotate clockwise around the white point (shown in the diagram "the limits of human vision"). Moving the primary downwards causes the colors to rotate counterclockwise.
Similar behavior can be observed with the green and blue primaries.
* When you move the red primary to the left, (reducing the distance to the white point) the saturation will increase.
* If you move it to the right, the saturation should decrease but additional colors will be added. This behavior is normal.

Still using the same example:
* When you change the illuminant (in this case D50) to a lower temperature (D41, stdA), the reds will turn orange. If you change it to a higher temperature (D80, D120) the reds will turn magenta. This is also normal.

This behavior is "normal", but why? The reason is that we don't modify the Working profile. Instead, we modify the data that has already been modified in the processing pipeline. For didactic purposes, let's look at the operation of CIECAM02/16 in symmetrical mode. If the white balance is set to 7500K for example and it corresponds to the illuminant at the time of shooting, the image will have yellowish whites and an overall dominant red color. Cat02/16 chromatic adaptation will allow us to cool down the image by setting the temperature in Viewing Conditions to the corresponding white balance i.e. 7500K. The white balance acts as the Working profile upstream and chromatic adaptation acts as an Abstract profile downstream.

Note: the diagram is given for information only. The limits are not always very precise, especially towards the greens.

===Which data and profiles are used or modified?===

The Abstract profiles (Virtual profiles) implemented here:
* Do not change the Working profile.
* Do not modify the Input profile.
* Do not modify the Output profiles.
* But they modify the data in the same way as any other RawTherapee algorithm. Particular features:
** The Abstract profile, which corresponds to a virtual ICC profile in LCMS, acts as a patch at the end of the pipeline (just before Ciecam and just before the conversion to a screen profile or an Output profile). It acts on the 3 components of the ICC profile (Tone Response Curve, Illuminant (white point) & Primaries). Depending on the choices and settings, the image appearance can be modified as follows:
*** In depth by acting on the distribution of luminance and colors – rather like a Channel Mixer or Color Toning to which an extra dimension has been added.
*** On the luminance distribution via the TRC, either to change the default aspect, which in RawTherapee is an sRGB TRC, or to act as a Shadows/Highlights control.
*** To modify or refine the results of the Input profile with the help of a color chart (Colorchecker24 or other), either with the same illuminant that was used during the elaboration of the Input profile, or with another illuminant. In this case CIECAM will need to be used also.

===Three main uses (with or without CIECAM)===

* TRC: adjust gamma and slope to: a) modify the image rendering, which by default is g=2.4 s=12.92; b) raise the shadows and modify the lighter tones while preserving the colorimetry and the gamut.
* Illuminant (white point): a) adjust the gamut of the Working profile to adapt it to the shooting conditions taking into account the colorimetry. If an image is taken at 4000K, in sRGB (which is D65), the gamut may not be suitable. The joint action of the Illuminant and CIECAM (symmetrical mode) allows you to ensure good chromatic adaptation; b) used in conjunction with the modification of the Primaries below.
* Primaries: this is where the notion of Abstract profiles comes into its own. Several possibilities are available: a) Use this module as a Channel Mixer in order to create special effects similar to Color Toning, with or without CIECAM; b) Use it to modify or refine the result of the Input profile to improve the colorimetry (calibration).

===Where is it located in the toolchain pipeline?===

It is located at the end of the process, just before CIECAM and allows the user to either:
* Apply special effects similar to Color Toning > Color Correction Regions.
* Make color corrections (calibration) at the end of the process just before the Output profile taking into account image modifications made upstream.

This position also avoids the introduction of non-linearities.

=== TRC - Tone Response Curve ===

This feature allows you to vary the gamma and slope based on the Working profile. It does not modify the profile, but takes its characteristics into account. It is applied at the end of the process, just before CIECAM. It can be found in other software such as UFRaw©, as well as in Output profiles.

It has several objectives:
* Didactic: you can see the main differences resulting from changes in gamma (g) and slope (s) directly on your monitor. For example:
** With standard gamma = 1.8 - used in the Output profile by Prophoto.
** With standard gamma = 2.2 - used in the Output profile by AdobeRGB.
** With a TRC e.g. BT709 which corresponds to gamma = 2.22 and slope = 4.5. This has a linear part up to a value of 4.5, then a logarithmic part with g = 2.22. This combination gives the same result as the "standard gamma = 1.8" for the medium tones and highlights, but has improved shadow rendering by removing the impression of grayness.
** An sRGB TRC, which corresponds to g=2.4 and s=12.92. This has a linear part up to the value of 12.92, then a logarithmic part with g=2.4. This is the usual rendering chosen by many software applications including Lightroom©, as well as the default screen output and output of RawTherapee.

* Particular export requirements: you can decide to work with a linear gamma for example, for exporting to another software application (for printing, or for modification in Photoshop or Gimp) and/or to see the results directly on your monitor.

* Action on shadows and highlights: this feature does not replace the other RawTherapee modules such as Shadows/Highlights, or the curves in Exposure, etc., but is complementary to them:
** You can lift the shadows by using the Slope slider. Values up to 300 allow a significant transformation of the image in the shadows.
** You can act on the highlights and mid-tones by acting on the Gamma slider. Values up to 15 are possible.
** You can observe the impact on the histogram.
* Adjust the luminance of the gray tones, for example when using a ColorChecker24 for calibration.

* Note that the Slope slider is only active for values of Gamma >1. Because of the algorithm used to generate the tone response curve, it will show erratic behavior when set to values below 1 and greater than 0.It behaves as expected when set to zero.
** When Slope is set to 0, only the gamma component of the TRC curve is activated. The image rendering will be similar to profiles such as “AdobeRGB 2.2” or “ProPhoto 1.8”.
** When Slope reaches the value 1 (in fact when Slope = 1 the system behaves as if gamma = 1), the number of shades of gray in the shadows are reduced and the shadows become darker. The overall contrast is increased with only minor changes to the mid-tones and highlights.
** Depending on the gamma setting, increasing the Slope will make the shadows progressively lighter. High Slope values (50 or more) require a high gamma value to take full advantage of the possibilities.
** Different profiles may have parts of their respective TRCs that are similar. For example an image opened with “Adobe g=2.2” will have approximately the same luminance values for the midtones and highlights as one opened with “sRGB g=2.4 s=12.92”. However there will be significant differences between the two in the shadows.

====Differences compared to a classic tone curve====

* As previously mentioned, it is located at the end of the process to avoid non-linearities as much as possible and guarantee better quality results.
* When used in conjunction with Illuminant or Primaries it guarantees that the result stays in gamut and gives better colorimetry. When it is used on its own (with Illuminant and “Destination primaries” set to the default values), there is no gamut control (to optimize processing time). Changing any of the default values will immediately invoke the gamut control.
* The linear part, often with a small value (s= 2 ... s=13), connected to a parabolic part is practically impossible to realize with a tone curve.
* It constitutes - as soon as you activate "Illuminant" (if only to confirm the illuminant, for example D50 for ProPhoto), or "Primaries" - a part of a virtual ICC profile that can be applied to an image or a series of images at the end of the process.

===Illuminant - white point===

By default, the illuminant is set to the corresponding value in the Working profile. For example this corresponds to D50 for "ProPhoto", D65 for "sRGB", D60 for "ACESp1".
[[File:ciexy-wp.jpg|600px|thumb|center|White point]]
Why change it? There are several reasons for wanting to change this value:
* To deliberately change the colors as you would with a Channel Mixer or with Color Toning. If we examine the "CIE xy" diagram, we can see that when we change the illuminant the white point moves:
** Towards the red zone if the temperature of the illuminant drops.
** Towards the blue zone if the temperature of the illuminant increases.
Used this way we are essentially modifying the red / blue balance.

* To "patch" the Working profile and adapt the colorimetry to specific images. For example, let's imagine that we took pictures around dusk and that the Working profile is "Prophoto" with a D50 illuminant.
* There are two possibilities:
** You want to accentuate the effects of the sunset and make the image even warmer. In this case choose a white point with a temperature lower than the Working profile; for example D41 if the Working profile is "Prophoto D50".
** You want to optimize the gamut to get the best range of colors in sunset shooting conditions. In this case choose a white point that has a temperature higher than the Working profile. For example if the Working profile is "Prophoto D50", and the shot is around 4000K, then choose an illuminant around D60 or D65. Note that the white point function is not linear so the approach can only be approximate.
** The virtual profile will "patch" the data by changing the XYZ values of the RGB-XYZ conversion matrix to better fit the image data, thus avoiding out-of-gamut values.

===Primaries===

By default the primaries are set to the values of the Working profile, so why change them?
* To create special effects similar to those that can be produced in the Channel Mixer or in Color Toning - note that a "primaries" Channel Mixer is a little more intuitive than an RGB Channel Mixer in the sense that a primary adjustment acts mainly on the particular primary color - in this case there are two possibilities:
** You can choose a set of primaries that are different to those used in the Working profile by selecting a different profile in the drop-down list in the “Destination primaries” combobox. This will have the effect of moving the triangle on the “CIE xy” diagram to take into account the difference between the primaries in the Working profile and the primaries used in the “Destination primaries”. This introduces a constant shift in any images to which this “patch” is applied. The final result will of course depend on how the colors are distributed in each of the images.
** You can also adjust the primaries individually by selecting Custom in the drop-down list in the “Destination primaries” combobox. In this case you can modify the location of the 3 vertices of the triangle of “Destination primaries” giving you almost unlimited possibilities.

* To modify/refine images so that they are as close as possible to the shooting conditions (deltaE minimized).
** The use with a chart (ColorChecker24 ...) is almost mandatory.
** CIECAM should be used if we want the Input profile to be relevant when used with an illuminant other than the one used to create it in the first place.

===Black & White===

Abstract profiles can also be used to produce striking black & white effects by varying the three components of the profile. For example by:
* Shifting the white point to a completely different setting e.g. to Tungsten 2000K.
* Significantly moving the primaries away from their working-profile settings.
* Using a different TRC to change the way the gray tones are distributed in the image e.g. by using a TRC g=2.793 s=4.26.

You can also use this module in conjunction with the CIECAM02/16 module to obtain color-toning effects such as Sepia etc., by modifying Temperature and Tint in the CIECAM Viewing Conditions (Advanced mode).

The settings given in the example are for didactic purposes. Of course you can (should) use settings that are closer to the Working profile values.

[[File:ciexy-bw1.jpg|600px|thumb|center|Black and White]]
Raw file: [https://drive.google.com/file/d/1azCxu1midw6dcuN7SbvbAiJH4pxX5BTA/view?usp=sharing]

===How the "Primaries and White Point" algorithm works===

When you change the primaries and white point, a new "XYZ=>RGB" matrix is applied to the data. This matrix is produced using the following simplified algorithm:
* Start with the chromaticity values of each of the red green and blue primaries (these correspond to the xyY values when Y=1).
* Convert the xyY values to XYZ to derive the first XYZ matrix: [M1].
* Invert this matrix: [IM1].
* Using [IM1] and the source XYZ white point values (e.g. D45, D55, D60, StdA etc.), derive the values of Sr, Sg & Sb.
* Produce a new matrix [Mat_xyz] by multiplying Sr, Sg, Sb with the original XYZ data in [M1].

Bradford transformation
* Preamble: Bradford is a chromatic adaptation, based on the concept of "response cones". Its purpose is to adapt the XYZ data calculated using a D50 illuminant to the XYZ values for another illuminant such as D41, D55, etc. It uses the concepts of "RGB source" (RGB s) and "RGB destination" (RGB d), to calculate the "response cone" values. This is similar to the LMS (long, medium, short) concept, which is a colorimetric space that represents the responses of the 3 types of cones in human vision.
* Calculate RGB s = Source White point * [M(Bradford)].
* Calculate RGB d = D50 White point * [M(Bradford)].
* Calculate the Cone _response (destination source) = RGB d / RGB s.
* Develop a new matrix [Cone_matrix] = Cone_response * [Inverse-M(Bradford)].
* Develop a new matrix [Chromatic_adaptation] = [M(Bradford)] * [Cone_matrix].
* Develop the final matrix taking into account the source White-point: [Mat_xyz_bradford] = [Mat_xyz] * [Chromatic_adaptation].
[http://www.brucelindbloom.com/index.html?Eqn_ChromAdapt.html Bruce Lindbloom Chromatic adaptation for information - (slightly different to RawTherapee implementation))].

====Display Matrix XYZ-RGB - "Mat_xyz_bradford"====

* If you run RawTherapee from the console, and in options set verbose = true, the XYZ to RGB conversion matrix "Mat_xyz_bradford" will be displayed. It takes into account the "Destination primaries" and Illuminant.
* Example with "Destination primaries” = Rec2020 and illuminant set to D80.
** Illuminant: D80
** rX=0.661827 gX=0.178737 bX=0.123636
** rY=0.274860 gY=0.678752 bY=0.046389
** rZ=-0.00275 gZ=0.031042 bZ=0.796608

Important note:
* The source white point is only used to modify the ICC profile (the data of the XYZ-RGB matrix). In-depth modification of the image cannot result from this modification and is part of the color-management process (White Balance, CIECAM,etc.).

===Possible example of use to modify/improve the behavior of the Input profile===

* Switch to Neutral.
* Load the image of the chart that was used to create the Input profile.
* Choose Abstract Profile > Custom. By default the selected profile will be the same as the Working profile (as will the Illuminant). Do not change these values.
* Select Custom in "Destination primaries”.
* The Working profile primaries are displayed, you can now modify them.
* Activate the Lockable Color Picker.
* Select among the patches: 2 or 3 grays distributed between the darkest and the lightest, 1 red (saturated), 1 green (saturated), 1 blue (saturated).
* The L*a*b* values of these patches (chart references) are the target values.
* Adjust gamma (g) and slope (s) so that the 3 grays are as close as possible to the reference values.
* Change the "x" and "y" values of the Red, Green and Blue primaries so that the measured values are as close as possible to the reference values.
* Use "Preserves Pastel tones" if necessary: this slider allows you to avoid modifying very lightly saturated tones (close to neutral tones) and allows you to progressively reduce the action on pastel tones.
* Save the result.

If you want your profile (e.g. developed in D50) to be used for another temperature range, it is necessary to take Cat16 into account in CIECAM:
* Choose the new temperature in "White balance" - for example 6000K.
* Select Color Appearance & Lighting (CIECAM02/16).
* Select: CAM Model = CIECAM16.
* Select CatO2/16 mode = Automatic Symmetric.
* Adjust the temperature in Viewing Conditions to that of the white balance (in this example 6000K),
* Then use the same process as before.

To use the results of this virtual profile for other images, do the following:
* Right click on the thumbnail in the file browserand choose "Processing profile operations" > Copy,then "Paste partial" > "Color management".

Note: the values can of course be adjusted empirically as in ART and Lightroom. For small deviations from the original primaries, the results are fairly predictable. On the other hand, if we make big changes, the results will be less so.

== Output Profile ==

Specify the output color profile; the saved image will be transformed into this color space and the profile will be embedded in the metadata. The effects the output profile has on the image cannot be seen in the preview.

RawTherapee lets you specify "input" (e.g. your camera's profile), "display" (e.g. computer screen) and "output" (e.g. printer) device class profiles with an RGB color space, because RawTherapee saves only RGB images. Profiles listed in this combobox are those which come bundled with RawTherapee and those located in the folder set in Preferences > [[Preferences#Color_Management_Tab|Color Management]].

The soft-proofing feature is dedicated to simulating printer rendering. It lets you preview what your image will look like when printed, assuming you use a printer profile which correctly simulates your printer and paper combination. For best printout quality, after you have tweaked your photo using soft-proofing, you should select your printer profile as the output profile and save the image using it. This ensures that the image is encoded using your printer's color space directly from RawTherapee's internal high quality floating-point representation, instead of being saved to an 8-bit image in sRGB for example and then having to be subsequently converted to the printer profile, which would be quite lossy.

The main histogram, navigator and clipping indicators will use either the working or the output profile. You can choose the behavior by using [[File:gamut-hist.png]] button in the Editor tab.

The recommended output profile when you're saving to an 8-bit format and/or publishing to the web is RTv4_sRGB. If no profile is selected, none will be embedded, which means that "sRGB" is implied, though it is safer to embed RTv4_sRGB to ensure your image is displayed properly in various applications.

RTv4_sRGB is a '''higher quality''' version of the standard sRGB profile, which surprisingly is inconsistent between implementations. RTv4_sRGB was custom-made for RawTherapee and has 4096 LUT points, as opposed to the lower quality 1024 point sRGB profiles. Applications that aren't color managed and won't take advantage of RTv4_sRGB will fall back on sRGB.

Wide-gamut output profiles such as RTv4_Large are generally used if you export to a 16-bit or higher bit-depth format for further editing in another application. If you will be sending your image for printing, a wide-gamut output profile is also recommended, since some printers may have wide gamuts (at least in certain colors).

You should have a wide-gamut monitor if you want to work with wide-gamut profiles, otherwise you're flying in the dark.

=== Bundled Output Profiles ===

RawTherapee comes bundled with a number of custom-made, high quality output profiles. There are two types: ones compatible with [https://en.wikipedia.org/wiki/ICC_profile ICC v2], and ones with [https://www.color.org/whyusev4.xalter v4]. The v4 versions should be compatible with most modern software. The legacy v2 versions are supplied as a fallback.

Each ICC profile's filename describes the ICC version and the primaries of the output space:
* sRGB: similar to sRGB.
* Medium : similar to AdobeRGB1998.
* Large: similar to ProPhoto.
* ACES-AP0: similar to ACES AP0.
* ACES-AP1: similar to ACES AP1.
* Wide: similar to Widegamut.
* Rec2020: similar to Rec2020.
* Best: similar to Best.
* Beta: similar to Beta.
* Bruce : similar to Bruce.

By default all these profiles have a TRC (Tone Reproduction Curve) with gamma=2.4 and slope=12.92.

You can customize these profiles using the [[ICC_Profile_Creator| ICC profile Creator]], which allows you to:
* change the TRC and assign any value from 1 (linear gamma) upwards.
* change the primaries and illuminant to suit your needs.
* change the labels, description etc.

File:ColorManagement-InputProfile-GUI.jpg

2021-06-19T10:21:32Z

Thanatomanic:

== Licensing ==
{{PD}}

Color Management

2021-06-19T10:16:21Z

Thanatomanic: Revised the text up to the DCP section.

<div class="pagetitle">Color Management</div>

Color management comprises all tasks to ensure a faithful representation of colors from scene to intermediate formats, editors and various output media. This is an often complicated and technical matter that RawTherapee tries to handle as correctly as possible behind the scenes. More can be read about it [http://rawpedia.rawtherapee.com/Color_Management_addon here]. The various options of the Color Management tool are explained below.

== Input Profile ==

An essential first step in raw processing is the faithful conversion of the [[Demosaicing#Introduction|camera sensor data]] to an internal RGB color space. This conversion requires an input profile made specifically for the camera. Such a profile is the result of the analysis of how specific colors and tones are captured, processed and represented as raw data by the camera (for more details, see e.g. [https://ninedegreesbelow.com/photography/articles.html#profile-digital-camera Elle Stone's article], [https://torger.se/anders/dcamprof.html DCamProf's documentation] or [[How to create DCP color profiles]]. Without a camera-specific input profile, accurate color representation is impossible.

The input profile is applied to the image data at the beginning of RawTherapee's [[Toolchain_Pipeline|processing pipeline]] because most tools depend on it. There are several ways to apply an input profile.

==== No Profile ====

No color conversion will take place and a unit transform of the image data is applied. '''Do not use this for regular editing.''' Applying no input profile is generally only useful for analytical purposes to show images in the camera's native RGB color space, or in extreme cases to prevent clipping of channels when the camera has recorded colors outside of conventional gamuts.

Note that selecting 'No Profile' for non-raw files bypasses the embedded color profile and the working profile will be assigned. This means that gamma-encoded files (e.g. sRGB) will be assumed linear, making them look brighter.

==== Use embedded, if possible ====

Only available for non-raw files. The embedded color profile is used. Which profile is embedded can be checked with GIMP for example.

==== Camera Standard ====

A conversion takes place based on profiled information from either of three sources, in decreasing priority:
* The <code>dcraw_matrix</code> field in the <code>camconst.json</code> data file available in RawTherapee's installation directory;
* Hard-coded values provided by the <code>dcraw</code> library embedded within RawTherapee;
* The raw file itself.

There is one exception: when a DNG raw file has a <code>ColorMatrix2</code> Exif tag and was not generated by the Adobe DNG Converter, the matrix from the Exif data is prioritized above all others.

Applying an input profile is nothing more than a linear algebra operation on the image data. The input profile consists of a square matrix (3×3 for RGB based sensors) that is multiplied with the pixel vectors of camera-native RGB values. These matrices are specifically calibrated for a specific illuminant ([https://en.wikipedia.org/wiki/Illuminant_D65 D65], i.e. 6500K) and provide the most accurate color reproduction if the scene illuminant matches the calibration illuminant. However, the color accuracy is usually still good enough for very different light sources and white balances.

The benefit of a matrix profile over other profiles (e.g. table-based DCP or ICC profiles) is its linearity. Because no non-linear functions are applied to the data, the scene-referred linearity of the light intensities is kept intact. This is important for several image processing operations and for example when exporting for further editing (e.g. HDR applications usually require a predictable linear color response).

==== Auto-Matched Camera Profile ====

RawTherapee allows you to use custom '''DCP''' (Adobe DNG Camera Profile) or '''ICC''' (International Color Consortium) color input profiles. These can be tailor-made to specific scene conditions to provide the most accurate color rendition, or to generally improve upon the standard matrix profiles available.

RawTherapee ships multiple high-quality, custom-made, general-purpose DCP profiles that can be automatically matched when an image from a supported camera is opened. The available profiles are found in the <code>dcpprofiles</code> folder in your installation directory. It is possible to add your own DCP or ICC profiles to this folder. Matching only works on the exact name of the camera (case-sensitive) as is present in the image metadata.

Most provided DCP profiles are dual-illuminant (see [[Color_Management#DCP_Illuminant|below]]) and some provide tone curves and looks as well. New profiles are added exclusively based on user submission. Please read [[How to create DCP color profiles]] for further instructions in case you want to contribute.

==== Custom ====

Specify a custom DCP or ICC camera input profile when an automatic match is not available, or if you want to override the standard or matched profile. DCP profiles for your camera may be available through the Adobe DNG Converter. Read [[How to get LCP and DCP profiles]] for further information.

Be aware that when you load a custom ICC profile that it is an ''input'' profile. ICC profiles can be created for a multitude of purposes (printers, displays, etc.) and not all profiles are suited as a camera input profile. Your results may vary.

=== DCP ===

==== DCP Illuminant ====

Some of RawTherapee's profiles are single-illuminant (Daylight/D50), while others are double-illuminant (Daylight/D50 and Tungsten/StdA). If a dual-illuminant profile is loaded the "DCP Illuminant" setting will be enabled and you can choose which illuminant to use. The actual DCP standard (part of the DNG standard) does not provide this choice, but instead an interpolation between the two illuminants is calculated based on the chosen white balance (there will only be an interpolation if the white balance is in-between both illuminants, otherwise the closest is picked). This "interpolated" mode is the default setting of "DCP Illuminant" and for any normal use you do not need to change this.

You can however choose to base the color rendering on one of the specific illuminants. In some cases this might produce more pleasing color. It can also be interesting for diagnostic purposes to see how large (or small) a difference there is in color rendering between the illuminants, but, as said, for general use this setting should be untouched.

==== DCP Tone Curve ====

Some DCPs contain a tone curve which may be used to add contrast and brightness to provide a film-like look. This is mainly used for profiles simulating camera maker settings. The tone curve checkbox will be disabled for profiles which do not contain a tone curve.

The curve mode used by the DCP tone curve is the same as the Exposure tool's "[[Exposure#Film-Like|film-like]]" mode, meaning you can reproduce the effect using the Exposure tool's tone curves in film-like mode. When contrast is applied with a film-like curve the appearance of the colors will change and overall saturation is increased, except for bright colors which instead are de-saturated. Some profiles which have curves embedded are pre-corrected for this color appearance change and will thus not provide the intended look without the curve applied. Most will however work well without the tone curve applied especially if you add a similar curve yourself using the Exposure tool's curves, but if you want to see exactly how the profile designer intended the colors to look you should enable the tone curve.

While the input color profile is applied at the first stages of the [[Toolchain_Pipeline|toolchain pipeline]], the DCP tone curve is applied later in the pipeline at some point after the Exposure tool.

{{acrrtc}}

If the DCP profile has a copyright tag with the value "Adobe Systems", regardless whether it contains a tone curve or not, RawTherapee will automatically create a tone curve shaped identically to the Adobe Camera Raw curve. The reason for this is so that using the DCP in RawTherapee can match the results of using that DCP in Lightroom. This is why the "Tone curve" checkbox will not be grayed-out when using a DCP profile which has no embedded tone curve, as long as it has the copyright tag set as described.

==== DCP Base Table ====

This enables the DCP "HueSatMap" lookup table which is used to add non-linear corrections on top of the basic matrix. This is an advanced user setting and unless you want only the pure matrix result should leave it on. It's grayed out if the loaded profile lacks a HueSatMap table.

==== DCP Look Table ====

This enables the DCP "LookTable" lookup table which is intended to add a subjective look on top generally together with an embedded tone curve. That is if you disable the DCP curve and looktable you may get a neutral "colorimetric" profile, if the DCP was designed that way which is not always the case (if the DCP has both a look table and a base table it's likely that it is, but if it only has a look table it will probably not work well with it disabled). Disabling individual DCP elements are considered advanced user settings, normally you would leave this on.

==== DCP Baseline Exposure ====

The DCP may indicate an exposure offset that corresponds to an offset of the exposure slider. The purpose of this is typically to make the brightness of the image match the brightness of the camera's own JPEGs, which can be useful if you're shooting with auto-exposure. Currently this offset is applied "under the surface" so you don't see it on the exposure slider.

Note that if you are using Adobe's proprietary profiles those are expecting that the DNG's "baseline exposure" tag is applied too (the profile's offset is added on top). Currently there is no support for the DNG tag so you need to find that out on your own (using exiftool for example) and then set that offset using the exposure slider if you want to get the exact same brightness as in Adobe Camera Raw.

=== Implementation Notes ===

==== Third-Party DCP Support ====

The DNG Camera Profile, DCP, is the preferred camera input profile format for RawTherapee. All elements of the 1.4 DNG specification are supported, with the exception of the black render tag (see below). A DCP can be a pure matrix profile, it can have a LUT (typically 2.5D) to improve the colorimetric accuracy, and then it can have an embedded curve and a separate "look table" on top. It may also add an exposure offset. All these elements can be toggled on/off via checkboxes. However, you should be aware that a profile will produce the most accurate colors when all the elements it was designed to include are enabled. For example, using a tone curve changes the color ''appearance'', so if you disable an embedded tone curve to get a linear profile you can't count on the colors being absolutely accurate. Nonetheless, most photographers rely on an aesthetically-pleasing appearance, and not on absolute accuracy, so this should not be a concern unless absolute accuracy is crucial. Typically, third-party profiles would come from Adobe Camera Raw/Lightroom/DNG Converter, and RawTherapee supports them. Many of Adobe's profiles lack a tone curve, but in Adobe's world that does not mean that no tone curve should be applied, but that Adobe's default curve should be applied. RawTherapee will therefore identify Adobe profiles (from the copyright string) and add the default curve to those (which you can toggle with the tone curve checkbox).

Adobe DNG Converter may add a "baseline exposure" to the DNG file. Some of Adobe's DCPs are designed to work with that baseline exposure and then produce a default output which is about the same brightness and contrast as the out-of-camera JPEG. RawTherapee can honor this baseline exposure if the DCP contains one.

The DCP format also has a black render tag. This indicates if the raw converter should do "automatic" black subtraction or not. RawTherapee ignores this tag - you can perform manual black subtraction with the [[Raw Black Points]] tool or with the [[Exposure#Black|black]] slider in the Exposure tool. As many of Adobe's profiles indicate auto black subtraction and Adobe Camera Raw/Lightroom does it, in those cases RawTherapee will render slightly lower contrast and brighter shadows.

==== Third-Party ICC Support ====

RawTherapee has specific support for ICC profiles bundled with Capture One and Nikon NX2, so those should work well. Older ICC profiles are not likely to work well though (typically the image becomes extremely dark with unsupported ICC profiles).

Some ICC profiles apply a tone-curve and desaturate bright highlights for a more film-like look. Those profiles may not work well together with [[Exposure#Highlight_Reconstruction|Highlight Reconstruction]]. If you see a radical change in contrast when you apply your ICC profile, it has applied a tone-curve and then you should not use it together with [[Exposure#Highlight_Reconstruction|Highlight Reconstruction]].

Unlike DCP profiles, ICC profile processing may cause clipping of extremely saturated colors during conversion. In practice this is rarely a problem, but still DCP should be considered the primary choice if available.

Note on using Capture One ICC profiles: RawTherapee applies the ICC before exposure adjustments, as the intention is that input profiles should only be used to make the colors more accurate, and not to apply a look - you design the look using the tools instead. Phase One's ICC profiles contain a subjective look though, which means that they typically contain "hue twists", for example saturation in the shadows is increased. This means that if you have an underexposed file and push it a few stops, those hue twists have been applied to the dark image before the exposure adjustment and will thus be in the wrong place after adjustment; that is you don't get the same look as in Phase One's Capture One. Therefore it is recommended to have the right exposure out of the camera when using Phase One ICC profiles. You should also apply a suitable RGB [[Exposure#Film-Like|film-like]] curve, as those ICC profiles are designed to be used together with that.

We are aware that LUT ICCs should typically be applied after exposure (just as DCP LookTables are applied), and that would support for example Capture One profiles better. This may be fixed in a future version.

=== Save Reference Image ===

Clicking the "Save Reference Image" button saves a linear TIFF image before the input profile is applied. This file can then be used for profiling, i.e. creating a camera input profile. You can use the open-source ArgyllCMS program to create ICC profiles, and DCamProf to create ICC or DCP profiles.

Cropping, resizing and transformations (rotation) will be applied, allowing you to make the output image more manageable by the receiving software. ArgyllCMS is very picky for instance, and requires that only the test target is visible in the image.

You can also choose if you want to export with white balance applied or not. For ICC profiles you should export with white balance applied, but if you intend to make a DNG profile or a dcraw-style color matrix you should export without applying white balance.

== Working Profile ==

The default working profile is ProPhoto and should not be changed for normal use.

The working profile specifies the working color space, which is the color space used for internal calculations, for instance for calculating saturation, RGB brightness/contrast and tone curve adjustments, chrominance, etc.

When RawTherapee was based on integer math it was wise to not use working space larger than absolutely needed to get the best precision in the calculations. However, RawTherapee had switched to floating-point processing in 2011, and since version 4.0.12 the default working profile is ProPhoto, which has a very large gamut.

The choice of working profile has an influence on the effect of the curves in all modes except for perceptual - in that mode, changing the working profile will not alter the effect of the curve. If you have trouble fitting colors within the output gamut you can experiment with changing the working profile when using curves in any mode but perceptual.

Note that the working profile will only specify the red, green and blue primaries, gamma will not change as RawTherapee's processing pipeline is floating point with no gamma encoding (that is gamma = 1.0). Some tools (like curves and histograms) will still display with a gamma (usually sRGB gamma) which is hard-coded for the tool and stays the same regardless of working profile.

=== Adding Custom Working Profiles ===

RawTherapee 5.5 allows you to specify custom working profiles through a [https://en.wikipedia.org/wiki/JSON JSON] file. The file should be named <code>workingspaces.json</code> and it can reside in:
* the ICC profile folder as set in [[Preferences#Color_Management_Tab|Preferences > Color Management > Directory containing color profiles]],
* or in RawTherapee's own ICC profile folder:
** Windows: <code><rt-install-folder>\iccprofiles</code>
** Linux:
*** When installed using your package manager or self-compiled with <code>BUILD_BUNDLE=OFF</code>: <code>/usr/share/rawtherapee/iccprofiles</code>
*** When self-compiled with <code>BUILD_BUNDLE=ON</code>: <code><rt-install-folder>/iccprofiles</code>
** macOS: <code>/library/ColorSync/Profiles/Displays</code>

The format of <code>workingspaces.json</code> is as follows:
<pre style="white-space: pre-wrap">
{"working_spaces": [
{
"name" : "ACES",
"file" : "/path/to/ACES.icc"
},
{
"name" : "ACEScg",
"matrix" : [0.7184354, 0.16578523, 0.09882643, 0.29728935, 0.66958117, 0.03571544, -0.00647622, 0.01469771, 0.66732561]
}
]}
</pre>

If "matrix" is present, "file" is ignored. If only "file" is present, the matrix is extracted from the ICC profile. For this, RawTherapee looks only at the R, G, and B matrix columns and the white point set in the profile. Bradford adaptation is used to convert the matrix to D50. Anything else in the profile (LUT, TRC, etc.) is ignored.

It is the user's responsibility to ensure that the profile is suitable to be used as a working space.

==Abstract Profiles==

===What is an Abstract profile?===

* According to the International Color Consortium (ICC), Abstract profiles allow you to perform custom image effects, such as applying a particular “look” to a series of images. Such a profile allows you to define CIELAB (or CIEXYZ) values as both Input and Output. This means you can algorithmically define whatever color changes you like and produce the corresponding LUT. A small number of color management applications support the creation and/or use of Abstract profiles.
* In the case of RawTherapee this is achieved using the Virtual profiles in LCMS, which allow you to modify the data using the same algorithms and principles as those used for Input profiles or Output profiles i.e. by acting on one or more of the 3 ICC profile components i.e. Tonal response curve (TRC), Illuminant (white point) and Primaries.
* Is an Abstract profile part of color management? This is debatable but it is certainly more so than the Working profile, which is simply a transformation in C++ code that converts RGB data into XYZ. If we use the ICC and LCMS (virtual profile) definitions, the answer is definitely yes.
* Note that Abstract Profile only works with the provided working profile package: ACESp0, ACESp1, Adobe RGB, Best RGB, BetaRGB, BruceRGB, ProPhoto, Rec2020, sRGB, WideGamut. The use of "Adding Custom Working Profiles through a JSON file" is not possible.

===The CIE xy diagram===

The LCMS virtual profile modifies the "x" & "y" data, which is one of the possible representations of the colorimetry. This representation makes it possible to easily see:
* The limits of human vision in terms of visible frequencies from 380nm to 770nm.
[[File:ciexy-color.jpg|600px|thumb|center|Limits of human vision]]
* A triangular color-space model based on the primaries.
[[File:ciexy-3space.jpg|600px|thumb|center|Colorimetric spaces]]
* The curve showing the evolution of the white point (one of the bases of the illuminants D50, D65, Std A, ).
[[File:ciexy-wp.jpg|600px|thumb|center|White point]]
* Note that this representation must be interpreted with care, because it is a vertical projection of the gamut. A color that is outside the gamut triangle is necessarily out of gamut, but a color inside the triangle can also be out of gamut, because this projection ignores the luminance component.

====Some Primary values====

* sRGB - Red x=0.64 y=0.33 - Green x=0.30 y=0.60 - Blue x=0.15 y=0.06
* Rec2020 - Red x=0.708 y=0.292 - Green x=0.17 y=0.797 - Blue x=0.131 y=0.046
* ProPhoto - Red x=0.7347 y=0.2653 - Green x=0.1596 y=0.8404 - Blue x=0.0366 y=0.0001
* ACESp0 - Red x=0.7347 y=0.2653 - Green x=0 y=1.0 - Blue x=0.0001 y=-0.077

When one of the primaries is outside the limits of human vision we speak of imaginary colors.

===Use of data from the "CIE xy" diagram in Abstract profiles.===

[[File:cie-abstract_graph3.jpg|600px|thumb|center|Abstract profiles]]

You can modify the 3 components of the virtual profile as you wish. The screen capture represents a configuration allowing you to improve the "calibration" of the Input profile.
* In this example, the Working profile is Prophoto, where the primaries have not been modified. When you choose "Destination primaries” > Custom the algorithm will by default choose this particular Working profile to build the Abstract or Virtual profile.
* If you change "Destination primaries" to any value other than those used for the Working profile you can create special effects similar to those produced in the more familiar Color Toning or Channel Mixer modules.
* You can change the D50 Illuminant to another value, either to create or amplify some special effect, or adapt the illuminant to a specific case.

If the first combobox in the Abstract Profile panel is set to Custom, the CIE xy diagram will display the default working-profile values. i.e:
* The 3 primaries: Red, Green & Blue.
* The white point.
If the first combobox in the Abstract Profile panel is set to Custom or some other option (e.g. BT709 etc.), the CIE xy diagram will display:
* The primaries and the white point of the profile selected in the "Destination primaries" combobox.

In addition to the profile options in the "Destination primaries" combobox there are also two custom options.
* Custom (sliders):
** The sliders Red (X, Y), Green (X, Y) & Blue (X, Y) will be active.
** The combobox Illuminant will be active.
** Any changes to the slider values will be shown in the CIE xy diagram. Note that the "Custom (sliders)" option does not allow you to make changes directly on the graph.

* Custom (CIE xy diagram):
** You can modify the primaries directly on the graph using the mouse and the changes will be made automatically to the Red, Green & Blue sliders. Note that in this case you can only modify the slider positions by moving the points on the graph.
** The illuminant cannot be changed.

Note:
If we take the example shown in the screen capture above (with the sliders set to the ProPhoto primary values):
* When you move the red primary vertically upwards, reds will move towards magenta.
* If you move it down the reds move towards orange.
Note that the color shifts move in the opposite direction to the red primary. This is because moving the primary upwards causes the colors to rotate clockwise around the white point (shown in the diagram "the limits of human vision"). Moving the primary downwards causes the colors to rotate counterclockwise.
Similar behavior can be observed with the green and blue primaries.
* When you move the red primary to the left, (reducing the distance to the white point) the saturation will increase.
* If you move it to the right, the saturation should decrease but additional colors will be added. This behavior is normal.

Still using the same example:
* When you change the illuminant (in this case D50) to a lower temperature (D41, stdA), the reds will turn orange. If you change it to a higher temperature (D80, D120) the reds will turn magenta. This is also normal.

This behavior is "normal", but why? The reason is that we don't modify the Working profile. Instead, we modify the data that has already been modified in the processing pipeline. For didactic purposes, let's look at the operation of CIECAM02/16 in symmetrical mode. If the white balance is set to 7500K for example and it corresponds to the illuminant at the time of shooting, the image will have yellowish whites and an overall dominant red color. Cat02/16 chromatic adaptation will allow us to cool down the image by setting the temperature in Viewing Conditions to the corresponding white balance i.e. 7500K. The white balance acts as the Working profile upstream and chromatic adaptation acts as an Abstract profile downstream.

Note: the diagram is given for information only. The limits are not always very precise, especially towards the greens.

===Which data and profiles are used or modified?===

The Abstract profiles (Virtual profiles) implemented here:
* Do not change the Working profile.
* Do not modify the Input profile.
* Do not modify the Output profiles.
* But they modify the data in the same way as any other RawTherapee algorithm. Particular features:
** The Abstract profile, which corresponds to a virtual ICC profile in LCMS, acts as a patch at the end of the pipeline (just before Ciecam and just before the conversion to a screen profile or an Output profile). It acts on the 3 components of the ICC profile (Tone Response Curve, Illuminant (white point) & Primaries). Depending on the choices and settings, the image appearance can be modified as follows:
*** In depth by acting on the distribution of luminance and colors – rather like a Channel Mixer or Color Toning to which an extra dimension has been added.
*** On the luminance distribution via the TRC, either to change the default aspect, which in RawTherapee is an sRGB TRC, or to act as a Shadows/Highlights control.
*** To modify or refine the results of the Input profile with the help of a color chart (Colorchecker24 or other), either with the same illuminant that was used during the elaboration of the Input profile, or with another illuminant. In this case CIECAM will need to be used also.

===Three main uses (with or without CIECAM)===

* TRC: adjust gamma and slope to: a) modify the image rendering, which by default is g=2.4 s=12.92; b) raise the shadows and modify the lighter tones while preserving the colorimetry and the gamut.
* Illuminant (white point): a) adjust the gamut of the Working profile to adapt it to the shooting conditions taking into account the colorimetry. If an image is taken at 4000K, in sRGB (which is D65), the gamut may not be suitable. The joint action of the Illuminant and CIECAM (symmetrical mode) allows you to ensure good chromatic adaptation; b) used in conjunction with the modification of the Primaries below.
* Primaries: this is where the notion of Abstract profiles comes into its own. Several possibilities are available: a) Use this module as a Channel Mixer in order to create special effects similar to Color Toning, with or without CIECAM; b) Use it to modify or refine the result of the Input profile to improve the colorimetry (calibration).

===Where is it located in the toolchain pipeline?===

It is located at the end of the process, just before CIECAM and allows the user to either:
* Apply special effects similar to Color Toning > Color Correction Regions.
* Make color corrections (calibration) at the end of the process just before the Output profile taking into account image modifications made upstream.

This position also avoids the introduction of non-linearities.

=== TRC - Tone Response Curve ===

This feature allows you to vary the gamma and slope based on the Working profile. It does not modify the profile, but takes its characteristics into account. It is applied at the end of the process, just before CIECAM. It can be found in other software such as UFRaw©, as well as in Output profiles.

It has several objectives:
* Didactic: you can see the main differences resulting from changes in gamma (g) and slope (s) directly on your monitor. For example:
** With standard gamma = 1.8 - used in the Output profile by Prophoto.
** With standard gamma = 2.2 - used in the Output profile by AdobeRGB.
** With a TRC e.g. BT709 which corresponds to gamma = 2.22 and slope = 4.5. This has a linear part up to a value of 4.5, then a logarithmic part with g = 2.22. This combination gives the same result as the "standard gamma = 1.8" for the medium tones and highlights, but has improved shadow rendering by removing the impression of grayness.
** An sRGB TRC, which corresponds to g=2.4 and s=12.92. This has a linear part up to the value of 12.92, then a logarithmic part with g=2.4. This is the usual rendering chosen by many software applications including Lightroom©, as well as the default screen output and output of RawTherapee.

* Particular export requirements: you can decide to work with a linear gamma for example, for exporting to another software application (for printing, or for modification in Photoshop or Gimp) and/or to see the results directly on your monitor.

* Action on shadows and highlights: this feature does not replace the other RawTherapee modules such as Shadows/Highlights, or the curves in Exposure, etc., but is complementary to them:
** You can lift the shadows by using the Slope slider. Values up to 300 allow a significant transformation of the image in the shadows.
** You can act on the highlights and mid-tones by acting on the Gamma slider. Values up to 15 are possible.
** You can observe the impact on the histogram.
* Adjust the luminance of the gray tones, for example when using a ColorChecker24 for calibration.

* Note that the Slope slider is only active for values of Gamma >1. Because of the algorithm used to generate the tone response curve, it will show erratic behavior when set to values below 1 and greater than 0.It behaves as expected when set to zero.
** When Slope is set to 0, only the gamma component of the TRC curve is activated. The image rendering will be similar to profiles such as “AdobeRGB 2.2” or “ProPhoto 1.8”.
** When Slope reaches the value 1 (in fact when Slope = 1 the system behaves as if gamma = 1), the number of shades of gray in the shadows are reduced and the shadows become darker. The overall contrast is increased with only minor changes to the mid-tones and highlights.
** Depending on the gamma setting, increasing the Slope will make the shadows progressively lighter. High Slope values (50 or more) require a high gamma value to take full advantage of the possibilities.
** Different profiles may have parts of their respective TRCs that are similar. For example an image opened with “Adobe g=2.2” will have approximately the same luminance values for the midtones and highlights as one opened with “sRGB g=2.4 s=12.92”. However there will be significant differences between the two in the shadows.

====Differences compared to a classic tone curve====

* As previously mentioned, it is located at the end of the process to avoid non-linearities as much as possible and guarantee better quality results.
* When used in conjunction with Illuminant or Primaries it guarantees that the result stays in gamut and gives better colorimetry. When it is used on its own (with Illuminant and “Destination primaries” set to the default values), there is no gamut control (to optimize processing time). Changing any of the default values will immediately invoke the gamut control.
* The linear part, often with a small value (s= 2 ... s=13), connected to a parabolic part is practically impossible to realize with a tone curve.
* It constitutes - as soon as you activate "Illuminant" (if only to confirm the illuminant, for example D50 for ProPhoto), or "Primaries" - a part of a virtual ICC profile that can be applied to an image or a series of images at the end of the process.

===Illuminant - white point===

By default, the illuminant is set to the corresponding value in the Working profile. For example this corresponds to D50 for "ProPhoto", D65 for "sRGB", D60 for "ACESp1".
[[File:ciexy-wp.jpg|600px|thumb|center|White point]]
Why change it? There are several reasons for wanting to change this value:
* To deliberately change the colors as you would with a Channel Mixer or with Color Toning. If we examine the "CIE xy" diagram, we can see that when we change the illuminant the white point moves:
** Towards the red zone if the temperature of the illuminant drops.
** Towards the blue zone if the temperature of the illuminant increases.
Used this way we are essentially modifying the red / blue balance.

* To "patch" the Working profile and adapt the colorimetry to specific images. For example, let's imagine that we took pictures around dusk and that the Working profile is "Prophoto" with a D50 illuminant.
* There are two possibilities:
** You want to accentuate the effects of the sunset and make the image even warmer. In this case choose a white point with a temperature lower than the Working profile; for example D41 if the Working profile is "Prophoto D50".
** You want to optimize the gamut to get the best range of colors in sunset shooting conditions. In this case choose a white point that has a temperature higher than the Working profile. For example if the Working profile is "Prophoto D50", and the shot is around 4000K, then choose an illuminant around D60 or D65. Note that the white point function is not linear so the approach can only be approximate.
** The virtual profile will "patch" the data by changing the XYZ values of the RGB-XYZ conversion matrix to better fit the image data, thus avoiding out-of-gamut values.

===Primaries===

By default the primaries are set to the values of the Working profile, so why change them?
* To create special effects similar to those that can be produced in the Channel Mixer or in Color Toning - note that a "primaries" Channel Mixer is a little more intuitive than an RGB Channel Mixer in the sense that a primary adjustment acts mainly on the particular primary color - in this case there are two possibilities:
** You can choose a set of primaries that are different to those used in the Working profile by selecting a different profile in the drop-down list in the “Destination primaries” combobox. This will have the effect of moving the triangle on the “CIE xy” diagram to take into account the difference between the primaries in the Working profile and the primaries used in the “Destination primaries”. This introduces a constant shift in any images to which this “patch” is applied. The final result will of course depend on how the colors are distributed in each of the images.
** You can also adjust the primaries individually by selecting Custom in the drop-down list in the “Destination primaries” combobox. In this case you can modify the location of the 3 vertices of the triangle of “Destination primaries” giving you almost unlimited possibilities.

* To modify/refine images so that they are as close as possible to the shooting conditions (deltaE minimized).
** The use with a chart (ColorChecker24 ...) is almost mandatory.
** CIECAM should be used if we want the Input profile to be relevant when used with an illuminant other than the one used to create it in the first place.

===Black & White===

Abstract profiles can also be used to produce striking black & white effects by varying the three components of the profile. For example by:
* Shifting the white point to a completely different setting e.g. to Tungsten 2000K.
* Significantly moving the primaries away from their working-profile settings.
* Using a different TRC to change the way the gray tones are distributed in the image e.g. by using a TRC g=2.793 s=4.26.

You can also use this module in conjunction with the CIECAM02/16 module to obtain color-toning effects such as Sepia etc., by modifying Temperature and Tint in the CIECAM Viewing Conditions (Advanced mode).

The settings given in the example are for didactic purposes. Of course you can (should) use settings that are closer to the Working profile values.

[[File:ciexy-bw1.jpg|600px|thumb|center|Black and White]]
Raw file: [https://drive.google.com/file/d/1azCxu1midw6dcuN7SbvbAiJH4pxX5BTA/view?usp=sharing]

===How the "Primaries and White Point" algorithm works===

When you change the primaries and white point, a new "XYZ=>RGB" matrix is applied to the data. This matrix is produced using the following simplified algorithm:
* Start with the chromaticity values of each of the red green and blue primaries (these correspond to the xyY values when Y=1).
* Convert the xyY values to XYZ to derive the first XYZ matrix: [M1].
* Invert this matrix: [IM1].
* Using [IM1] and the source XYZ white point values (e.g. D45, D55, D60, StdA etc.), derive the values of Sr, Sg & Sb.
* Produce a new matrix [Mat_xyz] by multiplying Sr, Sg, Sb with the original XYZ data in [M1].

Bradford transformation
* Preamble: Bradford is a chromatic adaptation, based on the concept of "response cones". Its purpose is to adapt the XYZ data calculated using a D50 illuminant to the XYZ values for another illuminant such as D41, D55, etc. It uses the concepts of "RGB source" (RGB s) and "RGB destination" (RGB d), to calculate the "response cone" values. This is similar to the LMS (long, medium, short) concept, which is a colorimetric space that represents the responses of the 3 types of cones in human vision.
* Calculate RGB s = Source White point * [M(Bradford)].
* Calculate RGB d = D50 White point * [M(Bradford)].
* Calculate the Cone _response (destination source) = RGB d / RGB s.
* Develop a new matrix [Cone_matrix] = Cone_response * [Inverse-M(Bradford)].
* Develop a new matrix [Chromatic_adaptation] = [M(Bradford)] * [Cone_matrix].
* Develop the final matrix taking into account the source White-point: [Mat_xyz_bradford] = [Mat_xyz] * [Chromatic_adaptation].
[http://www.brucelindbloom.com/index.html?Eqn_ChromAdapt.html Bruce Lindbloom Chromatic adaptation for information - (slightly different to RawTherapee implementation))].

====Display Matrix XYZ-RGB - "Mat_xyz_bradford"====

* If you run RawTherapee from the console, and in options set verbose = true, the XYZ to RGB conversion matrix "Mat_xyz_bradford" will be displayed. It takes into account the "Destination primaries" and Illuminant.
* Example with "Destination primaries” = Rec2020 and illuminant set to D80.
** Illuminant: D80
** rX=0.661827 gX=0.178737 bX=0.123636
** rY=0.274860 gY=0.678752 bY=0.046389
** rZ=-0.00275 gZ=0.031042 bZ=0.796608

Important note:
* The source white point is only used to modify the ICC profile (the data of the XYZ-RGB matrix). In-depth modification of the image cannot result from this modification and is part of the color-management process (White Balance, CIECAM,etc.).

===Possible example of use to modify/improve the behavior of the Input profile===

* Switch to Neutral.
* Load the image of the chart that was used to create the Input profile.
* Choose Abstract Profile > Custom. By default the selected profile will be the same as the Working profile (as will the Illuminant). Do not change these values.
* Select Custom in "Destination primaries”.
* The Working profile primaries are displayed, you can now modify them.
* Activate the Lockable Color Picker.
* Select among the patches: 2 or 3 grays distributed between the darkest and the lightest, 1 red (saturated), 1 green (saturated), 1 blue (saturated).
* The L*a*b* values of these patches (chart references) are the target values.
* Adjust gamma (g) and slope (s) so that the 3 grays are as close as possible to the reference values.
* Change the "x" and "y" values of the Red, Green and Blue primaries so that the measured values are as close as possible to the reference values.
* Use "Preserves Pastel tones" if necessary: this slider allows you to avoid modifying very lightly saturated tones (close to neutral tones) and allows you to progressively reduce the action on pastel tones.
* Save the result.

If you want your profile (e.g. developed in D50) to be used for another temperature range, it is necessary to take Cat16 into account in CIECAM:
* Choose the new temperature in "White balance" - for example 6000K.
* Select Color Appearance & Lighting (CIECAM02/16).
* Select: CAM Model = CIECAM16.
* Select CatO2/16 mode = Automatic Symmetric.
* Adjust the temperature in Viewing Conditions to that of the white balance (in this example 6000K),
* Then use the same process as before.

To use the results of this virtual profile for other images, do the following:
* Right click on the thumbnail in the file browserand choose "Processing profile operations" > Copy,then "Paste partial" > "Color management".

Note: the values can of course be adjusted empirically as in ART and Lightroom. For small deviations from the original primaries, the results are fairly predictable. On the other hand, if we make big changes, the results will be less so.

== Output Profile ==

Specify the output color profile; the saved image will be transformed into this color space and the profile will be embedded in the metadata. The effects the output profile has on the image cannot be seen in the preview.

RawTherapee lets you specify "input" (e.g. your camera's profile), "display" (e.g. computer screen) and "output" (e.g. printer) device class profiles with an RGB color space, because RawTherapee saves only RGB images. Profiles listed in this combobox are those which come bundled with RawTherapee and those located in the folder set in Preferences > [[Preferences#Color_Management_Tab|Color Management]].

The soft-proofing feature is dedicated to simulating printer rendering. It lets you preview what your image will look like when printed, assuming you use a printer profile which correctly simulates your printer and paper combination. For best printout quality, after you have tweaked your photo using soft-proofing, you should select your printer profile as the output profile and save the image using it. This ensures that the image is encoded using your printer's color space directly from RawTherapee's internal high quality floating-point representation, instead of being saved to an 8-bit image in sRGB for example and then having to be subsequently converted to the printer profile, which would be quite lossy.

The main histogram, navigator and clipping indicators will use either the working or the output profile. You can choose the behavior by using [[File:gamut-hist.png]] button in the Editor tab.

The recommended output profile when you're saving to an 8-bit format and/or publishing to the web is RTv4_sRGB. If no profile is selected, none will be embedded, which means that "sRGB" is implied, though it is safer to embed RTv4_sRGB to ensure your image is displayed properly in various applications.

RTv4_sRGB is a '''higher quality''' version of the standard sRGB profile, which surprisingly is inconsistent between implementations. RTv4_sRGB was custom-made for RawTherapee and has 4096 LUT points, as opposed to the lower quality 1024 point sRGB profiles. Applications that aren't color managed and won't take advantage of RTv4_sRGB will fall back on sRGB.

Wide-gamut output profiles such as RTv4_Large are generally used if you export to a 16-bit or higher bit-depth format for further editing in another application. If you will be sending your image for printing, a wide-gamut output profile is also recommended, since some printers may have wide gamuts (at least in certain colors).

You should have a wide-gamut monitor if you want to work with wide-gamut profiles, otherwise you're flying in the dark.

=== Bundled Output Profiles ===

RawTherapee comes bundled with a number of custom-made, high quality output profiles. There are two types: ones compatible with [https://en.wikipedia.org/wiki/ICC_profile ICC v2], and ones with [https://www.color.org/whyusev4.xalter v4]. The v4 versions should be compatible with most modern software. The legacy v2 versions are supplied as a fallback.

Each ICC profile's filename describes the ICC version and the primaries of the output space:
* sRGB: similar to sRGB.
* Medium : similar to AdobeRGB1998.
* Large: similar to ProPhoto.
* ACES-AP0: similar to ACES AP0.
* ACES-AP1: similar to ACES AP1.
* Wide: similar to Widegamut.
* Rec2020: similar to Rec2020.
* Best: similar to Best.
* Beta: similar to Beta.
* Bruce : similar to Bruce.

By default all these profiles have a TRC (Tone Reproduction Curve) with gamma=2.4 and slope=12.92.

You can customize these profiles using the [[ICC_Profile_Creator| ICC profile Creator]], which allows you to:
* change the TRC and assign any value from 1 (linear gamma) upwards.
* change the primaries and illuminant to suit your needs.
* change the labels, description etc.

Linux

2021-06-19T07:46:18Z

Thanatomanic: Document TCMALLOC

<div class="pagetitle">Linux</div>

This page details instructions for compiling RawTherapee on '''GNU/Linux''' systems. There are also instructions for compiling on [[Windows]] and [[macOS]].

When in doubt, [[IRC|join us on IRC]] or in the [[Forum]] and ask a human!

== Dependencies ==

To compile RawTherapee your system will need a set of tools and code libraries from other programs. These are called dependencies, and here is a list of them for the latest version of RawTherapee:

{| class="wikitable sortable"
|+ Build-time dependencies for RawTherapee:
! Package !! Version !! URL
|-
| CMake || cmake>=3.5 || https://cmake.org/
|-
| EXIV2 || exiv2>=0.19 || http://www.exiv2.org/
|-
| EXPAT || expat>=2.1.0 || https://libexpat.github.io/
|-
| FFTW3 || fftw>=3.2.2 || http://fftw.org/
|-
| GCC || gcc>=4.9 || https://gcc.gnu.org/
|-
| GLIB2 || glib-2.0>=2.24 || https://www.gtk.org/
|-
| GLIBMM || glibmm-2.4>=2.24 || https://www.gtkmm.org/
|-
| GTK+ || gtk+-3.16 < 3.24.0 || https://www.gtk.org/
|-
| GTKMM || gtkmm-3.16 || https://www.gtkmm.org/
|-
| JPEG || libjpeg>=6b || https://libjpeg-turbo.org/ https://jpegclub.org/ https://www.ijg.org/
|-
| LCMS2 || lcms>=2.6 || https://www.littlecms.com/
|-
| LENSFUN || lensfun>=0.2 || https://github.com/lensfun/lensfun
|-
| LIBCANBERRA || libcanberra>=0.29 || http://0pointer.de/lennart/projects/libcanberra/ (Linux only)
|-
| LIBIPTCDATA || libiptcdata>=1.0.2 || http://libiptcdata.sourceforge.net
|-
| PNG || libpng>=1.2.44 || http://www.libpng.org/
|-
| librsvg || librsvg>=2.40 || https://github.com/GNOME/librsvg
|-
| SIGC || sigc++-2.0 || https://github.com/libsigcplusplus/libsigcplusplus
|-
| TIFF || libtiff>=4.0.4 || http://libtiff.org/
|-
| ZLIB || zlib>=1.2.3 || http://www.zlib.net/
|}

In order to install all these dependencies, you will need to open a console and paste the code from the appropriate section into the console.

The code snippets below list dependencies for the latest RawTherapee code which requires GTK3. We dropped support for GTK2 with release "5.0-r1-gtk2" in February 2017. If you use a modern distribution, just copy and paste the code snippets as they are. If you're on an old distribution without the required GTK3 support, then refer to the archived [[Linux_GTK2|GTK2]] article, then checkout and compile the obsolete <code>5.0-r1-gtk2</code> tag.

=== Arch/Manjaro ===

Current versions of Arch and Manjaro work well out of the box. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 17.1.12.

<pre style="white-space: pre-wrap">sudo pacman -S --needed cmake exiv2 expat fftw glib2 glibmm gtk3 gtkmm3 lcms2 lensfun libcanberra libiptcdata libjpeg-turbo libpng librsvg libsigc++ libtiff zlib</pre>

Proceed to [[#Compilation|Compilation]].

=== CentOS ===

CentOS 7 has very outdated packages and requires extra steps to install a recent GCC, git, lensfun and libtiff. The steps below were verified to work in CentOS 7.4.1708, but proceed at your own risk.

GCC >=4.9.3:
<pre style="white-space: pre-wrap">sudo yum update
sudo yum install cmake git
sudo yum install centos-release-scl
sudo yum install devtoolset-7-gcc*
scl enable devtoolset-7 bash
source /opt/rh/devtoolset-7/enable</pre>

git >=2.7:
<pre style="white-space: pre-wrap">sudo yum install http://opensource.wandisco.com/centos/7/git/x86_64/wandisco-git-release-7-2.noarch.rpm</pre>

lensfun:
<pre style="white-space: pre-wrap">
wget http://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -ivh epel-release-latest-7.noarch.rpm</pre>

libtiff >=4.0.4:
<pre style="white-space: pre-wrap">sudo yum install ninja-build
mkdir ~/programs && cd ~/programs
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
mkdir tiff-4.0.9/libtiff-build && cd tiff-4.0.9/libtiff-build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

Install the other dependencies:
<pre style="white-space: pre-wrap">sudo yum install curl expat-devel fftw-devel gtk3-devel gtkmm30-devel lcms2-devel lensfun-devel libcanberra-devel libiptcdata-devel libjpeg-turbo-devel libpng-devel librsvg2-devel zlib-devel</pre>

Symlink libatomic:
<pre style="white-space: pre-wrap">sudo ln -s /usr/lib64/libatomic.so.1 /usr/lib64/libatomic.so</pre>

As you proceed to the next step - compilation - you will need to edit the <code>build-rawtherapee</code> script and add these three lines to the CMake section near the end of the file, for example after the "-DWITH_BENCHMARK" line before the "$HOME" line:
<pre style="white-space: pre-wrap"> -DTIFF_INCLUDE_DIR="$HOME/programs/tiff-4.0.9/libtiff" \
-DTIFF_LIBRARY="$HOME/programs/tiff-4.0.9/libtiff-build/libtiff/libtiff.so" \
-DCMAKE_CXX_FLAGS="-Wno-deprecated -Wno-parentheses" \
</pre>

Proceed to [[#Compilation|Compilation]].

=== Debian/Ubuntu/Mint/elementary OS ===

Current versions of these distributions work well out of the box (Debian >=9, Ubuntu >=18.04 LTS, Linux Mint >=19, elementary OS >=5). Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo apt install git build-essential cmake curl pkg-config libgtk-3-dev libgtkmm-3.0-dev liblensfun-dev librsvg2-dev liblcms2-dev libfftw3-dev libiptcdata0-dev libtiff5-dev libcanberra-gtk3-dev</pre>

==== Ubuntu 16.04 LTS (Xenial) ====
RawTherapee 5.8 (release) is the latest version supported for Xenial-based distributions. See [https://github.com/Beep6581/RawTherapee/issues/5943 here] for details. When compiling, follow the manual steps and use git to checkout the <code>5.8</code> branch.

==== Ubuntu <=14.04 LTS (Trusty), Debian <=8 (Jessie) ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Ubuntu. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Fedora ===

Current versions of Fedora work well out of the box. Instructions below assume a fully updated system. Additional packages may need to be installed on your particular system.

<pre style="white-space: pre-wrap">sudo dnf install git make cmake curl gcc gcc-c++ gtk3-devel gtkmm30-devel lensfun-devel librsvg2-devel lcms2-devel fftw-devel libiptcdata-devel libtiff-devel libjpeg-turbo-devel libcanberra-devel libatomic</pre>

==== Fedora <=23 ====
RawTherapee 5.6 (release) is the latest version supported for this distribution because of a higher CMake version requirement (see [https://github.com/Beep6581/RawTherapee/issues/5302 here]). When compiling, follow the manual steps and use git to checkout the <code>5.6</code> branch.

==== Fedora 22 ====
In addition to the above notices and requirements, an updated version of <code>libtiff</code> needs to be compiled manually.

<pre style="white-space: pre-wrap">sudo yum install ninja-build
cd ~
wget http://download.osgeo.org/libtiff/tiff-4.0.9.tar.gz
tar zxvf tiff-4.0.9.tar.gz
cd tiff-4.0.9.tar.gz
mkdir build && cd build
cmake -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/libtiff-4.0.9 -DCMAKE_INSTALL_PREFIX=/usr -G Ninja ..
ninja-build
sudo ninja-build install
</pre>

==== Fedora <=21 ====
Refer to the [[Linux_GTK2|GTK2]] article if compiling on earlier versions of Fedora. The GTK3 version of RawTherapee is unsupported in these distributions.

Proceed to [[#Compilation|Compilation]].

=== Gentoo/Sabayon ===

Sabayon users should use the same dependencies as for Gentoo, but instead of <code>sudo emerge -uva</code> use <code>sudo equo install sys-devel/gcc dev-vcs/git</code>.

<pre style="white-space: pre-wrap">sudo emerge -uva dev-cpp/gtkmm:3.0 dev-libs/expat dev-util/cmake media-gfx/exiv2 media-libs/lcms media-libs/lensfun media-libs/libcanberra media-libs/libiptcdata media-libs/libjpeg-turbo media-libs/libpng gnome-base/librsvg media-libs/tiff net-misc/curl sci-libs/fftw sys-libs/zlib x11-libs/gtk+:3</pre>

Proceed to [[#Compilation|Compilation]].

=== openSUSE ===

openSUSE Leap 15 and Tumbleweed should work well out of the box. Serious compilation issues can be expected with other versions. Refer to the [[Linux_GTK2|GTK2]] article if compiling on a version older than 42.1.

<pre style="white-space: pre-wrap">sudo zypper install git cmake gcc gcc-c++ gtk3-devel gtkmm3-devel liblcms2-devel fftw3-devel libitpcdata-devel librsvg-devel libtiff-devel libjpeg8-devel libcanberra-gtk3-devel</pre>

For openSUSE 15.1 and newer, the <code>lensfun</code> library needs to be installed as follows:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-data liblensfun1</pre>

For openSUSE Tumbleweed, the package is slightly different:

<pre style="white-space: pre-wrap">sudo zypper install lensfun-devel</pre>

For other versions of openSUSE <code>lensfun</code> has to be installed manually:

<pre>wget https://sourceforge.net/projects/lensfun/files/0.3.2/lensfun-0.3.2.tar.gz
tar xvf lensfun-0.3.2.tar.gz
cd lensfun-0.3.2.tar.gz
mkdir build
cd build
cmake ../
make
sudo make install</pre>

Proceed to [[#Compilation|Compilation]].

== Compilation ==

There are two general ways you can compile RawTherapee: either use the [[#The_Automatic_Way|automatic]] Bash script which compiles RawTherapee for you (recommended), or do so [[#The_Manual_Way|manually]].

=== The Automatic Way ===

This is the recommended way of compiling RawTherapee as it is fast, simple and fool-proof. It relies on a Bash script which downloads the latest RawTherapee source code and compiles it in a way which is optimized for your CPU. The compiled builds are ready for use. The script does not check for build-time dependencies, so be sure to read the [[#Dependencies|Dependencies]] section before using the script. The compiled builds are standalone, meaning that you can keep several versions of RawTherapee at the same time simply by renaming the build folders so that creating a new build does not overwrite the previous build, which happens by default.

Run the script as a normal user, not as root!

Open a terminal, get the script, make it executable, and run it:
<pre style="white-space: pre-wrap">cd ~
wget https://raw.githubusercontent.com/Beep6581/RawTherapee/dev/tools/build-rawtherapee -O build-rawtherapee
chmod +x build-rawtherapee
./build-rawtherapee</pre>

If everything goes well, the script will terminate with the message, "To run rawtherapee type: ...".

To update RawTherapee if you previously compiled it using this script, just re-run the script. That's it.

The <code>build-rawtherapee</code> script is included in RawTherapee's source code. Since running the script updates the source code, after you compiled your first build you can delete the script you downloaded manually above using wget, and instead use <code>~/programs/code-rawtherapee/tools/build-rawtherapee</code> which will always update itself.

The script compiles the current branch, which by default is <code>dev</code> where most of the development happens. To compile a different branch, check it out using standard git commands before running the script. Read more about RawTherapee's branches below in the [[Linux#Choose_a_branch|Choose a Branch]] section.

For more information, see <code>./build-rawtherapee --help</code>

You have finished, RawTherapee is ready for use. You can skip the "Manual Way" section.

=== The Manual Way ===

The recommended way of compiling RawTherapee is by using the automatic script - see [[#The_Automatic_Way|Compilation: The Automatic Way]]. If you want to learn how to compile manually, read on.

In order to keep your "home" folder clean when manually compiling multiple programs (i.e. when not using your distribution's package manager) and for this manual compilation tutorial to maintain compatibility with the automatic compilation script, you will create the folder <code>~/programs/</code> which will contain all RawTherapee-related source code in the <code>~/programs/code-rawtherapee</code> folder, and the compiled build in the <code>~/programs/rawtherapee</code> folder. You can use the same scheme when compiling other programs.

==== Clone the source ====

First, you need to clone RawTherapee's source code repository. Bring up your console and run this:

<pre style="white-space: pre-wrap">mkdir -p ~/programs
git clone https://github.com/Beep6581/RawTherapee ~/programs/code-rawtherapee
cd ~/programs/code-rawtherapee</pre>

==== Choose a branch ====

* Features are developed on their own feature branches.
* Development happens in the <code>dev</code> branch. Feature branches are merged into the <code>dev</code> branch when they're ready. The <code>dev</code> branch is unstable.
* Releases are tagged in the <code>releases</code> branch.

Checkout the latest tag if you want the most stable code. To see all available tags, type:
<pre style="white-space: pre-wrap">git tag</pre>

Checkout the <code>dev</code> branch or some other feature branch if you want to test the latest bleeding-edge code. To see all available branches, type:
<pre style="white-space: pre-wrap">git branch -a</pre>

Checking out is done via the "git checkout" command. To checkout a tag or a branch, type:
<pre style="white-space: pre-wrap">git checkout <tag or branch></pre>

RawTherapee uses GTK+ for the user interface and requires GTK+ version 3.16 or newer. If your system does not support version 3.16 or newer then you must checkout the <code>5.0-r1-gtk2</code> tag. Our GTK2 support has officially ended on 2 February 2017 - refer to the archived [[Linux_GTK2|GTK2]] article, and update your system.

Compiling old versions of RawTherapee will fail on a modern system, as you will be missing the old dependencies.

==== Compile RawTherapee ====

Now you will make an out-of-source compilation of RawTherapee, it will be built into the <code>~/programs/code-rawtherapee/build/release</code> folder, and then you will move this folder to <code>~/programs/rawtherapee</code>

===== CMake =====

There are a few compilation settings you need to be aware of, you will pass these to CMake using the <code>-D</code> option as described below:

; CMAKE_BUILD_TYPE
: One of: <code>release</code> (default), <code>relwithdebinfo</code> or <code>debug</code>.
: This controls whether the build will favor faster execution time or more verbose debugging output.
: The "debug" and "relwithdebinfo" builds will let you [[How_to_write_useful_bug_reports|get a useful stack-backtrace]] if RawTherapee crashes while running through GDB which you can then submit to us so we can find the problem and fix it. The "debug" build is the slowest but generates the most detailed information. The "relwithdebinfo" build is almost as fast as a "release" build and generates often sufficient information, though not as detailed as a "debug" build. The "release" build will not provide any useful information when it crashes, but does contain many speed optimizations resulting in a program that works several times faster than the "debug" build would. For normal use, make a "release" or "relwithdebinfo" build. If you find a reproducible bug, then make a "debug" build and send us a stack-backtrace (or fix it yourself and send us the patch!). We prefer stack backtraces from debug builds than from relwithdebinfo ones.
:: To make a "release" type build, set: <code>-DCMAKE_BUILD_TYPE="release"</code>

; USE_OLD_CXX_ABI
: <code>ON</code> or <code>OFF</code> (default).
: When compiling a program, one must use the same conventions as those used by the libraries which that program relies upon, otherwise compilation (linking) will fail. Generally one does not need to concern oneself with this, but we are now at a time when GCC4 is being phased out by GCC5, each by default using a convention incompatible with the other, and so this issue is relevant. If the libraries on your system have been compiled using GCC5, they probably use a standard called C++11. This means that your RawTherapee build must use the same standard, which is the case by default. However, if despite using GCC5 your libraries were built using the older C++03 standard, then RawTherapee must be set to use the same, and this is when you would set "USE_OLD_CXX_ABI" to "ON".
:: To enable USE_OLD_CXX_ABI, set: <code>-DUSE_OLD_CXX_ABI="ON"</code>

; CACHE_NAME_SUFFIX
: The CACHE_NAME_SUFFIX options sets the suffix of the cache and config folder names the compiled RawTherapee build will use. See the [[File Paths]] article for an explanation of what those are.
: For stable releases (if you checkout the "releases" branch) use <code>-DCACHE_NAME_SUFFIX=""</code>
: For development builds (if you checkout the "dev" branch or any branch other than "releases") use <code>-DCACHE_NAME_SUFFIX="5-dev"</code>

; PROC_TARGET_NUMBER
: From <code>0</code> (default) to <code>9</code>.
: The PROC_TARGET_NUMBER option sets which CPU type to optimize for.
: If building for yourself, use "2". It means "native", so the optimizations will be automatically detected for your CPU and RawTherapee will perform as fast as possible on your CPU. It might not run at all on older or other CPU architectures.
: If building for distribution (for other people), use "1". It means "generic", so only optimizations supported by most CPUs will be used, meaning the build can be downloaded and used by anyone, though it won't benefit from the best optimizations possible for the user's CPU.
: For more info, see the file "ProcessorTargets.cmake" in the cloned repository.
:: To make a build using "native" optimizations, set: <code>-DPROC_TARGET_NUMBER="2"</code>

; BUILD_BUNDLE
: <code>ON</code> or <code>OFF</code>.
: Forced to "ON" for Windows and macOS. Optional in Linux where it is "OFF" by default.
: If set to ON, the program will be built into the <code>DATADIR</code> folder, otherwise it will be installed relative to <code>CMAKE_INSTALL_PREFIX</code> which would typically be system-wide.

; BUNDLE_BASE_INSTALL_DIR
: Use an absolute path.
: The program will be built into this folder.
: For example, set it to: <code>-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee"</code>
: If it is not set, the default is to use <code>${CMAKE_BINARY_DIR}/${CMAKE_BUILD_TYPE}</code>

; LENSFUNDBDIR
: Unset by default.
: The <code>LENSFUNDBDIR</code> option permits to locate the lensfun database in the specified directory. It can be unset, absolute or relative.
: When unset, Lensfun uses its own logic to find the database. This is the recommended option if you have Lensfun installed system-wide and want to use it.
: You can set it to a relative or absolute path if you want to use a custom lensfun database.
: If building a bundle, it is relative to the bundle's root folder, otherwise it is relative to <code>DATADIR</code>, i.e. <code>${CMAKE_INSTALL_PREFIX}/share/rawtherapee</code>

; OPTION_OMP
: <code>ON</code> (default) or <code>OFF</code>.
: Build with OpenMP support when enabled, which enables multithreading and makes RawTherapee much faster.

; WITH_LTO
: <code>ON</code> or <code>OFF</code> (default).
: Build with link-time optimizations when enabled, which may make RawTherapee run a little faster.

; WITH_PROF
: <code>ON</code> or <code>OFF</code> (default).
: For debugging purposes. Generate extra code to write profile information suitable for the analysis program gprof.

; WITH_SAN
: <code>OFF</code> (default) or one of various other options.
: For debugging purposes. Allows enabling various sanitizers to help detect program issues.
: See GCC manual's [https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html Program Instrumentation Options] chapter for more information.

; WITH_SYSTEM_KLT
: <code>ON</code> or <code>OFF</code> (default).
: Build using system KLT library when ON, otherwise use KLT files bundled with RawTherapee.
: The Kanade–Lucas–Tomasi (KLT) feature tracker is used by the [[Lens/Geometry#Distortion_Correction|Auto Distortion Correction]] tool.

; WITH_BENCHMARK
: <code>ON</code> or <code>OFF</code> (default).
: Build with timing functions enabled to benchmark performance.

; ENABLE_TCMALLOC
: <code>ON</code> or <code>OFF</code> (default).
: In some cases the operating system has trouble handling memory allocation and deallocation required by RawTherapee (see [https://github.com/Beep6581/RawTherapee/issues/5459 here] for more information). Linking against [https://gperftools.github.io/gperftools/tcmalloc.html TCMalloc] may alleviate these problems. This library may not be available on all platforms or distributions.

===== Make =====

Find out how many threads your CPU supports. This only influences the compilation speed, it has no influence over how fast the compiled RawTherapee build runs. To find out how many threads your CPU supports, run this in a terminal:
<pre style="white-space: pre-wrap">nproc --all</pre>
It will return a number. Use this number for the <code>--jobs</code> parameter below.

Compile:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
mkdir build
cd build

cmake \
-DCMAKE_BUILD_TYPE="release" \
-DCACHE_NAME_SUFFIX="5-dev" \
-DPROC_TARGET_NUMBER="2" \
-DBUILD_BUNDLE="ON" \
-DBUNDLE_BASE_INSTALL_DIR="$HOME/programs/rawtherapee" \
-DOPTION_OMP="ON" \
-DWITH_LTO="OFF" \
-DWITH_PROF="OFF" \
-DWITH_SAN="OFF" \
-DWITH_SYSTEM_KLT="OFF" \
..

make --jobs=4
make install
</pre>

==== Run RawTherapee ====

To run RawTherapee:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee</pre>
Or to run the CLI version:
<pre style="white-space: pre-wrap">~/programs/rawtherapee/rawtherapee-cli</pre>

The source code repository is in <code>~/programs/code-rawtherapee</code> and the compiled program is in <code>~/programs/rawtherapee</code>

You can safely delete <code>~/programs/code-rawtherapee</code> if you so wish. The compiled program will still work, but then you will have to redo all the above steps if you want to update. Rather, leave the repository intact so that you can do the next step in a week or a month's time when you want to update.

==== Update RawTherapee ====

Every time you want to update RawTherapee to the latest code available, just do the following:
<pre style="white-space: pre-wrap">cd ~/programs/code-rawtherapee
git pull</pre>

Then repeat the [[#Make|Make]] step above.

When updating, you can re-use the <code>build</code> folder from last time to avoid having to recompile things which have not changed, to make the whole process faster. CMake should automatically detect changes. However, there are situations when compilation may fail when re-using an old <code>build</code> folder - typically that might happen when hopping between very different branches. If that happens, just delete the <code>build</code> folder, then proceed with the steps in the "Make" section.

Local Contrast

2021-06-19T07:21:14Z

Thanatomanic: Added information about the position in the pipeline

<div class="pagetitle">Local Contrast</div>

The Local Contrast tool adds local contrast to an image by applying an unsharp mask with a large blur radius. It it an easy way to give an image a little more 'punch'. In effect, the image is blended with a blurred version of itself, amplifying the local tones (highlights get lighter, shadows get darker), thus creating more contrast. The contrast can be tuned by several parameters explained below.

This tool was first implemented by [http://gmic.eu/ G'MIC] and then ported to RawTherapee. Its effect is applied in L*a*b* space and only on the lightness channel. Its position in the [http://rawpedia.rawtherapee.com/Toolchain_Pipeline processing pipeline] is after the Shadows / Highlight tool and before all other tools that operate in L*a*b* space.

<div class="img-comp-wrapper">
<div class="thumbinner thumbcompare tnone" style="width: 500px">
<imgcomp img1='LocalContrast-Off.jpg' img2='LocalContrast-On.jpg' width=500 />
<div class="thumbcaption">
'''Left side:''' original image<br>
'''Right side:''' image with local contrast applied (Radius = 100, Amount = 0.5)
</div>
</div>
</div>

=== Parameters ===
* '''Radius''' determines the extent of the local contrast (i.e. the radius of the blurring). Higher values give a smoother, but stronger contrast. Lower values give a more localized, less pronounced contrast.
* '''Amount''' determines the overall strength of the effect. Higher values amplify the differences between the original image and the blurred image, thereby increasing contrast.
* '''Darkness level''' modifies only those areas of the image that were darkened with respect to the original. Higher values amplify the change (making darker parts even darker), lower values diminish the change. N.B. A value of 0 means the local contrast is only modified by making the image lighter.
* '''Lightness level''' works similarly, but only on areas that were lightened.

Note that setting both the "Darkness level" and "Lightness level" to 0 effectively disables the tool.

Local Contrast

2021-06-19T07:17:05Z

Thanatomanic: Preliminary text

<div class="pagetitle">Local Contrast</div>

The Local Contrast tool adds local contrast to an image by applying an unsharp mask with a large blur radius. It it an easy way to give an image a little more 'punch'. In effect, the image is blended with a blurred version of itself, amplifying the local tones (highlights get lighter, shadows get darker), thus creating more contrast. The contrast can be tuned by several parameters explained below.

This tool was first implemented by [http://gmic.eu/ G'MIC] and then ported to RawTherapee. Its effect is applied in L*a*b*-space and only on the lightness channel.

<div class="img-comp-wrapper">
<div class="thumbinner thumbcompare tnone" style="width: 500px">
<imgcomp img1='LocalContrast-Off.jpg' img2='LocalContrast-On.jpg' width=500 />
<div class="thumbcaption">
'''Left side:''' original image<br>
'''Right side:''' image with local contrast applied (Radius = 100, Amount = 0.5)
</div>
</div>
</div>

=== Parameters ===
* '''Radius''' determines the extent of the local contrast (i.e. the radius of the blurring). Higher values give a smoother, but stronger contrast. Lower values give a more localized, less pronounced contrast.
* '''Amount''' determines the overall strength of the effect. Higher values amplify the differences between the original image and the blurred image, thereby increasing contrast.
* '''Darkness level''' modifies only those areas of the image that were darkened with respect to the original. Higher values amplify the change (making darker parts even darker), lower values diminish the change. N.B. A value of 0 means the local contrast is only modified by making the image lighter.
* '''Lightness level''' works similarly, but only on areas that were lightened.

Note that setting both the "Darkness level" and "Lightness level" to 0 effectively disables the tool.

File:LocalContrast-Off.jpg

2021-06-19T07:15:09Z

Thanatomanic:

== Licensing ==
{{cc-by-sa-4.0}}

File:LocalContrast-On.jpg

2021-06-19T07:14:47Z

Thanatomanic:

== Licensing ==
{{cc-by-sa-4.0}}

Dynamic Range Compression

2021-06-17T08:48:19Z

Thanatomanic: List and italics

<div class="pagetitle">Dynamic Range Compression</div>

== Introduction ==

Dynamic range is the ratio of the largest to the smallest value of a measured signal. In photography it commonly refers to the ratio of the brightest element of a scene to the darkest. An outdoor scene on a very foggy day commonly has very little difference between the brightest and darkest elements, which is known as a ''low dynamic range'' scene. In contrast, an indoor scene with a visible sunny sky through a window is known as a ''high dynamic range'' scene.

The dynamic range of a scene can easily exceed the dynamic range of the "sensor" that captures the scene. The [https://en.wikipedia.org/wiki/Dynamic_range#Human_perception human visual system] has an adaptive and wide dynamic range (you can see faint stars at night but also bright skies during day). This is very different from the fixed, lower dynamic range of your camera sensor and the (usually even lower) dynamic range of your monitor. As such, photography and image processing needs to deal with mapping high dynamic ranges to lower ones.

In general there are two ways to handle dynamic range changes: either discard a portion of the data outside the destination range (e.g. clipping highlights), or compress the data so that it fits the destination range. The Dynamic Range Compression tool uses the latter approach based on the [http://www.cs.huji.ac.il/~danix/hdr/ Gradient Domain High Dynamic Range Compression] algorithm developed by R. Fattal and coworkers. This algorithm is often simply referred to as "Fattal", e.g. in Luminance HDR.

The algorithm uses two parameters to control the compression (α and β) which can be tuned by the "detail" and "amount" sliders of the tool, respectively. The tool operates in RGB space and is applied right after [[Noise_Reduction|Noise Reduction]] and [[Haze_Removal|Haze Removal]], but before other tone curve adjustments such as the [[Exposure]] controls.

N.B. There are alternative ways of compressing the dynamic range using other tools. The simplest would be a negative contrast value in the [[Exposure]] tool to reduce (or rather to redistribute) the dynamic range, however the effect would most likely appear flat and unappealing. A curve gives more control over the process, but may need a lot of fine-tuning.

== Usage ==

Use this tool when the dynamic range of the photographed scene is too high to be reproduced on your monitor in an aesthetically pleasing way, that is when you find that the difference between the dark tones and the bright tones (the contrast) is so strong that there is a lack of detail in those areas.

'''Note for panorama's''' The effects of this tool depend on the dynamic range (and histogram) of the image being edited. If you are processing a series of images intended for stitching, where each image contains a section of a scene adjacent to the one before it, even if you were to apply identical parameters to these images using this tool, the end results would not be consistent - there would be sudden changes in brightness between adjacent images. Do not use this Dynamic Range Compression tool on the source images. If you need to compress the dynamic range across a series of images in a consistent way, use a curve instead. You can, however, use this tool on the stitched panorama.

== Interface ==

The tool provides three sliders.
* ''Amount'' sets the strength of the compression. Higher values lead to a narrower dynamic range (you can easily see the effect by observing the histogram).
* ''Detail'' sets how much local contrast is preserved. Positive values reduce the compression in favor of more contrast, negative values reduce the contrast.
* ''Anchor'' biases the compression towards the shadows or highlights, effectively functioning as an exposure compensation.

The example below shows the typical effects of each slider (click to enlarge).

[[File:DRC-Example.jpg]]

Dynamic Range Compression

2021-06-17T08:46:54Z

Thanatomanic: /* Interface */

<div class="pagetitle">Dynamic Range Compression</div>

== Introduction ==

Dynamic range is the ratio of the largest to the smallest value of a measured signal. In photography it commonly refers to the ratio of the brightest element of a scene to the darkest. An outdoor scene on a very foggy day commonly has very little difference between the brightest and darkest elements, which is known as a ''low dynamic range'' scene. In contrast, an indoor scene with a visible sunny sky through a window is known as a ''high dynamic range'' scene.

The dynamic range of a scene can easily exceed the dynamic range of the "sensor" that captures the scene. The [https://en.wikipedia.org/wiki/Dynamic_range#Human_perception human visual system] has an adaptive and wide dynamic range (you can see faint stars at night but also bright skies during day). This is very different from the fixed, lower dynamic range of your camera sensor and the (usually even lower) dynamic range of your monitor. As such, photography and image processing needs to deal with mapping high dynamic ranges to lower ones.

In general there are two ways to handle dynamic range changes: either discard a portion of the data outside the destination range (e.g. clipping highlights), or compress the data so that it fits the destination range. The Dynamic Range Compression tool uses the latter approach based on the [http://www.cs.huji.ac.il/~danix/hdr/ Gradient Domain High Dynamic Range Compression] algorithm developed by R. Fattal and coworkers. This algorithm is often simply referred to as "Fattal", e.g. in Luminance HDR.

The algorithm uses two parameters to control the compression (α and β) which can be tuned by the "detail" and "amount" sliders of the tool, respectively. The tool operates in RGB space and is applied right after [[Noise_Reduction|Noise Reduction]] and [[Haze_Removal|Haze Removal]], but before other tone curve adjustments such as the [[Exposure]] controls.

N.B. There are alternative ways of compressing the dynamic range using other tools. The simplest would be a negative contrast value in the [[Exposure]] tool to reduce (or rather to redistribute) the dynamic range, however the effect would most likely appear flat and unappealing. A curve gives more control over the process, but may need a lot of fine-tuning.

== Usage ==

Use this tool when the dynamic range of the photographed scene is too high to be reproduced on your monitor in an aesthetically pleasing way, that is when you find that the difference between the dark tones and the bright tones (the contrast) is so strong that there is a lack of detail in those areas.

'''Note for panorama's''' The effects of this tool depend on the dynamic range (and histogram) of the image being edited. If you are processing a series of images intended for stitching, where each image contains a section of a scene adjacent to the one before it, even if you were to apply identical parameters to these images using this tool, the end results would not be consistent - there would be sudden changes in brightness between adjacent images. Do not use this Dynamic Range Compression tool on the source images. If you need to compress the dynamic range across a series of images in a consistent way, use a curve instead. You can, however, use this tool on the stitched panorama.

== Interface ==

The tool provides three sliders. The '''Amount''' sets the strength of the compression. Higher values lead to a narrower dynamic range (you can easily see the effect by observing the histogram). The '''Detail''' sets how much local contrast is preserved. Positive values reduce the compression in favor of more contrast, negative values reduce the contrast. The '''Anchor''' biases the compression towards the shadows or highlights, effectively functioning as an exposure compensation.

The example below shows the typical effects of each slider (click to enlarge).

[[File:DRC-Example.jpg]]

Dynamic Range Compression

2021-06-17T08:45:18Z

Thanatomanic: Update text and include sample image

<div class="pagetitle">Dynamic Range Compression</div>

== Introduction ==

Dynamic range is the ratio of the largest to the smallest value of a measured signal. In photography it commonly refers to the ratio of the brightest element of a scene to the darkest. An outdoor scene on a very foggy day commonly has very little difference between the brightest and darkest elements, which is known as a ''low dynamic range'' scene. In contrast, an indoor scene with a visible sunny sky through a window is known as a ''high dynamic range'' scene.

The dynamic range of a scene can easily exceed the dynamic range of the "sensor" that captures the scene. The [https://en.wikipedia.org/wiki/Dynamic_range#Human_perception human visual system] has an adaptive and wide dynamic range (you can see faint stars at night but also bright skies during day). This is very different from the fixed, lower dynamic range of your camera sensor and the (usually even lower) dynamic range of your monitor. As such, photography and image processing needs to deal with mapping high dynamic ranges to lower ones.

In general there are two ways to handle dynamic range changes: either discard a portion of the data outside the destination range (e.g. clipping highlights), or compress the data so that it fits the destination range. The Dynamic Range Compression tool uses the latter approach based on the [http://www.cs.huji.ac.il/~danix/hdr/ Gradient Domain High Dynamic Range Compression] algorithm developed by R. Fattal and coworkers. This algorithm is often simply referred to as "Fattal", e.g. in Luminance HDR.

The algorithm uses two parameters to control the compression (α and β) which can be tuned by the "detail" and "amount" sliders of the tool, respectively. The tool operates in RGB space and is applied right after [[Noise_Reduction|Noise Reduction]] and [[Haze_Removal|Haze Removal]], but before other tone curve adjustments such as the [[Exposure]] controls.

N.B. There are alternative ways of compressing the dynamic range using other tools. The simplest would be a negative contrast value in the [[Exposure]] tool to reduce (or rather to redistribute) the dynamic range, however the effect would most likely appear flat and unappealing. A curve gives more control over the process, but may need a lot of fine-tuning.

== Usage ==

Use this tool when the dynamic range of the photographed scene is too high to be reproduced on your monitor in an aesthetically pleasing way, that is when you find that the difference between the dark tones and the bright tones (the contrast) is so strong that there is a lack of detail in those areas.

'''Note for panorama's''' The effects of this tool depend on the dynamic range (and histogram) of the image being edited. If you are processing a series of images intended for stitching, where each image contains a section of a scene adjacent to the one before it, even if you were to apply identical parameters to these images using this tool, the end results would not be consistent - there would be sudden changes in brightness between adjacent images. Do not use this Dynamic Range Compression tool on the source images. If you need to compress the dynamic range across a series of images in a consistent way, use a curve instead. You can, however, use this tool on the stitched panorama.

== Interface ==

The tool provides three sliders. The '''Amount''' sets the strength of the compression. Higher values lead to a narrower dynamic range (you can easily see the effect by observing the histogram). The '''Detail''' sets how much local contrast is preserved. Positive values reduce the compression in favor of more contrast, negative values reduce the contrast. The '''Anchor''' biases the compression towards the shadows or highlights, effectively functioning as an exposure compensation.

The example below shows the typical effects of each slider.

[[File:DRC-Example.jpg]]

File:DRC-Example.jpg

2021-06-17T08:40:51Z

Thanatomanic: Example of the effects of the Dynamic Range Compression tool.

== Summary ==
Example of the effects of the Dynamic Range Compression tool.
== Licensing ==
{{PD}}

Dynamic Range Compression

2021-06-17T08:03:43Z

Thanatomanic: /* Usage */

<div class="pagetitle">Dynamic Range Compression</div>

== Introduction ==

Dynamic range is the ratio of the largest to the smallest value of a measured signal. In photography it commonly refers to the ratio of the brightest element of a scene to the darkest. An outdoor scene on a very foggy day commonly has very little difference between the brightest and darkest elements, which is known as a ''low dynamic range'' scene. In contrast, an indoor scene with a visible sunny sky through a window is known as a ''high dynamic range'' scene.

The dynamic range of a scene can easily exceed the dynamic range of the "sensor" that captures the scene. The [https://en.wikipedia.org/wiki/Dynamic_range#Human_perception human visual system] has an adaptive and wide dynamic range (you can see faint stars at night but also bright skies during day). This is very different from the fixed, lower dynamic range of your camera sensor and the (usually even lower) dynamic range of your monitor. As such, photography and image processing needs to deal with mapping high dynamic ranges to lower ones.

In general there are two ways to handle dynamic range changes: either discard a portion of the data outside the destination range (e.g. clipping highlights), or compress the data so that it fits the destination range. The Dynamic Range Compression tool uses the latter approach based on the [http://www.cs.huji.ac.il/~danix/hdr/ Gradient Domain High Dynamic Range Compression] algorithm developed by R. Fattal and coworkers. This algorithm is often simply referred to as "Fattal", e.g. in Luminance HDR.

The algorithm uses two parameters to control the compression (α and β) which can be tuned by the "detail" and "amount" sliders of the tool, respectively. The tool operates in RGB space and is applied right after [[Noise_Reduction|Noise Reduction]] and [[Haze_Removal|Haze Removal]], but before other tone curve adjustments such as the [[Exposure]] controls.

N.B. There are alternative ways of compressing the dynamic range using other tools. The simplest would be a negative contrast value in the [[Exposure]] tool to reduce (or rather to redistribute) the dynamic range, however the effect would most likely appear flat and unappealing. A curve gives more control over the process, but may need a lot of fine-tuning.

== Usage ==

Use this tool when the dynamic range of the photographed scene is too high to be reproduced on your monitor in an aesthetically pleasing way, that is when you find that the difference between the dark tones and the bright tones (the contrast) is so strong that there is a lack of detail in those areas.

'''Note for panorama's''' The effects of this tool depend on the dynamic range (and histogram) of the image being edited. If you are processing a series of images intended for stitching, where each image contains a section of a scene adjacent to the one before it, even if you were to apply identical parameters to these images using this tool, the end results would not be consistent - there would be sudden changes in brightness between adjacent images. Do not use this Dynamic Range Compression tool on the source images. If you need to compress the dynamic range across a series of images in a consistent way, use a curve instead. You can, however, use this tool on the stitched panorama.

== Interface ==

=== Amount ===

Sets the amount of compression, where higher values lead to more dynamic range compression.

=== Detail ===

The amount of detail that is preserved can be tuned with this parameter. Negative values smooth the image by reducing local contrast, while positive values increase it.

=== Anchor ===

This parameter biases the compression towards the shadows or the highlights. It functions in effect as an exposure compensation.

Dynamic Range Compression

2021-06-17T08:02:46Z

Thanatomanic: Rewritten more compactly

<div class="pagetitle">Dynamic Range Compression</div>

== Introduction ==

Dynamic range is the ratio of the largest to the smallest value of a measured signal. In photography it commonly refers to the ratio of the brightest element of a scene to the darkest. An outdoor scene on a very foggy day commonly has very little difference between the brightest and darkest elements, which is known as a ''low dynamic range'' scene. In contrast, an indoor scene with a visible sunny sky through a window is known as a ''high dynamic range'' scene.

The dynamic range of a scene can easily exceed the dynamic range of the "sensor" that captures the scene. The [https://en.wikipedia.org/wiki/Dynamic_range#Human_perception human visual system] has an adaptive and wide dynamic range (you can see faint stars at night but also bright skies during day). This is very different from the fixed, lower dynamic range of your camera sensor and the (usually even lower) dynamic range of your monitor. As such, photography and image processing needs to deal with mapping high dynamic ranges to lower ones.

In general there are two ways to handle dynamic range changes: either discard a portion of the data outside the destination range (e.g. clipping highlights), or compress the data so that it fits the destination range. The Dynamic Range Compression tool uses the latter approach based on the [http://www.cs.huji.ac.il/~danix/hdr/ Gradient Domain High Dynamic Range Compression] algorithm developed by R. Fattal and coworkers. This algorithm is often simply referred to as "Fattal", e.g. in Luminance HDR.

The algorithm uses two parameters to control the compression (α and β) which can be tuned by the "detail" and "amount" sliders of the tool, respectively. The tool operates in RGB space and is applied right after [[Noise_Reduction|Noise Reduction]] and [[Haze_Removal|Haze Removal]], but before other tone curve adjustments such as the [[Exposure]] controls.

N.B. There are alternative ways of compressing the dynamic range using other tools. The simplest would be a negative contrast value in the [[Exposure]] tool to reduce (or rather to redistribute) the dynamic range, however the effect would most likely appear flat and unappealing. A curve gives more control over the process, but may need a lot of fine-tuning.

== Usage ==

Use this tool when the dynamic range of the photographed scene is too high to be reproduced on your monitor in an aesthetically pleasing way, that is when you find that the difference between the dark tones and the bright tones (the contrast) is so strong that there is a lack of detail in those areas.

Heads-up panorama stitchers! The effects of this tool depend on the dynamic range (and histogram) of the image being edited. If you are processing a series of images intended for stitching, where each image contains a section of a scene adjacent to the one before it, even if you were to apply identical parameters to these images using this tool, the end results would not be consistent - there would be sudden changes in brightness between adjacent images. Do not use this Dynamic Range Compression tool on the source images. If you need to compress the dynamic range across a series of images in a consistent way, use a curve instead. You can, however, use this tool on the stitched panorama.

== Interface ==

=== Amount ===

Sets the amount of compression, where higher values lead to more dynamic range compression.

=== Detail ===

The amount of detail that is preserved can be tuned with this parameter. Negative values smooth the image by reducing local contrast, while positive values increase it.

=== Anchor ===

This parameter biases the compression towards the shadows or the highlights. It functions in effect as an exposure compensation.

Spot Removal

2021-06-17T07:18:49Z

Thanatomanic: Added title

<div class="pagetitle">Spot Removal</div>

The spot removal tool can be used to mask portions of an image (e.g. blemishes, sensor dust) with another part of the same image. You can even use it to remove entire objects from an image, like in the example below.

[[File:SpotRemoval-Example.jpg]]

=== Activate spot editing mode ===

In order to add, remove or change spots, the spot editing mode needs to be active. Toggle this mode using the [[File:Edit-point.png]] button.

=== Adding spots ===

Ctrl-click on the location that you want to mask ("destination", solid lines) and drag the mouse to set the replacement location ("source", dotted lines). The area under the source will replace the area of the destination. A line connects the two areas, which helps identification if you add multiple spots. You can move both areas after placement by clicking within the inner circle and dragging. The thicker inner circle determines the size of the replacement area, the outer line determines a feather that gradually blends with the surrounding image. Both circles can be adjusted in size after the spot has been placed (within a certain size range).

=== Removing spots ===

Right click on any part of the spot to remove it.

Spot Removal

2021-06-17T07:17:55Z

Thanatomanic: Preliminary text

The spot removal tool can be used to mask portions of an image (e.g. blemishes, sensor dust) with another part of the same image. You can even use it to remove entire objects from an image, like in the example below.

[[File:SpotRemoval-Example.jpg]]

=== Activate spot editing mode ===

In order to add, remove or change spots, the spot editing mode needs to be active. Toggle this mode using the [[File:Edit-point.png]] button.

=== Adding spots ===

Ctrl-click on the location that you want to mask ("destination", solid lines) and drag the mouse to set the replacement location ("source", dotted lines). The area under the source will replace the area of the destination. A line connects the two areas, which helps identification if you add multiple spots. You can move both areas after placement by clicking within the inner circle and dragging. The thicker inner circle determines the size of the replacement area, the outer line determines a feather that gradually blends with the surrounding image. Both circles can be adjusted in size after the spot has been placed (within a certain size range).

=== Removing spots ===

Right click on any part of the spot to remove it.

File:SpotRemoval-Example.jpg

2021-06-17T06:59:13Z

Thanatomanic: Thanatomanic uploaded a new version of File:SpotRemoval-Example.jpg

== Summary ==
Spot removal can even remove entire objects from an image
== Licensing ==
{{PD}}

File:SpotRemoval-Example.jpg

2021-06-17T06:56:24Z

Thanatomanic: Spot removal can even remove entire objects from an image

== Summary ==
Spot removal can even remove entire objects from an image
== Licensing ==
{{PD}}

Editor Tab Modes

2021-06-17T06:44:38Z

Thanatomanic: Changed redirect target from The Image Editor Tab#Editor to Editor

#REDIRECT [[Editor]].

Editor Tab Modes

2021-06-17T06:44:22Z

Thanatomanic: Changed redirect target from The Image Editor Tab#Editor Tab Modes to The Image Editor Tab#Editor

#REDIRECT [[The_Image_Editor_Tab#Editor]].

Wavelet

2021-06-17T06:43:29Z

Thanatomanic: Changed redirect target from Wavelets to Wavelet Levels

#REDIRECT [[Wavelet Levels]]

Main Page

2021-06-17T06:40:30Z

Thanatomanic: /* Local Adjustements Tab */

<div class="main-page-title">RawPedia. The encyclopedia of RawTherapee, raw shooting and everything raw</div>

[[File:08_rt57_mushroom_blades_rawpedia.png|600px|right|link=]]

<div class="greetings">
Welcome to '''RawTherapee's''' documentation!

If you're a new user, don't miss the [[Getting Started]] page to quickly learn your way around this awesome raw image processing program.

If you're an experienced user, here you have an index of all the topics covered.
</div>

<div class=langsbox-wrapper>
<div class="row small-uncollapse large-collapse langsbox">
<span class="langsavail">In other languages</span>
<ul class="small-block-grid-2 medium-block-grid-4 large-block-grid-7 columns flagsbox">
<li>[[File:braz.png|90x60px|frameless|link=Main_Page/pt|Brasileiro]]<br>[[Main_Page/pt|Brasileiro]]</li>
<li>[[File:ct.png|90x60px|frameless|link=Main_Page/ca|Català]]<br>[[Main_Page/ca|Català]]</li>
<li>[[File:deu.png|90x60px|frameless|link=Main_Page/de|Deutsch]]<br>[[Main_Page/de|Deutsch]]</li>
<li>[[File:esp.png|90x60px|frameless|link=Main_Page/es|Español]]<br>[[Main_Page/es|Español]]</li>
<li>[[File:frc.png|90x60px|frameless|link=Main_Page/fr|Française]]<br>[[Main_Page/fr|Français]]</li>
<li>[[File:ita.png|90x60px|frameless|link=Main_Page/it|Italiano]]<br>[[Main_Page/it|Italiano]]</li>
<li>[[File:jap.png|90x60px|frameless|link=Main_Page/jp|日本]]<br>[[Main_Page/jp|日本語]]</li>
</ul>
</div>
</div>

<br style="clear: both;">

== RawTherapee ==

<div class="container">
=== General Information ===

<div class="RP3columns">
* [[Getting Started]]
* [[Features]]
* [[Download]]
* [[The Floating Point Engine]]
* [[Bit Depth]]
* [[RGB and Lab]]
* [[About Noise Reduction]]
* [[File Browser|The File Browser]]
* [[Queue|The Queue]]
* [[Editor|The Editor]]
* [[Batch Adjustments - Sync]]
* [[Saving Images]]
* [[Edit Current Image in External Editor]]
* [[Adding Support for New Raw Formats]]
* [[File Paths]]
* [[Preferences]]
* [[GIMP Plugin]]
* [[ICC Profile Creator]]
* [[Making a Portable Installation]]
* [[Command-Line Options]]
* [[Keyboard Shortcuts]]
* [[Toolchain Pipeline|Toolchain pipeline - Colorimetry]]
</div>
<hr/>

=== Processing Profiles ===

<div class="RP3columns">

<div class="keeptogether">
* [[Sidecar Files - Processing Profiles]]
* [[Creating processing profiles for general use]]
* [[Dynamic processing profiles]]
</div>

<div class="keeptogether">
==== Processing Profile Scripts ====
* [[RTProfileSelector]]
* [[RTbatch]]
</div>

<div class="keeptogether">
==== Bundled Processing Profiles ====
* [[Neutral]]
* [[Auto-Matched Curve]]
* [[Standard Film Curve]]
* [[Pop]]
* [[Unclipped]]
</div>
</div>
<hr/>

=== Tool Description ===

<div class="RP1columns">
* [[General Comments About Some Toolbox Widgets]]
* [[Favorites Tab]]
</div>

<div class="RP3columns">

<div class="keeptogether">
==== Exposure Tab ====

* [[Exposure]]
* [[Shadows/Highlights]]
* [[Tone Mapping]]
* [[Dynamic Range Compression]]
* [[Vignetting Filter]]
* [[Graduated Filter]]
* [[Lab Adjustments|L*a*b* Adjustments]]
</div>

<div class="keeptogether">
==== Detail Tab ====

* [[Spot Removal]]
* [[Sharpening]]
* [[Local Contrast]]
* [[Edges and Microcontrast]]
* [[Impulse Noise Reduction]]
* [[Noise Reduction]]
* [[Defringe]]
* [[Contrast by Detail Levels]]
* [[Haze Removal]]
</div>

<div class="keeptogether">

==== Color Tab ====

* [[White Balance]]
* [[Vibrance]]
* [[Channel Mixer]]
* [[Black-and-White]]
* [[Black-and-White addon]]
* [[HSV Equalizer]]
* [[Film Simulation]]
* [[Film Negative]]
* [[Soft Light]]
* [[RGB Curves]]
* [[Color Toning]]
* [[Color Management]]
* [[Color Management addon | Color Management Supplement]]
</div>

<div class="keeptogether">

==== Advanced Tab ====

* [[Retinex]]
* [[CIECAM02|CIE Color Appearance Model 2002/16 - Cat02/Cat16 - Log encoding]]
* [[Wavelet Levels]]
</div>

<div class="keeptogether">

==== Local Tab====
* [[Local Adjustments]]
</div>
<div class="keeptogether">

==== Transform Tab ====

* [[Crop]]
* [[Resize]]
* [[Lens/Geometry]]
</div>

<div class="keeptogether">
==== Raw Tab ====

* [[Sensor with Bayer/X-Trans Matrix]]
* [[Demosaicing]]
* [[Raw Black Points]]
* [[Preprocessing]]
* [[Chromatic Aberration Correction]]
* [[Raw White Points]]
* [[Preprocessing White Balance]]
* [[Dark-Frame]]
* [[Flat-Field]]
* [[Capture Sharpening]]
</div>

<div class="keeptogether">

==== Metadata Tab ====

* [[Metadata Copy Mode]]
* [[Exif Tab]]
* [[IPTC Tab]]
</div>
</div>
<hr/>

=== Interact ===

<div class="RP1columns">
* [[Forum]]
* [[IRC]]
</div>

=== Compiling ===

<div class="RP1columns">
* In [[Linux]]
* In [[Windows]]
* In [[macOS]]
</div>

=== Troubleshooting ===

<div class="RP1columns">
* [[How to write useful bug reports]]
* [[How to fix crashes on startup]]
* [[Wayland]]
</div>

=== Localization ===

<div class="RP1columns">
* [[Translating RawTherapee]]
* [[Translating RawPedia]]
</div>
</div>

== RawPedia ==

<div class="container">
<div class="RP1columns">
* [[Contributing]]
</div>
</div>

== General Photography ==

<div class="container">

<div class="RP1columns">
* [[How to convert raw formats to DNG]]
* [[How to create DCP color profiles]]
* [[How to create LCP profiles]]
* [[How to get LCP and DCP profiles]]
* [[How to extract and examine ICC profiles]]
* [[How to get Nikon ICM profiles]]
* [[Watermarking]]
* [[Image file formats and compression]]
</div>

</div>

Main Page

2021-06-17T06:40:00Z

Thanatomanic: Reorder two tabs

<div class="main-page-title">RawPedia. The encyclopedia of RawTherapee, raw shooting and everything raw</div>

[[File:08_rt57_mushroom_blades_rawpedia.png|600px|right|link=]]

<div class="greetings">
Welcome to '''RawTherapee's''' documentation!

If you're a new user, don't miss the [[Getting Started]] page to quickly learn your way around this awesome raw image processing program.

If you're an experienced user, here you have an index of all the topics covered.
</div>

<div class=langsbox-wrapper>
<div class="row small-uncollapse large-collapse langsbox">
<span class="langsavail">In other languages</span>
<ul class="small-block-grid-2 medium-block-grid-4 large-block-grid-7 columns flagsbox">
<li>[[File:braz.png|90x60px|frameless|link=Main_Page/pt|Brasileiro]]<br>[[Main_Page/pt|Brasileiro]]</li>
<li>[[File:ct.png|90x60px|frameless|link=Main_Page/ca|Català]]<br>[[Main_Page/ca|Català]]</li>
<li>[[File:deu.png|90x60px|frameless|link=Main_Page/de|Deutsch]]<br>[[Main_Page/de|Deutsch]]</li>
<li>[[File:esp.png|90x60px|frameless|link=Main_Page/es|Español]]<br>[[Main_Page/es|Español]]</li>
<li>[[File:frc.png|90x60px|frameless|link=Main_Page/fr|Française]]<br>[[Main_Page/fr|Français]]</li>
<li>[[File:ita.png|90x60px|frameless|link=Main_Page/it|Italiano]]<br>[[Main_Page/it|Italiano]]</li>
<li>[[File:jap.png|90x60px|frameless|link=Main_Page/jp|日本]]<br>[[Main_Page/jp|日本語]]</li>
</ul>
</div>
</div>

<br style="clear: both;">

== RawTherapee ==

<div class="container">
=== General Information ===

<div class="RP3columns">
* [[Getting Started]]
* [[Features]]
* [[Download]]
* [[The Floating Point Engine]]
* [[Bit Depth]]
* [[RGB and Lab]]
* [[About Noise Reduction]]
* [[File Browser|The File Browser]]
* [[Queue|The Queue]]
* [[Editor|The Editor]]
* [[Batch Adjustments - Sync]]
* [[Saving Images]]
* [[Edit Current Image in External Editor]]
* [[Adding Support for New Raw Formats]]
* [[File Paths]]
* [[Preferences]]
* [[GIMP Plugin]]
* [[ICC Profile Creator]]
* [[Making a Portable Installation]]
* [[Command-Line Options]]
* [[Keyboard Shortcuts]]
* [[Toolchain Pipeline|Toolchain pipeline - Colorimetry]]
</div>
<hr/>

=== Processing Profiles ===

<div class="RP3columns">

<div class="keeptogether">
* [[Sidecar Files - Processing Profiles]]
* [[Creating processing profiles for general use]]
* [[Dynamic processing profiles]]
</div>

<div class="keeptogether">
==== Processing Profile Scripts ====
* [[RTProfileSelector]]
* [[RTbatch]]
</div>

<div class="keeptogether">
==== Bundled Processing Profiles ====
* [[Neutral]]
* [[Auto-Matched Curve]]
* [[Standard Film Curve]]
* [[Pop]]
* [[Unclipped]]
</div>
</div>
<hr/>

=== Tool Description ===

<div class="RP1columns">
* [[General Comments About Some Toolbox Widgets]]
* [[Favorites Tab]]
</div>

<div class="RP3columns">

<div class="keeptogether">
==== Exposure Tab ====

* [[Exposure]]
* [[Shadows/Highlights]]
* [[Tone Mapping]]
* [[Dynamic Range Compression]]
* [[Vignetting Filter]]
* [[Graduated Filter]]
* [[Lab Adjustments|L*a*b* Adjustments]]
</div>

<div class="keeptogether">
==== Detail Tab ====

* [[Spot Removal]]
* [[Sharpening]]
* [[Local Contrast]]
* [[Edges and Microcontrast]]
* [[Impulse Noise Reduction]]
* [[Noise Reduction]]
* [[Defringe]]
* [[Contrast by Detail Levels]]
* [[Haze Removal]]
</div>

<div class="keeptogether">

==== Color Tab ====

* [[White Balance]]
* [[Vibrance]]
* [[Channel Mixer]]
* [[Black-and-White]]
* [[Black-and-White addon]]
* [[HSV Equalizer]]
* [[Film Simulation]]
* [[Film Negative]]
* [[Soft Light]]
* [[RGB Curves]]
* [[Color Toning]]
* [[Color Management]]
* [[Color Management addon | Color Management Supplement]]
</div>

<div class="keeptogether">

==== Advanced Tab ====

* [[Retinex]]
* [[CIECAM02|CIE Color Appearance Model 2002/16 - Cat02/Cat16 - Log encoding]]
* [[Wavelet Levels]]
</div>

<div class="keeptogether">

==== Local Adjustements Tab====
* [[Local Adjustments]]
</div>
<div class="keeptogether">

==== Transform Tab ====

* [[Crop]]
* [[Resize]]
* [[Lens/Geometry]]
</div>

<div class="keeptogether">
==== Raw Tab ====

* [[Sensor with Bayer/X-Trans Matrix]]
* [[Demosaicing]]
* [[Raw Black Points]]
* [[Preprocessing]]
* [[Chromatic Aberration Correction]]
* [[Raw White Points]]
* [[Preprocessing White Balance]]
* [[Dark-Frame]]
* [[Flat-Field]]
* [[Capture Sharpening]]
</div>

<div class="keeptogether">

==== Metadata Tab ====

* [[Metadata Copy Mode]]
* [[Exif Tab]]
* [[IPTC Tab]]
</div>
</div>
<hr/>

=== Interact ===

<div class="RP1columns">
* [[Forum]]
* [[IRC]]
</div>

=== Compiling ===

<div class="RP1columns">
* In [[Linux]]
* In [[Windows]]
* In [[macOS]]
</div>

=== Troubleshooting ===

<div class="RP1columns">
* [[How to write useful bug reports]]
* [[How to fix crashes on startup]]
* [[Wayland]]
</div>

=== Localization ===

<div class="RP1columns">
* [[Translating RawTherapee]]
* [[Translating RawPedia]]
</div>
</div>

== RawPedia ==

<div class="container">
<div class="RP1columns">
* [[Contributing]]
</div>
</div>

== General Photography ==

<div class="container">

<div class="RP1columns">
* [[How to convert raw formats to DNG]]
* [[How to create DCP color profiles]]
* [[How to create LCP profiles]]
* [[How to get LCP and DCP profiles]]
* [[How to extract and examine ICC profiles]]
* [[How to get Nikon ICM profiles]]
* [[Watermarking]]
* [[Image file formats and compression]]
</div>

</div>

Main Page

2021-06-17T06:38:17Z

Thanatomanic: Added Film Negative

<div class="main-page-title">RawPedia. The encyclopedia of RawTherapee, raw shooting and everything raw</div>

[[File:08_rt57_mushroom_blades_rawpedia.png|600px|right|link=]]

<div class="greetings">
Welcome to '''RawTherapee's''' documentation!

If you're a new user, don't miss the [[Getting Started]] page to quickly learn your way around this awesome raw image processing program.

If you're an experienced user, here you have an index of all the topics covered.
</div>

<div class=langsbox-wrapper>
<div class="row small-uncollapse large-collapse langsbox">
<span class="langsavail">In other languages</span>
<ul class="small-block-grid-2 medium-block-grid-4 large-block-grid-7 columns flagsbox">
<li>[[File:braz.png|90x60px|frameless|link=Main_Page/pt|Brasileiro]]<br>[[Main_Page/pt|Brasileiro]]</li>
<li>[[File:ct.png|90x60px|frameless|link=Main_Page/ca|Català]]<br>[[Main_Page/ca|Català]]</li>
<li>[[File:deu.png|90x60px|frameless|link=Main_Page/de|Deutsch]]<br>[[Main_Page/de|Deutsch]]</li>
<li>[[File:esp.png|90x60px|frameless|link=Main_Page/es|Español]]<br>[[Main_Page/es|Español]]</li>
<li>[[File:frc.png|90x60px|frameless|link=Main_Page/fr|Française]]<br>[[Main_Page/fr|Français]]</li>
<li>[[File:ita.png|90x60px|frameless|link=Main_Page/it|Italiano]]<br>[[Main_Page/it|Italiano]]</li>
<li>[[File:jap.png|90x60px|frameless|link=Main_Page/jp|日本]]<br>[[Main_Page/jp|日本語]]</li>
</ul>
</div>
</div>

<br style="clear: both;">

== RawTherapee ==

<div class="container">
=== General Information ===

<div class="RP3columns">
* [[Getting Started]]
* [[Features]]
* [[Download]]
* [[The Floating Point Engine]]
* [[Bit Depth]]
* [[RGB and Lab]]
* [[About Noise Reduction]]
* [[File Browser|The File Browser]]
* [[Queue|The Queue]]
* [[Editor|The Editor]]
* [[Batch Adjustments - Sync]]
* [[Saving Images]]
* [[Edit Current Image in External Editor]]
* [[Adding Support for New Raw Formats]]
* [[File Paths]]
* [[Preferences]]
* [[GIMP Plugin]]
* [[ICC Profile Creator]]
* [[Making a Portable Installation]]
* [[Command-Line Options]]
* [[Keyboard Shortcuts]]
* [[Toolchain Pipeline|Toolchain pipeline - Colorimetry]]
</div>
<hr/>

=== Processing Profiles ===

<div class="RP3columns">

<div class="keeptogether">
* [[Sidecar Files - Processing Profiles]]
* [[Creating processing profiles for general use]]
* [[Dynamic processing profiles]]
</div>

<div class="keeptogether">
==== Processing Profile Scripts ====
* [[RTProfileSelector]]
* [[RTbatch]]
</div>

<div class="keeptogether">
==== Bundled Processing Profiles ====
* [[Neutral]]
* [[Auto-Matched Curve]]
* [[Standard Film Curve]]
* [[Pop]]
* [[Unclipped]]
</div>
</div>
<hr/>

=== Tool Description ===

<div class="RP1columns">
* [[General Comments About Some Toolbox Widgets]]
* [[Favorites Tab]]
</div>

<div class="RP3columns">

<div class="keeptogether">
==== Exposure Tab ====

* [[Exposure]]
* [[Shadows/Highlights]]
* [[Tone Mapping]]
* [[Dynamic Range Compression]]
* [[Vignetting Filter]]
* [[Graduated Filter]]
* [[Lab Adjustments|L*a*b* Adjustments]]
</div>

<div class="keeptogether">
==== Detail Tab ====

* [[Spot Removal]]
* [[Sharpening]]
* [[Local Contrast]]
* [[Edges and Microcontrast]]
* [[Impulse Noise Reduction]]
* [[Noise Reduction]]
* [[Defringe]]
* [[Contrast by Detail Levels]]
* [[Haze Removal]]
</div>

<div class="keeptogether">

==== Color Tab ====

* [[White Balance]]
* [[Vibrance]]
* [[Channel Mixer]]
* [[Black-and-White]]
* [[Black-and-White addon]]
* [[HSV Equalizer]]
* [[Film Simulation]]
* [[Film Negative]]
* [[Soft Light]]
* [[RGB Curves]]
* [[Color Toning]]
* [[Color Management]]
* [[Color Management addon | Color Management Supplement]]
</div>

<div class="keeptogether">

==== Local Adjustements Tab====
* [[Local Adjustments]]
</div>
<div class="keeptogether">

==== Advanced Tab ====

* [[Retinex]]
* [[CIECAM02|CIE Color Appearance Model 2002/16 - Cat02/Cat16 - Log encoding]]
* [[Wavelet Levels]]
</div>

<div class="keeptogether">

==== Transform Tab ====

* [[Crop]]
* [[Resize]]
* [[Lens/Geometry]]
</div>

<div class="keeptogether">
==== Raw Tab ====

* [[Sensor with Bayer/X-Trans Matrix]]
* [[Demosaicing]]
* [[Raw Black Points]]
* [[Preprocessing]]
* [[Chromatic Aberration Correction]]
* [[Raw White Points]]
* [[Preprocessing White Balance]]
* [[Dark-Frame]]
* [[Flat-Field]]
* [[Capture Sharpening]]
</div>

<div class="keeptogether">

==== Metadata Tab ====

* [[Metadata Copy Mode]]
* [[Exif Tab]]
* [[IPTC Tab]]
</div>
</div>
<hr/>

=== Interact ===

<div class="RP1columns">
* [[Forum]]
* [[IRC]]
</div>

=== Compiling ===

<div class="RP1columns">
* In [[Linux]]
* In [[Windows]]
* In [[macOS]]
</div>

=== Troubleshooting ===

<div class="RP1columns">
* [[How to write useful bug reports]]
* [[How to fix crashes on startup]]
* [[Wayland]]
</div>

=== Localization ===

<div class="RP1columns">
* [[Translating RawTherapee]]
* [[Translating RawPedia]]
</div>
</div>

== RawPedia ==

<div class="container">
<div class="RP1columns">
* [[Contributing]]
</div>
</div>

== General Photography ==

<div class="container">

<div class="RP1columns">
* [[How to convert raw formats to DNG]]
* [[How to create DCP color profiles]]
* [[How to create LCP profiles]]
* [[How to get LCP and DCP profiles]]
* [[How to extract and examine ICC profiles]]
* [[How to get Nikon ICM profiles]]
* [[Watermarking]]
* [[Image file formats and compression]]
</div>

</div>

Main Page

2021-06-17T06:37:41Z

Thanatomanic: Reorder tools, remove Film Negative, add Preprocessing White Balance

<div class="main-page-title">RawPedia. The encyclopedia of RawTherapee, raw shooting and everything raw</div>

[[File:08_rt57_mushroom_blades_rawpedia.png|600px|right|link=]]

<div class="greetings">
Welcome to '''RawTherapee's''' documentation!

If you're a new user, don't miss the [[Getting Started]] page to quickly learn your way around this awesome raw image processing program.

If you're an experienced user, here you have an index of all the topics covered.
</div>

<div class=langsbox-wrapper>
<div class="row small-uncollapse large-collapse langsbox">
<span class="langsavail">In other languages</span>
<ul class="small-block-grid-2 medium-block-grid-4 large-block-grid-7 columns flagsbox">
<li>[[File:braz.png|90x60px|frameless|link=Main_Page/pt|Brasileiro]]<br>[[Main_Page/pt|Brasileiro]]</li>
<li>[[File:ct.png|90x60px|frameless|link=Main_Page/ca|Català]]<br>[[Main_Page/ca|Català]]</li>
<li>[[File:deu.png|90x60px|frameless|link=Main_Page/de|Deutsch]]<br>[[Main_Page/de|Deutsch]]</li>
<li>[[File:esp.png|90x60px|frameless|link=Main_Page/es|Español]]<br>[[Main_Page/es|Español]]</li>
<li>[[File:frc.png|90x60px|frameless|link=Main_Page/fr|Française]]<br>[[Main_Page/fr|Français]]</li>
<li>[[File:ita.png|90x60px|frameless|link=Main_Page/it|Italiano]]<br>[[Main_Page/it|Italiano]]</li>
<li>[[File:jap.png|90x60px|frameless|link=Main_Page/jp|日本]]<br>[[Main_Page/jp|日本語]]</li>
</ul>
</div>
</div>

<br style="clear: both;">

== RawTherapee ==

<div class="container">
=== General Information ===

<div class="RP3columns">
* [[Getting Started]]
* [[Features]]
* [[Download]]
* [[The Floating Point Engine]]
* [[Bit Depth]]
* [[RGB and Lab]]
* [[About Noise Reduction]]
* [[File Browser|The File Browser]]
* [[Queue|The Queue]]
* [[Editor|The Editor]]
* [[Batch Adjustments - Sync]]
* [[Saving Images]]
* [[Edit Current Image in External Editor]]
* [[Adding Support for New Raw Formats]]
* [[File Paths]]
* [[Preferences]]
* [[GIMP Plugin]]
* [[ICC Profile Creator]]
* [[Making a Portable Installation]]
* [[Command-Line Options]]
* [[Keyboard Shortcuts]]
* [[Toolchain Pipeline|Toolchain pipeline - Colorimetry]]
</div>
<hr/>

=== Processing Profiles ===

<div class="RP3columns">

<div class="keeptogether">
* [[Sidecar Files - Processing Profiles]]
* [[Creating processing profiles for general use]]
* [[Dynamic processing profiles]]
</div>

<div class="keeptogether">
==== Processing Profile Scripts ====
* [[RTProfileSelector]]
* [[RTbatch]]
</div>

<div class="keeptogether">
==== Bundled Processing Profiles ====
* [[Neutral]]
* [[Auto-Matched Curve]]
* [[Standard Film Curve]]
* [[Pop]]
* [[Unclipped]]
</div>
</div>
<hr/>

=== Tool Description ===

<div class="RP1columns">
* [[General Comments About Some Toolbox Widgets]]
* [[Favorites Tab]]
</div>

<div class="RP3columns">

<div class="keeptogether">
==== Exposure Tab ====

* [[Exposure]]
* [[Shadows/Highlights]]
* [[Tone Mapping]]
* [[Dynamic Range Compression]]
* [[Vignetting Filter]]
* [[Graduated Filter]]
* [[Lab Adjustments|L*a*b* Adjustments]]
</div>

<div class="keeptogether">
==== Detail Tab ====

* [[Spot Removal]]
* [[Sharpening]]
* [[Local Contrast]]
* [[Edges and Microcontrast]]
* [[Impulse Noise Reduction]]
* [[Noise Reduction]]
* [[Defringe]]
* [[Contrast by Detail Levels]]
* [[Haze Removal]]
</div>

<div class="keeptogether">

==== Color Tab ====

* [[White Balance]]
* [[Vibrance]]
* [[Channel Mixer]]
* [[Black-and-White]]
* [[Black-and-White addon]]
* [[HSV Equalizer]]
* [[Film Simulation]]
* [[Soft Light]]
* [[RGB Curves]]
* [[Color Toning]]
* [[Color Management]]
* [[Color Management addon | Color Management Supplement]]
</div>

<div class="keeptogether">

==== Local Adjustements Tab====
* [[Local Adjustments]]
</div>
<div class="keeptogether">

==== Advanced Tab ====

* [[Retinex]]
* [[CIECAM02|CIE Color Appearance Model 2002/16 - Cat02/Cat16 - Log encoding]]
* [[Wavelet Levels]]
</div>

<div class="keeptogether">

==== Transform Tab ====

* [[Crop]]
* [[Resize]]
* [[Lens/Geometry]]
</div>

<div class="keeptogether">
==== Raw Tab ====

* [[Sensor with Bayer/X-Trans Matrix]]
* [[Demosaicing]]
* [[Raw Black Points]]
* [[Preprocessing]]
* [[Chromatic Aberration Correction]]
* [[Raw White Points]]
* [[Preprocessing White Balance]]
* [[Dark-Frame]]
* [[Flat-Field]]
* [[Capture Sharpening]]
</div>

<div class="keeptogether">

==== Metadata Tab ====

* [[Metadata Copy Mode]]
* [[Exif Tab]]
* [[IPTC Tab]]
</div>
</div>
<hr/>

=== Interact ===

<div class="RP1columns">
* [[Forum]]
* [[IRC]]
</div>

=== Compiling ===

<div class="RP1columns">
* In [[Linux]]
* In [[Windows]]
* In [[macOS]]
</div>

=== Troubleshooting ===

<div class="RP1columns">
* [[How to write useful bug reports]]
* [[How to fix crashes on startup]]
* [[Wayland]]
</div>

=== Localization ===

<div class="RP1columns">
* [[Translating RawTherapee]]
* [[Translating RawPedia]]
</div>
</div>

== RawPedia ==

<div class="container">
<div class="RP1columns">
* [[Contributing]]
</div>
</div>

== General Photography ==

<div class="container">

<div class="RP1columns">
* [[How to convert raw formats to DNG]]
* [[How to create DCP color profiles]]
* [[How to create LCP profiles]]
* [[How to get LCP and DCP profiles]]
* [[How to extract and examine ICC profiles]]
* [[How to get Nikon ICM profiles]]
* [[Watermarking]]
* [[Image file formats and compression]]
</div>

</div>

Main Page

2021-06-17T06:35:13Z

Thanatomanic: /* Detail Tab */

<div class="main-page-title">RawPedia. The encyclopedia of RawTherapee, raw shooting and everything raw</div>

[[File:08_rt57_mushroom_blades_rawpedia.png|600px|right|link=]]

<div class="greetings">
Welcome to '''RawTherapee's''' documentation!

If you're a new user, don't miss the [[Getting Started]] page to quickly learn your way around this awesome raw image processing program.

If you're an experienced user, here you have an index of all the topics covered.
</div>

<div class=langsbox-wrapper>
<div class="row small-uncollapse large-collapse langsbox">
<span class="langsavail">In other languages</span>
<ul class="small-block-grid-2 medium-block-grid-4 large-block-grid-7 columns flagsbox">
<li>[[File:braz.png|90x60px|frameless|link=Main_Page/pt|Brasileiro]]<br>[[Main_Page/pt|Brasileiro]]</li>
<li>[[File:ct.png|90x60px|frameless|link=Main_Page/ca|Català]]<br>[[Main_Page/ca|Català]]</li>
<li>[[File:deu.png|90x60px|frameless|link=Main_Page/de|Deutsch]]<br>[[Main_Page/de|Deutsch]]</li>
<li>[[File:esp.png|90x60px|frameless|link=Main_Page/es|Español]]<br>[[Main_Page/es|Español]]</li>
<li>[[File:frc.png|90x60px|frameless|link=Main_Page/fr|Française]]<br>[[Main_Page/fr|Français]]</li>
<li>[[File:ita.png|90x60px|frameless|link=Main_Page/it|Italiano]]<br>[[Main_Page/it|Italiano]]</li>
<li>[[File:jap.png|90x60px|frameless|link=Main_Page/jp|日本]]<br>[[Main_Page/jp|日本語]]</li>
</ul>
</div>
</div>

<br style="clear: both;">

== RawTherapee ==

<div class="container">
=== General Information ===

<div class="RP3columns">
* [[Getting Started]]
* [[Features]]
* [[Download]]
* [[The Floating Point Engine]]
* [[Bit Depth]]
* [[RGB and Lab]]
* [[About Noise Reduction]]
* [[File Browser|The File Browser]]
* [[Queue|The Queue]]
* [[Editor|The Editor]]
* [[Batch Adjustments - Sync]]
* [[Saving Images]]
* [[Edit Current Image in External Editor]]
* [[Adding Support for New Raw Formats]]
* [[File Paths]]
* [[Preferences]]
* [[GIMP Plugin]]
* [[ICC Profile Creator]]
* [[Making a Portable Installation]]
* [[Command-Line Options]]
* [[Keyboard Shortcuts]]
* [[Toolchain Pipeline|Toolchain pipeline - Colorimetry]]
</div>
<hr/>

=== Processing Profiles ===

<div class="RP3columns">

<div class="keeptogether">
* [[Sidecar Files - Processing Profiles]]
* [[Creating processing profiles for general use]]
* [[Dynamic processing profiles]]
</div>

<div class="keeptogether">
==== Processing Profile Scripts ====
* [[RTProfileSelector]]
* [[RTbatch]]
</div>

<div class="keeptogether">
==== Bundled Processing Profiles ====
* [[Neutral]]
* [[Auto-Matched Curve]]
* [[Standard Film Curve]]
* [[Pop]]
* [[Unclipped]]
</div>
</div>
<hr/>

=== Tool Description ===

<div class="RP1columns">
* [[General Comments About Some Toolbox Widgets]]
* [[Favorites Tab]]
</div>

<div class="RP3columns">

<div class="keeptogether">
==== Exposure Tab ====

* [[Exposure]]
* [[Shadows/Highlights]]
* [[Tone Mapping]]
* [[Dynamic Range Compression]]
* [[Vignetting Filter]]
* [[Graduated Filter]]
* [[Lab Adjustments|L*a*b* Adjustments]]
</div>

<div class="keeptogether">
==== Detail Tab ====

* [[Spot Removal]]
* [[Sharpening]]
* [[Local Contrast]]
* [[Edges and Microcontrast]]
* [[Impulse Noise Reduction]]
* [[Noise Reduction]]
* [[Defringe]]
* [[Contrast by Detail Levels]]
* [[Haze Removal]]
</div>

<div class="keeptogether">

==== Color Tab ====

* [[White Balance]]
* [[Vibrance]]
* [[Channel Mixer]]
* [[Black-and-White]]
* [[Black-and-White addon]]
* [[HSV Equalizer]]
* [[Film Simulation]]
* [[Soft Light]]
* [[RGB Curves]]
* [[Color Toning]]
* [[Color Management]]
* [[Color Management addon | Color Management Supplement]]
</div>

<div class="keeptogether">

==== Local Adjustements Tab====
* [[Local Adjustments]]
</div>
<div class="keeptogether">

==== Advanced Tab ====

* [[Retinex]]
* [[CIECAM02|CIE Color Appearance Model 2002/16 - Cat02/Cat16 - Log encoding]]
* [[Wavelet Levels]]
</div>

<div class="keeptogether">

==== Transform Tab ====

* [[Crop]]
* [[Resize]]
* [[Lens/Geometry]]
</div>

<div class="keeptogether">
==== Raw Tab ====

* [[Sensor with Bayer/X-Trans Matrix]]
* [[Demosaicing]]
* [[Raw Black Points]]
* [[Preprocessing]]
* [[Chromatic Aberration]]
* [[Raw White Points]]
* [[Dark-Frame]]
* [[Flat-Field]]
* [[Film Negative]]
* [[Capture Sharpening]]
</div>

<div class="keeptogether">
==== Metadata Tab ====

* [[Metadata Copy Mode]]
* [[Exif Tab]]
* [[IPTC Tab]]
</div>
</div>
<hr/>

=== Interact ===

<div class="RP1columns">
* [[Forum]]
* [[IRC]]
</div>

=== Compiling ===

<div class="RP1columns">
* In [[Linux]]
* In [[Windows]]
* In [[macOS]]
</div>

=== Troubleshooting ===

<div class="RP1columns">
* [[How to write useful bug reports]]
* [[How to fix crashes on startup]]
* [[Wayland]]
</div>

=== Localization ===

<div class="RP1columns">
* [[Translating RawTherapee]]
* [[Translating RawPedia]]
</div>
</div>

== RawPedia ==

<div class="container">
<div class="RP1columns">
* [[Contributing]]
</div>
</div>

== General Photography ==

<div class="container">

<div class="RP1columns">
* [[How to convert raw formats to DNG]]
* [[How to create DCP color profiles]]
* [[How to create LCP profiles]]
* [[How to get LCP and DCP profiles]]
* [[How to extract and examine ICC profiles]]
* [[How to get Nikon ICM profiles]]
* [[Watermarking]]
* [[Image file formats and compression]]
</div>

</div>

Windows

2021-06-17T06:26:06Z

Thanatomanic: Remove notice about libiptcdata here

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

Since December 2020 the <code>libiptcdata</code> library is provided by MSYS2 and no longer requires manual compilation. <i>Only if you experience problems using this library</i>, follow the instructions below to manually build it. Otherwise, continue to the next section.
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Windows

2021-06-17T06:25:44Z

Thanatomanic: /* Download and build libiptcdata */

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

Note: the <code>mingw-w64-x86_64-libiptcdata</code> package has been added to MSYS2 in December 2020. If you experience difficulty using this package, please see the instructions below how to compile the library yourself.

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

Since December 2020 the <code>libiptcdata</code> library is provided by MSYS2 and no longer requires manual compilation. <i>Only if you experience problems using this library</i>, follow the instructions below to manually build it. Otherwise, continue to the next section.
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Windows

2021-06-17T06:25:13Z

Thanatomanic: Clarify build instructions

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

Note: the <code>mingw-w64-x86_64-libiptcdata</code> package has been added to MSYS2 in December 2020. If you experience difficulty using this package, please see the instructions below how to compile the library yourself.

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

Since December 2020 the <code>libiptcdata</code> library is provided by MSYS2 and no longer requires manual compilation. <i>Only if you experience problems using this library</i>, follow the instructions below to manually build it:
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Windows

2021-06-17T06:21:56Z

Thanatomanic: Note about libiptcdata

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

Note: the <code>mingw-w64-x86_64-libiptcdata</code> package has been added to MSYS2 in December 2020. If you experience difficulty using this package, please see the instructions below how to compile the library yourself.

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

The required <code>libiptcdata</code> library is not provided by MSYS2 and should be built manually. Follow the following steps:
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Windows

2021-06-17T06:20:42Z

Thanatomanic: libiptcdata is now provided by msys2

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun mingw-w64-x86_64-libiptcdata
</pre>

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

The required <code>libiptcdata</code> library is not provided by MSYS2 and should be built manually. Follow the following steps:
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Resize

2021-06-05T06:30:22Z

Thanatomanic: Reordered sections to match the order in the tool

<div class="pagetitle">Resize</div>

[[File:Resize tool 5.4-dev.png|frame|right|Screenshot of the whole Resize tool in RawTherapee 5.4-789-ga7b7f20b8.]]

== Resize ==

Resizing is one of the last things to happen when saving an image - this tool runs after most other tools and transformations. As downscaling an image involves a certain loss of detail, this tool includes a "Post-Resize Sharpening" component which you can use to make the downscaled image crisp.

The effects of the Resize tool will not be shown in the preview. The saved image will of course be resized.

Size limits:
* The downscaling limit is 32x32px.
* The upscaling limit is 16-times the image's size as of RawTherapee version 5.5. In versions prior to and including 5.4, it was 4-times the image's size.

=== Applies To ===

You will typically want the width and height to apply to the cropped area, however you can also have it apply to the full image. The crop will be scaled accordingly.

[[File:Resize-interpolation.png|thumb|500px|right|Demonstration of the effects of the resizing methods "nearest neighbor" vs "Lanczos".]]

=== Method ===

Resizing can be performed using various algorithms, each with its own strengths and weaknesses. We narrowed the choice down to the two most significant:
* Nearest
: The "nearest neighbor" method of interpolation is meant to be used when you want to upscale an image in order to make some detail larger without introducing smooth blending between pixels. It preserves the pixels as they are. It is usually used when upscaling by squares of 2: 2x, 4x, 8x, 16x, etc.. The result will be very sharp, but also very blocky. This method is not meant to be used for everyday photography.
* Lanczos
: Lanczos is the default method. It is meant to be used for everyday photography and in all cases except for the one described above. It results in a smooth yet sharp and high quality image. Use it to resize by any amount.

=== Specify ===

You can specify what dimensions to scale to or by:
* Scale
: Uniformly scale the image by a factor. Ranges from 0.01 (100 times smaller) to 16 (16 times bigger).
* Width / Height
: Set the desired absolute width or height in pixels, regardless of the image orientation. The other dimension is updated according to the aspect ratio.
* Bounding Box
: Resize to fit the image within a box of certain width and height in pixels, regardless of the image orientation. The image aspect ratio is kept. E.g. for a bounding box of 1920×1080 px and a landscape image of 3000×2000 px the resulting image will be 1620×1080 px. For the same bounding box and a portrait image of 2000×3000 px the resulting image will be 720×1080 px.
* Long Edge / Short Edge (Since RawTherapee 5.9)
: Set the desired size of either the long or short edge of the image in pixels. The other dimension is updated according to the aspect ratio. E.g. setting the long edge to 1500 px for a landscape image of 3000×2000 px gives a resulting image of 1500×1000 px. Setting the short edge to 1500 px for the same image gives a resulting image of 2250×1500 px. Setting the long edge to 1500 px for a portrait image of 2000×3000 px gives a resulting image of 1000×1500 px.

=== Allow Upscaling ===

This setting controls whether the resize tool will also upscale your images, or only downscale. If it is disabled and the combination of image dimensions, crop dimensions and resize dimensions is such that the image would need to be upscaled to meet your target, this setting will prevent it from being upscaled - it will remain at its current size.

This setting was introduced in RawTherapee 5.5. If in RawTherapee 5.5 you use a sidecar file from an older version of RawTherapee, this setting will automatically be disabled.

== Post-Resize Sharpening ==

Resizing an image often leads to a loss of sharpness, so it is common practice to sharpen the image again after having resized it. With the Post-Resize Sharpening tool you can save crystal-clear images straight away with no further hassle. Because this tool works on the image after it is resized, you cannot use the preview to see what it will do, though this is not a problem because the procedure for finding the right values is straightforward.

The default values work great, but if you want to change them, here's how to preview what the image will look like:
# Tweak your image as you usually would and enable the Resize tool, e.g. downscale using the Lanczos method to a 900x900px bounding box.
# Save the image to a lossless format such as TIFF.
# Open that saved TIFF in RawTherapee, apply the Neutral processing profile if that wasn't done automatically, and enable the [[Sharpening]] tool in the Detail tab.
# Zoom to 100% (1:1) and tweak the Sharpening tool's parameters until you get a result that satisfies you. These are the values you should use in the Post-Resize Sharpening tool.
# Go back to the raw image, enable the Post-Resize Sharpening tool and set it up with the values from the previous step.

The Post-Resize Sharpening tool is only available when you use the "Lanczos" resizing method.

As the Post-Resize Sharpening tool works identically to the standard Sharpening tool (except that it takes place right at the end of processing), refer to the [[Sharpening]] article to learn more about how the sharpening tools work.

Resize

2021-06-05T06:26:27Z

Thanatomanic: Rewritten and included new long / short edge option

<div class="pagetitle">Resize</div>

[[File:Resize tool 5.4-dev.png|frame|right|Screenshot of the whole Resize tool in RawTherapee 5.4-789-ga7b7f20b8.]]
[[File:Resize-interpolation.png|thumb|500px|right|Demonstration of the effects of the resizing methods "nearest neighbor" vs "Lanczos".]]

== Resize ==

Resizing is one of the last things to happen when saving an image - this tool runs after most other tools and transformations. As downscaling an image involves a certain loss of detail, this tool includes a "Post-Resize Sharpening" component which you can use to make the downscaled image crisp.

The effects of the Resize tool will not be shown in the preview. The saved image will of course be resized.

Size limits:
* The downscaling limit is 32x32px.
* The upscaling limit is 16-times the image's size as of RawTherapee version 5.5. In versions prior to and including 5.4, it was 4-times the image's size.

=== Method ===

Resizing can be performed using various algorithms, each with its own strengths and weaknesses. We narrowed the choice down to the two most significant:
* Nearest
: The "nearest neighbor" method of interpolation is meant to be used when you want to upscale an image in order to make some detail larger without introducing smooth blending between pixels. It preserves the pixels as they are. It is usually used when upscaling by squares of 2: 2x, 4x, 8x, 16x, etc.. The result will be very sharp, but also very blocky. This method is not meant to be used for everyday photography.
* Lanczos
: Lanczos is the default method. It is meant to be used for everyday photography and in all cases except for the one described above. It results in a smooth yet sharp and high quality image. Use it to resize by any amount.

=== Specify, Width and Height ===

You can specify what dimensions to scale to or by:
* Scale
: Uniformly scale the image by a factor. Ranges from 0.01 (100 times smaller) to 16 (16 times bigger).
* Width / Height
: Set the desired absolute width or height in pixels, regardless of the image orientation. The other dimension is updated according to the aspect ratio.
* Bounding Box
: Resize to fit the image within a box of certain width and height in pixels, regardless of the image orientation. The image aspect ratio is kept. E.g. for a bounding box of 1920×1080 px and a landscape image of 3000×2000 px the resulting image will be 1620×1080 px. For the same bounding box and a portrait image of 2000×3000 px the resulting image will be 720×1080 px.
* Long Edge / Short Edge (Since RawTherapee 5.9)
: Set the desired size of either the long or short edge of the image in pixels. The other dimension is updated according to the aspect ratio. E.g. setting the long edge to 1500 px for a landscape image of 3000×2000 px gives a resulting image of 1500×1000 px. Setting the short edge to 1500 px for the same image gives a resulting image of 2250×1500 px. Setting the long edge to 1500 px for a portrait image of 2000×3000 px gives a resulting image of 1000×1500 px.

=== Applies To ===

You will typically want the width and height to apply to the cropped area, however you can also have it apply to the full image, though even then of course only the cropped area gets saved.

=== Allow Upscaling ===

This setting controls whether the resize tool will also upscale your images, or only downscale. If it is disabled and the combination of image dimensions, crop dimensions and resize dimensions is such that the image would need to be upscaled to meet your target, this setting will prevent it from being upscaled - it will remain at its current size.

This setting was introduced in RawTherapee 5.5. If in RawTherapee 5.5 you use a sidecar file from an older version of RawTherapee, this setting will automatically be disabled.

== Post-Resize Sharpening ==

Resizing an image often leads to a loss of sharpness, so it is common practice to sharpen the image again after having resized it. With the Post-Resize Sharpening tool you can save crystal-clear images straight away with no further hassle. Because this tool works on the image after it is resized, you cannot use the preview to see what it will do, though this is not a problem because the procedure for finding the right values is straightforward.

The default values work great, but if you want to change them, here's how to preview what the image will look like:
# Tweak your image as you usually would and enable the Resize tool, e.g. downscale using the Lanczos method to a 900x900px bounding box.
# Save the image to a lossless format such as TIFF.
# Open that saved TIFF in RawTherapee, apply the Neutral processing profile if that wasn't done automatically, and enable the [[Sharpening]] tool in the Detail tab.
# Zoom to 100% (1:1) and tweak the Sharpening tool's parameters until you get a result that satisfies you. These are the values you should use in the Post-Resize Sharpening tool.
# Go back to the raw image, enable the Post-Resize Sharpening tool and set it up with the values from the previous step.

The Post-Resize Sharpening tool is only available when you use the "Lanczos" resizing method.

As the Post-Resize Sharpening tool works identically to the standard Sharpening tool (except that it takes place right at the end of processing), refer to the [[Sharpening]] article to learn more about how the sharpening tools work.

Windows

2021-05-18T07:49:04Z

Thanatomanic: /* Install tools and libraries */ added ninja package

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-ninja mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun
</pre>

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

The required <code>libiptcdata</code> library is not provided by MSYS2 and should be built manually. Follow the following steps:
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Getting Started

2021-05-17T06:05:09Z

Thanatomanic: Removed unnecessary sentence

<div class="pagetitle">Getting Started</div>

== Welcome ==

RawTherapee is a cross-platform raw image processing program, released under the GNU General Public License Version 3. It was originally written by Gábor Horváth of Budapest, and development was taken over in 2010 by a team of people from around the world. Rather than being a raster graphics editor such as Photoshop or GIMP or a digital asset management program like digiKam, it is specifically aimed at raw photo post-production. And it does it very well - at a minimum, RawTherapee is one of the most powerful raw processing programs available.

== Get RawTherapee ==

{{Template:Download_stable}}

== Start RawTherapee==

[[File:Rt setm fb.png|thumb|RawTherapee in Single Editor Tab Mode - Vertical Tabs, showing: 1- Main sections: [[File Browser]] (currently opened), Queue, Editor and Preferences. 2- Panels used for navigating to files and folders. 3- Thumbnails of the currently opened folder. 4- Filters to limit the thumbnails shown to only those which match some metadata or state. 5- Thumbnail zooming and info. 6- Quick image operations. 7- Sub-tabs of the File Browser: Filter (currently opened), Inspect (to see a full-sized embedded JPEG preview), Batch Edit (to apply some setting to all selected images) and Fast Export (low quality and bypasses some tools but fast saving - don't use this for typical saving!). 8- Right-click context menu (you will typically use this to apply some processing profile to all selected files).]]

When you start RawTherapee you will land in the [[File Browser]] tab, and it might be empty. You need to point RawTherapee to where your raw photos are stored. Use the folder tree browser on the left of the ''File Browser'' tab to navigate to your raw photo repository and double-click on the folder to open it. Then double-click on a raw photo to start editing it.

== Edit your first image ==

First, a little background. A raw photo contains a dump of sensor data, which makes up the bulk of the raw file. This sensor data does not look like a pretty image, in fact it does not look like anything - it is "raw" data, ergo the name. It must be "cooked" to look like the image you saw through the viewfinder. Your camera cooks the raw data into a pretty image, which it stores as a JPEG file inside the raw file (yes, even when you're shooting in only "RAW" mode as opposed to "RAW+JPEG" mode). Due to this fundamental fact of the data being "raw", there is no one correct way for a raw photo to look - the way your camera makes it look is not "the right way", nor is it the only way. However, many photographers would like to use the "camera look" as a starting point for further adjustments, and RawTherapee makes this possible.

When displaying a raw photo in the [[File Browser]] which has never been edited in RawTherapee before, the photo's thumbnail is based on the JPEG image embedded inside that raw file -- the exact same image you see when viewing that photo on your camera or in most other software. Once you open that photo in the [[Editor]], RawTherapee creates a new thumbnail based on the actual raw data. Since creating an image from raw data requires "cooking" it, and since you have not manually edited that image yet, RawTherapee uses parameters from the [[Preferences#Default_Processing_Profile|default processing profile for raw photos]] to process it. From that moment on, the photo's thumbnail is no longer based on the embedded JPEG but on the actual raw data. When you make adjustments to the image in the Editor, the thumbnail is updated to reflect your changes.

Editing is done in the [[Editor]]. This is where you work with RawTherapee to create stunning works of art - or perhaps just apply first aid to your snapshots. When you open a raw photo in the Editor for the first time, the [[Preferences#Default_Processing_Profile|default processing profile for raw photos]] is applied, which as of RawTherapee 5.4 is set to "Auto-Matched Curve - ISO Low" (unless you changed it in Preferences), and it automatically adjusts your raw photo to look like the out-of-camera JPEG. It does so by analyzing the JPEG image which was created by your camera and is stored within the raw file, and adjusting the tone curve so as to match it. In most cases this match is very close to the "camera look". In rare cases it may fail. See the [[Auto-Matched Curve]] article for more information.

[[File:Rt setm editor.png|thumb|The Editor.]]

Take a moment to look around this Editor tab.
Notice that there are tabs within this tab - on the right of screen towards the top. These tabs and the controls under them are the Toolbox. You probably have the first tab open and, if you hover your mouse over it, you'll find that it's called the Exposure tab. Below the choice of tabs are the tools the chosen tab contains – Exposure, Shadows/Highlights, Tone Mapping etc. If you click on one of them it will expand so that you can see its contents. Click again and it will collapse. Right-click on one and that one will expand while all others will collapse - a time-saving shortcut. To the left of each tool's label is a power button ([[File:Power-on-small.png]] on / [[File:Power-off-small.png]] off) which lets you turn it on or off, or in some cases instead of a power button there is a triangular expander [[File:Expander-closed-small.png]]. Read the [[General_Comments_About_Some_Toolbox_Widgets#Tools|Tools section of the General Comments About Some Toolbox Widgets]] article for a detailed explanation.
Browse through the tabs and panels until you feel totally overwhelmed by all that's available.

Before you start working on an image, here is some important advice – '''Don't Panic!''' You are in no danger of destroying any of your prized images if you make a mistake. RawTherapee has some features which help you protect your images:
* RawTherapee does non-destructive editing of your raw files. This means that RawTherapee will never, ever change the raw file itself. All changes are stored in sidecar files. You can find out more about them in the [[Sidecar Files - Processing Profiles]] article.
* When using the Editor, you'll see the [[Editor#History|History]] panel on the left. This panel shows a history stack of every change you have made to your image. To go back to any step (including when the image was first loaded), just click on the relevant line in the History panel.
* Under the History panel you'll see a [[Editor#Snapshots|Snapshots]] panel. You can skip it for now, but you'll find it handy when you gain experience with RawTherapee. This panel stores the state of all the tools as a "snapshot". This allows you to easily, for example, tweak your photo to a nice and colorful look and take a snapshot, then tweak it again to a lovely black-and-white look and take a snapshot, and then compare the two just by clicking on either snapshot. (Note: RawTherapee does not save snapshots to the PP3 file yet, it will do so in the future. If you have three snapshots which you want to retain, you will need to click through them and save a PP3 file each time under a unique name).
* As you might expect, Control-z will undo the previous change.

=== Basics ===

# Open the raw photo. RawTherapee automatically makes it look like your camera's output. If you're happy with the result, you're done. Else read on.
# Click on the [[File:Color-circles.png]] Color tab and expanding the [[White Balance]] tool by right-clicking on it (or use the {{k|w}} [[Keyboard Shortcuts|keyboard shortcut]]). RawTherapee will start with the white balance used by your camera. Most white balance adjustments involve moving the Temperature and Tint sliders, or using the [[File:Color-picker.png]] Spot White-Balance Picker on a colorless (neutral gray) patch. Adjust to taste.
# Next, fix the exposure by going to the [[File:Exposure.png]] Exposure tab, expanding the [[Exposure]] tool and adjusting it to taste. For now, just use the Exposure Compensation and Saturation sliders.
# If your image is noisy, switch to the [[File:Detail.png]] Detail tab, zoom to 100% either using the [[File:Magnifier-1to1.png]] button or using the {{k|z}} keyboard shortcut, because the effects of the tools in this tab are only visible in the zoomed-to-100% preview (and of course in the saved image), and enable the [[Noise Reduction]] tool by clicking on the power button [[File:Power-on-small.png]] leaving the settings at their default values for now. RawTherapee has automatically removed color (chrominance) noise. Luminance noise is removed [[Noise_Reduction#Usage|manually]], though leave it for now as luminance noise generally lends a pleasing, grainy, film-like look. As a general rule, when using noise reduction don't use sharpening. Zoom back out to see the whole image either using the [[File:Magnifier-fit.png]] button or using the {{k|f}} keyboard shortcut key.
# Now you decided you want to fix the [[Lens/Geometry|geometry]] and composition of your photo.
#* First make the horizon level, or correct the things which should be vertical such as street lamps or building edges. To easily do this, press the "s" key on your keyboard (the same as clicking the [[File:Rotate-straighten.png]] button), and click-and-drag a line along the horizon or along the edge of a building over the preview. Your image will rotate accordingly and you will automatically be taken into the [[File:Transform.png]] Transform tab.
#* To crop the photo, press the {{k|c}} shortcut key on your keyboard (or use the [[File:Crop.png]] button) and click-and-drag a crop over the preview; you will notice that the [[Crop]] tool becomes automatically enabled. There is no need to "apply" a crop - it takes effect the moment you draw it. You can zoom to fit the crop area by using the {{k|f}} keyboard shortcut, or {{k|alt}}+{{k|f}} if you want to fit the whole image. You may want to set the Crop "Guide type" to "none" if it's a problem.
#* Finally, you want to downscale the photo, because who wants to upload a 10MB JPEG to your social network. Enable the [[Resize]] tool and the [[Resize#Post-Resize_Sharpening|Post-Resize Sharpening]] sub-tool, and leave them at the default settings. The resizing effect is only applied to the saved image, not to the preview, so you won't see any change in the preview as you enable these tools.
# You're all set, let's [[Saving|save]] it straight away. Click the [[File:save.png]] Save Current Image button (located below the lower left corner of the preview area), or use the {{k|Ctrl}}+{{k|s}} keyboard shortcut. Save it as a JPG file using default settings (quality at "92", subsampling at "balanced"). These are good all-round settings. Choose a folder where you want it saved to, and after a few seconds your file will be ready in the folder you selected. If you close RawTherapee, the settings you used will be stored in a [[Sidecar_Files_-_Processing_Profiles|PP3 sidecar file]] next to the raw file, so that you can re-open the raw photo in the future and retain the tool settings you used.

Now that you went through basic photo adjustment and are familiar with the steps, let's recap the steps but with more advanced details.

=== Advanced ===

Always read each tool's article here on RawPedia before using it, to get a firm understanding of what it does. The articles explain how the tools work in RawTherapee, while the general concepts unspecific to RawTherapee are left to the user to find on Wikipedia or elsewhere.

Be sure to see the [[Keyboard Shortcuts]].

The order of the tools inside RawTherapee's engine pipeline is hard-coded, so from that point of view it does not matter when you enable or disable a tool. However some tools can make a large impact on other tools, e.g. changing exposure may require you to re-adjust color toning, and some tools may require plenty of CPU power to calculate the preview making updates of the preview from then on slow, so it is for this reason we suggest you stick to this general order of operations:
# Start off by making sure that RawTherapee's environment is set up correctly, meaning:
#* Make sure that RawTherapee is using your monitor's color profile if you use a color-managed workflow. Check Preferences > Color Management. You may also need to load the appropriate calibration curves into your graphics card if you built your monitor color profile on top of them, though how you do that is outside the scope of RawTherapee.
#* Make sure that the Color Management tool is configured correctly. Usually the defaults are best. Read the [[Color Management]] and [[Color Management addon]] articles. If instead of using the color matrix or DCP or ICC profiles shipped with RawTherapee you decide to use an external one, for example a self-made DCP or one from Adobe, load it as the first thing you do, otherwise you may need to re-adjust some of the color tools. Always use an output profile - in most cases the default one, RT_sRGB. If you think you're being smart by selecting "No ICM: sRGB Output", you're mistaken.
# If you want to use a [[Flat Field|Flat-Field]] and/or [[Dark Frame|Dark-Frame]] image, do so now, to avoid re-adjustment.
# Now set the correct [[White Balance]]. You may fix the exposure first if the image is too dark (or too bright) to see white balance changes.
# Next, adjust the [[Exposure]], using the Exposure Compensation and Black sliders to get the image into the right ballpark. Once in the right ballpark, continue with using both tone curves. Be sure to read the [[Exposure#Tone_Curves|Tone Curve section]] in the Exposure article to learn why there are two of them and how best to use them - they are a very powerful tool!
# In the Basics section above we suggested that you use the [[Exposure#Saturation|Saturation]] slider (in the Exposure tool). Now that you've learned the basics and are exploring more advanced techniques, we suggest you not use the Saturation slider anymore, and instead use the more powerful [[Lab_Adjustments#CC_Curve|CC curve]] in the [[Lab Adjustments]] tool, as it gives you finer control.
# The order of the rest gets fuzzy. Some tools will unavoidably influence others. Carry on with the [[Lab Adjustments]] tool and then the rest of the tools in the Exposure tab.
# Then use the tools in the [[File:Color-circles.png]] Color tab.
# Then zoom to 100% and use the tools in the [[File:Detail.png]] Detail tab. Generally, don't sharpen if you're using noise reduction.
# Finally, zoom out again and use the tools in the [[File:Transform.png]] Transform tab. The reason you left these for last is that they may make the preview image appear a bit blurry, because in order for the preview to be responsive, RawTherapee uses that very preview image you see at the very resolution you see - small - to show what the tools do, and when you rotate or otherwise change the geometry of a small image, there is a clear softening. This is not a problem when saving as by that point RawTherapee does its processing on the full-sized image, which is slow but of high quality.
# You can edit metadata in the [[File:Metadata.png]] [[Metadata_Copy_Mode|Meta]] tab at any time before saving.
# Save, either directly [[file:save.png]] when you want to save a single photo, or via the [[file:gears.png]] [[The_Batch_Queue|Batch Queue]] when you want to process many photos. See the [[Saving Images]] article.

Download

2021-05-17T05:11:27Z

Thanatomanic: Rewritten development build section, including more links to nightly builds

<div class="pagetitle">Download</div>

== Stable Releases ==

{{Template:Download_stable}}

== Development Builds ==

If you wish to make use of the very latest features and updates, you can use a development build. These can be downloaded from several locations:

* The [https://github.com/Beep6581/RawTherapee/releases/tag/nightly official RawTherapee] GitHub repository. ''Note: currently, the Windows builds are not being generated.''
* The [https://keybase.pub/gaaned92/RTW64NightlyBuilds/ unofficial builds] by André Gauthier.
* The [https://keybase.pub/kd6kxr/ unofficial macOS builds] by Richard Barber.

While the development builds can be safely run alongside an installed version of RawTherapee, be aware that edits in a newer version do not generally carry over to older versions. In other words: there is no guaranteed [https://en.wikipedia.org/wiki/Forward_compatibility forward compatibility], but we aim for complete backward compatibility.

There are several benefits from using a development build. It contains all the latest bug fixes and usually has better support for the latest camera's. You can also test out newly introduced features before they are officially released. Feel free to comment on these and suggest changes on our [https://github.com/Beep6581/RawTherapee GitHub issue tracker] or [https://discuss.pixls.us support forum]. Be aware that backward compatibility between subsequent development builds is not guaranteed and the look and function of tools may change before a next release. If stability is key for you, we recommend that you use the [http://www.rawtherapee.com/downloads/ latest release].

The filenames for the development builds roughly follow this structure:

<code>RawTherapee_branch_tag_commit_date.extension</code>

* Code changes happen several times a day, and each code change is referenced by a unique hash number in the commit - it looks like this: <code>d9ad93c15</code>.
* Each commit happens on a "branch". The main branch is called <code>dev</code>. New features are developed on their own branches, and then merged into <code>dev</code> when ready.
* The "tag" is the human-friendly version of the latest release, e.g. <code>5.8</code>.

Windows

2021-05-16T17:00:40Z

Thanatomanic: Major rewrite: remove 32-bit instructions (deprecated), use Ninja for building, remove other unnecessary information, and various other changes

<div class="pagetitle">Windows</div>

Follow the instructions on this page to compile RawTherapee on Windows using the [https://www.msys2.org MSYS2] build environment. For more details on customizing and understanding the build process, see the [[Linux]] article.

Note: this guide applies to compiling the '''64-bit''' version of RawTherapee under '''Windows 7 and newer'''. Compiling the 32-bit version is no longer supported, nor is compilation on older operating systems. The latest version of RawTherapee to work under 32-bit Windows XP is 5.0-rc1, and can be downloaded [http://www.rawtherapee.com/downloads/5.0-r1/ here] (dated 2017-02-02).

Note that RawTherapee also requires the availability of GTK+ 3.22.24 or newer to have [https://gitlab.gnome.org/GNOME/gtk/issues/760#note_110809 native window support]. Without it RawTherapee may exhibit [https://github.com/Beep6581/RawTherapee/issues/4125 strange behavior], such as maximizing underneath the taskbar in Windows 10. When using an up to date build environment, you should not encounter this problem.

== MSYS2 Installation ==

=== Install MSYS2 base system ===

Install the build environment MSYS2 carefully by following the instructions from the [https://www.msys2.org MSYS2 website]. Make sure to update the system fully until no further updates are available, using the command:
<pre style="white-space: pre-wrap">
$ pacman -Syu
</pre>

MSYS2 provides [https://www.msys2.org/wiki/MSYS2-introduction/ three 'shells'] (command-line interfaces) for different purposes: '''MSYS''', '''MinGW 32-bit''' and '''MinGW 64-bit'''. They can be launched through shortcuts in your Start menu. Most commonly you will be running a 64-bit operating system and will want to create applications that are optimized for that. Therefore, start the '''MSYS2 MinGW 64-bit''' shell and continue below.

[[File:MSYS2 Shell.jpg]]

Note: in following text, <code><MSYS2></code> refers to the MSYS2 installation folder, typically <code>C:\msys64</code>

=== Install tools and libraries ===

MSYS2 uses the package manager <code>pacman</code> to install software and components. Please refer to the [https://wiki.archlinux.org/index.php/pacman pacman manual] for details.

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 and the required libraries:
<pre style="white-space: pre-wrap">
$ 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 mingw-w64-x86_64-gtkmm3 mingw-w64-x86_64-lcms2 mingw-w64-x86_64-fftw mingw-w64-x86_64-lensfun
</pre>

=== Updating Lensfun database ===

RawTherapee uses the [https://lensfun.github.io Lensfun] library for lens-specific corrections. Run the following command to update the database:
<pre style="white-space: pre-wrap">
$ lensfun-update-data
</pre>
The updater returns the path where the updated database is located. '''Copy this path for later use!'''

=== Download and build libiptcdata ===

The required <code>libiptcdata</code> library is not provided by MSYS2 and should be built manually. Follow the following steps:
<pre style="white-space: pre-wrap">
$ cd ~
$ 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
$ ./configure --prefix=/mingw64
</pre>

Some modifications to the resulting <code>Makefile</code> are needed. You can edit the file with any text editor (either through your OS or from within the shell). We use the <code>nano</code> editor from within the shell:
<pre style="white-space: pre-wrap">
$ nano Makefile

# search (command Ctrl+W)
DIST_SUBDIRS = m4 libiptcdata po iptc docs win python
# and replace with
DIST_SUBDIRS = m4 libiptcdata po win python

# search
SUBDIRS = m4 libiptcdata po iptc docs win $(MAYBE_PYTHONLIB)
# and replace with
SUBDIRS = m4 libiptcdata po win $(MAYBE_PYTHONLIB)

# save and quit
Ctrl+X, Y
</pre>

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

== Clone and build RawTherapee ==

=== Clone RawTherapee's git repository. ===
RawTherapee's source code can be cloned from [https://github.com/Beep6581/RawTherapee the official GitHub repository]:
<pre style="white-space: pre-wrap">
$ cd ~
$ git clone git://github.com/Beep6581/RawTherapee.git
$ cd RawTherapee
</pre>

=== Switching branches ===
After cloning you will automatically have checked out the <code>dev</code> branch. This is the main development branch of RawTherapee and probably what you want to use. To switch to a [https://github.com/Beep6581/RawTherapee/branches different branch], do the following:
<pre style="white-space: pre-wrap">
$ git checkout branchname # replace with another available branch name
</pre>

=== Create a separate directory for the build ===
It is essential to create a new directory to build the application. The directory can have any name, for example:
<pre style="white-space: pre-wrap">
$ mkdir build
$ cd build
</pre>

Note: if you switch branches, ''always build in an empty directory'' to prevent issues. From within a build directory, you can run <code>rm -rf *</code> to remove all files.

=== Configuration and compilation ===
To create an optimized build for your machine architecture, use the following commands:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=put/your/lensfun/directory/here -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" ..
$ cmake --build . --target install
</pre>
Make sure to replace the path to the Lensfun database with the actual path obtained a few steps before. See the [[Linux#CMake|Linux article]] for more details on the various options. Depending on your system, the build process may take anywhere between 5 and 25 minutes.

There may be warnings during the build process which you can safely ignore. Errors that are not traceable to a mistake when following this guide should be reported [https://github.com/Beep6581/RawTherapee/issues/new?assignees=&labels=&template=bug_report.md&title= here].

=== Starting RawTherapee ===
RawTherapee can now be run:
<pre style="white-space: pre-wrap">
$ ./release/rawtherapee.exe # replace release with debug or relwithdebinfo if you built another target
</pre>

=== Optional: preloaded CMake cache ===
As described in the [https://cmake.org/cmake/help/latest/manual/cmake.1.html CMake manual]
<pre style="white-space: pre-wrap">
-C <initial-cache>

Pre-load a script to populate the cache.

When cmake is first run in an empty build tree, it creates a CMakeCache.txt file and populates it with customizable settings for the project. This option may be used to specify a file from which to load cache entries before the first pass through the project’s cmake listfiles. The loaded entries take priority over the project’s default values. The given file should be a CMake script containing SET commands that use the CACHE option, not a cache-format file.
</pre>

To simplify the invocation of CMake and be able to easily define Windows specific options, a <code>win.cmake</code> template script is provided with the sources. Copy it out of RawTherapee's source to avoid overwriting by update for instance in <code>mywin.cmake</code>.
Edit it to define or modify options. To preload the cache, in the CMake command line:
<pre style="white-space: pre-wrap">
$ cmake -G "Ninja" -DLENSFUNDBDIR=share/lensfun -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="2" -DCACHE_NAME_SUFFIX="5-dev" -C <path/to/mywin.cmake> ..
</pre>

== Making a bundled build ==

This section only applies if you want to run RawTherapee outside the MinGW shell or distribute it.

Note: You can copy either with the Windows file manager or, recommended, with [https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/robocopy robocopy] inside the <code>mingw64</code> shell script using <code>-</code> instead of <code>/</code> for the options.

=== Definition of folders ===
*<code><prefix></code> is <code><MSYS2>\mingw64</code>,
*<code><MSYS2></code> is the MSYS2 installation folder,
*and <code>.</code> is the RawTherapee installation folder.

=== Copy RawTherapee executable and generated files ===
Copy the content of <code>c:\code\repo-rt\build\<debug|release|relwithdebinfo></code> into <code>.</code>.

=== Copy the dependencies ===
Copy the necessary DLLs and exe from <code><prefix>\bin</code> into <code>.</code>.
The current list of required DLLs and EXE is:
<pre style="white-space: pre-wrap">
gspawn-win64-helper.exe
gspawn-win64-helper-console.exe
gdbus.exe
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
libdatrie-1.dll
libepoxy-0.dll
libexpat-1.dll
libffi-6.dll
libfftw3f-3.dll
libfontconfig-1.dll
libfreetype-6.dll
libfribidi-0.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
libthai-0.dll
libtiff-5.dll
libtre-5.dll
libwinpthread-1.dll
libxml2-2.dll
libzstd.dll
zlib1.dll
</pre>

Copy the following list of Adwaita theme files and directories from <code><prefix>\share\icons\Adwaita\</code> to <code>.\share\icons\Adwaita\</code>:
<pre style="white-space: pre-wrap">
scalable\actions
scalable\devices
scalable\mimetypes
scalable\places
scalable\status
scalable\ui
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>

Copy following files :
<pre style="white-space: pre-wrap">
<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>

Create in .\share\gtk-3.0 a file <code>settings.ini</code> containing :
<pre style="white-space: pre-wrap">
[Settings] gtk-button-images=1
</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.

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 and will be copied into Rawtherapee installation folder.

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_<version>_WinVista_64_<buildtype>.zip</code>

If you are building and distributing nightly builds, follow this template:
<code>RawTherapee_<branch>_<version>_WinVista_64_<buildtype>.zip</code>

* "WinVista" means it can run on any version of Windows from Vista upwards, including 10.
* The "version" will either look like <code>5.8</code> if you checkout the <code>5.8</code> tag, or <code>5.8-g35abd92
</code> if you checkout the <code>dev</code> branch after 5.8 was tagged.
* If you are shipping more than one build type in an installer, don't include <buildtype> in the name.

Sidecar Files - Processing Profiles

2021-03-22T06:00:06Z

Thanatomanic: Extended description on profile toolbar, including image and clarification of operation order (first file selection, then parameter selection)

<div class="pagetitle">Sidecar Files / Processing Profiles</div>

== Introduction ==

Processing profiles (with a PP3 extension for version 3 or PP2 for the older version 2) are text files which contain all of the tool settings which RawTherapee applies to the associated photo. If you are familiar with other raw processors, you may know their equivalent as "presets". They are stored alongside their associated photos, which is why they are also called [https://en.wikipedia.org/wiki/Sidecar_file sidecar files].

When you open a folder with photos in RawTherapee's File Browser for the first time, none of the images will have PP3 sidecar files. The thumbnails shown for images which have no processing profile assigned (images which have never been opened or edited) are created from the JPEG image embedded in each raw file. A processing profile is assigned to the image the moment one of these actions are taken:
* You open the photo for [[The Image Editor Tab|editing]].
* You apply a processing profile manually, by using the right-click context menu in the [[The File Browser Tab|File Browser]] or [[The_Image_Editor_Tab#The_Filmstrip|Filmstrip]].
* You apply a [[Dynamic processing profiles|dynamic processing profile]].

When you open an image for editing, or when a processing profile is assigned, RawTherapee will convert the real raw data into a viewable image. In order to do this, there are many settings which need to be set to ''something'', and what these specific values are depends on:
* Your [[Preferences#Default_Processing_Profile|default processing profile]].
* Your [[Dynamic processing profiles|dynamic processing profile rules]], if any.
* Or on the processing profile you selected from the right-click context menu if you right-clicked on a thumbnail.

== Sources ==
Processing profiles come from three quite different sources, though they work in exactly the same way:
* "Bundled profiles".
*: RawTherapee comes with a bundle of profiles. Their purpose is to give you a good starting point, to demonstrate how the tools can be used together. They are the ones you see in the [[The Image Editor Tab#Processing Profile Selector|Processing Profile Selector]] drop-down list's "Bundled profiles" section, in the [[The_Image_Editor_Tab|Image Editor]].
* "My profiles".
*: When you make a processing profile which you want to re-use, for example one which works well with your camera and your style, you can save it so that it also appears in the Processing Profile Selector drop-down list, in the "My profiles" section. To have it appear there, save it to the "profiles" folder within the "config" folder - see the [[File Paths]] article to find it.
* Automatically generated profiles.
*: Whenever you edit an image, the tool settings you want applied to that image are stored in a processing profile that is particular to that image (ranking information, the history panel contents and snapshots are not stored in these files yet, see [https://code.google.com/p/rawtherapee/issues/detail?id=473 issue #473]).

== Saving ==
As simply viewing the image requires processing, RawTherapee stores the settings it used to show you the image in a sidecar processing profile. That processing profile also stores all the tool tweaks you made in the Editor tab.

The processing profile is written to disk:
* When you apply a processing profile manually or using a dynamic profile.
* When you close the current image (the Editor tab) if using [[The_Image_Editor_Tab#Editor_Tab_Modes|Multiple Editor Tabs Mode]] (METM).
* When you close the current image by opening a different image if using [[The_Image_Editor_Tab#Editor_Tab_Modes|Single Editor Tab Mode]] (SETM).
* When you close the current image by closing RawTherapee.
* When you manually save the processing profile using the [[The_Image_Editor_Tab#Processing_Profile_Selector|Processing Profile Selector]] panel in the Editor tab.
* When you use the "force saving current settings to the processing profile" [[Keyboard_Shortcuts|keyboard shortcut]] from the Editor tab.

If a photo has an associated processing profile, a green check mark will appear over its thumbnail.

If you have a photo opened in an Editor tab and you make changes to it from the File Browser, the changes are reflected immediately in the Editor tab.

== Storage ==
Where the processing profile is stored can be configured in [[Preferences#Processing_Profile_Handling|Preferences > Processing Profile Handling]].

By default, the processing profile for an image is stored alongside the input image (if you open <code>kitty.raw</code>, a new file <code>kitty.raw.pp3</code> will be created next to it), but they can also be stored in a [[File_Paths|central cache]]. You can choose whether RawTherapee should use the cache, write the processing profile alongside the image, or both, from "''Preferences > Image Processing''". We suggest you store these files alongside your input image files so that if you decide to move the images you can move the processing profiles easily along with them.

When saving an image you have the option of ticking the "Save processing parameters with image" checkbox. If it is ticked, and if you are working on <code>kitty.raw</code> and saving to a JPG file, then the processing profile used to develop that image will be stored in a file called <code>kitty.jpg.out.pp3</code>. The ".out" part if there so that conflicts do not occur if you are working on a non-raw file.

== Defaults ==
The default processing profile used when opening '''non-raw''' images is called "[[Neutral]]". This profile has all tool settings at their neutral values, so they have no effect. Since non-raw images usually have already been processed and are ready for viewing, having RawTherapee not introduce any tweaks by default is the desirable behavior.

The default profile for '''raw''' photos is called "[[Auto-Matched Curve]]" (from RawTherapee 5.4 onward). This profile makes your raw image look like the out-of-camera JPEG, which is usually a desirable starting point.

Furthermore, most tools in the Editor tab have a reset button.
* Clicking the reset button resets the tool to its hard-coded neutral value, usually zero.
* Ctrl+clicking the reset button resets the tool to whatever value it had when you opened the image, i.e. the way it was if you rewind the history stack to the top.

== Partial Processing Profiles and Fill Modes ==
Application and storage of processing profiles is controlled by the buttons in the top right corner of the editor.

<div class="image-sample">[[File:Processing-profiles-selector.png|left|frame]]Clicking the four right-hand buttons handles opening, saving, copying and pasting the profiles in full, while Ctrl+clicking handles them in partially. When using the latter, a window pops up to let you choose which parameters to include. This allows you to, for example, copy only the noise reduction parameters from one image to another, or only the white balance, or any other selection of parameters. Note that when loading or saving a profile, the parameter window appears after the file selection dialog.</div>

The processing profile fill mode lets you decide what happens when you use the drop-down list to apply a processing profile to an image when that profile does not contain information about all of the tool settings.
* "Fill" mode [[image:Profile-filled.png]] takes any missing values from RawTherapee's hard-coded defaults. For instance if you apply a partial profile containing only sharpening settings, all of the remaining tools will pop into their default positions overwriting any edit you have made up to that point.
* "Preserve" mode [[image:Profile-partial.png]] applies only those values that are available in the profile and leave missing values unchanged.

Most of the profiles that come bundled with RawTherapee are partial profiles. The article on [[File Paths]] explains where on your system you can find the available processing profiles shown in the drop-down list.

== Creating Your Own Processing Profiles ==
Using certain tools in certain ways may make your processing profile only usable with that specific image. For example if you set a white balance, cropping and rotation, you won't get good results if you apply that profile to an image taken under different lighting with the camera rotated any other way. See the article [[Creating processing profiles for general use]] for advice on how to make processing profiles which can be used on many images.

== Compatibility ==
Processing profiles evolve from one version of RawTherapee to the next. We strive to ensure backward compatibility (e.g. a profile created in 5.3 and opened in 5.4 should look the same), but this is not always possible.

Processing profiles can gain new parameters or lose ones which became obsolete. Tool behavior can also evolve, wherein default values change or in extreme cases the meaning of a value is interpreted differently; an example of this is the noise reduction tool, where a luminance noise reduction value of 10 in RawTherapee-3.0 would lead to a different result in RawTherapee-4.0.10 as the whole noise reduction engine has been greatly improved.

Consolidating processing profiles into a cache allows one to store isolated copies of the processing profiles per specific version of RawTherapee. In such a case, the cache can be used to re-process photos in order to get the same output as originally intended (but e.g. with a new size or output color space) using the same version of RawTherapee in which the image was originally edited. Whether this is desirable is debatable. Consider that you want to squeeze as much out of your raw files as possible. If two years later you want to go back to an old raw file, perhaps getting the same result as you did two years ago is not the best idea, because RawTherapee's capabilities would have greatly improved in that time, you may have acquired a better monitor, and your taste and skill would also have evolved. Nevertheless, by backing up the whole cache folder, when installing a new version of RawTherapee you retain the option of going back to an older version of RawTherapee in order to get the exact same result.

The [[File Paths]] article describes where you can find the "''cache''" and "''config''" folders on your system.

When releasing a major new version of RawTherapee, it may happen that we use a new suffix for the "''cache''" and "''config''" folders. This means that the new version of RawTherapee will not see your old configuration or processing profiles. Though this sounds undesirable, there are good reasons we may (rarely) choose to do that.
* Backward compatibility. There may be changes in behavior between old and new versions of a specific tool. For instance, the effects of the Auto Levels tool have changed (for the better) between versions 4.0.11 and 4.0.12, so if your old processing profiles had it enabled, the results in 4.0.12 will be a little different and may require tuning your old profiles.
* Some users have not checked "[[Preferences]]" in a long time, and their program is tuned for what worked best long ago, not for what works best now. Our defaults are good defaults, we keep them up to date to make RawTherapee look and function well out-of-the-box, so sometimes having RawTherapee start with fresh defaults is a good thing, and it will motivate users to look into "[[Preferences]]" again.
* Some users have never looked inside "[[Preferences]]" in the first place, and are unaware of some of the features that can be unlocked there. As above, fresh defaults will activate these things.
* Some old cache and config files can cause RawTherapee to crash. While we patch the specific cases made known to us, it is safe to assume there will always be cases unknown to us which will still cause instability. Starting with clean cache and config folders mitigates this problem.

Editor

2021-03-22T05:55:22Z

Thanatomanic: Added image of buttons, removed duplicate explanation, now refer to detailed article on processing profiles.

<div class="pagetitle">The Editor</div>

[[File:Rt 55 trains.png|none|frame|link=|class=heroed|The Image Editor tab in RawTherapee 5.5.]]

== Introduction ==

The Image Editor tab is where you tweak your photos. By default RawTherapee is in "''Single Editor Tab Mode, Vertical Tabs''" (SETM) which is more memory-efficient and lets you use the ''Filmstrip'' (described below). You can switch to "''Multiple Editor Tabs Mode''" (METM) by going to "''Preferences > General > Layout''", however each Editor tab will require a specific amount of RAM relative to the image size and the tools you use, and also the ''Filmstrip'' is hidden in this mode, so we recommend you first give SETM a try.

== The Preview Panel ==

The central panel holds a preview of your photo. This preview is generated from the actual raw data by processing it according to the settings either you manually set, or those that are stored in the [[Sidecar_Files_-_Processing_Profiles | processing profile]] used when opening that photo, as specified in "''Preferences > Image Processing > Default Processing Profile''". The preview will show you the effect of all the adjustments you make. Note that the effects of some tools are only accurately visible when you are zoomed in to 1:1 (100%) or more. These tools are marked in the interface with a "1:1" icon [[File:One-to-one-small.png|Zoom 1:1]] next to the tool's name.

The image you see in the preview is taken from the working profile's color space and converted into the monitor profile's color space, if a monitor profile is loaded, or into sRGB if one is not. It does not take into account the "[[Color_Management#Output_Profile|Output Profile]]" section of the "[[Color_Management|Color Management]]" tool.

=== Eek! My Raw Photo Looks Different than the Camera JPEG ===

After opening a raw photo you will notice that it looks different, often worse - darker, less sharp, more dull, lacking contrast, more noisy - than your camera's JPEG, or than the same raw photo when viewed in other software. What gives? Witches, aliens, possums, or by design?

There are three things you must know first to understand what is happening here:
# Your camera does not show you the real raw data when you shoot raw photos. It processes the raw image in many ways before presenting you with the histogram and the preview on your camera's digital display. Even if you set all the processing features your camera's firmware allows you to tweak to their neutral, "0" positions, what you see is still not an unprocessed image. Exactly what gets applied depends on the choices your camera's engineers and management made, but usually this includes a custom tone curve, saturation boost, sharpening and noise reduction. Some cameras, particularly low-end ones and [http://en.wikipedia.org/wiki/Micro_Four_Thirds_system Micro Four-Thirds system], may also apply lens distortion correction to not only fix [http://en.wikipedia.org/wiki/Distortion_(optics)#Radial_distortion barrel and pincushion distortion] but also to hide severe [http://en.wikipedia.org/wiki/Vignetting vignetting] problems. Most cameras also underexpose every photo you take by anywhere from -0.3EV to even -1.3EV or more, in order to gain headroom in the highlights. When your camera (or other software) processes the raw file it increases exposure compensation by the same amount, making the brightness appear correct and hoping to recover some highlights in the process. RawTherapee shows you the real raw data which may mean your photos appear dark, so it is up to you whether you apply the required exposure increase and how you go about doing so, whether by using the Exposure Compensation slider or one of the various tone curves. Increasing exposure compensation makes noise more apparent regardless whether it is your camera or RawTherapee which does it, but other than this [b]RawTherapee does not "add noise"![/b] Many cameras apply noise reduction to the JPEGs (behind your back) to lower the noise level after increasing the exposure compensation, so you should expect there to be a difference between your out-of-camera JPEG and RawTherapee's image if noise reduction in RawTherapee is not enabled.
# Every DSLR raw file contains a processed JPEG image. Most raw files contain a JPEG image of the same full resolution as your camera can shoot, and some raw files contain as many as three JPEG images differing only in resolution. When you open raw files in other software, what you are usually seeing is '''not''' the raw data, but the embedded, processed JPEG image. Examples of software which are either incapable of or which in their default settings do not show you the real raw data: [http://en.wikipedia.org/wiki/IrfanView IrfanView], [http://en.wikipedia.org/wiki/XnView XnView], [http://en.wikipedia.org/wiki/Gwenview Gwenview], [http://en.wikipedia.org/wiki/Geeqie Geeqie], [http://en.wikipedia.org/wiki/Eye_of_GNOME Eye of GNOME], [http://en.wikipedia.org/wiki/F-Spot F-Spot], [http://en.wikipedia.org/wiki/Shotwell_(software) Shotwell], [http://en.wikipedia.org/wiki/GThumb gThumb], etc. It is worth mentioning at this point that if you shoot in "RAW+JPEG" mode, you are in fact wasting disk space and gaining nothing for it, as your raw files already contain the embedded JPEG files which you can view using the listed programs. The embedded JPEG may differ from an 'external' one as saved using "RAW+JPEG" mode in compression.
# Most raw development programs (programs which do read the real raw data instead of just reading the embedded JPEG) apply some processing to it, such as a base tone curve, even at their most neutral settings, thereby making it impossible for users to see the real, untouched contents of their raw photos. Adobe Lightroom is an example. Comparing RawTherapee's real neutral image to a quasi-neutral one from these other programs will expose the differences.

RawTherapee, on the other hand, is designed to show you the real raw image in the main preview, leaving the way you want this data processed up to you. When you use the "Neutral" processing profile you will see the demosaiced image with camera white balance in your working color space with no other modifications. You can even see the non-demosaiced image by setting the [[demosaicing]] option to "None". To provide you with a more aesthetically pleasing starting point, we do ship a collection of processing profiles with RawTherapee. After installing RawTherapee, the default profile for processing raw photos is eponymously called "Default". We also ship the "Default ISO Medium" and "Default ISO High" profiles which are designed to give a good starting point to moderately noisy and very noisy images, respectively.

None of the shipped profiles (at least none of the ones shipped in RawTherapee 5.0) are designed to imitate your camera's look. Why not? Every camera is different. My camera's image quality at ISO1600 could be far noisier than your camera's. My camera's response to colors differs from yours. Even the same camera can behave differently at various settings. To provide such profiles, we would need access to raw files for every supported camera model, often multiple raw files in various shooting modes for a single camera, and countless [http://en.wikipedia.org/wiki/Man-hour person-hours]. This may be possible as a community effort, but it is not a job for a small team. Even then, of what purpose would RawTherapee be if you ended up with a camera JPEG look?

It is far more reasonable that you learn how to use the powerful tools that RawTherapee provides to get the most out of your raws, to surpass the camera look.

As of September 2015 we are starting to ship DCP input profiles made using [http://www.ludd.ltu.se/~torger/dcamprof.html DCamProf] which include an [http://www.ludd.ltu.se/~torger/dcamprof.html#dcp_tone optional tone curve]. This curve is modeled after Adobe Camera Raw's default film curve and renders a result similar to your "camera look". The reason we include the curve in new DCP profiles is because it makes for a good vibrant starting point (as opposed to the flat look of using the "Neutral" processing profile) without having to use [[Exposure#Auto_Levels|Auto Levels]] and without having to touch any of the other tools, and it is entirely optional. Do read the article on [[Color_Management#Input_Profile|input profiles]]. If we ship a DCP for your camera model which includes the tone curve, the "Tone curve" checkbox in Color Management > Input Profile > DCP will be clickable. Applying the (Neutral) processing profile will disable the tone curve.
While the input color profile is applied at the first stages of the [[Toolchain_Pipeline|toolchain pipeline]], the DCP tone curve is applied later in the pipeline at some point after the Exposure tool.

You can create a processing profile ideally tailored to your camera and lens combination, and set RawTherapee to use it by default on your raw photos. See the [[Creating processing profiles for general use]] article to learn how.

=== Scrollable Toolbars ===

The toolbars above and below the main preview hold a certain number of buttons and other widgets which might not fit on lower resolution screens. {{:Scrollable Toolbar}}

=== Preview Modes ===

In addition to the normal preview, RawTherapee supports a number of other preview modes to help you tweak your photos. Preview modes are controlled via buttons in the ''Editor'' toolbar or via [[Keyboard_Shortcuts | keyboard shortcuts]]. Only one preview mode can be engaged at a time.

<div style="margin-left: 16px; margin-top: -1em;">
{| class="RPwt-table"
|+ align="bottom" | <nowiki>*</nowiki> The preview is returned to normal by deselecting any other mode.
! Preview Mode
! Shortcut
! Button
|-
| style="padding:10px;" | Regular* || || [[Image:preview mode 1 regular.png]]
|-
| style="padding:10px;" | Red channel || align="center" | r || [[Image:preview mode 2 red.png]]
|-
| style="padding:10px;" | Green channel || align="center" | g || [[Image:preview mode 3 green.png]]
|-
| style="padding:10px;" | Blue channel || align="center" | b || [[Image:preview mode 4 blue.png]]
|-
| style="padding:10px;" | Luminance channel || align="center" | v || [[Image:preview mode 5 luminance.png]]
|-
| style="padding:10px;" | Focus Mask || align="center" | Shift+f || [[Image:preview mode 6 focus.png]]
|}
</div>
The following preview modes are currently supported:
* Red channel,
* Green channel,
* Blue channel,
* Luminosity, which is calculated as 0.299*R + 0.587*G + 0.114*B,
* Focus mask, to see which areas are in focus

<gallery mode="packed" caption="Preview modes" style="clear: both">
Image:Preview_1_regular.jpg|Regular
Image:Preview_2_red.jpg|Red
Image:Preview_3_green.jpg|Green
Image:Preview_4_blue.jpg|Blue
Image:Preview_5_luminosity.jpg|Luminosity
Image:Preview_6_focus.jpg|Focus Mask
</gallery>

==== Red, Green, Blue and Luminosity Preview Modes ====

{{:Clipping_Indication}}

Preview of individual channels may be helpful when editing RGB curves, planning black/white conversion using the channel mixer, evaluating image noise, etc. Luminosity preview is helpful to instantly view the image in black and white without altering development parameters, to see which channel might be clipping or for aesthetic reasons.

==== Focus Mask ====

[[Image:Preview_6_focus_2.jpg|Focus mask indicating the focusing plane|thumb]]
The focus mask is designed to highlight areas of the image which are in focus. Naturally, focused areas are sharper, so the sharp areas are being highlighted. The focus mask is more accurate on images with a shallow depth of field, low noise and at higher zoom levels.To improve detection accuracy for noisy images evaluate at smaller zoom, around the 10-30% range. Note that the preview is rendered more slowly when the focus mask is enabled.

The current implementation analyzes the preview image which is rescaled from the original captured size. This process of rescaling reduces the noise and is helpful to identify truly sharper details rather than noise itself which may also contain micro texture. At the same time, rescaling of the original image to the preview size compresses larger scale details into a smaller size, and it may introduce aliasing artifacts, both of which could lead to false positives. You can increase your confidence by viewing the mask at various zoom levels. It is not always fault proof, but can be helpful in many cases.

'''Warning''': Be sure to double-check your images if you decide to delete them based on the focus mask.

=== Background color of the preview ===

The background color of the preview panel surrounding the image area may be changed to ease image preview during editing and to better visualize image cropping. A vertical stack of three thin buttons in the preview modes toolbar above the image preview panel allows to set the background color of the area around the photo preview.

<div style="margin-left: 16px; margin-top: -1em;">
{| class="RPwt-table"
! Preview<br />Background
! Shortcut
! Button
! Preview Background<br />and Crop Visualization
! Description
|-
| Theme-based || align="center" | 8 || [[Image:Previewback_7_theme.png]] || [[Image:Previewback_flower_theme.png|180px]] || The cropped area of the image is masked with a theme-based color. The cropped area visibility is based on the crop mask color and transparency as set in "''Preferences > Default Theme > Crop mask color/transparency''".
|-
| Black || align="center" | 9 || [[Image:Previewback_8_black.png]] || [[Image:Previewback_flower_white.png|frameless]] || The cropped area of the image is masked with black.
|-
| White || align="center" | 0 || [[Image:Previewback_9_white.png]] || [[Image:Previewback_flower_black.png|frameless]] || The cropped area of the image is masked with white.
|}
</div>

=== Detail Window ===

The "New detail window" button [[File:Window-add.png]], situated below the main preview next to the zoom buttons, opens a new viewport over the main preview of an adjustable size and of adjustable zoom. This lets you work on the photo zoomed-to-fit while examining several areas of interest at a 100% zoom (or even more). The benefit of using this feature is particularly important to users with slower machines, though not only them, as the zoomed-out main preview takes a shorter amount of time to update than if you were to zoom it to 100% because working at a zoom level less than 100% excludes certain slow tools, such as Noise Reduction, while the little detail windows zoomed to 100% do include all tools and are fast to update because of their small size. This allows you can use the main preview for your general exposure tweaks where it is necessary to see the whole image, and one or more detail windows to get sharpening and/or noise reduction just right.

=== Preview refresh delay ===

Changing any tool's parameters sends a signal for the preview image to be updated accordingly. Imagine what would happen if there was no "delay period", and you dragged, for example, the exposure compensation slider from 0.00 to +0.60. A signal would be sent to update the preview for every single change of that value - for +0.01, +0.02, ... +0.59, +0.60. Updating the preview 60 times would be completely unnecessary and actually take longer than it takes you to move the slider. This is especially true for more complicated tools, such as noise reduction, where a preview update can take even a second (depending on your CPU and preview size). The solution is for RawTherapee to wait for a very short period from the moment you stop moving a slider (you don't have to let go of it, pausing movement is enough) until the moment it sends a signal for the preview to be refreshed.

We have introduced two parameters which control the length of this waiting period:
; AdjusterMinDelay
: Default value = 100ms.
: This is used for tools with a very fast response time, for example the exposure compensation slider.
; AdjusterMaxDelay
: Default value = 200ms.
: This is used for tools with a slow response time, for example the CIECAM02 sliders.

You can adjust both of these values in the options file in the [[File_Paths|config folder]].

== The Left Panel ==

To the left is a panel which optionally shows the main histogram ("''Preferences > General > Layout > Histogram in left panel''"), and always shows the ''Navigator'', ''History'' and ''Snapshots''.
You can hide this panel using the [[Image:panel-to-left.png|Hide left panel icon]] hide icon, or its [[Keyboard Shortcuts|keyboard shortcut]].

=== Main Histogram ===

[[File:Rt57 histogram wide labeled.png|none|frame|class=heroed|Histogram showing all 3 channels and luminosity.]]

[[File:RT57 histogram ani.gif|frame|The histogram in RawTherapee 5.7, showing a histogram of the raw data in all three modes - linear-linear, linear-log and log-log. We can see that the raw file is not clipped.]]

[[File:Rt histogram rgbindicator.png|frame|The RGB indicator shows the position in the histogram of the R, G, B and L values of the pixel your cursor is hovering over.]]

A histogram in photography is a graphical representation of the number of pixels of a given value. Typically the horizontal axis represents the range of possible values while the vertical axis represents the count of pixels with that value. The axes need not be linear - RawTherapee can also scale the histogram logarithmically.

Regardless of the photo's bit depth, the histogram itself has a precision of 256 sampling bins. To understand this, let us look at the example of a 16-bit image using integer precision. Its range of possible values spans from 0 to 65535 (2^16 = 65536 possible values, and since 0 is a possible minimum value then the maximum value is 65535). Drawing a histogram using 16-bit precision would mean that it would need to be 65535 pixels wide to faithfully represent the data, and no screen today is anywhere near that wide. Instead, all pixels with values from 0 to 255 (65535/256*1) are grouped into the first "bin". The second bin consists of a count of all pixels with values from 256 to 511 (65535/256*2). The third bin represents values 512 to 767 (65535/256*3). And so on until bin 256. This happens regardless of the input image's bit depth - and RawTherapee's engine uses 32-bit floating-point precision anyway.

The main histogram can simultaneously show one or more of the following:
* [[File:Histogram-red-on-small.svg]] the red channel,
* [[File:Histogram-green-on-small.svg]] the green channel,
* [[File:Histogram-blue-on-small.svg]] the blue channel,
* [[File:Histogram-silver-on-small.svg]] CIELab luminance,
* [[File:Histogram-gold-on-small.svg]] [http://en.wikipedia.org/wiki/Chromaticity chromaticity].
* [[File:Histogram-bayer-on-small.svg]] red, green and blue channels of the source raw image before demosaicing.

The histogram shows the channels listed above using the gamma-corrected output profile when the gamut button [[File:Gamut-hist.png]] is disabled (default), or using the working profile when the button is enabled. The status of this button also affects the values shown in the Navigator panel, as well as the clipped shadow [[File:Warning-shadows.png]] and [[File:Warning-highlights.png]] highlight indicators. It does not affect the raw histogram.

Like water in a pipeline, image data flows through RawTherapee from the input file through various stages, most of which the user can control, to the output. The output could be the image saved in a file, or the image displayed on your screen. Each stage affects the color data. The histogram allows you to visualize this data at several stages. By default, the histogram shows color data as it will appear if you save the output image, including processing done at all intermediate stages. By enabling the gamut button [[File:Gamut-hist.png]] you can peak at the data at the early stage where it gets converted into the working space. You can even look at the raw data before any transformations or demosaicing are applied.

Let's examine the large histogram example above. Though it actually shows four histograms (red, green, blue and luminance), focus on one histogram at a time. The horizontal axis represents the possible values of the histogram, where "A" are the darkest values possible, "C" the mid-tones, and "E" the brightest possible values. The position of the histogram line on the vertical axis represents how many pixels have that value. We can see that there are zero pixels in the red channel with values around "A" (from zero to very dark), because the histogram line lies right along the bottom. There is a significant number of pixels where the red channel is dark (between A and B), and a significant number where it is light (around D). Then, importantly, there is a spike at the right end of the histogram, at E - it tells us that a large number of pixels have maximal red values - they are clipped.

Generally speaking, you should care when clipping occurs on skin, and not care when it's due to [https://en.wikipedia.org/wiki/Specular_highlight specular highlights]. If a histogram shows clipping, and if you care about the clipped regions, you should start by establishing where the clipping occurs. Check the raw histogram - are any channels clipped? If yes, then maybe [[Exposure#Highlight_Reconstruction|highlight reconstruction]] can help. If the raw histograms are not clipped, then all the required information is intact, and it is some stage downstream in the pipeline which causes clipping. Ensure your working profile's gamut is large enough by enabling the gamut button [[File:Gamut-hist.png]] to see histograms at the working profile stage of the pipeline. You might want to temporarily apply the [[Neutral]] profile to disable all the tools while checking, then revert. If your working space is not causing clipping (the default working space is ProPhoto and it's huge), then it's likely your adjustments which are causing clipping. Reduce exposure, go easy on the curves, use dynamic range compression if necessary.

Knowing how to read a histogram is a basic and very useful skill, as it can point out issues with your image regardless of how dim or miscalibrated your monitor may be.

To help you visualize the data, the histogram (as of RawTherapee 5.5) has three modes which scale the data in the x and y axes differently:
* [[File:Histogram-mode-linear-small.png]] Linear-linear mode. You find gridlines at halves, quarters, eighths and sixteenths, depending on the size of the histogram.
* [[File:Histogram-mode-logx-small.png]] Linear-log mode. The x-axis is linear, the y-axis and the horizontal gridlines are scaled logarithmically. The position of the gridlines still corresponds to the halves, quarters, etc.
* [[File:Histogram-mode-logxy-small.png]] Log-log mode. Both the x- and y-axes are scaled logarithmically. The gridlines are not scaled logarithmically, but correspond to [https://en.wikipedia.org/wiki/Exposure_value stops] - with every gridline the value doubles, so there are lines for the values 1, 3, 7, 15, 31, 63, and 127 (<code>pow(2.0,i) - 1)</code>).

When there is a disproportionately bright area relative to the rest of the image, it will show up as a spike in the histogram. If you want to show this on a histogram with a linear y axis, the spike may push the lesser values down the y-axis, making them difficult to see. Switch to one of the log modes to scale the data and help you get a better overview of all values.

The histogram can be moved to the left/right panel from "''Preferences > General > Layout > Histogram in left panel''".

==== Raw Histograms ====

Raw files contain a dump of data captured by the sensor and quantified by the analog-to-digital converter. The raw file as a container has a bit depth of its own, typically 16-bit, while the data it contains could have a lower bit depth - typically it is 12-bit (0-4096) or 14-bit (0-16384). To display the data from a raw file as an image, one of the several key bits of information required to process the data correctly are the black and white levels. The black level is not necessarily 0, as the sensor and camera electronics produce digital noise, so the noise floor may lie for instance at 512. The white level is also not necessarily 16384; it depends on various things, and may lie for instance at 16300. For more information, see the articles [[Demosaicing]] and [[Adding Support for New Raw Formats]] (especially the header of the <code>camconst.json</code> file). The black and white level values used by RawTherapee are hierarchically set by looking in several places: in <code>dcraw.c</code>, inside the raw file's metadata, and in <code>camconst.json</code> (latter takes precedence). Furthermore, the user can tweak the raw [[Raw Black Points|black]] and [[Raw White Points|white]] levels from within RawTherapee.

The raw histograms show data after black level subtraction. The right end of the histogram is anchored on the white level. The raw histograms are affected by the detected black and white levels as well as by the black and white level adjustments made by the user in RawTherapee.

When examining the raw histogram, you may also want to set the demosaicing method to "none". This will reveal the sensor pattern in the preview, and also cause the [[Editor#Navigator|Navigator]] panel to show the raw RGB values of the pixel currently being hovered over. These values are affected by the detected black and white levels as well as by the black level adjustments made by the user in RawTherapee, but they are not affected by the white level adjustments ("white-point correction") made by the user in RawTherapee.

=== Navigator ===

The ''Navigator'' panel shows a thumbnail of the currently opened image, and RGB, HSV and Lab values of the pixel your cursor is currently hovering over.

The values shown in the main histogram and Navigator panel are either those of the working profile or of the gamma-corrected output profile, depending on the state of the gamut button [[File:Gamut-hist.png]] located in the toolbar above the main preview. When the gamut button is enabled the working profile is used, otherwise the gamma-corrected output profile is used.

By clicking on the values in the Navigator you can cycle between these three formats:
* [0-255]
* [0-1]
* [%]

RawTherapee 5.1 onward can show the real raw photosite values. To see them, set the Navigator to use the [0-255] range, apply the [[Neutral]] [[Sidecar_Files_-_Processing_Profiles|processing profile]], then set the [[Demosaicing]] method to "None". The Navigator will show the real raw photosite values after black level subtraction within the range of the original raw data.

=== History ===

The History panel contains a stack of entries which reflect each of your image editing actions. By clicking on the entries you can step back and forth through the different stages of your work.

An entry is added each time you adjust a ''different'' widget - multiple edits to the same widget are stored as one entry. For example, adjusting the exposure compensation slider from "0" to "0.3" and then to "0.6" will result in one entry being stored with a final value of "0.6". Likewise, when adjusting a curve, all individual control point adjustments are grouped into one history entry. Should you wish to store the adjustments as two (or more) history entries, you will have to split them by adjusting some other widget. For example, assuming a curve is in "Film-like" mode and you want to keep to that way: adjust several control points on the curve, then toggle the curve mode from "Film-like" to "Standard" and then back to "Film-like" to create a new history entry, and then continue adjusting the curve.

The history stack is not saved - it is lost as soon as you close the Editor tab. None of your adjustments are lost though, as the final state of all tools is saved in the [[Sidecar Files - Processing Profiles|sidecar file]], ready to be used the next time you open that image.

=== Snapshots ===

Under the ''History'' panel is a panel called ''Snapshots''. Its use is in that you can save a snapshot of the photo with all the adjustments up to that point in time, and then proceed to further modify your photo to give it a different appearance, saving new snapshots at every moment you feel you might have reached a version of your photo worth saving. Once you have two or more snapshots, you can just click on them to flip through the different versions and stick with whichever one you like best. In the future, the snapshots will be saved to the PP3 sidecar file. For now, the history and snapshots are lost when you load a new photo in the ''Image Editor'' or close RawTherapee.

== The Right Panel ==

To the right is a panel which optionally shows the main histogram and ''Processing Profiles'' selector ("''Preferences > General > Layout > Histogram in left panel''"), and always shows the [[Toolbox]].
You can hide this panel using the [[Image:panel-to-right.png|Hide right panel icon]] hide icon, or its [[Keyboard Shortcuts|keyboard shortcut]].

=== Processing Profile Selector ===

In the top right corner you find options to apply and store specific processing profiles:

[[File:Processing-profiles-selector.png|center|frame]]

Read the page on [[Sidecar_Files_-_Processing_Profiles | processing profiles]] for more information.

=== Toolbox ===

The ''Toolbox'', in the right panel, contains all the tools you use to tweak your photos. Each tool has its own RawPedia article.

== Editor Tab Modes ==

RawTherapee allows you to work on photos in two modes:
* ''Single Editor Tab Mode'' (SETM), where you work only on one photo at a time, and each photo is opened in the same ''Editor'' tab. There is a horizontal panel called the ''[[The_Image_Editor_Tab#The_Filmstrip | Filmstrip]]'' at the top of the ''[[The_Image_Editor_Tab#The_Filmstrip | Editor]]'' tab showing the rest of the photos in that folder for easy access. There are ''Previous Image'' and ''Next Image'' [[File:Nav-prev.png]] [[File:Nav-next.png]] buttons in the bottom toolbar (and [[Keyboard Shortcuts | keyboard shortcuts]] for them) to switch to the previous/next image.
* ''Multiple Editor Tabs Mode'' (METM), where each photo is opened in its own ''[[The_Image_Editor_Tab#The_Filmstrip | Editor]]'' tab. The ''[[The_Image_Editor_Tab#The_Filmstrip | Filmstrip]]'' is hidden in this mode and there are no previous/next buttons. Having multiple photos opened at the same time requires more RAM.

Try both modes and see which one suits you best. To do that, click on the ''Preferences'' icon [[image:preferences.png|Preferences icon]] in the bottom-left or top-right corner of the RT window, choose "''General > Layout''" and set ''Editor Layout'' to your preferred choice.

Use this ''Preferences'' window to select a different language for the user interface, to choose a different color theme, change the font size, etc.

It is also possible to start RawTherapee in no-File-Browser-mode (without the ''File Browser'' tab) by specifying RawTherapee to open an image from your operating system's file browser (in other words, right-click on a photo and select "''Open With > RawTherapee''"), or by using the image filename as an argument when starting RawTherapee from the command line (<code>rawtherapee /path/to/some/photo.raw</code>). This mode was introduced for people with little RAM as not having a ''File Browser'' tab means RawTherapee uses a little less memory, however in practice the amount of memory saved is little and the usability cost outweighs the little benefit, so it is likely to be removed in the future (see [https://code.google.com/p/rawtherapee/issues/detail?id=2254 issue 2254]).

== The Filmstrip ==

[[File:Rt filmstrip 21 toolbar-visible.jpg|none|frame|class=heroed|RawTherapee-4.2 showing the Filmstrip with the toolbar visible, which takes up more screen space but lets you easily label, rate and filter the visible thumbnails.]]
[[File:Rt filmstrip 21 toolbar-hidden.jpg|none|frame|class=heroed|RawTherapee-4.2 showing the Filmstrip with the toolbar hidden, which makes it less high and provides more screen space for the main preview (partially visible at the bottom).]]

If you use ''Single Editor Tab Mode'' ("''Preferences > General > Layout''") you can display a horizontal panel above the preview, this is called the ''Filmstrip''. It contains thumbnails of all images in the currently opened album, and is synchronized with the currently opened image so that you can use [[Keyboard Shortcuts|keyboard shortcuts]] or the previous [[Image:nav-prev.png|Open previous image icon]] and next [[Image:nav-next.png|Open next image icon]] image buttons to open the previous/next image without needing to go back to the ''[[The File Browser Tab|File Browser]]'' tab.

As of RawTherapee version 4.2.10, you can hide the Filmstrip's toolbar to save screen space. There are two ways of doing this: one way just toggles the toolbar on/off without resizing the filmstrip to the new height, and the other way does the same but also automatically resizes the filmstrip's height. Both are invoked via [[Keyboard Shortcuts|keyboard shortcuts]] only. As resizing the filmstrip's height will trigger a refresh of the image preview and this might take a while if using CPU-hungry tools like noise reduction while zoomed in at 100%, the mode that doesn't resize has been implemented for users with slow machines. Users with fast machines will find the auto-resizing mode more helpful.

== Monitor Profile and Soft-Proofing ==

The widgets under the main preview in RawTherapee 5 allow you to apply a monitor color profile to the preview image. This enables users who have calibrated and profiled their monitors to get an instant and accurate preview of their work, whether you're staying in sRGB or working in a wide gamut. Note: OS X users are limited to sRGB and will not get an accurate preview otherwise ([https://discuss.pixls.us/t/wide-gamut-preview-in-os-x/2481 see discussion]), while users of Linux and Windows will get a correct wide-gamut preview.

Go to Preferences > [[Preferences#Color_Management_Tab|Color Management]] and point the "Directory containing color profiles" to the folder into which you saved your monitor and printer ICC profile. Restart RawTherapee for the changes to take effect. Now you will be able to select your monitor's color profile in the combo-box under the preview. Use the "Relative Colorimetric" rendering intent unless you have a good reason otherwise.

One can also enable soft-proofing of the preview. This will show you what your image will look like once it gets transformed by the printer profile set in Preferences > [[Preferences#Color_Management_Tab|Color Management]]. If you want to adjust an image for printing and you have an ICC profile for your printer-paper combination you could set that as your output profile, enable "Black point compensation" in Preferences so that the blackest black in your image will match the blackest black your printer-paper combination is capable of reproducing, then enable soft-proofing. You will see what your image will look like if you print it. This allows you to make adjustments and get an instant preview of the result, saving you time and ink on test prints.

The icon with exclamation mark next to the soft-proofing button will gray out areas that cannot be reproduced by your printer, i.e. areas where you will loose details.

You should have a calibrated and profiled monitor in order for the soft-proofing preview to be accurate.

The items you see in the monitor profile combo-box (under the main preview) and in the printer profile combobox (in Preferences > [[Preferences#Color_Management_Tab|Color Management]]) are ICC files located in a folder which you can point RawTherapee to by going to "[[Preferences]] > [[Preferences#Color_Management_Tab|Color Management]] > Directory containing color profiles".