Program M3PLOT

Summary

M3Tools program m3plot to do high performance tile, smoothed-tile, contour, vector, scalar and vector observational-overlay graphics for large GRIDDED I/O API data sets. The design goal was to fit in, e.g, a production hydrological forecast system that uses a 4000x2500 grid to compute flood-water depth at a 5 minute time step for a 120-hour forecast period (approximately 600 GB of data per forecast, much larger than available RAM), cycled every 6 hours, and completing the product generation in 15 minutes or less. This requirement is either impossible for, or orders of magnitude more performance than, other (in-memory) vis tools such as PAVE>, VERDI, or Panoply can deliver.

Using the PLOTONLY option, one can generate images with no legends: e.g., for publication at Linoitype® 4096-dpi resolution, one can generate 5-inch-by-4-inch (20480x16384-pixel) or larger images (also impossible for, e.g., PAVE>, VERDI, or Panoply).

Unlike VERDI or PAVE, m3plot always generates images with the correct aspect ratio, without the distortion of stretching in the horizontal or vertical -- it displays the largest aspect-correct image consistent with the specified image WIDTH and HEIGHT.

m3plot creates (optionally smoothed) tile-plots, contour, gridded wind-vector, (scalar) observation, and vector observation-overlay plots, with optional windowing, and saves the results as image files, using the libgd image library. Output file formats are GIF, JPEG, and PNG; output file names are of the form ${BASENAME}.<VNAME>[.<LLL>].<YYYYDDDHHMMSS>.[gif | jpg | png] where ${BASENAME} may be a partial file-name, a directory, or blank, VNAME is the variable-name, LLL is the layer number if the input file has more than one layer, and YYYYDDDHHMMSS is the Julian date&time, according to I/O API conventions. If there are no tile/smooth-plot variables, but there are vector-variables, VNAME is <U-component-name>_<V-component-name>.

For time stepped files, there are two modes of indexing: date-time based and record based. As an example, for a file starting at date&time 2009151 11:30:00, the starting record has index 2009150113000 in the date-time indexing scheme and index 0000 in the record based scheme. For this file example, if the variable is TA2 and the type is GIF, for the date&time based indexing, the first image file names wil be as follows:

    ${BASENAME} /foo/bar/qux:  /foo/bar/qux.TA2.2009150113000.gif
    ${BASENAME} /foo/bar/:     /foo/bar/TA2.2009150113000.gif
    ${BASENAME} <blank>        ${cwd}/TA2.2009150113000.gif
    

With record based indexing the first file name would be something like

    /foo/bar/qux.TA2.0000.gif
    

If the file is time independent, the index field will be omitted, e.g.

    /foo/bar/qux.LANDUSE.gif
    

If the file is multilayered, a 3-digit layer-number field will precede the date-time/record-number field, e.g., for layer-31 of variable TA a file name might be

    /foo/bar/qux.TA.031.2009150113000.gif
    

If there are vector-overlays, the variable-name field will also include the vector-component variable names, separated by underscores, e.g.,

    TA_UWIND_VWIND.031.2009150113000.gif
    

Tiled/smoothed variables and observations may contain MISSING data; however, vector-component or contour input data must not.

Usage

This program is designed primarily for scripted production usage with large modeling domains and time periods, hence has very high computational performance; the graphics configuration is controlled by a (re-usable) ASCII configuration file (below).

Before you run the program:

        setenv  INFILE    <path name for gridded tile-plot input file>
        setenv  VECFILE   <path name for       vector-input file, or "NONE"> [NONE]
        setenv  CONFILE   <path name for      contour-input file, or "NONE"> [NONE]
        setenv  OBSFILE   <path name for observations-input file, or "NONE"> [NONE]
        setenv  OVECFILE  <path name for   obs-vector-input file, or "NONE"> [NONE]

        setenv  CONFIG    <path name for configuration file>
        setenv  BASENAME  <base name or directory for output images>
        setenv  MAPDIR    <directory for maps, or , or "NONE">
        setenv  IMGDATES  <use date-&-time instead of record-numbers? (Y/N)> [Y]
        setenv  LOGSTATS  <report gridded stats to log? (Y/N)> [N]
    

If OBSFILE or OVECFILE not "NONE">:

        setenv  LLFILE    <path name for Lat-Lon (e.g., GRID_CRO_2D) file>
    

Then

        m3plot [and answer the prompts, below]
    

Constraints:

INFILE determines the default time step sequence for the program run. User-prompt selects the actual time step sequence. All input files (INFILE and if present VECFILE CONFILE, OBSFILE, and OVECFILE must contain the selected time step sequence

INFILE and VECFILE share either a same-grid or dot-point::cross-point grid relationship for the very same grid.

INFILE and CONFILE share the very same grid.

OBSFILE should be of type CUSTOM3 with NCOLS=<number of observations> and REAL variables LAT and LON for the obs-site, as well as the specified observation-variables.

OVECFILE should be of type CUSTOM3 with NCOLS=<number of observations> and REAL variables LAT and LON for the obs-site, as well as the specified wind-component observation-variables.

Program Control: CONFIG files and prompts

THE PROGRAM WILL PROMPT YOU for starting date and time, time step, and number of time steps to process. These default to the corresponding values from INFILE. All input files must contain this time step sequence.

The CONFIG file is an ASCII file, with lines to control each of the program options. These lines are of the form

    <name>    <value(s)>
    

The following table gives these name, descriptions, and defaults of the values, where note that COLOR, VCOLOR, CCOLOR are each multiple lines with sub-tables of consecutive color-indices and RGB values. Default values are indicated in square brackets [LIKE THIS].

IMGFORMAT

GIF | JPG | PNG [GIF]

IMGMETHOD

TILED | SMOOTHED [TILED]

WIDTH

number of pixels wide for the entire image [960]

HEIGHT

number of pixels high for the entire image [720]
(minimum image-size 240x280)

WINDOW_COLS

first and last grid-col for the plot [entire grid]

WINDOW_ROWS

first and last grid-row for the plot [entire grid]

PLOTONLY

WIDTH | HEIGHT [WIDTH]
to suppress legend, and generate correct-aspect tiled image only, with image dimensions from WIDTH or HEIGHT.

LEGEND_BINS

number of color-labels on the color-scale legend [6]

COLOR

<index> <red> <green> <blue>
for tile/smooth map, where index is consecutive for some range 0 ... N < 253 and red-green-blue color-values are in the range [0...255]
[default tile-color palette is a 10-color scale]

VCOLOR

<index> <red> <green> <blue>
for vector-wind map, as above.
[default vector-color palette is a 10-color scale from dark blue to dark green]

CCOLOR

<index> <red> <green> <blue>
for vector-wind map, as above.
[default vector-color palette is a 10-color scale from dark blue to dark red]

MISSING_COLOR

<red> <green> <blue> [127 127 127]

MAPNAME1

"states" map-file name in ${MAPDIR} [OUTLHRES], or <blank> to suppress this map

MAPNAME2

"county" map-file name in ${MAPDIR} [OUTLCOUNTIES], or <blank> to suppress this map

MAPNAME3

"extra" map-file name in ${MAPDIR} [<blank>]

MAPCOLOR1

<red> <green> <blue> [ 0 0 0]

MAPCOLOR2

<red> <green> <blue> [ 31 31 31]

MAPCOLOR3

<red> <green> <blue> [ 63 63 63]

MAPWIDTH1

line-width (pixels) [1]

MAPWIDTH2

line-width (pixels) [1]

MAPWIDTH3

line-width (pixels) [1]

with repeated sections of variable-names and options, per variable plotted:

VARIABLE

<variable-name from INFILE or ALL> <[LIN|LOG|EXP]> [LIN
where the second component of the value indicates linear scaling, log-scaling, or exponential-scaling
e.g., VARIABLE ALL LIN for all-vbles "normal" plots, VARIABLE TA LIN for a "normal" TA-plot, VARIABLE TA LOG for a log-scaled TA-plot, and VARIABLE TA EXP for an exp-scaled TA-plot.

UNITS

<units-name> [<scale factor> <scale offset>]
where default is units from the file, and if present, scaling uses the formula

            Y_display = scale * Y_file +  offset
            

This can be used, for example to convert temperatures from Kelvin to Fahrenheit...

LEVEL

model-level [1]

SCALE_RANGE

<min> <max> for the tile color-scale [data-min,data-max]

FORMAT_BINS

C-language format for color-scale legend-labels ["%g"]

VECTOR

<X-component variable-name> <Y-component variable-name> in VECFILE

VEC_RANGE

<max> for the windspeed color-scale [vec-max]

VEC_LEVEL

wind-grid model level [1]

VEC_INCREMENT

sampling interval for the vector plot (cells) [1]

VEC_THICKNESS

arrow-shaft thickness (pixels) [1]

CONTOUR

<variable-name> from CONFILE

CON_UNITS

<units-name> [<scale factor> <scale offset>]
where default is units from the file

CON_RANGE

<min> <max> for the tile color-scale [data-min,data-max]

CON_LEVEL

model-level [1]

CON_THICKNESS

contour-line thickness (pixels) [2]

CON_SMOOTH

smooth grid to be contoured? (TRUE|FALSE) [TRUE]

OBSERVATION

scalar <observation variable name>

OBS_SIZE

obs-marker size (pixels) [10]

OBS_VECTOR

<speed-vble name> <bearing-vble name>

OVEC_RANGE

<max> for the windspeed color-scale [vec-max]

OVEC_LENGTH

obs-arrow length (pixels) [10]

OVEC_THICKNESS

arrow-shaft thickness (pixels) [1]

TITLE1

First legend-header line [tile-variable name]

TITLE2

Second legend-header line [tile-variable description]

TITLE3

Third legend-header line> [path name for INFILE]

Constraints:

Blank lines are ignored (and may be used as section-separators).

UNITS, LEVEL,and SCALE_RANGE options are invalid after VARIABLE ALL...

Options may appear at most once per tile/smooth-plot variable.

One may plot vector-only by using an empty set of VARIABLEs; however, INFILE is still required in order to specify the grid definitions and time step sequence.

Total number of colors used (tile + vector + contour + observation + vector-observation) is at most 253.

Examples:

• Here is a config-file for smooth tile-plots for level-1 TA
  The total image is 1200x800-pixels (counting legends as well as the tiling), output is in PNG format.
  The UNITS degF 1.8 523.67 converts the temperature from degrees Kelvin to to degrees Fahrenheit.
  There are 50 colors, in 10 bands ranging from light to dark, for blues, cyans, greens, yeallows, and reds. The SCALE_RANGE 12.0 112.0 The blue band represents "freezing" temperatures of 12-32 °F, cyan temperatures 32-52 °F, etc. Temperatures below 12 show up as the lightest blue, and above 122 are darkest red.
  State-boundary maps are drawn 2 pixels wide in black, and county-boundary mpas in very dark gray 1 pixel wide.

• Here is a config-file for tile plots for level-1 of O3 with NO2 contour overlays, with units converted to PPBV. Similar to the above, the blue hues represent 40-60, PPBV, etc., through the red hues that represent 120-140 PPBV.
  The data is windowed to columns 10-110 and rows 20-100, and the plots are 1000x800 pixels.
  Maps are as above.

• Here is a config-file for precipitation rate PRATE tile plots, converted from units M/S to inches/hour with scale-legend values formatted %5.2f (XX.XX). There is a 51-color scale with dark gray for 0.0 or below, and 50 colors as above for values from 0.0 to 2.0. Maps are as above.

• Here is a config-file for LSM stream-flooding fraction without legends, for publication.
  This generates a 14000x10000-pixel tile-plot image from the 3500x2500-cell LSM grid; at Linotype 4096-dpi resolution, the published size will be about 3.42x2.44 inches.

See Also:

• Program GISPLOT to create GIF, JPG, or PNG tile-plots for GIS data.

---

To: Models-3/EDSS I/O API: The Help Pages

Up: M3Tools Programs

Copyright © 2025 Carlie J. Coats, Jr., Ph.D.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

Send comments to

Carlie J. Coats, Jr.
carlie@jyarborough.com