From ed0828d0a81888db089a3546a941b7c52d417612 Mon Sep 17 00:00:00 2001 From: Fedor Morozov Date: Thu, 1 Aug 2013 15:34:03 +0400 Subject: [PATCH] New HDR documentation --- modules/photo/doc/hdr_imaging.rst | 337 +++++++++++++++++++++--------- 1 file changed, 241 insertions(+), 96 deletions(-) diff --git a/modules/photo/doc/hdr_imaging.rst b/modules/photo/doc/hdr_imaging.rst index a9fdb4cced..94c544629e 100644 --- a/modules/photo/doc/hdr_imaging.rst +++ b/modules/photo/doc/hdr_imaging.rst @@ -3,114 +3,259 @@ HDR imaging .. highlight:: cpp -makeHDR ------------ -Creates HDR image from a set of bracketed exposures using algorithm by Debevec and Malik. +This section describes high dynamic range imaging algorithms, namely tonemapping, exposure alignment, camera calibration with multiple exposures and exposure fusion. -"Recovering High Dynamic Range Radiance Maps from Photographs", Debevec, Malik, 1997 +Tonemap +------------- +.. ocv:class:: Tonemap : public Algorithm -.. ocv:function:: void makeHDR(InputArrayOfArrays srcImgs, const std::vector& expTimes, OutputArray dst, bool align = false) - - :param src_imgs: vector of 8-bit 3-channel images +The base class for tonemapping algorithms - tools, that are used to map HDR image to 8-bit range. + +Tonemap::process +----------------------- +Tonemaps image + +.. ocv:function:: void Tonemap::process(InputArray src, OutputArray dst) + :param src: source image - 32-bit 3-channel Mat + :param dst: destination image - 32-bit 3-channel Mat with values in [0, 1] range + +TonemapLinear +-------- +.. ocv:class:: TonemapLinear : public Tonemap + +Simple linear mapper with gamma correction. + +createTonemapLinear +------------------ +Creates TonemapLinear object + +.. ocv:function:: Ptr createTonemapLinear(float gamma = 1.0f); + + :param gamma: gamma value for gamma correction - :param exp_times: exposure times for each of source images - - :param dst: output image - - :param align: if true, images are first aligned using median threshold bitmap algorithm. See :ocv:func:`getExpShift`. - -tonemap ------------ -Tonemaps image. +TonemapDrago +-------- +.. ocv:class:: TonemapDrago : public Tonemap -.. ocv:function:: tonemap(InputArray src, OutputArray dst, int algorithm, const std::vector& params = std::vector()) - - :param src: input HDR image +"Adaptive Logarithmic Mapping For Displaying HighContrast Scenes", Drago et al. + +createTonemapDrago +------------------ +Creates TonemapDrago object + +.. ocv:function:: Ptr createTonemapDrago(float gamma = 1.0f, float bias = 0.85f); + + :param gamma: gamma value for gamma correction - :param dst: floating-point image in [0; 1] range - - :param algorithm: - * TONEMAP_LINEAR - simple linear mapping - - * TONEMAP_DRAGO - "Adaptive Logarithmic Mapping For Displaying HighContrast Scenes", Drago et al., 2003 - - * TONEMAP_REINHARD - "Dynamic Range Reduction Inspired by Photoreceptor Physiology", Reinhard, Devlin, 2005 - - * TONEMAP_DURAND - "Fast Bilateral Filtering for the Display of High-Dynamic-Range Images", Durand, Dorsey, 2002 - - :param params: vector of parameters for specified algorithm. - If some parameters are missing default values are used. - The first element is gamma value for gamma correction. - - * TONEMAP_LINEAR: - - No parameters. - - * TONEMAP_DRAGO: - - params[1] - value for bias function. Range [0.7, 0.9], default 0.85. - - * TONEMAP_REINHARD: - - params[1] - result intensity. Range [-8, 8], default 0. - - params[2] - chromatic adaptation. Range [0, 1], default 0. - - params[3] - light adaptation. Range [0, 1], default 0; - - * TONEMAP_DURAND: - - params[1] - result contrast on logarithmic scale. - - params[2] - bilateral filter sigma in the color space. - - params[3] - bilateral filter sigma in the coordinate space. - -exposureFusion ------------ -Fuses a bracketed exposure sequence into a single image without converting to HDR first. + :param bias: value for bias function in [0, 1] range + +TonemapDurand +-------- +.. ocv:class:: TonemapDurand : public Tonemap -"Exposure Fusion", Mertens et al., 2007 +"Fast Bilateral Filtering for the Display of High-Dynamic-Range Images", Durand, Dorsey, 2002 -.. ocv:function:: exposureFusion(InputArrayOfArrays src_imgs, OutputArray dst, bool align = false, float wc = 1, float ws = 1, float we = 0) - - :param src_imgs: vector of 8-bit 3-channel images - - :param dst: output image. Although it's a floating-point image tonemapping is not necessary. - - :param align: if true, images are first aligned using median threshold bitmap algorithm. See :ocv:func:`getExpShift`. - - :param wc: contrast factor weight - - :param ws: saturation factor weight - - :param we: well-exposedness factor weight - -getExpShift ------------ -Calculates translation vector that can be used to align img1 with img0. -Uses median threshold bitmap algorithm by Ward. +This implementation uses regular bilateral filter from opencv. + +createTonemapDurand +------------------ +Creates TonemapDurand object + +.. ocv:function:: Ptr createTonemapDurand(float gamma = 1.0f, float contrast = 4.0f, float sigma_space = 2.0f, float sigma_color = 2.0f); + + :param gamma: gamma value for gamma correction + + :param contrast: resulting contrast on logarithmic scale + + :param sigma_space: filter sigma in the color space + + :param sigma_color: filter sigma in the coordinate space + +TonemapReinhardDevlin +-------- +.. ocv:class:: TonemapReinhardDevlin : public Tonemap + +"Dynamic Range Reduction Inspired by Photoreceptor Physiology", Reinhard, Devlin, 2005 + +createTonemapReinhardDevlin +------------------ +Creates TonemapReinhardDevlin object + +.. ocv:function:: Ptr createTonemapReinhardDevlin(float gamma = 1.0f, float intensity = 0.0f, float light_adapt = 1.0f, float color_adapt = 0.0f) + + :param gamma: gamma value for gamma correction + + :param intensity: result intensity. Range in [-8, 8] range + + :param light_adapt: light adaptation in [0, 1] range. If 1 adaptation is based on pixel value, if 0 it's global + + :param color_adapt: chromatic adaptation in [0, 1] range. If 1 channels are treated independently, if 0 adaptation level is the same for each channel + +ExposureAlign +------------- +.. ocv:class:: ExposureAlign : public Algorithm + +The base class for algorithms that align images of the same scene with different exposures + +ExposureAlign::process +----------------------- +Aligns images + +.. ocv:function:: void ExposureAlign::process(InputArrayOfArrays src, OutputArrayOfArrays dst, const std::vector& times, InputArray response) + + :param src: vector of input images + + :param dst: vector of aligned images + + :param times: vector of exposure time values for each image + + :param response: matrix with camera response, one column per channel + +AlignMTB +-------- +.. ocv:class:: AlignMTB : public ExposureAlign "Fast, Robust Image Registration for Compositing High Dynamic Range Photographs from Handheld Exposures", Ward, 2003 -.. ocv:function:: getExpShift(InputArray img0, InputArray img1, int max_bits = 6, int exclude_range = 4) +This algorithm does not use exposure values and camera response, new image regions are filled with zeros. + +AlignMTB::process +----------------------- +Short version of process, that doesn't take extra arguments. + +.. ocv:function:: void AlignMTB::process(InputArrayOfArrays src, OutputArrayOfArrays dst) + + :param src: vector of input images - :param img0: 8-bit 1-channel image + :param dst: vector of aligned images + +AlignMTB::calculateShift +----------------------- +Calculates shift between two images. + +.. ocv:function:: void AlignMTB::calculateShift(InputArray img0, InputArray img1, Point& shift) + + :param img0: first image - :param img1: 8-bit 1-channel image - - :param max_bits: logarithm to the base 2 of maximal shift in each dimension - - :param exclude_range: range value for exclusion bitmap. Refer to the article. - -shiftMat ------------ -Shifts image filling the new regions with zeros. + :param img1: second image + + :param shift: how to shift the second image to correspond it with the first -.. ocv:function:: shiftMat(InputArray src, Point shift, OutputArray dst) - - :param src: input image +AlignMTB::shiftMat +----------------------- +Gelper function, that shift Mat filling new regions with zeros. + +.. ocv:function:: void AlignMTB::shiftMat(InputArray src, OutputArray dst, const Point shift) + + :param src: input image + + :param dst: result image + + :param shift: shift value + +createAlignMTB +------------------ +Creates AlignMTB object + +.. ocv:function:: Ptr createAlignMTB(int max_bits = 6, int exclude_range = 4) + + :param max_bits: logarithm to the base 2 of maximal shift in each dimension + + :param exclude_range: range for exclusion bitmap + +ExposureCalibrate +------------- +.. ocv:class:: ExposureCalibrate : public Algorithm + +The base class for camera response calibration algorithms. + +ExposureCalibrate::process +----------------------- +Recovers camera response. + +.. ocv:function:: void ExposureCalibrate::process(InputArrayOfArrays src, OutputArray dst, std::vector& times) + + :param src: vector of input images + + :param dst: matrix with calculated camera response, one column per channel + + :param times: vector of exposure time values for each image + +CalibrateDebevec +-------- +.. ocv:class:: CalibrateDebevec : public ExposureCalibrate + +"Recovering High Dynamic Range Radiance Maps from Photographs", Debevec, Malik, 1997 + +createCalibrateDebevec +------------------ +Creates CalibrateDebevec object + +.. ocv:function:: Ptr createCalibrateDebevec(int samples = 50, float lambda = 10.0f) + + :param samples: number of pixel locations to use + + :param lambda: smoothness term weight + +ExposureMerge +------------- +.. ocv:class:: ExposureMerge : public Algorithm + +The base class algorithms that can merge exposure sequence to a single image. + +ExposureMerge::process +----------------------- +Merges images. + +.. ocv:function:: void process(InputArrayOfArrays src, OutputArray dst, const std::vector& times, InputArray response) + + :param src: vector of input images - :param shift: shift vector + :param dst: result image + + :param times: vector of exposure time values for each image + + :param response: matrix with camera response, one column per channel + +MergeDebevec +-------- +.. ocv:class:: MergeDebevec : public ExposureMerge + +"Recovering High Dynamic Range Radiance Maps from Photographs", Debevec, Malik, 1997 + +createMergeDebevec +------------------ +Creates MergeDebevec object + +.. ocv:function:: Ptr createMergeDebevec(); + +MergeMertens +-------- +.. ocv:class:: MergeMertens : public ExposureMerge + +"Exposure Fusion", Mertens et al., 2007 + +The resulting image doesn't require tonemapping and can be converted to 8-bit image by multiplying by 255. + +MergeMertens::process +----------------------- +Short version of process, that doesn't take extra arguments. + +.. ocv:function:: void MergeMertens::process(InputArrayOfArrays src, OutputArray dst) + + :param src: vector of input images - :param dst: output image \ No newline at end of file + :param dst: result image + + +createMergeMertens +------------------ +Creates MergeMertens object + +.. ocv:function:: Ptr createMergeMertens(float contrast_weight = 1.0f, float saturation_weight = 1.0f, float exposure_weight = 0.0f) + + :param contrast_weight: contrast factor weight + + :param saturation_weight: saturation factor weight + + :param exposure_weight: well-exposedness factor weight \ No newline at end of file