Files
file	WlzHistogram.c
	Functions for computing and transforming Woolz histograms domains.

Data Structures
struct	_WlzHistogramDomain
	Histograms are Woolz domains and not values as might be expected. Typedef: WlzHistogramDomain. More...

Enumerations
enum	_WlzHistFeature { WLZ_HIST_FEATURE_NONE = (0), WLZ_HIST_FEATURE_PEAK = (1<<0), WLZ_HIST_FEATURE_TROUGH = (1<<1) }
	Features of histograms. Typedef: WlzHistFeature. More...

Functions
WlzObject *	WlzHistogramObj (WlzObject srcObj, int nBins, double binOrigin, double binSize, WlzErrorNum dstErrNum)
	Creates a woolz histogram object (with an int histogram domain) using the given 2D or 3D woolz domain object and histogram parameters. If the requested number of bins is zero then the number of bins, the origin and the bin size will be computed as follows: More...

WlzObject *	WlzHistogramCopy (WlzObject srcHistObj, WlzObjectType dstType, WlzErrorNum dstErrNum)
	Copies the given Woolz histogram object to a new one of the required type. More...

WlzObject *	WlzHistogramRebin (WlzObject srcHistObj, WlzObjectType dstType, int dstMaxBins, int dstNBins, double dstOrigin, double dstBinSize, WlzErrorNum dstErrNum)
	Re-bins the given Woolz histogram object to a new one of the required type, number of bins, origin and bin size. More...

WlzErrorNum	WlzHistogramRsvFilter (WlzObject histObj, WlzRsvFilter flt)
	Applies an infinite impulse response (IIR) filter to the histogram object'c bin values. More...

WlzErrorNum	WlzHistogramConvolve (WlzObject histObj, int krnSz, double krn)
	Convolves the given Woolz histogram object's histogram bin values with the given convolution kernel. More...

WlzErrorNum	WlzHistogramCnvGauss (WlzObject *histObj, double sigma, int deriv)
	Convolves the given Woolz histogram object's histogram bin values with a Gaussian, 1st derivative of Gaussian or 2nd derivative of Gaussian convolution kernel. More...

WlzErrorNum	WlzHistogramRsvGauss (WlzObject *histObj, double sigma, int deriv)
	Uses an infinite impulse response (IIR) filter to convolve the given Woolz histogram object's bin values with a Gaussian, 1st derivative of Gaussian or 2nd derivative of Gaussian. More...

WlzErrorNum	WlzHistogramSmooth (WlzObject *histObj, int width)
	Low pass filters the given Woolz histogram object's histogram bin values by convolving them in the space domain with a Gaussian kernel of the given half height full width. More...

WlzErrorNum	WlzHistogramCummulative (WlzObject *srcHist)
	Modifies the given histogram so that its values are cummulative. More...

WlzErrorNum	WlzHistogramMapValues (WlzObject srcObj, WlzObject mapHistObj, int dither)
	Uses the given mapping histogram with integral bin values to remap the grey values of the given 2D or 3D domain object. The mapping histogram MUST have integral bin values and bins appropriate for all domain object values. More...

WlzErrorNum	WlzHistogramFindPeaks (WlzObject histObj, double sigma, double thresh, int dstFeatSz, int **dstFeat, WlzHistFeature feat)
	Find the peaks and/or troughs of the given histogram. Peaks are found by searching through the 1st derivative (h') of the histogram bin values (h). For a peak. More...

WlzErrorNum	WlzHistogramFitPeaks (WlzObject histObj, int numDbn, double smooth, double thresh, double tol, int dstNumMu, double *dstMu, int dstNumSigma, double *dstSigma, int dstNumAlpha, double *dstAlpha, double dstLL)
	Fit the given Woolz histogram object's histogram bin values using a mixture of Gaussian distributions. More...

WlzErrorNum	WlzHistogramNorm (WlzObject *histObj, double maxVal)
	Normalise the given Woolz histogram object's histogram bin values to the given range [0-maxVal]. If the given maximum value is 0.0 then the histogram bin values are normalised so that maxVal is equal to the number of bins. More...

int	WlzHistogramBinMax (WlzHistogramDomain *histDom)
	Finds the bin of the histogram domain which has the greatest occupancy. More...

double	WlzHistogramDistance (WlzObject histObj0, WlzObject histObj1, WlzErrorNum *dstErrNum)
	Calculates a distance measure for comparing two histograms. The histogram distance is in the range [0.0 - 1.0] with 1.0 being a perfect match between histograms. The given histograms are not modified. More...

WlzErrorNum	WlzHistogramMatchObj (WlzObject srcObj, WlzObject targetHist, int independentPlanes, int smoothing, double minDist, double maxDist, int dither)
	Modifies the grey values of the given Woolz 2D or 3D domain object so that the resulting object's histogram matches the target histogram object. More...

WlzErrorNum	WlzHistogramEqualiseObj (WlzObject *srcObj, int smoothing, int dither)
	Modifies the grey values of the given Woolz 2D or 3D domain object so that the resulting object's histogram approximates a uniform histogram. If the specified smoothing is non-zero then the objects histogram is smoothed by WlzHistogramSmooth(). More...

Detailed Description

Enumeration Type Documentation

◆ _WlzHistFeature

enum _WlzHistFeature

Features of histograms. Typedef: WlzHistFeature.

Enumerator
WLZ_HIST_FEATURE_NONE	No feature.
WLZ_HIST_FEATURE_PEAK	Histogram peak.
WLZ_HIST_FEATURE_TROUGH	Histogram trough.

Function Documentation

◆ WlzHistogramObj()

WlzObject* WlzHistogramObj	(	WlzObject *	srcObj,
		int	nBins,
		double	binOrigin,
		double	binSize,
		WlzErrorNum *	dstErrNum
	)

Creates a woolz histogram object (with an int histogram domain) using the given 2D or 3D woolz domain object and histogram parameters. If the requested number of bins is zero then the number of bins, the origin and the bin size will be computed as follows:

Returns: New woolz object with histogram domain.

                nBins = ceil(max(g) - min(g) + 1.0)
                binOrigin = min(g)
                binSize = 1.0

Where min(g) and max(g) are the minimum and maximum grey values in the source object.

Parameters

srcObj	Given source object.
nBins	Required number of histogram bins.
binOrigin	Lowest grey value in first histogram bin.
binSize	Grey value range for each histogram bin.
dstErrNum	Destination error pointer.

References _WlzValues::core, _WlzDomain::core, _WlzObject::type, WLZ_2D_DOMAINOBJ, WLZ_DBG, WLZ_DBG_LVL_1, WLZ_EMPTY_OBJ, WLZ_ERR_NONE, WLZ_ERR_OBJECT_NULL, WLZ_ERR_PARAM_DATA, WLZ_ERR_UNSPECIFIED, and WlzMakeEmpty().

Referenced by WlzSplitObj().

◆ WlzHistogramCopy()

WlzObject* WlzHistogramCopy	(	WlzObject *	srcHistObj,
		WlzObjectType	dstType,
		WlzErrorNum *	dstErrNum
	)

Copies the given Woolz histogram object to a new one of the required type.

Returns: Copied Woolz histogram object or NULL on error.

Parameters

srcHistObj	Given histogram object.
dstType	Required type of histogram domain values.
dstErrNum	Destination error pointer, may be NULL.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramRebin()

WlzObject* WlzHistogramRebin	(	WlzObject *	srcHistObj,
		WlzObjectType	dstType,
		int	dstMaxBins,
		int	dstNBins,
		double	dstOrigin,
		double	dstBinSize,
		WlzErrorNum *	dstErrNum
	)

Re-bins the given Woolz histogram object to a new one of the required type, number of bins, origin and bin size.

Returns: Copied Woolz histogram object or NULL on error.

Parameters

srcHistObj	Given histogram object.
dstType	Required type of histogram domain values.
dstMaxBins	Total number of bins to be allocated.
dstNBins	Number of bins to be used in new histogram.
dstOrigin	New histogram origin.
dstBinSize	New histogram bin size.
dstErrNum	Destination error pointer, may be NULL.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramRsvFilter()

WlzErrorNum WlzHistogramRsvFilter	(	WlzObject *	histObj,
		WlzRsvFilter *	flt
	)

Applies an infinite impulse response (IIR) filter to the histogram object'c bin values.

Returns: Woolz error code.

Parameters

histObj	Given histogram object.
flt	IIR filter.

References WLZ_DBG, WLZ_DBG_LVL_1, WLZ_ERR_NONE, and WLZ_ERR_PARAM_NULL.

◆ WlzHistogramConvolve()

WlzErrorNum WlzHistogramConvolve	(	WlzObject *	histObj,
		int	krnSz,
		double *	krn
	)

Convolves the given Woolz histogram object's histogram bin values with the given convolution kernel.

Returns: Woolz error code.

Parameters

histObj	Given histogram object.
krnSz	Kernel size, must be odd.
krn	The convolution kernel.

References ALG_ERR_NONE, WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramCnvGauss()

WlzErrorNum WlzHistogramCnvGauss	(	WlzObject *	histObj,
		double	sigma,
		int	deriv
	)

Convolves the given Woolz histogram object's histogram bin values with a Gaussian, 1st derivative of Gaussian or 2nd derivative of Gaussian convolution kernel.

Returns: Woolz error code.

Parameters

histObj	Given histogram object.
sigma	Sigma value of the Gaussian which is scaled within this function to account for the histogram bin size.
deriv	Derivative must be in range [0-2].

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

Referenced by WlzSplitObj().

◆ WlzHistogramRsvGauss()

WlzErrorNum WlzHistogramRsvGauss	(	WlzObject *	histObj,
		double	sigma,
		int	deriv
	)

Uses an infinite impulse response (IIR) filter to convolve the given Woolz histogram object's bin values with a Gaussian, 1st derivative of Gaussian or 2nd derivative of Gaussian.

Returns: Woolz error code.

Parameters

histObj	Given histogram object.
sigma	Sigma value of the Gaussian which is scaled within this function to account for the histogram bin size.
deriv	Derivative must be in range [0-2].

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

Referenced by WlzHistogramSmooth().

◆ WlzHistogramSmooth()

WlzErrorNum WlzHistogramSmooth	(	WlzObject *	histObj,
		int	width
	)

Low pass filters the given Woolz histogram object's histogram bin values by convolving them in the space domain with a Gaussian kernel of the given half height full width.

Returns: Woolz error code.

Parameters

histObj	Given histogram object.
width	Gaussian kernel half height full width.

References WLZ_DBG, WLZ_DBG_LVL_1, WLZ_DBG_LVL_FN, WLZ_ERR_NONE, and WlzHistogramRsvGauss().

◆ WlzHistogramCummulative()

WlzErrorNum WlzHistogramCummulative ( WlzObject * srcHist )

Modifies the given histogram so that its values are cummulative.

Returns: Woolz error code.

Parameters

srcHist Given histogram object.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramMapValues()

WlzErrorNum WlzHistogramMapValues	(	WlzObject *	srcObj,
		WlzObject *	mapHistObj,
		int	dither
	)

Uses the given mapping histogram with integral bin values to remap the grey values of the given 2D or 3D domain object. The mapping histogram MUST have integral bin values and bins appropriate for all domain object values.

Returns: Woolz error code.

Parameters

srcObj	Given 2D or 3D domain object.
mapHistObj	Mapping histogram.
dither	If non zero then dither mapped values to avoid generating a histogram with a comb appearence.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramFindPeaks()

WlzErrorNum WlzHistogramFindPeaks	(	WlzObject *	histObj,
		double	sigma,
		double	thresh,
		int *	dstFeatSz,
		int **	dstFeat,
		WlzHistFeature	feat
	)

Find the peaks and/or troughs of the given histogram. Peaks are found by searching through the 1st derivative (h') of the histogram bin values (h). For a peak.

Returns: Woolz error code.

                (h'[i - 1] > 0) && (h'[i + 1] < 0) &&
                (h[i] > thresh).

If the first or last histogram bin has the maximum bin occupancy of the histogram it is classified as a peak too.

Parameters

histObj	Given histogram object.
sigma	Gaussian sigma smooth histogram and compute 1st derivative.
thresh	Minimum (smoothed) histogram value at peak, not used for troughs.
dstFeatSz	Destination ptr for the number of peaks/troughs found.
dstFeat	Destination ptr for the array of peak/trough positions (indicies into the histogram bin values). May have dstFeat == NULL on return if dstFeatSz == 0.
feat	Features to find: peaks, troughs or both.

References WLZ_ERR_NONE.

◆ WlzHistogramFitPeaks()

WlzErrorNum WlzHistogramFitPeaks	(	WlzObject *	histObj,
		int	numDbn,
		double	smooth,
		double	thresh,
		double	tol,
		int *	dstNumMu,
		double **	dstMu,
		int *	dstNumSigma,
		double **	dstSigma,
		int *	dstNumAlpha,
		double **	dstAlpha,
		double *	dstLL
	)

Fit the given Woolz histogram object's histogram bin values using a mixture of Gaussian distributions.

Returns

Woolz error code.

          First guess at peak positions, the method of guessing
          depends on the parameter numDbn. If (numDbn > 0) guess
          numDbn equally spaced Gaussians, else use the function
          WlzHistogramFindPeaks().
          After initial guess use the function AlgMixture() to find
          the maximum liklihood mixture of Gaussian distributions
          which best fit the histogram

\[ h(x) = \sum_{i=0}^k {\alpha_i g_i(x)} \]

where

\[ \sum_{i=0}^k {\alpha_i} = 1.0 \]

\(g_i(x)\) are the gaussians defined by standard deviation \(sigma_i\) and mean \(mu_i\).

Parameters

histObj	Given histogram object.
numDbn	If greater than zero the number of Gaussians to fit. If less than or equal to zero then the Gaussians are fitted to peaks found by WlzHistogramFindPeaks().
smooth	Gaussian \(sigma\) smooth histogram and compute 1st derivative.
thresh	Mimimum bin count for a peak.
tol	Log-likihood tolerance value for terminating the iteration.
dstNumMu	Destination ptr for the number of Gaussian mean values.
dstMu	Destination ptr for \(mu\), the Gaussian mean values.
dstNumSigma	Destination ptr for the number of Gaussian \(sigma\) values.
dstSigma	Destination ptr for the Gaussian \(sigma\) values.
dstNumAlpha	Destination ptr for the Gaussian \(alpha\) values.
dstAlpha	Destination ptr for the log-liklihood, may be NULL.
dstLL

References ALG_ERR_NONE, WLZ_ERR_NONE, and WLZ_ERR_PARAM_NULL.

◆ WlzHistogramNorm()

WlzErrorNum WlzHistogramNorm	(	WlzObject *	histObj,
		double	maxVal
	)

Normalise the given Woolz histogram object's histogram bin values to the given range [0-maxVal]. If the given maximum value is 0.0 then the histogram bin values are normalised so that maxVal is equal to the number of bins.

Returns: Woolz error code.

Parameters

histObj	Given histogram object.
maxVal	Given maximum value.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramBinMax()

int WlzHistogramBinMax ( WlzHistogramDomain * histDom )

Finds the bin of the histogram domain which has the greatest occupancy.

Returns: Woolz error code.

Parameters

histDom Given histogram domain.

References _WlzHistogramDomain::binValues, _WlzGreyP::dbp, _WlzGreyP::inp, _WlzHistogramDomain::nBins, _WlzHistogramDomain::type, WLZ_HISTOGRAMDOMAIN_FLOAT, and WLZ_HISTOGRAMDOMAIN_INT.

Referenced by WlzCompThresholdVT().

◆ WlzHistogramDistance()

double WlzHistogramDistance	(	WlzObject *	histObj0,
		WlzObject *	histObj1,
		WlzErrorNum *	dstErrNum
	)

Calculates a distance measure for comparing two histograms. The histogram distance is in the range [0.0 - 1.0] with 1.0 being a perfect match between histograms. The given histograms are not modified.

Returns: Histogram distance measure, range [0.0 - 1.0].

Parameters

histObj0	First histogram object.
histObj1	Second histogram object.
dstErrNum	Destination error pointer, may be NULL.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramMatchObj()

WlzErrorNum WlzHistogramMatchObj	(	WlzObject *	srcObj,
		WlzObject *	targetHist,
		int	independentPlanes,
		int	smoothing,
		double	minDist,
		double	maxDist,
		int	dither
	)

Modifies the grey values of the given Woolz 2D or 3D domain object so that the resulting object's histogram matches the target histogram object.

Returns

Woolz error code.

          If the given domain object is a 3D object and the
          independentPlanes flag is set then each of the 3D
          object's planes is matched independently.
          A domain object or plane will only be matched to the
          given histogram if the distance between it's histogram
          and the given histogram is within the given distance
          range.
          If the specified smoothing is non-zero then the source
          objects histogram is smoothed by WlzHistogramSmooth().
          The histogram distance is in the range [0.0 - 1.0] with
          1.0 being a perfect match between histograms. If the
          given minimum distance is <= 0.0 and the maximum
          distance is >= 1.0 then matching will always be done.
          The given histogram is not modified.

Parameters

srcObj	Given domain object.
targetHist	Target histogram object.
independentPlanes	If srcObj is a 3D domain object and independentPlanes is set (non-zero) then the domain objects planes are matched independently.
smoothing	Gaussian smoothing of the source object histogram before matching.
minDist	Minimum distance between the histograms.
maxDist	Maximum distance between the histograms.
dither	If non zero then dither mapped values to avoid generating a histogram with a comb appearence.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

◆ WlzHistogramEqualiseObj()

WlzErrorNum WlzHistogramEqualiseObj	(	WlzObject *	srcObj,
		int	smoothing,
		int	dither
	)

Modifies the grey values of the given Woolz 2D or 3D domain object so that the resulting object's histogram approximates a uniform histogram. If the specified smoothing is non-zero then the objects histogram is smoothed by WlzHistogramSmooth().

Returns: Woolz error code.

Parameters

srcObj	Given domain object.
smoothing	Gaussian smoothing of the histogram before equalisation.
dither	If non zero then dither mapped values to avoid generating a histogram with a comb appearence.

References WLZ_DBG, WLZ_DBG_LVL_1, and WLZ_ERR_NONE.

Files

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ _WlzHistFeature

Function Documentation

◆ WlzHistogramObj()

◆ WlzHistogramCopy()

◆ WlzHistogramRebin()

◆ WlzHistogramRsvFilter()

◆ WlzHistogramConvolve()

◆ WlzHistogramCnvGauss()

◆ WlzHistogramRsvGauss()

◆ WlzHistogramSmooth()

◆ WlzHistogramCummulative()

◆ WlzHistogramMapValues()

◆ WlzHistogramFindPeaks()

◆ WlzHistogramFitPeaks()

◆ WlzHistogramNorm()

◆ WlzHistogramBinMax()

◆ WlzHistogramDistance()

◆ WlzHistogramMatchObj()

◆ WlzHistogramEqualiseObj()