org.geotoolkit.image.io.plugin
Class TextRecordImageReader

Object
  ImageReader
      SpatialImageReader
          StreamImageReader
              TextImageReader
                  TextRecordImageReader

All Implemented Interfaces:

Disposable, Localized, WarningProducer

public class TextRecordImageReader
extends TextImageReader

Image decoder for text files storing pixel values as records. Such text files use one line (record) by pixel. Each line contains at least 3 columns (in arbitrary order):

• Pixel's x coordinate.
• Pixel's y coordinate.
• An arbitrary number of pixel values.

For example, some Sea Level Anomaly (SLA) files contains rows of longitude (degrees), latitude (degrees), SLA (cm), East/West current (cm/s) and North/South current (cm/s), as below:

45.1250 -29.8750    -7.28     10.3483     -0.3164
45.1250 -29.6250    -4.97     11.8847      3.6192
45.1250 -29.3750    -2.91      3.7900      3.0858
45.1250 -29.1250    -3.48     -5.1833     -5.0759
45.1250 -28.8750    -4.36     -1.8129    -16.3689
45.1250 -28.6250    -3.91      7.5577    -24.6801
(...etc...)

From this decoder point of view, the two first columns (longitude and latitude) are pixel's logical coordinate (x,y), while the three last columns are three image's bands. The whole file contains only one image, unless SpatialImageReader.getNumImages(boolean) has been overridden. All (x,y) coordinates belong to pixel's center. This decoder will automatically translate (x,y) coordinates from logical space to pixel space.

By default, TextRecordImageReader assumes that x and y coordinates appear in column #0 and 1 respectively. It also assumes that numeric values are encoded using current defaults Charset and Locale, and that there is no pad value. The easiest way to change the default setting is to create a TextRecordImageReader.Spi subclass. There is no need to subclass TextRecordImageReader, unless you want more control on the decoding process.

Example
The text of the left side is an extract of a list of (longitude, latitude, elevation of the ocean floor) records. The image on the right side is the image produced by TextRecordImageReader when reading such file.

# Longitude Latitude Altitude 59.9000 -30.0000 -3022 59.9333 -30.0000 -3194 59.9667 -30.0000 -3888 60.0000 -30.0000 -3888 45.0000 -29.9667 -2502 45.0333 -29.9667 -2502 45.0667 -29.9667 -2576 45.1000 -29.9667 -2576 45.1333 -29.9667 -2624 45.1667 -29.9667 -2690 45.2000 -29.9667 -2690 45.2333 -29.9667 -2692 45.2667 -29.9667 -2606 45.3000 -29.9667 -2606 45.3333 -29.9667 -2528 etc...

Since:

3.08 (derived from 1.2)

Version:

3.08

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

coverage/geotk-coverageio (download)

View source code for this class

Nested Class Summary

static class

TextRecordImageReader.Spi Service provider interface (SPI) for TextRecordImageReaders.

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

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

Method Summary

protected void	close() Closes the reader created by TextImageReader.getReader().
protected SpatialMetadata	createMetadata(int imageIndex) Returns metadata associated with the given image.
protected int	getColumnX(int imageIndex) Returns the column number for x values.
protected int	getColumnY(int imageIndex) Returns the column number for y values.
int	getHeight(int imageIndex) Returns the height in pixels of the given image within the input source.
int	getNumBands(int imageIndex) Returns the number of bands available for the specified image.
int	getWidth(int imageIndex) Returns the width in pixels of the given image within the input source.
BufferedImage	read(int imageIndex, ImageReadParam param) Reads the image indexed by imageIndex and returns it as a buffered image.
protected void	round(double[] values) Invoked during read operation for rounding a record of values.

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, dispose, getDefaultReadParam, getDestination, getDimension, getGridEnvelope, getImageMetadata, getImageType, getImageTypes, getNumImages, getRawDataType, 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

TextRecordImageReader

public TextRecordImageReader(TextRecordImageReader.Spi provider)

Constructs a new image reader.

Parameters:

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

Method Detail

getColumnX

protected int getColumnX(int imageIndex)
                  throws IOException

Returns the column number for x values. The default implementation returns TextRecordImageReader.Spi.xColumn, or 0 if no service prodiver were specified to the constructor. Subclasses should override this method if this information should be obtained in an other way.

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The column number for x values.

Throws:

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

getColumnY

protected int getColumnY(int imageIndex)
                  throws IOException

Returns the column number for y values. The default implementation returns TextRecordImageReader.Spi.yColumn, or 1 if no service prodiver were specified to the constructor. Subclasses should override this method if this information should be obtained in an other way.

Parameters:

imageIndex - The index of the image to be queried.

Returns:

The column number for y values.

Throws:

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

getNumBands

public int getNumBands(int imageIndex)
                throws IOException

Returns the number of bands available for the specified image. The default implementation reads the image immediately and counts the number of columns after the geodetic coordinate columns.

Overrides:

getNumBands in class SpatialImageReader

Parameters:

imageIndex - The image index.

Returns:

The number of bands available for the specified image.

Throws:

IOException - if an error occurs while reading the information from the input source.

getWidth

public int getWidth(int imageIndex)
             throws IOException

Returns the width in pixels of the given image within the input source. Invoking this method forces the reading of the whole image.

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 while 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. Invoking this method forces the reading of the whole image.

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 while reading the height information from the input source.

createMetadata

protected SpatialMetadata createMetadata(int imageIndex)
                                  throws IOException

Returns metadata associated with the given image. Calling this method may force loading of full 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.

round

protected void round(double[] values)

Invoked during read operation for rounding a record of values. The default implementation does nothing. The main purpose of this method is to give to subclasses an opportunity to fix rounding errors in latitude and longitude coordinates.

Example
Assume that the longitudes in a file are likely to have an interval of 1/6° but are written with only 3 decimal digits. In such case, the x values look like 10.000, 10.167, 10.333, etc., which can leads to an error of 0.001° in longitude. This error may cause TextRecordImageReader to fails validation tests and throws an IIOException: "Points dont seem to be distributed on a regular grid".

A work around is to multiply the x and y coordinates by 6, round to the nearest integer and divide them by 6 as in the code below (which is doing the same process to latitude):

int xColumn = getColumnX();
int yColumn = getColumnY();
values[xColumn] = XMath.roundIfAlmostInteger(values[xColumn] * 6, 3) / 6;
values[yColumn] = XMath.roundIfAlmostInteger(values[yColumn] * 6, 3) / 6;

Parameters:

values - The values to round in place.

read

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

Reads the image indexed by imageIndex and returns it as a buffered image.

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 error occurs during reading.

close

protected void close()
              throws IOException

Closes the reader created by TextImageReader.getReader(). This method does nothing if the reader is the input instance given by the user rather than a reader created by this class from a File or URL input.

Overrides:

close in class TextImageReader

Throws:

IOException - If an error occurred while closing the reader.

See Also:

StreamImageReader.closeOnReset