Package noaa.coastwatch.tools

Class cwrender

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

The render tool performs earth data visualization.

Name

cwrender - performs earth data visualization.

Synopsis

cwrender [OPTIONS] input output

Rendering type options:

-c, --composite=RED/GREEN/BLUE
-e, --enhance=VARIABLE1[/VARIABLE2]

General options:

-h, --help
-v, --verbose
--version
--split=EXPRESSION

Output content and format options:

-a, --noantialias
-D, --date=STARTDATE[/ENDDATE]
--font=FAMILY[/STYLE[/SIZE]]
--fontlist
-f, --format=TYPE
--hybridmask=EXPRESSION
-i, --indexed
-I, --imagecolors=NUMBER
-l, --nolegends
-m, --magnify=LATITUDE/LONGITUDE/FACTOR
-o, --logo=NAME
--logolist
-s, --size=PIXELS | full
-T, --tiffcomp=TYPE
-W, --worldfile=FILE

Plot overlay options:

-A, --bath=COLOR[/LEVEL1/LEVEL2/...]
-b, --bitmask=VARIABLE/MASK/COLOR
-C, --coast=COLOR[/FILL]
-d, --cloud=COLOR
-g, --grid=COLOR
-H, --shape=FILE/COLOR[/FILL]
-L, --land=COLOR
-p, --political=COLOR
-S, --nostates
-t, --topo=COLOR[/LEVEL1/LEVEL2/...]
-u, --group=GROUP
-w, --water=COLOR
-X, --exprmask=EXPRESSION/COLOR
--watermark=TEXT[/COLOR[/SIZE[/ANGLE]]]
--watermarkshadow

Color enhancement options:

-E, --enhancevector=STYLE/SYMBOL[/SIZE]
-F, --function=TYPE
-k, --background=COLOR
-M, --missing=COLOR
-P, --palette=NAME
--palettefile=FILE
--palettecolors=COLOR1[/COLOR2[/COLOR3...]]
--palettelist
--paletteimage=FILE
-r, --range=MIN/MAX
--scalewidth=PIXELS
--ticklabels=LABEL1[/LABEL2[/LABEL3/...]]
-U, --units=UNITS
--varname=TEXT

Color composite options:

-B, --bluerange=MIN/MAX
-G, --greenrange=MIN/MAX
-R, --redrange=MIN/MAX
-x, --redfunction=TYPE
-y, --greenfunction=TYPE
-z, --bluefunction=TYPE
--compositehint=HINT

Description

Overview

The render tool performs earth data visualization by converting 2D datasets in the input file to color images. The data values are converted from scientific units to a color using either an enhancement function and color palette or by performing a color composite of three data variables — one for each of the red, green, and blue color components. The resulting earth data plot may have legends displaying the color scale, data origin, date, time, and projection information as well as data overlays showing latitude/longitude grid lines, coast lines, political boundaries, masks, and shapes.

As of version 3.7.1, a hybrid rendering mode is possible that combines both color composite and color enhancement. The color enhancement is rendered on top of the color composite and by default any missing data pixels in the enhancement are transparent and allow the composite pixels to show through. See the --enhance, --composite, and --hybridmask options below for more details.

Overlay colors

Overlay colors may be specified using simple color names such as 'red', 'gray', 'cyan', 'blue', and 'green'. Overlays may be made to appear slightly transparent (allowing the color behind to show through) by following the color name with a colon ':' and a transparency value in percent, for example 'red:50' would make the overlay red with a 50% transparency. Transparency values range from 0 (completely opaque) to 100 (completely transparent).

Colors may also be specified using explicit hexadecimal notation for red/green/blue color components and optional alpha component as follows:

   0xAARRGGBB
     ^ ^ ^ ^          
     | | | ----- Blue              \
     | | ------- Green             |---- Range: 00 -> ff
     | --------- Red               |
     ----------- Alpha (optional)  /

Note that the prepended '0x' denotes a hexadecimal constant, and must be used even though it is not part of the color component values. As an example, the simple color names above may be specified as hexadecimal values:

   0xff0000    red
   0x555555    gray
   0x00ffff    cyan
   0x0000ff    blue
   0x00ff00    green
   0x80ff0000  red, 50% transparent

Rendering order

The data view itself (not including the legends) is rendered in such a way that overlays may overlap each other. For example, latitude/longitude grid lines may fall on top of land polygons because the grid overlay is rendered after the coastline overlay. Knowing the order in which the data and overlays are rendered may answer some questions if the data view doesn't look the way the user expects. The data view is rendered in the following order:

  1. Before any overlay or data, the data view is filled with a background color (normally white) for vector plots or a missing color (normally black) for color enhancement or color composite plots.
  2. Color vectors or image pixels are rendered to the data view. The background or missing color will show though where no vectors or pixels were rendered.
  3. Data overlays are rendered to the view in the following order (see the description of each option below):
    • Cloud mask (--cloud)
    • Bit masks (--bitmask), possibly more than one
    • Expression masks (--exprmask), possibly more than one
    • Water mask (--water)
    • Bathymetric contours (--bath)
    • Land mask (--land)
    • Coastline and filled land polygons (--coast)
    • Political lines (--political)
    • Topography contours (--topo)
    • Shape files (--shape), possibly more than one
    • Latitude/longitude grid lines (--grid)
    • Overlay groups (--group)
    • Markers (--marker)

Parameters

Main parameters:

input
The input data file name.
output
The output image file name. Unless the --format option is used, the file extension indicates the desired output format: '.png', '.jpg', '.tif', or '.pdf'.

Rendering type options:

-c, --composite=RED/GREEN/BLUE
Specifies color composite mode using the named variables. The data variable values are converted to colors using an individual enhancement function for each variable. The data values are scaled to the range [0..255] and used as the red, green, and blue components of each pixel's color. Either this option or --enhance must be specified, or both options for hybrid mode rendering (see the --hybridmask option below).
-e, --enhance=VARIABLE1[/VARIABLE2]
Specifies color enhancement mode using the named variable(s). The data variable values are converted to colors using an enhancement function and color palette. Either this option or --composite must be specified, or both options for hybrid mode rendering (see the --hybridmask option below). If one variable name is specified, the plot shows color-enhanced image data. If two variable names are specified, the plot shows color-enhanced vectors whose direction is derived using the two variables as vector components. See the --enhancevector and --background options for settings that are specific to vector plots.

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.
--split=EXPRESSION
The command line parameter splitting expression. By default, parameters on the command line are specified using a slash '/' character between multiple arguments, for example --coast white/brown. But in some cases, for example when a variable name includes a slash, another character should be used to parse the command line parameters. A common alternative to the slash is a comma ',' character, for example --coast white,brown.

Output content and format options:

-a, --noantialias
Turns off line and font antialiasing. By default, the edges of lines and fonts are smoothed using shades of the drawing color. It may be necessary to turn off antialiasing if the smoothing is interfering with the readability of annotation graphics, such as in the case of very small fonts. This option only effects raster image output formats such as PNG, GIF and JPEG.
-D, --date=STARTDATE[/ENDDATE]
Specifies that the plot legend should be rendered with the given date(s). By default the date is automatically detected from the input file metadata. In some cases the metadata is incorrect or the date and time information is not available. In these cases, the data start and end date can be manually specified by this option, in ISO date/time format 'yyyy-mm-ddThh:mm:ssZ'. For example, Dec 19, 2013 at 11 pm UTC would be specified as '2013-12-19T23:00:00Z'. If the data has no known end date, the end date value may be omitted.
--font=FAMILY[/STYLE[/SIZE]]
The legend and overlay text font with optional style and size. The default is 'Dialog/plain/9'. The font family names available differ based on the fonts installed on a given system. The family names 'Dialog', 'DialogInput', 'Monospaced', 'Serif', and 'SansSerif' are always available and map to certain system fonts at runtime. For a full listing of fonts families available on the system, use the --fontlist option. Valid styles are 'plain', 'bold', 'italic', and 'bold-italic'. For example to use an Arial font available on some systems, bold style, of 12 point size, specify 'Arial/bold/12'. To use a sans serif font with default style and size, specify 'SansSerif'.
--fontlist
Lists the font family names available on the system.
-f, --format=TYPE
The output format. The current formats are 'png' for Portable Network Graphics, 'gif' for Graphics Interchange Format, 'jpg' for Joint Picture Experts Group, 'tif' for Tagged Image File Format with geolocation tags (GeoTIFF), 'pdf' for Portable Document Format, or 'auto' to detect the format from the output file name. The default is 'auto'. The correct choice of output format is governed by the desired use of the rendered image as follows:
  • PNG is a non-lossy compressed image format supported by most web browsers and image manipulation software. It has similar data compression characteristics to GIF and additionally supports 24-bit color images.
  • GIF is a non-lossy compressed format also supported by most web browsers and image manipulation software. The GIF files produced use LZW compression. Images stored in GIF format are run through a color quantization algorithm to reduce the color map to 256 colors or less. Although file sizes are generally smaller than PNG, image quality may be compromised by the reduced color map.
  • JPEG is a lossy compressed format that should be used with caution for images with sharp color lines such as those found in text and annotation graphics. The JPEG format generally achieves higher compression than PNG or GIF resulting in smaller image file sizes.
  • GeoTIFF is a flexible image format with support for earth location metadata. Many popular GIS packages handle GeoTIFF images and allow the user to combine a GeoTIFF base map image with other sources of raster and vector data. The GeoTIFF images generated are non-lossy image data compressed with the deflate algorithm (unless no compression or a different compression scheme is specified using --tiffcomp), and can be larger than the corresponding PNG, GIF, or JPEG. Since GeoTIFF images are generally destined for import into a GIS system, the use of this format turns on the --nolegends option. In general the GeoTIFFs generated are 24-bit colour images, but when no overlays are specified or the --indexed or --imagecolors options are used, a special 8-bit paletted image file is generated and comments describing the data value scaling are inserting into the image description tags (unless JPEG compression is used).
  • PDF is a standard for high quality publishing developed by Adobe Systems and is used for output to a printer via such tools as the Adobe Acrobat Reader. In general PDF files are slightly larger than the equivalent PNG but retain highly accurate vector graphics components such as lines and fonts.
--hybridmask=EXPRESSION
Specifies the mask expression used to determine the transparent pixels in the color enhancement layer during hybrid mode rendering. The mask expression is a boolean expression that evaluates to true where the color enhancement pixels should be transparent, and false where they should be opaque. By default the color enhancement pixels are tested for missing values, and the missing data pixels are set to transparent. The syntax for the expression is identical to the right-hand-side of a cwmath Java expression (see the cwmath tool manual page).
-i, --indexed
Short for --imagecolors 256. See the --imagecolors option below.
-I, --imagecolors=NUMBER
The number of colors to use for the index color model of the data image, up to 256. Normally the data image uses an unlimited number of colors because this achieves the best visual rendering quality. But in some cases it may be desirable to make the output file smaller by limiting the number of colors to <=256 values and using a index color model so that each data pixel can be represented as 8-bit bytes. This option can only be used with PNG, GIF, GeoTIFF, and PDF output formats, and only with color enhancements, not color composites. While in index color mode, antialiasing is turned off.
-l, --nolegends
Turns the plot legends off. By default, the Earth data view is shown in a frame on the left and to the right color scale and plot information legends are drawn. With no legends, the Earth data is simply rendered by itself with no frame, borders, or legends.
-m, --magnify=LATITUDE/LONGITUDE/FACTOR
The magnification center and factor. The data view is set to the specified center and pixel magnification factor. The center position is specified in terms of Earth location latitude and longitude in the range [-90..90] and [-180..180] and the magnification factor (greater than zero) is a decimal value, the image to data pixel ratio. A factor of 1 shows data at its native resolution, where as factors > 1 zoom in and factors < 1 zoom out. By default, the data view shows the entire data field with an optimal magnification factor to fit the desired view size (see --size).
-o, --logo=NAME
The logo used for plot legends. The list of predefined logo names can be listed using the --logolist option. The user can also specify a custom logo file name, which can be any PNG, GIF, or JPEG file. The default is the official NOAA logo.
--logolist
Lists the logo names available on the system.
-s, --size=PIXELS | full | WIDTH/HEIGHT
The Earth data view size in pixels. The data view is normally accompanied by a set of legends unless the --nolegends option is used. By default, the view size is 512 pixels, plus the size of any legends. If 'full' is specified rather than a size in pixels, the view size is set to match the actual full extent of the data, ie: full resolution. If the --magnify option is used, the size of the magnified region may optionally be specified by width and height, otherwise the region is a square.
-T, --tiffcomp=TYPE
The TIFF compression algorithm. The valid types are 'none' for no compression, 'deflate' or 'lzw' for ZIP style compression, 'pack' for RLE style PackBits compression, and 'jpeg' for JPEG compression (JPEG is experimental/beta). By default, deflate compression is used. This option is only used with GeoTIFF output.
-W, --worldfile=FILE
The name of the world file to write. A world file is an ASCII text file used for georeferencing images that contains the following lines:
  • Line 1: x-dimension of a pixel in map units
  • Line 2: rotation parameter
  • Line 3: rotation parameter
  • Line 4: NEGATIVE of y-dimension of a pixel in map units
  • Line 5: x-coordinate of center of upper left pixel
  • Line 6: y-coordinate of center of upper left pixel
World files may be written for any GIF, PNG, or JPEG image. The use of this option turns on the --nolegends option. The convention used in GIS is to name the world file similarly to the image file, but with a different extension. GDAL expects world files with a ".wld" extension, where as ESRI applications expect ".pgw" for PNG, ".gfw" for GIF, and ".jgw" for JPEG. Users should name their world files accordingly.

Plot overlay options:

-A, --bath=COLOR[/LEVEL1/LEVEL2/...]
The bathymetric contour color and levels. The color is specified by name or hexadecimal value (see above). Bathymetric contours are generated for the specified integer levels in meters. If no levels are specified, contours are drawn at 200 m and 2000 m. The default is not to render bathymetric contours.
-b, --bitmask=VARIABLE/MASK/COLOR
Specifies that a mask should be rendered on top of the data image whose pixels are obtained by a bitwise AND with the mask value. The named variable is used to mask the Earth data with the specified color and mask. The color is a name or hexadecimal value (see above). The mask is a 32-bit integer hexadecimal value specifying the mask bits. The bitmask is formed by bitwise ANDing the data value and mask value. If the result of the operation is non zero, the pixel is colored with the bitmask color. This option is useful for overlaying graphics on the data image when the graphics are stored as an integer valued variable in the data set. Such variables include cloud and land mask graphics. Multiple values of the --bitmask option may be given, in which case the masks are applied in the order that they are specified.
-C, --coast=COLOR[/FILL]
The coast line color and optional fill color. The colors are specified by name or hexadecimal value (see above). The default is not to render coast lines.
-d, --cloud=COLOR
The cloud mask color. The color is specified by name or hexadecimal value (see above). Cloud masking requires that a 'cloud' variable exists in the input file. The default is not to render a cloud mask.
-g, --grid=COLOR
The latitude/longitude grid line color. The color is specified by name or hexadecimal value (see above). The default is not to render grid lines.
-H, --shape=FILE/COLOR[/FILL]
The name and drawing/fill colors for a user-supplied shape file. The colors are specified by name or hexadecimal value (see above). The file formats currently supported are ESRI shapefile format (line and polygon data, no point data), and simple text files with lists of lat/lon values (the same format as described for the --polygon option in the cwstats tool). The fill color is optional and is used to fill polygons if any are found in the file. Multiple values of the --shape option may be given, in which case the shape overlays are rendered in the order that they are specified.
-L, --land=COLOR
The land mask color. The color is specified by name or hexadecimal value (see above). Land masking requires that a 'graphics' variable exists in the input file with a land mask at bit 3 where bit numbering starts at 0 for the least significant bit. The default is not to render a land mask. For an alternative to the --land option, try using the --coast option with a fill color.
--marker=LAT/LON/COLOR[/FILL[/SYMBOL[/TEXT]]]
The specifications for a symbol used to mark a location. The marker position is specified in terms of earth location latitude and longitude in the range [-90..90] and [-180..180]. The color is specified by name or hexadecimal value (see above). Optional parameters may be specified by appending the fill color (default is no fill), symbol (default is a circle), and text label (default is no label). The symbol may be one of 'cross', 'x', 'square', 'circle', 'triup', 'tridown', or 'diamond'.
-p --political=COLOR
The political boundaries color. The color is specified by name or hexadecimal value (see above). The default is not to render political boundaries.
-S, --nostates
Turns off state boundary rendering. The default when --political is specified is to render international and state boundaries. With this option is specified, only international boundaries are rendered.
-t, --topo=COLOR[/LEVEL1/LEVEL2/...]
The topographic contour color and levels. The color is specified by name or hexadecimal value (see above). Topographic contours are generated for the specified integer levels in meters. If no levels are specified, contours are drawn at 200 m, 500 m, 1000 m, 2000 m, and 3000 m. The default is not to render topographic contours.
-u, --group=GROUP
The overlay group name to render. Overlay groups are a concept from the CoastWatch Data Analysis Tool (CDAT). CDAT users can save a set of preferred overlays as a group and then restore those overlays when viewing a new data file. The same group names saved from CDAT are available to be rendered here. This is an extremely useful option that allows users to design a set of overlays graphically and adjust the various overlay properties beyond what can be achieved using the command line options for cwrender. If specified, this option will cause all overlays in the group to be drawn on top of any other overlays specified by command line options.
-w, --water=COLOR
The water mask color. The color is specified by name or hexadecimal value (see above). Water masking is performed similarly to land masking (see the --land option), but the sense of the land mask is inverted. The default is not to render a water mask.
-X, --exprmask=EXPRESSION/COLOR
Specifies that a mask should be rendered on top of the data image whose pixels are obtained by evaluating the expression. The color is specified by name or hexadecimal value (see above). An expression mask is a special type of multipurpose mask similar to a bitmask (see the --bitmask option above) but which allows the user to specify a mathematical expression to determine the mask. If the result of the expression is true (in the case of a boolean result) or non-zero (in the case of a numerical result), the data image is masked at the given location with the given color. Multiple values of the --exprmask option may be given, in which case the masks are applied in the order that they are specified. The syntax for the expression is identical to the right-hand-side of a cwmath legacy mode expression (see the cwmath tool manual page).
--watermark=TEXT[/COLOR[/SIZE[/ANGLE]]]
Specifies the text for a watermark that is placed in the center of the image plot to denote special status such as experimental or restricted, or some other property of the data. The default watermark text is white, 50% opacity, 50 point font, and 0 degrees rotation. Optional parameters may be specified by appending the watermark color (name or hexadecimal value as described above), the point size, and baseline angle (0 is horizontal, 90 is vertical). For example, --watermark=EXPERIMENTAL/white/36/20 adds the text EXPERIMENTAL in solid white, 36 point font, at a 20 degree baseline rotation.
--watermarkshadow
Draws a drop shadow behind the watermark to increase visibility. By default the watermark is drawn plain with no drop shadow.

Color enhancement options:

-E, --enhancevector=STYLE/SYMBOL[/SIZE]
The color-enhanced vector specifications. This option is only used if two variable names are passed to the --enhance option. The vector style may be either 'uvcomp' or 'magdir'; the default is 'uvcomp'. In uvcomp mode, the variables that are passed to the --enhance option are taken to be the U (x-direction) and V (y-direction) components of the vector. In magdir mode, the first variable is taken to be the vector magnitude, and the second to be the vector direction in degrees clockwise from north. The vector symbol may be either 'arrow' to draw arrows in the direction of the vector, or 'barb' to draw WMO wind barbs; the default is 'arrow'. If wind barbs are used, the feathered end of the barb points in the direction that the wind is coming from (unless metadata attached to the direction variable is used to alter that convention). WMO wind barbs are drawn differently depending on the wind speed units, m/s or knots:
  • Solid pennant: 25 m/s or 50 knots
  • Full barb: 5 m/s or 10 knots
  • Half barb: 2.5 m/s or 5 knots
  • X symbol: missing wind speed
  • No symbol: missing wind direction
Lastly, the size of the vector symbols in pixels may be specified; the default size is 10.
-F, --function=TYPE
The color enhancement function. Data values are mapped to the range [0..255] by the enhancement function and range, and then to colors using the color palette. The valid enhancement function types are 'linear', 'boolean', 'stepN', 'log', 'gamma', 'linear-reverse', 'stepN-reverse','log-reverse', and 'gamma-reverse' where N is the number of steps in the function, for example 'step10'. The 'boolean' function is a shorthand way of specifying 'step2' as the function, and '0/1' as the range, useful for data with only 0 and 1 as data values. The reverse functions are equivalent to the non-reversed functions but map data values to the range [255..0] rather then [0..255]. By default, the enhancement function is 'linear'. A log enhancement may be necessary when the data value range does not scale well with a linear enhancement such as with chlorophyll concentration derived from ocean color data. A gamma enhancement may be needed when the data values represent a brightness from 0% to 100% and compensates for the gamma correction in computer displays.
-k, --background=COLOR
The color for the background of vector plots. The color is specified by name or hexadecimal value (see above). The default background color is white.
-M, --missing=COLOR
The color for missing or out of range data values. The color is specified by name or hexadecimal value (see above). The default missing color is black.
-P, --palette=NAME
The color palette for converting data values to colors. The current list of color palette names can be listed using the --palettelist option. The palettes have been derived from a number of sources including SeaSpace Terascan, Interactive Data Language (IDL) v5.4, and the Python matplotlib cmocean package, and have similar names. By default the grayscale 'BW-Linear' palette is used.
--palettefile=FILE
The file of color palette XML data for converting data values to colors. The format of the XML file is described in the User's Guide. By default, the 'BW-Linear' palette is used.
--palettecolors=COLOR1[/COLOR2[/COLOR3...]]
The palette colors for converting data values to colors. Up to 256 colors may be specified by name or hexadecimal value (see above). By default, the 'BW-Linear' palette is used.
--palettelist
Lists the palette names available on the system, including any palettes in the user's resource directory.
--paletteimage=FILE
Renders an image of the palette names and color bars available on the system, including any palettes in the user's resource directory. The file name can end in '.png', '.jpg', '.tif', or '.bmp'.
-r, --range=MIN/MAX
The color enhancement range. Data values are mapped to colors using the minimum and maximum values and an enhancement function. By default, the enhancement range is derived from the data value mean and standard deviation to form an optimal enhancement window of 1.5 standard deviation units around the mean.
--scalewidth=PIXELS
The data color scale width. By default the data color scale is 90 pixels wide which includes the color bar, tick marks, value labels, and the variable name and units. This default accommodates most scales, but if a scale requires a wider size, it will grow to fit. In some cases this results in data plots with different data ranges being different widths overall, which may be undesirable. In these cases the scale width can be set explicitly to a larger value.
--ticklabels=LABEL1[/LABEL2[/LABEL3/...]]
The numeric tick mark labels to use for the data color scale. By default the tick mark labels are generated automatically. For example:
--ticklabels=1.0/1.1/1.2/1.3/1.4/1.5
would put tick marks and labels at evenly spaced locations on the color scale from 1.0 to 1.5.
-U, --units=UNITS
The range and color scale units for the enhancement variable(s). By default, the user must specify the values for the --range option in the standard units indicated in the data. If the user prefers a different set of units to be used, they may be specified here. Many common units are accepted (and various forms of those units), for example 'kelvin', 'celsius' and 'fahrenheit' for temperature data, 'knots', 'meters per second' or 'm/s' for wind speed, and 'mg per m^-3' or 'kg/m-3' for concentration. For other possible unit names, see the conventions used by the Unidata UDUNITS package and its supported units file.
--varname=TEXT
The variable name to show in the color scale legend. By default the name of the variable is used, or in the case of a vector plot either the magnitude variable or U/V components.

Color composite options:

-B, --bluerange=MIN/MAX
The blue component enhancement range, see --redrange.
-G, --greenrange=MIN/MAX
The green component enhancement range, see --redrange.
-R, --redrange=MIN/MAX
The red component enhancement range. Data values are mapped to the range [0..255] using the minimum and maximum values and an enhancement function. By default, the enhancement range is derived from the data value mean and standard deviation to form an optimal enhancement window of 1.5 standard deviation units around the mean.
-x, --redfunction=TYPE
The red component enhancement function. Data values are mapped to the range [0..255] by the enhancement function and range, and then the pixel color is created by compositing the red, green, and blue mapped values into one 32-bit integer color value. See the --function option for valid function types. By default, the red, green, and blue enhancements are linear.
-y, --greenfunction=TYPE
The green component enhancement function, see --redfunction.
-z, --bluefunction=TYPE
The blue component enhancement function, see --redfunction.
--compositehint=HINT
Performs the color composite using a hint for setting the composite functions and ranges, ignoring any other composite settings. The hints available are:
  • 'true_color' -- Creates a true color image from red/green/blue variables that have been corrected for atmosphere so that all variables contain reflectance data with a range [0..1].
  • 'true_color_vivid' -- Similar to true color above, but produces slightly higher contrast true color images.
  • 'true_color_uncorr' -- Similar to true color above, but handles data that has not been corrected for atmosphere and contains albedo or radiance data. The components are analyzed to determine approximate dark pixel correction and maximum brightness values.
  • 'avhrr_day' -- AVHRR daytime false color using channels 1, 2, and 4.
  • 'avhrr_night' -- AVHRR nighttime false color using channels 3, 4, and 5.

Exit status

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

  • Invalid command line option
  • Invalid input or output file names
  • Invalid variable name
  • Unrecognized format
  • Unrecognized color name
  • Invalid palette name
  • Invalid magnification center

Examples

As an example of color enhancement, the following command shows the rendering of AVHRR channel 2 data from a CoastWatch HDF file to a PNG image, with coast and grid lines in red and the default linear black to white palette. We allow the routine to calculate data statistics on channel 2 for an optimal enhancement range:

   phollema$ cwrender --verbose --enhance avhrr_ch2 --coast red --grid red 
     2002_288_1435_n17_er.hdf 2002_288_1435_n17_er_ch2.png

   [INFO] Reading input 2002_288_1435_n17_er.hdf
   [INFO] Normalizing color enhancement
   [INFO] Preparing data image
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.LatLonOverlay
   [INFO] Writing output 2002_288_1435_n17_er_ch2.png

For a color composite of the same file, the following command shows the rendering of AVHRR channels 1, 2, and 4 to a PNG image. Again, we allow the routine to calculate statistics for optimal enhancement ranges. Note that the final enhancement function is reversed in order to map warm AVHRR channel 4 values to dark and cold values to bright:

   phollema$ cwrender --verbose --composite avhrr_ch1/avhrr_ch2/avhrr_ch4
     --bluefunction reverse-linear --coast black --grid gray 
     2002_288_1435_n17_er.hdf 2002_288_1435_n17_er_ch124.png

   [INFO] Reading input 2002_288_1435_n17_er.hdf
   [INFO] Normalizing red enhancement
   [INFO] Normalizing green enhancement
   [INFO] Normalizing blue enhancement
   [INFO] Preparing data image
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.LatLonOverlay
   [INFO] Writing output 2002_288_1435_n17_er_ch124.png

A further example below shows the rendering of AVHRR derived sea-surface-temperature data from the same file with a cloud mask applied. The color enhancement uses a blue to red color palette and an explicit range from 5 to 20 degrees Celsius:

   phollema$ cwrender --verbose --enhance sst --coast white --grid white 
     --palette HSL256 --range 5/20 --cloud gray 2002_288_1435_n17_er.hdf
     2002_288_1435_n17_er_sst.png

   [INFO] Reading input 2002_288_1435_n17_er.hdf
   [INFO] Preparing data image
   [INFO] Rendering overlay noaa.coastwatch.render.BitmaskOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.LatLonOverlay
   [INFO] Writing output 2002_288_1435_n17_er_sst.png

An example usage of the --magnify option is shown below to create a plot of cloud masked sea-surface-temperature data off Nova Scotia:

   phollema$ cwrender --verbose --enhance sst --coast white --grid white 
     --palette HSL256 --range 5/20 --cloud gray --magnify 43/-66/1
     2002_288_1435_n17_er.hdf 2002_288_1435_n17_er_sst_mag.png

   [INFO] Reading input 2002_288_1435_n17_er.hdf
   [INFO] Preparing data image
   [INFO] Rendering overlay noaa.coastwatch.render.BitmaskOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.LatLonOverlay
   [INFO] Writing output 2002_288_1435_n17_er_sst_mag.png

For an example of true color rendering, the next example shows the use of the --compositehint option for rendering top of atmopshere OLCI radiance data to a JPEG image:

   phollema$ cwrender --verbose --nolegends --size 1024
     --composite EV_BandOa07/EV_BandOa06/EV_BandOa04
     --compositehint true_color_uncorr
     --coast white OLCMCW.I2021048.135053.hdf OLCMCW.I2021048.135053.true.jpg

   [INFO] Reading input OLCMCW.I2021048.135053.hdf
   [INFO] Set red component range to [0.8290487916208804, 28.153357705221403]
   [INFO] Set green component range to [1.4429238677024843, 30.664745965510583]
   [INFO] Set blue component range to [2.5182327458634974, 35.567549666418145]
   [INFO] Preparing data image
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Writing output OLCMCW.I2021048.135053.true.jpg

The following shows a unique example of true color rendering from an existing color GeoTIFF file into a PNG with legends. The GDAL and NetCDF Operators (NCO) software are also needed to accomplish this:

   phollema$ gdal_translate n20_viirs_20201031_175619.tif
     n20_viirs_20201031_175619.nc
   phollema$ ncatted -a sensor,GLOBAL,c,c,VIIRS n20_viirs_20201031_175619.nc
   phollema$ ncatted -a platform_ID,GLOBAL,c,c,N20 n20_viirs_20201031_175619.nc
   phollema$ ncatted -a institution,GLOBAL,c,c,"NOAA CoastWatch"
     n20_viirs_20201031_175619.nc
   phollema$ ncatted -a time_coverage_start,GLOBAL,c,c,2020-10-31T17:56:19Z
     n20_viirs_20201031_175619.nc
   phollema$ ncatted -a time_coverage_end,GLOBAL,c,c,2020-10-31T17:56:19Z
     n20_viirs_20201031_175619.nc
   phollema$ cwrender --verbose --size 700 --coast white --grid white
     --composite Band1/Band2/Band3 --redrange 0/255 --greenrange 0/255
     --bluerange 0/255 n20_viirs_20201031_175619.nc n20_viirs_20201031_175619.png

   [INFO] Reading input n20_viirs_20201031_175619.nc
   [INFO] Preparing data image
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.LatLonOverlay
   [INFO] Writing output n20_viirs_20201031_175619.png

This next example shows how to render ocean current vector data by supplying two variables to the --enhance option. Rendering vector data is best done by using the --magnify option as well. This call renders data off the east coast of Japan using color vectors on a black background:

   phollema$ cwrender --verbose --enhance ugos/vgos --range 0/2 --palette Blue-Red 
     --function step10 --coast black/gray40 --grid white --background black
     --magnify 35/143/10 --size 800/700 example_altim_surface_curr_feb_2023.nc 
     example_altim_surface_curr_feb_vector.png
 
   [INFO] Reading input example_altim_surface_curr_feb_2023.nc
   [INFO] Preparing data image noaa.coastwatch.render.ColorPointEnhancement
   [INFO] Rendering overlay noaa.coastwatch.render.PointFeatureOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.CoastOverlay
   [INFO] Rendering overlay noaa.coastwatch.render.LatLonOverlay
   [INFO] Writing output example_altim_surface_curr_feb_vector.png

Known Bugs

When using the --coast option with a fill color and output is to a PDF file, lakes may contain a thin stripe of land in some places. In this case, use the --land for land filling instead.

When using the --coast option with a fill color, map projection discontinuities or swath projection edges may not be filled correctly.

Since:
3.1.1
Author:
Peter Hollemans

  • Method Details

    • main

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