org.tinfour.utils

Class GridFileReader

java.lang.Object

org.tinfour.utils.GridFileReader

All Implemented Interfaces:

Closeable, AutoCloseable

public class GridFileReader
extends Object
implements Closeable

Provides a utility for reading a file specified in the Esri ASCII file format. This class implements a simple one-pass file access approach. The constructor reads the file header to obtain the overall grid dimensions. The readGrid() method reads the rest of the file. Once the grid is read, this class cannot be used to perform further file access. If an application is using the constructor that accepts a File, the close method should be called. If the application is using the InputStream variation, the management of the InputStream is left to the calling application.

Because grids can be quite large, there may be an advantage to reading only part of the grid into memory. A future version of this class may include access methods for reading the grid a row at a time.

The ASCII grid file format was created by Esri, Inc. and is widely documented on the web. However, an official description of the format was never released to the public. Therefore most information about the format has been obtained through inspection by various developers.

Development Note: The ASCII grid format supports two approaches to grid geometry depending on whether the specified coordinates for the lower-left corner indicate the center of the cell or the edge of the cell (e.g. cell-center or cell-corner representations). The Tinfour implementation of the cell-center approach has been verified using independent software applications. The implementation of the cell-corner approach has not been independently verified. The Tinfour project welcomes the assistance of anyone with resources to perform further testing and verification of this class and the GridSpecification class.

Constructor Summary

Constructors

Constructor and Description
GridFileReader(File file) Opens the specified file, reads the grid specification header, and prepares to read the grid.
GridFileReader(InputStream input) Reads the grid specification header, from the specified input stream and prepares to read the grid.

Method Summary

Modifier and Type	Method and Description
void	close()
GridSpecification	getGridSpecification() Gets the specification read from the file header.
double[][]	readGrid() Reads the grid portion of the file.

Methods inherited from class java.lang.Object

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

Constructor Detail

GridFileReader

public GridFileReader(File file)
               throws IOException

Opens the specified file, reads the grid specification header, and prepares to read the grid. The internal input stream is advanced through the header and positioned at the start of the data section of the file.

Parameters:

file - a valid file reference

Throws:

IOException - in the event of an unrecoverable I/O condition or file-format error

GridFileReader

public GridFileReader(InputStream input)
               throws IOException

Reads the grid specification header, from the specified input stream and prepares to read the grid. The input stream is advanced through the header and positioned at the start of the data section of the file.

Performance note: It is strongly advised that the specified input stream include some kind of buffering to ensure efficient operations. For example, if the input is a Java FileInputStream, it should be wrapped in a Java BufferedInputStream.

Parameters:

input - a valid input stream positioned to the start of the ASCII file header.

Throws:

IOException - in the event of an unrecoverable I/O condition or file-format error

Method Detail

getGridSpecification

public GridSpecification getGridSpecification()

Gets the specification read from the file header. The specification indicates the dimensions of the grid section of the file.

Returns:

a valid instance.

readGrid

public double[][] readGrid()
                    throws IOException

Reads the grid portion of the file. This method should be called only once. The grid is organized following the Esri convention giving data in row-major order starting from the upper-left row of the gird.

Returns:

if successful, a valid instance of a fully populated grid

Throws:

IOException - in the event of an unrecoverable I/O condition or file-format error

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException