ClassesClasses | | Operators

reconstruct_height_field_from_gradientT_reconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient (Operator)

Name

reconstruct_height_field_from_gradientT_reconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient — Reconstruct a surface from surface gradients.

Signature

reconstruct_height_field_from_gradient(Gradient : HeightField : ReconstructionMethod, GenParamName, GenParamValue : )

Herror T_reconstruct_height_field_from_gradient(const Hobject Gradient, Hobject* HeightField, const Htuple ReconstructionMethod, const Htuple GenParamName, const Htuple GenParamValue)

void ReconstructHeightFieldFromGradient(const HObject& Gradient, HObject* HeightField, const HTuple& ReconstructionMethod, const HTuple& GenParamName, const HTuple& GenParamValue)

HImage HImage::ReconstructHeightFieldFromGradient(const HString& ReconstructionMethod, const HTuple& GenParamName, const HTuple& GenParamValue) const

HImage HImage::ReconstructHeightFieldFromGradient(const char* ReconstructionMethod, const HTuple& GenParamName, const HTuple& GenParamValue) const

static void HOperatorSet.ReconstructHeightFieldFromGradient(HObject gradient, out HObject heightField, HTuple reconstructionMethod, HTuple genParamName, HTuple genParamValue)

HImage HImage.ReconstructHeightFieldFromGradient(string reconstructionMethod, HTuple genParamName, HTuple genParamValue)

Description

reconstruct_height_field_from_gradientreconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient reconstructs a surface from the surface gradients that are given in GradientGradientGradientGradientgradient. 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 ReconstructionMethodReconstructionMethodReconstructionMethodReconstructionMethodreconstructionMethod. 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'"fft_cyclic""fft_cyclic""fft_cyclic""fft_cyclic", 'rft_cyclic'"rft_cyclic""rft_cyclic""rft_cyclic""rft_cyclic" and 'poisson'"poisson""poisson""poisson""poisson".

Reconstruction with Fast Fourier transforms

The variants 'fft_cyclic'"fft_cyclic""fft_cyclic""fft_cyclic""fft_cyclic" and 'rft_cyclic'"rft_cyclic""rft_cyclic""rft_cyclic""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'"poisson""poisson""poisson""poisson" algorithm instead.

The difference between 'fft_cyclic'"fft_cyclic""fft_cyclic""fft_cyclic""fft_cyclic" and 'rft_cyclic'"rft_cyclic""rft_cyclic""rft_cyclic""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_gradientreconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient internally uses a fast Fourier transform, the run time of the operator can be influenced by a previous call to optimize_fft_speedoptimize_fft_speedOptimizeFftSpeedOptimizeFftSpeedOptimizeFftSpeed or optimize_rft_speedoptimize_rft_speedOptimizeRftSpeedOptimizeRftSpeedOptimizeRftSpeed, respectively.

Reconstruction according to Poisson

The 'poisson'"poisson""poisson""poisson""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_gradientreconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient. Its run time can only be optimized by setting GenParamNameGenParamNameGenParamNameGenParamNamegenParamName to 'optimize_speed'"optimize_speed""optimize_speed""optimize_speed""optimize_speed" and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue to 'standard'"standard""standard""standard""standard", 'patient'"patient""patient""patient""patient", or 'exhaustive'"exhaustive""exhaustive""exhaustive""exhaustive". These parameters are described in more detail with the description of optimize_fft_speedoptimize_fft_speedOptimizeFftSpeedOptimizeFftSpeedOptimizeFftSpeed.

Note that by default, the 'poisson'"poisson""poisson""poisson""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'"poisson""poisson""poisson""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 GenParamNameGenParamNameGenParamNameGenParamNamegenParamName to 'caching'"caching""caching""caching""caching" and the parameter GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue to 'no_cache'"no_cache""no_cache""no_cache""no_cache". The cache can explicitly be deallocated by setting GenParamNameGenParamNameGenParamNameGenParamNamegenParamName to 'caching'"caching""caching""caching""caching" and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue to 'free_cache'"free_cache""free_cache""free_cache""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'"caching""caching""caching""caching".

Saving and loading optimization parameters

The optimization parameters for all algorithms can be saved and loaded by write_fft_optimization_datawrite_fft_optimization_dataWriteFftOptimizationDataWriteFftOptimizationDataWriteFftOptimizationData and read_fft_optimization_dataread_fft_optimization_dataReadFftOptimizationDataReadFftOptimizationDataReadFftOptimizationData.

Non obvious applications

Please note that the operator reconstruct_height_field_from_gradientreconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient 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_gradientreconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient 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.

Attention

reconstruct_height_field_from_gradient takes into account the values of all pixels in GradientGradientGradientGradientgradient, not only the values within its domain. If GradientGradientGradientGradientgradient does not have a full domain, one could cut out the relevant square part of the gradient field and generate a smaller image with full domain.

Execution Information

Parameters

GradientGradientGradientGradientgradient (input_object)  singlechannelimage objectHImageHImageHobject (vector_field)

The gradient field of the image.

HeightFieldHeightFieldHeightFieldHeightFieldheightField (output_object)  image objectHImageHImageHobject * (real)

Reconstructed height field.

ReconstructionMethodReconstructionMethodReconstructionMethodReconstructionMethodreconstructionMethod (input_control)  string HTupleHTupleHtuple (string) (string) (HString) (char*)

Type of the reconstruction method.

Default value: 'poisson' "poisson" "poisson" "poisson" "poisson"

List of values: 'fft_cyclic'"fft_cyclic""fft_cyclic""fft_cyclic""fft_cyclic", 'poisson'"poisson""poisson""poisson""poisson", 'rft_cyclic'"rft_cyclic""rft_cyclic""rft_cyclic""rft_cyclic"

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  string-array HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters.

Default value: []

List of values: 'caching'"caching""caching""caching""caching", 'optimize_speed'"optimize_speed""optimize_speed""optimize_speed""optimize_speed"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  integer-array HTupleHTupleHtuple (integer / real / string) (int / long / double / string) (Hlong / double / HString) (Hlong / double / char*)

Values of the generic parameters.

Default value: []

List of values: 'exhaustive'"exhaustive""exhaustive""exhaustive""exhaustive", 'free_cache'"free_cache""free_cache""free_cache""free_cache", 'no_cache'"no_cache""no_cache""no_cache""no_cache", 'patient'"patient""patient""patient""patient", 'standard'"standard""standard""standard""standard", 'use_cache'"use_cache""use_cache""use_cache""use_cache"

Result

If the parameters are valid reconstruct_height_field_from_gradientreconstruct_height_field_from_gradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradientReconstructHeightFieldFromGradient returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.

References

M. Kazhdan, M. Bolitho, and H. Hoppe: “Poisson Surface Reconstruction.” Symposium on Geometry Processing (June 2006).

Module

3D Metrology


ClassesClasses | | Operators