gsubset - generate subsets based on earth transform coordinates

gsubset - Generate subsets based on earth transform coordinates

SYNOPSIS

gsubset  [ parameter=value ]  [ inputfile outputfile ]
gsubset  [ parameter=value ]  [ inputfile ... directory ]

Parameters are: include_vars, range_pairs, master_file, percent_width, percent_height, unit_affine, wait_variable, hang_secs, instantiate.

DESCRIPTION

gsubset generates dataset subsets based on earth transform coordinates, rather than on image coordinates. The conversion from 0-relative image line/sample dimension to 0-relative earth transform coordinates is simple. Suppose that a given image variable has dimensions vline and vsamp. Then

earth transform y = image line * vline->scale + vline->offset
earth transform x = image samp * vsamp->scale + vsamp->offset

scale and offset are built-in dimension attributes initially set by TeraScan ingest functions.

This function is most useful for subsetting multi-resolution data, such as that from geostationary satellites, like GOES-8.

gsubset is most useful for generating several views of the same input dataset, without actually moving any data. For example, from the same GOES-8 full disk datasets, subsets covering just the continental US, just the northern hemisphere, and just the southern hemisphere can be generated.

gsubset is very similar to subset, except that all earth surface dimensions are clipped, and that clipping is based on earth transform coordinates. In the case of GOES-8 data, earth transform coordinates are absolute visible channel coordinates.

Earth transform coordinates can be specified in two ways: (1) by two range pairs (min y, max y, min x, max x), and (2) by master file. If a master file is supplied, it is used to compute the earth transform coordinates of the limiting box. If a master is not supplied, then the user is required to supply the range pairs defining the limiting box.

gsubset generates subsets only when the area specified in terms of earth transform coordinates meets percent width and height coverage criteria. If percent_width and percent_height are both 100, the limiting box must be entirely inside all the earth locatable input image variables.

gsubset can homogenize output subsets so they can be assembled with no earth location anomalies. If parameter unit_affine=yes, then the et_affine attribute in the output subsets is set to unity, and compensating changes are made to all image dimension scale and offsets. If unit_affine=no, then the ef_affine attribute is copied from each input dataset to corresponding output subset without change.

If the input dataset contains the progress variable dim_counts, gsubset can wait until progress is beyond the subset area before exiting. gsubset will only wait if the parameter wait_variable is set; gsubset assumes that the wait_variable corresponds to the first entry in dim_counts. For GOES GVAR, gvar_ch1 must be used as the wait_variable, if waiting is desired. If gsubset is waiting on progress, the hang_secs parameter is used so gsubset does not hang forever. If progress does not change for hang_secs, gsubset stops waiting and proceeds toward completion.

PARAMETERS

include_vars: List of variables to include in the output subsets. If the list is prefixed with a minus sign, the listed variables are excluded from the subsets. Wildcards * and ? are allowed. The default is to include all variables.

master_file: OPTIONAL. Name of map projection dataset used to compute the earth transform coordinates of the subset area box. The default is no master.

range_pairs: Minimum and maximum 1-relative limits for earth transform line (y) and sample (x), e.g., ymin ymax xmin xmax. Limits are 1-relative. Minimums must not be greater than corresponding maximums. There is no default.

percent_height: OPTIONAL. Minimum acceptable subset area height coverage by the input data. Valid range is [0, 100]. The default is 100 percent.

percent_width: OPTIONAL. Minimum acceptable subset area width coverage by the input data. Valid range is [0, 100]. The default is 100 percent.

unit_affine: OPTIONAL. Controls whether or not the et_affine attribute in output subsets is going to be set to unity. Valid responses are [yes and no]. The default is yes.

wait_variable: OPTIONAL. Used only if the input dataset contains the progress vector dim_counts, and waiting on progresss is desired. wait_variable must be the variable corresponding to the first element of dim_counts. The default is no waiting.

hang_secs: OPTIONAL. Used only if wait_variable is set. Number of seconds to wait before deciding progress is permanently stalled. The minimum valid value is 5 seconds. The default is 60 seconds.

instantiate: Indicates that the variable data is to be copied over to the subsets. Valid responses are [yes and no]. The default is no.

EXAMPLES

The following range_pairs are good choices for GVAR image subsets:

 2985  6495 9260 17730 - Continental US
 2815 10110 8180 22010 - Extended Northern Hemisphere
 2595 13390 5900 24810 - Full Disk
 2815 7790  8180 22015 - Northern Hemisphere
10045 12480 8180 22010 - South Southern Hemisphere

NOTES

gsubset cannot instantiate subsets of datasets that are not completely created, e.g., during live ingest. gvsend can be used to generate instantiated subsets of live GVAR data being ingested by gvarin.

Last Update: $Date: 2002/05/07 23:21:07 $