sing the ImageMosaic plugin

Introduction
This tutorial describes the process of creating a new coverage using the new ImageMosaic plugin. The ImageMosaic plugin is authored by Simone Giannecchini of GeoSolutions, and allows the creation of a mosaic from a number of georeferenced rasters. The plugin can be used with Geotiffs, as well as rasters accompanied by a world file (.pgw for png files, .jgw for jpg files, etc.). In addition, if imageio-ext GDAL extensions are properly installed we can also serve all the formats supported by it like MrSID, ECW, JPEG2000, etc... See GDAL Image Formats for more information on how to install them. The JAI documentation gives a good description about what a Mosaic does: The Mosaic operation creates a mosaic of two or more source images. This operation could be used for example to assemble a set of overlapping geospatially rectified images into a contiguous image. It could also be used to create a montage of photographs such as a panorama. Briefly the ImageMosaic plugin is responsible for composing together a set of similar raster data, which, from now on I will call granules. The plugin has, of course, some limitations: 1. All the granules must share the same Coordinate Reference System, no reprojection is performed. This will always be a constraint. 2. All the granules must share the same ColorModel and SampleModel. This is a limitation/assumption of the underlying JAI Mosaic operator: it basically means that the granules must share the same pixel layout and photometric interpretation. It would be quite difficult to overcome this limitation, but to some extent it could be done. Notice that, in case of colormapped granules, if the various granules share the same colormap the code will do its best to retain it and try not to expand them in memory. This can also be controlled via a parameter in the configuration file (se next sections) 3. All the granules must share the same spatial resolution and set of overviews. Note About point 3, in the original version of the ImageMosaic plugin this assumption was entirely true since we made an assumption to work with real tiles coming from a set of adjacent images. Lately we have been doing a substantial refactoring, so this condition could be removed, but doing so would take some more work and a few additional options in the configuration file.

To be more specific, if we cant assume that all the granules share the same spatial layout and overviews set we would not be able to asses the raster dimensions (width and height) the spatial dimensions (grid-to-world and envelope) and the overviews set to the final mosaic coverage, unless we specify them somehow or we default to something. As long as we can assume that the various granules share the same spatial elements as well as the same overviews set we can inherit the first definition for the final mosaic. This limitation can be overcome with more work.

Granule Index
In order to configure a new CoverageStore and a new Coverage with this plugin, an index file needs to be generated first in order to associate each granule to its bounding box. Currently we support only a Shapefile as a proper index, although it would be possible to extend this and use other means to persist the index. More specifically, the following files are needed: 1. A shapefile that contains enclosing polygons for each raster file. This shapefile needs to have a field whose values are the paths for the mosaic granules. The path can be either relative to the shapefile itself or absolute, moreover, while the default name for the shapefile attribute that contains the granules paths is location, such a name can be configured to be different (well describe this later on). 2. A projection file (.prj) for the above-mentioned shapefile. 3. A configuration file (.properties). This file contains properties such as cell size in x and y direction, the number of rasters for the ImageMosaic coverage, etc.. We will describe this file in the next section. Later on we will describe the process of creating an index for a set of granules.

Configuration File
The mosaic configuration file is used to store some configuration parameters to control the ImageMosaic plugin. It is created as part of the mosac creation and usually do not require manual editing. The table below describes the various elements in this configuration file. Parameter Mandatory Description Contains the envelope for this mosaic formatted as LLCx,LLXy URCx,URCy (notice the space between the Y coordinates of the Lower Left Corner and the coordinates of the Upper Right Corner). An example is Envelope2D=432500.25,81999.75 439250.25,84999.75 Y Represents the number of reduced resolution layers that we

Envelope2D

LevelsNum

Levels

Name

ExpandToRGB

AbsolutePath

LocationAttribute N

currently have for the granules of this mosaic. Represents the resolutions for the various levels of the granules of this mosaic. Please remember that we are currently assuming that the number of levels and the resolutions for such levels are the same across alll the granules. Represents the name for this mosaic. Applies to colormapped granules. Asks the internal mosaic engine to expand the colormapped granules to RGB prior to mosaicing them. This is needed whenever the the granulesdo not share the same color map hence a straight composition that would retain such a color map cannot be performed. It controls whether or not the path stored inside the location attribute represents an absolute path or a path relative to the location of the shapefile index. Notice that a relative index ensure much more portability of the mosaic itself. Default value for this parameter is False, which means relative paths. The name of the attribute path in the shapefile index. Default value is location.

Creating Granules Index and Configuration File

The refactored version of the ImageMosaic plugin can be used to create the shapefile index as well as the mosaic configuration file on the fly without having to rely on gdal or some other similar utility. If you have a tree of directories containing the granules you want to be able to serve as a mosaic (and providing that you are respecting the conditions written above) all you need to do is to point the GeoServer to such a directory and it will create the proper ancillary files by inspecting all the files present in the the tree of directories starting from the provided input one.

Configuring a Coverage in Geoserver

This is a process very similar to creating a FeatureType. More specifically, one has to perform the steps higlighted in the sections here below.

Create a new CoverageStore:

1. Go to Data Panel | Stores via the web interface and click Add new Store. Finally click ImageMosaic - Image mosaicking plugin from Raster Data Source:

ImageMosaic in the list of raster data stores 2. In order to create a new mosaic is necessary:

To chose the Workspace in the Basic Store Info section. To give a name in the Basic Store Info section. To fill the field URL in the Connection Parameters section. You have three alternatives: o Inserting the absolute path of the shapefile. o Inserting the absolute path of the directory in which the mosaic shapefile index resides, the GeoServer will look for it and make use of it. o Inserting the absolute path of a directory where the files you want to mosaic together reside. In this case GeoServer automatically creates the needed mosaic files (.dbf, .prj, .properties, .shp and .shx) by inspecting the data of present in the given directory (GeoServer will also find the data in the subdirectories).

Finally click the Save button:

Configuring an ImageMosaic data store

Create a new Coverage using the new ImageMosaic CoverageStore:

1. Go to Data Panel | Layers via the web interface and click Add a new resource. Finally choose the name of the Store you just created:

Layer Chooser 2. Click on the layer you wish to configure and you will be presented with the Coverage Editor:

Coverage Editor 3. Make sure there is a value for Native SRS, then click the Submit button. If the Native CRS is UNKNOWN, you must to declare the SRS specifying him in the Declared SRS field. Hopefully there are no errors. 4. Click on the Save button. Once you complete the preceding operations it is possible to access the OpenLayers map preview of the created mosaic. Warning In case the created layer appears to be all black it might be that GeoServer has not found no acceptable granules in the provided ImageMosaic index. It is possible that the shapefile index empty (not granules where found in in the provided directory) or it might be that the granules paths in the shapefile index are not correct as it might happen in case we have moved an existing index using absolute paths to another place. If the shapefile index paths are not correct the dbf file can be opened and fixed with, as an instance OpenOffice. As an alternative on could simple delete the index and let GeoServer recreate it from the root directory.

Tweaking an ImageMosaic CoverageStore:

The Coverage Editor gives users the possibility to set a few control parameters to further tweak and/or control the mosaic creation process. Such parameters are as follows: Parameter Description Set the maximum number of the tiles that can be load simulatenously for a request. In case of a large mosaic this MaxAllowedTiles parameter should be opportunely set to not saturating the server with too many granules loaded at the same time. Set the value of the mosaic background. Depending on the BackgroundValues nature of the mosaic it is wise to set a value for the no data area (usually -9999). This value is repeated on all the mosaic bands. Set the transparent color for the created mosaic. See below for an OutputTransparentColor example:

OutputTransparentColor parameter configured with no color

OutputTransparentColor parameter configured with no data color Set the transparent color for the granules prior to mosaicing them in order to control the superimposition process between them. When GeoServer composes the granules to satisfy the user InputTransparentColor request, some of them can overlap some others, therefore, setting this parameter with the opportune color avoids the overlap of no data areas between granules. See below for an example:

10

InputTransparentColor parameter not configured

InputTransparentColor parameter configured If true enable tiles multithreading loading. This allows to perform parallelized loading of the granules that compose the mosaic. Controls the low level mechanism to read the granules. If true GeoServer will make use of JAI ImageRead operation USE_JAI_IMAGEREAD and its deferred loading mechanism, if false GeoServer will perform direct ImageIO read calls which will result in immediate loading. Controls the tile size of the input granules as well as the tile SUGGESTED_TILE_SIZE: size of the output mosaic. It consists of two positive integersseparated by a comma,like 512,512. AllowMultithreading 11

Note Deferred loading consumes less memory since it uses a streaming approach to load in memory only the data that is needed for the processing at each time, but, on the other side, may cause problems under heavy load since it keeps granules files open for a long time to support deferred loading. Note Immediate loading consumes more memory since it loads in memory the whole requested mosaic at once, but, on the other side, it usually performs faster and does not leave room for too many files open error conditions as it happens for deferred loading.

Configuration examples
Now we are going to provide a few examples of mosaic configurations to demonstrate how we can make use of the ImageMosaic parameters.

DEM/Bathymetric mosaic configuration (raw data)

Such a mosaic can be use to serve large amount of data which represents altitude or depth and therefore does not specify colors directly while it reather needs an SLD to generate pictures. In our case we have a DEM dataset which consists of a set of raw geotiff files. The first operation is to create the CoverageStore following the three steps showed in Create a new CoverageStore specifying, for example, the path of the shapefile in the URL field. Inside the Coverage Editor, Publishing tab - Default Title section, you can specify the dem default style (Default Style combo box) in order to represent the visualization style of the mosaic. The following is an example style:
<?xml version="1.0" encoding="ISO-8859-1"?> <StyledLayerDescriptor version="1.0.0" xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/sld http://schemas.opengis.net/sld/1.0.0/StyledLayerDescriptor.xsd"> <NamedLayer> <Name>gtopo</Name> <UserStyle> <Name>dem</Name> <Title>Simple DEM style</Title> <Abstract>Classic elevation color progression</Abstract> <FeatureTypeStyle> <Rule> <RasterSymbolizer> <Opacity>1.0</Opacity> <ColorMap>

12

<ColorMapEntry color="#000000" label="nodata" opacity="1.0" /> <ColorMapEntry color="#AAFFAA" /> <ColorMapEntry color="#00FF00" label="values" /> <ColorMapEntry color="#FFFF00" label="values" /> <ColorMapEntry color="#FF7F00" label="values" /> <ColorMapEntry color="#BF7F3F" label="values" /> <ColorMapEntry color="#000000" label="values" /> </ColorMap> </RasterSymbolizer> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

quantity="-9999" quantity="0" label="values" quantity="1000" quantity="1200" quantity="1400" quantity="1600" quantity="2000"

In this way you have a clear distinction between the different intervals of the dataset that compose the mosaic, like the background and the no data area.

13

14

Note The no data on the sample mosaic is -9999, on the other side the default background value is for mosaics is 0.0. The result is the following.

Basic configuration By setting in opportune ways the other configuration parameters, it is possible to improve at the same time both the appearance of the mosaic as well as the its performances. As an instance we could: 1. Make the no data areas transparent and coherent with the real data. To achieve this we need to change the opacity of the no data ColorMapEntry in the dem

15

style to 0.0 and set BackgroundValues parameter at -9999 so that empty areas will be filled with this value. The result is as follows:

Advanced configuration 2. Allow multithreaded granules loading. By setting the AllowMultiThreading parameter to tru GeoServer will load the granules in parallell sing multiple threads with a consequent increase of the performances on some architectures.. The configuration parameters are the followings: 1. 2. 3. 4. 5. 6. 7. 8. MaxAllowedTiles: 2147483647 BackgroundValues: -9999. OutputTransparentColor: no color. InputImageThresholdValue: NaN. InputTransparentColor: no color. AllowMultiThreading: true. USE_JAI_IMAGEREAD: true. SUGGESTED_TILE_SIZE: 512,512.

Aerial Imagery mosaic configuration

In this example we are going to create a mosaic that will serve aerial imagery, RGB geotiffs in this case. Noticed that since we are talking about visual data, in the Coverage Editor you can use the basic raster style, as reported here below, which is just a stub 16

SLD to instruct the GeoServer raster renderer to not do anything particular in terms of color management:
<?xml version="1.0" encoding="ISO-8859-1"?> <StyledLayerDescriptor version="1.0.0" xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/sld http://schemas.opengis.net/sld/1.0.0/StyledLayerDescriptor.xsd"> <NamedLayer> <Name>raster</Name> <UserStyle> <Name>raster</Name> <Title>Raster</Title> <Abstract>A sample style for rasters, good for displaying imagery </Abstract> <FeatureTypeStyle> <FeatureTypeName>Feature</FeatureTypeName> <Rule> <RasterSymbolizer> <Opacity>1.0</Opacity> </RasterSymbolizer> </Rule> </FeatureTypeStyle> </UserStyle> </NamedLayer> </StyledLayerDescriptor>

The result is the following.

17

Basic configuration Note Those ugly black areas, are the resulting of applying the eafalt mosaic parameters to a mosaic that does not entirey cover its bounding box. The areas within the BBOX that are not covered with data will default to a value of 0 on each band. Since this mosaic is RGB wecan simply set the OutputTransparentCOlor to 0,0,0 in order to get back transparent fills for the BBOX. The various parameters can be set as follows: 1. 2. 3. 4. 5. 6. MaxAllowedTiles: 2147483647 BackgroundValues: default value. OutputTransparentColor: #000000 (to make transparent the background). InputImageThresholdValue: NaN. InputTransparentColor: no color. AllowMultiThreading: true (in this way GeoServer manages the loading of the tiles in parallel mode with a consequent increase of the performances). 7. USE_JAI_IMAGEREAD: true. 8. SUGGESTED_TILE_SIZE: 512,512. The results is the following:

18

Advanced configuration

Scanned Maps mosaic configuration

In this case we want to show how to serve scanned maps (mostly B&W images) via a GeoServer mosaic. In the Coverage Editor you can use the basic raster style as shown above since there is not need to use any of the advanced RasterSymbolizer capabilities. The result is the following.

19

Basic configuration This mosaic, formed by two single granules, shows a typical case where the no data collar areas of the granules overlap, as it is shown in the picture above. In this case we can use the InputTrasparentColor parameter at to make the collar areas disappear during the superimposition process, as instance, in this case, by using the #FFFFFF InputTrasparentColor. This is the result:

Advanced configuration The final configuration parameters are the followings: 1. MaxAllowedTiles: 2147483647 2. BackgroundValues: default value. 3. OutputTransparentColor: no color.

20

4. InputImageThresholdValue: NaN. 5. InputTransparentColor: #FFFFFF. 6. AllowMultiThreading: true (in this way GeoServer manages the loading of the tiles in parallel mode with a consequent increase of the performances). 7. USE_JAI_IMAGEREAD: true. 8. SUGGESTED_TILE_SIZE: 512,512. Previous: CQL and ECQL Next: Building and using an image pyramid

Table Of Contents

Using the ImageMosaic plugin o Introduction o Granule Index o Configuration File o Creating Granules Index and Configuration File o Configuring a Coverage in Geoserver Create a new CoverageStore: Create a new Coverage using the new ImageMosaic CoverageStore: Tweaking an ImageMosaic CoverageStore: o Configuration examples DEM/Bathymetric mosaic configuration (raw data) Aerial Imagery mosaic configuration Scanned Maps mosaic configuration

Continue Reading

Previous: CQL and ECQL Next: Building and using an image pyramid

This Page

Show Source

21