reconstruct_height_field_from_gradient — Reconstruct a surface from surface gradients.
reconstruct_height_field_from_gradient reconstructs a surface from the surface gradients that are given in Gradient. The surface is returned as a height field, i.e., an image in which the gray value of each image point corresponds to a relative height.
The reconstruction is done by integrating the gradients by different algorithms that can be selected in the parameter ReconstructionMethod. Because gradient fields are typically non-integrable due to noise, the various algorithms return a solution in a least-squares sense. The algorithms differ in the way how they model the boundary condition. Currently three algorithms are supported: 'fft_cyclic', 'rft_cyclic' and 'poisson'.
Reconstruction with Fast Fourier transforms
The variants 'fft_cyclic' and 'rft_cyclic' assume that the image function is cyclic at the boundaries. Note that due to the assumed cyclic image function artefacts may occur at the image boundaries. Thus, in most cases, we recommend to use the 'poisson' algorithm instead.
The difference between 'fft_cyclic' and 'rft_cyclic' is that the rft version has faster processing times and requires less memory than the fft version. While theoretically fft and rft should return the same result, the fft version is numerically slightly more accurate. As reconstruct_height_field_from_gradient internally uses a fast Fourier transform, the run time of the operator can be influenced by a previous call to optimize_fft_speed or optimize_rft_speed, respectively.
Reconstruction according to Poisson
The 'poisson' algorithm assumes that the image has constant gradients at the image border. In most cases, it is the recommended reconstruction method for reconstruct_height_field_from_gradient. Its run time can only be optimized by setting GenParamName to 'optimize_speed' and GenParamValue to 'standard', 'patient', or 'exhaustive'. These parameters are described in more detail with the description of optimize_fft_speed.
Note that by default, the 'poisson' algorithm uses a cache that depends on the image size and that speeds up the reconstruction significantly, provided that all images have the same size. The cache is allocated at the first time when the 'poisson' algorithm is called. Therefore the first call always takes longer than subsequent calls. The additionally needed memory corresponds to the memory needed for the specific size of one image. Please note that when calling the operator with different image sizes, the cache needs to be reallocated, which leads to a longer processing time. In this case it may be preferable to not use the cache. To switch off the caching, you must set the parameter GenParamName to 'caching' and the parameter GenParamValue to 'no_cache'. The cache can explicitly be deallocated by setting GenParamName to 'caching' and GenParamValue to 'free_cache'. However, in the majority of cases, we recommend to use the cache, i.e., to use the default setting for the parameter 'caching'.
Saving and loading optimization parameters
The optimization parameters for all algorithms can be saved and loaded by write_fft_optimization_data and read_fft_optimization_data.
Non obvious applications
Please note that the operator reconstruct_height_field_from_gradient has various non-obvious applications, especially in the field called gradient domain manipulation technique. In many applications, the gradient values that are passed as input to the operator do not have the semantics of surface gradients (i.e., the first derivatives of the height values), but are rather the first derivatives of other kinds of parameters, typically gray values (then, the gradients have the semantics of gray value edges). When processing these gradient images by various means, e.g., by adding or subtracting images, or by a filtering, the original gradient values are altered and the subsequent call to reconstruct_height_field_from_gradient delivers a modified image, in which, e.g., unwanted edges are removed or the contrast has been changed locally. Typical applications are noise removal, seamless fusion of images, or high dynamic range compression.
The gradient field of the image.
Reconstructed height field.
Type of the reconstruction method.
Default value: 'poisson'
List of values: 'fft_cyclic', 'rft_cyclic', 'poisson'
Names of the generic parameters.
Default value: 
List of values: 'optimize_speed', 'caching'
Values of the generic parameters.
Default value: 
List of values: 'standard', 'patient', 'exhaustive', 'use_cache', 'no_cache', 'free_cache'
If the parameters are valid reconstruct_height_field_from_gradient returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.