Package com.luciad.format.bufr

Class TLcdBUFRModelDecoder

java.lang.Object
com.luciad.format.bufr.TLcdBUFRModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder, ILcdStatusSource
@LcdService(priority=20000) public final class TLcdBUFRModelDecoder extends Object implements ILcdModelDecoder, ILcdStatusSource, ILcdInputStreamFactoryCapable
This model decoder decodes BUFR files.

A BUFR file consists of one or more BUFR messages, with each message containing one or more subsets. The structure for each subset in a message is the same, but the data differs. The data in a subset are scientific observations (e.g height, cloud type, degree of turbulence, ...). A collection of related observations describes a weather feature (e.g. a cloud, a jet-stream, clear air turbulence, ...). To make sense of which observations belong together to make a weather feature, a format needs to be defined. This model decoder supports the following formats:

  • SIGWX

SIGWX

SIGWX BUFR files contain forecast information that are used for flight planning. The BUFR messages in a BUFR file with SIGWX weather features should be structured according to one of the following SWH or SWM SIGWX formats:
  • JETS - Jet-streams
  • M-JETS - SWM jet-streams
  • CAT - Clear Air Turbulence (C.A.T.)
  • M-CAT - SWM Clear Air Turbulence (C.A.T.)
  • CLOUD - Embedded Cumulonimbus
  • M-CLOUD - SWM cloud, in-cloud icing and turbulence
  • TROP - Tropopause height
  • M-TROP - SWM Tropopause height
  • V_T_S - Tropical cyclone, Sandstorms, Volcanoes, Radiation incidents
The SIGWX formats FRONTS (Frontal systems) and M-FRONTS (SWM fronts) are also accepted but will result in no weather features.

A SIGWX BUFR message will have a header that describes the type of weather features that are included in the message. This model decoder checks the header of the BUFR messages to the determine what types of weather features to decode from the BUFR file. For SIGWX weather features the following table describes what features are decoded for every header.

Headers Weather Features
JUWE96 EGRR, JUWE96 KKCI, JUTE00 EGRR, JUTE00 KKCI Jet-streams
JUCE00 EGRR, JUCE00 KKCI, JUME00 EGRR, JUME00 KKCI Clear Air Turbulence
JUBE99 EGRR, JUBE99 KKCI, JUNE00 EGRR, JUNE00 KKCI Clouds
JUTE97 EGRR, JUTE97 KKCI, JUOE00 EGRR, JUOE00 KKCI Tropopause heights
JUVE00 EGRR, JUVE00 KKCI Storms, volcanic clouds, radiation incidents
JUFE00 EGRR, JUFE00 KKCI, JUJE00 EGRR, JUJE00 KKCI No weather features

Input

File Required Entry point Description
*.bufr, *.bin, no extension x x
 The BUFR file
Note that for .bin files or files with no extension the decoder looks for the 'BUFR' byte indicating the start of a BUFR message

Supported file transfer protocols

  • This model decoder decodes data from a file system.

Model structure

  • This model decoder creates a model for every BUFR subset.
  • If the input BUFR file has more than one message or subset, the resulting model is an ILcdModelTreeNode.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

  • If SIGWX weather features are decoded, the model descriptor will be TLcdSIGWXModelDescriptor. This descriptor will include the SIGWX header information like forecast data and height level boundaries.
  • The type name of the model descriptor is the display name of this decoder.

Model reference

Model elements

  • Each decoded leaf model contains elements that implement ILcdDataObject.
    • For BUFR files containing SIGWX data, see TLcdSIGWXDataTypes for the possible weather features and their properties.

Sample code


 ILcdModelDecoder decoder = new TLcdBUFRModelDecoder();
 ILcdModel model = decoder.decode("file.bufr");

Thread safety

  • The decoded models are thread-safe for read access when taking a read lock.

Supported versions and specifications

The BUFR file has to adhere to the following requirements:

  • The edition of the BUFR file should be 2, 3 or 4.
  • The BUFR file should use the Meteorology master table defined by the WMO.
  • SIGWX data in the BUFR files should follow the requirements laid out in edition 19 of the ICAO Annex 3.

Known limitations

  • This model decoder assumes that all coordinates in a BUFR file use the WSG84 reference. It is not possible to change this.
Since:
2020.0

  • Field Details

    • BUFR_TYPE_NAME

      public static final String BUFR_TYPE_NAME

      The type name for BUFR data. The model descriptor of models decoded by this decoder will have the type name set to this value.

      This constant can be used to check if a model has BUFR data. Note that an instanceof check on the model descriptor can be used to determine the specific data type (e.g. SIGWX data will have a TLcdSIGWXModelDescriptor as the model descriptor).

      See Also:

  • Constructor Details

    • TLcdBUFRModelDecoder

      public TLcdBUFRModelDecoder()
      Create a new decoder instance.

  • Method Details

    • getDisplayName

      public String getDisplayName()
      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:
      the displayable name of this ILcdModelDecoder.

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      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 this decoder can likely decode the data specified by the source name, false otherwise.
      See Also:

    • decode

      public ILcdModel decode(String aSourceName) throws IOException
      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:

    • addStatusListener

      public void addStatusListener(ILcdStatusListener aListener)
      Description copied from interface: ILcdStatusSource

      Registers the given listener so it will receive status events from this source.

      In case you need to register a listener which keeps a reference to an object with a shorter life-time than this status source, you can use a ALcdWeakStatusListener instance as status listener.

      Specified by:
      addStatusListener in interface ILcdStatusSource
      Parameters:
      aListener - The listener to be notified when the status has changed.

    • removeStatusListener

      public void removeStatusListener(ILcdStatusListener aListener)
      Description copied from interface: ILcdStatusSource
      Removes the specified listener so it is no longer notified.
      Specified by:
      removeStatusListener in interface ILcdStatusSource
      Parameters:
      aListener - The listener to remove.

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the input stream factory to be used. When the input stream factory is set,
      1. This model decoder reads all the data from the created stream and stores it in a temporary file. The temporary file is created by File.createTempFile(String, String) in the OS temporary files directory.
      2. The temporary file is used as the BUFR source file.
      3. The temporary file is deleted either when the root NetCDF model is disposed or JVM terminates normally.
      Note: Ensure that the running process has enough privileges to read and write temporary files directory to use an input stream as a BUFR data source.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the input stream factory to be used.
      See Also:

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Description copied from interface: ILcdInputStreamFactoryCapable
      Returns the input stream factory that is used.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the input stream factory that is used.