navbox2 - select boxes for use in automatic navigation

navbox2 - Select boxes for use in automatic navigation

SYNOPSIS

navbox2  [ parameter=value ]  [ inputfile outputfile ]

Parameters are: variable, coast_file, box_height, box_width, min_cross_dev, min_feature, max_regions, min_region_perc, min_coast_pts, min_sat_elev, min_good_boxes, debug.

DESCRIPTION

navbox2 selects boxes to be used by nav2 in automatic navigation. Boxes are selected based on how many land/water boundary points they contain, and whether or not the boundary points are too correlated (i.e., the boundary is too straight a line).

navbox2 is similar to the navboxes function, except that nav2 lets the user control box size and shape in terms of image variable pixels. (The boxes selected by navbox always circumscribe whole [1 deg lat, N deg lon] boxes, where N is chosen so the aspect is reasonably square.) Unlike navboxes, navbox2 never selects boxes that extend beyond the input image area.

Also, navbox2 overlaps boxes by 50% of their size, which usually results in a far greater number of boxes. navbox2 avoids having too many boxes (which slows the automatic navigation process down) by eliminating redundant boxes whose land/water boundaries are covered by other qualified boxes.

The boxes selected by navbox2 are written to an output dataset using the following variables: latitude, longitude, delta_lat, delta_lon. The boxes are related to the input dataset by earth location only, NOT by image coordinates. This allows boxes to be selected based on subsets or masters.

PARAMETERS

variable: The name of the variable to use as a base image. The variable must be earth locatable. If the user does not provide the name of a variable, navbox2 will automatically select one.

coast_file: The name of the coastline file from which to select land/water boundary points. Coastline files are normally located in the directory $REFDATA/coast. The default is wdb2.cil, which is a good choice because it includes islands and lakes as well as continental boundaries.

box_height: The box height in terms of image pixels. The valid range is [2, inf]. The default is 100 pixels.

box_width: The box width in terms of image pixels. The valid range is [2, inf]. The default is box_height.

min_cross_dev

Minimum second principal component of land/water boundary points in a given box in order for that box to be selected. This may be thought of as the standard deviation of the points across a line fit through the points. The valid range is [0, inf], although values greater than 2 are strongly recommended. The default is 2.5.

Note, the principal component test is run twice, first using all boundary points, then using only boundary points between regions with size greater than or equal to min_region_perc. Also in the second test, the mean of each region is subtracted off its boundary points before computing the covariance matrix. This helps avoid situations like the following:

                  *            *
                   *            *
                    *            *
                     * +----------*---------------+
                      *|           *              |
                       *            *     LAND    |
                       |*            *            |
                       | *            *           |
                       |  *   WATER    *          |
                       |   *            *         |
                  LAND |    *            *        |
                       |     *            *       |
                       |      *            *      |
                       |       *            *     |
                       +--------*------------*----+
                                 *            *
                                  *            *
                                   *            *

min_feature: Minimum percent land/water feature in a given box. The valid range is [0, 100] percent. The default is 15 percent.; Note, the min_feature test is performed twice, first using all regions, then only using contiguous land/water regions with size greater than or equal to min_region_perc.

max_regions: The maximum number of regions, sorted in decreasing size order, needed to cover 99% of a given box. The valid range is [2, 8]. The default is 4 regions.

min_region_perc: The minimum size of a contiguous land/water region in a given box. The valid range is [0, 100] percent. The default is 10 percent.

min_coast_pts: The minimum number of land/water boundary points in a given box, in order for that box to be selected. The valid range is [1, inf]. The default is the greater of box_height and box_width.

min_sat_elev: The minimum satellite elevation in degrees at the center of a given box, in order for that box to be selected. The valid range is [0, 90]. The default is 0 degrees, which essentially nullifies the test. This parameter is used only if earth location is sensor-based (not projection-based).

min_good_boxes: The minimum number of qualified boxes needed before navbox2 will write the output dataset. navbox2 will fail if there is not at least this many qualified boxes. The valid range is [1, inf]. The default is 1.

debug: Redundant box elimination level. The valid range is [0, 3]. If less than 3, redundant boxes are eliminated by an empty-half rule. If less than 2, redundant boxes are also eliminated by a three-in-a-row rule. If less than 1, redundant boxes are also eliminated by a covered-by-neighbors rule. The default is 0, which removes the greatest number of redundant boxes.

EXAMPLES

In the following example, 50x50 pixel boxes are selected based on an AVHRR input dataset. Since AVHRR channels all have the same spatial resolution, there isn't any real need to select one as opposed to another.

% navbox2 n07.84191.2316 box
variable       : char( 31) ? []
coast_file     : char(255) ? [wdb2.cil]
box_height     : int       ? [100] 50
box_width      : int       ? [50] 50
min_cross_dev  : real      ? [2.5]
min_feature    : int       ? [15]
max_regions    : int       ? [4]
min_region_perc: int       ? [10]
min_coast_pts  : int       ? [50]
min_sat_elev   : real      ? [0]
min_good_boxes : int       ? [1]
n07.84191.2316: Looking for boxes in the LS area [1 377] x [1 628]
n07.84191.2316: 6 boxes selected

% printvar box
include_vars   : char(255) ? []
line_per_elem  : char(  3) ? [yes]
list_dims      : char(  3) ? [yes]
printout       : char(  3) ? [no]
Printvar  box  Page 1

               delta_lat       delta_lon        latitude       longitude
       1       0.4227401      -0.5753224         32.5676       -116.9821
       2       0.4212537      -0.5711167        33.44448       -117.9114
       3       0.4206238      -0.5704688        33.65526       -118.1972
       4       0.4129537       -0.579523        34.35877       -120.1887
       5       0.4123401      -0.5833917         34.8428       -120.3398
       6        0.412028      -0.5853628        35.08475       -120.4158

FILES

coastfile

NOTES

The following rules are used for eliminating redundant boxes:

Two overlapping boxes; eliminate box with no land/water boundary
points on one side.

            +------+------+------+
            |cccc  .      |      .
            |   c  .      |      .
            |   ccc.ccc   |      .
            |      .  c   |      .
            |      .  cccc|      .
            |      .     c|      .
            +------+------+------+

Eliminate middle box in a sequence of three overlapping boxes in a vertical or horizontal row.

            +------+------+------+------+
            |cccc  .      |      .      |
            |   c  .      |   ccc.cccccc|
            |   ccc.ccc   |   c  .      |
            |      .  c   |   c  .      |
            |      .  cccc|cccc  .      |
            |      .      |      .      |
            +------+------+------+------+

Similar to previous rule, except that overlapping boxes are not necessarily in a vertical or horizontal row.

Last Update: $Date: 1998/06/23 17:03:29 $