|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.imageio.ImageReader
org.geotools.image.io.GeographicImageReader
public abstract class GeographicImageReader
Base class for readers of geographic images. The default implementation assumes that only one
image type is supported (as opposed to the arbitrary number
allowed by the standard ImageReader
). It also provides a default image type built
automatically from a color palette and a range of valid values.
More specifically, this class provides the following conveniences to implementors:
Provides default getNumImages(boolean)
and getNumBands(int)
implementations,
which return 1. This default behavior matches simple image formats like flat binary
files or ASCII files. Those methods need to be overrided for more complex image
formats.
Provides checkImageIndex(int)
and checkBandIndex(int, int)
convenience methods.
Those methods are invoked by most implementation of public methods. They perform their
checks based on the informations provided by the above-cited getNumImages(boolean)
and
getNumBands(int)
methods.
Provides default implementations of getImageTypes(int)
and getRawImageType(int)
,
which assume that only one image type is supported. The
default image type is created from the informations provided by getRawDataType(int)
and getImageMetadata(int)
.
Provides getStreamMetadata()
and getImageMetadata(int)
default
implementations, which return null
as authorized by the specification.
Note that subclasses should consider returning GeographicMetadata
instances.
Field Summary |
---|
Fields inherited from class javax.imageio.ImageReader |
---|
availableLocales, ignoreMetadata, input, locale, minIndex, originatingProvider, progressListeners, seekForwardOnly, updateListeners, warningListeners, warningLocales |
Constructor Summary | |
---|---|
protected |
GeographicImageReader(javax.imageio.spi.ImageReaderSpi provider)
Constructs a new image reader. |
Method Summary | |
---|---|
protected void |
checkBandIndex(int imageIndex,
int bandIndex)
Ensures that the specified band index is inside the expected range. |
protected void |
checkImageIndex(int imageIndex)
Ensures that the specified image index is inside the expected range. |
protected boolean |
collapseNoDataValues(boolean isZeroValid,
double[] nodataValues,
int unusedSpace)
Returns true if the no-data values should be collapsed to 0 in order to save memory. |
protected static void |
flipVertically(javax.imageio.ImageReadParam param,
int srcHeight,
java.awt.Rectangle srcRegion)
Flips the source region vertically. |
javax.imageio.ImageReadParam |
getDefaultReadParam()
Returns a default parameter object appropriate for this format. |
protected java.awt.image.BufferedImage |
getDestination(int imageIndex,
javax.imageio.ImageReadParam parameters,
int width,
int height,
SampleConverter[] converters)
Returns the buffered image to which decoded pixel data should be written. |
int |
getDimension(int imageIndex)
Returns the number of dimension of the image at the given index. |
GeographicMetadata |
getGeographicMetadata(int imageIndex)
Returns a helper parser for metadata associated with the given image. |
javax.imageio.metadata.IIOMetadata |
getImageMetadata(int imageIndex)
Returns metadata associated with the given image. |
java.util.Iterator<javax.imageio.ImageTypeSpecifier> |
getImageTypes(int imageIndex)
Returns a collection of ImageTypeSpecifier containing possible image types to which
the given image may be decoded. |
int |
getNumBands(int imageIndex)
Returns the number of bands available for the specified image. |
int |
getNumImages(boolean allowSearch)
Returns the number of images available from the current input source. |
protected int |
getRawDataType(int imageIndex)
Returns the data type which most closely represents the "raw" internal data of the image. |
javax.imageio.ImageTypeSpecifier |
getRawImageType(int imageIndex)
Returns an image type specifier indicating the SampleModel and ColorModel
which most closely represents the "raw" internal format of the image. |
protected javax.imageio.ImageTypeSpecifier |
getRawImageType(int imageIndex,
javax.imageio.ImageReadParam parameters,
SampleConverter[] converters)
Returns an image type specifier indicating the SampleModel and ColorModel
which most closely represents the "raw" internal format of the image. |
javax.imageio.metadata.IIOMetadata |
getStreamMetadata()
Returns metadata associated with the input source as a whole. |
java.awt.image.BufferedImage |
read(int imageIndex)
Reads the image indexed by imageIndex using a default ImageReadParam . |
void |
setInput(java.lang.Object input,
boolean seekForwardOnly,
boolean ignoreMetadata)
Sets the input source to use. |
void |
warningOccurred(java.util.logging.LogRecord record)
Invoked when a warning occured. |
Methods inherited from class javax.imageio.ImageReader |
---|
abort, abortRequested, addIIOReadProgressListener, addIIOReadUpdateListener, addIIOReadWarningListener, canReadRaster, checkReadParamBandSettings, clearAbortRequest, computeRegions, dispose, getAspectRatio, getAvailableLocales, getDestination, getFormatName, getHeight, getImageMetadata, getInput, getLocale, getMinIndex, getNumThumbnails, getOriginatingProvider, getSourceRegion, getStreamMetadata, getThumbnailHeight, getThumbnailWidth, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, getWidth, hasThumbnails, isIgnoringMetadata, isImageTiled, isRandomAccessEasy, isSeekForwardOnly, processImageComplete, processImageProgress, processImageStarted, processImageUpdate, processPassComplete, processPassStarted, processReadAborted, processSequenceComplete, processSequenceStarted, processThumbnailComplete, processThumbnailPassComplete, processThumbnailPassStarted, processThumbnailProgress, processThumbnailStarted, processThumbnailUpdate, processWarningOccurred, processWarningOccurred, read, readAll, readAll, readAsRenderedImage, readerSupportsThumbnails, readRaster, readThumbnail, readTile, readTileRaster, removeAllIIOReadProgressListeners, removeAllIIOReadUpdateListeners, removeAllIIOReadWarningListeners, removeIIOReadProgressListener, removeIIOReadUpdateListener, removeIIOReadWarningListener, reset, setInput, setInput, setLocale |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected GeographicImageReader(javax.imageio.spi.ImageReaderSpi provider)
provider
- The ImageReaderSpi
that is invoking this constructor,
or null
if none.Method Detail |
---|
public void setInput(java.lang.Object input, boolean seekForwardOnly, boolean ignoreMetadata)
setInput
in class javax.imageio.ImageReader
input
- The input object to use for future decoding.seekForwardOnly
- If true
, images and metadata may only be read
in ascending order from this input source.ignoreMetadata
- If true
, metadata may be ignored during reads.protected void checkImageIndex(int imageIndex) throws java.io.IOException, java.lang.IndexOutOfBoundsException
minIndex
inclusive (initially 0)
to getNumImages
(false)
exclusive.
imageIndex
- Index to check for validity.
java.lang.IndexOutOfBoundsException
- if the specified index is outside the expected range.
java.io.IOException
- If the operation failed because of an I/O error.protected void checkBandIndex(int imageIndex, int bandIndex) throws java.io.IOException, java.lang.IndexOutOfBoundsException
getNumBands
(imageIndex)
exclusive.
imageIndex
- The image index.bandIndex
- Index to check for validity.
java.lang.IndexOutOfBoundsException
- if the specified index is outside the expected range.
java.io.IOException
- If the operation failed because of an I/O error.public int getNumImages(boolean allowSearch) throws java.lang.IllegalStateException, java.io.IOException
getNumImages
in class javax.imageio.ImageReader
allowSearch
- If true, the number of images will be returned
even if a search is required.
allowSearch
is false and a search would be required.
java.lang.IllegalStateException
- if the input source has not been set.
java.io.IOException
- if an error occurs reading the information from the input source.public int getNumBands(int imageIndex) throws java.io.IOException
imageIndex
- The image index.
java.io.IOException
- if an error occurs reading the information from the input source.public int getDimension(int imageIndex) throws java.io.IOException
imageIndex
- The image index.
java.io.IOException
- if an error occurs reading the information from the input source.public javax.imageio.metadata.IIOMetadata getStreamMetadata() throws java.io.IOException
null
.
getStreamMetadata
in class javax.imageio.ImageReader
java.io.IOException
- if an error occurs during reading.public javax.imageio.metadata.IIOMetadata getImageMetadata(int imageIndex) throws java.io.IOException
null
.
getImageMetadata
in class javax.imageio.ImageReader
imageIndex
- The image index.
null
if none.
java.io.IOException
- if an error occurs during reading.public GeographicMetadata getGeographicMetadata(int imageIndex) throws java.io.IOException
getImageMetadata(imageIndex)
, wraps
the result in a GeographicMetadata
object if non-null and caches the result.
Note that this method forces ImageReader.ignoreMetadata
to false
for the time of
getImageMetadata(imageIndex)
execution,
because some image reader implementations need geographic metadata in order to infer
a valid color model.
imageIndex
- The image index.
null
if none.
java.io.IOException
- if an error occurs during reading.public java.util.Iterator<javax.imageio.ImageTypeSpecifier> getImageTypes(int imageIndex) throws java.io.IOException
ImageTypeSpecifier
containing possible image types to which
the given image may be decoded. The default implementation returns a singleton containing
getRawImageType
(imageIndex)
.
getImageTypes
in class javax.imageio.ImageReader
imageIndex
- The index of the image to be retrieved.
java.io.IOException
- If an error occurs reading the format information from the input source.public javax.imageio.ImageTypeSpecifier getRawImageType(int imageIndex) throws java.io.IOException
SampleModel
and ColorModel
which most closely represents the "raw" internal format of the image. The default
implementation delegates to the following:
getRawImageType(imageIndex, getDefaultReadParam(), null);
If this method needs to be overriden, consider overriding the later instead.
getRawImageType
in class javax.imageio.ImageReader
imageIndex
- The index of the image to be queried.
null
).
java.io.IOException
- If an error occurs reading the format information from the input source.protected javax.imageio.ImageTypeSpecifier getRawImageType(int imageIndex, javax.imageio.ImageReadParam parameters, SampleConverter[] converters) throws java.io.IOException
SampleModel
and ColorModel
which most closely represents the "raw" internal format of the image. The default
implementation applies the following rules:
The range of expected values and the no-data values are extracted from the geographic metadata, if any.
If the given parameters
argument is an instance of GeographicImageReadParam
,
then the user-supplied palette name
is fetched. Otherwise or if no palette name was explicitly set, then this method default
to "rainbow". The
palette name will be used in order to read a
predefined set of colors (as RGB values) to be given to the
index color model.
If the raw data type is TYPE_FLOAT
or TYPE_DOUBLE
, then this method builds
a continuous palette suitable for
the range fetched at step 1. The data are assumed geophysics values
rather than some packed values. Consequently, the sample
converters will replace no-data values by NaN with no other
changes.
Otherwise, if the raw data type is a unsigned integer type
like TYPE_BYTE
or TYPE_USHORT
,
then this method builds an indexed palette (i.e. a
palette backed by an index color model) with just the minimal
size needed for containing fully the range and the
no-data values fetched at step 1. The data are assumed packed values rather
than geophysics values. Consequently, the sample converters
will be the identity converter except in the
following cases:
collapseNoDataValues
method.Otherwise, if the raw data type is a signed integer
type like TYPE_SHORT
, then this method builds an
indexed palette with the maximal size supported by the raw data type (note that this is
memory expensive - typically 256 kilobytes). Negative values will be stored in their
two's complement binary form in order to fit in the range of positive integers
supported by the index color model.
int minimum = -2000; //
minimal expected valuemaximal expected value
int maximum = +2300; //Value for missing data
int fillValue = -9999; //Named set of RGB colors
String palette = "SST-Nasa";//
converters[0] = SampleConverter.createOffset(1 - minimum, fillValue);
return PaletteFactory.getDefault().getPalettePadValueFirst(paletteName, maximum - minimum).getImageTypeSpecifier();
imageIndex
- The index of the image to be queried.parameters
- The user-supplied parameters, or null
. Note: we recommand to supply
getDefaultReadParam()
instead of null
since subclasses may
override the later with default values suitable to a particular format.converters
- If non-null, an array where to store the converters created by this method.
Those converters should be used by read(imageIndex, parameters)
implementations for converting the values
read in the datafile to values acceptable for the underling color model.
null
).
java.io.IOException
- If an error occurs while reading the format information from the input source.getRawDataType(int)
,
collapseNoDataValues(boolean, double[], int)
,
getDestination(int, ImageReadParam, int, int, SampleConverter[])
protected int getRawDataType(int imageIndex) throws java.io.IOException
DataBuffer
constants. The default GeographicImageReader
implementation works better with the following types:
TYPE_BYTE
,
TYPE_SHORT
,
TYPE_USHORT
and
TYPE_FLOAT
.
The default implementation returns TYPE_FLOAT
in every cases.
TYPE_BYTE
or TYPE_USHORT
),
then the values will be translated in order to fit in the range of strictly positive values.
For example if the raw internal data range from -23000 to +23000, then there is a choice:
If this method returns DataBuffer.TYPE_SHORT
, then the data will be
stored "as is" without transformation. However the index color model will have the maximal length allowed by 16 bits integers, with
positive values in the [0 .. 32767] range and negative
values wrapped in the [32768 .. 65535] range in two's complement binary form. The
results is a color model consuming 256 kilobytes in every cases. The space not used
by the [-23000 .. +23000] range (in the above example) is lost.
If this method returns DataBuffer.TYPE_USHORT
, then the data will be
translated to the smallest strictly positive range that can holds the data
([1..46000] for the above example). Value 0 is reserved for missing data. The
result is a smaller index color model than the
one used by untranslated data.
imageIndex
- The index of the image to be queried.
DataBuffer.TYPE_FLOAT
by default).
java.io.IOException
- If an error occurs reading the format information from the input source.getRawImageType(int, ImageReadParam, SampleConverter[])
protected boolean collapseNoDataValues(boolean isZeroValid, double[] nodataValues, int unusedSpace)
true
if the no-data values should be collapsed to 0 in order to save memory.
This method is invoked automatically by the getRawImageType
method when it detected some unused space between the
range of valid values and at least one
no-data value.
The default implementation returns false
in all cases, thus avoiding arbitrary
choice. Subclasses can override this method with some arbitrary threashold, as in the
example below:
return unusedSpace >= 1024;
isZeroValid
- true
if 0 is a valid value. If this method returns true
while
isZeroValid
is true
, then the sample
converter to be returned by getRawImageType
will offset all valid values by 1.nodataValues
- The sorted
no-data values (never null and never empty).unusedSpace
- The largest amount of unused space outside the range of valid values.protected java.awt.image.BufferedImage getDestination(int imageIndex, javax.imageio.ImageReadParam parameters, int width, int height, SampleConverter[] converters) throws java.io.IOException
Implementations of the ImageReader.read(int,ImageReadParam)
method should invoke this
method instead of ImageReader.getDestination(ImageReadParam,Iterator,int,int)
.
imageIndex
- The index of the image to be retrieved.parameters
- The parameter given to the read
method.width
- The true width of the image or tile begin decoded.height
- The true width of the image or tile being decoded.converters
- If non-null, an array where to store the converters required
for converting decoded pixel data into stored pixel data.
java.io.IOException
- If an error occurs reading the format information from the input source.getRawImageType(int, ImageReadParam, SampleConverter[])
public javax.imageio.ImageReadParam getDefaultReadParam()
GeographicImageReadParam
.
getDefaultReadParam
in class javax.imageio.ImageReader
ImageReadParam
object which may be used.public java.awt.image.BufferedImage read(int imageIndex) throws java.io.IOException
imageIndex
using a default ImageReadParam
.
This is a convenience method that calls read(imageIndex, getDefaultReadParam())
.
The default Java implementation passed a null
parameter. This implementation
passes the default parameter instead in order to improve consistency when a subclass
overrides getDefaultReadParam()
.
read
in class javax.imageio.ImageReader
imageIndex
- the index of the image to be retrieved.
java.lang.IllegalStateException
- if the input source has not been set.
java.lang.IndexOutOfBoundsException
- if the supplied index is out of bounds.
java.io.IOException
- if an error occurs during reading.protected static void flipVertically(javax.imageio.ImageReadParam param, int srcHeight, java.awt.Rectangle srcRegion)
computeRegions
when the image to be read will be flipped
vertically, for example when the raster sample
values are filled in a "for (y=ymax-1; y>=ymin; y--)
" loop instead of
"for (y=ymin; y<ymax; y++)
".
This method should be invoked as in the example below:
computeRegions(param, srcWidth, srcHeight, image, srcRegion, destRegion); flipVertically(param, srcHeight, srcRegion);
param
- The param
argument given to computeRegions
.srcHeight
- The srcHeight
argument given to computeRegions
.srcRegion
- The srcRegion
argument given to computeRegions
.public void warningOccurred(java.util.logging.LogRecord record)
warningOccurred
method is
invoked for each of them and the log record is not logged."org.geotools.image.io"
logger.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |