Files
11eb72f578 feat(planner): Coverage tab, reach of a candidate repeater site (#2406)
The repeater planner (#2391) gets a fourth tab, **Coverage**: put a
marker where you are thinking of placing a repeater, set its antenna
height, and see on the map who would hear it. It answers the siting
question "what does a repeater reach if we put it here", with two
layers: handheld users and other repeaters.

## What it shows

- **Users layer:** the chance that a handheld at 1.5 m hears the site,
in 4 bands (10-25%, 25-50%, 50-75%, 75% and up; below 10% is not
painted). The chance comes from a distance curve `P(d) = 1 / (1 +
exp((ln d - ln d50) / slope))`, fitted on drive-test receptions of 41
Belgian repeaters (d50 2.7 km, slope 0.30). Terrain only lowers a cell
by 2 bands where a 1.5 m receiver sits deeper than 1 first-Fresnel
radius under the terrain (`cmd/server/planner_viewshed.go:19-21`).
Antenna height does not change the curve: in the drive tests, handheld
reach barely changed between 1, 7 and 15 m. The panel says so in one
line.
- **Repeaters layer:** first-Fresnel clearance from the site to every
cell, for a receiver at "Repeaters at" height (default
`planner.existingAntennaM`). 3 classes: line of sight (clearance 0% or
more), slightly blocked (-20% to 0%), blocked (not painted). Every known
repeater within range gets its link computed with the existing planner
link code, a dot in its class colour, a line for line of sight and
slightly blocked, and an entry in a list.
- **Compute button:** changing site, height or range moves the marker
and updates the URL hash right away, and dims an existing result with an
"Outdated" note. Only "Compute coverage" starts a job. A shared link
that carries a site computes once on open. The planner has 1 heavy-job
slot shared with Area and allows 6 jobs per minute per IP, so
recomputing on every change would burn both.

State is in the hash:
`#/tools/planner?mode=coverage&site=51.06,4.41&h=10&rx=5&range=30&layer=repeaters`.

This builds on the repeater planner @zfouts wrote in #2391: the terrain
tiles, the first-Fresnel analysis, the link code, the job protocol and
the Area module pattern are all reused here. Thanks for that work, it
made this tab a small addition instead of a new subsystem.

## Why the Repeaters classes are not the route LOS verdicts

The route verdicts (clear 100%+, clear60 60%+, marginal 0%+, blocked)
almost never show on Shuttle Radar Topography Mission (SRTM) terrain at
mast heights. At 10 m / 5 m, 30 km around Mechelen, 109 of 70,980 cells
reach clear60 or clear. SRTM includes trees and roofs, so the line
between 2 masts rarely clears 60% of the Fresnel zone.

I checked the clearance against one Belgian repeater (28 m, receivers at
5 m) and the repeaters live data shows it actually hears:

| Distance | Heard, clearance >= 0 | Heard, clearance < 0 |
|---|---|---|
| 0-10 km | 9 of 11 | none in range |
| 10-20 km | 3 of 4 | 1 of 8 |
| 20-30 km | 0 of 6 | 3 of 35 |
| 30-60 km | 1 of 2 | 0 of 84 |

Every link heard within 16 km had a clearance between 2% and 54%, so
"marginal" is where working links live. The map classes follow that
(`repeaterClass`, `cmd/server/planner_viewshed.go:75-89`). Chain, Relay
and Area keep the shared verdicts; `losVerdict` is unchanged. This rests
on 17 heard links from 1 repeater, which is why the -20% band is narrow
and the panel says line of sight stops being enough beyond about 20 km.

## Server

- `GET /api/planner/viewshed?site=&h=&rx=&range=`
(`cmd/server/planner_api.go:603`, route `cmd/server/routes.go:393`).
Same job protocol, result cache, rate limits and opt-in as the other
planner endpoints: 404 while `planner.enabled` is false.
- One byte per cell: low nibble Users class 1-5, high nibble Repeaters
class 1-3, 0 for no data. The grid is about 300 x 300 at every range:
0.2 km cells up to 30 km, `range/150` above (`planner_viewshed.go:47`).
- Links skip rooms, stale repeaters and a repeater within 100 m of the
site (that is the site itself). They carry no `elev_m` profile.
- `truncated` is true only when the 300-node cap may have dropped a
repeater within range (`viewshedTruncated`, `planner_api.go:694`).
- Tile cap: `Viewshed` in the planner tile limits, sized from the
largest offered range (60 km).
- New config: `planner.userReach.{d50Km,slope}` with a `_comment` in
`config.example.json`. Bounds 0.2-50 km and 0.05-2.
- No writes, no new `map[string]interface{}`; response types
`PlannerViewshedResponse/Params/Link` in `planner_types.go`.

## Frontend

- `public/planner-coverage.js` + `.css`, mounted like `planner-area.js`.
`planner.js` gets a `MODULES` table (`public/planner.js:31`) so Area and
Coverage share one enter/leave path.
- Canvas raster in an `L.imageOverlay`; the layer switch repaints
locally without a new request. Requests go through `fetchJob` / `CSApi`.
- Colours are CSS variables `--pl-cov-user-2..5` and `--pl-cov-rep-1..3`
in `:root` and both dark blocks of `style.css`; the Repeaters ones point
at `--status-*`, so a theme that changes those changes the map.

## Performance

The job is opt-in and runs in the existing planner job slot, never in a
hot path. Measured on real SRTM tiles, local build, 304 Belgian
repeaters:

| Site | Range | Mast | Job time |
|---|---|---|---|
| Maasvallei (hilly) | 30 km | 10 m | 2.07 s |
| Maasvallei | 30 km | 30 m | 2.57 s |
| Maasvallei | 60 km | 10 m | 3.98 s |
| Mechelen (flat) | 30 km | 10 m | 2.61 s |

On a staging instance (ARM64, cold tile cache) a 30 km job took 6.8 s
including the tile downloads. Response size at 60 km with 115 links:
239,942 bytes with link elevation profiles, 149,984 without (what this
PR ships). `BenchmarkViewshedMaxLeg` covers the 60 km worst case on a
synthetic terrain view.

## Verification

- Go: 26 viewshed tests and benchmarks in `planner_viewshed_test.go`,
`planner_api_test.go`, `planner_config_test.go` and
`planner_tiles_test.go`, among them: flat terrain equals the plain curve
and `analyzeLOS`, a ridge shadows only its far side, missing terrain is
"no data", the `truncated` rule (proven to fail on the old rule), links
without `elev_m`, the repeater at the site left out. `go test ./...` in
`cmd/server` passes.
- Frontend: `tests/unit/test-planner-coverage.js` (23 tests, in
`test-all.sh`): grid decode, class-to-colour mapping, unpainted classes,
hash round trip, no fetch on parameter change, 1 fetch per click,
deep-link autorun once, stale responses ignored, link classes at the
boundaries, escaped repeater names.
- E2E: 5 Coverage cases in `tests/e2e/test-planner-e2e.js` (stubbed
viewshed): click and compute, layer switch without a request, outdated
then recompute, deep link, leaving the tab removes the overlay. Planner
E2E 25/25 locally.
- eslint 0 errors. Browser: light and dark theme, Users and Repeaters on
flat, hilly and coastal sites, deep links, no console errors; also on a
staging instance with live data.

## Not in this PR

- The `--pl-cov-*` colours are not in the customizer's `THEME_CSS_MAP`
yet. They follow `--status-*` for the Repeaters layer; the Users colours
need their own entries (AGENTS.md rule 8, later milestone).
- In Flanders the Users layer is close to a circle: 0.3% of cells differ
from the plain curve around Mechelen, 42% in the Maasvallei, 64% in the
Ardennes. The terrain correction is untested in hilly areas, the drive
tests had no repeater there.
- The Repeaters calibration uses 1 repeater. Other operators with drive
tests or neighbour data can tighten it.
- A link's class comes from `clearance_pct`, rounded to 0.1%, while the
grid uses the raw clearance: within 0.05% of a bound a link can land 1
class off the cell under it. List, line and dot always agree with each
other.
- An OS dark-mode switch without the theme toggle does not repaint the
overlay until the next compute, the same as the planner's tile layer.

---------

Co-authored-by: zfouts <zachary.fouts@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 23:19:49 +01:00

156 lines
5.3 KiB
Go

package main
import (
"fmt"
"log"
)
func (c *PlannerConfig) enabled() bool { return c != nil && c.Enabled }
// resolved applies defaults; invalid values fall back with a warning.
func (c *PlannerConfig) resolved() (PlannerConfig, []string) {
out := PlannerConfig{
DefaultRangeKm: defaultPlannerRangeKm,
NewAntennaM: defaultPlannerNewAntennaM,
ExistingAntennaM: defaultPlannerExistAntenna,
MaxAreaKm: defaultPlannerMaxAreaKm,
NodeMarginKm: defaultPlannerNodeMarginKm,
MaxLegKm: defaultPlannerMaxLegKm,
UserReach: &PlannerUserReach{D50Km: defaultPlannerUserD50Km, Slope: defaultPlannerUserSlope},
}
if c == nil {
return out, nil
}
var warns []string
out.Enabled = c.Enabled
if c.DefaultRangeKm != 0 {
if plannerRangeAllowed(c.DefaultRangeKm) {
out.DefaultRangeKm = c.DefaultRangeKm
} else {
warns = append(warns, "planner.defaultRangeKm must be one of 10,15,20,30,40,50,60; using the default")
}
}
if c.NewAntennaM != 0 {
if c.NewAntennaM > 0 && c.NewAntennaM <= 100 {
out.NewAntennaM = c.NewAntennaM
} else {
warns = append(warns, "planner.newAntennaM must be within 0-100; using the default")
}
}
if c.ExistingAntennaM != 0 {
if c.ExistingAntennaM > 0 && c.ExistingAntennaM <= 100 {
out.ExistingAntennaM = c.ExistingAntennaM
} else {
warns = append(warns, "planner.existingAntennaM must be within 0-100; using the default")
}
}
out.MaxAreaKm = plannerSizeKm("maxAreaKm", c.MaxAreaKm, defaultPlannerMaxAreaKm, plannerAreaKmMin, plannerAreaKmMax, &warns)
out.NodeMarginKm = plannerSizeKm("nodeMarginKm", c.NodeMarginKm, defaultPlannerNodeMarginKm,
plannerMarginKmMin, plannerMarginKmMax, &warns)
out.MaxLegKm = plannerSizeKm("maxLegKm", c.MaxLegKm, defaultPlannerMaxLegKm, plannerLegKmMin, plannerLegKmMax, &warns)
if u := c.UserReach; u != nil {
out.UserReach.D50Km = plannerSizeKm("userReach.d50Km", u.D50Km, defaultPlannerUserD50Km,
plannerUserD50KmMin, plannerUserD50KmMax, &warns)
out.UserReach.Slope = plannerSizeKm("userReach.slope", u.Slope, defaultPlannerUserSlope,
plannerUserSlopeMin, plannerUserSlopeMax, &warns)
}
// No range above the leg limit is offered, so the default cannot be one.
if out.DefaultRangeKm > out.MaxLegKm {
r := out.rangesKm()
warns = append(warns, fmt.Sprintf("planner.defaultRangeKm %g is over planner.maxLegKm %g; using %g",
out.DefaultRangeKm, out.MaxLegKm, r[len(r)-1]))
out.DefaultRangeKm = r[len(r)-1]
}
return out, warns
}
// plannerSizeKm resolves one size limit: v when it lies within lo-hi, def
// when it is unset (0), and def with a warning otherwise (NaN included).
func plannerSizeKm(name string, v, def, lo, hi float64, warns *[]string) float64 {
switch {
case v == 0:
return def
case v >= lo && v <= hi:
return v
}
*warns = append(*warns, fmt.Sprintf("planner.%s must be within %g-%g; using the default", name, lo, hi))
return def
}
// rangesKm is the range values resolved c accepts and offers: those of
// plannerRangesKm up to MaxLegKm, since a relay leg is never longer than the
// A→B leg. The smallest range equals the smallest MaxLegKm, so it is never
// empty.
func (c PlannerConfig) rangesKm() []float64 {
n := 0
for n < len(plannerRangesKm) && plannerRangesKm[n] <= c.MaxLegKm {
n++
}
return plannerRangesKm[:n:n]
}
// tileLimits is the per-endpoint terrain tile caps for c's size limits. A
// size that is 0 counts as its default, as in resolved().
func (c PlannerConfig) tileLimits() plannerTileLimits {
or := func(v, def float64) float64 {
if v == 0 {
return def
}
return v
}
return plannerTileCaps(or(c.MaxAreaKm, defaultPlannerMaxAreaKm), or(c.NodeMarginKm, defaultPlannerNodeMarginKm),
or(c.MaxLegKm, defaultPlannerMaxLegKm))
}
func plannerRangeAllowed(km float64) bool {
for _, r := range plannerRangesKm {
if r == km {
return true
}
}
return false
}
// clientConfig is /api/config/client "planner"; nil when disabled. Radio
// defaults come from the los block (frequency, k) so both tools agree.
func (c *PlannerConfig) clientConfig(los *LOSConfig) *PlannerClientConfig {
if !c.enabled() {
return nil
}
r, _ := c.resolved()
l, _ := los.resolved()
return &PlannerClientConfig{
DefaultRangeKm: r.DefaultRangeKm,
RangesKm: r.rangesKm(),
NewAntennaM: r.NewAntennaM,
ExistingAntennaM: r.ExistingAntennaM,
FrequencyMHz: l.FrequencyMHz,
KFactor: l.KFactor,
MaxPoints: plannerMaxPoints,
MaxLegKm: r.MaxLegKm,
MaxAreaKm: r.MaxAreaKm,
NodeMarginKm: r.NodeMarginKm,
MaxSites: plannerMaxSites,
MinClearance: plannerMinClearance,
UserReach: *r.UserReach,
}
}
func logPlannerConfig(c *PlannerConfig) {
if !c.enabled() {
return
}
r, warns := c.resolved()
for _, w := range warns {
log.Printf("[planner] %s", w)
}
lim := r.tileLimits()
log.Printf("[planner] enabled (range=%.0f km, new=%.0f m, existing=%.0f m, "+
"maxArea=%g km, nodeMargin=%g km, maxLeg=%g km, userReach d50=%g km slope=%g)",
r.DefaultRangeKm, r.NewAntennaM, r.ExistingAntennaM, r.MaxAreaKm, r.NodeMarginKm, r.MaxLegKm,
r.UserReach.D50Km, r.UserReach.Slope)
log.Printf("[planner] terrain tiles per request: coverage %d, relay %d, profile %d, viewshed %d; "+
"one view takes up to %.0f MB (%.1f MB a tile)",
lim.Coverage, lim.Relay, lim.Profile, lim.Viewshed, float64(lim.max())*srtmTileBytes/1e6, float64(srtmTileBytes)/1e6)
}