Unidata - To provide the data services, tools, and cyberinfrastructure leadership that advance Earth system science, enhance educational opportunities, and broaden participation.

DataToolsCommunityDownloadsSupportProjectsAbout Us

•

IMGCOPY

Copies image data from one dataset to another.

Format

IMGCOPY sdataset ddataset [keywords]

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 (no default for group/descriptor or alias ; default=0 for position)
ddataset	destination ADDE dataset name and position; specify one of the following formats:
		group/descriptor.position alias.position
	use only positive integers or the default for position ; to use the default position, do not specify .position (no default for group/descriptor or alias ; position default=the position following the most recent image)

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 keywords; use one of the following:
	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

Image Selection Keywords

DAY=	selects from sdataset images with the specified day
ID=	selects from sdataset images with the specified NEXRAD station ID, e.g., MKX
RTIme=	bmin emin	selects from sdataset images within the specified range of minutes in the current hour; overrides the TIME keyword
TIMe=	btime etime	selects from sdataset images within the specified time range
	btime etime C	copies all POES data for the specified time range; valid only with real-time POES data on an SDI server; cannot be used with LATLON, LINELE, PLACE, STATION, or SIZE keyword

Output Keywords

BANd=	image band number to copy (default=existing band for single-band images; no default for multiband images); if the source image is AIRS Level 1b data in HDF format, you can copy a range of bands by specifying two values that indicate the beginning and ending bands; if the source image is GVAR raw data on an SDI server, MODIS Level 1b data in HDF format, or real-time segmented Meteosat Second Generation Level 1.5 files transmitted by EUMETSAT, you can copy selected bands by specifying them in the same format as frames are specified in the LS command, e.g., BAND=2 5 for bands 2 and 5, and BAND=1 3-6 10 for bands 1, 3, 4, 5, 6 and 10; if there are multiple resolutions among the bands they are all copied at the lowest resolution
	ALL	copies all bands; if there are multiple resolutions among the bands they are all copied at the lowest resolution; BAND=ALL is not valid with STYPE=VISR
DOC=	NO	does not include image documentation when copying the sdataset image data (default)
	YES	includes image documentation; specify DOC=YES to include necessary calibration values when copying POES images
GAUge=	percent	displays the system's progress during the image copy; specify percent as a number between 0 and 50 to control how often status messages are displayed; for example, if you specify 25, a message is shown when the copy is 25%, 50%, and 75% complete
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=	LALO linc einc	use lat/lon navigation instead of the regular (native) navigation; this keyword is valid only if the source image is area format; linc and einc specify the image line and element increments, e.g., NAVTYPE=LALO 4 3 requests lat/lon nav using the data from every fourth line and every third element (default=use native nav; if you specify LALO, lat/lon nav is used and the linc and einc defaults are the computed values that result in using the largest number of data points allowable without exceeding the max size of the AUX block)
OVERride=	NO	does not copy the image if the most recent image in ddataset contains the same date, time and band (default)
	YES	copies the image to the ddataset position following the most recent image even if the date, time and band are same; this keyword is ignored if a position number is specified in ddataset
SIZe=	line ele	number of lines and elements to copy (default=480 640 unless copying POES data and specifying the C option with the TIME keyword)
	ALL	copies the entire sdataset image including all bands and documentation; if the image has multiple bands with different sizes and resolutions (Stretched Data Format files on SDI servers, for example), all bands are copied at the lowest resolution and smallest size; the only other keywords valid with SIZE=ALL are DAY, RTIME, TIME, ALL, REPEAT, and CYCLE
	SAME	retains the original image size; can be used to copy a single band from a multibanded image
STYpe=	VISR	reduces 2-byte data to 1-byte brightness data without image documentation; do not use with BAND=ALL or SIZE=ALL; see the Remarks
UNIT=	calibration unit for the output image file; use this keyword with GEOT- and NCDF-format destination datasets; to determine available units, display the source image and run the D command (default=primary calibration unit in the source image)
WL=	bwl ewl	copies all bands with image wavelengths in the range bwl to ewl; valid only with high spectral resolution data, e.g., Aqua AIRS
WN=	bwn ewn	copies all bands with image wave numbers in the range bwn to ewn; valid only with high spectral resolution data, e.g., Aqua AIRS

Loop Maintenance Keyword

CYCle=

inc tol

updates the destination dataset by copying the image specified in sdataset to the ddataset position determined by the following formula:

position=modulus((time-tol)/inc, numpos)+1

see the Remarks (default=1:00 0, meaning a 1-hour increment and no time tolerance)

Multiple Copy Keywords

ALL=	YES	copies multiple sdataset images into ddataset positions; if the number of positions is greater than or equal to the number of images, all sdataset images are copied in time order with the oldest image in ddataset position 1; if the number of positions is less than the number of images, images are copied to all positions with the most recent image in the last ddataset position, the second most recent image in the previous position, etc; this keyword overrides the positions specified in sdataset and ddataset
	NO	does not copy multiple images (default)
REPeat=	number of sdataset images to copy; the image specified in sdataset is copied to the position specified in ddataset , the next image is copied to the next position, etc.; this keyword is valid only if the position numbers for sdataset and ddataset are positive integers (default=1)

Remarks

By default, the upper-left 480 lines and 640 elements of the sdataset image are copied to the specified position in ddataset . Use the keywords LATLON, LINELE, STATION and PLACE to specify different locations in the sdataset or ddataset images. Use the keyword SIZE to specify a different line and element size and the keyword MAG to blowup or blowdown the image.

Use the keyword STYPE=VISR to convert the original 2-byte data to 1-byte brightness data without image documentation. 2-byte image data is usually a raw value which can be operated on with calibration coefficients to convert the data to other values such as radiance, temperature or albedo. If you do not need documentation or values other than albedo, use this keyword.

The keywords TIME and RTIME select an image to copy. They allow you to limit image selection to a specific time range. This is useful for choosing an image when new images are received frequently, such as GOES images during a Rapid Scan schedule. These keywords also allow you to spread out the scheduled image copies so scheduler activity is more evenly distributed throughout the hour.

The keyword CYCLE is most useful when used with the time scheduler to copy the most recent image to another dataset. The image is copied to the position in the destination dataset determined by the following formula.

position=modulus((time-tol)/inc, numpos)+1

Time is the image time of the selected image, tol and inc are the time tolerance and increment values specified in the CYCLE keyword, and numpos is the number of positions defined in the destination dataset. The position determined with this keyword overrides the position specified in ddataset .

For example, if the command:

IMGCOPY SAT/GOES-IR4K CLIENT/GOESIR STATION=DCA CYCLE=1:00

is scheduled to run once an hour and five positions are defined in the dataset CLIENT/GOESIR, the 13:00 UTC image in SAT/GOES-IR4K is copied to position 4 in CLIENT/GOESIR, since time=13.0, inc=1.0 and numpos=5 (13.0/1.0=13; 13/5=2 with a remainder of 3; 3+1=4). The 14:00 UTC image is copied to position 5; the 15:00 UTC image is copied to position 1, etc.

If a similar IMGCOPY command is scheduled to run every half-hour, but CYCLE=00:30 and the destination dataset has six positions, the 20:00 UTC image is copied to position 5, since time=20.0, inc=0.5 and numpos=6 (20.0/.5=40; 40/6=6 with a remainder of 4; 4+1=5). The 20:30 UTC image is copied to position 6; the 21:00 UTC image is copied to position 1, etc.

Specify a tol value in the CYCLE keyword only when the exact image times vary in a way that may result in one or more of the images being copied into the position following the desired one. This can happen when the selected image has an image time greater than the ending of the time range defined for the desired position by the inc value and the number of positions in the destination dataset. The tol value adjusts the image time backward in the position calculation equation so the image is copied to the desired position. For example, if you want to copy each hour's "half-past" image (e.g., 00:30, 01:30, ..., 23:30) but the exact image times vary from 25 to 33 minutes past the hour, specify 1:00 for inc and a value of at least 00:04 for tol to ensure that the :30 to :33 images are copied to the correct positions so that none of the :25 to :29 images overwrite :30 to :33 images from the the previous hour. The value specified in tol must be less than one-half the value specified for inc .

You can use IMGCOPY to create a netCDF image file. You can use the UNIT keyword to select the calibration unit for the file. To create a netCDF file, the destination dataset must be NCDF-format and IMAGE-type. See the Remarks section in the DSSERVE command for more information.

Examples

IMGCOPY G8/VIS-CONUS MY/DATA

This entry copies the most recent image in dataset G8/VIS-CONUS to the position following the most recent image in dataset MY/DATA. The destination image is 480 lines by 640 elements with the upper-left corner of the source image placed at its upper-left corner.

IMGCOPY G8/VIS-CONUS.-1 MY/DATA.12 STATION=STL SIZE=600 1000

This entry copies the second most recent image in dataset G8/VIS-CONUS to position 12 in dataset MY/DATA. The destination image is 600 lines by 1000 elements with St. Louis placed at its center.

IMGCOPY G8/VIS-CONUS.5 MY/DATA.1 LATLON=35.5 100.2 PLACE=ULEFT MAG=2

This entry copies the image in position 5 in dataset G8/VIS-CONUS to position 1 in dataset MY/DATA. The destination image is 480 lines by 640 elements, is blown up by a factor of 2 from the source image's resolution, and has earth coordinate 35.5° N, 100.2° W placed at its upper-left corner.

IMGCOPY G8/VIS-GLOBE.5 MY/DATA.1 LINELE=1400 2400 F PLACE=CENTER MAG=-7

This entry copies the image in position 5 in dataset G8/VIS-GLOBE to position 1 in dataset MY/DATA. The destination image is 480 lines by 640 elements, is blown down by a factor of 7 from the source image's resolution, and has file (area) coordinate 1400,2400 placed at its center.

IMGCOPY G8/VIS-GLOBE.5 MY/DATA.1 SIZE=ALL

This entry copies the image in position 5 in dataset G8/VIS-GLOBE to position 1 in dataset MY/DATA. The entire source image, including all bands and the documentation section, is copied to the destination image.

IMGCOPY N14/GAC SCRATCH/POES.9 DAY=#Y TIME=11:45 12:15 BAND=2 SIZE=SAME

This entry copies band 2 of the image in dataset N14/GAC with today's date and an image time between 11:45 and 12:15 UTC to position 9 in dataset SCRATCH/POES. The destination image is the same size and coverage as the source image. If more than one image in the source dataset meets the specified time and date criteria, the most recent of those images is copied. If none of the source dataset's images meets those criteria, no image is copied.

IMGCOPY N14/GAC SCRATCH/POES.9 DAY=#Y TIME=11:45 12:15 BAND=ALL SIZE=900 408

This entry copies all bands of the image in dataset N14/GAC with today's date and an image time between 11:45 and 12:15 UTC to position 9 in dataset SCRATCH/POES. The destination image is 900 lines by 408 elements with the upper-left corner of the source image placed at its upper-left corner. If more than one image in the source dataset meets the specified time and date criteria, the most recent of those images is copied. If none of the source dataset's images meets those criteria, no image is copied.

IMGCOPY N14/GAC SCRATCH/POES.9 DAY=#Y TIME=12:34 12:36 C BAND=ALL

This entry copies all POES satellite data in dataset N14/GAC recorded today between 12:34 and 12:36 UTC. This data is copied to position 9 in dataset SCRATCH/POES. Because the TIME keyword's C option is specified, the command ignores the start times of the images in dataset N14/GAC and instead copies all data recorded during the specified time range. The C option is valid only with POES data on an SDI server. Use the NAVDISP command to preview the data coverage for a time range before copying it with IMGCOPY.

IMGCOPY RADAR/MDR_IMAGES.1 LOCAL/MDR.10 STATION=PIT REPEAT=4

This entry copies four consecutive images in dataset RADAR/MDR_IMAGES to four consecutive positions in dataset LOCAL/MDR. The images in positions 1, 2, 3 and 4 in dataset RADAR/MDR_IMAGES are copied to positions 10, 11, 12 and 13 in dataset LOCAL/MDR, respectively. The destination images are each 480 lines by 640 elements with Pittsburgh placed at the center.

IMGCOPY RADAR/MDR _IMAGES MY/MDR STATION=PIT PLACE=ULEFT ALL=YES

This entry copies multiple images from dataset RADAR/MDR_IMAGES to dataset MY/MDR. The number of images copied depends on the number of images in RADAR/MDR_IMAGES and the available positions in MY/MDR. For example, if RADAR/MDR_IMAGES contains 10 images and MY/MDR has six positions, the 6 most recent images are copied in time order to positions 1 through 6. If RADAR/MDR_IMAGES contains 10 images and MY/MDR has 10 or more positions, all 10 images are copied in time order beginning with the oldest image in position 1. The destination images are each 480 lines by 640 elements with Pittsburgh placed in the upper-left corner.

NOTE: You can run either of the two commands below once an hour from the time scheduler (see commands SKE, SKL and SKU) to copy the current hour's image to another dataset. The only difference between them is that they use different methods of choosing the position in the destination dataset. In the first example, the image is always copied to the position following the most recent image. In the second example, the image is copied to the position determined by this formula:

position=modulus(time/inc,numpos)+1

IMGCOPY RT/GOES-IR MY/GOES LATLON=40 100 RTIME=0 5

This entry copies the image in dataset RT/GOES-IR with an image time between 0 and 5 minutes after the current hour to the position following the most recent image in dataset MY/GOES. The destination image is 480 lines by 640 elements with earth coordinate 40° N, 100° W placed at its center.

IMGCOPY RT/GOES-IR MY/GOES LATLON=40 100 RTIME=0 5 CYCLE=1:00

This entry copies the image in dataset RT/GOES-IR with an image time between 0 and 5 minutes after the current hour to dataset MY/GOES. The destination image is 480 lines by 640 elements with earth coordinate 40° N, 100° W placed at its center. The position number in MY/GOES of the destination image is determined by the formula:position=modulus(time/1,numpos)+1 where numpos is the number of positions in MY/GOES. For example, if MY/GOES has six positions, the 17:00 UTC image is copied to position 6, the 18:00 UTC image is copied to position 1, etc. See the Remarks for additional details and examples.

Contact Us • Site Map • Search • Terms and Conditions • Privacy Policy • Participation Policy

Unidata is a member of the UCAR Office of Programs, is managed by the University Corporation for Atmospheric Research, and is sponsored by the National Science Foundation.

P.O. Box 3000 • Boulder, CO 80307-3000 USA • Tel: 303-497-8643 • Fax: 303-497-8690