Package com.luciad.format.grib

Class TLcdGRIB2ModelDecoder

java.lang.Object
com.luciad.format.grib.TLcdGRIB2ModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@Deprecated public class TLcdGRIB2ModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
Deprecated.
TLcdNetCDFModelDecoder can be used instead.
This model decoder decodes GRIB2 formats.

Each GRIB format contains the values of meteorological parameters (e.g., temperature, pressure...) at different grid points. Most of the formats are predictions.

Input files

File Required Entry point Description
*.grib2
*.grb2		 x x GRIB file containing one or more meteorological rasters

Supported file transfer protocols

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

Model structure

  • The models returned by this model decoder implement ILcd2DBoundsIndexedModel if only one dataset was included.
  • If multiple datasets are included in the format, the model decoder creates an ILcdModelContainer containing implementations for each included dataset.

Model descriptor

  • All models returned by this model decoder have a TLcdGRIB2ModelDescriptor.
  • The type name of the model descriptor is the display name of this decoder.

Model reference

  • All models returned by this model decoder have instances of ILcdGeodeticReference or ILcdGridReference as model references.

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.
  • If the decoded model is an ILcdModelContainer, the number of rasters equals its model count

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.
  • The property CreateModelTreeNodes allows to choose the ILcdModelContainer implementation for GRIB2 formats containing multiple datatsets. If this property is true, the model decoder generates an ILcdModelTreeNode implementation
    • .

More information

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;

Each GRIB2 format can contain one or multiple rasters. If a file contains only one raster, the model decoder generates one instance of a TLcdBoundsIndexedModel. When a GRIB2 file contains multiple rasters, the decoder generates a model list or a model tree, depending on the property createModelTreeNodes

Note that this decoder will only decode the first message of a GRIB2 file that contains multiple messages (called a bulletin). To decode all messages in a bulletin, use TLcdGRIBBulletinModelDecoder.

GRIB Format Data structure

The structure of the model and the model descriptor depend on the number of datasets included in the format.

GRIB2 file containing one raster

The decoded model is very similar to a decoded GRIB1 file, except for some additional meta data. The decimal scale factor, the reference value and the binary scale factor, and other raster specific properties are configured. The model descriptor contains one product definition.

GRIB2 file containing multiple rasters

The decoded model contains multiple rasters and therefore it is not possible to assign values to the raster properties in the TLcdGRIBModelDescriptor. In this case the model decoder generates for each raster a model and a TLcdGRIB2ModelDescriptor. This model descriptor contains the raster specific properties.

A common case: a GRIB2 file containing 2 rasters

This type of file is typically used for wind information. One of the rasters typically contains the wind direction and the other raster contains the wind speed. In order to display this information in one layer you can define an instance of a TLcdMultivaluedRaster.


 ILcdModelContainer model_container = ((ILcdModelContainer)model); ILcdModel u_model = model_container.getModel( 0 );
 ILcdModel v_model = model_container.getModel( 1 );
 ILcdRaster[] rasters =
 { ( ILcdRaster ) u_model.elements().nextElement(), ( ILcdRaster )v_model.elements().nextElement() };
 

 // Create a multi-valued raster that contains both rasters.
 TLcdMultivaluedRaster uv_raster = new TLcdMultivaluedRaster( rasters );
 

 // Create a new model.
 TLcd2DBoundsIndexedModel uv_model = new TLcd2DBoundsIndexedModel();
 

 // Create an array containing the model descriptors.
 TLcdRasterModelDescriptor[] descriptors =
 { ( TLcdRasterModelDescriptor ) u_model.getModelDescriptor(),
 ( TLcdRasterModelDescriptor ) v_model.getModelDescriptor()};
 

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

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

Supported versions and specifications

  • FM 92 GRIB Edition 2, 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.
  • Embedded PNG encoding is not supported

Disciplines - Categories - Parameters

GRIB2 parameters belong to categories and categories belong to disciplines. An example is the Meteorological discipline. This discipline has a number of categories of which one is "temperature". The "temperature" category has a number of parameters of which one is the "Maximum temperature" using "K" as unit. By default the mapping of these values is done as specified by the GRIB2 standard.

Decoding GRIB files with non-standard parameters and/or categories

It is possible to alter the mapping by loading new or altered parameter and category tables. This can be done by using addParameterTable(TLcdGRIB2ParameterTable, boolean) and addCategoryTable(TLcdGRIB2CategoryTable) before decoding the GRIB2 file with the customized category and/or parameter.
Since:
10.1

  • Constructor Details

    • TLcdGRIB2ModelDecoder

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

    • TLcdGRIB2ModelDecoder

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

  • Method Details

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Deprecated.
      Sets the input stream factory that is 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 used for creating input streams given source names.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      The input stream factory that is used.
      See Also:

    • addCategoryTable

      public void addCategoryTable(TLcdGRIB2CategoryTable aCategoryTable)
      Deprecated.
      Adds a category table. If a table with the same table version, center ID, subcenter ID and discipline ID already exists, it is replaced.

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

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

    • addParameterTable

      public void addParameterTable(TLcdGRIB2ParameterTable aParameterTable)
      Deprecated.
      Adds a parameter table. If a table with the same table version, center ID, subcenter ID, category ID and discipline ID already exists, it is replaced.

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

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

    • addCategoryTable

      public void addCategoryTable(TLcdGRIB2CategoryTable aCategoryTable, boolean aMatchCenter)
      Deprecated.
      Adds a category table. If a table with the same center ID, subcenter ID and discipline ID already exists, it is replaced.

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

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

    • addParameterTable

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

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

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

    • setDisciplineTable

      public void setDisciplineTable(TLcdGRIB2DisciplineTable aDisciplineTable)
      Deprecated.
      Sets the discipline table.
      Parameters:
      aDisciplineTable - The discipline table to be used.
      See Also:

    • getDisciplineTable

      public TLcdGRIB2DisciplineTable getDisciplineTable()
      Deprecated.
      Returns the discipline table.
      Returns:
      The discipline table that is used.
      See Also:

    • removeCategoryTable

      public void removeCategoryTable(TLcdGRIB2CategoryTable aCategoryTable)
      Deprecated.
      Removes a category table.
      Parameters:
      aCategoryTable - the parameter table to remove.

    • removeParameterTable

      public void removeParameterTable(TLcdGRIB2ParameterTable 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:
      "grib2".

    • 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 "grb2" or "grib2" (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:

    • isCreateModelTreeNodes

      public boolean isCreateModelTreeNodes()
      Deprecated.
      Returns true if the decoder creates model tree nodes for GRIB files with multiple datasets, false if the decoder creates model lists for GRIB files with multiple datasets.
      Returns:
      true if decoder creates model tree nodes for GRIB files with multiple datasets.
      See Also:

    • setCreateModelTreeNodes

      public void setCreateModelTreeNodes(boolean aCreateModelTreeNodes)
      Deprecated.
      Sets the behavior of the decoder when GRIB files contain multiple datasets.
      Parameters:
      aCreateModelTreeNodes - true if the decoder should create model tree nodes, false if it should create model lists.
      See Also: