# Land and coast

Every `seagrid` model (`glorys`, `ecco2`, `scrippsgog`) has a land mask and
a distance-to-land field. Both return a NumPy-backed `xarray.DataArray` on
the model's `(y, x)` T-cells, with `lon` and `lat` coordinates:

```python
from tracmass.seagrid import glorys

land = glorys.landmask()             # bool, True on land (kmt == 0)
dist = glorys.distance_to_land()     # float32 km, 0 on land
deep = glorys.distance_to_land(k=20) # at level 20 the sea floor counts as land
```

- `k` is the 1-based model level. At level `k`, every column with
  `kmt < k` counts as land.
- Distance is the great-circle distance between cell centres, so a cell next
  to the coast is about one cell width from land. It is computed with a
  KD-tree on unit-sphere coordinates, which handles curvilinear grids and
  the date line. Full GLORYS takes about 5 s.
- On a regional grid such as GoG, land outside the domain is unknown, so
  distances near the open boundaries can be too large.
- A model only resolves the islands its grid resolves. In the open South
  Pacific, ECCO2 (1/4°) gives distances up to about 4900 km, where GLORYS
  (1/12°) gives about 3100 km.

For another grid, pass any dataset with `kmt`, `lon` and `lat` to the
generic functions:

```python
from tracmass.seagrid import coast

mask = coast.landmask(grid_ds, k=1)
dist = coast.distance_to_land(mask)
```

Typical uses are seeding only near the coast, or removing particles that
start too close to it:

```python
near = dist < 50                                   # within 50 km of land
state = seed.mask(near.values & ~land.values, kpos=1)
```