hdrl_mode.h File Reference

#include "hdrl_mode_defs.h"
#include "hdrl_parameter.h"
#include <cpl.h>

Include dependency graph for hdrl_mode.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
CPL_BEGIN_DECLS cpl_parameterlist *	hdrl_mode_parameter_create_parlist (const char *base_context, const char *prefix, const hdrl_parameter *defaults)
	Create parameters for the mode collapse.
cpl_error_code	hdrl_mode_parameter_parse_parlist (const cpl_parameterlist *parlist, const char *prefix, double *histo_min, double *histo_max, double *bin_size, hdrl_mode_type *method, cpl_size *error_niter)
	parse parameterlist for mode parameters to init corresponding hdrl structure parameters
cpl_error_code	hdrl_mode_clip_image (const cpl_image *source, const double histo_min, const double histo_max, const double bin_size, const hdrl_mode_type method, const cpl_size error_niter, double *mode, double *mode_error, cpl_size *naccepted)
	Compute mode of data.
cpl_error_code	hdrl_mode_clip (cpl_vector *vec, const double histo_min, const double histo_max, const double bin_size, const hdrl_mode_type method, const cpl_size error_niter, double *mode, double *mode_error, cpl_size *naccepted)
	Compute mode of data.

Function Documentation

hdrl_mode_clip()

cpl_error_code hdrl_mode_clip	(	cpl_vector *	vec,
		const double	histo_min,
		const double	histo_max,
		const double	bin_size,
		const hdrl_mode_type	method,
		const cpl_size	error_niter,
		double *	mode,
		double *	mode_error,
		cpl_size *	naccepted
	)

Compute mode of data.

Parameters

	vec	The data for which mode is to be computed.
	histo_min	Min of histogram
	histo_max	Max of histogram
	bin_size	the histogram bin size
	method	the mode computation method
	error_niter	the number of iterations to determine error model
[out]	mode	The mode
[out]	mode_error	The error associated to the mode
[out]	naccepted	the number of good data points

Returns

CPL_ERROR_NONE or the appropriate error code.

The developer provide vec != NULL See also hdrl_mode_clip_image().

hdrl_mode_clip_image()

cpl_error_code hdrl_mode_clip_image	(	const cpl_image *	source,
		const double	histo_min,
		const double	histo_max,
		const double	bin_size,
		const hdrl_mode_type	method,
		const cpl_size	error_niter,
		double *	mode,
		double *	mode_error,
		cpl_size *	naccepted
	)

Compute mode of data.

Parameters

	source	The data for which mode is to be computed.
	histo_min	Min of histogram
	histo_max	Max of histogram
	bin_size	the histogram bin size
	method	the mode computation method
	error_niter	the number of iterations to determine error model
[out]	mode	The mode
[out]	mode_error	The error associated to the mode
[out]	naccepted	the number of bins used to determine mode

Returns

CPL_ERROR_NONE or the appropriate error code.

The developer provide source != NULL

The mode (or modal value) of a distribution of values is defined as the value of the distribution that appears more often (the maximum of the function distribution). This function computes the mode and the associated error for the case of a discrete distribution of points as defined by the input source image.

In the case of a discrete distribution, one can define the modal class'' (the position of the highest peak of the histogram), and themodal frequency" (the value of the highest peak of the histogram), which are related to the mode of the underlying continuous distribution. The values of histo_min/max can be changed to remove outliers or optimise computation time. The value of the modal frequency depends from the chosen bin size used to create the histogram and from statistical noise. Large bin size helps in finding an high and unique modal frequency, but decreases the resolution because the bin is large. A small bin increases the resolution of the modal class but decreases the modal frequency and therefore increases the chance that, because of the statistical noise, the highest peak in the histogram is not related to the mode of the underlying distribution.

The mode can be computed with three different methods:

fit: the distribution function maximum is obtained via a parabolic fit after making some check (that the distribution is sufficiently symmetric)

weight: the distribution function maximum is obtained by an ad hoc weight of the histogram bins adjacent to the maximum. This method is appropriate for point distributions that are not perfectly symmetric.

median: the distribution function maximum is obtained by computing the median of the data points.

The error computation can be computed analytically (if error_miter=0) or using a Montecarlo simulation (if error_miter > 0)

Results depend additionally on following parameters:

bin_size: if bin_size <=0 bin_size is automatically determined. as bin_size = 2. * 3.49 * stdev / pow(size, 1. / 3. ) ; where stdev is a robust estimation of the standard deviation obtained from the MAD of the image

histo_min: if histo_min < histo_max histo_min if histo_min < histo_max else histo_min = is equal min(distribution) - 0.5 * bin_size

histo_max: if histo_min < histo_max histo_max = histo_min + nbin * bin_size else histo_min = is equal max(distribution) + 0.5 * bin_size

hdrl_mode_parameter_create_parlist()

CPL_BEGIN_DECLS cpl_parameterlist * hdrl_mode_parameter_create_parlist	(	const char *	base_context,
		const char *	prefix,
		const hdrl_parameter *	defaults
	)

Create parameters for the mode collapse.

Parameters

base_context	base context of parameter (e.g. recipe name)
prefix	prefix of parameter, may be empty string
defaults	default mode parameters

Returns

The created parameter list Creates a parameterlist containing base_context.prefix.histo_min, base_context.prefix.histo_max, base_context.prefix.bin_size, base_context.prefix.method, base_context.prefix.error_niter

the allocated parameter structure or NULL in case of error The user should make sure that base_context != NULL, prefix != NULL, defaults != NULL

hdrl_mode_parameter_parse_parlist()

cpl_error_code hdrl_mode_parameter_parse_parlist	(	const cpl_parameterlist *	parlist,
		const char *	prefix,
		double *	histo_min,
		double *	histo_max,
		double *	bin_size,
		hdrl_mode_type *	method,
		cpl_size *	error_niter
	)

parse parameterlist for mode parameters to init corresponding hdrl structure parameters

Parameters

parlist	parameter list to parse
prefix	prefix of parameter name
histo_min	minimum value of low pixels to use
histo_max	maximum value of high pixels to be use
bin_size	size of the histogram bin
method	method to use for the mode computation
error_niter	number of iterations to compute the error of the mode

See also

hdrl_mode_clip_get_parlist()

Returns

cpl_error_code

parameterlist should have been created with hdrl_mode_clip_get_parlist or have the same name hierarchy

Developer should make sure that parlist != NULL, prefix != NULL