Package com.luciad.formats.gdal

Class GdalModelDecoder

java.lang.Object
com.luciad.formats.gdal.GdalModelDecoder
public final class GdalModelDecoder extends Object
This class is a factory that provides new instances of a Model that are decoded using the GDAL library.

The created model is either an IRasterModel or an IFeatureModel giving the ability to access the data within files of the following supported formats:

  • GeoTIFF (*.tif, *.tiff)
  • Esri Shapefile (*.shp)

  • Method Details

    • decode

      @NotNull public static Model decode(@NotNull String source) throws IOException
      Creates a model for a raster or vector file supported by the GDAL library.

      See class documentation for more information on the supported file formats.

      Raster data

      Raster limitations
      Currently, the following features are supported:
      • the raster can be positioned on the world using
        • a translation and a (positive, non-mirror) scaling
        • a translation, scaling, and rotation
        • tie points, i.e., a mapping between raster pixel locations and a location in a coordinate reference system
          • the number of tie points must be at least 3
          • 3 tie points: an affine transformation is derived
          • 4 or more tie points: an affine transformation is derived using a least-squares approach
        • Rational Polynomial Coefficients (RPC)
      • supported data formats
        • RGB(A) data, 8-bit per band
        • Indexed color data, 8-bit index band data (256 colors)
        • Single band data, 32-bit float or 16-bit integer

      This model decoder considers single band data, using either 32-bit float or 16-bit signed integer, as raster elevation data.

      Raster elevation data using single unsigned 16-bit integers are supported under the following conditions:

      • The dataset contains information about the raster unit type to indicate that raster data should be interpreted as elevation data.
      • The raster unit type is either "m" for an elevation model in meters, "ft" for feet or "us-ft" for US survey feet.

      For more information, please read the related article: Elevation support.

      Example usage:
          try {
      Model model = GdalModelDecoder.decode(source);
      if (model instanceof IRasterModel) {
        IRasterModel rasterModel = (IRasterModel) model;
        // ...
      }
    } catch (IOException exception) {
      Log.w("", "Failed to open file '" + source + "': " + exception.getMessage());
    }

      Note
      External overviews in GeoTIFF format:
      This model decoder supports external overviews created in GeoTIFF format, i.e. overviews generated in an external .ovr file. Please note that the external overview file must have the same name as the GeoTIFF file, but the extension .ovr appended and it must be in the same folder. For more information on GeoTIFF overviews, please read the gdal documentation.

      Feature data

      Supported geometries
      Geometry Type Description for geometry in model
      Point Point
      Polyline Polyline
      Polygon Polygon
      MultiPoint MultiGeometry with Point sub-geometries
      MultiPolyline MultiGeometry with Polyline sub-geometries
      MultiPolygon MultiGeometry with Polygon sub-geometries
      Point Z Point
      Polyline Z Polyline
      Polygon Z Polygon
      MultiPoint Z MultiGeometry with Point sub-geometries
      MultiPolyline Z MultiGeometry with Polyline sub-geometries
      MultiPolygon Z MultiGeometry with Polygon sub-geometries

      SHP geometry types having measurement values are not supported!

      Coordinate reference for SHP files
      The ESRI SHP file must have a corresponding .prj file containing the WKT representation of the Coordinate Reference System. If it does not exist this decoder attempts to read the Coordinate Reference System from a .epsg file containing an EPSG code, e.g. EPSG:4326.

      Query filtering support
      FeatureQuery expression filter can be used to filter the features that have to be loaded in memory. It supports filtering by ID, using a bounding box, and using a condition.

      Note that when the condition contains expressions using a spatial bbox operator the filtering cannot be propagated efficiently to GDAL. In this case a best effort is done to translate the condition towards GDAL and a post filtering step in memory is performed.

      Use of index files for SHP files
      When available the decoder uses the ESRI spatial index files (.sbn / .sbx) or spatial index files (in .qix format). When no spatial index files are available the decoder creates a spatial index file using the .qix format.

      When the index file (*.shx) or one of the spatial index files (*.sbx,*.sbn or *.qix) is missing, the decoder creates them at runtime. The index files are stored next to the source data. If the record index file *.shx cannot be written next to the source data (e.g. no write permission) the decoding fails. If the spatial index file *.qix cannot be written next to the source data (e.g. no write permission) the decoding continues but spatial filtering will be slower.

      Example usage:
          try {
      Model model = GdalModelDecoder.decode(source);
      if (model instanceof IFeatureModel) {
        IFeatureModel featureModel = (IFeatureModel) model;
        // ...
      }
    } catch (IOException exception) {
      Log.w("", "Failed to open file '" + source + "': " + exception.getMessage());
    }
      Parameters:
      source - The absolute path to the file.
      Returns:
      the decoded model for the source.
      Throws:
      IOException - when decoding the source file fails.