Class Grids

This class is used to initialize grid information for a map projection. This grid can be any desired size and resolution. Common uses could be 1 cell per meter, 1 cell per 500km, etc. This class helps translate between map units and grid units.

Constructor Summary

Grids ( )
Create a grids object, uninitialized.

Method Summary

initialize_grid (1) ( filename )
Initialize a grid with a built-in grid description
initialize_grid (2) ( origin_col , origin_row , cols_per_map_unit , rows_per_map_unit , num_cols , num_rows , mapx_obj )
Initialize a grid by manually defining the grid parameters.
copy_grid ( )
Creates a copy of the object.
forward_grid ( lat , lon , row , col )
Converts a lat/lon coordinate to a row/col coordinate.
inverse_grid ( row , col , lat , lon )
Converts a row/col coordinate to a lat/lon coordinate.

Constructor Detail

Grids
Create a grids object, uninitialized.


Parameters
None.

Returns
Returns a new, uninitialized Grids object

Examples 
var gr = new Grids();
// Creates a new empty Grids object

Notes
After creating the Grids object you will then need to initialize the grid information using one of the initialize_grid methods.

Method Detail

initialize_grid (1)
Initialize a grid with a built-in grid description


Parameters
filename - The "filename" of the built-in grid definition.

Returns
A reference to the Grids object used to make the call

Examples 
gr.initialize_grid('East.gpd');
// Initializes the Grids object with the built in "East.gpd"
// grids definition

Notes
See the mapx_definitions.txt file for a list of predefined grid definitions. Using this initializer will cause a Mapx object to be created and attached automatically. The Mapx object created will depend on the definition used.

initialize_grid (2)
Initialize a grid by manually defining the grid parameters.


Parameters
origin_col - The grid column coordinate of the map origin
origin_row - The grid row coordinate of the map origin
cols_per_map_unit - The number of grid columns per map unit
rows_per_map_unit - The number of grid rows per map unit
num_cols - The number of columns in the grid
num_rows - The number of rows in the grid
mapx_obj - A pre-initialized Mapx projection object

Returns
A reference to the Grids object used to make the call

Examples 
gr.initialize_grid(2159.5, 1079.5, 12, 12, 4320, 4320, mx)
// Initializes a 4320x4320 grid, in which the map's origin
// is in the center, and each column represents 1/12 of a
// map unit (defined by the projection).  Predefined mapx
// object mx is passed in as well.

Notes
The mapx_obj must be initialized prior to using this method. See the Mapx object for details on creating the projection object.

copy_grid
Creates a copy of the object.


Parameters
None.

Returns
Returns a copy of the Grids object used to make the call

Examples 
var newgr = gr.copy_grid();
// Creates a copy of the gr Grids object.

Notes
The mapx_obj object used internally is NOT copied, but rather a pointer to the same object is used by both Grids objects.

forward_grid
Converts a lat/lon coordinate to a row/col coordinate.


Parameters
lat - A number representing the latitude of the coordinate
lon - A number representing the longitude of the coordinate
row - An array that will store the resulting row
col - An array that will store the resulting column

Returns
false if there is a problem converting, true otherwise.

Examples 
status = gr.forward_grid(20, -30.3, r, c);
// Converts the coordinate 20N,30.3W, puts the row in r[0]
// and the column in c[0]

Notes
The latitude value should be between -90 and 90, with negative numbers representing south latitudes, positive representing north. The longitude values should be between -180 and 180, with negative values representing west longitudes, positive representing east. The row and col arrays MUST be created before calling the method, though any values stored in them will be ignored. Only the [0] element is used. Typically, the false value is returned if no mapx object has been set (rare), if the coordinates do not have a mapping for the projection, or lat/lon value is outside the defined boundaries of the mapx_obj object.

inverse_grid
Converts a row/col coordinate to a lat/lon coordinate.


Parameters
row - The grid row coordinate
col - The grid column coordinate
lat - An array that will store the resulting latitude
lon - An array that will store the resulting longitude

Returns
false if there is a problem converting, true otherwise

Examples 
status = gr.inverse_grid(3.4, 1.1, lat, lon);
// Converts the grid coordinate 3.4,1.1, puts the latitude
// value in lat[0] and the longitude value in lon[0]

Notes
The resulting latitude will be between -90 and 90, with negative values representing south latitudes, positive representing north. The resulting longitude will be between -180 and 180, with negative values representing west longitudes, postitive representing east. The lat and lon arrays MUST be created before calling the method, though any values stored in them will be ignored. Only the [0] element is used. Typically, the false value is returned if no mapx object has been set (rare), if the coordinates do not have a mapping for the projection, or the resulting lat/lon values are outside the defined boundaries of the mapx_obj object. longitue will be between -180 and 180