bordado.grid_coordinates

bordado.grid_coordinates(region, *, shape=None, spacing=None, adjust='spacing', pixel_register=False, non_dimensional_coords=None)

Generate evenly spaced points on an n-dimensional grid.

The grid can be specified by either the number of points in each dimension (the shape) or by the grid node spacing in each dimension.

If the given region is not divisible by the desired spacing, either the region or the spacing will have to be adjusted. By default, the spacing will be rounded to the nearest multiple. Optionally, the boundaries of the region can be adjusted to fit the exact spacing given. See the examples below.

Supports laying out points on a grid-node registration or a pixel registration. See examples below for more information.

Parameters:

regionlist = [W, E, S, N, …]

The boundaries of a given region in Cartesian or geographic coordinates. Should have a lower and an upper boundary for each dimension of the coordinate system.

shapetuple = (…, size_SN, size_WE) or None

The number of points in each direction of the given region, in reverse order. Must have one integer value per dimension of the region. The order of arguments is the opposite of the order of the region for compatibility with numpy’s .shape attribute. If None, spacing must be provided. Default is None.

spacingfloat, tuple = (…, space_SN, space_WE), or None

The grid spacing in each direction of the given region, in reverse order. A single value means that the spacing is equal in all directions. If a tuple, must have one value per dimension of the region. The order of arguments is the opposite of the order of the region for compatibility with shape. If None, shape must be provided. Default is None.

adjuststr = “spacing” or “region”

Whether to adjust the spacing or the region if the spacing is not a multiple of the region. Ignored if shape is given instead of spacing. Default is "spacing".

pixel_registerbool

If True, the coordinates will refer to the center of each grid pixel instead of the grid lines. In practice, this means that there will be one less element per dimension of the grid when compared to grid line registered (only if given spacing and not shape). Default is False.

non_dimensional_coordsNone, scalar, or tuple of scalars

If not None, then value(s) of extra non-dimensional coordinates (coordinates that aren’t part of the grid dimensions, like height for a lat/lon grid). Will generate extra coordinate arrays from these values with the same shape of the final grid coordinates and the constant value given here. Use this to generate arrays of constant heights or times, for example, which might be needed to accompany a grid.

Returns:

coordinatestuple of arrays

Arrays with coordinates of each point in the grid. Each array contains values for a dimension in the order of the given region, and any extra values given in non_dimensional_coords. All arrays will have the same shape.

Examples

>>> east, north = grid_coordinates(region=(0, 5, 0, 10), shape=(5, 3))
>>> print(east.shape, north.shape)
(5, 3) (5, 3)
>>> print(east)
[[0.  2.5 5. ]
 [0.  2.5 5. ]
 [0.  2.5 5. ]
 [0.  2.5 5. ]
 [0.  2.5 5. ]]
>>> print(north)
[[ 0.   0.   0. ]
 [ 2.5  2.5  2.5]
 [ 5.   5.   5. ]
 [ 7.5  7.5  7.5]
 [10.  10.  10. ]]

The grid can also be specified using the spacing between points instead of the shape:

>>> east, north = grid_coordinates(region=(0, 5, 0, 10), spacing=2.5)
>>> print(east.shape, north.shape)
(5, 3) (5, 3)
>>> print(east)
[[0.  2.5 5. ]
 [0.  2.5 5. ]
 [0.  2.5 5. ]
 [0.  2.5 5. ]
 [0.  2.5 5. ]]
>>> print(north)
[[ 0.   0.   0. ]
 [ 2.5  2.5  2.5]
 [ 5.   5.   5. ]
 [ 7.5  7.5  7.5]
 [10.  10.  10. ]]

The spacing can be different for northing and easting, respectively:

>>> east, north = grid_coordinates(region=(-5, 1, 0, 10), spacing=(2.5, 1))
>>> print(east.shape, north.shape)
(5, 7) (5, 7)
>>> print(east)
[[-5. -4. -3. -2. -1.  0.  1.]
 [-5. -4. -3. -2. -1.  0.  1.]
 [-5. -4. -3. -2. -1.  0.  1.]
 [-5. -4. -3. -2. -1.  0.  1.]
 [-5. -4. -3. -2. -1.  0.  1.]]
>>> print(north)
[[ 0.   0.   0.   0.   0.   0.   0. ]
 [ 2.5  2.5  2.5  2.5  2.5  2.5  2.5]
 [ 5.   5.   5.   5.   5.   5.   5. ]
 [ 7.5  7.5  7.5  7.5  7.5  7.5  7.5]
 [10.  10.  10.  10.  10.  10.  10. ]]

Grids of more dimensions can be generated by specifying more elements in region and shape/spacing:

>>> east, north, up = grid_coordinates(
...     region=(0, 5, 0, 10, -4, 0), shape=(2, 5, 3)
... )
>>> print(east.shape, north.shape, up.shape)
(2, 5, 3) (2, 5, 3) (2, 5, 3)
>>> print(east)
[[[0.  2.5 5. ]
  [0.  2.5 5. ]
  [0.  2.5 5. ]
  [0.  2.5 5. ]
  [0.  2.5 5. ]]

 [[0.  2.5 5. ]
  [0.  2.5 5. ]
  [0.  2.5 5. ]
  [0.  2.5 5. ]
  [0.  2.5 5. ]]]
>>> print(north)
[[[ 0.   0.   0. ]
  [ 2.5  2.5  2.5]
  [ 5.   5.   5. ]
  [ 7.5  7.5  7.5]
  [10.  10.  10. ]]

 [[ 0.   0.   0. ]
  [ 2.5  2.5  2.5]
  [ 5.   5.   5. ]
  [ 7.5  7.5  7.5]
  [10.  10.  10. ]]]
>>> print(up)
[[[-4. -4. -4.]
  [-4. -4. -4.]
  [-4. -4. -4.]
  [-4. -4. -4.]
  [-4. -4. -4.]]

 [[ 0.  0.  0.]
  [ 0.  0.  0.]
  [ 0.  0.  0.]
  [ 0.  0.  0.]
  [ 0.  0.  0.]]]

If the region can’t be divided into the desired spacing, the spacing will be adjusted to conform to the region:

>>> east, north = grid_coordinates(region=(-5, 0, 0, 5), spacing=2.6)
>>> print(east.shape, north.shape)
(3, 3) (3, 3)
>>> print(east)
[[-5.  -2.5  0. ]
 [-5.  -2.5  0. ]
 [-5.  -2.5  0. ]]
>>> print(north)
[[0.  0.  0. ]
 [2.5 2.5 2.5]
 [5.  5.  5. ]]
>>> east, north = grid_coordinates(region=(-5, 0, 0, 5), spacing=2.4)
>>> print(east.shape, north.shape)
(3, 3) (3, 3)
>>> print(east)
[[-5.  -2.5  0. ]
 [-5.  -2.5  0. ]
 [-5.  -2.5  0. ]]
>>> print(north)
[[0.  0.  0. ]
 [2.5 2.5 2.5]
 [5.  5.  5. ]]

You can choose to adjust the East and North boundaries of the region instead:

>>> east, north = grid_coordinates(
...     region=(-5, 0, 0, 5), spacing=2.6, adjust='region',
... )
>>> print(east.shape, north.shape)
(3, 3) (3, 3)
>>> print(east)
[[-5.1 -2.5  0.1]
 [-5.1 -2.5  0.1]
 [-5.1 -2.5  0.1]]
>>> print(north)
[[-0.1 -0.1 -0.1]
 [ 2.5  2.5  2.5]
 [ 5.1  5.1  5.1]]
>>> east, north = grid_coordinates(
...     region=(-5, 0, 0, 5), spacing=2.4, adjust='region',
... )
>>> print(east.shape, north.shape)
(3, 3) (3, 3)
>>> print(east)
[[-4.9 -2.5 -0.1]
 [-4.9 -2.5 -0.1]
 [-4.9 -2.5 -0.1]]
>>> print(north)
[[0.1 0.1 0.1]
 [2.5 2.5 2.5]
 [4.9 4.9 4.9]]

We can optionally generate coordinates for the center of each grid pixel instead of the corner (default):

>>> east, north = grid_coordinates(
...     region=(0, 5, 0, 10), spacing=2.5, pixel_register=True,
... )
>>> # Notice that the shape is 1 less than when pixel_register=False
>>> print(east.shape, north.shape)
(4, 2) (4, 2)
>>> print(east)
[[1.25 3.75]
 [1.25 3.75]
 [1.25 3.75]
 [1.25 3.75]]
>>> print(north)
[[1.25 1.25]
 [3.75 3.75]
 [6.25 6.25]
 [8.75 8.75]]
>>> east, north = grid_coordinates(
...     region=(0, 5, 0, 10), shape=(4, 2), pixel_register=True,
... )
>>> print(east)
[[1.25 3.75]
 [1.25 3.75]
 [1.25 3.75]
 [1.25 3.75]]
>>> print(north)
[[1.25 1.25]
 [3.75 3.75]
 [6.25 6.25]
 [8.75 8.75]]

Generate arrays for other coordinates that have a constant value:

>>> east, north, height = grid_coordinates(
...     region=(0, 5, 0, 10), spacing=2.5, non_dimensional_coords=57
... )
>>> print(east.shape, north.shape, height.shape)
(5, 3) (5, 3) (5, 3)
>>> print(height)
[[57. 57. 57.]
 [57. 57. 57.]
 [57. 57. 57.]
 [57. 57. 57.]
 [57. 57. 57.]]
>>> east, north, height, time = grid_coordinates(
...     region=(0, 5, 0, 10), spacing=2.5, non_dimensional_coords=[57, 0.1]
... )
>>> print(east.shape, north.shape, height.shape, time.shape)
(5, 3) (5, 3) (5, 3) (5, 3)
>>> print(height)
[[57. 57. 57.]
 [57. 57. 57.]
 [57. 57. 57.]
 [57. 57. 57.]
 [57. 57. 57.]]
>>> print(time)
[[0.1 0.1 0.1]
 [0.1 0.1 0.1]
 [0.1 0.1 0.1]
 [0.1 0.1 0.1]
 [0.1 0.1 0.1]]