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.12.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.
663. If you want to build a static library instead of a dynamic one, include `-DBUILD_SHARED_LIBS=OFF`
67
68## Using librtprocess:
69
70Include `-lrtprocess`, and `#include <rtprocess/librtprocess.h>` to use this library.
71
72### Demosaic
73
74The demosaic routines expect raw data in the form 1) single-channel, 2) float, 3) range 0.0 - 65535.0. This roughly
75corresponds to what the raw libraries deliver, e.g. Libraw's mosaic is single-channel unsigned short 0-65535, except
76for the float number format, so at least a unsigned short -> float cast is probably required.
77
78The raw data array expected by the demosaic routines is float**, which is an array of pointers to pointers. This
79hierarchical 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
80individual pixels can be accessed with pointer dereferencing, but at the expense of rather convoluted memory management
81in C.
82
83The demosaic routines' output are three separate float** arrays, one for each channel. This output organization helps
84certain applications that like to start with the separate channels; for 'regular' use, the red, green, and blue floats
85have to be loaded separately into each channel of the destination RGB struct or array.
86
87Here's a code segment that demonstrates the marshalling/demarshalling of data, taken from the rawproc application. Note:
88rawproc's internal image is a row-major contiguous array of RGB floats in the range 0.0 - 1.0, so the code includes
89the logic to convert from/to this structure.
90
91```
92 //build the input and output data structures. 'w' and 'h' are the image width and height.
93 float **rawdata = (float **)malloc(h * sizeof(float *));
94 rawdata[0] = (float *)malloc(w*h * sizeof(float));
95 for (unsigned i=1; i<h; i++)
96 rawdata[i] = rawdata[i - 1] + w;
97
98 float **red = (float **)malloc(h * sizeof(float *));
99 red[0] = (float *)malloc(w*h * sizeof(float));
100 for (unsigned i=1; i<h; i++)
101 red[i] = red[i - 1] + w;
102
103 float **green = (float **)malloc(h * sizeof(float *));
104 green[0] = (float *)malloc(w*h * sizeof(float));
105 for (unsigned i=1; i<h; i++)
106 green[i] = green[i - 1] + w;
107
108 float **blue = (float **)malloc(h * sizeof(float *));
109 blue[0] = (float *)malloc(w*h * sizeof(float));
110 for (unsigned i=1; i<h; i++)
111 blue[i] = blue[i - 1] + w;
112
113 //loads the internal data to the librtprocess rawData structure. The interal data's red channel
114 //is arbitrarily chosen as a monochrome image is represented R=G=B:
115 #pragma omp parallel for num_threads(threadcount)
116 for (unsigned y=0; y<h; y++) {
117 for (unsigned x=0; x<w; x++) {
118 unsigned pos = x + y*w;
119 rawdata[y][x] = image[pos].r * 65535.f;
120 }
121 }
122
123 vng4_demosaic (w, h, rawdata, red, green, blue, cfarray, f);
124
125 //assemble the demosaiced RGB array from the individual channels:
126 #pragma omp parallel for num_threads(threadcount)
127 for (unsigned y=0; y<h; y++) {
128 for (unsigned x=0; x<w; x++) {
129 unsigned pos = x + y*w;
130 image[pos].r = red[y][x] /65535.f;
131 image[pos].g = green[y][x] /65535.f;
132 image[pos].b = blue[y][x] /65535.f;
133 }
134 }
135
136 free (blue[0]);
137 free( blue );
138 free (green[0]);
139 free( green );
140 free (red[0]);
141 free( red );
142 free (rawdata[0]);
143 free( rawdata );
144```
145
146The 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.
147
148### Highlight Recovery
149
150The 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.
151