IBA::contrast_remap() and oiiotool --contrast (#2043)

Allows flexible linear or sigmoidal contrast remapping.

Author: lgritz

src/doc/imagebufalgo.tex

@@ -1197,6 +1197,80 @@ \section{Image arithmetic}
 \apiend
 
 
+\apiitem{ImageBuf {\ce contrast_remap} (const ImageBuf \&src, \\
+        \bigspc\spc cspan<float> black=0.0f, cspan<float> white=1.0f, \\
+        \bigspc\spc cspan<float> min=0.0f, cspan<float> max=1.0f, \\
+        \bigspc\spc cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f, \\
+        \bigspc\spc ROI roi=\{\}, int nthreads=0) \\
+bool {\ce contrast_remap} (ImageBuf \&dst, const ImageBuf \&src,\\
+        \bigspc\spc cspan<float> black=0.0f, cspan<float> white=1.0f, \\
+        \bigspc\spc cspan<float> min=0.0f, cspan<float> max=1.0f, \\
+        \bigspc\spc cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f, \\
+        \bigspc\spc ROI roi=\{\}, int nthreads=0)}
+\index{ImageBufAlgo!contrast_remap} \indexapi{contrast_remap}
+\NEW % 1.9
+
+Return (or copy into {\cf dst}) pixel values that are a contrast-remap
+of the corresponding values of the {\cf src} image, transforming pixel
+value domain [black, white] to range [min, max], either linearly or with
+optional application of a smooth sigmoidal remapping (if scontrast != 1.0).
+
+\noindent The following steps are performed, in order:
+
+\begin{enumerate}
+\item Linearly rescale {\cf black} to 0.0 and {\cf white} to 1.0.
+\item Optionally raise to power 1/gamma (only if {\cf gamma} is not 1.0).
+\item Apply a sigmoidal remapping (only if {\cf scontrast} $> 1$) where a larger
+   {\cf scontrast} value makes a steeper slope, and the steepest part is at
+   value {\cf sthresh} (relative to the new remapped value after steps 1 \& 2;
+   the default is 0.5).
+\item Rescale the range of that result: 0.0 to min and 1.0 to max.
+\end{enumerate}
+
+Values outside of the [black,white] range will be extrapolated to
+outside [min,max], so it may be prudent to apply a clamp() to the
+results.
+
+The black, white, min, max, scontrast, sthresh parameters may each
+either be a single float value for all channels, or a span giving
+per-channel values.
+
+You can use this function for a simple linear contrast remapping of
+[black, white] to [min, max] if you use the default values for sthresh.
+Or just a simple sigmoidal contrast stretch within the [0,1] range if
+you leave all other parameters at their defaults, or a combination of
+these effects. Note that if black == white, the result will be a simple
+binary thresholding where values < black map to min and values >= bkack
+map to max.
+
+\smallskip
+\noindent Examples:
+\begin{code}
+    ImageBuf A ("tahoe.tif");
+
+    // Simple linear remap that stretches input 0.1 to black, and input
+    // 0.75 to white.
+    ImageBuf linstretch = ImageBufAlgo::contrast_remap (A, 0.1f, 0.75f);
+
+    // Remapping 0->1 and 1->0 inverts the colors of the image,
+    // equivalent to ImageBufAlgo::invert().
+    ImageBuf inverse = ImageBufAlgo::contrast_remap (A, 1.0f, 0.0f);
+
+    // Use a sigmoid curve to add contrast but without any hard cutoffs.
+    // Use a contrast parameter of 5.0.
+    ImageBuf sigmoid = ImageBufAlgo::contrast_remap (a, 0.0f, 1.0f,
+                                                     0.0f, 1.0f, 5.0f);
+\end{code}
+
+\noindent \begin{tabular}{cccc}
+\includegraphics[width=1.1in]{figures/tahoe-small.jpg} &
+\includegraphics[width=1.1in]{figures/tahoe-lincontrast.jpg} &
+\includegraphics[width=1.1in]{figures/tahoe-inverse.jpg} &
+\includegraphics[width=1.1in]{figures/tahoe-sigmoid.jpg} \\
+original & linstretch & inverse & sigmoid \\
+\end{tabular}
+\apiend
+
 
 \apiitem{ImageBuf {\ce color_map} (const ImageBuf \&src, int srcchannel, \\
         \bigspc\spc int nknots, int channels, cspan<float> knots, \\
@@ -1237,7 +1311,7 @@ \section{Image arithmetic}
     // Use luminance of a.exr (assuming Rec709 primaries and a linear
     // scale) and map to a color spectrum:
     ImageBuf A ("a.exr");
-    ImageBuf B = ImageBufAlgo::color_map (B, A, -1, "inferno");
+    ImageBuf B = ImageBufAlgo::color_map (A, -1, "inferno");
 
     float mymap[] = { 0.25, 0.25, 0.25,  0, 0.5, 0,  1, 0, 0 };
     B = ImageBufAlgo::color_map (A, -1 /* use luminance */,

src/doc/makefigures.bash

@@ -72,6 +72,10 @@ ${OIIOTOOL} --autocc dilate.jpg erode.jpg -sub -d uint8 -o morphgradient.jpg
 ${OIIOTOOL} --autocc morphsource.jpg morphopen.jpg -sub -d uint8 -o tophat.jpg
 ${OIIOTOOL} --autocc morphclose.jpg morphsource.jpg -sub -d uint8 -o bottomhat.jpg
 
+${OIIOTOOL} -autocc tahoe-small.jpg --contrast:black=0.1:white=0.75 -o tahoe-lincontrast.jpg
+${OIIOTOOL} -autocc tahoe-small.jpg --contrast:black=1:white=0 -o tahoe-inverse.jpg
+${OIIOTOOL} -autocc tahoe-small.jpg --contrast:scontrast=5 -o tahoe-sigmoid.jpg
+
 ${OIIOTOOL} -autocc tahoe-small.jpg --colormap inferno -o colormap-inferno.jpg
 ${OIIOTOOL} -autocc tahoe-small.jpg --colormap viridis -o colormap-viridis.jpg
 ${OIIOTOOL} -autocc tahoe-small.jpg --colormap spectrum -o colormap-spectrum.jpg

src/doc/oiiotool.tex

@@ -940,27 +940,6 @@ \section{\oiiotool commands: general and image information}
 expansion for a subset of the command line.
 \apiend
 
-\begin{comment}
-\apiitem{\ce --inplace}
-Causes the output to \emph{replace} the input file, rather than create a
-new file with a different name.
-
-Without this flag, \oiiotool expects two file names, which will
-be used to specify the input and output files, respectively.
-
-But when {\cf --inplace} option is used, any number of file names $\ge 1$ may
-be specified, and the image conversion commands are applied to each file
-in turn, with the output being saved under the original file name.  This
-is useful for applying the same conversion to many files.  
-
-For example, the following example will add the caption ``Hawaii
-vacation'' to all JPEG files in the current directory:
-
-\begin{code}
-        oiiotool --inplace --adjust-time --caption "Hawaii vacation" *.jpg
-\end{code}
-\apiend
-\end{comment}
 
 
 \section{\oiiotool commands: reading and writing images}
@@ -1982,6 +1961,45 @@ \section{\oiiotool commands that do image processing}
 \includegraphics[width=1.5in]{figures/luma.jpg} \\
 \apiend
 
+\apiitem{\ce --contrast}
+\NEW % 1.9
+Remap pixel values from [black, white] to [min, max], with an optional
+smooth sigmoidal contrast stretch as well.
+
+Optional appended arguments include:
+
+\begin{tabular}{p{10pt} p{1in} p{3.75in}}
+ & {\cf black=}\emph{vals} & Specify black value(s), default 0.0. \\
+ & {\cf white=}\emph{vals} & Specify white value(s), default 1.0. \\
+ & {\cf min=}\emph{vals} & Specify the minimum range value(s), default 0.0. \\
+ & {\cf max=}\emph{vals} & Specify the maximum range value(s), default 1.0. \\
+ & {\cf scontrast=}\emph{vals} & Specify sigmoidal contrast slope value(s), default 1.0. \\
+ & {\cf sthresh=}\emph{vals} & Specify sigmoidal threshold value(s) giving
+        the position of maximum slope, default 0.5. \\
+ & {\cf clamp=}\emph{on} & If \emph{on} is nonzero, will optionally clamp
+                                    all result channels to [min,max].
+\end{tabular}
+
+\noindent Each \emph{vals} may be either a single floating point value
+for all channels, or a comma-separated list of per-channel values.
+
+\noindent Examples:
+\begin{code}
+    oiiotool tahoe.tif --contrast:black=0.1:white=0.75 -o linstretch.tif
+    oiiotool tahoe.tif --contrast:black=1.0:white=0.0:clamp=0 -o inverse.tif
+    oiiotool tahoe.tif --contrast:scontrast=5 -o sigmoid.tif
+\end{code}
+
+\noindent \begin{tabular}{cccc}
+\includegraphics[width=1.1in]{figures/tahoe-small.jpg} &
+\includegraphics[width=1.1in]{figures/tahoe-lincontrast.jpg} &
+\includegraphics[width=1.1in]{figures/tahoe-inverse.jpg} &
+\includegraphics[width=1.1in]{figures/tahoe-sigmoid.jpg} \\
+original & linstretch & inverse & sigmoid \\
+\end{tabular}
+\apiend
+
+
 \apiitem{\ce --colormap {\rm \emph{mapname}}}
 Creates an RGB color map based on the luminance of the input image. The
 {\cf mapname} may be one of: \qkw{magma}, \qkw{inferno}, \qkw{plasma},

src/doc/openimageio.tex

@@ -96,7 +96,7 @@
  \bigskip \\
 }
 \date{{\large
-Date: 8 Oct 2018
+Date: 21 Oct 2018
 %\\ (with corrections, 19 Mar 2018)
 }}
 

src/doc/pythonbindings.tex

@@ -2579,6 +2579,41 @@ \subsection{Image arithmetic}
 \apiend
 
 
+\apiitem{ImageBuf ImageBufAlgo.{\ce contrast_remap} (src, \\
+        \bigspc\spc black=0.0, white=1.0, min=0.0, max=1.0, \\
+        \bigspc\spc sthresh=0.0, scontrast=1.0, \\
+        \bigspc\spc ROI roi=\{\}, int nthreads=0) \\
+bool ImageBufAlgo.{\ce contrast_remap} (ImageBuf \&dst, src,\\
+        \bigspc\spc black=0.0, white=1.0, min=0.0, max=1.0, \\
+        \bigspc\spc sthresh=0.0, scontrast=1.0, \\
+        \bigspc\spc ROI roi=\{\}, int nthreads=0)}
+\index{ImageBufAlgo!contrast_remap} \indexapi{contrast_remap}
+\NEW % 1.9
+
+Return (or copy into {\cf dst}) pixel values that are a contrast-remap
+of the corresponding values of the {\cf src} image, transforming pixel
+value domain [black, white] to range [min, max], either linearly or with
+optional application of a smooth sigmoidal remapping (if scontrast != 1.0).
+
+\smallskip
+\noindent Examples:
+\begin{code}
+    A = ImageBuf('tahoe.tif');
+
+    # Simple linear remap that stretches input 0.1 to black, and input
+    # 0.75 to white.
+    linstretch = ImageBufAlgo.contrast_remap (A, black=0.1, white=0.75)
+
+    // Remapping 0->1 and 1->0 inverts the colors of the image,
+    // equivalent to ImageBufAlgo.invert().
+    inverse = ImageBufAlgo.contrast_remap (A, black=1.0, white=0.0)
+
+    // Use a sigmoid curve to add contrast but without any hard cutoffs.
+    // Use a contrast parameter of 5.0.
+    sigmoid = ImageBufAlgo.contrast_remap (a, contrast=5.0)
+\end{code}
+\apiend
+
 \apiitem{ImageBuf ImageBufAlgo.{\ce color_map} (src, srcchannel, \\
 \bigspc\bigspc        nknots, channels, knots, roi=ROI.All, nthreads=0) \\
 ImageBuf ImageBufAlgo.{\ce color_map} (src, srcchannel, \\

src/include/OpenImageIO/imagebufalgo.h

@@ -795,6 +795,46 @@ bool OIIO_API color_map (ImageBuf &dst, const ImageBuf &src, int srcchannel,
 
 
 
+/// Remap contrast by transforming values [black, white] to new range
+/// [min, max], either linearly or with optional application of a smooth
+/// sigmoidal remapping (if scontrast != 1.0).
+///
+/// The following steps are performed, in order:
+/// 1. Linearly rescale values [black, white] to [0, 1].
+/// 2. If scontrast != 1, apply a sigmoidal remapping where a larger
+///    scontrast value makes a steeper slope, and the steepest part is at
+///    value sthresh (relative to the new remapped value after steps 1 & 2;
+///    the default is 0.5).
+/// 3. Rescale the range of that result: 0.0 -> min and 1.0 -> max.
+///
+/// Values outside of the [black,white] range will be extrapolated to
+/// outside [min,max], so it may be prudent to apply a clamp() to the
+/// results.
+///
+/// The black, white, min, max, scontrast, sthresh parameters may each
+/// either be a single float value for all channels, or a span giving
+/// per-channel values.
+///
+/// You can use this function for a simple linear contrast remapping of
+/// [black, white] to [min, max] if you use the default values for sthresh.
+/// Or just a simple sigmoidal contrast stretch within the [0,1] range if
+/// you leave all other parameters at their defaults, or a combination of
+/// these effects. Note that if black == white, the result will be a simple
+/// binary thresholding where values < black map to min and values >= bkack
+/// map to max.
+OIIO_API ImageBuf contrast_remap (const ImageBuf &src,
+                    cspan<float> black=0.0f, cspan<float> white=1.0f,
+                    cspan<float> min=0.0f, cspan<float> max=1.0f,
+                    cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f,
+                    ROI={}, int nthreads=0);
+OIIO_API bool contrast_remap (ImageBuf &dst, const ImageBuf &src,
+                    cspan<float> black=0.0f, cspan<float> white=1.0f,
+                    cspan<float> min=0.0f, cspan<float> max=1.0f,
+                    cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f,
+                    ROI={}, int nthreads=0);
+
+
+
 
 struct OIIO_API PixelStats {
     std::vector<float> min;