Some software internals can be accessed throught the Console, which can be displayed under the Tools menu. This allows permits scripting for those familiar with TCL.

The TCL Console

The “console,” available from the Tools menu, is a fully-featured Tcl/Tk interpreter with access to Bluewater internals. You can paste TCL scripts into this window and run them. A collection of tools for managing GriB files can be run from the console command line. In addition, any Tcl script added into bluewater.pref (AppData/bluewater folder) will be executed at startup.

Manipulating Gribs From the Console

To use the full set of GRiB tools described below it will help to understand Tcl programming and the Tk widget model. Each GRiB sequence is stored and accessed as an object in the form of a TK-style widget. When the program loads GriBs, it assigns the corresponding object an internal name of the form "gnn", where nn is a sequence of digits. The internal names of loaded Grib files are displayed in the Grib Manager window.

For example, you can view raw Grib values for the sequence gnn at period <period> by opening the console and typing:

         gm::draw_raw_data $c raw gnn <period>

The effect of this operation is to simply display the actual numerical value of the Grib data at period <period> at every grid point. The forecast periods for a Grib can be viewed in the Grib Manager, or by a grib object call

         g?? periods

Remove the raw data by typing:

         $c delete raw

Some examples of things you can do: to view the header information for the GRiB with internal name g00, type into the console:

	g00 header

To view the Grib data interpolated at 12N, 98W on July 1, 2011 12:00 Z, (assuming the GRiB covers that time and place) type into the console:

        g00 data -point 12 -98 -attime "2011-07-01 12:00 Z"

To copy the GRiB to a new GRiB named "mygrib", using only every other data point, and write it to a file, type into the console:

        g00 copy mygrib -step 2
        mygrib write -file mygrib.grb

If you create your own GRiB mygrib from the console, by loading files or copying or using the other functions described below, you can make the Grib Manager aware of it, so that it can be displayed in the main window. In the console window type:

        gm::registerGrib mygrib

You may also use the list form:

        gm::registerGrib [list mygrib1 mygrib2 ... ]

The Grib Widget Documentation

A grib widget is created by the following command.
      grib  <gribID> {-file <gribfile> | -data <datalistn>}

"grib" creates one or more new grib widgets, one for each weather parameter in the input data. It either gets the data from a GRIB file (-file option) or from the command line (-data option). It generates a sequence of new TCL commands with name <gribID>, if only one sequence is constructed, or names

<gribID>i>, i=0,1,2,3...
if the -file option is used and the file contains multiple GRiB sequences. The widget names are returned by "grib" as a list. The command takes the option:

  -messages <varname>

A list of error messages generated while processing subsequence -file of -data options will be stored in <varname>. If the -data option is used, the grib data is given on the the command line, as follows.

   -data [list t1 <record1> ? t2 <record2>... t_nx <recordn>?]

ti: integer forecast time for this record, in forecast time units. (Determines P1 in PDS). Default time unit is hours. For a different unit, modify -forecastunit with widget configure.

   recordi: [list   ... ]
   rowi:  [list d(i,0) d(i,1) ... d(i,nx-1)]
   d(i,j): the value at latitude lat0+i*dlat, longitude lon0+j*dlon
           either a single value, or a list {u v} giving vector values.

PDS and GDS values, including lat0, lon0, dlat, and dlon, can be modified by subsequent configure calls to the returned grib widget.

Once a grib widget has been created, the data in the sequence can be accessed with a widget ccommand:

   gribID ?command? ?options?

The grib widget accepts the following commands:

      header       Returns a list of (keyword value) pairs from the sequence header.
      periods      Returns a list of sequence periods.
      destroy      Destroy the widget command.
      configure    Set grib attributes
           example: set the grib creation date to Jan 12, 2007
	     g00 config -century 21 -year 7 -month 1 -day 12
	     with no arguments, returns a list of pairs of "-arg
	     value" pairs for all modifiable attributes.  Thus 
	     "eval g1 configure [g2 configure]" will set g1 to match g2 in
	     all modifiable attributes.
      cget       Get grib attributes.
           With no arguments, returns a list of "-arg value" pairs for all
	   attributes, including non-modifiable ones.
	   With a list of attribute options, returns a list of corresponding 
	   values in the same order.
      periods    Return a list of valid times for each period in
                 the sequence.
      data       Returns the data values at each grid point for a given period.
	   If the data is scalar, the value will be returned as a single number
	   if vector, then value is returned as a 2 element list {U V}, where
	   U is the value of the grib "U" coordinate, positive in the East direction and
	   V is the value of the "V" coordinate, positive in the North direction

	   The data is returned as a list of lists: {row0 row1 row2} with latitude and
	   longitude of data points given implicitly: the ith element in rowj is at
	   latitude lat0 + j*dlat and longitude lon0 + i*dlon, where lat0, lon0, dlat, dlon
	   are available with the "cget" command.  Note that since dlat,dlon are (normally)
	   positive, this means the rows occur in order of increasing latitude.

           The data command takes the following options:

	   -norm <TF>:  <TF> is a boolean value; if true, then vector data is return 
            as a normalized triple {u v m}, so that (u,v) is a unit vector 
            and (U,V) = (m*u, m*v).

	   -period <i>: return the data for the ith, defaults to period 0

           -point <lat> <lon> returns only an interpolated value at lat, lon, at the
	    valid time of whatever period is specified.  <lat> and <lon> must lie
	    within the bounds of lat0, lon0, latmax, lonmax, or an error will be

	   -attime <t>: ignored unless -point is specified.  Causes 3-D
 	    interpolation at lat, lon, and time <t>.  <t> is the
	    interpolation time, in any time format acceptable to Tcl.
	    Overrides -period switch.  If the time does not fall between 
            the forecast time of the first period, and the forecast time
            of the last period, an error is generated, unless -extrapolate True
            is added, in which case the time is pinned to the nearest of
            first or last time.

      surface     Construct a triangulated surface from grid data.  Takes the 
                  following options:
          -contours <T/F> If true, returns a list of contour lines.  Each line is 
                        a list of lat/lon coordinates, representing the intersection of
                        the surface with a clip plane specified in the next option.
          -clipplanes [zval0 zval1 ...] The surface is clipped against the horizontal 
                        planes implied by the z values.

      write   -file <filename> -append <T/F>
           Appends grib records to an output file
	   -file <fname> : output file.  If unspecified, default is

      copy  <newname> ?-step <k> -region <region-spec>?
           Create a copy of this grib with name newname
           -region lat0 lon0 lat1 lon1 | [list lat0 lon0 lat1 lon1]
               defines a subregion of the grib to extract
           -period i
               only extract the ith period.