org.geotoolkit.image.io.mosaic
Class Tile

Object
  Tile

All Implemented Interfaces:

Serializable, Comparable<Tile>

@Immutable
public class Tile
extends Object
implements Comparable<Tile>, Serializable

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

• An ImageReaderSpi instance. The same provider is typically used for every tiles, but this is not mandatory. An image reader will be instantiated and the input will be assigned to it before a tile is read.

• An input, typically a file, URL, URI or String. The input is typically different for every tile to be read, but this is not mandatory. For example different tiles could be stored at different image index in the same file.

• An image index to be given to ImageReader.read(int) for reading the tile. This index is often 0.

• The upper-left corner in the destination image as a point, or the upper-left corner together with the image size as a rectangle. If the upper-left corner has been given as a point, then the width and height will be obtained from the image reader when first needed, which may have a slight performance cost. If the upper-left corner has been given as a rectangle instead, then this performance cost is avoided but the user is responsible for the accuracy of the information provided.

  NOTE: The upper-left corner is the location of this tile in the destination image 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.

• The subsampling relative to the tile having the best resolution. This is not the subsampling to apply when reading this tile, but rather the subsampling that we would need to apply on the tile having the finest resolution in order to produce an image equivalent to this tile. The subsampling is (1,1) for the tile having the finest resolution, (2,3) for an overview having half the width and third of the height for the same geographic extent, etc. (note that overviews are not required to have the same geographic extent - the above is just an example).

  NOTE 1: The semantic assumes that overviews are produced by subsampling, not by interpolation or pixel averaging. The later are not prohibited, but doing so introduce some subsampling-dependent variations in images produced by MosaicImageReader, which would not be what we would expect from a strictly compliant ImageReader.
  
  NOTE 2: Tile location and region coordinates should be specified in the overview pixel units - they should not be pre-multiplied by subsampling. This multiplication will be performed automatically by TileManager when comparing regions from tiles at different subsampling levels.

The tiles are not required to be arranged on a regular grid, but performances may be better if they are. TileManagerFactory is responsible for analyzing 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:

3.15

Author:

Martin Desruisseaux (Geomatys)

See Also:

TileManagerFactory, MosaicTableModel, Serialized Form

Module:

coverage/geotk-coverageio (download)

View source code for this class

Constructor Summary

Tile(ImageReaderSpi provider, File input, int imageIndex)
Creates a tile for the given file and its World File.

Tile(ImageReaderSpi provider, Object input, int imageIndex, Point location, Dimension subsampling)
Creates a tile for the given provider, input and location.

Tile(ImageReaderSpi provider, Object input, int imageIndex, Rectangle region)
Creates a tile for the given region with default subsampling.

Tile(ImageReaderSpi provider, Object input, int imageIndex, Rectangle region, AffineTransform gridToCRS)
Creates a tile for the given provider, input and "grid to real world" transform.

Tile(ImageReaderSpi provider, Object input, int imageIndex, Rectangle region, Dimension subsampling)
Creates a tile for the given provider, input and region.

Tile(Tile tile, Object input)
Creates a new tile which is a copy of the given one except for input.

Method Summary

int	compareTo(Tile other) Compares two tiles for optimal order in sequential reads.
boolean	equals(Object object) Compares this tile with the specified one for equality.
String	getFormatName() Returns a format name inferred from the provider.
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.
ImageReader	getImageReader() Returns a new reader created by the provider and setup for reading the image from the input.
protected ImageReader	getImageReader(MosaicImageReader mosaic, boolean seekForwardOnly, boolean ignoreMetadata) Returns a reader created by the provider and setup for reading the image from the input.
ImageReaderSpi	getImageReaderSpi() Returns the image reader provider (never null).
Object	getInput() Returns the input to be given to the image reader for reading this tile.
String	getInputName() Returns a short string representation of the input.
Point	getLocation() Returns the upper-left corner in the destination image.
Rectangle	getRegion() Returns the upper-left corner in the destination image, with the image size.
Dimension	getSize() Returns the image size.
Dimension	getSubsampling() Returns the subsampling relative to the tile having the finest resolution.
Dimension	getSubsamplingFloor(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.
static boolean	ignore(ImageReaderSpi provider) Returns true if we recommend to ignore the given provider.
String	toString() Returns a string representation of this tile.
static void	writeTable(Collection<Tile> tiles, Writer out, int maximum) Formats a collection of tiles in a table.

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

Tile

public Tile(Tile tile,
            Object input)

Creates a new tile which is a copy of the given one except for input. The subsampling, grid to CRS transform, image index and image reader SPI are copied unchanged.

This method is useful when the filename or the directory of a file changed.

Parameters:

tile - The tile to copy.

input - The new input to be given to the image reader.

Since:

3.15

Tile

public Tile(ImageReaderSpi provider,
            Object input,
            int imageIndex,
            Point location,
            Dimension subsampling)

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".

Tile

public Tile(ImageReaderSpi provider,
            Object input,
            int imageIndex,
            Rectangle region,
            Dimension subsampling)

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".

Tile

public Tile(ImageReaderSpi provider,
            Object input,
            int imageIndex,
            Rectangle region,
            AffineTransform gridToCRS)

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 mapping pixel upper left corner.

Tile

public Tile(ImageReaderSpi provider,
            Object input,
            int imageIndex,
            Rectangle region)

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.

Tile

public Tile(ImageReaderSpi provider,
            File input,
            int imageIndex)
     throws IOException

Creates a tile for the given file and its World File. The world file typically has a "tfw" extension (if the input is a TIFF image) or a "jgw" extension (if the input is a JPEG image), and must exists.

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.

Throws:

IOException - If no ".tfw or ".jgw" file (depending on the extension of the input file) is found, or if an error occurred while reading that file.

See Also:

TileManagerFactory.listTiles(ImageReaderSpi, File[])

Method Detail

ignore

public static boolean ignore(ImageReaderSpi provider)

Returns true if we recommend to ignore the given provider. The current implementation returns true if the given provider is an instance of ImageReaderAdapter.Spi, but the conditions may change in any future version.

The intend is to ignore the providers that are wrappers around "native" providers adding only support for SpatialMetadata. Because Tile does not need those metadata, the overhead of using those wrappers is not needed.

Note: If this method returns true for every submitted providers, then callers are encouraged to nevertheless use one of the "ignored" providers.

Parameters:

provider - An image reader provider.

Returns:

true if the given provider should be ignored for usage with Tile.

Since:

3.14

See Also:

ImageReaderAdapter.Spi.unwrap(ImageReaderSpi)

getImageReader

protected ImageReader getImageReader(MosaicImageReader mosaic,
                                     boolean seekForwardOnly,
                                     boolean ignoreMetadata)
                              throws 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:

IOException - if the image reader can't be initialized.

getImageReader

public ImageReader getImageReader()
                           throws 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 responsibility to close the reader input after usage and dispose the reader.

Returns:

An image reader with its input set.

Throws:

IOException - if the image reader can't be initialized.

getImageReaderSpi

public 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 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 String getInputName()

Returns a short string representation of the input. The default implementation returns the following:

• For Character sequence, returns the string form.
• For File, returns only the name part.
• For URL or URI, returns the path without the protocol or query parts.
• For other classes, returns "class" followed by the unqualified class name.

Returns:

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

getFormatName

public 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 AffineTransform getGridToCRS()
                             throws 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.

Tip: The World File coefficients of this tile (i.e. the grid to CRS transform that we would have if the pixel in the upper-left corner always had indices (0,0)) can be computed as below:

Point location = tile.getLocation();
AffineTransform gridToCRS = new AffineTransform(tile.getGridToCRS());
gridToCRS.translate(location.x, location.y);

Returns:

The "grid to real world" transform mapping pixel upper left corner, or null if undefined.

Throws:

IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.

See Also:

TileManager.getGridGeometry()

getSubsampling

public Dimension getSubsampling()
                         throws 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:

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 Dimension getSubsamplingFloor(Dimension subsampling)
                              throws IllegalStateException

Returns the highest subsampling that this tile can handle, not greater than the given subsampling. Special cases:

• If the given subsampling is null, then this method returns null.
• Otherwise if the given subsampling is (0,0), then this method returns the same subsampling reference unchanged. Callers can test using the identity (==) operator.
• Otherwise if this tile can handle exactly the given subsampling, then this method returns the same subsampling reference unchanged. Callers can test using the identity (==) operator.
• Otherwise if there is no subsampling that this tile could handle, then this method returns null.
• Otherwise this method returns a new Dimension set to the greatest subsampling that this tile can handle, not greater than the given subsampling.

Parameters:

subsampling - The subsampling along x and y axis.

Returns:

A subsampling equals or finer than the given one.

Throws:

IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.

getLocation

public Point getLocation()
                  throws 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:

IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.

See Also:

IIOParam.setDestinationOffset(java.awt.Point)

getSize

public Dimension getSize()
                  throws IOException

Returns the image size. If this tile has been created with the constructor expecting a rectangle, the dimension of that rectangle is returned. Otherwise the image width and height are read from the image reader and cached for future usage.

At the difference of getLocation() and getRegion(), this method never throw IllegalStateException because the tile size does not depend on the processing performed by TileManagerFactory.

Returns:

The tile size.

Throws:

IOException - if it was necessary to fetch the image dimension from the reader and this operation failed.

getRegion

public Rectangle getRegion()
                    throws IllegalStateException,
                           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:

IllegalStateException - If this tile has been created without location and not yet processed by TileManagerFactory.

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 (preferably File, URL, URI or String), and there is no duplicated (input, image index) pair.

Specified by:

compareTo in interface 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(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 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 sufficient for uniquely distinguish every tiles.

Overrides:

hashCode in class Object

toString

public 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 Object

Returns:

A string representation of this tile.

writeTable

public static void writeTable(Collection<Tile> tiles,
                              Writer out,
                              int maximum)
                       throws 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 recommended since attempt to format millions of tiles leads to OutOfMemoryError.

Throws:

IOException - If an error occurred while writing to the given writer.

See Also:

Collections.sort(List)