Adding land features including lidar
This commit is contained in:
202
DESIGN.md
202
DESIGN.md
@@ -402,3 +402,205 @@ No raw `new` or `delete` anywhere in the codebase. No `malloc`/`free`.
|
||||
3.0 (a mid-range estimate). This is applied in the radar equation computation
|
||||
for Chain Home targets only, before the result is passed to the bloom/
|
||||
brightness pipeline.
|
||||
|
||||
17. **Terrain and land clutter** are rendered from pre-processed binary grids
|
||||
in `map/lidar_processed/`. The offline tool `terrain_preprocess` fuses the
|
||||
SRTM DEM, both LiDAR surveys, and the S-57 ENC into elevation, material,
|
||||
and shadow-mask grids. At runtime `TerrainMap` loads these grids once;
|
||||
`LandClutter` generates a polar clutter texture once per sweep period.
|
||||
See the TERRAIN CLUTTER VISUAL DESIGN REFERENCE section below for
|
||||
per-material appearance and speckle tuning guidance.
|
||||
|
||||
---
|
||||
|
||||
## Terrain Clutter Visual Design Reference
|
||||
|
||||
All tunable values described here have corresponding constants in
|
||||
`src/settings.h`. Edit `settings.h` to change values; this section
|
||||
explains the perceptual intent behind each constant.
|
||||
|
||||
### Purpose
|
||||
|
||||
The goal is historical authenticity. Period marine radar operators in the
|
||||
1950s saw the Bellingham shoreline as a bright, stable ring of returns that
|
||||
formed a recognizable coastline silhouette. Skilled operators mentally
|
||||
subtracted this from the display and watched only for moving or changing
|
||||
returns. That experience should be reproducible on this exhibit.
|
||||
|
||||
---
|
||||
|
||||
### Material Visual Character
|
||||
|
||||
**SOIL** (vegetated land, fields, low hills)
|
||||
|
||||
Period appearance: moderate-brightness, moderately grainy returns. The
|
||||
grain (speckle) is high because vegetation is irregular — individual trees,
|
||||
bushes, and undulations produce slightly different returns each sweep.
|
||||
The overall brightness holds steady between sweeps but the texture shimmers.
|
||||
|
||||
- σ° constant: `TERRAIN_SIGMA0_SOIL` (~0.010, −20 dB)
|
||||
- Speckle: `TERRAIN_SPECKLE_SOIL` (suggested starting value: **0.35**)
|
||||
- Appearance: mid-grey; clearly visible but not dominating. Rolling
|
||||
hillsides read as a diffuse bright edge along the coastline
|
||||
and inland ridges.
|
||||
|
||||
---
|
||||
|
||||
**ROCK** (exposed cliff faces, upper Chuckanut ridgeline, rock outcrops)
|
||||
|
||||
Period appearance: brighter than soil, less speckle. Rock faces are
|
||||
geometrically consistent so returns are stable sweep to sweep. Steep faces
|
||||
pointing toward the radar return a disproportionately strong echo.
|
||||
|
||||
- σ° constant: `TERRAIN_SIGMA0_ROCK` (~0.032, −15 dB)
|
||||
- Speckle: `TERRAIN_SPECKLE_ROCK` (suggested starting value: **0.20**)
|
||||
- Appearance: noticeably brighter than soil; Chuckanut Mountain's western
|
||||
face reads as a bright arc, stable between sweeps. Little
|
||||
shimmer — the texture is coarser and more consistent.
|
||||
|
||||
---
|
||||
|
||||
**CONCRETE** (breakwaters, piers, dock structures, Boulevard Park boardwalk,
|
||||
harbor facilities)
|
||||
|
||||
Period appearance: the strongest land returns on the scope after large steel
|
||||
vessels. Structures built over water (piers on pilings, breakwater walls)
|
||||
produce corner-reflector effects — the right-angle junction between the
|
||||
vertical face and the water surface acts as a retroreflector. Operators used
|
||||
these as navigation aids; the Bellingham harbor entrance is identifiable by
|
||||
its distinctive bright return pattern.
|
||||
|
||||
- σ° constant: `TERRAIN_SIGMA0_CONCRETE` (~0.100, −10 dB)
|
||||
- Speckle: `TERRAIN_SPECKLE_CONCRETE` (suggested starting value: **0.12**)
|
||||
- Appearance: bright, stable, low shimmer. Breakwaters and piers appear as
|
||||
sharp bright lines or arcs. The Boulevard Park boardwalk over
|
||||
the water appears as a bright thin arc. These features should
|
||||
be the most prominent land returns on the scope after large
|
||||
steel ships.
|
||||
|
||||
---
|
||||
|
||||
**WATER — CALM** (open bay, light wind)
|
||||
|
||||
Period appearance: very weak, near-invisible. Calm water reflects most radar
|
||||
energy away from the antenna (specular reflection). Operators saw a nearly
|
||||
blank area over open water even at high gain.
|
||||
|
||||
- σ° constant: `TERRAIN_SIGMA0_WATER_CALM` (~0.0003, −35 dB)
|
||||
- Appearance: at normal gain, essentially black. Only visible at extreme
|
||||
gain settings as a faint salt-and-pepper noise floor.
|
||||
|
||||
---
|
||||
|
||||
**WATER — ROUGH** (choppy bay, wind >10 knots)
|
||||
|
||||
Period appearance: a low-level fuzzy return rising from the noise floor,
|
||||
affecting the inner ranges most strongly. Sea clutter was a major nuisance
|
||||
on small-vessel marine radar. The wave clutter filter (keys 5/6) suppresses
|
||||
this.
|
||||
|
||||
- σ° constant: `TERRAIN_SIGMA0_WATER_ROUGH` (~0.010, −20 dB)
|
||||
- Appearance: at normal gain, a hazy shimmer at short ranges that fades
|
||||
outward. Heavy speckle — random wave facets scatter
|
||||
incoherently. The wave clutter filter reduces this.
|
||||
|
||||
---
|
||||
|
||||
### Speckle / Grain Tuning Guide
|
||||
|
||||
Speckle simulates pulse-to-pulse amplitude variation caused by incoherent
|
||||
scattering from irregular surfaces. Implemented as a per-cell random
|
||||
fraction multiplied by the computed P_r each sweep:
|
||||
|
||||
```
|
||||
Speckle = P_r × (1.0 + TERRAIN_SPECKLE_xxx × random(−1, +1))
|
||||
```
|
||||
|
||||
Values close to 0.0 give stable, solid returns (correct for concrete and
|
||||
large flat surfaces). Values closer to 0.5 give vigorous shimmer (correct
|
||||
for vegetation and choppy water). Values above 0.5 are unrealistically noisy
|
||||
for terrain — avoid unless simulating a very rough or complex surface.
|
||||
|
||||
Suggested starting values:
|
||||
|
||||
| Constant | Value | Character |
|
||||
|-----------------------------|-------|-----------------------------------------|
|
||||
| `TERRAIN_SPECKLE_SOIL` | 0.35 | visible shimmer, naturalistic |
|
||||
| `TERRAIN_SPECKLE_ROCK` | 0.20 | moderate, stable with some texture |
|
||||
| `TERRAIN_SPECKLE_CONCRETE` | 0.12 | mostly stable; slight flicker from edge |
|
||||
|
||||
**Tuning procedure:**
|
||||
1. Set max range to 6 miles on the Marine PPI.
|
||||
2. Rotate to a bearing showing the Bellingham breakwater and open bay.
|
||||
3. Adjust `TERRAIN_MARINE_CLUTTER_BRIGHTNESS` until the breakwater return
|
||||
is clearly bright but does not wash out nearby ship targets.
|
||||
4. Adjust `TERRAIN_SIGMA0_CONCRETE` if breakwater brightness relative to
|
||||
soil hills looks wrong.
|
||||
5. Adjust speckle values until soil hillsides shimmer naturally and concrete
|
||||
structures hold steady between sweeps.
|
||||
6. Verify at all three marine range settings (2, 4, 6 miles) that clutter
|
||||
does not overwhelm vessel targets at any range.
|
||||
|
||||
---
|
||||
|
||||
### Overall Brightness Balance
|
||||
|
||||
The most important perceptual tuning parameter is
|
||||
`TERRAIN_MARINE_CLUTTER_BRIGHTNESS`. It is a linear scale factor applied to
|
||||
all terrain return brightness before the clutter texture is uploaded to the
|
||||
GPU. It does not change the relative balance between materials — it scales
|
||||
all terrain uniformly.
|
||||
|
||||
**Target appearance goal:**
|
||||
- A steel AIS vessel at 3 miles range should be 2–3× brighter than the
|
||||
strongest adjacent land clutter return (a concrete breakwater).
|
||||
- The coastline silhouette should be clearly readable as geography — a
|
||||
visitor who knows Bellingham Bay should recognize the shape.
|
||||
- Open water should be visually clean at default gain settings.
|
||||
|
||||
Suggested starting value: `TERRAIN_MARINE_CLUTTER_BRIGHTNESS = 0.55`
|
||||
|
||||
**ATC PPI:** `ATC_TERRAIN_CLUTTER_SUPPRESSED = true` means land clutter is
|
||||
hidden by MTI cancellation — no brightness tuning needed for ATC. If
|
||||
suppression is disabled for debugging, use `TERRAIN_MARINE_CLUTTER_BRIGHTNESS`
|
||||
as a guide.
|
||||
|
||||
---
|
||||
|
||||
### Shadow Zones
|
||||
|
||||
Shadow zones are the most dramatic visual effect on the Marine PPI. They
|
||||
appear as dark wedge-shaped gaps in the land clutter pattern, pointing
|
||||
outward from the radar, behind ridgelines and hills.
|
||||
|
||||
Key shadow features visible from the marine bay platform:
|
||||
- **Chuckanut Mountain** (southwest) casts a prominent shadow into the
|
||||
southern bay and beyond.
|
||||
- **Lummi Island** (northwest) shadows a sector of the northern bay.
|
||||
- **Bellingham waterfront bluff** shadows part of the inner harbor.
|
||||
|
||||
These shadows are inherently dark against surrounding clutter — no tuning
|
||||
required. Shadow = zero amplitude, computed geometrically by the preprocessor.
|
||||
|
||||
For the ATC scope with `ATC_TERRAIN_SHADOW_ENABLED = true`, shadows affect
|
||||
aircraft returns only (not the display background, which is suppressed). An
|
||||
aircraft descending behind Chuckanut Mountain will fade out and reappear as
|
||||
it clears the ridge on final approach — authentic behavior of period ASR radar.
|
||||
|
||||
---
|
||||
|
||||
### Polar Clutter Texture Resolution
|
||||
|
||||
`TERRAIN_POLAR_BEARING_BINS` and `TERRAIN_POLAR_RANGE_BINS` control the
|
||||
resolution of the GPU texture carrying terrain clutter to the shader.
|
||||
Recommended values:
|
||||
|
||||
| Scope | Bearing bins | Range bins | Notes |
|
||||
|---------------------|-------------|------------|------------------------------|
|
||||
| Marine PPI (6 mi) | 720 | 512 | 0.5° matches marine beamwidth|
|
||||
| ATC PPI (20 mi) | 720 | 1024 | wider range needs more bins |
|
||||
|
||||
The texture is regenerated once per sweep period (every 4–5 seconds), not
|
||||
every frame. Upload cost is not time-critical. Reducing to 360 bearing bins
|
||||
is acceptable and halves the texture upload cost at the expense of slightly
|
||||
blocky angular transitions near prominent features.
|
||||
|
||||
Reference in New Issue
Block a user