HIST_2D

The HIST_2D function returns the two dimensional density function (histogram) of two variables.

This routine is written in the IDL language. Its source code can be found in the file hist_2d.pro in the lib subdirectory of the IDL distribution.

Note: The data type of the values specified for BIN1, BIN2, MAX1, MAX2, MIN1, and MIN2 should match the data type of the V1 and V2 arguments. Since these keyword values are converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results. For example, if you have two byte images as inputs, but you want to use a fractional binsize, you should convert your input arrays to floating-point before calling HIST_2D.

Examples

; Read an RGB image of a rose.

file = FILE_WHICH('rose.jpg')

rose = READ_IMAGE(file)

; Compare the red versus green bands of the image,

; in 5 x 5 bins.

red_band = rose[0,*,*]

green_band = rose[1,*,*]

h2d = HIST_2D(red_band, green_band, bin1=5, bin2=5)

; Resize (with nearest-neighbor sampling) the

; output array of bins to the original range of

; intensities in the red and green bands, [0-255].

h2d = CONGRID(h2d, MAX(red_band), MAX(green_band))

; Squash peaks by displaying logs of bins.

h2d = BYTSCL(ALOG10(h2d > 1))

; Plot the 2D histogram.

ct = COLORTABLE(0, /REVERSE)

g0 = IMAGE(h2d, RGB_TABLE=ct, AXIS_STYLE=2, MARGIN=0.1, $

   XTITLE='Red band pixel intensity', $

   YTITLE='Green band pixel intensity', $

   TITLE='Density plot of red vs green intensities in $\bf rose.jpg$')

g1 = IMAGE(rose, POSITION=[0.20, 0.65, 0.40, 0.85], /CURRENT)

Syntax

Result = HIST_2D( V₁, V₂ [, BIN1=width] [, BIN2=height] [, MAX1=value] [, MAX2=value] [, MIN1=value] [, MIN2=value] )

Return Value

Returns a longword array of dimensions (MAX(V1)+1, MAX(V2)+1). Result(i,j) is equal to the number of simultaneous occurrences of V1 = i and V2 = j at the specified element.

Arguments

V1, V2

The arguments are arrays containing the variables. V1 and V2 may be of any numeric type except complex. If V1 and V2 do not contain the same number of elements, then the extra elements in the longer array are ignored.

Keywords

BIN1

Set this keyword equal to the size of each bin in the V1 direction (column width). If this keyword is not specified, the size is set to 1.

Note: The data type of the value specified for BIN1 should match the data type of the V1 and V2 arguments. Since BIN1 is converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results.

BIN2

Set this keyword equal to the size of each bin in the V2 direction (row height). If this keyword is not specified, the size is set to 1.

Note: The data type of the value specified for BIN2 should match the data type of the V1 and V2 arguments. Since BIN2 is converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results.

MAX1

Set this keyword equal to the maximum V1 value to consider. If this keyword is not specified, then V1 is searched for its largest value.

Note: The data type of the value specified for MAX1 should match the data type of the V1 and V2 arguments. Since MAX1 is converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results.

MAX2

Set this keyword equal to the maximum V2 value to consider. If this keyword is not specified, then V2 is searched for its largest value.

Note: The data type of the value specified for MAX2 should match the data type of the V1 and V2 arguments. Since MAX2 is converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results.

MIN1

Set this keyword to the minimum V1 value to consider. If this keyword is not specified and if the smallest value of V1 is greater than zero, then MIN1=0 is used, otherwise the smallest value of V1 is used.

Note: The data type of the value specified for MIN1 should match the data type of the V1 and V2 arguments. Since MIN1 is converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results.

MIN2

Set this keyword to the minimum V2 value to consider. If this keyword is not specified and if the smallest value of V2 is greater than zero, then MIN2=0 is used; otherwise, the smallest value of V2 is used.

Note: The data type of the value specified for MIN2 should match the data type of the V1 and V2 arguments. Since MIN2 is converted to the data type of V1 and V2, specifying mismatched data types may produce undesired results.

Additional Examples

To return the 2D histogram of two byte images:

R = HIST_2D(image1, image2)

To display the 2D histogram made from two floating point images, restricting the range from -1 to +1, and with 101 bins:

F1 = RANDOMN(seed, 256, 256)
F2 = RANDOMN(seed, 256, 256)
Result = HIST_2D(F1, F2, MIN1=-1, MAX1=1, $
   MIN2=-1, MAX2=1, BIN1=0.02, BIN2=0.02)
TVSCL, Result

Version History

Pre 4.0

Introduced