McIDAS-X User's Guide
Version 2024.1
[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]
Copies image data from one dataset to another.
IMGCOPY sdataset ddataset [keywords]
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) |
|
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 |
|||
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 |
BANd= |
image band number to copy (default=existing band for single-band images; no default for multiband images); if there are multiple resolutions among the bands they are all copied at the lowest resolution; some servers support copies of only single bands or ALL; see below for servers that also support copies of selected and/or ranges of bands:
|
|
|
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 |
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 |
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 or AVHRR Level 1b 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) |
|
RECT |
remaps MODIS imagery into a Rectangular 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 |
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 |
use to copy a single band, including the documentation, from a multibanded image; the output image is the same size as the source image unless the resolution is decreased by using MAG= with negative value(s) |
STYpe= |
VISR |
reduces 2-byte data to 1-byte brightness data; does not include the image documentation unless DOC=YES or SIZE=SAME is also specified; do not use STYPE=VISR with BAND=ALL or SIZE=ALL; see the Remarks |
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 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 |
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) |
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) |
CONTinue= |
YES |
continues copying of images when using ALL= or REPEAT= even if one or more of the source images is skipped because it does not contain the specified geographical region (default=NO, meaning that IMGCOPY stops if it encounters a source image that does not contain the specified geographical region); this keyword's YES option is valid only with Area or raw GVAR format images |
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) |
|
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. If the destination dataset is Area-format, the number of elements in the output Area file will be rounded up, if necessary, to a multiple of 4. For example, if SIZE=1950 1950 is specified, the size of the output Area is 1950 x 1952.
If you specify a negative value in the MAG= keyword, IMGCOPY uses a sampling method to reduce the resolution. For example, if you specify MAG=-2 it copies the top left pixel of the 2x2 block of source image pixels into the destination image, and MAG=-4 copies the top left pixel of the 4x4 block of source image pixels into the destination image. Use the AVGI command if you prefer to use an averaging method to reduce the resolution of local Area files.
The keyword STYPE=VISR converts the original 2-byte data to 1-byte values (BRIT, which are the 0-255 grayscale values). It does not include the image documentation unless DOC=YES or SIZE=SAME is also specified. 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, brightness temperature or albedo. If you do not need the other calibration data (i.e., BRIT values are sufficient for your needs), you can use STYPE=VISR to retain only the grayscale data (and brightness temperatures for infrared bands, with less precision) while reducing the resultant file size.
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. To do so, specify a destination dataset that was created (with the DSSERVE command) with NCDF for its format and IMAGE for its TYPE= value. Use the UNIT keyword in IMGCOPY to select the calibration unit for the netCDF file. Only single-band copies are allowed to netCDF files, so if the source image is multi-band you must use the BAND keyword to select the band for the output netCDF file.
In satellite imagery, the latitude/longitude location of a pixel is determined by where the instrument is pointing. It is often the center of the field of view of the instrument, though the instrument vendor can define the geolocation any way they want. Regardless, in McIDAS it is assumed to be the center. For geographic projections, a pixel is just a point. So there is no notion of dimensionality, and it is again assumed to be the center. For users collocating pixels from different satellites, a larger issue is the viewing angle differences. They can be on the order of several pixels near nadir to tens of pixels away from nadir.
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.
[Search Manual] [Table of Contents] [Go to Previous] [Go to Next]