Package com.luciad.format.grib

Class TLcdGRIB1ModelDecoder

java.lang.Object
com.luciad.format.grib.TLcdGRIB1ModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@Deprecated public class TLcdGRIB1ModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
Deprecated.
TLcdNetCDFModelDecoder can be used instead.
This model decoder decodes meteorological rasters in the GRIB version 1 format (GRIdded Binary).

Each GRIB file contains the values of a single meteorological parameter (e.g., temperature, pressure...) at different grid points. The parameter values in the file are not the actual values, but internal values to eliminate redundancy and negative or broken values. These internal values are decoded as unsigned shorts.

The actual value of a parameter can be calculated with the formula:

Y * 10D = R + (X*2E)

where

  • Y = actual or unpacked value;
  • D = decimal scale factor;
  • R = reference value;
  • X = internal value;
  • E = binary scalefactor;

Input files

File Required Entry point Description
*.grb
*.grib
*.dat		 x x GRIB file containing the meteorological raster

Supported file transfer protocols

  • This model decoder supports all transfer protocols that are supported by the inputStreamFactory of this decoder.

Model structure

  • This model decoder creates a model per GRIB message file.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

  • All models returned by this model decoder have a TLcdGRIBModelDescriptor. Among other information about the GRIB data, it contains the values of D, R and E. For convenience, it already provides methods to calculate actual values from internal values, and vice versa: getActualValue and getInternalValue.
  • Furthermore, the model descriptor contains information about the parameter that is retrieved from the GRIB parameter tables: parameter description, abbreviation, and measurement unit. By default, the decoder supports the standard parameter table versions (1, 2, 3, 128, 129, and 130). These parameter tables are loaded from the resource files <version>_NCEP.txt. If a GRIB file refers to a parameter table with another version, the model descriptor will contain "Unknown" values, unless the parameter table has been explicitly registered with the model decoder. The user may register extra parameter tables (or override default parameter tables) using the methods addParameterTable(ILcdGRIBParameterTable) and addParameterTable(ILcdGRIBParameterTable,boolean). The most convenient way to create parameter tables is by decoding them from files, using the class TLcdGRIB1ParameterTableDecoder.
  • The type name of the model descriptor is the display name of this decoder.

Model elements

  • Each decoded model contains a single element that implements ILcdRaster. The raster has a single tile with unsigned shorts that represent the internal values of the parameter.

Useful settings

  • The property colorModel allows to override the default 16-bits index color that is attached to the decoded rasters, since GRIB files don't contain any color information. Note that the indexing must be based on the internal GRIB values, not on the actual values.

Sample code


 TLcdGRIB1ModelDecoder decoder = new TLcdGRIB1ModelDecoder();

 ILcdModel model = decoder.decode("data.grb");

In some cases, you may want to combine related parameters from to decoded models into a single representation, for instance the u-component and the v-component of the wind speed. You can do this as follows: 


 TLcdGRIB1ModelDecoder decoder = new TLcdGRIB1ModelDecoder();

 ILcdModel u_model = decoder.decode("u_component.grb");
 ILcdModel v_model = decoder.decode("v_component.grb");

 ILcdRaster[] uv_rasters = {
   (ILcdRaster)u_model.elements().nextElement(),
   (ILcdRaster)v_model.elements().nextElement()
 };

 ILcdMultiValuedRaster raster = new TLcdMultivaluedRaster(rasters);

 TLcdRasterModelDescriptor[] descriptors = {
   (TLcdRasterModelDescriptor)u_model.getModelDescriptor(),
   (TLcdRasterModelDescriptor)v_model.getModelDescriptor()
 };

 ILcdModelDescriptor uv_descriptor =
   new TLcdMultivaluedRasterModelDescriptor(u_model.getModelDescriptor().getSourceName(),
                                            u_model.getModelDescriptor().getDisplayName(),
                                            u_model.getModelDescriptor().getTypeName(),
                                            descriptors);

 TLcd2DBoundsIndexedModel uv_model = new TLcd2DBoundsIndexedModel();
 uv_model.setModelDescriptor(uv_descriptor);
 uv_model.setModelReference(u_model.getModelReference());
 uv_model.addElement(uv_raster, ILcdFireEventMode.NO_EVENT);

Performance tips

  • A GRIB message often only contains a single tile from a larger raster. For instance, a raster covering the entire globe may be partitioned into 8 tiles, each covering 90 by 90 degrees. For further processing and visualization, it is generally more efficient to collect the individual tiles from the decoded rasters and put them in a single raster.

Thread safety

  • The decoding of models is thread-safe, as long as no properties are changed during the decoding.
  • The decoded models and elements are thread-safe for read access, on the condition that a thread-safe buffer is used.

Supported versions and specifications

  • FM 92-VIII Ext. GRIB (GRIdded Binary), World Meteorological Organization (WMO)

Known limitations

  • Only the following grids are supported:
    • Latitude/Longitude Grid or Equidistant Cylindrical Projection Grid
    • Mercator Projection Grid
    • Lambert Conformal Projection Grid
    • Polar Stereographic Projection Grid
  • Complex packing is not supported.
  • Spherical harmonic coefficients are not supported.
  • Predefined bitmaps are not supported.
  • Predefined grids are not supported.
Since:
10.1
See Also:

  • Constructor Details

    • TLcdGRIB1ModelDecoder

      public TLcdGRIB1ModelDecoder()
      Deprecated.
      Creates a new TLcdGRIB1ModelDecoder, with a globally shared buffer for caching tiles.
      See Also:

    • TLcdGRIB1ModelDecoder

      public TLcdGRIB1ModelDecoder(ILcdBuffer aBuffer)
      Deprecated.
      Creates a new TLcdGRIB1ModelDecoder.
      Parameters:
      aBuffer - the shared buffer that decoded models will use.

  • Method Details

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Deprecated.
      Sets the input stream factory that will be used for creating input streams given source names.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - The input stream factory to be used.
      See Also:

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Deprecated.
      Returns the input stream factory that is be used for creating input streams given source names.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      The input stream factory that is used.
      See Also:

    • addParameterTable

      public void addParameterTable(ILcdGRIBParameterTable aParameterTable)
      Deprecated.
      Adds a parameter table. If a table with the same version, center ID, and subcenter ID already exists, it will be replaced.

      The decoder will first try to use the parameter table with a matching table version, center ID, and subcenter ID. If it can't find it, it it will fall back on the parameter table that only matches the table version.

      Parameters:
      aParameterTable - the parameter table to add.
      See Also:

    • addParameterTable

      public void addParameterTable(ILcdGRIBParameterTable aParameterTable, boolean aMatchCenter)
      Deprecated.
      Adds a parameter table. If a table with the same version, center ID, and subcenter ID already exists, it will be replaced.

      The decoder will first try to use the parameter table with a matching table version, center ID, and subcenter ID. If it can't find it, it it will fall back on the parameter table that only matches the table version, if non-exact matches are allowed.

      Parameters:
      aParameterTable - the parameter table to add.
      aMatchCenter - a boolean flag that indicates if the center ID and subcenter ID have to match in order for this table to be used.

    • removeParameterTable

      public void removeParameterTable(ILcdGRIBParameterTable aParameterTable)
      Deprecated.
      Removes a parameter table.
      Parameters:
      aParameterTable - the parameter table to remove.

    • setColorModel

      public void setColorModel(ColorModel aColorModel)
      Deprecated.
      Sets the color model that is attached by default to the decoded rasters. The default is null.
      Parameters:
      aColorModel - an 8-bit or 16-bit IndexColorModel that is compatible with the GRIB data to be decoded.
      See Also:

    • getColorModel

      public ColorModel getColorModel()
      Deprecated.
      Returns the color model that is attached by default to the decoded rasters.
      Returns:
      The default color model.
      See Also:

    • setSampleStrategy

      public void setSampleStrategy(int aSampleStrategy)
      Deprecated.
      Sets the sampling strategy that is used for displaying raster data.
      Parameters:
      aSampleStrategy - one of
      • TLcdGRIBModelDecoder.NORTH_WEST_CORNER,
      • TLcdGRIBModelDecoder.SOUTH_WEST_CORNER,
      • TLcdGRIBModelDecoder.NORTH_EAST_CORNER,
      • TLcdGRIBModelDecoder.SOUTH_EAST_CORNER,
      • TLcdGRIBModelDecoder.MINIMUM,
      • TLcdGRIBModelDecoder.MAXIMUM,
      • TLcdGRIBModelDecoder.AVERAGE
      • TLcdGRIBModelDecoder.BILINEAR.
      See Also:

    • getSampleStrategy

      public int getSampleStrategy()
      Deprecated.
      Returns the sampling strategy that is used for displaying raster data.
      Returns:
      The sampling strategy
      See Also:

    • getDefaultExtension

      public String getDefaultExtension()
      Deprecated.
      Gets the default file extension of GRIB messages.
      Returns:
      "grb".

    • getDisplayName

      public String getDisplayName()
      Deprecated.
      Description copied from interface: ILcdModelDecoder
      Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      "grib".

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      Deprecated.
      Description copied from interface: ILcdModelDecoder
      Checks whether this model decoder can decode the specified data source. It is acceptable for this method to return true for a source name while decode throws an exception for that same source name.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the file extension of a file, but not that the file exists or contains expected content.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source to be verified; typically a file name or a URL.
      Returns:
      true if the given file name has extension "grb", "grib", or "dat" (possibly extended with ".gz" or ".zip").
      See Also:

    • decode

      public ILcdModel decode(String aSourceName) throws IOException
      Deprecated.
      Description copied from interface: ILcdModelDecoder
      Creates a new model from the given data source.
      Specified by:
      decode in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source to be decoded; typically a file name or a URL.
      Returns:
      A model containing the decoded data. While null is allowed, implementors are advised to throw an error instead.
      Throws:
      IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below. 
      
   public ILcdModel decode( String aSourceName ) throws IOException {
      try (InputStream input = fInputStreamFactory.createInputStream(aSourceName)) {
         // Perform decoding ...
      } catch (RuntimeException e) {
         throw new IOException(e);
      }
   }
      See Also: