1/*M///////////////////////////////////////////////////////////////////////////////////////
2//
3// IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
4//
5// By downloading, copying, installing or using the software you agree to this license.
6// If you do not agree to this license, do not download, install,
7// copy or use the software.
8//
9//
10// License Agreement
11// For Open Source Computer Vision Library
12//
13// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
14// Copyright (C) 2008-2012, Willow Garage Inc., all rights reserved.
15// Third party copyrights are property of their respective owners.
16//
17// Redistribution and use in source and binary forms, with or without modification,
18// are permitted provided that the following conditions are met:
19//
20// * Redistribution's of source code must retain the above copyright notice,
21// this list of conditions and the following disclaimer.
22//
23// * Redistribution's in binary form must reproduce the above copyright notice,
24// this list of conditions and the following disclaimer in the documentation
25// and/or other materials provided with the distribution.
26//
27// * The name of the copyright holders may not be used to endorse or promote products
28// derived from this software without specific prior written permission.
29//
30// This software is provided by the copyright holders and contributors "as is" and
31// any express or implied warranties, including, but not limited to, the implied
32// warranties of merchantability and fitness for a particular purpose are disclaimed.
33// In no event shall the Intel Corporation or contributors be liable for any direct,
34// indirect, incidental, special, exemplary, or consequential damages
35// (including, but not limited to, procurement of substitute goods or services;
36// loss of use, data, or profits; or business interruption) however caused
37// and on any theory of liability, whether in contract, strict liability,
38// or tort (including negligence or otherwise) arising in any way out of
39// the use of this software, even if advised of the possibility of such damage.
40//
41//M*/
42
43#ifndef OPENCV_PHOTO_HPP
44#define OPENCV_PHOTO_HPP
45
46#include "opencv2/core.hpp"
47#include "opencv2/imgproc.hpp"
48
49/**
50@defgroup photo Computational Photography
51
52This module includes photo processing algorithms
53@{
54 @defgroup photo_inpaint Inpainting
55 @defgroup photo_denoise Denoising
56 @defgroup photo_hdr HDR imaging
57
58 This section describes high dynamic range imaging algorithms namely tonemapping, exposure alignment,
59 camera calibration with multiple exposures and exposure fusion.
60
61 @defgroup photo_decolor Contrast Preserving Decolorization
62
63 Useful links:
64
65 http://www.cse.cuhk.edu.hk/leojia/projects/color2gray/index.html
66
67 @defgroup photo_clone Seamless Cloning
68
69 Useful links:
70
71 https://www.learnopencv.com/seamless-cloning-using-opencv-python-cpp
72
73 @defgroup photo_render Non-Photorealistic Rendering
74
75 Useful links:
76
77 http://www.inf.ufrgs.br/~eslgastal/DomainTransform
78
79 https://www.learnopencv.com/non-photorealistic-rendering-using-opencv-python-c/
80
81@}
82 */
83
84namespace cv
85{
86
87//! @addtogroup photo
88//! @{
89
90//! @addtogroup photo_inpaint
91//! @{
92//! the inpainting algorithm
93enum
94{
95 INPAINT_NS = 0, //!< Use Navier-Stokes based method
96 INPAINT_TELEA = 1 //!< Use the algorithm proposed by Alexandru Telea @cite Telea04
97};
98
99/** @brief Restores the selected region in an image using the region neighborhood.
100
101@param src Input 8-bit, 16-bit unsigned or 32-bit float 1-channel or 8-bit 3-channel image.
102@param inpaintMask Inpainting mask, 8-bit 1-channel image. Non-zero pixels indicate the area that
103needs to be inpainted.
104@param dst Output image with the same size and type as src .
105@param inpaintRadius Radius of a circular neighborhood of each point inpainted that is considered
106by the algorithm.
107@param flags Inpainting method that could be cv::INPAINT_NS or cv::INPAINT_TELEA
108
109The function reconstructs the selected image area from the pixel near the area boundary. The
110function may be used to remove dust and scratches from a scanned photo, or to remove undesirable
111objects from still images or video. See <http://en.wikipedia.org/wiki/Inpainting> for more details.
112
113@note
114 - An example using the inpainting technique can be found at
115 opencv_source_code/samples/cpp/inpaint.cpp
116 - (Python) An example using the inpainting technique can be found at
117 opencv_source_code/samples/python/inpaint.py
118 */
119CV_EXPORTS_W void inpaint( InputArray src, InputArray inpaintMask,
120 OutputArray dst, double inpaintRadius, int flags );
121
122//! @} photo_inpaint
123
124//! @addtogroup photo_denoise
125//! @{
126
127/** @brief Perform image denoising using Non-local Means Denoising algorithm
128<http://www.ipol.im/pub/algo/bcm_non_local_means_denoising/> with several computational
129optimizations. Noise expected to be a gaussian white noise
130
131@param src Input 8-bit 1-channel, 2-channel, 3-channel or 4-channel image.
132@param dst Output image with the same size and type as src .
133@param templateWindowSize Size in pixels of the template patch that is used to compute weights.
134Should be odd. Recommended value 7 pixels
135@param searchWindowSize Size in pixels of the window that is used to compute weighted average for
136given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater
137denoising time. Recommended value 21 pixels
138@param h Parameter regulating filter strength. Big h value perfectly removes noise but also
139removes image details, smaller h value preserves details but also preserves some noise
140
141This function expected to be applied to grayscale images. For colored images look at
142fastNlMeansDenoisingColored. Advanced usage of this functions can be manual denoising of colored
143image in different colorspaces. Such approach is used in fastNlMeansDenoisingColored by converting
144image to CIELAB colorspace and then separately denoise L and AB components with different h
145parameter.
146 */
147CV_EXPORTS_W void fastNlMeansDenoising( InputArray src, OutputArray dst, float h = 3,
148 int templateWindowSize = 7, int searchWindowSize = 21);
149
150/** @brief Perform image denoising using Non-local Means Denoising algorithm
151<http://www.ipol.im/pub/algo/bcm_non_local_means_denoising/> with several computational
152optimizations. Noise expected to be a gaussian white noise
153
154@param src Input 8-bit or 16-bit (only with NORM_L1) 1-channel,
1552-channel, 3-channel or 4-channel image.
156@param dst Output image with the same size and type as src .
157@param templateWindowSize Size in pixels of the template patch that is used to compute weights.
158Should be odd. Recommended value 7 pixels
159@param searchWindowSize Size in pixels of the window that is used to compute weighted average for
160given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater
161denoising time. Recommended value 21 pixels
162@param h Array of parameters regulating filter strength, either one
163parameter applied to all channels or one per channel in dst. Big h value
164perfectly removes noise but also removes image details, smaller h
165value preserves details but also preserves some noise
166@param normType Type of norm used for weight calculation. Can be either NORM_L2 or NORM_L1
167
168This function expected to be applied to grayscale images. For colored images look at
169fastNlMeansDenoisingColored. Advanced usage of this functions can be manual denoising of colored
170image in different colorspaces. Such approach is used in fastNlMeansDenoisingColored by converting
171image to CIELAB colorspace and then separately denoise L and AB components with different h
172parameter.
173 */
174CV_EXPORTS_W void fastNlMeansDenoising( InputArray src, OutputArray dst,
175 const std::vector<float>& h,
176 int templateWindowSize = 7, int searchWindowSize = 21,
177 int normType = NORM_L2);
178
179/** @brief Modification of fastNlMeansDenoising function for colored images
180
181@param src Input 8-bit 3-channel image.
182@param dst Output image with the same size and type as src .
183@param templateWindowSize Size in pixels of the template patch that is used to compute weights.
184Should be odd. Recommended value 7 pixels
185@param searchWindowSize Size in pixels of the window that is used to compute weighted average for
186given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater
187denoising time. Recommended value 21 pixels
188@param h Parameter regulating filter strength for luminance component. Bigger h value perfectly
189removes noise but also removes image details, smaller h value preserves details but also preserves
190some noise
191@param hColor The same as h but for color components. For most images value equals 10
192will be enough to remove colored noise and do not distort colors
193
194The function converts image to CIELAB colorspace and then separately denoise L and AB components
195with given h parameters using fastNlMeansDenoising function.
196 */
197CV_EXPORTS_W void fastNlMeansDenoisingColored( InputArray src, OutputArray dst,
198 float h = 3, float hColor = 3,
199 int templateWindowSize = 7, int searchWindowSize = 21);
200
201/** @brief Modification of fastNlMeansDenoising function for images sequence where consecutive images have been
202captured in small period of time. For example video. This version of the function is for grayscale
203images or for manual manipulation with colorspaces. See @cite Buades2005DenoisingIS for more details
204(open access [here](https://static.aminer.org/pdf/PDF/000/317/196/spatio_temporal_wiener_filtering_of_image_sequences_using_a_parametric.pdf)).
205
206@param srcImgs Input 8-bit 1-channel, 2-channel, 3-channel or
2074-channel images sequence. All images should have the same type and
208size.
209@param imgToDenoiseIndex Target image to denoise index in srcImgs sequence
210@param temporalWindowSize Number of surrounding images to use for target image denoising. Should
211be odd. Images from imgToDenoiseIndex - temporalWindowSize / 2 to
212imgToDenoiseIndex + temporalWindowSize / 2 from srcImgs will be used to denoise
213srcImgs[imgToDenoiseIndex] image.
214@param dst Output image with the same size and type as srcImgs images.
215@param templateWindowSize Size in pixels of the template patch that is used to compute weights.
216Should be odd. Recommended value 7 pixels
217@param searchWindowSize Size in pixels of the window that is used to compute weighted average for
218given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater
219denoising time. Recommended value 21 pixels
220@param h Parameter regulating filter strength. Bigger h value
221perfectly removes noise but also removes image details, smaller h
222value preserves details but also preserves some noise
223 */
224CV_EXPORTS_W void fastNlMeansDenoisingMulti( InputArrayOfArrays srcImgs, OutputArray dst,
225 int imgToDenoiseIndex, int temporalWindowSize,
226 float h = 3, int templateWindowSize = 7, int searchWindowSize = 21);
227
228/** @brief Modification of fastNlMeansDenoising function for images sequence where consecutive images have been
229captured in small period of time. For example video. This version of the function is for grayscale
230images or for manual manipulation with colorspaces. See @cite Buades2005DenoisingIS for more details
231(open access [here](https://static.aminer.org/pdf/PDF/000/317/196/spatio_temporal_wiener_filtering_of_image_sequences_using_a_parametric.pdf)).
232
233@param srcImgs Input 8-bit or 16-bit (only with NORM_L1) 1-channel,
2342-channel, 3-channel or 4-channel images sequence. All images should
235have the same type and size.
236@param imgToDenoiseIndex Target image to denoise index in srcImgs sequence
237@param temporalWindowSize Number of surrounding images to use for target image denoising. Should
238be odd. Images from imgToDenoiseIndex - temporalWindowSize / 2 to
239imgToDenoiseIndex + temporalWindowSize / 2 from srcImgs will be used to denoise
240srcImgs[imgToDenoiseIndex] image.
241@param dst Output image with the same size and type as srcImgs images.
242@param templateWindowSize Size in pixels of the template patch that is used to compute weights.
243Should be odd. Recommended value 7 pixels
244@param searchWindowSize Size in pixels of the window that is used to compute weighted average for
245given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater
246denoising time. Recommended value 21 pixels
247@param h Array of parameters regulating filter strength, either one
248parameter applied to all channels or one per channel in dst. Big h value
249perfectly removes noise but also removes image details, smaller h
250value preserves details but also preserves some noise
251@param normType Type of norm used for weight calculation. Can be either NORM_L2 or NORM_L1
252 */
253CV_EXPORTS_W void fastNlMeansDenoisingMulti( InputArrayOfArrays srcImgs, OutputArray dst,
254 int imgToDenoiseIndex, int temporalWindowSize,
255 const std::vector<float>& h,
256 int templateWindowSize = 7, int searchWindowSize = 21,
257 int normType = NORM_L2);
258
259/** @brief Modification of fastNlMeansDenoisingMulti function for colored images sequences
260
261@param srcImgs Input 8-bit 3-channel images sequence. All images should have the same type and
262size.
263@param imgToDenoiseIndex Target image to denoise index in srcImgs sequence
264@param temporalWindowSize Number of surrounding images to use for target image denoising. Should
265be odd. Images from imgToDenoiseIndex - temporalWindowSize / 2 to
266imgToDenoiseIndex + temporalWindowSize / 2 from srcImgs will be used to denoise
267srcImgs[imgToDenoiseIndex] image.
268@param dst Output image with the same size and type as srcImgs images.
269@param templateWindowSize Size in pixels of the template patch that is used to compute weights.
270Should be odd. Recommended value 7 pixels
271@param searchWindowSize Size in pixels of the window that is used to compute weighted average for
272given pixel. Should be odd. Affect performance linearly: greater searchWindowsSize - greater
273denoising time. Recommended value 21 pixels
274@param h Parameter regulating filter strength for luminance component. Bigger h value perfectly
275removes noise but also removes image details, smaller h value preserves details but also preserves
276some noise.
277@param hColor The same as h but for color components.
278
279The function converts images to CIELAB colorspace and then separately denoise L and AB components
280with given h parameters using fastNlMeansDenoisingMulti function.
281 */
282CV_EXPORTS_W void fastNlMeansDenoisingColoredMulti( InputArrayOfArrays srcImgs, OutputArray dst,
283 int imgToDenoiseIndex, int temporalWindowSize,
284 float h = 3, float hColor = 3,
285 int templateWindowSize = 7, int searchWindowSize = 21);
286
287/** @brief Primal-dual algorithm is an algorithm for solving special types of variational problems (that is,
288finding a function to minimize some functional). As the image denoising, in particular, may be seen
289as the variational problem, primal-dual algorithm then can be used to perform denoising and this is
290exactly what is implemented.
291
292It should be noted, that this implementation was taken from the July 2013 blog entry
293@cite MA13 , which also contained (slightly more general) ready-to-use source code on Python.
294Subsequently, that code was rewritten on C++ with the usage of openCV by Vadim Pisarevsky at the end
295of July 2013 and finally it was slightly adapted by later authors.
296
297Although the thorough discussion and justification of the algorithm involved may be found in
298@cite ChambolleEtAl, it might make sense to skim over it here, following @cite MA13 . To begin
299with, we consider the 1-byte gray-level images as the functions from the rectangular domain of
300pixels (it may be seen as set
301\f$\left\{(x,y)\in\mathbb{N}\times\mathbb{N}\mid 1\leq x\leq n,\;1\leq y\leq m\right\}\f$ for some
302\f$m,\;n\in\mathbb{N}\f$) into \f$\{0,1,\dots,255\}\f$. We shall denote the noised images as \f$f_i\f$ and with
303this view, given some image \f$x\f$ of the same size, we may measure how bad it is by the formula
304
305\f[\left\|\left\|\nabla x\right\|\right\| + \lambda\sum_i\left\|\left\|x-f_i\right\|\right\|\f]
306
307\f$\|\|\cdot\|\|\f$ here denotes \f$L_2\f$-norm and as you see, the first addend states that we want our
308image to be smooth (ideally, having zero gradient, thus being constant) and the second states that
309we want our result to be close to the observations we've got. If we treat \f$x\f$ as a function, this is
310exactly the functional what we seek to minimize and here the Primal-Dual algorithm comes into play.
311
312@param observations This array should contain one or more noised versions of the image that is to
313be restored.
314@param result Here the denoised image will be stored. There is no need to do pre-allocation of
315storage space, as it will be automatically allocated, if necessary.
316@param lambda Corresponds to \f$\lambda\f$ in the formulas above. As it is enlarged, the smooth
317(blurred) images are treated more favorably than detailed (but maybe more noised) ones. Roughly
318speaking, as it becomes smaller, the result will be more blur but more sever outliers will be
319removed.
320@param niters Number of iterations that the algorithm will run. Of course, as more iterations as
321better, but it is hard to quantitatively refine this statement, so just use the default and
322increase it if the results are poor.
323 */
324CV_EXPORTS_W void denoise_TVL1(const std::vector<Mat>& observations,Mat& result, double lambda=1.0, int niters=30);
325
326//! @} photo_denoise
327
328//! @addtogroup photo_hdr
329//! @{
330
331enum { LDR_SIZE = 256 };
332
333/** @brief Base class for tonemapping algorithms - tools that are used to map HDR image to 8-bit range.
334 */
335class CV_EXPORTS_W Tonemap : public Algorithm
336{
337public:
338 /** @brief Tonemaps image
339
340 @param src source image - CV_32FC3 Mat (float 32 bits 3 channels)
341 @param dst destination image - CV_32FC3 Mat with values in [0, 1] range
342 */
343 CV_WRAP virtual void process(InputArray src, OutputArray dst) = 0;
344
345 CV_WRAP virtual float getGamma() const = 0;
346 CV_WRAP virtual void setGamma(float gamma) = 0;
347};
348
349/** @brief Creates simple linear mapper with gamma correction
350
351@param gamma positive value for gamma correction. Gamma value of 1.0 implies no correction, gamma
352equal to 2.2f is suitable for most displays.
353Generally gamma \> 1 brightens the image and gamma \< 1 darkens it.
354 */
355CV_EXPORTS_W Ptr<Tonemap> createTonemap(float gamma = 1.0f);
356
357/** @brief Adaptive logarithmic mapping is a fast global tonemapping algorithm that scales the image in
358logarithmic domain.
359
360Since it's a global operator the same function is applied to all the pixels, it is controlled by the
361bias parameter.
362
363Optional saturation enhancement is possible as described in @cite FL02 .
364
365For more information see @cite DM03 .
366 */
367class CV_EXPORTS_W TonemapDrago : public Tonemap
368{
369public:
370
371 CV_WRAP virtual float getSaturation() const = 0;
372 CV_WRAP virtual void setSaturation(float saturation) = 0;
373
374 CV_WRAP virtual float getBias() const = 0;
375 CV_WRAP virtual void setBias(float bias) = 0;
376};
377
378/** @brief Creates TonemapDrago object
379
380@param gamma gamma value for gamma correction. See createTonemap
381@param saturation positive saturation enhancement value. 1.0 preserves saturation, values greater
382than 1 increase saturation and values less than 1 decrease it.
383@param bias value for bias function in [0, 1] range. Values from 0.7 to 0.9 usually give best
384results, default value is 0.85.
385 */
386CV_EXPORTS_W Ptr<TonemapDrago> createTonemapDrago(float gamma = 1.0f, float saturation = 1.0f, float bias = 0.85f);
387
388
389/** @brief This is a global tonemapping operator that models human visual system.
390
391Mapping function is controlled by adaptation parameter, that is computed using light adaptation and
392color adaptation.
393
394For more information see @cite RD05 .
395 */
396class CV_EXPORTS_W TonemapReinhard : public Tonemap
397{
398public:
399 CV_WRAP virtual float getIntensity() const = 0;
400 CV_WRAP virtual void setIntensity(float intensity) = 0;
401
402 CV_WRAP virtual float getLightAdaptation() const = 0;
403 CV_WRAP virtual void setLightAdaptation(float light_adapt) = 0;
404
405 CV_WRAP virtual float getColorAdaptation() const = 0;
406 CV_WRAP virtual void setColorAdaptation(float color_adapt) = 0;
407};
408
409/** @brief Creates TonemapReinhard object
410
411@param gamma gamma value for gamma correction. See createTonemap
412@param intensity result intensity in [-8, 8] range. Greater intensity produces brighter results.
413@param light_adapt light adaptation in [0, 1] range. If 1 adaptation is based only on pixel
414value, if 0 it's global, otherwise it's a weighted mean of this two cases.
415@param color_adapt chromatic adaptation in [0, 1] range. If 1 channels are treated independently,
416if 0 adaptation level is the same for each channel.
417 */
418CV_EXPORTS_W Ptr<TonemapReinhard>
419createTonemapReinhard(float gamma = 1.0f, float intensity = 0.0f, float light_adapt = 1.0f, float color_adapt = 0.0f);
420
421/** @brief This algorithm transforms image to contrast using gradients on all levels of gaussian pyramid,
422transforms contrast values to HVS response and scales the response. After this the image is
423reconstructed from new contrast values.
424
425For more information see @cite MM06 .
426 */
427class CV_EXPORTS_W TonemapMantiuk : public Tonemap
428{
429public:
430 CV_WRAP virtual float getScale() const = 0;
431 CV_WRAP virtual void setScale(float scale) = 0;
432
433 CV_WRAP virtual float getSaturation() const = 0;
434 CV_WRAP virtual void setSaturation(float saturation) = 0;
435};
436
437/** @brief Creates TonemapMantiuk object
438
439@param gamma gamma value for gamma correction. See createTonemap
440@param scale contrast scale factor. HVS response is multiplied by this parameter, thus compressing
441dynamic range. Values from 0.6 to 0.9 produce best results.
442@param saturation saturation enhancement value. See createTonemapDrago
443 */
444CV_EXPORTS_W Ptr<TonemapMantiuk>
445createTonemapMantiuk(float gamma = 1.0f, float scale = 0.7f, float saturation = 1.0f);
446
447/** @brief The base class for algorithms that align images of the same scene with different exposures
448 */
449class CV_EXPORTS_W AlignExposures : public Algorithm
450{
451public:
452 /** @brief Aligns images
453
454 @param src vector of input images
455 @param dst vector of aligned images
456 @param times vector of exposure time values for each image
457 @param response 256x1 matrix with inverse camera response function for each pixel value, it should
458 have the same number of channels as images.
459 */
460 CV_WRAP virtual void process(InputArrayOfArrays src, std::vector<Mat>& dst,
461 InputArray times, InputArray response) = 0;
462};
463
464/** @brief This algorithm converts images to median threshold bitmaps (1 for pixels brighter than median
465luminance and 0 otherwise) and than aligns the resulting bitmaps using bit operations.
466
467It is invariant to exposure, so exposure values and camera response are not necessary.
468
469In this implementation new image regions are filled with zeros.
470
471For more information see @cite GW03 .
472 */
473class CV_EXPORTS_W AlignMTB : public AlignExposures
474{
475public:
476 CV_WRAP virtual void process(InputArrayOfArrays src, std::vector<Mat>& dst,
477 InputArray times, InputArray response) CV_OVERRIDE = 0;
478
479 /** @brief Short version of process, that doesn't take extra arguments.
480
481 @param src vector of input images
482 @param dst vector of aligned images
483 */
484 CV_WRAP virtual void process(InputArrayOfArrays src, std::vector<Mat>& dst) = 0;
485
486 /** @brief Calculates shift between two images, i. e. how to shift the second image to correspond it with the
487 first.
488
489 @param img0 first image
490 @param img1 second image
491 */
492 CV_WRAP virtual Point calculateShift(InputArray img0, InputArray img1) = 0;
493 /** @brief Helper function, that shift Mat filling new regions with zeros.
494
495 @param src input image
496 @param dst result image
497 @param shift shift value
498 */
499 CV_WRAP virtual void shiftMat(InputArray src, OutputArray dst, const Point shift) = 0;
500 /** @brief Computes median threshold and exclude bitmaps of given image.
501
502 @param img input image
503 @param tb median threshold bitmap
504 @param eb exclude bitmap
505 */
506 CV_WRAP virtual void computeBitmaps(InputArray img, OutputArray tb, OutputArray eb) = 0;
507
508 CV_WRAP virtual int getMaxBits() const = 0;
509 CV_WRAP virtual void setMaxBits(int max_bits) = 0;
510
511 CV_WRAP virtual int getExcludeRange() const = 0;
512 CV_WRAP virtual void setExcludeRange(int exclude_range) = 0;
513
514 CV_WRAP virtual bool getCut() const = 0;
515 CV_WRAP virtual void setCut(bool value) = 0;
516};
517
518/** @brief Creates AlignMTB object
519
520@param max_bits logarithm to the base 2 of maximal shift in each dimension. Values of 5 and 6 are
521usually good enough (31 and 63 pixels shift respectively).
522@param exclude_range range for exclusion bitmap that is constructed to suppress noise around the
523median value.
524@param cut if true cuts images, otherwise fills the new regions with zeros.
525 */
526CV_EXPORTS_W Ptr<AlignMTB> createAlignMTB(int max_bits = 6, int exclude_range = 4, bool cut = true);
527
528/** @brief The base class for camera response calibration algorithms.
529 */
530class CV_EXPORTS_W CalibrateCRF : public Algorithm
531{
532public:
533 /** @brief Recovers inverse camera response.
534
535 @param src vector of input images
536 @param dst 256x1 matrix with inverse camera response function
537 @param times vector of exposure time values for each image
538 */
539 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst, InputArray times) = 0;
540};
541
542/** @brief Inverse camera response function is extracted for each brightness value by minimizing an objective
543function as linear system. Objective function is constructed using pixel values on the same position
544in all images, extra term is added to make the result smoother.
545
546For more information see @cite DM97 .
547 */
548class CV_EXPORTS_W CalibrateDebevec : public CalibrateCRF
549{
550public:
551 CV_WRAP virtual float getLambda() const = 0;
552 CV_WRAP virtual void setLambda(float lambda) = 0;
553
554 CV_WRAP virtual int getSamples() const = 0;
555 CV_WRAP virtual void setSamples(int samples) = 0;
556
557 CV_WRAP virtual bool getRandom() const = 0;
558 CV_WRAP virtual void setRandom(bool random) = 0;
559};
560
561/** @brief Creates CalibrateDebevec object
562
563@param samples number of pixel locations to use
564@param lambda smoothness term weight. Greater values produce smoother results, but can alter the
565response.
566@param random if true sample pixel locations are chosen at random, otherwise they form a
567rectangular grid.
568 */
569CV_EXPORTS_W Ptr<CalibrateDebevec> createCalibrateDebevec(int samples = 70, float lambda = 10.0f, bool random = false);
570
571/** @brief Inverse camera response function is extracted for each brightness value by minimizing an objective
572function as linear system. This algorithm uses all image pixels.
573
574For more information see @cite RB99 .
575 */
576class CV_EXPORTS_W CalibrateRobertson : public CalibrateCRF
577{
578public:
579 CV_WRAP virtual int getMaxIter() const = 0;
580 CV_WRAP virtual void setMaxIter(int max_iter) = 0;
581
582 CV_WRAP virtual float getThreshold() const = 0;
583 CV_WRAP virtual void setThreshold(float threshold) = 0;
584
585 CV_WRAP virtual Mat getRadiance() const = 0;
586};
587
588/** @brief Creates CalibrateRobertson object
589
590@param max_iter maximal number of Gauss-Seidel solver iterations.
591@param threshold target difference between results of two successive steps of the minimization.
592 */
593CV_EXPORTS_W Ptr<CalibrateRobertson> createCalibrateRobertson(int max_iter = 30, float threshold = 0.01f);
594
595/** @brief The base class algorithms that can merge exposure sequence to a single image.
596 */
597class CV_EXPORTS_W MergeExposures : public Algorithm
598{
599public:
600 /** @brief Merges images.
601
602 @param src vector of input images
603 @param dst result image
604 @param times vector of exposure time values for each image
605 @param response 256x1 matrix with inverse camera response function for each pixel value, it should
606 have the same number of channels as images.
607 */
608 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst,
609 InputArray times, InputArray response) = 0;
610};
611
612/** @brief The resulting HDR image is calculated as weighted average of the exposures considering exposure
613values and camera response.
614
615For more information see @cite DM97 .
616 */
617class CV_EXPORTS_W MergeDebevec : public MergeExposures
618{
619public:
620 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst,
621 InputArray times, InputArray response) CV_OVERRIDE = 0;
622 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst, InputArray times) = 0;
623};
624
625/** @brief Creates MergeDebevec object
626 */
627CV_EXPORTS_W Ptr<MergeDebevec> createMergeDebevec();
628
629/** @brief Pixels are weighted using contrast, saturation and well-exposedness measures, than images are
630combined using laplacian pyramids.
631
632The resulting image weight is constructed as weighted average of contrast, saturation and
633well-exposedness measures.
634
635The resulting image doesn't require tonemapping and can be converted to 8-bit image by multiplying
636by 255, but it's recommended to apply gamma correction and/or linear tonemapping.
637
638For more information see @cite MK07 .
639 */
640class CV_EXPORTS_W MergeMertens : public MergeExposures
641{
642public:
643 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst,
644 InputArray times, InputArray response) CV_OVERRIDE = 0;
645 /** @brief Short version of process, that doesn't take extra arguments.
646
647 @param src vector of input images
648 @param dst result image
649 */
650 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst) = 0;
651
652 CV_WRAP virtual float getContrastWeight() const = 0;
653 CV_WRAP virtual void setContrastWeight(float contrast_weiht) = 0;
654
655 CV_WRAP virtual float getSaturationWeight() const = 0;
656 CV_WRAP virtual void setSaturationWeight(float saturation_weight) = 0;
657
658 CV_WRAP virtual float getExposureWeight() const = 0;
659 CV_WRAP virtual void setExposureWeight(float exposure_weight) = 0;
660};
661
662/** @brief Creates MergeMertens object
663
664@param contrast_weight contrast measure weight. See MergeMertens.
665@param saturation_weight saturation measure weight
666@param exposure_weight well-exposedness measure weight
667 */
668CV_EXPORTS_W Ptr<MergeMertens>
669createMergeMertens(float contrast_weight = 1.0f, float saturation_weight = 1.0f, float exposure_weight = 0.0f);
670
671/** @brief The resulting HDR image is calculated as weighted average of the exposures considering exposure
672values and camera response.
673
674For more information see @cite RB99 .
675 */
676class CV_EXPORTS_W MergeRobertson : public MergeExposures
677{
678public:
679 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst,
680 InputArray times, InputArray response) CV_OVERRIDE = 0;
681 CV_WRAP virtual void process(InputArrayOfArrays src, OutputArray dst, InputArray times) = 0;
682};
683
684/** @brief Creates MergeRobertson object
685 */
686CV_EXPORTS_W Ptr<MergeRobertson> createMergeRobertson();
687
688//! @} photo_hdr
689
690//! @addtogroup photo_decolor
691//! @{
692
693/** @brief Transforms a color image to a grayscale image. It is a basic tool in digital printing, stylized
694black-and-white photograph rendering, and in many single channel image processing applications
695@cite CL12 .
696
697@param src Input 8-bit 3-channel image.
698@param grayscale Output 8-bit 1-channel image.
699@param color_boost Output 8-bit 3-channel image.
700
701This function is to be applied on color images.
702 */
703CV_EXPORTS_W void decolor( InputArray src, OutputArray grayscale, OutputArray color_boost);
704
705//! @} photo_decolor
706
707//! @addtogroup photo_clone
708//! @{
709
710
711//! Flags for the seamlessClone algorithm
712enum SeamlessCloneFlags
713{
714 /**
715 @brief Normal seamless cloning.
716 This method is ideal for inserting objects with complex outlines into a new background.
717 It preserves the original appearance and lighting of the inserted object, ensuring a natural blend.
718 */
719 NORMAL_CLONE = 1,
720
721 /**
722 @brief Mixed seamless cloning.
723 This method addresses cases where simple color-based selection or alpha masking is time-consuming
724 and may result in undesirable halos. By combining structure from the source and texture from the
725 destination, mixed seamless cloning is highly effective, even with loosely defined selections.
726 */
727 MIXED_CLONE = 2,
728
729 /**
730 @brief Monochrome transfer cloning.
731 This method allows users to replace specific features of an object, such as grayscale textures
732 or patterns, with alternative features. It is particularly useful for artistic effects or
733 targeted object modifications.
734 */
735 MONOCHROME_TRANSFER = 3,
736
737 /**
738 @brief Enhanced normal seamless cloning.
739 Similar to `NORMAL_CLONE`, but with an advanced approach to ROI (Region of Interest) calculation.
740 This mode processes a larger source region by considering the entire mask area instead of only
741 the bounding rectangle of non-zero pixels.
742 */
743 NORMAL_CLONE_WIDE = 9,
744
745 /**
746 @brief Enhanced mixed seamless cloning.
747 Similar to `MIXED_CLONE`, but with an advanced approach to ROI (Region of Interest) calculation.
748 This mode processes a larger source region by considering the entire mask area instead of only
749 the bounding rectangle of non-zero pixels.
750 */
751 MIXED_CLONE_WIDE = 10,
752
753 /**
754 @brief Enhanced monochrome transfer cloning.
755 Similar to `MONOCHROME_TRANSFER`, but with an advanced approach to ROI (Region of Interest) calculation.
756 This mode processes a larger source region by considering the entire mask area instead of only
757 the bounding rectangle of non-zero pixels.
758 */
759 MONOCHROME_TRANSFER_WIDE = 11
760};
761
762
763/** @example samples/cpp/tutorial_code/photo/seamless_cloning/cloning_demo.cpp
764An example using seamlessClone function
765*/
766/** @brief Performs seamless cloning to blend a region from a source image into a destination image.
767This function is designed for local image editing, allowing changes restricted to a region
768(manually selected as the ROI) to be applied effortlessly and seamlessly. These changes can
769range from slight distortions to complete replacement by novel content @cite PM03.
770
771@param src The source image (8-bit 3-channel), from which a region will be blended into the destination.
772@param dst The destination image (8-bit 3-channel), where the src image will be blended.
773@param mask A binary mask (8-bit, 1, 3, or 4-channel) specifying the region in the source image to blend.
774Non-zero pixels indicate the region to be blended. If an empty Mat is provided, a mask with
775all non-zero pixels is created internally.
776@param p The point where the center of the src image is placed in the dst image.
777@param blend The output image that stores the result of the seamless cloning. It has the same size and type as `dst`.
778@param flags Flags that control the type of cloning method, can take values of `cv::SeamlessCloneFlags`.
779 */
780CV_EXPORTS_W void seamlessClone( InputArray src, InputArray dst, InputArray mask, Point p,
781 OutputArray blend, int flags);
782
783/** @brief Given an original color image, two differently colored versions of this image can be mixed
784seamlessly.
785
786@param src Input 8-bit 3-channel image.
787@param mask Input 8-bit 1 or 3-channel image.
788@param dst Output image with the same size and type as src .
789@param red_mul R-channel multiply factor.
790@param green_mul G-channel multiply factor.
791@param blue_mul B-channel multiply factor.
792
793Multiplication factor is between .5 to 2.5.
794 */
795CV_EXPORTS_W void colorChange(InputArray src, InputArray mask, OutputArray dst, float red_mul = 1.0f,
796 float green_mul = 1.0f, float blue_mul = 1.0f);
797
798/** @brief Applying an appropriate non-linear transformation to the gradient field inside the selection and
799then integrating back with a Poisson solver, modifies locally the apparent illumination of an image.
800
801@param src Input 8-bit 3-channel image.
802@param mask Input 8-bit 1 or 3-channel image.
803@param dst Output image with the same size and type as src.
804@param alpha Value ranges between 0-2.
805@param beta Value ranges between 0-2.
806
807This is useful to highlight under-exposed foreground objects or to reduce specular reflections.
808 */
809CV_EXPORTS_W void illuminationChange(InputArray src, InputArray mask, OutputArray dst,
810 float alpha = 0.2f, float beta = 0.4f);
811
812/** @brief By retaining only the gradients at edge locations, before integrating with the Poisson solver, one
813washes out the texture of the selected region, giving its contents a flat aspect. Here Canny Edge %Detector is used.
814
815@param src Input 8-bit 3-channel image.
816@param mask Input 8-bit 1 or 3-channel image.
817@param dst Output image with the same size and type as src.
818@param low_threshold %Range from 0 to 100.
819@param high_threshold Value \> 100.
820@param kernel_size The size of the Sobel kernel to be used.
821
822@note
823The algorithm assumes that the color of the source image is close to that of the destination. This
824assumption means that when the colors don't match, the source image color gets tinted toward the
825color of the destination image.
826 */
827CV_EXPORTS_W void textureFlattening(InputArray src, InputArray mask, OutputArray dst,
828 float low_threshold = 30, float high_threshold = 45,
829 int kernel_size = 3);
830
831//! @} photo_clone
832
833//! @addtogroup photo_render
834//! @{
835
836//! Edge preserving filters
837enum
838{
839 RECURS_FILTER = 1, //!< Recursive Filtering
840 NORMCONV_FILTER = 2 //!< Normalized Convolution Filtering
841};
842
843/** @brief Filtering is the fundamental operation in image and video processing. Edge-preserving smoothing
844filters are used in many different applications @cite EM11 .
845
846@param src Input 8-bit 3-channel image.
847@param dst Output 8-bit 3-channel image.
848@param flags Edge preserving filters: cv::RECURS_FILTER or cv::NORMCONV_FILTER
849@param sigma_s %Range between 0 to 200.
850@param sigma_r %Range between 0 to 1.
851 */
852CV_EXPORTS_W void edgePreservingFilter(InputArray src, OutputArray dst, int flags = 1,
853 float sigma_s = 60, float sigma_r = 0.4f);
854
855/** @brief This filter enhances the details of a particular image.
856
857@param src Input 8-bit 3-channel image.
858@param dst Output image with the same size and type as src.
859@param sigma_s %Range between 0 to 200.
860@param sigma_r %Range between 0 to 1.
861 */
862CV_EXPORTS_W void detailEnhance(InputArray src, OutputArray dst, float sigma_s = 10,
863 float sigma_r = 0.15f);
864
865/** @example samples/cpp/tutorial_code/photo/non_photorealistic_rendering/npr_demo.cpp
866An example using non-photorealistic line drawing functions
867*/
868/** @brief Pencil-like non-photorealistic line drawing
869
870@param src Input 8-bit 3-channel image.
871@param dst1 Output 8-bit 1-channel image.
872@param dst2 Output image with the same size and type as src.
873@param sigma_s %Range between 0 to 200.
874@param sigma_r %Range between 0 to 1.
875@param shade_factor %Range between 0 to 0.1.
876 */
877CV_EXPORTS_W void pencilSketch(InputArray src, OutputArray dst1, OutputArray dst2,
878 float sigma_s = 60, float sigma_r = 0.07f, float shade_factor = 0.02f);
879
880/** @brief Stylization aims to produce digital imagery with a wide variety of effects not focused on
881photorealism. Edge-aware filters are ideal for stylization, as they can abstract regions of low
882contrast while preserving, or enhancing, high-contrast features.
883
884@param src Input 8-bit 3-channel image.
885@param dst Output image with the same size and type as src.
886@param sigma_s %Range between 0 to 200.
887@param sigma_r %Range between 0 to 1.
888 */
889CV_EXPORTS_W void stylization(InputArray src, OutputArray dst, float sigma_s = 60,
890 float sigma_r = 0.45f);
891
892//! @} photo_render
893
894//! @} photo
895
896} // cv
897
898#endif
899

source code of opencv/modules/photo/include/opencv2/photo.hpp