Package noaa.coastwatch.tools

Class cwnavigate

java.lang.Object
noaa.coastwatch.tools.cwnavigate
public final class cwnavigate extends Object

The navigation tool adds navigation corrections to 2D variables in an earth data file.

Name

cwnavigate - adds navigation corrections to earth data.

Synopsis

cwnavigate [OPTIONS] input

Correction options:

-t, --trans=ROWS/COLS
-r, --rotate=ANGLE
-a, --affine=A/B/C/D/E/F
-R, --reset

General options:

-h, --help
-m, --match=PATTERN
-v, --verbose
--version

Description

The navigation tool adds navigation corrections to 2D variables in an earth data file by setting navigation transform parameters. The most basic navigation transform consists of additive translation in the row and column data coordinates. As an example of translation, the following diagram shows coastlines in the earth image data as a '.' (period) symbol and coastlines derived from a GIS database as a '*' (star). Translation has been used to correct the position of the image data:

        ***                              ***
      ... ***         *****                ***         *****
        ... ***     **...                    ***     **
          ... *   .**          ---->           *    **
            . *  **                            *  **
            . ****        row trans = 1        ****
            ....          col trans = -2

A more generic navigation transform consists of a translation combined with a rotation or shear. To represent generic navigation transforms, an affine transform matrix is used to convert "desired" data coordinates to "actual" data coordinates as follows:

   |row'|   |a  c  e|  |row|
   |    |   |       |  |   |
   |col'| = |b  d  f|  |col|
   |    |   |       |  |   |   
   | 1  |   |0  0  1|  | 1 |

where [a..f] are the affine transform matrix coefficients and (row',col') is the actual data coordinates at which the desired data value for (row,col) may be found.

To apply a navigation transform to a 2D variable, the existing navigation transform is read and the new transform is applied to it using matrix multiplication to create a combined transform. As an example, suppose that T1 is the initial navigation transform. The application of an additional transform T2 results in a new transform that is equivalent to:

   T2 (T1 (row, col))

A navigation transform can be applied to a subset of 2D variables, or all variables in the file. Note that satellite channel data or channel-derived variables should be corrected with navigation but GIS-derived variables such as coastline and lat/lon grid graphics should not be corrected. Setting the navigation transform simply establishes a mapping between desired and actual data coordinates — it does not change the gridded data values themselves. Once a navigation transform has been set, other CoastWatch tools in this package will take the transform into account when reading the data.

Parameters

Main parameters:

input
The input data file name. The navigation corrections are applied to the input file in-situ. For CoastWatch HDF files, the corrections are applied to individual variables. No other file formats are supported.

Correction options:

-t, --trans=ROWS/COLS
The translation transform to apply. The actual row and column coordinates are calculated by adding the specified row and column translation to the desired coordinates.
-r, --rotate=ANGLE
The rotation transform to apply. The actual row and column coordinates are calculated by rotating the desired row and column coordinates about the data center by the specified angle in degrees. Positive angles rotate counter-clockwise while negative angles rotate clockwise.
-a, --affine=A/B/C/D/E/F
The explicit affine transform to apply. The coefficients are used to form the affine transform matrix (see the Description section above) which is applied to the existing transform using matrix multiplication.
-R, --reset
Specifies that the existing navigation transform should be reset to the identity. Under the identity transform, no navigation correction is performed.

General options:

-h, --help
Prints a brief help message.
-m, --match=PATTERN
The variable name matching pattern. If specified, the pattern is used as a regular expression to match variable names. Only variables matching the pattern will be navigated. By default, no pattern matching is performed and all variables are navigated.
-v, --verbose
Turns verbose mode on. The status of navigation correction is printed periodically. The default is to run quietly.
--version
Prints the software version.

Exit status

0 on success, > 0 on failure. Possible causes of errors:

  • Invalid command line option
  • Invalid input file name
  • Unsupported input file format
  • Unsupported navigation correction

Examples

The following example shows the navigation correction of a NOAA-15 CoastWatch HDF data file from the Gulf of Mexico:

   phollema$ cwnavigate --trans -3/3 -v --match '(avhrr.*|cloud|sst)' 
     2002_328_1326_n15_ml.hdf

   cwnavigate: Reading input 2002_328_1326_n15_ml.hdf
   cwnavigate: Applying navigation correction to avhrr_ch1
   cwnavigate: Applying navigation correction to avhrr_ch2
   cwnavigate: Applying navigation correction to avhrr_ch4
   cwnavigate: Applying navigation correction to cloud
   cwnavigate: Applying navigation correction to sst

Another example below shows the navigation correction of a NOAA-15 CoastWatch HDF data file from the US east coast:

   phollema$ cwnavigate --trans -2/1 -v 2002_326_1330_n15_er_c2.hdf

   cwnavigate: Reading input 2002_326_1330_n15_er_c2.hdf
   cwnavigate: Applying navigation correction
Since:
3.1.2
Author:
Peter Hollemans

  • Method Details

    • main

      public static void main(String[] argv)
      Performs the main function.
      Parameters:
      argv - the list of command line parameters.