Mosaic Plugin

This format make use of a shapefile to act as a kind of index, the features in this shapefile list the filename of the “images” to display and the location in which they should be displayed.

Maven:

<dependency>
  <groupId>org.geotools</groupId>
  <artifactId>gt-imagemosaic</artifactId>
  <version>${geotools.version}</version>
</dependency>

To create the shapefile you simply provide the location of a folder with “images” to the constructor of ImageMosaicReader. Those image files must conatin it’s own world-file to be a part of the image mosaic.

To display the mosaic within a map, you will use a GridReaderLayer.

            ImageMosaicReader reader = new ImageMosaicReader(new File(pathMosaic));
            layer = new GridReaderLayer(reader, style);

The simplest style to provide would be like this:

        Style style = styleFactory.createStyle();

        FeatureTypeStyle type = styleFactory.createFeatureTypeStyle();
        style.featureTypeStyles().add(type);

        Rule rule = styleFactory.createRule();
        rule.symbolizers().add(styleFactory.createRasterSymbolizer());

        type.rules().add(rule);

To use mulitthreading you must provide a threading pool to the mosaic reader, and also tell the grid reader layer to allow multithreading.

            ExecutorService executor = Executors.newFixedThreadPool(numThreads);

            ImageMosaicReader reader =
                    new ImageMosaicReader(new File(pathMosaic), new Hints(Hints.EXECUTOR_SERVICE, executor));

            ParameterValue<Boolean> multithreadParam = ImageMosaicFormat.ALLOW_MULTITHREADING.createValue();
            multithreadParam.setValue(true);

            layer = new GridReaderLayer(reader, style, new GeneralParameterValue[] {multithreadParam});

Example Image Mosaic files

An example data set looks something like:

bluemarble.shp
bluemarble.prj
bluemarble.properties
sample_image.dat
... a bunch of raster files ...

  • Shapefile file

    The schema of your shapefile is important:

    You MUST have a attribute called “location”, this will be used to look up the raster files

  • PRJ file

    The usual projection file associated with a shapefile, using the WKT format for a CoordinateReferenceSystem.

  • Sample image file

    The sample_image.dat (legacy sample_image) is a sample image used to determine color model upfront without requiring a full scan.

    By default the sample image file is limited to built-in image formats and color models. The old sample image file format that used the javax.media.jai.remote.SerializableRenderedImage class is also blocked by default. This restriction may be relaxed using the system property org.geotools.gce.imagemosaic.sampleimage.allowlist:

    org.geotools.gce.imagemosaic.sampleimage.allowlist=^java\\.(net\\.InetAddress|util\\.Hashtable)$

  • Properties File

    The property file is REQUIRED and use to provide a bunch of settings:

    Example bluemarble.properties:

    #
#Thu Jan 11 14:53:30 CET 2007
Name=modis
ExpandToRGB=true
Levels=10000.0,10000.0
LevelsNum=1
GeneralBounds=-3637013.0,-1158091.0 1019969.0,4092819.0
NumFiles=3

    Where the following are required:

    • Name

    • ExpandToRGB: true if we need to expand the color model from indexed to rgba

      • If all your images use the same indexed palette you can set this to false and get a large performance gain

    • Levels: list of resolutions

      • Format: level_0_x_resolution, level_0_y_resolution, level_1_x_resolution, level_1_y_resolution

      • This measure of resolution describes how big each pixel is in real world units

      • Sample calculation: envelope.getLength(0) / image.getWidth()

      • You can define several levels in order to capture overview files if you have them

    • LevelsNum: the number of levels mentioned above

    • GeneralBounds: bounds in the CRS specified in the .prj file

    • Format: minX,minY maxX,maxY

    • NumFiles: should be the same as the number of features in your shapefile

Granule image cache

Mosaics made of many small granules (small tiles, or zoomed-out views that compose thousands of tiny overviews when no pyramid was built) re-read and re-decode the same granules from disk on every request. An optional cache can keep the decoded granule images in memory and serve later reads of the same granule from there, skipping the disk I/O and decode. All later processing (band select, rescale, affine, ROI) still runs after the cache, so the output is identical to an uncached read.

The cache is a shared pool that is created and owned outside the reader and injected through the Hints.GRANULE_IMAGE_CACHE hint (an org.geotools.gce.imagemosaic.GranuleImageCache instance), much like the multithreaded-read ExecutorService is injected through Hints.EXECUTOR_SERVICE. The pool is bounded by total decoded bytes and evicts least-recently-used entries; a single pool can be shared by many readers. Entries are keyed by owning mosaic plus granule URL, image index and bands, so disposing a reader drops all of that mosaic’s entries at once (via invalidateMosaic). A single stale granule (an in-place overwrite, a re-harvest, a delete) is dropped with GranuleImageCache.invalidateGranule, while invalidateAll clears the whole pool.

Caching is off unless enabled per read, through two read parameters:

  • CacheGranules (Boolean, default false): enables reuse and population of the injected cache.

  • CacheGranulesThresholdKB (Integer, default -1): overrides the pool’s default per-granule eligibility threshold for this read; a granule whose full decoded raster is larger than the threshold is read normally and not cached. -1 keeps the pool default.

Reference