Woolz Image Processing  Version 1.8.3
WlzHistogram

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

WlzObjectWlzHistogramObj (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...
 
WlzObjectWlzHistogramCopy (WlzObject *srcHistObj, WlzObjectType dstType, WlzErrorNum *dstErrNum)
 Copies the given Woolz histogram object to a new one of the required type. More...
 
WlzObjectWlzHistogramRebin (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

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
srcObjGiven source object.
nBinsRequired number of histogram bins.
binOriginLowest grey value in first histogram bin.
binSizeGrey value range for each histogram bin.
dstErrNumDestination 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
srcHistObjGiven histogram object.
dstTypeRequired type of histogram domain values.
dstErrNumDestination 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
srcHistObjGiven histogram object.
dstTypeRequired type of histogram domain values.
dstMaxBinsTotal number of bins to be allocated.
dstNBinsNumber of bins to be used in new histogram.
dstOriginNew histogram origin.
dstBinSizeNew histogram bin size.
dstErrNumDestination 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
histObjGiven histogram object.
fltIIR 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
histObjGiven histogram object.
krnSzKernel size, must be odd.
krnThe 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
histObjGiven histogram object.
sigmaSigma value of the Gaussian which is scaled within this function to account for the histogram bin size.
derivDerivative 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
histObjGiven histogram object.
sigmaSigma value of the Gaussian which is scaled within this function to account for the histogram bin size.
derivDerivative 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
histObjGiven histogram object.
widthGaussian 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
srcHistGiven 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
srcObjGiven 2D or 3D domain object.
mapHistObjMapping histogram.
ditherIf 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
histObjGiven histogram object.
sigmaGaussian sigma smooth histogram and compute 1st derivative.
threshMinimum (smoothed) histogram value at peak, not used for troughs.
dstFeatSzDestination ptr for the number of peaks/troughs found.
dstFeatDestination ptr for the array of peak/trough positions (indicies into the histogram bin values). May have *dstFeat == NULL on return if *dstFeatSz == 0.
featFeatures 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
histObjGiven histogram object.
numDbnIf 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().
smoothGaussian \(sigma\) smooth histogram and compute 1st derivative.
threshMimimum bin count for a peak.
tolLog-likihood tolerance value for terminating the iteration.
dstNumMuDestination ptr for the number of Gaussian mean values.
dstMuDestination ptr for \(mu\), the Gaussian mean values.
dstNumSigmaDestination ptr for the number of Gaussian \(sigma\) values.
dstSigmaDestination ptr for the Gaussian \(sigma\) values.
dstNumAlphaDestination ptr for the Gaussian \(alpha\) values.
dstAlphaDestination 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
histObjGiven histogram object.
maxValGiven 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
histDomGiven 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
histObj0First histogram object.
histObj1Second histogram object.
dstErrNumDestination 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
srcObjGiven domain object.
targetHistTarget histogram object.
independentPlanesIf srcObj is a 3D domain object and independentPlanes is set (non-zero) then the domain objects planes are matched independently.
smoothingGaussian smoothing of the source object histogram before matching.
minDistMinimum distance between the histograms.
maxDistMaximum distance between the histograms.
ditherIf 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
srcObjGiven domain object.
smoothingGaussian smoothing of the histogram before equalisation.
ditherIf 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.