Package org.tinfour.utils

Class 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 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