# Utils/Distance

Distance calculations and related geodetic operations.

## Import and use

Generally, we import the library itself:

```python
from gri_utils import distance

meters = distance.surface_dist_vincenty(lla1, lla2)
```

But to distinguish from other libraries, the [Google Style Guide](https://google.github.io/styleguide/pyguide.html#22-imports) also recommends giving it a more unique name, eg:

```python
from gri_utils import distance as gri_dist

meters = gri_dist.surface_dist_vincenty(lla1, lla2)
```

## Vectorization

Most functions support vectorized operations for efficient batch processing. Pass arrays of shape `(N, 2+)` for LLA coordinates or `(N, 3)` for XYZ coordinates to compute pairwise results:

```python
import numpy as np
from gri_utils import distance

# Compute distances for 3 point pairs at once
lla1 = np.array([[0, 0, 0], [45, 0, 0], [90, 0, 0]])
lla2 = np.array([[0, 1, 0], [45, 1, 0], [90, 1, 0]])
distances = distance.surface_dist_haversine(lla1, lla2)  # Returns (3,) array
```

Single point inputs return scalar `float` values for convenience.

## Distance Formulas

Each distance formula has its own strengths and weaknesses and are documented in their respective modules, usually with links to Wikipedia for more reading.

### dist_xyz

A straight line 3D distance that is simply the magnitude of p2-p1 in XYZ (same units as p2 and p1). Simple, but included to prevent retyping the same equation over and over. Supports vectorized inputs.

### surface_dist_simple

A rudimentary calculation using the mean latitude to provide a very fast spherical Earth estimated distance. Useful when speed and _relative_ distance is most important. Still about as accurate as haversine with distances under 500km. Supports vectorized inputs.

### surface_dist_haversine

One of the "gold standard" calculations used for surface distance. Assumes a spherical Earth and is known to have errors around 0.5%. Optionally uses geocentric radius at the midpoint latitude for improved accuracy. Supports vectorized inputs.

### surface_dist_vincenty

An iterative, but far more accurate series expansion to determine most distances on an oblate spheroid Earth. The calculation is more expensive, but can be as accurate as 0.5mm across distances. Scalar inputs only (no vectorization due to iterative convergence).

## Geodetic Utilities

### central_angle

Computes the central angle (in radians) between two points on a sphere using the haversine formula. This is the arc length divided by the radius. Supports vectorized inputs.

### osculating_sphere

Calculates the osculating sphere at a point on the WGS84 ellipsoid - the sphere that best approximates the ellipsoid locally with the same curvature in all directions. Returns the sphere center (ECEF) and radius. Supports vectorized inputs.
