Skip to content

Refactor vector mask external footprint generation

Jump to bottom Edit New page
Daniele Romagnoli edited this page Apr 13, 2016 · 27 revisions

Description

The main goal of this work is to extract support for vector mask external footprint from ImageMosaic plugin so that it can be used by other coverage plugin too, as an instance the GDAL one as per GEOT-5385. Therefore, it is mainly a "move" of several Footprint related helper classes and related logic from ImageMosaic plugin to gt-coverage library, allowing to have footprint management classes available as main dependency for other plugins

It is mainly a package renames work plus a set of refinements to adopt these capabilities in GDAL based readers.

No gt-coverage interfaces have been changed. It shouldn't cause any regression or introduce new API-methods so the risk of integrating it in 15.x should be relative low.

References:

Status

Choose one of:

  • Under Discussion
  • In Progress
  • Completed
  • Rejected
  • Deferred

Voting:

  • Andrea Aime: +1
  • Ben Caradoc-Davies: +1
  • Christian Mueller:
  • Ian Turton: +1
  • Justin Deoliveira: +1
  • Jody Garnett: +1
  • Simone Giannecchini: +1

Tasks

  1. Refactor classes to gt-coverage, and document ✅
  2. Add footprint generation to gdal plugin, and add a code example to the documentation ✅

API Change

The following main interfaces and classes have been moved from gt-imagemosaic to gt-coverage:

Summary of the interfaces moved or extracted from gt-imagemosaic to gt-coverage:

/**
 * A ROI provider that handles multi-scale ROI
 */
public interface MultiLevelROI {
 
    /**
     * Returns a transformed ROI based on the input parameters
     * 
     * @param at AffineTransformation
     * @param imageIndex Overview level used for extracting the correct image overview
     * @param imgBounds ImageBounds to set for Raster ROIs
     * @param readType {@link ReadType} object indicating how the image file must be read. 
     *        This may be useful for raster ROIs
     * @return a {@link ROI} object
     */
    public ROI getTransformedROI(AffineTransform at, int imageIndex, Rectangle imgBounds, 
                                 ImageReadParam params, ReadType readType);

    /**
     * Checks if the provided {@link MultiLevelROI} object is empty or not
     */
    public boolean isEmpty();

    /**
     * This method returns a {@link Geometry} object containing the ROI footprint 
     * or, at least, its bounding box
     */
    public Geometry getFootprint();
}

/**
 * Provider used for generating a {@link MultiLevelROI} object from a granule
 */
public interface MultiLevelROIProvider {

    /**
     * Returns a {@link MultiLevelROI} object from a granule
     * 
     * @param sf {@link SimpleFeature} related to a granule (if several are available). 
     *     Specifying a null feature should return the default provider. 
     * @throws IOException
     */
    public MultiLevelROI getMultiScaleROI(SimpleFeature sf) throws IOException;

    /**
     * Optional method to call for disposing the Provider
     */
    public void dispose();
}

public interface FootprintGeometryProvider {

    /**
     * Retrieves the footprint. If a feature is specified, return the footprint from 
     * the current granule representative feature as it comes from the index.
     * @param feature the granule representative feature (if any). 
     * Specifying a null feature will return a default footprint 
     * (this is used in general for single-granule stores) 
     */
     Geometry getFootprint(SimpleFeature feature) throws IOException;

    /**
     * Close up the provider (in case it holds onto persistent resources such as files or
     * database connections)
     */
    void dispose();
}


/**
 * Helper that loads a sidecar footprint file in a certain format
 */
public interface FootprintLoader {

    /**
     * Tries to load the sidecar geometry given the granule path without extension.
     * 
     * @param pathNoExtension the granule path without extension
     * @return The footprint, or null if the file was not found
     * @throws Exception In case the file was found, but there were issues loading the geometry
     */
    Geometry loadFootprint(String pathNoExtension) throws Exception;
}

/**
 * Constructs a live FootprintLoader
 */
public interface FootprintLoaderSpi {
    FootprintLoader createLoader();
}

Usage Examples

    //sample.ecw is a full world RGB dataset 
    //a sample.wkt sidecar footprint contains a geometry which covers Africa
    final File file = new File("/data/sample.ecw");
    final URL url = file.toURI().toURL();
    final BaseGDALGridCoverage2DReader reader = new ECWReader(url, null);

    // Setting the footprint behavior
    ParameterValue<String> footprint = AbstractGridFormat.FOOTPRINT_BEHAVIOR.createValue();
    footprint.setValue(FootprintBehavior.Transparent.toString());

    // Adding the footprint behavior parameter to apply transparency on footprint
    GridCoverage2D gc = (GridCoverage2D) reader.read(new GeneralParameterValue[] {footprint});

    // Set a coordinate in Greenland
    DirectPosition pointInGreenland = new DirectPosition2D(-43.3, 75.9);
    byte[] pixel = new byte[4];
    
    // Assert point in Greenland is masked out (Transparent)
    gc.evaluate(pointInGreenland, pixel);
    assertTrue((pixel[3] & 0xFF) == 0); // Alpha channel is zero = transparent

    // Set a coordinate in Africa
    DirectPosition pointInAfrica = new DirectPosition2D(20, 0);

    // Assert point in Africa isn't masked out
    gc.evaluate(pointInAfrica, pixel);
    assertTrue((pixel[3] & 0xFF) == 255); // Alpha channel is 255 = fully opaque
Add a custom footer
Add a custom sidebar
Clone this wiki locally