bordado.get_spacing

bordado.get_spacing(coordinates, tol=1e-05)

Determine the point spacing from a set of coordinates.

Tries to infer the spacing between adjacent points for cases where the coordinates describe regularly spaced points. If points are not regularly spaced, an exception will be raised.

Parameters:

coordinatestuple = (easting, northing, …)

Tuple of arrays with the coordinates of each point. Arrays can be Python lists or any numpy-compatible array type. Arrays must all have the same shape. The number of dimensions of each array must be equal to the number of arrays in the tuple. For example, 2D grids require 2 arrays and each array must be 2D.

tolfloat

The relative tolerance used to check if the spacing is uniform and if the spacing is equal in all dimensions. Floating point checks cannot be done with equality so a tolerance is always necessary. Should be a positive float and can be interpreted as a decimal percentage of difference that is tolerated.

Returns:

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

The spacing in each direction of the given coordinates, in reverse order. A single value means that the spacing is equal in all directions (within the given tolerance). If a tuple, will have one value per coordinate. The order of arguments is the opposite of the order of the coordinates for compatibility with the shape argument of functions like grid_coordinates.

Examples

Let’s say we have the following sequence of values:

>>> coordinates = ([1, 2, 3, 4],)

The spacing between them is clearly 1 and it’s constant. This won’t be easy to tell for most datasets, though. To get the spacing information, we can do this instead:

>>> spacing = get_spacing(coordinates)
>>> print(f"{spacing:.1f}")
1.0

If the spacing isn’t constant, an exception will be raised:

>>> get_spacing(([1, 2, 3, 5],))
Traceback (most recent call last):
...
ValueError: Coordinate 0 is not evenly spaced along axis 0...

The same works for multidimensional coordinates. In this case, 2D coordinates must describe a regular grid as produced by bordado.grid_coordinates. All coordinates must be 2D arrays, the first varying along axis 1 and the second along axis 0:

>>> coordinates = (
...     [[1.0, 1.5, 2.0],
...      [1.0, 1.5, 2.0],
...      [1.0, 1.5, 2.0]],
...     [[-6.0, -6.0, -6.0],
...      [-5.5, -5.5, -5.5],
...      [-5.0, -5.0, -5.0]]
... )
>>> spacing = get_spacing(coordinates)
>>> print(f"{spacing:.1f}")
0.5

Multidimensional coordinates may be evenly spaced but the spacing may vary between each dimension. In this case, the returned value will be a tuple with the spacing along each dimension in the opposite order of the coordinates:

>>> coordinates = (
...     [[1.0, 1.5, 2.0],
...      [1.0, 1.5, 2.0],
...      [1.0, 1.5, 2.0]],
...     [[-6.0, -6.0, -6.0],
...      [-4.5, -4.5, -4.5],
...      [-3.0, -3.0, -3.0]]
... )
>>> spacing = get_spacing(coordinates)
>>> print(len(spacing))
2
>>> print(", ".join([f"{s:.1f}" for s in spacing]))
1.5, 0.5

The checks that the spacing is regular cannot be exact because of floating point rounding errors. So they are done within a specified relative tolerance. For example, this should fail with the default tolerance:

>>> spacing = get_spacing(([1, 2, 3.0001, 4],))
Traceback (most recent call last):
...
ValueError: Coordinate 0 is not evenly spaced along axis 0...

But if we increase the tolerance to 1%, it could be made to pass.

>>> spacing = get_spacing(([1, 2, 3.0001, 4],), tol=0.01)
>>> print(f"{spacing:.3f}")
1.000