image.histograms - Function

Compute histograms from the image

Synopsis
histograms(histout, axes, region, mask, nbins, includepix, gauss, cumu, log, list, plotter, nx, ny, size, force, disk, async)

Arguments

histout	out	Glish record containing the histograms
		Allowed:	Glish variable
		Default:	No retrieval
axes	in	List of axes to compute histograms over
		Allowed:	Vector of integers
		Default:	All axes
region	in	Region of interest
		Allowed:	Region tool
		Default:	Whole image
mask	in	OTF mask
		Allowed:	Boolean LEL expression or mask region
		Default:	None
nbins	in	Number of bins in histograms
		Allowed:	Positive integer
		Default:	25
includepix	in	Range of pixel values to include
		Allowed:	A vector of 1 or 2 Floats
		Default:	Include all pixels
gauss	in	If T overlay a Gaussian on each histogram
		Allowed:	Bool
		Default:	F
cumu	in	If T plot cumulative histograms, otherwise plot non-cumulatively
		Allowed:	Bool
		Default:	F
log	in	If T plot the ordinate logarithmically, otherwise plot linearly
		Allowed:	Bool
		Default:	F
list	in	If T then list some statistics as well
		Allowed:	Bool
		Default:	T
plotter	in	The PGPLOT device name to make plots on
		Allowed:	Any valid PGPLOT device
		Default:	No plotting
nx	in	The number of subplots per page in the x direction
		Allowed:	Positive integer
		Default:	1
ny	in	The number of subplots per page in the y direction
		Allowed:	Positive integer
		Default:	1
size	in	Size of plotter
		Allowed:	Vector of integers
		Default:	[600,450]
force	in	If T then force the stored statistical accumulations to be regenerated
		Allowed:	Bool
		Default:	F
disk	in	If T then force the storage image to disk
		Allowed:	Bool
		Default:	F
async	in	Run asynchronously?
		Allowed:	Bool
		Default:	!dowait - but always F if plotting

Returns
T or fail

Description

This function (short-hand name is histo) computes histograms of the pixel values in the image file. You can plot them and retrieve them (into a Glish record) for further analysis or display.

The chunk of the image over which you compute the histograms is specified by a vector of axis numbers (argument axes). For example, consider a 3-dimensional image for which you specify axes=[1,3]. The histograms would be computed for each XZ (axes 1 and 3) plane in the image. You could then examine those histograms as a function of the Y (axis 2) axis. Or perhaps you set axes=[3], whereupon you could examine the histogram for each Z (axis 3) profile as a function of X and Y location in the image.

You have control over the number of bins for each histogram (nbins). The bin width is worked out automatically for each histogram and may vary from histogram to histogram (the range of pixel values is worked out for each chunk being histogrammed).

You have control over which pixels are included in the histograms via the includepix argument. This vector specifies a range of pixel values to be included in the histograms. If you only give one value for this, say includepix=[b], then this is interpreted as includepix=[-abs(b),abs(b)]. If you specify an inclusion range, then the range of pixel intensities over which the histograms are binned is given by this range too. This is a way to make the bin width the same for each histogram.

You have control over the form of the histogram; the ordinate can be linear or logarithmic (log=T), and cumulative or non-cumulative (cumu=T).

You can overlay a Gaussian on each histogram (gauss=T). It has the same mean and standard deviation about the mean of the pixels that were binned and the same integral as the histogram.

You can list some additional statistical information about the data in each image chunk that is being histogrammed (list=T).

You can retrieve the histograms into a Glish record (the counts and the abcissa values for each histogram). The names of the fields in the record are `values' and `counts'. The shape of the first dimension of those arrays contained in those fields is nbins. The number and shape of the remaining dimensions are those in the image for which you did not compute the histograms. For example, in the second example above, we set axes=[3] and asked for histograms as a function of the remaining axes, in this case, the X and Y (axes 1 and 2) axes. The shape of each histogram array is then [nbins,nx,ny]. The form of the retrieved histograms is that specified by the cumu and log arguments.

The plotting is done directly on a PGPLOT plotting device (function is always run synchronously when plotting). The syntax is plotter=name/type. For example plotter='plot1.ps/ps' (disk postscript file) or plotter='plot1/glish' (Glish PGplotter).

This function generates ``storage'' images, into which the histograms and statistics are written. They are only regenerated when necessary. For example, if you run the function twice successively with identical arguments, the histograms will be directly retrieved from the storage image. However, you can force regeneration of the storage image if you set force=T. The storage medium is either in memory or on disk, depending upon its size. You can force it to disk if you set disk=T, otherwise it decides for itself.

Example

 
- im.histograms(plotter='plot/glish')

In this example we plot the histogram of the entire image on a PGPLOT X-windows device.

Example

 
- im.histograms(histout=myhist,axes=[1,3],nbins=30,includepix=1e-3,
                cumu=T,gauss=T,plotter='plot/glish',nx=4,ny=3)

In this example, let us assume the image has 3 dimensions. We generate cumulative histograms of XZ (axes 1 and 3) planes for pixels with values in the range -0.001 to 0.001 and plot them with Gaussian overlays as a function of Y-axis location on the standard PGPLOT X-windows device with 12 plots per page. The histograms are retrieved into a Glish record called myhist for further use (because we are plotting the function is run synchronously).

Next: image.history - Function Up: image - Tool Previous: image.haslock - Function Contents Index

	Package	general
	Module	images
	Tool	image