Package noaa.coastwatch.tools

Class cwregister2

java.lang.Object

noaa.coastwatch.tools.cwregister2

public final class cwregister2
extends Object

The new registration tool resamples gridded earth data to a master projection using a revised set of high accuracy algorithms.

Name

cwregister2 - resamples gridded earth data to a master projection using a revised set of high accuracy algorithms.

Synopsis

cwregister2 [OPTIONS] input output

Options:

-h, --help
-c, --clobber
-d, --diagnostic
-D, --diagnostic-long
-g, --nogroup
-M, --master=FILE
-m, --match=PATTERN
-p, --proj=SYSTEM
-r, --resolution=SIZE
-S, --savemap
-H, --sensorhint=HINT
--serial
--threads=MAX
-t, --tiledims=ROWS/COLS
-u, --usemap=FILE[/ROW_VAR/COL_VAR]
-v, --verbose
--version

Description

The new registration tool resamples gridded earth data to a master projection using a revised set of high accuracy algorithms. The new tool replaces the old cwregister tool in order to simplify and streamline registration. Specifically, the new tool improves registration by:

1. Selecting the most appropriate resampling algorithm automatically rather than making the user choose
2. Automatically creating an optimal master projection for the input file
3. Performing diagnostics on the accuracy of the resampling algorithm
4. Handling terrain-corrected data with sensor-specific algorithms
5. Performing registration on 2D tiles of data in parallel

Parameters

Main parameters:

input

The input data file name.

output

The output data file name.

Options:

-h, --help

Prints a brief help message.

-c, --clobber

Turns on clobber mode, in which the output file is overwritten even if it already exists. The default is to check if an output file exists and not overwrite it if so.

-d, --diagnostic

Turns on diagnostic mode, in which the output file resampling accuracy is checked and compared to the optimal resampling. The default is to run without diagnostics because diagnostic mode is much slower. The diagnostics calculated are:

• Distance - distance in kilometers from the destination pixel center to the corresponding source pixel center.
• Distance error - the value of (dist - opt) where dist is the distance in kilometers between the destination pixel and mapped source pixel (see above) and opt is the distance in kilometers between the destination pixel and optimal source pixel. The optimal source pixel is the source pixel whose center has the minimum physical distance from the destination pixel center out of all pixels in the input file. Thus the value of (dist - opt) is always positive since dist >= opt.
• Normalized performance metric - normalized value calculated as 1 - (dist - opt)/(dist + opt) where dist and opt are defined above. The normalized metric has a range of [0..1] where 0 is the least optimal resampling and 1 is the most optimal.
• % of suboptimal destination pixels. A suboptimal destination pixel is one where the source pixel mapped to it wasn't the optimal source pixel.

Diagnostic mode also turns on verbose mode.

-D, --diagnostic-long

Turns on long form diagnostic mode. In addition to the diagnostics mentioned above, each suboptimal remapping is printed: destination coordinates, source coordinates, optimal source coordinates, and distance error.

-g, --nogroup

Turns on removal of the group path in variable names. If variable names contain a leading group path ending with '/', the group path is removed.

-M, --master=FILE

The master projection file name. The master file is not modified, only accessed for earth transform parameters. By default an optimal output projection is determined automatically from the input file if no master file is specified.

-m, --match=PATTERN

The variable name matching pattern. The pattern is a regular expression that determines which variables to register, otherwise all variables are registered.

-p, --proj=SYSTEM

The projection system to use for a master. This can be:

• geo - Geographic
• ortho - Orthographic
• mercator - Mercator
• polar - Polar Stereographic
• tm - Transverse Mercator
• utm - Universal Transverse Mercator

An optimal destination master is created using the specified projection system, and is set up with its center location, resolution, and extents matching the input file. If no projection system is specified and no master file is provided, the default is UTM.

-r, --resolution=SIZE

Specifies the pixel resolution for the optimal destination master. The pixel resolution is specified in degrees for a geographic projection or kilometers for all other projections. By default the resolution is automatically determined from the center location of the input file unless a master file is specified (see --master above).

-S, --savemap

Saves the row and column mapping to the output file. These can be used in a later registration run with --usemap to speed up the registration for input files that always have the same source coordinates. The variables 'source_row' and 'source_col' are added to the output file, and specify for each destination pixel, which source row and column they were mapped from.

-H, --sensorhint=HINT

Provides a hint for the sensor for non-invertible transform types to help with the resampling. The default is to automatically detect if sensor-specific handling is needed from the input file. The hints available are 'viirs_mband_edr' and 'viirs_iband_edr', which are not detected automatically.

--serial

Turns on serial processing mode. By default the program will use multiple processors in parallel to process chunks of data.

--threads=MAX

Specifies the maximum number of threads for parallel processing. By default the program will automatically detect the maximum number of threads possible.

-t, --tiledims=ROWS/COLS

Specifies the 2D tile size to use in the output file. This is the size the HDF chunks will be written as. The default is 512 by 512 tiles for all variables.

-u, --usemap=FILE[/ROW_VAR/COL_VAR]

Uses the file to load previously saved row and column mapping variables. The names of the variables are optional, and default to 'source_row' and 'source_col'. The data can be from a previous run of cwregister2, or can be user-generated from some other method -- if so the variables should be saved as int32 type.

-v, --verbose

Runs in verbose mode, printing the current status of data registration rather than running silently.

--version

Prints the software version.

Exit status

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

• Invalid command line option
• Invalid master, input or output file names
• Unsupported master or input file format
• Output file already exists
• Invalid tile dimensions
• No variables found for registration
• Projection system specified is unsupported
• Error during registration computation

Examples

The following shows the registration of a VIIRS level 2 granule to an optimal Mercator projection wih diagnostic output:

   phollema$ cwregister2 --diagnostic --proj mercator --clobber
     VRSLCW.B2018157.213433.hdf VRSLCW.B2018157.213433.mercator.hdf
   [INFO] Opening input file VRSLCW.B2018157.213433.hdf
   [INFO] Creating optimal destination transform
   [INFO] Creating output file VRSLCW.B2018157.213433.mercator.hdf
   [INFO] Creating output variable latitude
   [INFO] Creating output variable longitude
   [INFO] Creating output variable rel_azimuth
   [INFO] Creating output variable sat_zenith
   [INFO] Creating output variable sun_zenith
   [INFO] Creating output variable EV_BandM8
   [INFO] Creating output variable EV_BandM6
   [INFO] Creating output variable EV_BandM11
   [INFO] Creating output variable EV_BandM1
   [INFO] Creating output variable EV_BandM5
   [INFO] Creating output variable EV_BandM2
   [INFO] Creating output variable EV_BandM10
   [INFO] Creating output variable EV_BandM4
   [INFO] Creating output variable EV_BandM3
   [INFO] Creating output variable EV_BandM7
   [INFO] Creating output variable edgemask
   [INFO] Initializing resampling map factory
   [INFO] Source has size 768x3200
   [INFO] Destination has size 1378x4032
   [INFO] Found 8 processor(s) to use
   [INFO] Processing 384 chunks of size 512x512
   [INFO] Performing diagnostic
   [INFO] Diagnostic summary statistics
     Distance (km)       min = 0.002940, max = 1.265793, avg = 0.376542
     Distance error (km) min = 0.000000, max = 0.001918, avg = 0.000000
     Norm perf metric    min = 0.998856, max = 1.000000, avg = 1.000000
   [INFO] Found 22 suboptimal of 28851 samples (0.08%)
   [INFO] Closing files
 

Since:

3.5.0

Author:

Peter Hollemans

Method Summary

Modifier and Type	Method	Description
static void	main(String[] argv)	Performs the main function.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

main

public static void main(String[] argv)

Performs the main function.

Parameters:

argv - the list of command line parameters.