org.geotools.image.io.mosaic
Class MosaicBuilder

java.lang.Object
  extended by org.geotools.image.io.mosaic.MosaicBuilder

public class MosaicBuilder
extends java.lang.Object

A convenience class for building tiles using the same image reader and organized according some common tile layout. Optionally, this builder can also write the tiles to disk from an initially untiled image.

Since:
2.5
Version:
$Id: MosaicBuilder.java 33009 2009-05-14 19:40:06Z simonegiannecchini $
Author:
Cédric Briançon, Martin Desruisseaux

Field Summary
protected  TileManagerFactory factory
          The factory to use for creating TileManager instances.
 
Constructor Summary
MosaicBuilder()
          Generates tiles using the default factory.
MosaicBuilder(TileManagerFactory factory)
          Generates tiles using the specified factory.
 
Method Summary
protected  GridToEnvelopeMapper createGridToEnvelopeMapper(TileManager tiles)
          Invoked automatically when a "grid to CRS" transform needs to be computed.
 TileManager createTileManager()
          Creates a tile manager from the informations supplied in above setters.
 TileManager createTileManager(java.lang.Object input)
          Creates a tile manager from an untiled image.
 TileManager createTileManager(java.lang.Object input, int inputIndex, TileWritingPolicy policy)
          Creates a tile manager from an untiled image.
protected  java.lang.String generateFilename(int level, int column, int row)
          Generates a filename for the current tile based on the position of this tile in the raster.
 java.util.logging.Level getLogLevel()
          Returns the logging level for tile information during read and write operations.
 org.opengis.geometry.Envelope getMosaicEnvelope()
          Returns the envelope for the mosaic as a whole, or null if none.
 java.awt.Dimension[] getSubsamplings()
          Returns the subsampling for overview computations.
 java.io.File getTileDirectory()
          Returns the tile directory, or null for current directory.
 TileLayout getTileLayout()
          Returns the tile layout.
 javax.imageio.spi.ImageReaderSpi getTileReaderSpi()
          Returns the image reader provider to use for reading tiles.
 java.awt.Dimension getTileSize()
          Returns the tile size.
 java.awt.Rectangle getUntiledImageBounds()
          Returns the bounds of the untiled image, or null if not set.
protected  void onTileWrite(Tile tile, javax.imageio.ImageWriteParam parameters)
          Invoked automatically when a tile is about to be written.
 void setLogLevel(java.util.logging.Level level)
          Sets the logging level for tile information during read and write operations.
 void setMosaicEnvelope(org.opengis.geometry.Envelope envelope)
          Sets the envelope for the mosaic as a whole, or null if none.
 void setSubsamplings(java.awt.Dimension[] subsamplings)
          Sets the subsamplings for overview computations.
 void setSubsamplings(int[] subsamplings)
          Sets uniform subsamplings for overview computations.
 void setTileDirectory(java.io.File directory)
          Sets the directory where tiles will be read or written.
 void setTileLayout(TileLayout layout)
          Sets the tile layout to the specified value.
 void setTileReaderSpi(javax.imageio.spi.ImageReaderSpi provider)
          Sets the image reader provider for each tiles to be read.
 void setTileReaderSpi(java.lang.String format)
          Sets the image reader provider by name.
 void setTileSize(java.awt.Dimension size)
          Sets the tile size.
 void setUntiledImageBounds(java.awt.Rectangle bounds)
          Sets the bounds of the untiled image to the specified value.
static int[][] suggestedNumTiles(java.awt.Rectangle imageBounds, java.awt.Dimension tileSize, int preferredCount, boolean multiples)
          Returns a suggested set of divisors of the number of tiles that can fit in an image.
static int suggestedTileSize(int imageSize, int tileSize, int minSize, int maxSize)
          Returns a suggested tile size (width or height) for the given image size.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

factory

protected final TileManagerFactory factory
The factory to use for creating TileManager instances.

Constructor Detail

MosaicBuilder

public MosaicBuilder()
Generates tiles using the default factory.


MosaicBuilder

public MosaicBuilder(TileManagerFactory factory)
Generates tiles using the specified factory.

Parameters:
factory - The factory to use, or null for the default one.
Method Detail

getLogLevel

public java.util.logging.Level getLogLevel()
Returns the logging level for tile information during read and write operations.

Returns:
The current logging level.

setLogLevel

public void setLogLevel(java.util.logging.Level level)
Sets the logging level for tile information during read and write operations. The default value is Level.FINE. A null value restore the default.

Parameters:
level - The new logging level.

getTileLayout

public TileLayout getTileLayout()
Returns the tile layout. The default value is CONSTANT_TILE_SIZE, which is the most efficient layout available in org.geotools.image.io.mosaic implementation.

Returns:
An identification of current tile layout.

setTileLayout

public void setTileLayout(TileLayout layout)
Sets the tile layout to the specified value. Valid values are CONSTANT_TILE_SIZE and CONSTANT_GEOGRAPHIC_AREA.

Parameters:
layout - An identification of new tile layout.

getTileDirectory

public java.io.File getTileDirectory()
Returns the tile directory, or null for current directory. The directory may be either relative or absolute. The default value is null.

Returns:
The current tiles directory.

setTileDirectory

public void setTileDirectory(java.io.File directory)
Sets the directory where tiles will be read or written. May be a relative or absolute path, or null (the default) for current directory.

Parameters:
directory - The new tiles directory.

getTileReaderSpi

public javax.imageio.spi.ImageReaderSpi getTileReaderSpi()
Returns the image reader provider to use for reading tiles. The initial value is null, which means that the provider should be the same than the one detected by writeFromUntiledImage.

Returns:
The current image reader provider for tiles.

setTileReaderSpi

public void setTileReaderSpi(javax.imageio.spi.ImageReaderSpi provider)
Sets the image reader provider for each tiles to be read. A null value means that the provider should be automatically detected by writeFromUntiledImage.

Parameters:
provider - The new image reader provider for tiles.

setTileReaderSpi

public void setTileReaderSpi(java.lang.String format)
                      throws java.lang.IllegalArgumentException
Sets the image reader provider by name. This convenience method searchs a provider for the given name in the default IIORegistry and delegates to setTileReaderSpi(ImageReaderSpi).

Parameters:
format - The image format name for tiles.
Throws:
java.lang.IllegalArgumentException - if no provider was found for the given name.

getMosaicEnvelope

public org.opengis.geometry.Envelope getMosaicEnvelope()
Returns the envelope for the mosaic as a whole, or null if none. This is optional, but if specified this builder uses it for assigning values to Tile.getGridToCRS().

Returns:
The current envelope, or null if none.

setMosaicEnvelope

public void setMosaicEnvelope(org.opengis.geometry.Envelope envelope)
Sets the envelope for the mosaic as a whole, or null if none. This is optional, but if specified this builder uses it for assigning values to Tile.getGridToCRS().

This is merely a convenient way to invoke TileManager.setGridToCRS(java.awt.geom.AffineTransform) with a transform computed from the envelope and the untiled image bounds, where the later may be known only at reading time. As always, creating "grid to CRS" from an envelope is ambiguous, since we don't know if axis need to be interchanged, y axis flipped, etc. Subclasses can gain more control by overriding the createGridToEnvelopeMapper method. The default behavior fits most typical cases however.

Parameters:
envelope - The new envelope, or null if none.
See Also:
createGridToEnvelopeMapper(org.geotools.image.io.mosaic.TileManager)

getUntiledImageBounds

public java.awt.Rectangle getUntiledImageBounds()
Returns the bounds of the untiled image, or null if not set. In the later case, the bounds will be inferred from the input image when #writeFromUntiledImage is invoked.

Returns:
The current untiled image bounds.

setUntiledImageBounds

public void setUntiledImageBounds(java.awt.Rectangle bounds)
Sets the bounds of the untiled image to the specified value. A null value discarts any value previously set.

Parameters:
bounds - The new untiled image bounds.

getTileSize

public java.awt.Dimension getTileSize()
Returns the tile size. If no tile size has been explicitly set, then a default tile size will be computed from the untiled image bounds. If no size can be computed, then this method returns null.

Returns:
The current tile size.
See Also:
suggestedTileSize(int)

setTileSize

public void setTileSize(java.awt.Dimension size)
Sets the tile size. A null value discarts any value previously set.

Parameters:
size - The new tile size.

suggestedTileSize

public static int suggestedTileSize(int imageSize,
                                    int tileSize,
                                    int minSize,
                                    int maxSize)
                             throws java.lang.IllegalArgumentException
Returns a suggested tile size (width or height) for the given image size. This method searchs for a value x inside the [minSize...maxSize] range where imageSize/x has the largest amount of divisors. If more than one value have the same amount of divisors, then the one which is the closest to tileSize is returned.

Parameters:
imageSize - The image size.
tileSize - The preferred tile size. Must be inside the [minSize...maxSize] range.
minSize - The minimum size, inclusive. Must be greater than 0.
maxSize - The maximum size, inclusive. Must be equals or greater that minSize.
Returns:
The suggested tile size. Inside the [minSize...maxSize] range except if imageSize was smaller than minSize.
Throws:
java.lang.IllegalArgumentException - if any argument doesn't meet the above-cited conditions.

suggestedNumTiles

public static int[][] suggestedNumTiles(java.awt.Rectangle imageBounds,
                                        java.awt.Dimension tileSize,
                                        int preferredCount,
                                        boolean multiples)
Returns a suggested set of divisors of the number of tiles that can fit in an image. More specifically, this method executes the following pseudo code twice, once for width and once for height, resulting in two arrays of type int[]:
divisors(round(imageBounds / tileSize))
The two arrays are then decimated using the following procedures:


getSubsamplings

public java.awt.Dimension[] getSubsamplings()
Returns the subsampling for overview computations. If no subsamplings were explicitly set, then this method computes automatically some subsamplings from the untiled image bounds and tile size, with the following properties (note that those properties are not garanteed if the subsampling was explicitly specified rather than computed):

If no subsampling can be computed, then this method returns null.

Returns:
The current subsamplings for each overview levels.

setSubsamplings

public void setSubsamplings(java.awt.Dimension[] subsamplings)
Sets the subsamplings for overview computations. The number of overview levels created by this MosaicBuilder will be equals to the subsamplings array length.

Subsamplings most be explicitly provided for TileLayout.CONSTANT_GEOGRAPHIC_AREA, but is optional for TileLayout.CONSTANT_TILE_SIZE. In the later case subsamplings may be null (the default), in which case they will be automatically computed from the untiled image bounds and tile size in order to have only entire tiles (i.e. tiles in last columns and last rows don't need to be cropped).

Parameters:
subsamplings - The new subsamplings for each overview levels.

setSubsamplings

public void setSubsamplings(int[] subsamplings)
Sets uniform subsamplings for overview computations. This convenience method delegates to setSubsamplings(Dimension[]) with the same value affected to both width and height.

Parameters:
subsamplings - The new subsamplings for each overview levels.

createTileManager

public TileManager createTileManager()
                              throws java.io.IOException
Creates a tile manager from the informations supplied in above setters. The following methods must be invoked prior this one:

The other setter methods are optional.

Returns:
The tile manager created from the information returned by getter methods.
Throws:
java.io.IOException - if an I/O operation was required and failed. The default implementation does not perform any I/O, but subclasses are allowed to do so.

createTileManager

public TileManager createTileManager(java.lang.Object input)
                              throws java.io.IOException
Creates a tile manager from an untiled image. The untiled image bounds and tile reader SPI are inferred from the input, unless they were explicitly specified.

This method does not write any tile to disk.

Parameters:
input - The image input, typically as a File or an other TileManager.
Returns:
The tiles, or null if the process has been aborted.
Throws:
java.io.IOException - if an error occured while reading the untiled image.

createTileManager

public TileManager createTileManager(java.lang.Object input,
                                     int inputIndex,
                                     TileWritingPolicy policy)
                              throws java.io.IOException
Creates a tile manager from an untiled image. The untiled image bounds and tile reader SPI are inferred from the input, unless they were explicitly specified.

Optionnaly if the tile writing policy is anything else than NO_WRITE, then pixel values are read from the untiled images, organized in tiles as specified by the TileManager to be returned and saved to disk. This work is done using a default MosaicImageWriter.

Parameters:
input - The image input, typically as a File or an other TileManager.
inputIndex - Index of image to read, typically 0.
policy - Sets whatever tiles are created and saved to disk.
Returns:
The tiles, or null if the process has been aborted while writing tiles.
Throws:
java.io.IOException - if an error occured while reading the untiled image or (only if writeTiles is true) while writting the tiles to disk.

generateFilename

protected java.lang.String generateFilename(int level,
                                            int column,
                                            int row)
Generates a filename for the current tile based on the position of this tile in the raster. For example, a tile in the first overview level, which is localized on the 5th column and 2nd row may have a name like "L1_E2.png".

Subclasses may override this method if they want more control on generated tile filenames.

Parameters:
level - The level of overview. First level is 0.
column - The index of columns. First column is 0.
row - The index of rows. First row is 0.
Returns:
A filename based on the position of the tile in the whole raster.

createGridToEnvelopeMapper

protected GridToEnvelopeMapper createGridToEnvelopeMapper(TileManager tiles)
Invoked automatically when a "grid to CRS" transform needs to be computed. The default implementation returns a new GridToEnvelopeMapper instance in its default configuration, except for the pixel anchor which is set to CELL_CORNER (OGC specification maps pixel center, while Java I/O maps pixel upper-left corner).

Subclasses may override this method in order to configure the mapper in an other way.

Parameters:
tiles - The tiles for which a "grid to CRS" transform needs to be computed.
Returns:
An "grid to envelope" mapper having the desired configuration.
See Also:
setMosaicEnvelope(org.opengis.geometry.Envelope)

onTileWrite

protected void onTileWrite(Tile tile,
                           javax.imageio.ImageWriteParam parameters)
                    throws java.io.IOException
Invoked automatically when a tile is about to be written. The default implementation does nothing. Subclasses can override this method in order to set custom write parameters. The source region and source subsampling should not be set since they will be inconditionnaly overwritten by the caller.

Parameters:
tile - The tile to be written.
parameters - The parameters to be given to the image writer.
Throws:
java.io.IOException - if an I/O operation was required and failed.


Copyright © 1996-2010 Geotools. All Rights Reserved.