Package noaa.coastwatch.tools

Class cwcoverage

java.lang.Object
noaa.coastwatch.tools.cwcoverage
public class cwcoverage extends Object

The coverage tool creates an earth data coverage map.

Name

cwcoverage - creates an earth data coverage map.

Synopsis

cwcoverage [OPTIONS] input1 [input2 ...] output
cwcoverage [OPTIONS] output

General options:

-h, --help
-v, --verbose
--version

Output content and format options:

-a, --noantialias
-b, --background=COLOR
-c, --center=LATITUDE/LONGITUDE
-f, --foreground=COLOR
-s, --size=PIXELS

Dataset boundary options:

-H, --highlight=PATTERN
-l, --labels=LABEL1/LABEL2/...
-m, --map=OUTPUT
-x, --box=COLOR

Ground station options:

-C, --stationcolor=COLOR
-e, --elevation=DEGREES
-E, --height=KILOMETERS
-L, --stationlabels=LABEL1/LABEL2/...
-S, --stations=LAT1/LON1/LAT2/LON2/...

Description

The coverage tool creates an earth data coverage map by accessing a number of user-specified earth data sets and tracing the boundaries onto an orthographic map projection. The map is output as a PNG graphics file. Approximate satellite ground station coverage boundaries may also be added to the map.

Parameters

Main parameters:

input1 [input2 ...]
The input data files name(s). If none are specified, the output PNG image contains only map graphics and possibly ground station circles (see the --stations option).
output
The output PNG file name.

General options:

-h, --help
Prints a brief help message.
-v, --verbose
Turns verbose mode on. The current status of data rendering is printed periodically. The default is to run quietly.
--version
Prints the software version.

Output content and format options:

-a, --noantialias
Turns off line antialiasing. By default, the edges of lines are smoothed using shades of the drawing color. The use of this option can significantly reduce the size of the output file, while sacrificing visual quality.
-b, --background=COLOR
The map background color. The color is specified by name or hexadecimal value. The default is black.
-c, --center=LATITUDE/LONGITUDE
The map center location. By default, the center location is determined from the data sets.
-f, --foreground=COLOR
The map foreground color. The color is specified by name or hexadecimal value. The default is a gray of 63% RGB intensity.
-s, --size=PIXELS
The coverage map size in pixels. By default, the map size is 512 pixels.

Dataset boundary options:

-H, --highlight=PATTERN
The highlighted input file matching pattern. By default, all input files are highlighted with the box boundary fill and color. With this option, only input files whose names match the pattern are highlighted. The remaining non-matching input file boundaries are drawn using the foreground color.
-l, --labels=LABEL1/LABEL2/...
The labels for each input file. Labels are drawn at the center point of each dataset boundary. By default, no labels are drawn.
-m, --map=OUTPUT
The output file for HTML image map output. The output file contains an HTML fragment with an image map and area polygons for each input file, similar to the following: 
  <map name="coverage_map">
    <area shape="poly" id="region_0" coords="111,64,170,63,179,132,108,134,111,64" />
    <area shape="poly" id="region_1" coords="75,106,132,109,133,179,66,174,75,106" />
    <area shape="poly" id="region_2" coords="121,124,183,121,192,188,119,191,121,124" />
  </map>
The map may be used in an HTML document in conjunction with the output PNG coverage image to provide users with a clickable interface for area of interest selection.
-x, --box=COLOR
The box boundary and fill color. The color is specified by name or hexadecimal value. The default is a color close to cyan.

Ground station options:

-C, --stationcolor=COLOR
The ground station circle color. This option is only used in conjunction with the --stations option. By default, the box color is used (see the --box option).
-e, --elevation=DEGREES
The minimum elevation of the ground station antenna above the horizon in degrees. This option is only used in conjunction with the --stations option. By default, the antenna elevation is set to 5 degrees, which approximates a NOAA HRPT tracking station with a 1.7 m diameter dish.
-E, --height=KILOMETERS
The orbital height of the theoretical satellite above the earth surface in kilometers. This option is only used in conjunction with the --stations option. By default, the satellite orbital height is set to 846.5 km which approximates a NOAA polar orbiter.
-L, --stationlabels=LABEL1/LABEL2/...
The ground station labels. This option is only used in conjunction with the --stations option. When specified, each ground station location is labelled with its corresponding label. By default, no labels are drawn.
-S, --stations=LAT1/LON1/LAT2/LON2/...
A list of ground station locations. For each ground station, a circle is drawn on the Earth, centered at the ground station. The circle shows the approximate area that a theoretical satellite can view from orbit while in sight of the station, ie: the ground station's real-time coverage area. See the --height and --elevation options to control the orbital parameters of the theoretical satellite. Note that the swath width of the satellite sensor is not taken into account in drawing the circle, so the area should be used as a conservative estimate of satellite coverage.

Exit status

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

  • Invalid command line option
  • Unrecognized color name
  • Invalid map center or station location
  • Mismatch between label and file or station count

Examples

As an example, the following command shows the creation of a coverage plot of the ER and SR CoastWatch regions covering the US East coast:

   phollema$ cwcoverage -v --labels ER/SR 2004_155_1147_n15_er.hdf 
     2004_155_1147_n15_sr.hdf east_coast.png
 
   cwcoverage: Reading input 2004_155_1147_n15_er.hdf
   cwcoverage: Reading input 2004_155_1147_n15_sr.hdf
   cwcoverage: Writing east_coast.png
Since:
3.1.6
Author:
Peter Hollemans

  • Method Details

    • getVisibility

      public static double getVisibility(double radius, double height, double elev)
      Calculates the angle of visibility for a satellite capture station. The visibility angle is the angle between a line from the center of the earth to the ground station and a line from the center of the earth to the satellite.
      Parameters:
      radius - the radius of the earth in kilometers.
      height - the height of the satellite above the surface in kilometers.
      elev - the elevation for the satellite receiver above the horizon in degrees.
      Returns:
      the visibility angle in degrees.

    • getCircle

      public static LineFeature getCircle(EarthLocation center, double radius, int segments)
      Creates a circle of earth locations centered at the specified location.
      Parameters:
      center - the center location.
      radius - the circle radius in degrees. The circle radius is essentially the great circle distance between the center of the circle and the radial points.
      segments - the number of segments around the circle.
      Returns:
      an earth vector specifying the circle points.

    • main

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