Program GISPLOT


I/O API 4.0 only!!

Summary

M3Tools program gisplot to do production high performance tile and smoothed-tile graphics for a sequence of (potentially large) files for the same variable, of one of the supported GIS "raster" (gridded) formats. The program saves the results as image files, using the libgd image library. Output file formats are GIF, JPEG, and PNG.

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. Supported input file types are:

BIL , BIL2 , BIL4 , FLT
BIL , ZBIL2, ZBIL4, ZFLT
ARCI , ARCR , ASCI , ASCR
where BIL...FLT are binary direct access, ZBIL...ZFLT are gzip<.VAR>-compressed, ASCI, ASCR are ASCII with header lines specifying "north", "south" "east", "west", "rows", and "cols" (one poer line); and ARCI, ARCR are ASCII with header lines specifying "ncols", "nrows", "xllcorner", "yllcorner", "cellsize"' and optionally "NODATA_value".

Usage

To run the program: 
        setenv  GRIDDESC    <path name>
        setenv  GRIDNAME    <GRIDDESC name for input grid>
        setenv  CONFIG    <path name for configuration file (see below)>
        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>
For each INFILE in CONFIG 
        setenv <file-name>  <path name>
Then 
        gisplot [and answer the prompts]
Output file names are of the form 
    <BASENAME>.<VNAME>[.<record-index>].[ gif | jpg | png ]
where <BASENAME>ay be a partial file-name, a directory, or blank, <VNAME> is the variable-name, and <record-index> is the Julian date&time, formatted YYYYDDDHHMMSS.

Program Control: CONFIG files and prompts

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, and 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 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 each red-green-blue color-component is in the range [0...255]
[default tile-color palette is a 10-color scale]
MISSING_COLOR
<red> <green> <blue> [127 127 127]

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...
MISSING_VALUE
"missing" value for these files
SCALE_RANGE
<min> <max> for the tile color-scale [data-min,data-max]
FORMAT_BINS
C-language format for color-scale legend-labels ["%g"]

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, per file/timestep plotted:
INFILE
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]
Blank lines are ignored (and may be used as section-separators).

See Also:
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