Home
Latest News
Downloads
Repositories

Nbsp
Quick guide
Wiki
Article for Geo Quarterly

Npemwin
Project | Wiki
Manual
What's new

Support
Problem reports
Group
Contact







TclGempak

TclGempak is a library of procedures for executing Gempak programs from Tcl scripts, thus making available the extensive processing capabilities of Tcl to manipulate the input to those programs. The library currently supports

gpfront, gpmap, sfcntr, sflist, sfmap, gdcntr, gdstream, gdwind, gdplot, gdplot2, gdinfo, gdmap

This document contains installation instructions, as well as some example scripts and their corresponding output to illustrate its usage.

Requirements

In addition to Tcl, TclGempak requires Tcllib but it has no further requirements apart from Gempak itself.

Downloading the software

The source ``tclgempak-version.tgz'' of the tclgempak library can be downloaded from the software area of this site The distribution comes with an INSTALL file that contains the installation instructions, a set of examples to illustrate the basic functionality, and with a README file that lists the available procedures and their usage.

In addition there are binary packages for FreeBSD, CentOS and Debian, in tbz, rpm and deb formats respectively, that can be installed with the native package management tools (e.g., pkg_add, rpm, dpkg).

Installation

Requirements

The following are required and must be installed:

Tcl
Tcllib
Gempak

Installing from Packages

Binary packages exist for FreeBSD (tbz), CentOS (rpm) and Debian (deb). Since tclgempak is written entirely in Tcl and no compilation is involved, the rpm packages should work anywhere rpm is the package management tool.

The packages, available from the software section, can be installed with the native package management tools:

pkg_add tclgempak-version.tbz
rpm -i tclgempak-version.rpm
dpkg -i tclgempak-version.deb

Installation using the Makefile

This boils down to executing

./configure.sh
make install-dirs
make install
inside the tclgempak distribution directory.

Manual installation

TclGempak is written entirely in Tcl, so there is no compilation involved. The package consists of single file ``gempak.tcl'' and the accompanying index file ``pkgIndex.tcl''.

Perhaps the best option is to create a directory ``tclgempak'' at the same level as the tcllib directory, and put both of the above files in that directory.

The files can be saved anywhere, for example

/usr/local/lib/tcl_site
Any script that will use the package can then add the lines
lappend auto_path "/usr/local/lib/tcl_site"
package require gempak
and it will be found.

Usage

A script will typically be of the form

#!/usr/local/bin/tclsh8.4

package require gempak;

gempak::define asfil "latest.fronts";
gempak::define device "gif|fronts.gif";
gempak::define garea "us";

gempak::init gpfront;
gempak::run;
gempak::end;

If such scripts are executed from a terminal, the user must have sourced one of the Gemenviron files (depending on the user's shell). Alternatively, if Nbsp is installed, the following line can be added at the top of the script

source /usr/local/etc/nbsp/gempak.env
to load the environment variables. The advantage of the latter approach is that the scripts can be run in the background as well. A copy of the gempak.env file is included in the documentation directory of the tclgempak package.

The complete set of procedures contained in the package are listed and described in the README file mentioned above, and here we mention a few, taken from the examples that are provided with the distribution and the packages.

NOTE

As of Nbsp-2.0, the TclGempak library is included in the Nbsp package and therefore there is no need to install it separately as instructed above. However, to use it, the scripts must set the auto_path variable properly so that the library is found. Specifically, the scripts must contain the instructions

lappend auto_path "/usr/local/libexec/nbsp"
package require gempak

Examples

In the examples below, only the relevant portion of the scripts is shown. See the examples subdirectory for the corresponding output files.

Example 1

To produce a radar image from a given data file

set nidsdir "/var/noaaport/data/digatmos/nexrad/nids/jua/n0r";
set datafile [file join $nidsdir "n0rjua_20090114_2048.nids"];

gempak::define radfil $datafile;
gempak::define proj "rad";
gempak::define device "gif|n0rjua.gif";
gempak::define garea "dset";

gempak::init gpmap;
gempak::run;
gempak::end;

Example 2

Same thing, but specifying the parts of the device and map parameters separately, and using the ``latest'' file.

set nidsdir "/var/noaaport/data/digatmos/nexrad/nids";

set site "jua";
set type "n0r";

set datafile [file join $nidsdir $site $type "latest"];


gempak::define radfil $datafile;
gempak::define proj "rad";
gempak::define garea "dset";

gempak::device_device "gif";
gempak::device_name ${type}${site}.gif;
gempak::device_size 1024 768;
gempak::set_device;

gempak::map_color 1;
gempak::map_dash 7;
gempak::set_map;

gempak::init gpmap;
gempak::run;
gempak::end;

Example 3

Adding these lines anywhere before the call to ``gempak::init gpmap'' above, will draw the color bar:

gempak::imcbar_color 5;
gempak::imcbar_orientation "V";
gempak::imcbar_anchor "LL";
gempak::imcbar_xy 0.05 0.1
gempak::imcbar_lengthwidth 0.5 0.1;
gempak::imcbar_frequency 1;
gempak::set_imcbar;

Example 4

These lines will add a selected set of city names

gempak::stnplt_text_color 5;
gempak::stnplt_text_size 1;
gempak::stnplt_marker_color 3;
gempak::stnplt_marker_type 12;
gempak::stnplt_marker_size 1.25;
gempak::stnplt_marker_width 2;
gempak::stnplt_stnfile_name \
  "/usr/local/etc/nbsp/defaults/gpmap/rad/radmap-cities.tbl";
gempak::set_stnplt;

Example 5

The tclgempak equivalent of the Gempak parameter settings

\$mapfil = county + cities
map = = 1//2 + 2//3
is the following:
gempak::mapfil "county" "cities";

# first one
gempak::map_color 1;
gempak::map_width 2;
gempak::set_map

# second one
gempak::map_color 2;
gempak::map_width 3;
gempak::append_map

Notice in particular the absence of the ``\, $, +, /'' symbols in the parameter specification. In general the tclgempak functions have keywords in their names to help recognize their use.

Example 6

This is the classic example for drawing a stereographic projection of the Northern Hemisphere.

gempak::define map 1;
gempak::define proj "str/90;-80;0";
gempak::define garea "-10;-130;-10;50";

#gempak::define latlon "2/10/1/1/10;10";
gempak::latlon_color 2;
gempak::latlon_linetype 10;
gempak::latlon_linewidth 1;
gempak::latlon_freq 1 1;
gempak::latlon_incr 10 10;
gempak::set_latlon;

gempak::device_device "gif";
gempak::device_name "latlon.gif";
gempak::set_device;

Example 7

This will draw the latest watch/warn areas.

gempak::define device "gif|wwa.gif";
gempak::define garea "us";

gempak::define wstm "last";
gempak::define warn "last";
gempak::define watch "last";
gempak::define wcn "last";
gempak::define wcp "last";

gempak::init gpmap;
gempak::run;
gempak::end;

Example 8

A more sophisticated version of the above, to draw the outlines of the latest watch/warn areas.

gempak::define device "gif|wwa.gif";

::gempak::garea_lat1 15;
::gempak::garea_lon1 -125
::gempak::garea_lat2 50
::gempak::garea_lon2 -60;
::gempak::set_garea;

::gempak::latlon_color 1;
::gempak::latlon_linetype 10;
::gempak::latlon_linewidth 1;
::gempak::latlon_freq 15 15;
::gempak::set_latlon;

::gempak::wstm_end_time {last};
::gempak::wstm_outline_flag {yes};
::gempak::wstm_outline_width_warn {1};
::gempak::wstm_outline_width_watch {1};
::gempak::wstm_outline_width_advisory {1};
::gempak::set_wstm;

gempak::init gpmap;
gempak::run;
gempak::end;

Example 9

This will draw the latest fronts, and shows how to define the ``garea'' by specifying independently the corner points.

set datafile "/var/noaaport/data/digatmos/nwx/hpc/fronts/latest.front";

gempak::define asfil $datafile;
gempak::define device "gif|fronts.gif";

gempak::garea_lat1 15;
gempak::garea_lon1 -125;
gempak::garea_lat2 50;
gempak::garea_lon2 -60;
gempak::set_garea;

gempak::init gpfront;
gempak::run;
gempak::end;

This example also shows once more the general rule that the tclgempak functions have keywords in their names that indicate what they set or do.

Example 10

Besides gpmap an gpfront, the library can be used with the sfmap and sfcntr programs. This examples uses sfmap to make a plot of the ``skyc'' and ``tmpf'' variables.

# Find the current file in the surface data directory
set surfacedir [file join $env(GEMDATA) "surface"];
set now [expr [clock seconds]];
set sffile_name [clock format $now  -format "%Y%m%d" -gmt true];
append sffile_name "_sao.gem";
set sffile [file join $surfacedir $sffile_name];

# main
gempak::define sffile $sffile
gempak::define device "gif|sfmap.gif";

gempak::define garea "15;-125;50;-60";
gempak::define area "garea";
gempak::define dattim "last";
gempak::define sfparm "skyc;tmpf"
gempak::define colors "26;2";

gempak::init sfmap;
gempak::run;
gempak::end;

To show only the Texas area, for example, use

gempak::define garea "tx";
gempak::define area "garea";

Instead of using the last data in the above example, it is best to use the data for the last (previous) hour. This can be acomplished by adding the following in the above script:

set last_hour [clock format [expr $now - 3600] -format "%H" -gmt true];
gempak::define dattim "/$last_hour";

Instead of setting the sfparm and colors directly, the various arrtibutes can be set separately:

# first parameter
gempak::sfparm_name "skyc";
gempak::sfparm_size 0.75;
gempak::set_sfparm;
gempak::colors 26;

# second one
gempak::sfparm_name "tmpf";
gempak::sfparm_size 0.75;
gempak::append_sfparm;
gempak::append_colors 2;

# third one
gempak::sfparm_name "brbk";
gempak::sfparm_size 0.75;
gempak::append_sfparm;
gempak::append_colors "26";

Example 11

This example uses sfcntr to make a contour plot of the the ``tmpf'' variable.

# Find the current file in the surface data directory
set surfacedir [file join $env(GEMDATA) "surface"];
set now [expr [clock seconds]];
set sffile_name [clock format $now  -format "%Y%m%d" -gmt true];
append sffile_name "_sao.gem";
set sffile [file join $surfacedir $sffile_name];

# main
gempak::define sffile $sffile
gempak::define device "gif|sfcntr.gif";

gempak::define garea "15;-125;50;-60";
gempak::define area "garea";
gempak::define dattim "last";

gempak::define sfparm "tmpf"
gempak::define colors 0;
gempak::define cntrprm "tmpf";
gempak::define cint 5;

gempak::init sfcntr;
gempak::run;
gempak::end;

For the Texas area alone, a setting such as these

gempak::define garea "tx";
gempak::define area "garea";
gempak::define cint 3;
can be used.

Example 12

This example plots a 10 day (script executed on 17 Jan 2009) forecast temperature at 900 mb using gdcntr.

# Choose a model and file
set datadir [file join $env(GEMDATA) "model" "gfs"];
set gdfile_name "2009011718_gfs211.gem";

set gdfile [file join $datadir $gdfile_name];

# main

gempak::define gdfile $gdfile
gempak::define device "gif|gdcntr.gif";

gempak::define garea "tx";
gempak::define dattim "last";

gempak::define gfunc "tmpf"
gempak::define glevel 900;
gempak::define gvcord "pres";

# for contour only or fill only use one of these
## gempak::ctype_fill;
## gempak::ctype_contour;

# we will do both
gempak::ctype_fc;

# Put more contours than the defaults
gempak::cint_interval 3;
gempak::set_cint;

gempak::init gdcntr;
gempak::run;
gempak::end;

Example 13

This example plots several 900 mb wind streamlines forecast using gdstream.

# Choose a model and file. We will pick the latest gfs211.
#
set datadir [file join $env(GEMDATA) "model" "gfs"];
set filelist [lsort [glob -directory $datadir "*gfs211.gem"]];
set gdfile [lindex $filelist end];

# main

gempak::define gdfile $gdfile

gempak::define garea "tx";

gempak::define gvect "wnd"
gempak::define glevel 900;
gempak::define gvcord "pres";

gempak::define line "3//1";
gempak::define map "1/7";
gempak::define title "5";
gempak::define latlon "2/10/1/1/5;5";

# Do several forecast times
foreach t [list 24 36 48 72] {
    gempak::define gdattim f$t;
    gempak::define device "gif|gdstream_$t.gif";
    gempak::init gdstream;
    gempak::run;
    gempak::end;
}

Example 14

Similar to the previous example but using gdwind.

# Choose a model and file. We will pick the latest gfs211.
set datadir [file join $env(GEMDATA) "model" "gfs"];
set filelist [lsort [glob -directory $datadir "*gfs211.gem"]];
set gdfile [lindex $filelist end];

# main

gempak::define gdfile $gdfile

gempak::define garea "tx";

gempak::define gvect "wnd"
gempak::define glevel 900;
gempak::define gvcord "pres";

gempak::define map "1/7";
gempak::define title "3";
gempak::define latlon "2/10/1/1/5;5";

# Set them like this or as set below
## gempak::define wind "ak4"
## gempak::define refvec "10";
## gempak::define skip "/1;1";

gempak::wind_symbol_type "a";
gempak::wind_symbol_units "k";
gempak::wind_symbol_color "4";
gempak::set_wind;

gempak::refvec_magnitude 10;
gempak::set_refvec;

gempak::skip_plot_xy 1 1;
gempak::set_skip;

# Do several forecast times
foreach t [list 24 36 48] {
    gempak::define gdattim f$t;
    gempak::define device "gif|gdwind_$t.gif";
    gempak::init logfile gdwind;
    gempak::run;
    gempak::end;
}

Example 15

This example uses gdinfo to extract the list of variables from a grib file. Each record in the output is formatted like

tmpk_150_pres,000,006,012,018,024,030,036,042,048,054,060, ...
The first element of the comma-separated record is a variable identifier constructed from the variable name, the level and the level coordinate, separated by an underscore. The rest of the record are the forecast hours for which the data is available for that variable identifier.

# Choose a model and file. We will pick the latest gfs211.
set datadir [file join $env(GEMDATA) "model" "gfs"];
set filelist [lsort [glob -directory $datadir "*gfs211.gem"]];
set gdfile [lindex $filelist end];

gempak::gdinfo::define gdfile $gdfile;
gempak::gdinfo::define lstall "yes";
gempak::gdinfo::define output "t";
gempak::gdinfo::define gdattim "all";
gempak::gdinfo::define glevel "all";
gempak::gdinfo::define gvcord "all";
gempak::gdinfo::define gfunc "all";

gempak::gdinfo::init;
gempak::gdinfo::run;
gempak::gdinfo::end;

puts [gempak::gdinfo::output];

Example 16

This example uses sflist to extract the data from a surface file.

gempak::sflist::sffile $env(GEMDATA)/surface/20090202_sao.gem
gempak::sflist::dattim "all";
gempak::sflist::sfparm tmpf relh dwpf pmsl sped drct;
gempak::sflist::stations tjsj
gempak::sflist::init;
gempak::sflist::run;
gempak::sflist::end;
puts [gempak::sflist::output];

The output of the scripts looks as follows

stn,yymmdd/hhmm,tmpf,relh,dwpf,pmsl,sped,drct
tjsj,090202/0000,78.80,73.95,69.80,-9999.00,4.63,70.00
tjsj,090202/0100,78.08,76.19,69.98,1017.70,4.63,60.00
tjsj,090202/0200,78.08,76.19,69.98,1017.70,4.63,70.00
tjsj,090202/0300,77.00,76.57,69.08,1017.90,4.63,90.00
...