README.md
1# librtprocess
2
3This is a project that aims to make some of RawTherapee's highly optimized raw processing routines readily available for other FOSS photo editing software.
4
5The goal is to move certain source files from RawTherapee into this library.
6Thus, any changes to the source can be done here and will be used by the projects which use librtprocess.
7
8librtprocess currently is maintained by developers of the following projects:
9
10. Filmulator https://github.com/CarVac/filmulator-gui
11
12. HDRMerge https://github.com/jcelaya/hdrmerge
13
14. LuminanceHdr https://github.com/LuminanceHDR/LuminanceHDR
15
16. PhotoFlow https://github.com/aferrero2707/PhotoFlow
17
18. rawproc https://github.com/butcherg/rawproc
19
20. RawTherapee https://github.com/Beep6581/RawTherapee
21
22... the latter is where currently all the code comes from ;-)
23
24This is version 0.11.0, which furnishes the following routines:
25
26* ahd_demosaic
27* amaze_demosaic
28* bayerfast_demosaic
29* dcb_demosaic
30* hphd_demosaic
31* igv_demosaic
32* lmmse_demosaic
33* rcd_demosaic
34* vng4_demosaic
35* markesteijn_demosaic
36* xtransfast_demosaic
37* CA_correct
38* HLRecovery_inpaint
39
40## Build instructions:
41
421. Make a subdirectory named `build`, and `cd` to that directory.
432. Run `cmake -DCMAKE_BUILD_TYPE="Release" ..`
443. Run `make`
454. Run `make install` as root.
46
47Build instructions for Windows msys2 environment:
48
491. Make a subdirectory named `build`, and `cd` to that directory.
502. Run `cmake -G "MSYS Makefiles" -DCMAKE_INSTALL_PREFIX="$MSYSTEM_PREFIX" -DCMAKE_BUILD_TYPE="Release" ..`
513. Run `make`
524. Run `make install`.
53
54Build instructions for macOS:
55
56Prerequisites: XCode/XCode command line tools. An optional SDK (this example uses macOS 10.9). An implementation of OpenMP, for example `libiomp.5`.
571. Make a subdirectory named `build`, and `cd` to that directory.
582. On macOS 10.12 _Sierra_, run `sudo cmake -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="1" -DCMAKE_C_COMPILER="clang-mp-3.9" -DCMAKE_CXX_COMPILER="clang++-mp-3.9" -DCMAKE_CXX_FLAGS=-I/opt/local/include -DCMAKE_OSX_SYSROOT="/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk" -DCMAKE_OSX_DEPLOYMENT_TARGET="10.9" -DOpenMP_C_FLAGS=-fopenmp="libiomp5" -DOpenMP_CXX_FLAGS=-fopenmp="libiomp5" -DOpenMP_C_LIB_NAMES="libiomp5" -DOpenMP_CXX_LIB_NAMES="libiomp5" -DOpenMP_libiomp5_LIBRARY="/opt/local" -DCMAKE_INSTALL_PREFIX=/opt/local ..`
59<br><br>On macOS 10.14 _Mojave_, run `cmake -DCMAKE_BUILD_TYPE="release" -DPROC_TARGET_NUMBER="1" -DCMAKE_CXX_COMPILER="clang++" -DCMAKE_CXX_FLAGS=-I/opt/local/include -DCMAKE_OSX_SYSROOT="/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk" -DCMAKE_OSX_DEPLOYMENT_TARGET="10.9" -DOpenMP_CXX_FLAGS=-fopenmp=lomp -DOpenMP_CXX_LIB_NAMES="libomp" -DOpenMP_CXX_FLAGS="-Xpreprocessor -fopenmp /opt/local/lib/libomp.dylib -I/opt/local/include" -DOpenMP_CXX_LIB_NAMES="libomp" -DOpenMP_libomp_LIBRARY=/opt/local/lib/libomp.dylib -DCMAKE_INSTALL_PREFIX=/opt/local -DCMAKE_SHARED_LINKER_FLAGS=-L/opt/local/lib ..`
603. Run `sudo make -j$(sysctl -n hw.ncpu) install`
61
62Optional switches to be included in the `cmake` command:
63
641. To build in verbose mode, include `-DVERBOSE=ON`
652. If you make your own builds, include `-DPROC_TARGET_NUMBER=2` for maximum speed. Keep in mind that this build will only work on the machine you built it.
66
67## Using librtprocess:
68
69Include `-lrtprocess`, and `#include <rtprocess/librtprocess.h>` to use this library.
70
71### Demosaic
72
73The demosaic routines expect raw data in the form 1) single-channel, 2) float, 3) range 0.0 - 65535.0. This roughly
74corresponds to what the raw libraries deliver, e.g. Libraw's mosaic is single-channel unsigned short 0-65535, except
75for the float number format, so at least a unsigned short -> float cast is probably required.
76
77The raw data array expected by the demosaic routines is float**, which is an array of pointers to pointers. This
78hierarchical pointer arrangement is "row-major", that is, the first array of pointers point to pointers that point to a contiguous block of memory containing the pixel data for a row. This choice of storage is for fast performance, as
79individual pixels can be accessed with pointer dereferencing, but at the expense of rather convoluted memory management
80in C.
81
82The demosaic routines' output are three separate float** arrays, one for each channel. This output organization helps
83certain applications that like to start with the separate channels; for 'regular' use, the red, green, and blue floats
84have to be loaded separately into each channel of the destination RGB struct or array.
85
86Here's a code segment that demonstrates the marshalling/demarshalling of data, taken from the rawproc application. Note:
87rawproc's internal image is a row-major contiguous array of RGB floats in the range 0.0 - 1.0, so the code includes
88the logic to convert from/to this structure.
89
90```
91 //build the input and output data structures. 'w' and 'h' are the image width and height.
92 float **rawdata = (float **)malloc(h * sizeof(float *));
93 rawdata[0] = (float *)malloc(w*h * sizeof(float));
94 for (unsigned i=1; i<h; i++)
95 rawdata[i] = rawdata[i - 1] + w;
96
97 float **red = (float **)malloc(h * sizeof(float *));
98 red[0] = (float *)malloc(w*h * sizeof(float));
99 for (unsigned i=1; i<h; i++)
100 red[i] = red[i - 1] + w;
101
102 float **green = (float **)malloc(h * sizeof(float *));
103 green[0] = (float *)malloc(w*h * sizeof(float));
104 for (unsigned i=1; i<h; i++)
105 green[i] = green[i - 1] + w;
106
107 float **blue = (float **)malloc(h * sizeof(float *));
108 blue[0] = (float *)malloc(w*h * sizeof(float));
109 for (unsigned i=1; i<h; i++)
110 blue[i] = blue[i - 1] + w;
111
112 //loads the internal data to the librtprocess rawData structure. The interal data's red channel
113 //is arbitrarily chosen as a monochrome image is represented R=G=B:
114 #pragma omp parallel for num_threads(threadcount)
115 for (unsigned y=0; y<h; y++) {
116 for (unsigned x=0; x<w; x++) {
117 unsigned pos = x + y*w;
118 rawdata[y][x] = image[pos].r * 65535.f;
119 }
120 }
121
122 vng4_demosaic (w, h, rawdata, red, green, blue, cfarray, f);
123
124 //assemble the demosaiced RGB array from the individual channels:
125 #pragma omp parallel for num_threads(threadcount)
126 for (unsigned y=0; y<h; y++) {
127 for (unsigned x=0; x<w; x++) {
128 unsigned pos = x + y*w;
129 image[pos].r = red[y][x] /65535.f;
130 image[pos].g = green[y][x] /65535.f;
131 image[pos].b = blue[y][x] /65535.f;
132 }
133 }
134
135 free (blue[0]);
136 free( blue );
137 free (green[0]);
138 free( green );
139 free (red[0]);
140 free( red );
141 free (rawdata[0]);
142 free( rawdata );
143```
144
145The Bayer demosaic routines also take in a `cfarray` parameter that is a 2x2 array corresponding to the indexing of the color filters corresponding to the top left corner of the raw image plane. The `xtrans` parameter for the X-Trans routines is similar but has dimensions of 6 by 6. For these, `0` corresponds to red, `1` corresponds to green channel one, `2` corresponds to blue, and `3` corresponds to green channel two. Some algorithms require both greens, others only one.
146
147### Highlight Recovery
148
149The highlight recovery algorithm uses inpainting to reconstruct clipped highlights when not all channels are clipped. The input data should be full RGB for each pixel, in the raw color space, with the white balance multipliers already applied to it. `chmax` is simply the maximum pixel value in each of the three color channels. `clmax` is the raw clip point for each channel; that is, the whitepoint minus the blackpoint for each channel, multiplied by the white balance multipliers.
150