The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Geo-ReadGRIB-0.98
River stage zero No dependents
++
/ Geo::ReadGRIB

NAME

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

SYNOPSIS

  use Geo::ReadGRIB;
  $w = new Geo::ReadGRIB "grib-file";
  
  $w->getFullCatalog() # only needed for text descriptions and units.
  
  # 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 

  $plit = $w->extractLaLo(data_type, lat1, long1, lat2, long2, time); 
  
  die $w->getError,"\n" if $w->getError;    # undef if no error

  while (  $place =  $plit->current and $plit->next ) {
      
      # $place is a Geo::ReadGRIB::Place object

      $time       = $place->thisTime;
      $latitude   = $place->lat;
      $longitude  = $place->long;
      $data_types = $place->types; # an array ref of type names
      $data       = $place->data;

      # do something with each place in the extracted rectangular area
  }


  $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.

This version introduces the Geo::ReadGRIB::PlaceIterator class. PlaceIterator objects are returned by extractLaLo() and can be used for an ordered traversal of the extracted data for a given time. This greatly simplifies map image creation and other data analysis tasks. See Geo::ReadGRIB::PlaceIterator documentation and demo programs in the examples directory.

Wavewatch III 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 or Straberry Perl and dmake 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->getFullCatalog();

getFullCatalog() will extract the full text descriptions of data items in the GRIB file and store them in the object.

$object->getParam("show");

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

$object->getParam(param);

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.

$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 getFullCatalog() has been run).

$plit = $object->extractLaLo([data_type, ...], lat1, long1, lat2, long2, time);

Extracts forecast data for a given type and time and data type(s) 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...)

data_type is either a data type name as a string of a list of data name strings as an array reference.

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.

Returns a Geo::ReadGRIB::PlaceIterator object containing the extracted data which can be used to iterate through the data in order sorted by lat and then long.

Extracted data is also retained in the ReadGRIB object data structure.

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 one at a time.

$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}
$object->getCatalog() DEPRECATED;
$object->getCatalogVerbose() DEPRECATED;

getCatalog() is DEPRECATED and no longer does anything but set an error. It's function of Getting the critical offset index for each data type and time in the file is now done during object creation.

getCatalogVerbose() is also DEPRECATED as redundent and now just calls getFullCatalog(). and sets an error.

SEE ALSO

For more on wgrib.c see

http://www.cpc.ncep.noaa.gov/products/wesley/wgrib.html

For more on Wavewatch III see

http://polar.ncep.noaa.gov/waves/wavewatch/wavewatch.html

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2006, 2009 by Frank Cox

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.