Package org.tinfour.utils

Class GridSpecification

  • public class GridSpecification
extends Object
    Provides metadata for describing a grid and mapping Cartesian coordinates to and from grid coordinates. Also provides convenience routines for writing data to Esri's ASCII raster format (.asc files).

    • Constructor Detail

      • GridSpecification

        public GridSpecification​(GridSpecification.CellPosition cellPosition,
                         double cellSize,
                         double xmin,
                         double xmax,
                         double ymin,
                         double ymax)
        Constructs an instance based on a specified set of bounds with the requirement that the grid coordinates are integral multiples of the cellSize.

        Because the grid coordinate points will be aligned on integral multiples of the cellSize, there is no guarantee that the grid coordinates will exactly match the xmin/xmax, ymin/ymax values. The guarantee is that the grid points will be within the specified bounds. The cell alignment will be treated according to the specified CellPosition. The number of rows and columns will be computed based on the bounds and cell size.

        Caution: Interpretation of grid coordinates for Esri ASCII grid file form

        If you use this class to write files in Esri's ASCII format, the following cautions apply. The available documentation regarding how Esri specifies the coordinates for an ASCII grid are not publically available. Thus this class makes the following assumption based on the available information regarding the positioning of cells. If CenterOfCell is specified, then the coordinates for the lower-left corner and upper-right corners of the rectangular domain would lie in the lie in the center of the cell. If the CornerOfCell argument was specified, then these coordinates would lie respectively on the lower-left corner of the lower-left cell and on the upper-right corner of the upper-right cell. Consequently, when an application specifies a CornerOfCell positioning, the grid will contain one more row and column than when the application specifies a CenterOfCell. *

        Parameters:
        cellPosition - specifies the orientation of grid cells relative to the origin; the origin may be at the center or lower-left corner of a grid cell.
        cellSize - the dimension of the grid cell in the same coordinate system as the bounds
        xmin - the minimum x coordinate for the area of interest
        xmax - the maximum x coordinate for the area of interest
        ymin - the minimum y coordinate for the area of interest
        ymax - the maximum y coordinate for the area of interest

    • Method Detail

      • mapRowColumnToXy

        public void mapRowColumnToXy​(double row,
                             double col,
                             Point2D p2d)
        Maps the specified row and column values to the Cartesian coordinates in the system defined by the grid. The result is stored in an instance of Point2D.
        Parameters:
        row - the specified row, numbered from zero, ordered top to bottom
        col - the specified column, numbered from zero, ordered left to right
        p2d - an instance of Point2D to receive the x,y coordinates

      • mapXyToRowColumn

        public void mapXyToRowColumn​(double x,
                             double y,
                             double[] c,
                             int offset)
        Maps the specified x and y coordinates to non-integral row and column values.
        Parameters:
        x - the x coordinate for computation
        y - the y coordinate for computation
        c - an array to store the row and column values; row will be stored at the specified offset, column will be stored at offset+1.
        offset - the starting position within array c for storing data

      • writeAsciiFile

        public void writeAsciiFile​(File file,
                           float[][] values,
                           String dataFormat,
                           String noDataString)
                    throws IOException
        Writes a two dimensional array of values to a file in a form compatible with Esri's ASCII raster file format. The array is assumed to be structured to match the specifications of the current instance. Esri uses the extension ".asc" to indicate ASCII raster files.

        The dataFormat is a Java-style format string, such as "%f" or "%8.3f". No default is provided because it is assumed that the application has more valid information about the nature of the data than could be readily deduced from the inputs. The no-data value is usually a string giving numeric value outside the range of what could be expected in the normal course of operations. These formats should follow the conventions defined by Esri (see on-line ArcGIS documentation for more detail).

        Parameters:
        file - a value file reference.
        values - a two-dimensional array of values to be written to the output file; array must be dimensioned compatible with the specifications of the current instance.
        dataFormat - the format converter for formatting numerical values.
        noDataString - the string to be used for no-data values.
        Throws:
        IOException - in the event of an unrecoverable I/O error.

      • getCellPosition

        public GridSpecification.CellPosition getCellPosition()
        Get an enumerated value indicating the cellPosition
        Returns:
        a valid instance

      • getCellSize

        public double getCellSize()
        Gets the cellSize
        Returns:
        a valid, finite floating-point value.

      • getLowerLeftX

        public double getLowerLeftX()
        Gets the x coordinate of the lower-left bounds of the grid
        Returns:
        a valid, finite floating-point value.

      • getLowerLeftY

        public double getLowerLeftY()
        Gets the y coordinate of the lower-left bounds of the grid
        Returns:
        a valid, finite floating-point value.

      • getUpperRightX

        public double getUpperRightX()
        Gets the x coordinate of the upper-right bounds of the grid.
        Returns:
        a valid, finite floating-point value.

      • getUpperRightY

        public double getUpperRightY()
        Gets the y coordinate of the upper-right bounds of the grid
        Returns:
        a valid, finite floating-point value

      • getRowCount

        public int getRowCount()
        Gets the number of rows in the grid
        Returns:
        a positive number greater than zero.

      • getColumnCount

        public int getColumnCount()
        Gets the number of Columns in the grid.
        Returns:
        a positive number greater than zero.

      • getCellCount

        public int getCellCount()
        Gets the number of cells in the grid/
        Returns:
        a positive number greater than zero.