Package noaa.coastwatch.tools

Class cwgraphics

java.lang.Object

noaa.coastwatch.tools.cwgraphics

public class cwgraphics
extends Object

The graphics tool creates earth data annotation graphics.

Name

cwgraphics - creates earth data annotation graphics.

Synopsis

cwgraphics [OPTIONS] input
cwgraphics [OPTIONS] input output

Options:

-c, --coast=PLANE
-g, --grid=PLANE
-h, --help
-l, --land=PLANE
-p, --political=PLANE
-v, --verbose
-V, --variable=NAME
--version

Description

The graphics tool creates earth data annotation graphics in the form of a byte-valued variable. Each output byte in the new variable contains 8 bits, one for each of 8 possible graphics planes numbered 1 to 8 from the least significant bit to the most significant bit. The graphics planes are independent of one another and encode a bitmask for graphical data annotation, where a bit value of 0 is interpreted as 'off' and a bit value of 1 as 'on'. In this way, 8 separate binary bitmasks may be encoded into one byte value. For example a pixel with graphics planes 2, 3, and 4 on is encoded as:

    Binary value  = 00001110
    Decimal value = 14
 

Following the standard convention for graphics planes in CoastWatch product files, the default behaviour places latitude/longitude grid graphics in plane 2, coastline graphics in plane 3, and land mask graphics in plane 4. Coastlines are derived from GSHHS coastline data, and land polygons are filled GSHHS polygons (see the GSHHS website). The default output variable name is 'graphics'. These defaults may be changed using command line options to alter the planes used for each type of annotation, to exclude or add some types of annotation, and to change the output variable name.

Once the graphics planes are created, they may be used as overlay graphics for rendered earth data images. The graphics byte data may be exported using the cwexport tool for use in other software packages, or may be used in the cwrender tool with the --bitmask option.

Parameters

Main parameters:

input

The input data file name.

output

The output file name. If the output file name is not specified, the input file name is used and the new variable must not already exist in the input file.

Options:

-c, --coast=PLANE

The coastline graphics plane. The default is plane 3. If the plane value is 0, no coast graphics are rendered.

-g, --grid=PLANE

The grid line graphics plane. The default is plane 2. If the plane value is 0, no grid graphics are rendered.

-h, --help

Prints a brief help message.

-l, --land=PLANE

The land mask graphics plane. The default is plane 4. If the plane value is 0, no land graphics are rendered.

-p, --political=PLANE

The political line graphics plane. There is no default plane for political lines, as they are normally excluded from rendering.

-v, --verbose

Turns verbose mode on. The current status of data rendering is printed periodically. The default is to run quietly.

-V, --variable=NAME

The output variable name. The default name is 'graphics'.

--version

Prints the software version.

Exit status

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

• Invalid command line option
• Invalid input or output file names
• Unsupported input file format
• Output variable already exists in input file

Examples

The following shows the creation of a standard set of graphics planes using cwgraphics. The file being acted upon is a CoastWatch HDF file created using the graphical cwmaster tool:

   phollema$ cwgraphics -v bc_coast.hdf
 
   [INFO] Reading input bc_coast.hdf
   [INFO] Creating graphics variable
   [INFO] Rendering overlay at plane 2
   [INFO] Rendering overlay at plane 3
   [INFO] Rendering overlay at plane 4
 

Another example below shows the alteration of the default options. Only coastline and political line graphics are rendered to plane 1, and the output variable is named 'geography':

   phollema$ cwgraphics -v --land 0 --grid 0 --coast 1 --political 1 
     --variable geography bc_coast.hdf

   [INFO] Reading input bc_coast.hdf
   [INFO] Creating geography variable
   [INFO] Rendering overlay at plane 1
   [INFO] Rendering overlay at plane 1
   [INFO] Rendering overlay at plane 1
 

Since:

3.1.5

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.