org.tinfour.utils

Class GridSpecification

java.lang.Object

org.tinfour.utils.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).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GridSpecification.CellPosition Specifies how the cells are oriented relative to the coordinates of the of the grid.

Constructor Summary

Constructors

Constructor and Description
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.

Method Summary

Modifier and Type	Method and Description
int	getCellCount()
GridSpecification.CellPosition	getCellPosition()
double	getCellSize()
int	getColumnCount()
double	getLowerLeftX()
double	getLowerLeftY()
int	getRowCount()
double	getUpperRightX()
double	getUpperRightY()
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.
void	mapXyToRowColumn(double x, double y, double[] c, int offset) Maps the specified x and y coordinates to non-integral row and column values.
void	writeAsciiFile(File file, float[][] values, String dataFormat, String noDataString) Writes a two dimensional array of values to a file in a form compatible with Esri's ASCII raster file format.

Methods inherited from class java.lang.Object

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

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()

Returns:

the cellPosition

getCellSize

public double getCellSize()

Returns:

the cellSize

getLowerLeftX

public double getLowerLeftX()

Returns:

the x coordinate of the lower-left bounds of the grid

getLowerLeftY

public double getLowerLeftY()

Returns:

the y coordinate of the lower-left bounds of the grid

getUpperRightX

public double getUpperRightX()

Returns:

the x coordinate of the upper-right bounds of the grid

getUpperRightY

public double getUpperRightY()

Returns:

the y coordinate of the upper-right bounds of the grid

getRowCount

public int getRowCount()

Returns:

the number of rows in the grid

getColumnCount

public int getColumnCount()

Returns:

the number of Columns in the grid.

getCellCount

public int getCellCount()

Returns:

the number of cells in the grid.