McIDAS-X User's Guide
Version 2023.1

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]

IMGFILT

Applies filters to image data.

Formats

IMGFILT sdataset ddataset [keywords] "comment
IMGFILT sdataset1 sdataset2 ddataset [keywords] "comment

Parameters

sdataset	source ADDE dataset name and position; specify one of the following formats:
		group/descriptor.position alias.position
	a position greater than zero represents an absolute position in the dataset; a position less than or equal to zero represents a relative position in the dataset based on image time, for example, 0 is the most recent and -1 is the next most recent; to use the default position, do not specify .position; specify two source datasets only if using FILTER=CLOUD, CORE, DIS or MERGE (no default for group/descriptor or alias; default=0 for position)
ddataset	destination ADDE dataset name and absolute position; specify one of the following formats:
		group/descriptor.position alias.position
	use only positive integers for position
"comment	description placed in the image file directory's memo field; 32 characters maximum (default=no comment)

Image Positioning Keywords

LATlon=	lat lon		latitude and longitude of the sdataset image to place at the ddataset image location specified in the PLACE keyword
LINele=	line ele sys
		line	line number of the sdataset image to place at the ddataset image location specified in the PLACE keyword (default=0)
		ele	element number of the sdataset image to place at the ddataset image location specified in the PLACE keyword (default=line)
		sys	coordinate system of the line and ele values; specify either F for file (area) coordinates or I for image coordinates (default=F)
PLAce=	location in the ddataset image to place the point specified in the LATLON, STATION or LINELE keyword
	ULEFT		upper-left corner of the image (default when the LINELE keyword is used)
	CENTER		center of the image (default when the LATLON or STATION keyword is used)
STAtion=	station ID to place at the ddataset image 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]; see the TYPE keyword in the STNLIST command for valid station types

Output Keywords

BANd=	b1 b2	bands in the source image to filter; specify b2 only if using FILTER=CLOUD, CORE, DIS or MERGE (b1 default=existing band for single-band images; no b1 default for multiband images; b2 default=b1)
CF=	YES	creates a CF-compliant netCDF file (default)
	NO	creates a netCDF file in the previous (pre-2009.2) format, which is not CF-compliant; the CF=YES/NO keyword is valid only when writing to netCDF format destination datasets; it is ignored when writing to datasets of other formats
ID=	selects from sdataset images with the specified NEXRAD station ID, e.g., MKX
MAG=	lmag emag	line and element magnification of the data; use a positive integer for blowup and a negative integer for blowdown (default=1 lmag)
NAVtype=	RECT	remaps MODIS imagery into a rectilinear projection and applies a bowtie correction using MRTSwath (MODIS Reprojection Tool - Swath, package courtesy of the U.S. Geological Survey); use this keyword only when the source image is MODIS Level 1B or Level 2 data on a remote server with the MRTSwath package installed; this keyword is ignored if used with any other type of data
PROd=	product name for destination image, up to four characters (default=PRD)
SCAle=	prodlo prodhi britlo brithi minimum and maximum product and brightness values for the calibration (prodlo prodhi defaults=dataset_min dataset_max; britlo brithi defaults=0 255)
SIZe=	line ele	number of lines and elements of the sdataset image to copy (default=480 640)
	ALL	copies the entire sdataset image including all bands and the documentation section
TAIl=	lo hi	tail percentage after filtering (default=0 0)
TRACKing=	YES	tracks image if allowed by the server; tracking allows commands to receive data as it's being ingested by the server; commands complete when their data request has been fulfilled; tracking is only supported on some servers (e.g., Area, GVAR and MTSAT) and it can be disabled by the server administrator
	NO	does not track image so server only sends data that is currently available (default=value of MCTRACK environment variable; if MCTRACK is not set, default=value set by server or server administrator)
UNIt=	calibration units for output (default=BRIT)
WL=	l1 l2	filters source image bands with image wavelengths closest to those specified in l1 and l2; valid only with high spectral resolution data, e.g., Aqua AIRS; specify l2 only if using FILTER=CLOUD, CORE, DIS or MERGE (no default for l1; l2 default=l1)
WN=	n1 n2	filters source image bands with image wave numbers closest to those specified in n1 and n2; valid only with high spectral resolution data, e.g., Aqua AIRS; specify n2 only if using FILTER=CLOUD, CORE, DIS or MERGE (no default for n1; n2 default=n1)

Filter and Stretch Keywords

FILter=	filter used to generate the destination image; see the Remarks for more details
	CLEAN	replace bline eline pdiff ldiff
	CLOUD	replace constant
	CORE	brkpnt1 brkpnt2 replace1 replace2
	DIS	brkpnt1 brkpnt2 brkpnt3 brkpnt4 replace
	GRAD
	HIGH1	distance efficiency
	HIGH2
	HOLE	brkpnt1 brkpnt2
	LOW1	distance efficiency
	LOW2	lcoef ecoef
	MERGE	brkpnt1 brkpnt2 constant
	REPLACE	outval bline eline belem eelem inval1..invaln
	SHOT	bline eline pdiff
	SPOT	omcon oacon imcon iacon cmin cmax DISt= TARget=
STRetch=	applies a stretch to sdataset's brightness values
	CONT	contrast stretch (default)
	HIST	bin	histogram stretch; increment, or bin width (default=16)

Remarks

IMGFILT generates a new image by applying a filter to data from a source image or images. The CLOUD, CORE, DIS and MERGE filters use two source datasets; all other filters use only one.

All filters are applied to each data point of an image line. The CLEAN filter is also applied to each line in the image. The HIGH2 and LOW2 filters are applied to each data point, but use surrounding lines and elements in their calculations.

The IMGFILT command automatically applies a contrast stretch to images after the filter process. The range of the stretch is specified with the SCALE keyword. Product values outside the range are set to zero. If no values are supplied, the minimum to maximum product values are stretched from 0 to 255. The tail percentages specified with the TAIL keyword clip the ddataset minimum and maximum data values before the stretch. Use this option to sharpen an image.

The ddataset has a generated product source type, PRD, and a 1-byte data calibration type, BRIT. The data point values in brightness units. The image file's calibration allows you display native product values by specifying the native units in the IMGPROBE command.

Use IMGOPER to perform arithmetic operations on individual data points.

You can use IMGFILT to create a netCDF image file. To do so, the destination dataset must be NCDF-format and IMAGE-type. See the Remarks section in the DSSERVE command for more information.

Each option for the FILTER keyword is described below. Positional parameters and the equation used by the filter to generate the destination image are listed. Defaults for the filters are based on brightness (UNIT=BRIT).

CLEAN

This option cleans an image by first applying a shot noise filter to each data point in the source image, and then locating and replacing bad lines. Each data point is compared to the data points to its left and right and is replaced by the shot noise filter if the values are significantly different. The average value of each line is then compared to the lines above and below and replaced if it is significantly different.

Positional parameters:
replace	AVE	average of surrounding values (default)
	MIN	sdataset minimum value
	MAX	sdataset maximum value
bline	beginning line in the source image to clean (default=first line)
eline	ending line in the source image to clean (default=last line)
pdiff	absolute difference between a data point's value and the value of the data points to its left and right (default=15)
ldiff	percentage difference between a line's average value and the average value of the line above and below (default=15)
Equation for each ddataset data point:
	if (the difference between the sdataset data point and the data points to its left and right < pdiff) then ddataset = sdataset else ddatset = replace
Equation for each ddataset line:
	if (the difference between sdataset line average and the previous line is < ldiff) and (deviation of data point values on the sdataset line is > 0) then ddataset = sdataset else ddataset = replace

CLOUD

This option applies a cloud filter to an image by comparing each data point to the data points of another image. Use this filter to mask off a portion of the first source image.

Positional parameters:
replace	replacement value (default=minimum value in either sdataset)
constant	additive constant (default=0)
Equation for each ddataset data point:
	if (sdataset1 > sdataset2 + constant) then ddataset = sdataset1 else ddataset = replace

CORE

This option applies a core filter to two images by comparing data point values to the specified breakpoint values. The resulting image has only two values.

Positional parameters:
brkpnt1	sdataset1 breakpoint value (default=minimum value in either sdataset)
brkpnt2	sdataset2 breakpoint value (default=maximum value in either sdataset)
replace1	success condition replacement value (default=maximum value in either sdataset)
replace2	failure condition replacement value (default=minimum value in either sdataset)
Equation for each ddataset data point:
	if (sdataset1 > brkpnt1) and (sdataset2 > brkpnt2) then ddataset = replace1 else ddataset = replace2

DIS

This option applies a discriminate filter to two images by comparing data points in each image to different high and low breakpoints. Use this filter to mask off a portion of the first source image.

Positional parameters:
brkpnt1	low end breakpoint value for sdataset1 (default=minimum value in either sdataset)
brkpnt2	high end breakpoint value for sdataset1 (default=maximum value in either sdataset)
brkpnt3	low end breakpoint value for sdataset2 (default=minimum value in either sdataset)
brkpnt4	high end breakpoint value for sdataset2 (default=maximum value in either sdataset)
replace	failure condition replacement value (default=minimum value in either sdataset)
Equation for each ddataset data point:
	if (brkpnt1 < sdataset1 < brkpnt2) and (brkpnt3 < sdataset2 < brkpnt4) then ddataset = sdataset1 else ddataset = replace

GRAD

This option applies a gradient filter to the source image.

Equation for each ddataset data point:

ddataset = ABSOLUTE(sdataset_n - (sdataset_n+1) )

HIGH1

This option applies a one-dimensional high-pass filter to each data point in the source image. It eliminates low-frequency deviations by clustering them around the distribution's midpoint. A sample average is determined using values to the left and right of the source data point and the percentage of filter efficiency.

Positional parameters:
distance	sample length surrounding the source data point; used for sample average (default=50)
efficiency	filter efficiency (default=100)

Equation for each ddataset data point:

ddataset = (sdataset - (sample average) + (sample midpoint))

HIGH2

This option applies a two-dimensional high-pass filter to each data point in the source image. It eliminates low-frequency deviations by clustering them around the distribution's midpoint. A sample average is calculated by the program using values to the left, right, above and below the source data point.

Equation for each ddataset data point:

ddataset = (sdataset - (sample average) + (sample midpoint))

HOLE

This option searches for missing data and fills the holes in the image using the average of the values to the left and right of the source data point.

Positional parameters:
brkpnt1	low end breakpoint value (default=minimum sdataset value)
brkpnt2	high end breakpoint value (default=maximum sdataset value)
Equation for each ddataset data point:
	if (brkpnt1 < sdataset < brkpnt2) then ddataset = (average of the values to the left and right of the source data point) else ddataset = sdataset

LOW1

This option applies a one-dimensional low-pass filter to each data point of the source image. It eliminates high-frequency deviations by replacing the source image data values with the average of the values to the left and right of the source data point. The sample average is determined using the percentage of filter efficiency.

Positional parameters:
distance	sample length in pixels surrounding the source data point; used for sample average (default=50)
efficiency	filter efficiency (default=100)

Equation for each ddataset data point:

ddataset = (sample average)

LOW2

This option applies a two-dimensional low-pass filter to each data point in the source image. It eliminates high-frequency deviations by replacing the source image data values with the average of the values in the sample defined with the line and element coefficients.

Positional parameters:
lcoef	line coefficient; 0.0 < lcoef < 1.0 (default=0.5)
ecoef	element coefficient; 0.0 < ecoef < 1.0 (default=lcoef)

Equation for each ddataset data point:

ddataset = (sample average)

MERGE

This option merges two images by selecting the sdataset1 value for each data point if its value is between the specified breakpoints. Otherwise it selects the sdataset2 value minus the specified constant.

Positional parameters:
brkpnt1	low end breakpoint value (default=minimum value in either sdataset)
brkpnt2	high end breakpoint value (default=maximum value in either sdataset)
constant	subtractive constant (default=0)
Equation for each ddataset data point:
	if (brkpnt1 < sdataset1 < brkpnt2) then ddataset = sdataset1 else ddataset = (sdataset2 - constant)

REPLACE

This option replaces selected data points in the defined region of the source image with the specified replacement value.

Positional parameters:
outval	replacement value (default=0)
bline	beginning line in the source image region (default=first line)
eline	ending line in the source image region (default=last line)
belem	beginning element in the source image region (default=first element)
eelem	ending element in the source image region (default=last element)
inval1..invaln	source image values in the region to replace with outval; specify values in the list format, e.g., val1 val2 val3 etc., and/or a range format, e.g., bval-eval (default=0-255)
Equation for each ddataset data point:
	if sdataset lies outside the region defined by the line and element ranges, or its value is not in inval1..invalN then ddataset = sdataset else ddataset = outval

SHOT

This option cleans an image by applying a shot noise filter to each data point in the source image. Each data point is compared to the data points to its left and right and is replaced if the values are significantly different.

Positional parameters:
bline	beginning line in the source image to clean (default=first line)
eline	ending line in the source image to clean (default=last line)
pdiff	maximum percentage of the product range specified in the SCALE keyword to allow before a new value for the data point is derived using the average of the data points to its left and right (default=15)
Equation for each ddataset data point:
	if the difference between sdataset and the data points to its left and right is < pdiff then ddataset = sdataset else dataset = (average of the data points to its left and right)

SPOT

This option illuminates or darkens one or more spots on an image. The locations and sizes of the spots are determined by the TARGET and DIST keywords.

Positional parameters:
omcon	value by which to multiply the data points located outside the spots defined by the TARGET and DIST keywords (default=0.0)
oacon	value to add to the data points located outside the spots defined by the TARGET and DIST keywords (default=0.0)
imcon	value by which to multiply the data points located inside the spots defined by the TARGET and DIST keywords (default=1.0)
iacon	value to add to the data points located inside the spots defined by the TARGET and DIST keywords (default=0.0)
cmin	conditional minimum value for data points located inside the spots defined by the TARGET and DIST keywords; data points with values less than cmin are treated as if they are outside the spots (default=no minimum)
cmax	conditional maximum value for data points located inside the spots defined by the TARGET and DIST keywords; data points with values greater than cmax are treated as if they are outside the spots (default=no maximum)
Equation for each ddataset data point:
	if sdataset is located outside the spots defined by the TARGET and DIST keywords then ddataset = (sdataset1 * omcon) + oacon else ddataset = (sdataset1 * imcon) + iacon

Keywords valid only with the SPOT filter:

DISt=	dist1[unit1] . . distN[unitN]		radial distance(s) from the target(s); the distance value(s) determine the size of the spot(s); run CU LIST to list valid units (default=0[KM] for first value; last specified value for all subsequent values)
TARget=	tar1 . . tarN target location(s); these determine the location(s) of the spot(s); valid input formats are:
		lat lon	latitude and longitude, e.g., 43:08:26 89:20:43
		station	station ID or ID number, e.g., MSN or 72645
		'city,st,co'	city, where st and co are the two-letter state and country codes for the city, e.g., 'MADISON,WI,US' or 'TORONTO,,CA'

Examples

IMGFILT GOES7/VIS.1 LOCAL/AREA.1

This entry applies a contrast stretch to the brightness data in the image in position 1 of dataset GOES7/VIS. The resulting image is placed in position 1 of dataset LOCAL/AREA.

IMGFILT BLIZZARD/G7-IR-4K.2 BLIZZARD/CLEAN.2 FILTER=CLEAN STATION=DCA

This entry applies clean and shot noise filters and contrast stretch to the image in position 2 of dataset BLIZZARD/G7-IR-4K. The resulting image is placed in position 2 of dataset BLIZZARD/CLEAN. The destination image is 480 lines by 640 elements and centered over Washington, DC.

IMGFILT COMPOSITE/MOSAIC LOCAL/MOSAIC.1 FILTER=HOLE 0 1 LATLON=-90 0

This entry applies a hole filter to the most recent image in dataset COMPOSITE/MOSAIC. The resulting image is placed in position 1 of dataset LOCAL/MOSAIC. The filter averages data points that have brightness values between 0 and 1 (inclusive) to fill holes and gaps in the data. The destination image is 480 lines by 640 elements and centered over the South Pole.

IMGFILT A/A.8101 A/A.4000 FILTER=REPLACE 119 2001 2209 3362 3726

This entry replaces the brightness values in a region of the image in position 8101 of dataset A/A. The brightness values between image lines 2001 and 2209 and elements 3362 and 3726 are replaced with a new brightness value of 119. The resulting image is 480 lines by 640 elements. It is placed in position 4000 of dataset A/A.

IMGFILT GOES9/IR A/A.4001 BAND=3 FILTER=LOW2 STRETCH=HIST STATION=IRK SIZE=600 600 PROD=LO-2 UNIT=TEMP

This entry applies a two-dimensional low pass filter and histogram stretch to the band 3 temperature data in the most recent image in dataset GOES9/IR. The resulting 600 line by 600 element image is placed in position 4001 of dataset A/A, has the product name LO-2, and is centered over Kirksville, MO.

IMGFILT EASTS/CONUS LOCAL/AREA.1 BAND=1 STA=KCHI MAG=-3 -6 FILT=SPOT .5 X 1.25 TARGET=BIS OAX TLX MKX LSX MRX PBZ RAX DIST=124[NMI]

This entry applies a spot filter to band 1 of the most recent image in dataset EASTS/CONUS. The resulting image is centered on Chicago, blown down by a factor of 3 in the line direction and 6 in the element direction, and is placed in position 1 of dataset LOCAL/AREA. The filter sets the brightness values of pixels outside the spots defined by the TARGET and DIST keywords to 50% of their original values, and pixels inside the spots to 125% of their original values. In this case, the spots show the 124 nautical mile coverage of the NEXRAD "short range" (S Rng) reflectivity products for NEXRAD stations BIS, OAX, TLX, MKX, LSX, MRX, PBZ and RAX.

[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]