org.geotools.image.io.mosaic
Class Tile

java.lang.Object
  extended by org.geotools.image.io.mosaic.Tile
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Tile>
Direct Known Subclasses:
LargeTile

public class Tile
extends java.lang.Object
implements java.lang.Comparable<Tile>, java.io.Serializable

A tile to be read by MosaicImageReader. Each tile must contains the following:

The tiles are not required to be arranged on a regular grid, but performances may be better if they are. TileManagerFactory is responsible for analysing the layout of a collection of tiles and instantiate TileManager subclasses optimized for the layout geometry.

Tiles can be considered as immutable after construction. However some properties may be available only after this tile has been given to a TileManagerFactory.

Tiles are serializable if their input given at construction time are serializable too. The ImageReaderSpi doesn't need to be serializable, but its class must be known to IIORegistry at deserialization time.

Since:
2.5
Version:
$Id: Tile.java 32440 2009-02-09 11:14:54Z acuster $
Author:
Martin Desruisseaux
See Also:
Serialized Form

Constructor Summary
Tile(javax.imageio.spi.ImageReaderSpi provider, java.lang.Object input, int imageIndex, java.awt.Point location, java.awt.Dimension subsampling)
          Creates a tile for the given provider, input and location.
Tile(javax.imageio.spi.ImageReaderSpi provider, java.lang.Object input, int imageIndex, java.awt.Rectangle region)
          Creates a tile for the given region with default subsampling.
Tile(javax.imageio.spi.ImageReaderSpi provider, java.lang.Object input, int imageIndex, java.awt.Rectangle region, java.awt.geom.AffineTransform gridToCRS)
          Creates a tile for the given provider, input and "grid to real world" transform.
Tile(javax.imageio.spi.ImageReaderSpi provider, java.lang.Object input, int imageIndex, java.awt.Rectangle region, java.awt.Dimension subsampling)
          Creates a tile for the given provider, input and region.
 
Method Summary
 int compareTo(Tile other)
          Compares two tiles for optimal order in sequential reads.
 boolean equals(java.lang.Object object)
          Compares this tile with the specified one for equality.
 java.lang.String getFormatName()
          Returns a format name inferred from the provider.
 java.awt.geom.AffineTransform getGridToCRS()
          Returns the "grid to real world" transform, or null if unknown.
 int getImageIndex()
          Returns the image index to be given to the image reader for reading this tile.
 javax.imageio.ImageReader getImageReader()
          Returns a new reader created by the provider and setup for reading the image from the input.
protected  javax.imageio.ImageReader getImageReader(MosaicImageReader mosaic, boolean seekForwardOnly, boolean ignoreMetadata)
          Returns a reader created by the provider and setup for reading the image from the input.
 javax.imageio.spi.ImageReaderSpi getImageReaderSpi()
          Returns the image reader provider (never null).
 java.lang.Object getInput()
          Returns the input to be given to the image reader for reading this tile.
 java.lang.String getInputName()
          Returns a short string representation of the input.
 java.awt.Point getLocation()
          Returns the upper-left corner in the destination image.
 java.awt.Rectangle getRegion()
          Returns the upper-left corner in the destination image, with the image size.
 java.awt.Dimension getSubsampling()
          Returns the subsampling relative to the tile having the finest resolution.
 java.awt.Dimension getSubsamplingFloor(java.awt.Dimension subsampling)
          Returns the highest subsampling that this tile can handle, not greater than the given subsampling.
 int hashCode()
          Returns a hash code value for this tile.
 java.lang.String toString()
          Returns a string representation of this tile.
static void writeTable(java.util.Collection<Tile> tiles, java.io.Writer out, int maximum)
          Formats a collection of tiles in a table.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Tile

public Tile(javax.imageio.spi.ImageReaderSpi provider,
            java.lang.Object input,
            int imageIndex,
            java.awt.Point location,
            java.awt.Dimension subsampling)
     throws java.lang.IllegalArgumentException
Creates a tile for the given provider, input and location. This constructor can be used when the size of the image to be read by the supplied reader is unknown. This size will be fetched automatically the first time getRegion() is invoked.

Parameters:
provider - The image reader provider to use. The same provider is typically given to every Tile objects to be given to the same TileManager instance, but this is not mandatory. If null, the provider will be inferred from the input. If it can't be inferred, then an exception is thrown.
input - The input to be given to the image reader.
imageIndex - The image index to be given to the image reader for reading this tile.
location - The upper-left corner in the destination image.
subsampling - The subsampling relative to the tile having the finest resolution, or null if none. If non-null, width and height should be strictly positive. This argument if of dimension kind because it can also be understood as relative "pixel size".
Throws:
java.lang.IllegalArgumentException - If a required argument is null or some argument has an invalid value.

Tile

public Tile(javax.imageio.spi.ImageReaderSpi provider,
            java.lang.Object input,
            int imageIndex,
            java.awt.Rectangle region,
            java.awt.Dimension subsampling)
     throws java.lang.IllegalArgumentException
Creates a tile for the given provider, input and region. This constructor can be used when the size of the image to be read by the supplied reader is known. It avoid the cost of fetching the size from the reader when getRegion() will be invoked.

Parameters:
provider - The image reader provider to use. The same provider is typically given to every Tile objects to be given to the same TileManager instance, but this is not mandatory. If null, the provider will be inferred from the input. If it can't be inferred, then an exception is thrown.
input - The input to be given to the image reader.
imageIndex - The image index to be given to the image reader for reading this tile.
region - The region in the destination image. The width and height should match the image size.
subsampling - The subsampling relative to the tile having the finest resolution, or null if none. If non-null, width and height should be strictly positive. This argument if of dimension kind because it can also be understood as relative "pixel size".
Throws:
java.lang.IllegalArgumentException - If a required argument is null or some argument has an invalid value.

Tile

public Tile(javax.imageio.spi.ImageReaderSpi provider,
            java.lang.Object input,
            int imageIndex,
            java.awt.Rectangle region,
            java.awt.geom.AffineTransform gridToCRS)
     throws java.lang.IllegalArgumentException
Creates a tile for the given provider, input and "grid to real world" transform. This constructor can be used when the location of the image to be read by the supplied reader is unknown. The definitive location and the subsampling will be computed automatically when this tile will be given to a TileManagerFactory.

When using this constructor, the getLocation(), getRegion() and getSubsampling() methods will throw an IllegalStateException until this tile has been given to a TileManager, which will compute those values automatically.

Parameters:
provider - The image reader provider to use. The same provider is typically given to every Tile objects to be given to the same TileManager instance, but this is not mandatory. If null, the provider will be inferred from the input. If it can't be inferred, then an exception is thrown.
input - The input to be given to the image reader.
imageIndex - The image index to be given to the image reader for reading this tile.
region - The tile region, or null if unknown. The (x,y) location of this region is typically (0,0). The definitive location will be computed when this tile will be given to a TileManagerFactory.
gridToCRS - The "grid to real world" transform.
Throws:
java.lang.IllegalArgumentException - If a required argument is null or some argument has an invalid value.

Tile

public Tile(javax.imageio.spi.ImageReaderSpi provider,
            java.lang.Object input,
            int imageIndex,
            java.awt.Rectangle region)
     throws java.lang.IllegalArgumentException
Creates a tile for the given region with default subsampling. This constructor is provided for avoiding compile-tile ambiguity between null subsampling and null affine transform (the former is legal, the later is not).

Parameters:
provider - The image reader provider to use. The same provider is typically given to every Tile objects to be given to the same TileManager instance, but this is not mandatory. If null, the provider will be inferred from the input. If it can't be inferred, then an exception is thrown.
input - The input to be given to the image reader.
imageIndex - The image index to be given to the image reader for reading this tile.
region - The region in the destination image. The width and height should match the image size.
Throws:
java.lang.IllegalArgumentException - If a required argument is null or some argument has an invalid value.
Method Detail

getImageReader

protected javax.imageio.ImageReader getImageReader(MosaicImageReader mosaic,
                                                   boolean seekForwardOnly,
                                                   boolean ignoreMetadata)
                                            throws java.io.IOException
Returns a reader created by the provider and setup for reading the image from the input. If a reader is already setup with the right input, then it is returned immediately. Otherwise if the image reader can accept the input directly, than that input is given to the image reader. Otherwise the input is wrapped in an image input stream.

This method is invoked automatically by MosaicImageReader and should not needs to be invoked directly. If an image input stream has been created, it will be closed automatically when needed.

Note that this method will typically returns an instance to be shared by every tiles in the given MosaicImageReader. Callers should not dispose the reader or change its configuration, unless the mosaic argument was null.

Parameters:
mosaic - The caller, or null if none.
seekForwardOnly - If true, images and metadata may only be read in ascending order from the input source.
ignoreMetadata - If true, metadata may be ignored during reads.
Returns:
An image reader with its input set.
Throws:
java.io.IOException - if the image reader can't be initialized.

getImageReader

public javax.imageio.ImageReader getImageReader()
                                         throws java.io.IOException
Returns a new reader created by the provider and setup for reading the image from the input. This method returns a new reader on each invocation.

It is the user's responsability to close the reader input after usage.

Returns:
An image reader with its input set.
Throws:
java.io.IOException - if the image reader can't be initialized.

getImageReaderSpi

public javax.imageio.spi.ImageReaderSpi getImageReaderSpi()
Returns the image reader provider (never null). This is the provider used for creating the image reader to be used for reading this tile.

Returns:
The image reader provider.
See Also:
ImageReaderSpi.createReaderInstance()

getInput

public java.lang.Object getInput()
Returns the input to be given to the image reader for reading this tile.

Returns:
The image input.
See Also:
ImageReader.setInput(java.lang.Object, boolean, boolean)

getInputName

public java.lang.String getInputName()
Returns a short string representation of the input. The default implementation returns the following:

Returns:
A short string representation of the input (never null).

getFormatName

public java.lang.String getFormatName()
Returns a format name inferred from the provider.

Returns:
The format name.

getImageIndex

public int getImageIndex()
Returns the image index to be given to the image reader for reading this tile.

Returns:
The image index, numbered from 0.
See Also:
ImageReader.read(int)

getGridToCRS

public java.awt.geom.AffineTransform getGridToCRS()
                                           throws java.lang.IllegalStateException
Returns the "grid to real world" transform, or null if unknown. This transform is derived from the value given to the constructor, but may not be identical since it may have been translated in order to get a uniform grid geometry for every tiles in a TileManager.

Returns:
The "grid to real world" transform, or null if undefined.
Throws:
java.lang.IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.
See Also:
TileManager.getGridGeometry()

getSubsampling

public java.awt.Dimension getSubsampling()
                                  throws java.lang.IllegalStateException
Returns the subsampling relative to the tile having the finest resolution. This method never returns null, and the width & height shall never be smaller than 1. The return type is of dimension kind because the value can also be interpreted as relative "pixel size".

Returns:
The subsampling along x and y axis.
Throws:
java.lang.IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.
See Also:
IIOParam.setSourceSubsampling(int, int, int, int)

getSubsamplingFloor

public java.awt.Dimension getSubsamplingFloor(java.awt.Dimension subsampling)
                                       throws java.lang.IllegalStateException
Returns the highest subsampling that this tile can handle, not greater than the given subsampling. Special cases:

Parameters:
subsampling - The subsampling along x and y axis.
Returns:
A subsampling equals or finer than the given one.
Throws:
java.lang.IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.

getLocation

public java.awt.Point getLocation()
                           throws java.lang.IllegalStateException
Returns the upper-left corner in the destination image. This is the location when no destination offset are specified. If the user specified a destination offset, then the tile location will be translated accordingly for the image being read.

Returns:
The tile upper-left corner.
Throws:
java.lang.IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.
See Also:
IIOParam.setDestinationOffset(java.awt.Point)

getRegion

public java.awt.Rectangle getRegion()
                             throws java.lang.IllegalStateException,
                                    java.io.IOException
Returns the upper-left corner in the destination image, with the image size. If this tile has been created with the constructor expecting a rectangle, a copy of the specified rectangle is returned. Otherwise the image width and height are read from the image reader and cached for future usage.

Returns:
The region in the destination image.
Throws:
java.lang.IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.
java.io.IOException - if it was necessary to fetch the image dimension from the reader and this operation failed.
See Also:
IIOParam.setSourceRegion(java.awt.Rectangle)

compareTo

public final int compareTo(Tile other)
Compares two tiles for optimal order in sequential reads. Default implementation sorts by input first, then increasing image index. This ordering allows efficient access for tiles that use the same image reader.

For tiles having the same input and index, additional criterions are used like increasing subsampling, increasing y then increasing x coordinates. But the actual set of additional criterions may change.

This method is consistent with equals(java.lang.Object) in the most common case where every tiles to be compared (typically every tiles given to a TileManager instance) have inputs of the same kind (preferrably File, URL, URI or String), and there is no duplicated (input, image index) pair.

Specified by:
compareTo in interface java.lang.Comparable<Tile>
Parameters:
other - The tile to compare with.
Returns:
-1 if this tile should be read before other, +1 if it should be read after or 0 if equals.

equals

public boolean equals(java.lang.Object object)
Compares this tile with the specified one for equality. Two tiles are considered equal if they have the same provider, input, image index, region and subsampling.

Overrides:
equals in class java.lang.Object
Parameters:
object - The object to compare with.
Returns:
true if both objects are equal.

hashCode

public int hashCode()
Returns a hash code value for this tile. The default implementation uses the reader, input and image index, which should be suffisient for uniquely distinguish every tiles.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Returns a string representation of this tile. The default implementation uses only the public getter methods, so if a subclass override them the effect should be visible in the returned string.

Overrides:
toString in class java.lang.Object

writeTable

public static void writeTable(java.util.Collection<Tile> tiles,
                              java.io.Writer out,
                              int maximum)
                       throws java.io.IOException
Formats a collection of tiles in a table. The tiles are appended in iteration order. Tip: consider sorting the tiles before to invoke this method; tiles are comparable for this purpose.

Parameters:
tiles - The tiles to format in a table.
out - Where to write the table.
maximum - The maximum number of tiles to format. If there is more tiles, a message will be formatted below the table. A reasonable value like 5000 is recommanded since attempt to format millions of tiles leads to OutOfMemoryError.
Throws:
java.io.IOException - If an error occured while writing to the given writer.
See Also:
Collections.sort(List)


Copyright © 1996-2010 Geotools. All Rights Reserved.