Package noaa.coastwatch.io

Class EarthDataReader

java.lang.Object
noaa.coastwatch.io.EarthDataReader
Direct Known Subclasses:
HDFReader, NCReader, NOAA1bFileReader, NOAA1bReader, OpendapReader
public abstract class EarthDataReader extends Object
An EarthDataReader obtains earth data from a data source and provides it to the user in a consistent format. A reader should do the following:
  • Construct from some type of file or data stream
  • Read global information into a EarthDataInfo object
  • Report the number of DataVariable objects
  • Read a "preview" of a DataVariable, which consists of all attributes but no actual data values
  • Read a DataVariable object with data
  • Close the source when no longer needed
The only methods that child classes must implement are: as well as a constructor that sets the protected info and variables variables and fills the rawMetadataMap map.
Since:
3.1.0
Author:
Peter Hollemans

  • Field Details

    • info

      protected EarthDataInfo info
      Earth data info object.

    • variables

      protected String[] variables
      Earth data variable names.

    • dataProjection

      protected static boolean dataProjection
      The data projection flag, true if reading explicit lat/lon data should return a DataProjection rather than a SwathProjection.

    • rawMetadataMap

      protected Map rawMetadataMap
      The raw metadata map.

  • Constructor Details

    • EarthDataReader

      protected EarthDataReader(String source)
      Creates a new earth data reader.
      Parameters:
      source - the data source.

  • Method Details

    • setUnitsMap

      public static void setUnitsMap(Map map)
      Sets the variable name to units map. If set, data variables accessed via getPreview(int) and getVariable(int) will automatically have their units converted to the new units before being passed to the caller.
      Parameters:
      map - the new map of variable name to units string.

    • setDataProjection

      public static void setDataProjection(boolean flag)
      Sets the data projection flag. This is only applicable to readers that deal with earth transforms stored as explicit earth location data. When true, the data projection flag forces the reader to return a DataProjection object for the earth transform when reading explicit latitude and longitude data, rather than interpolating the data and returning a SwathProjection. The main difference is that a DataProjection cannot be used to transform an EarthLocation object into a DataLocation object. Generally, setting this flag is only desirable if there are inherent problems with interpolating the earth location data. By default, the reader is set to return a SwathProjection.
      Parameters:
      flag - the data projection flag.

    • getStatisticsVariables

      public List<String> getStatisticsVariables()
      Gets the list of all variable names that have associated statistics.
      Returns:
      the list of variable names.

    • getStatistics

      public Statistics getStatistics(String name)
      Gets the statistics data stored for the specified variable name.
      Parameters:
      name - the variable name.
      Returns:
      the statistics, or null if the variable name has no associated statistics data.
      See Also:

    • putStatistics

      public void putStatistics(String name, Statistics stats)
      Associates statistics with the specified variable name.
      Parameters:
      name - the variable name.
      stats - the statistics data.

    • getInfo

      public EarthDataInfo getInfo()
      Gets the earth data info object.

    • getVariables

      public int getVariables()
      Gets the total count of data variables.

    • getName

      public String getName(int index)
      Gets the variable name at the specified index.

    • getDataFormat

      public abstract String getDataFormat()
      Gets the data format description.

    • getSource

      public String getSource()
      Get the earth data source.

    • getSceneTime

      public String getSceneTime()
      Gets the scene time based on the first grid variable.
      Returns:
      the scene time or unknown if the scene time cannot be determined.

    • containsVariable

      public boolean containsVariable(String name)
      Determines if a variable exists in the reader.
      Parameters:
      name - the variable name to search for.
      Returns:
      true if the variable exists or false if not.
      Since:
      3.5.0

    • getIndex

      public int getIndex(String name)
      Retrieves a variable index based on the name.
      Parameters:
      name - the variable name to search for.
      Returns:
      the variable index, or -1 if the variable could not be found.

    • getPreview

      public DataVariable getPreview(int index) throws IOException
      Creates a data variable preview. A preview contains all metadata but no data value array. The preview can be used in a filtering loop to determine if the reading of the variable data is desired, as I/O can be a time-intensive operation.
      Parameters:
      index - the index of the variable to preview. Indexing starts at 0.
      Returns:
      a data variable object with data value array of length 1.
      Throws:
      IOException - if the data source had I/O errors.
      See Also:

    • getPreviewImpl

      protected abstract DataVariable getPreviewImpl(int index) throws IOException
      Implementation for the subclass.
      Throws:
      IOException
      See Also:

    • getChunkProducer

      public ChunkProducer getChunkProducer(String name) throws IOException
      Creates a chunk producer for the specified variable.
      Parameters:
      name - the variable name.
      Returns:
      a chunk producer for the specified variable.
      Throws:
      IOException
      Since:
      3.5.0

    • getPreview

      public DataVariable getPreview(String name) throws IOException
      Creates a data variable preview. A preview contains all metadata but no data value array. The preview can be used in a filtering loop to determine if the reading of the variable data is desired, as I/O can be a time-intensive operation.
      Parameters:
      name - the name of the variable to get.
      Returns:
      a data variable object with data value array of length 1.
      Throws:
      IOException - if the data source had I/O errors, or the variable was not found.
      See Also:

    • getVariable

      public abstract DataVariable getVariable(int index) throws IOException
      Creates a data variable object. The full data is read into the object.
      Parameters:
      index - the index of the variable to get. Indexing starts at 0.
      Returns:
      a data variable object with full data value array.
      Throws:
      IOException - if the data source had I/O errors.
      See Also:

    • getVariable

      public DataVariable getVariable(String name) throws IOException
      Creates a data variable object. The full data is read into the object.
      Parameters:
      name - the name of the variable to get.
      Returns:
      a data variable object with full data value array.
      Throws:
      IOException - if the data source had I/O errors, or the variable was not found.
      See Also:

    • close

      public abstract void close() throws IOException
      Closes the reader and frees any resources.
      Throws:
      IOException - if the data source had I/O errors.

    • finalize

      protected void finalize() throws Throwable
      Closes the resources associated with the data source.
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • getAllGrids

      public List<String> getAllGrids() throws IOException
      Gets a list of all 2D grid variable names in this reader.
      Returns:
      the list of grid variable names.
      Throws:
      IOException - if an error occurred getting the list of grids.

    • getAllVariables

      public List<String> getAllVariables()
      Gets a list of all variable names in this reader.
      Returns:
      the list of variable names.

    • updateNavigation

      public void updateNavigation(List variableNames, AffineTransform affine) throws IOException
      Updates the navigation transform for the specified list of variables (optional operation). Classes that override this method should also override canUpdateNavigation().
      Parameters:
      variableNames - the list of variable names to update.
      affine - the navigation transform to apply. If null, the navigation is reset to the identity.
      Throws:
      IOException - if an error occurred writing the file metadata.
      UnsupportedOperationException - if the class does not support navigation transform updates.
      See Also:

    • canUpdateNavigation

      public boolean canUpdateNavigation()
      Determines the ability of the file format to have its navigation updated. Classes that override updateNavigation(java.util.List, java.awt.geom.AffineTransform) should also override this method.
      Returns:
      true if the navigation can be updated, or false if not.
      See Also:

    • getRawMetadata

      public Map getRawMetadata()
      Gets the detailed raw metadata. Each key is an attribute name and each value the corresponding wrapped primitive, primitive array, or string value.

    • getRawMetadata

      public Map<String,Object> getRawMetadata(int index) throws IOException
      Gets the detailed raw metadata for a variable.
      Parameters:
      index - the index of the variable for raw metadata.
      Returns:
      the map of attribute name to attribute value.
      Throws:
      IOException - if the data source had I/O errors.
      Since:
      3.7.1
      See Also:

    • getCoordinateSystems

      public List<ucar.nc2.dataset.CoordinateSystem> getCoordinateSystems()
      Gets the NetCDF CDM style coordinate systems accessed by this reader.
      Returns:
      the list of coordinate systems, possibly empty.

    • getVariablesForSystem

      public List<String> getVariablesForSystem(ucar.nc2.dataset.CoordinateSystem system)
      Gets the variable names for the specified NetCDF CDM style coordinate systems accessed by this reader.
      Returns:
      the list of variable names, possibly empty.

    • findVariable

      public String findVariable(List<String> searchTerms, double minScore) throws IOException
      Searches for a variable in a dataset using a set of search terms.
      Parameters:
      searchTerms - the search terms to use.
      minScore - the minimum acceptable matching score in the range [0..1].
      Returns:
      the variable name with the best match for the search terms, or null if no variables could be found. Match quality is measured based on how similar the variable name or its long name are to one of to search terms.
      Throws:
      IOException
      Since:
      3.8.1