Refactor ImageMosaic Index and Catalog management for improved extensibility

• Contact: Devon Tucker
• Discussion: http://osgeo-org.1560.x6.nabble.com/Proposal-Refactor-ImageMosaic-index-management-td5271633.html
• Tracker: https://osgeo-org.atlassian.net/browse/GEOT-5392
• TLDR: Refactor ImageMosaic catalog management for improved extensibility
• Branch: https://github.com/dvntucker/geotools/tree/granule_acceptors
• See also the original proposal, which had a much larger scope

Description

The proposal expands on gt-mosaic's current abilities for customizing index and catalog management. Some of the use cases for this proposal:

• Allow future implementations to subvert the heterogenous CRS limitations.
• Pre-process coverage footprints before being added to the mosaic index

Status

Choose one of:

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

Voting:

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

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success. Use initials to indicate volunteer, or ⚠️ where volunteer is needed. Proposals that lack resources to be successful are unlikely to be approved.

1. DT: ✅ Removed CatalogManager
2. DT: ✅ Implemented GranuleAcceptInterface and SPI
3. DT: ✅ Implemented GranuleGeometry and SPI
4. DT: ✅ Pull request (waiting on proposal being accepted)
5. SG: ✅ Review
6. MP: ✅ User guide documentation upgrade

Remove CatalogManager

CatalogManager is not a useful class with a singular purpose. Much of its functionality is in static utility methods.

Delegate coverage acceptance to a new GranuleAcceptor API

Currently coverages that don't meet certain requirements aren't added to the ImageMosaic catalog (incompatible band models, incompatible CRS). This proposal moves these checks to a new interface called GranuleAcceptor.

• Before: CatalogManager can reject rasters from the mosaic for a number of reasons (eg. incompatible color model, different CRSs).

    CatalogManager {
      void updateCatalog() {
        ...
        ///just an example of current code
        if (Utils.checkColorModels(colorModel, palette, actualCM)) {
          eventHandler.fireFileEvent(Level.INFO, fileBeingProcessed, false, "Skipping image "
                  + fileBeingProcessed + " because color models do not match.",
                  (((fileIndex + 1) * 99.0) / numFiles));
          return;
        }
      }
    }

• After: Whether a raster should be included or excluded from a mosaic is delegated to a new interface named GranuleAcceptor. ImageMosaicWalker uses this class to determine whether the granule it's handling should be added to the mosaic.

Create a GranuleGeometryHandler interface

Currently the incoming granule geometry is handled one of two ways:

• For most coverage types the coverage's envelope is taken from the coverage reader and used in the index.
• For structured coverages, all the coverage feature attributes are copied directly and used in the image mosaic feature.

This proposal adds a GranuleGeometryHandler for potentially pre-processing this geometry (in case we need to reproject it).

• Before: Granule footprint is added to the index as is:

  CatalogManager {
      updateCatalog(...) {
          ...lots of code elided
          //we set the geom attribute for the incoming granule
          feature.setAttribute(indexSchema.getGeometryDescriptor().getLocalName(), coverageReader.getOriginalEnvelope());
      }
  }

• After: Granule footprint is processed before being added to the index:

  GranuleGeometryHandler geometryHandler = this.getGeometryHandler();
  geometryHandler.handleGeometry(
      inputReader, feature, indexSchema imageMosaicConfiguration);

  /**
   * Handle setting the geometry of the index feature for incoming granules
   */
  public interface GranuleGeometryHandler {
  
      /**
       * Handle the case of a regular grid coverage being added to the mosaic. In the default case
       * this is generally just taking the envelope from the coverage and adding it to the target
       * feature.
       * @param inputReader input reader of the incoming granule
       * @param feature target index feature
       * @param indexSchema schema of the index
       * @param mosaicConfigurationBean the mosaic configuration
       */
      void handleGeometry(GridCoverage2DReader inputReader, SimpleFeature feature,
              SimpleFeatureType indexSchema, MosaicConfigurationBean mosaicConfigurationBean);
  
      /**
       * Handle the case of a structured grid coverage being added to the mosaic. In the default case
       * this is just copying the geometry feature from the incoming granule.
       *
       * @param inputReader input reader of the incoming granule
       * @param targetFeature the target index feature
       * @param targetFeatureType the index schema
       * @param inputFeature the incoming granule feature
       * @param inputFeatureType the incoming coverage schema
       * @param mosaicConfiguration the mosaic configuration
       */
      void handleGeometry(
              StructuredGridCoverage2DReader inputReader,
              SimpleFeature targetFeature,
              SimpleFeatureType targetFeatureType,
              SimpleFeature inputFeature,
              SimpleFeatureType inputFeatureType,
              MosaicConfigurationBean mosaicConfiguration);
  }