org.geotoolkit.image.io.plugin
Class AsciiGridReader

Object
  ImageReader
      SpatialImageReader
          StreamImageReader
              TextImageReader
                  AsciiGridReader

All Implemented Interfaces:

WarningProducer, Disposable, Localized

public class AsciiGridReader
extends TextImageReader

Reader for the ASCII Grid format. As the "ASCII" name implies, the data files are read in US-ASCII character encoding no matter what the TextImageReader.Spi.charset value is. In addition, the US locale is enforced no matter what the ImageReader.locale value is, with a tolerance for the decimal separator character which can be either '.' or ','.

ASCII grid files contains a header before the actual data. The header contains (key value) pairs, one pair per line and using the space as the separator between key and value. The valid keys are listed in table below (see the ASCII Grid Format Description for more details). Note that Geotk adds some extensions to the standard ASCII grid format:

• Comment lines and empty lines are ignored.
• The '=' and ':' characters can be used as a separator between the keys and the values.
• The CELLSIZE attribute can be substituted by the DX and DY attributes. DX/DY are not standard, but can be produced by the GDAL library. See GDAL notes for more information.
• The "MIN_VALUE" and "MAX_VALUE" attributes are Geotk extensions not defined in the ASCII Grid standard. While optional, they are quite convenient for setting the color space.

Subclasses can add their own (key, value) pairs, or modify the ones defined below, by overriding the processHeader(Map) method.

Keyword	Value type	Obligation
NCOLS	Integer	Mandatory
NROWS	Integer	Mandatory
XLLCORNER or XLLCENTER	Floating point	Mandatory
YLLCORNER or YLLCENTER	Floating point	Mandatory
CELLSIZE	Floating point	Mandatory, unless DX and DY are present
DX and DY	Floating point	Accepted but non-standard
NODATA_VALUE	Floating point	Optional
MIN_VALUE	Floating point	Optional - this is a Geotk extension
MAX_VALUE	Floating point	Optional - this is a Geotk extension
BINARY_TYPE	String	Optional - this is a Geotk extension

BINARY_TYPE is a Geotk extension provided for performance only. If this attribute is provided and if the input is a File, URL or URI, then AsciiGridReader will looks for a file of the same name with the ".raw" extension. If this file is found, then the data in the ASCII file will be ignored (they can be non-existent) and the RAW file will be read instead, which is usually much faster. The value of the BINARY_TYPE attribute specify the data type: BYTE, SHORT, USHORT, INT, FLOAT or DOUBLE.

Since:

3.08 (derived from 3.07)

Version:

3.12

Author:

Martin Desruisseaux (Geomatys)

See Also:

ASCII Grid Format Description, ESRI Grid on Wikipedia, AsciiGridWriter

Module:

coverage/geotk-coverageio (download)

View source code for this class

TODO:

The current implementation ignores the seekForwardOnly parameter. It processes as if that parameter was always set to true.

Nested Class Summary

static class

AsciiGridReader.Spi Service provider interface (SPI) for AsciiGridReaders.

Field Summary

Fields inherited from class StreamImageReader

closeOnReset

Fields inherited from class ImageReader

availableLocales, ignoreMetadata, input, locale, minIndex, originatingProvider, progressListeners, seekForwardOnly, updateListeners, warningListeners, warningLocales

Fields inherited from interface WarningProducer

LOGGER

Constructor Summary

protected

AsciiGridReader(AsciiGridReader.Spi provider) Constructs a new image reader.

Method Summary

protected void	close() Closes the input stream created by this reader as documented in the super-class method.
protected SpatialMetadata	createMetadata(int imageIndex) Returns metadata associated with the given image.
void	dispose() Allows any resources held by this reader to be released.
int	getHeight(int imageIndex) Returns the height in pixels of the given image within the input source.
protected int	getRawDataType(int imageIndex) Returns the data type which most closely represents the "raw" internal data of the image.
int	getWidth(int imageIndex) Returns the width in pixels of the given image within the input source.
protected void	processHeader(Map<String,String> header) Invoked automatically after the (key, value) pairs in the header have been read.
BufferedImage	read(int imageIndex, ImageReadParam param) Reads the image indexed by imageIndex.

Methods inherited from class TextImageReader

getCharset, getLineFormat, getPadValue, getPositionString, getReader, isComment

Methods inherited from class StreamImageReader

finalize, getChannel, getInputStream, getStreamLength, setInput

Methods inherited from class SpatialImageReader

checkBandIndex, checkImageIndex, collapseNoDataValues, flipVertically, getDefaultReadParam, getDestination, getDimension, getGridEnvelope, getImageMetadata, getImageType, getImageTypes, getNumBands, getNumImages, getRawImageType, getStreamMetadata, hasColors, warningOccurred

Methods inherited from class ImageReader

abort, abortRequested, addIIOReadProgressListener, addIIOReadUpdateListener, addIIOReadWarningListener, canReadRaster, checkReadParamBandSettings, clearAbortRequest, computeRegions, getAspectRatio, getAvailableLocales, getDestination, getFormatName, getImageMetadata, getInput, getLocale, getMinIndex, getNumThumbnails, getOriginatingProvider, getSourceRegion, getStreamMetadata, getThumbnailHeight, getThumbnailWidth, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, 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 Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface Localized

getLocale

Constructor Detail

AsciiGridReader

protected AsciiGridReader(AsciiGridReader.Spi provider)

Constructs a new image reader.

Parameters:

provider - The ImageReaderSpi that is constructing this object, or null.

Method Detail

getWidth

public int getWidth(int imageIndex)
             throws IOException

Returns the width in pixels of the given image within the input source.

Specified by:

getWidth in class ImageReader

Parameters:

imageIndex - the index of the image to be queried.

Returns:

Image width.

Throws:

IOException - If an error occurs reading the width information from the input source.

getHeight

public int getHeight(int imageIndex)
              throws IOException

Returns the height in pixels of the given image within the input source.

Specified by:

getHeight in class ImageReader

Parameters:

imageIndex - the index of the image to be queried.

Returns:

Image height.

Throws:

IOException - If an error occurs reading the width information from the input source.

getRawDataType

protected int getRawDataType(int imageIndex)
                      throws IOException

Returns the data type which most closely represents the "raw" internal data of the image. If a "BINARY_TYPE" attribute is presents in the header, then the code corresponding to that attribute is returned. Otherwise DataBuffer.TYPE_FLOAT is returned.

Overrides:

getRawDataType in class SpatialImageReader

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The data type (DataBuffer.TYPE_FLOAT by default).

Throws:

IOException - If an error occurs reading the format information from the input source.

See Also:

SpatialImageReader.getImageType(int, ImageReadParam, SampleConverter[]), SampleConversionType.SHIFT_SIGNED_INTEGERS

createMetadata

protected SpatialMetadata createMetadata(int imageIndex)
                                  throws IOException

Returns metadata associated with the given image.

Overrides:

createMetadata in class SpatialImageReader

Parameters:

imageIndex - The image index.

Returns:

The metadata, or null if none.

Throws:

IOException - If an error occurs reading the data information from the input source.

processHeader

protected void processHeader(Map<String,String> header)
                      throws IOException

Invoked automatically after the (key, value) pairs in the header have been read. Subclasses can override this method in order to modify the map passed in argument. They can freely add, remove of modify values.

Keys shall be upper-case, and the mandatory attributes defined in the class javadoc shall be present in the header map after the completion of this method.

The default implementation does nothing.

Parameters:

header - A modifiable map of (key, value) pairs.

Throws:

IOException - If an error occurred while processing the header values.

read

public BufferedImage read(int imageIndex,
                          ImageReadParam param)
                   throws IOException

Reads the image indexed by imageIndex.

Specified by:

read in class ImageReader

Parameters:

imageIndex - The index of the image to be retrieved.

param - Parameters used to control the reading process, or null.

Returns:

The desired portion of the image.

Throws:

IOException - if an input operation failed.

close

protected void close()
              throws IOException

Closes the input stream created by this reader as documented in the super-class method. If an input stream was created for reading the data from a RAW file, it is also closed.

Overrides:

close in class TextImageReader

Throws:

IOException - If an error occurred while closing the reader.

See Also:

StreamImageReader.closeOnReset

dispose

public void dispose()

Allows any resources held by this reader to be released.

Specified by:

dispose in interface Disposable

Overrides:

dispose in class SpatialImageReader