HIS

Name	Type	Caption	Length	Value range
FILE *	str	Input file name	1 -
DBIC *	List[int]	Input raster channel	1 -
GMOD	str	Graphic mode: ON\|OFF	0 - 3	ON \| OFF Default: ON
CMOD	str	Cumulative mode: ON\|OFF	0 - 3	ON \| OFF Default: ON
PCMO	str	Percentage mode: ON\|OFF	0 - 3	ON \| OFF Default: ON
NSAM	List[int]	Number of pixel values to sample	0 - 1	0 -
TRIM	List[float]	Tail trimming % (left, right)	0 - 2
HISW	List[float]	Histogram window	0 - 4
MASK	List[int]	Area mask	0 - 4
IMSTAT	List[float]	Image statistics	0 - 13

Parameter descriptions

FILE

Specifies the name of the PCIDSK image file containing the channel(s) to process.

DBIC

Specifies the image channels from which histogram data is extracted.

GMOD

Specifies graphic or numeric display of histogram data.

Available options are:

ON: graphic display. A vertical bar graph displays the distribution of gray-level value frequencies in the image. This is the default value.
OFF: numerical display. A table displayes the exact counts for the number of pixels that have each gray-level value. You may also use HISDUMP to generate a histogram table output suitable for reading into other functions.

CMOD

Specifies the plotting density function of the histogram.

Available options are:

ON: the histogram is plotted as a cumulative density function (cdf); this is the default value
OFF: the histogram is plotted as a probability density function (pdf)

PCMO

Specifies the count mode of the histogram data.

Available options are:

ON: each value on the histogram is a pixel count; this is the default value
OFF: each value is a ratio of the pixel count to the toal number of pixels sampled (that is, the percentage of pixels having that gray-level value)

NSAM

Specifies the number of pixel samples used to construct the histogram.

If set to 0, all pixels in the image (or under a specified window) are sampled.

If set to n , the actual n number of pixels in the image (or under a specified bitmap or window) are sampled, using a square grid to sample the required pixels.

The value specified for this parameter affects the speed and accuracy of the function.

TRIM

Specifies the percentage of each tail of the histogram to be trimmed before being plotted (min,max).

These are real values in units of percent (%). The first percentage is for the left (low) tail; the second percentage is for the right (high).

HISW

Specifies the portion of the histogram to print.

The histogram window has four values:

minimum gray level
maximum gray level
minimum pixel count
maximum pixel count

This parameter is specified as follows:

HISW	=	mingraylevel,maxgraylevel,minpixelcount,maxpixelcount

MASK

Specifies the window or bitmap that defines the area to be processed within the input raster.

If a single value is specified, that value represents the channel number of the bitmap segment in the input file. Only the pixels under the bitmap are processed; the rest of the image remains unchanged.

If four values are specified, they define the x,y offsets and x,y dimensions of a rectangular window identifying the area to process. Xoffset, Yoffset define the upper-left starting pixel coordinates of the window. Xsize is the number of pixels that define the window width. Ysize is the number of lines that define the window height.

If no value is specified, the entire channel is processed.

Note: When sampling under a bitmap, the Number of Pixel Values to Sample (NSAM) parameter is ignored.

IMSTAT

Upon completion, HIS writes out to the IMSTAT parameter the following information about the last channel histogrammed:

first IMSTAT array element : Channel number
second IMSTAT array element : Channel mean
third IMSTAT array element : Channel median (for 8-bit channel only)
fourth IMSTAT array element : Channel standard deviation
fifth IMSTAT array element : Window X offset
sixth IMSTAT array element : Window Y offset
seventh IMSTAT array element : Window X size
eighth IMSTAT array element : Window Y size
ninth IMSTAT array element : Bitmap Segment used for sampling (0 if none used)
tenth IMSTAT array element : Number of samples used
eleventh IMSTAT array element : Lowest gray level found
twelfth IMSTAT array element : Highest gray level found
thirteenth IMSTAT array element : Mode (or zero for non-eight bit data)

Details

HIS calculates and prints histograms of sampled gray-level values of up to 16 image channels. Both graphic histograms (GMOD = "ON") and numeric histograms (GMOD = "OFF") may be plotted. The plotted histogram may be cumulative (CMOD = "ON") or non-cumulative (CMOD = "OFF").

Values of the plotted histogram may represent either pixel counts (PCMO="OFF") or a percentage of the total count (PCMO = "ON"). The user may choose to print only a portion of the histogram using HISW or TRIM.

The MASK parameter specifies the area within the input channel which will be processed. Only the area under MASK will be processed; the rest of the image remains unchanged.

If a single value is specified, this value points to a bitmap segment, which defines the area to be processed. If four values are specified, these values define the x,y offsets and x,y dimensions of the rectangular window within the image to be processed.

If MASK is not specified, the entire image is processed.

The number of samples used to construct the histogram may also be specified. The functionality of these parameters is particularly useful in that histogramming takes considerably less time for smaller sample sizes than it does for larger ones.

HIS can generate histograms for 8-bit unsigned integer, 16-bit signed integer, 16-bit unsigned integer, and 32-bit real channels. These channels have the following ranges for data:

Type                          Min                    Max

8-bit unsigned integer          0                    255
16-bit signed integer      -32768                  32767
16-bit unsigned integer         0                  65535
32-bit signed integer  -2147483648            2147483647
32-bit unsigned integer         0             4294967295
32-bit real              -3.4E+38                3.4E+38
64-bit unsigned integer         0               2E64 - 1
64-bit signed integer       -9E18                   9E18
64-bit real              -1.8E308                1.8E308

HIS writes image data statistics to the output parameter IMSTAT.

HIS must perform a binning operation when computing the histogram. For data types other than 8-bit unsigned, this binning results in grouping different pixel values into a single bin. If explicit binning control is required, use the HISDUMP function.

Examples

Examples are provided for several types of available histograms.

Print the default graphic histogram, where histogram values represent pixel counts for all data on the 8-bit channel.

from pci.his import his

file	=	'irvine.pix'
dbic	=	[4]	# 8-bit unsigned
gmod	=	'ON'	# show graphic mode
cmod	=	'OFF'	# no cumulative mode
pcmo	=	'OFF'	# no percentage mode
nsam	=	[]	# no number of samples
trim	=	[]	# no trimming
hisw	=	[]	# no specific histogram window
mask	=	[]	# process entire image
imstat	=	[]	# parameter to receive output

his( file, dbic, gmod, cmod, pcmo, nsam, trim, hisw, mask, imstat )
print("Channel number : ", imstat[0])
print("Channel mean   : ", imstat[1])

 Output Report

irvine.pix
                                        [S   14PIC     512P     512L]

  4 [ 8U] Description: 0.830um +/- 0.070um  TM band 4: near infra-red
   37759+            *
        |            *
        |            *
        |           ***
   28319+           ***
        |           ***
        |          ****
        |          *****
   18880+          *****
        |         *******
        |         *******
        |        ********
    9440+        *********
        |       ***********
        |      *************
        |006*****************85432110000000000000000
       0+---------+---------+---------+---------+------
        2        32        62        92       122

  Number of pixels plotted : 262144  Cell width : 3.0000
  Mean:  39.841  Median: 40  Standard Dev: 11.219  Min: 2  Max: 130
Channel number : 4
Channel mean   : 39.841

Print the default graphic histogram, where histogram values represent pixel counts for all data on the 16-bit channel.

from pci.his import his

file	=	'irvine.pix'
dbic	=	[10]	# 16-bit signed
gmod	=	'ON'	# show graphic mode
cmod	=	'OFF'	# no cumulative mode
pcmo	=	'OFF'	# no percentage mode
nsam	=	[]	# no number of samples
trim	=	[]	# no trimming
hisw	=	[]	# no specific histogram window
mask	=	[]	# process entire image
imstat	=	[]	# parameter to receive output

his( file, dbic, gmod, cmod, pcmo, nsam, trim, hisw, mask, imstat )
print("Channel number : ", imstat[0])
print("Channel mean   : ", imstat[1])

irvine.pix
                                        [S   14PIC     512P     512L]

  10 [16S] Description:                      USGS Elevation Data
   17056+ *
        | **
        | **
        | ** **
   12792+ *****
        | ******
        | ******
        | ******     *
    8528+ ******     ***
        | ******** ******
        | *****************
        |*******************      *
    4264+***************************
        |******************************
        |********************************
        |*************************************333221110000000000000000
       0+---------+---------+---------+---------+---------+---------+--
       40       180       320       460       600       740       880

  Number of pixels plotted : 262144  Cell width : 14.0000
  Minimum Value in data:  40.0000  Pixels less than histogram min:       24
  Maximum Value in data: 883.0000  Pixels more than histogram max:        0
  For all data: Mean:     231.640 Standard Deviation:     146.730
Channel number : 10
Channel mean   : 231.640

Print the default graphic histogram, where histogram values represent pixel counts under a specified bitmap on the 16-bit channel.

from pci.his import his

file	=	'irvine.pix'
dbic	=	[10]	# 16-bit signed
gmod	=	'ON'	# show graphic mode
cmod	=	'ON'	# cumulative mode
pcmo	=	'OFF'	# no percentage mode
nsam	=	[]	# no number of samples
trim	=	[]	# no trimming
hisw	=	[]	# no specific histogram window
mask	=	[16]	# process under bitmap of wetland
imstat	=	[]	# parameter to receive output

his( file, dbic, gmod, cmod, pcmo, nsam, trim, hisw, mask, imstat )
print("Channel number : ", imstat[0])
print("Channel mean   : ", imstat[1])

irvine.pix
                                        [S   14PIC     512P     512L]

  10 [16S] Description:                      USGS Elevation Data
    1973+                                                             *****
        |                                                        **********
        |                                                   ***************
        |                                                   ***************
    1480+                                                   ***************
        |                                              ********************
        |                                              ********************
        |                                         *************************
     986+                                         *************************
        |                                    ******************************
        |                               ***********************************
        |                               ***********************************
     493+                          ****************************************
        |                     *********************************************
        |                **************************************************
        |******************************************************************
       0+---------+---------+---------+---------+---------+---------+------
   407.00    481.85    556.70    631.55    706.39    781.24    856.09

  Number of pixels plotted : 1973  Cell width : 7.4848
  Minimum Value in data: 407.0000  Pixels less than histogram min:        0
  Maximum Value in data: 883.0000  Pixels more than histogram max:        0
  For all data: Mean:     694.157 Standard Deviation:     120.039
Channel number : 10
Channel mean   : 694.157

Print a cumulative graphic histogram, where histogram values represent pixel counts for all data on the 16-bit channel:

from pci.his import his

file='irvine.pix'
dbic	=	[10]	# 16-bit signed
gmod	=	'ON'	# show graphic mode
cmod	=	'ON'	# cumulative mode
pcmo	=	'OFF'	# no percentage mode
nsam	=	[]	# no number of samples
trim	=	[]	# no trimming
hisw	=	[]	# no specific histogram window
mask	=	[]	# process entire image
imstat	=	[]	# parameter to receive output

his( file, dbic, gmod, cmod, pcmo, nsam, trim, hisw, mask, imstat )
print("Channel number : ", imstat[0])
print("Channel mean   : ", imstat[1])

irvine.pix
                                        [S   14PIC     512P     512L]

  10 [16S] Description:                      USGS Elevation Data
  262144+                                                            *
        |                               ******************************
        |                          ***********************************
        |                       **************************************
  196608+                    *****************************************
        |                 ********************************************
        |               **********************************************
        |             ************************************************
  131072+           **************************************************
        |         ****************************************************
        |       ******************************************************
        |      *******************************************************
   65536+    *********************************************************
        |   **********************************************************
        |  ***********************************************************
        |*************************************************************
       0+---------+---------+---------+---------+---------+---------+--
       40       180       320       460       600       740       880

  Number of pixels plotted : 262144  Cell width : 14.0000
  Minimum Value in data:  40.0000  Pixels less than histogram min:        0
  Maximum Value in data: 883.0000  Pixels more than histogram max:        0
  For all data: Mean:     231.640 Standard Deviation:     146.730
Channel number : 10
Channel mean   : 231.640

Print a numeric histogram, where histogram values represent pixel counts for all data on the 32-bit real channel. Copy the 16-bit channel used in previous examples to a 32-bit real channel on another file.

from pci.cim import cim
from pci.iii import iii
from pci.his import his

file	=	'real.pix'
tex1	=	''
tex2	=	''
dbsz	=	[512,512]	# 512 pixels x 512 lines
pxsz	=	[30,30]	# resolution 30x30 meters
dbnc	=	[0,0,0,1]	# one 32-bit channel
dblayout	=	'BAND'	# band interleaving

cim( file, tex1, tex2, dbsz, pxsz, dbnc, dblayout )

fili	=	'irvine.pix'
filo	=	'real.pix'
dbic	=	[10]	# copy 16-bit data to 32-bit channel
dboc	=	[1]
dbiw	=	[]	# process entire image
dbow	=	[]

iii( fili, filo, dbic, dboc, dbiw, dbow )

file	=	'real.pix'
dbic	=	[1]	# 32-bit real
gmod	=	'OFF'	# no graphic mode
cmod	=	'OFF'	# no cumulative mode
pcmo	=	'OFF'	# no percentage mode
nsam	=	[]	# no number of samples
trim	=	[]	# no trimming
hisw	=	[]	# no specific histogram window
mask	=	[]	# process entire image
imstat	=	[]	# parameter to receive output

his( file, dbic, gmod, cmod, pcmo, nsam, trim, hisw, mask, imstat )
print("Channel number : ", imstat[0])
print("Channel mean   : ", imstat[1])

real.pix
                                        [S   1PIC     512P     512L]

  1 [32R] Description:                      USGS Elevation Data
  Number of pixels sampled: 262144    Number of pixels plotted:   262144

                0.0000000e+00 1.3093750e+01 2.6187500e+01 3.9281250e+01
                +------------+------------+------------+------------+
4.0000000e+01 |        4524       15285       15607       13155
9.2375000e+01 |       12629       14544       12356        9812
1.4475000e+02 |        7318        6966        7689        7695
1.9712500e+02 |        7712        9661        8782        8341
2.4950000e+02 |        7525        6232        6102        5309
3.0187500e+02 |        4953        4831        4719        4777
3.5425000e+02 |        4771        4842        4996        5068
4.0662500e+02 |        4220        3880        3586        3372
4.5900000e+02 |        2840        2392        1953        1709
5.1137500e+02 |        1424        1250        1108        1011
5.6375000e+02 |         899         913         806         658
6.1612500e+02 |         557         484         411         296
6.6850000e+02 |         245         199         178         176
7.2087500e+02 |         158         154         121         131
7.7325000e+02 |         124         138         134         131
8.2562500e+02 |         117          83          40          39
8.7800000e+02 |           6           0           0           0

  For all data: Mean:     231.640 Standard Deviation:     146.730
 Channel number : 1
 Channel mean   : 231.640

Print a cumulative numeric histogram, where histogram values represent percentages of total count for all data on the 8-bit channel.

from pci.his import his

file	=	'irvine.pix'
dbic	=	[4]	# 8-bit unsigned
gmod	=	'OFF'	# no graphic mode
cmod	=	'ON'	# cumulative mode
pcmo	=	'ON'	# percentage mode
nsam	=	[]	# no number of samples
trim	=	[]	# no trimming
hisw	=	[]	# no specific histogram window
mask	=	[]	# process entire image
imstat	=	[]	# parameter to receive output

his( file, dbic, gmod, cmod, pcmo, nsam, trim, hisw, mask, imstat )
print("Channel number : ", imstat[0])
print("Channel mean   : ", imstat[1])

irvine.pix
                                        [S   14PIC     512P     512L]

  4 [ 8U] Description: 0.830um +/- 0.070um  TM band 4: near infra-red
  Number of pixels sampled: 262144    Number of pixels plotted:   262144

              0       1       2       3       4       5       6       7
       +----------------------------------------------------------------
   0  |  0.0000  0.0000  0.0000  0.0001  0.0003  0.0005  0.0009  0.0021
   8  |  0.0046  0.0079  0.0120  0.0155  0.0187  0.0219  0.0254  0.0294
  16  |  0.0342  0.0395  0.0457  0.0526  0.0602  0.0685  0.0781  0.0890
  24  |  0.1018  0.1158  0.1322  0.1509  0.1713  0.1946  0.2214  0.2515
  32  |  0.2827  0.3168  0.3536  0.3950  0.4396  0.4870  0.5346  0.5836
  40  |  0.6305  0.6716  0.7074  0.7383  0.7679  0.7959  0.8214  0.8435
  48  |  0.8627  0.8796  0.8944  0.9075  0.9183  0.9282  0.9368  0.9447
  56  |  0.9513  0.9570  0.9623  0.9666  0.9706  0.9739  0.9768  0.9793
  64  |  0.9814  0.9834  0.9851  0.9866  0.9880  0.9893  0.9905  0.9915
  72  |  0.9925  0.9933  0.9941  0.9948  0.9954  0.9961  0.9966  0.9970
  80  |  0.9973  0.9977  0.9979  0.9982  0.9984  0.9986  0.9988  0.9989
  88  |  0.9991  0.9992  0.9993  0.9994  0.9995  0.9995  0.9996  0.9996
  96  |  0.9997  0.9997  0.9997  0.9998  0.9998  0.9998  0.9998  0.9998
 104  |  0.9999  0.9999  0.9999  0.9999  0.9999  0.9999  0.9999  0.9999
 112  |  0.9999  0.9999  0.9999  0.9999  0.9999  0.9999  0.9999  1.0000
 120  |  1.0000  1.0000  1.0000  1.0000  1.0000  1.0000  1.0000  1.0000
 128  |  1.0000  1.0000  1.0000  1.0000  1.0000  1.0000  1.0000  1.0000

  Mean: 39.8405 Median: 40 Mode: 41 Standard Dev: 11.2186
  Min: 2                                        Max: 130
Channel number : 4
Channel mean   : 39.84054184

Environments	PYTHON :: EASI :: MODELER
Quick links	Description :: Parameters :: Parameter descriptions :: Details :: Examples :: Related

HIS

Histogramming database image

Description

Parameters

Parameter descriptions

Details

Examples