Geo::ReadGRIB - Perl extension that gives read access to GRIB "GRIdded Binary" format Weather data files.

wgrib.c

Methods
SEE ALSO
AUTHOR
COPYRIGHT AND LICENSE

NAME

Geo::ReadGRIB - Perl extension that gives read access to GRIB ``GRIdded Binary'' format Weather data files.

SYNOPSIS

  use Geo::ReadGRIB;
  $w = new Geo::ReadGRIB "grib-file";


  $w->getCatalog();         #
  $w->getCatalogVerbose();  # or just use $w->getFullCatalog() 
                            #


  # The object now contains the full inventory of the GRIB file
  # including the "verbose" text description of each parameter


  print $w->show();


  $w->extract(data_type, lat, long, time);

  #
  # or $w->extractLaLo(data_type, lat1, long1, lat2, long2, time);
  # to extract a range of locations
  #

  print $w->getError(),"\n";    # undef if no error
  $data = $w->getDataHash();


  # $data contains a hash reference to all grib data extracted
  # by the object in its lifetime.
  #  
  # $data->{time}->{lat}->{long}->{data_type} now contains data 
  # for data_type at lat,long and time unless there was an error

DESCRIPTION

Geo::ReadGRIB is an object Perl module that provides read access to data distributed in GRIB files. Specifically, I wrote it to access NOAA Wavewatch III marine weather model forecasts which are packaged as GRIB. Wavewatch GRIB's can currently be found under

ftp://polar.ncep.noaa.gov/pub/waves/

GRIB stands for ``GRIdded Binary'' and it's a format developed by the World Meteorological Organization (WMO) for the exchange of weather product information. See for example

http://www.nco.ncep.noaa.gov/pmb/docs/on388/

for more about the GRIB format.

wgrib.c

Geo::ReadGRIB uses the C program wgrib to retrieve the GRIB file catalog and to extract the data. wgrib.c is included in the distribution and will compile when you make the module. The resulting executable is named wgrib.exe and should install in the same location as ReadGRIB.pm. ReadGRIB will search for wgrib.exe at run time and die if it can't find it.

wgrib.c is known to compile and install correctly with Geo::ReadGRIB on FreeBSD, LINUX and Windows. In all cases the compiler was gcc and on Windows ActivePerl and nmake were used and the CC=gcc option was used with Makefile.PL I've also been able to compile wgrib.c with gcc on Solaris Sparc and i386.

wgrib.exe creates a file called wgrib.tmp.XXXXXXXXX in the local directory where the X's are random chars. The id that runs a program using Geo::ReadGRIB needs write access to work. This temp file will be removed after use by each method calling wgrib.exe

Methods

$object = new Geo::ReadGRIB ``grib_file'';

Returns a Geo::ReadGRIB object that can open GRIB format file ``grib_file''. wgrib.exe is used to extract full header info from the ``self describing'' GRIB file.

$object->getCatalog();

$object->getCatalogVerbose();

$object->getFullCatalog();

Retrieve Catalog info from the GRIB file.

getCatalog() gets most of the info including the critical offset index for each data type and time in the file.

getCatalogVerbose() will get the full text descriptions of data items.

getFullCatalog() just runs both getCatalog() and getCatalogVerbose() . Each method invocation needs to call wgrib.exe. Just running getCatalog() may save some cycles if full descriptions aren't needed.

$object->getParam(param);

$object->getParam(``show'');

getParam(param) returns a scalar with the value of param where param is one of TIME, LAST_TIME, La1, La2, LaInc, Lo1, Lo2, LoInc, fileName.

: TIME is the time of the earliest data items in epoch seconds.
: LAST_TIME is the time of the last data items in epoch seconds.
: La1 La2 First and last latitude points in the GRIB file (or most northerly and most southerly).
: LaInc The increment between latitude points in the GRIB file.
: Lo1 Lo2 First and last longitude points in the GRIB file (or most westerly and most easterly).
: LoInc The increment between latitude points in the GRIB file.
: filename The file name of the GRIB file this object will open to extract data.

getParam(show) Returns a string listing the names of all published parameters.

$object->show();

Returns a formatted text string description of the data in the GRIB file. This includes latitude, longitude, and time ranges, and data type text descriptions (if getCatalogVerbose() has run).

$object->extractLaLo(data_type, lat1, long1, lat2, long2, time);

Extracts forecast data for a given type and time for a range of locations. The locations will be all (lat, long) points in the GRIB file inside the rectangular area defined by (lat1, long1) and (lat2, long2) where lat1 >= lat2 and long1 <= long2. That is, lat1 is north or lat2 and long1 is west of long2 (or is the same as...)

Since extractLaLo() needs only one call to wgrib and one temp file open, this is faster than using extract() to get the same data points.

$object->extract(data_type, lat, long, [time]);

Extracts forecast data for given type and location. Time is optional. Extracts data for all times in file unless a specific time is given in epoch seconds.

lat and long will be in the range -90 to 90 degrees lat and 0 to 359 degrees long. Longitude in GRIB files is 0 to 359 east. If you have degrees in longitude west you will need to convert it first. If lat or long is out of range for the current file an error will be set ( see getError() ).

time will be in epoch seconds as returned, for example, by Time::Local. If the time requested is in the range of times in the file but not one of the exact times in the file, the nearest existing time will be used. An error will be set if time is out of range.

type will be one of the data types in the data or an error is set.

$object->getError();

Returns string messages for the last error set. If no error is set getError() returns undef. Any method that sets errors will clear errors first when called. It's good practice to check errors after an extract().

$object->getDataHash();

Returns a hash ref with all the data items in the object. This will be all the data extracted from the GRIB file for in the life of the object.


The hash structure is

   $d->{time}->{lat}->{long}->{type}

AUTHOR

Frank Cox, <frank.l.cox@gmail.com>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.

Geo::ReadGRIB - Perl extension that gives read access to GRIB "GRIdded Binary" format Weather data files.