IMGPROBE

Lists or plots image data for a region of the displayed image.

Format

IMGPROBE option region unit [keywords]

Parameters

option	LIST	lists the values for the data points in the specified region (default)
	STAT	lists the statistical parameters for the data points in the specified region
	CONT	contours the values of the data points in the specified region
	HIST	displays a histogram of the data points in the specified region
	PLOT	plots the values of the data points in the specified region; if the region is BOX or LINE, a line plot is drawn; if the region is POINT, the value of the data point is plotted see the Remarks for valid combinations of option and region
region	BOX	data points in a rectangle defined by the cursor limits or with the SIZE keyword
	LINE	data points along a line defined with the mouse
	POINT	data point at the center of the cursor's current position (default) see the Remarks for valid combinations of option and region
unit	output calibration units (default=BRIT, meaning grayscale brightness values between 0 and 255; all available units are listed when LIST POINT is requested)

Keywords

BANd=	image band from which to obtain data (default=band displayed on the frame)
EXClude=	value1 . . valueN	image data values to exclude from the analysis; specify numeric values and/or SPACE, which excludes the values of all points without navigation; see the Remarks for information about formats to use for entering multiple numeric values; this keyword is valid only with the STAT and HIST options
IMA=	image frame displaying the data to examine (default=current)
OUTline=	NO	does not draw an outline of the region (default)
	YES color	draws an outline on the current graphics frame in the specified graphics color level (color default=3)
SIZe=	line ele	number of lines and elements defining a region centered at the cursor position; use this keyword only with a BOX region; see the Remarks regarding even number values for line and ele (default=cursor size)
SU=	stretch table name; use this keyword to examine modified brightness values that would be present if the image was displayed using the specified stretch table (default=stretch table currently applied to the displayed image)
WL=	obtains data from band with image wavelength closest to the specified value; valid only with high spectral resolution data, e.g., Aqua AIRS (default=wavelength of band displayed on frame)
WN=	obtains data from band with image wave number closest to the specified value; valid only with high spectral resolution data, e.g., Aqua AIRS (default=wave number of band displayed on frame)

Keywords valid with CONT option

CINt=	contour interval (default=computed)
CLImit=	min max	contour interval limits (default=computed)
COLor=	graphics color level of the contours (default=3)
DASh=	YES	use dashed lines for contours
	NO	use solid lines for contours (default)
GRA=	graphics frame to display the contours (default=current)
LHGt=	height of the contour labels, in pixels; specify zero for no contour labels (default=6)
LINt=	contour label interval (default=2, label every other contour)
SMOoth=	contour smoothing; the range is 0 to 50; larger numbers produce smoother contours (default=20)

Keywords valid with HIST and PLOToptions

COLor=	graphics color level of the histogram or plot (default=3)
EG=	NO	does not erase the graphics frame before plotting HIST BOX, HIST LINE, PLOT BOX, or PLOT LINE diagrams (default=YES)
GRA=	graphics frame to display the histogram or plot (default=current)
LENgth=	length of each class interval; valid with the HIST option only (default=1.0)
PTYpe=	DOT	plots data as points
	SOLID	plots data with connecting line segments (default)
XRAnge=	min max	range of values for the x-axis
YRAnge=	min max	range of values for the y-axis

Keywords valid with Interactive and Batch Modes

DATaset=	name and position of the ADDE dataset containing the image to read data from; specify as group/descriptor.position or alias.position; valid only when used with MODE=N, SIZE, and LATLON, LINELE, or STATION keywords; not valid with the CONT option, LINE region, or PLOT POINT combination (default=dataset and position of the displayed image; if a different dataset is specified the default position is 0)
ID=	NEXRAD station ID (e.g., MKX) of the desired image in the dataset specified in the DATASET keyword; this keyword is needed only with NEXRAD datasets
LATlon=	lat lon		latitude and longitude for the POINT region, or to place at the BOX region location specified in the PLACE keyword; LATLON is valid only with MODE=N, and you cannot use LATLON with the LINELE or STATION keyword (default=location of the cursor on the frame)
LINele=	line ele sys		line and element numbers and their coordinate system for the POINT region, or to place at the BOX region location specified in the PLACE keyword; for the coordinate system, specify either F for file (area) coordinates or I for image coordinates; LINELE is valid only with MODE=N, and you cannot use LINELE with the LATLON or STATION keyword (default=location of the cursor on the frame)
MODE=	N	non-interactive batch mode; uses the cursor's position and size at time the command is run or the LATLON= or LINELE= or STATION= with SIZE= to determine the image region; not valid with LINE region
	I	interactive mode; you can select multiple image regions using the right mouse button or Alt G with commands like IMGPROBE LIST BOX, then press Alt Q to quit (default)
PLAce=	location in the BOX region to place the point specified in the LATLON, STATION or LINELE keywords; use one of the following:
	ULEFT		upper-left corner of the BOX region (default when the LINELE keyword is used)
	CENTER		center of the BOX region (default when the LATLON or STATION keyword is used)
STAtion=	station ID for the POINT region, or to place at the BOX region location specified in the PLACE keyword; specify as the ID, e.g., KMSN or YSSY, optionally followed by the station type in brackets, e.g., ARX[N] or ARX[V]; this keyword is valid is valid only with MODE=N and you cannot use it with the LATLON or LINELE keyword (default=location of the cursor on the frame)

Remarks

IMGPROBE lists or plots data for a region of the image displayed on the current frame or an image specified in the DATASET keyword. When using a displayed image, the image file must be present on disk (as opposed to workstation memory) because IMGPROBE uses data directly from the image file.

The following combinations of option and region parameters are valid:

option	region
CONT	BOX
LIST	BOX, LINE and POINT
HIST	BOX and LINE
PLOT	BOX, LINE and POINT
STAT	BOX and LINE

When you use the PLOT option with the BOX region, the x-axis of the line plot lists the pixel numbers in the box from left to right and top to bottom. Pixel number 1 is the upper-left data point, and the largest pixel number is the bottom-right data point.

When you use the LIST option with the BOX or LINE region, the output is listed in Output Blocks. There is no limit to the number of lines in an Output Block, so the output is divided into multiple Output Blocks only if it's too wide to fit in the text frame. The number of Output Blocks depends on the number of data points in each line of output and the calibration unit selected. For example, you can fit more brightness values across the text frame than IR radiance values. In the output for the BOX region, each successive Output Block is located to the right of the previous Output Block.

If you specify an even number for the line or ele parameter of the SIZE keyword, it is not possible to place an equal number of lines or elements on each side of the cursor center. The bottom line or right column of elements is omitted. For example, if the cursor is positioned at line 100 and element 200 and you specify SIZE=50 50, the data points used are those in a box covering lines 75 to 124 and elements 175 to 224.

When using a BOX region with any option, there must be less than 524,288 data points in the region. To calculate this number, you must know the image blowup or blowdown factor. If the image is displayed:

at the image's resolution (blowup or blowdown factor of 1), use the formula: region height x region width
with a blowup factor of M, use the formula:
{[(region height - 1)/M ] + 1} x {[(region width - 1)/M ] + 1}
note: if a division in the formula yields a decimal value, it is truncated before adding 1 and multiplying the terms
with a blowdown factor of N, use the formula: (region height x N) x (region width x N)

For example, a 10 by 100 region size over a 1 km resolution image displayed with a blowup/blowdown factor of 1 contains 1000 data points. If the image is displayed at 2 km resolution (blowdown factor of 2), the region contains 4000 data points. If it is displayed at 0.5 km resolution (blowup factor of 2), the region contains 250 data points.

If you specify a BOX or POINT region, MODE=N, and a dataset in the DATASET keyword, you must specify the location with the LATLON, LINELE, or STATION keyword. If it is a BOX region, you must also specify the region size with the SIZE keyword.

If you specify MODE=N but do not specify the DATASET keyword, the cursor is moved to the location specified in the LATLON, LINELE or STATION keyword.

Use the IMGPROBE LIST POINT command to determine valid options for the unit parameter.

You can enter numeric values in the EXCLUDE keyword using the list format (value1 value2 value3 etc.) and/or range format (x-yBn where x and y are the beginning and ending values, and n is the increment). If you don't specify an increment, all real numbers from x through y are excluded. For example, EXCLUDE=0 126-129 255 excludes 0, all values from 126 through 129, and 255; EXCLUDE=0 126-129B1 255 excludes 0, 126, 127, 128, 129 and 255; EXCLUDE=0 126-130B2 255 excludes 0, 126, 128, 130 and 255; EXCLUDE=-12--1 excludes all values from -12 through -1; EXCLUDE=150-140 excludes all values greater than 150 and all values less than 140.

Examples

IMGPROBE

This entry lists information for one or more data points at the center of the cursor, including all calibration units for the image. The command is interactive, so you are prompted to select each point by moving the cursor and pressing the right mouse button or Alt G. Press Alt Q to quit.

IMGPROBE LIST LINE

This entry lists information for the data points along one or more lines. You are prompted to define each line's beginning and ending points using the mouse; then, press Alt Q to quit. The lines are not drawn on the frame.

IMGPROBE LIST LINE OUTLINE=YES 2

IMGPROBE STAT BOX OUTLINE=YES BAND=4 EXCLUDE=255 SPACE MODE=N

This entry draws an outline around the data points in the region defined by the cursor limits and lists the statistical values for band 4 of those data points. Pixels without navigation or with a brightness value of 255 are not included in the statistical analysis.

IMGPROBE CONT BOX BRIT SIZE=200 300 CINT=10 MODE=N

This entry contours brightness values of the data points in a 200 by 300 pixel region centered at the cursor position. Contours are drawn at an interval of every 10 brightness values.

IMGPROBE PLOT LINE OUTLINE=YES 5 COLOR=4

This entry draws a line plot of the data point values along a line. You are prompted to define the line's beginning and ending points using the mouse. The plot is drawn in graphics color level 4. The line is drawn in graphics color level 5. The command is interactive, so you can draw additional line plots by selecting each line's beginning and ending points using the mouse. Note, however, that the graphics are erased each time you select a new beginning point since EG=YES is the default.

IMGPROBE HIST BOX SU=WARM COLOR=2

This entry draws a histogram of the values of the data points in the region defined by the cursor limits. The histogram is drawn in graphics color level 2. The values for the histogram are those that would be present if the image was displayed using the stretch table WARM. The command is interactive, so you can draw additional histograms by selecting new box regions using the mouse. Note, however, that the graphics are erased each time you select a new region since EG=YES is the default.

IMGPROBE HIST BOX TEMP XRANGE=200 300 YRANGE=0 100 LENGTH=.1 DATASET=GOES/IR.5 MODE=N LATLON=40 100 SIZE=50 50

This entry draws a histogram of the temperatures of the region's data points. The region is a 50- by 50-pixel box centered at 40°N, 100°W on the image in position 5 in dataset GOES/IR. The histogram's x-axis range is 200 to 300 degrees Kelvin, and the y-axis range is 0 to 100 occurrences. The length of the class interval is 0.1 degrees Kelvin.