|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.geotools.image.io.mosaic.Tile
public class Tile
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 prohibed, but doing so introduce some subsampling-dependant variations in images produced byMosaicImageReader
, which would not be what we would expect from a strictly compliantImageReader
.
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 byTileManager
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 analysing the layout
of a collection of tiles and instantiate TileManager
subclasses optimized for
the layout geometry.
Tile
s can be considered as immutable after construction. However some properties
may be available only after this tile has been given to a TileManagerFactory
.
Tile
s 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.
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 |
---|
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
getRegion()
is invoked.
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".
java.lang.IllegalArgumentException
- If a required argument is null
or some argument has an invalid value.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
getRegion()
will be invoked.
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".
java.lang.IllegalArgumentException
- If a required argument is null
or some argument has an invalid value.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
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.
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.
java.lang.IllegalArgumentException
- If a required argument is null
or some argument has an invalid value.public Tile(javax.imageio.spi.ImageReaderSpi provider, java.lang.Object input, int imageIndex, java.awt.Rectangle region) throws java.lang.IllegalArgumentException
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.
java.lang.IllegalArgumentException
- If a required argument is null
or some argument has an invalid value.Method Detail |
---|
protected javax.imageio.ImageReader getImageReader(MosaicImageReader mosaic, boolean seekForwardOnly, boolean ignoreMetadata) throws java.io.IOException
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.
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.
java.io.IOException
- if the image reader can't be initialized.public javax.imageio.ImageReader getImageReader() throws java.io.IOException
It is the user's responsability to close the reader input after usage.
java.io.IOException
- if the image reader can't be initialized.public javax.imageio.spi.ImageReaderSpi getImageReaderSpi()
null
). This is the provider used for
creating the image reader to be used for reading this tile.
ImageReaderSpi.createReaderInstance()
public java.lang.Object getInput()
ImageReader.setInput(java.lang.Object, boolean, boolean)
public java.lang.String getInputName()
"class"
followed by the unqualified class name.
null
).public java.lang.String getFormatName()
public int getImageIndex()
ImageReader.read(int)
public java.awt.geom.AffineTransform getGridToCRS() throws java.lang.IllegalStateException
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
.
null
if undefined.
java.lang.IllegalStateException
- If this tile has been created without location and not yet
processed by TileManagerFactory
.TileManager.getGridGeometry()
public java.awt.Dimension getSubsampling() throws java.lang.IllegalStateException
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".
java.lang.IllegalStateException
- If this tile has been created without location and not yet
processed by TileManagerFactory
.IIOParam.setSourceSubsampling(int, int, int, int)
public java.awt.Dimension getSubsamplingFloor(java.awt.Dimension subsampling) throws java.lang.IllegalStateException
null
, then this method returns null
.(0,0)
, then this method returns the
same subsampling
reference unchanged. Callers can test using the identity
(==
) operator.subsampling
reference unchanged. Callers can test using
the identity (==
) operator.null
.Dimension
set to the greatest subsampling
that this tile can handle, not greater than the given subsampling.
subsampling
- The subsampling along x and y axis.
java.lang.IllegalStateException
- If this tile has been created without location and not yet
processed by TileManagerFactory
.public java.awt.Point getLocation() throws java.lang.IllegalStateException
java.lang.IllegalStateException
- If this tile has been created without location and not yet
processed by TileManagerFactory
.IIOParam.setDestinationOffset(java.awt.Point)
public java.awt.Rectangle getRegion() throws java.lang.IllegalStateException, java.io.IOException
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.IIOParam.setSourceRegion(java.awt.Rectangle)
public final int compareTo(Tile other)
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.
compareTo
in interface java.lang.Comparable<Tile>
other
- The tile to compare with.
other
, +1 if it should be read
after or 0 if equals.public boolean equals(java.lang.Object object)
equals
in class java.lang.Object
object
- The object to compare with.
true
if both objects are equal.public int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
public static void writeTable(java.util.Collection<Tile> tiles, java.io.Writer out, int maximum) throws java.io.IOException
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
.
java.io.IOException
- If an error occured while writing to the given writer.Collections.sort(List)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |