Notes

# RangeBlends 3D

The RangeBlends world as Taichi kernels, and a valley you can fly around.

The same world as the browser and as `~/pytools/rangeblends.py` — which is not
a claim, it is checked: `check.py` compares heights cell by cell.

## Running it

```
~/taichi-env/bin/python view3d.py
~/taichi-env/bin/python view3d.py --seed heron --g 40000 --nx 768 --nz 512
~/taichi-env/bin/python view3d.py --turntable out/ --frames 36     # headless
```

`--hour 0.29` is Sundial's dawn. `--massif`, `--vscale`, `--elev`, `--fog`,
`--no-towns` all do what they say.

## The environment

Taichi has no wheel for Python 3.14, which is what `~/.spenv` is. So:

- `~/opt/python312` — a standalone CPython 3.12.14, extracted, no root, and it
  touches neither the system Python nor `~/.spenv`
- `~/taichi-env` — the venv, with taichi 1.7.4 and numpy

All four backends work on this machine, CUDA included:

```
cuda -> running on cuda      opengl -> running on opengl
vulkan -> running on vulkan  cpu    -> running on x64
```

## Speed

```
  256 x  192  =     49,152 columns    209 ms   (first call, JIT)
 1024 x  768  =    786,432 columns      4 ms
 2048 x 1536  =  3,145,728 columns     12 ms
```

3.1 million columns in 12 ms. The browser does 2,666 per frame. Rendering
393,216 columns as 783,874 triangles runs at over 100 fps on the 3070.

## It is the same world

```
integer hash          MATCH
stream_of()           MATCH
heights massif=0.00   1536/1536 identical   max difference 0
heights massif=0.45   1535/1536 identical   max difference 1
```

The one cell is f32 against f64 at a block boundary, and is stated rather than
rounded away.

**The check earned its keep immediately.** The first version accepted `massif`
and silently ignored it — 13.7% agreement, max difference 21 blocks.
`square_ramp` needs 96-bit integers, which a GPU does not have. But it is a
function of (peak, scale) rather than of column, and a window holds few peaks,
so the host computes the exact values with Python ints and hands over a small
table. The world stays the world; only the arithmetic moved.

## Notes

- **The terracing is the data, not a style.** Heights are integers, so the
  surface comes out banded, and it reads as sedimentary strata. Snow is a
  height threshold, so the terraces expose it in bands up the slopes.
- **Fog is recomputed every frame**, because it follows the eye rather than the
  ground. Taichi's scene has none; without it the far edge of the mesh stops
  dead against the background and reads as a wall rather than a distance.
- **The settlements are the run law.** A hut wherever v2(g+1) reaches 4, a
  cottage at 7, a farmstead at 10, a hall at 13. The law says where along the
  river; the ground says exactly where, by taking the first dry shelf out from
  the channel.

## drone.py — the one to run

```
~/taichi-env/bin/python drone.py
```

A slow orbit and a slow drift downstream, with the controls to hand: hour,
massif, trees, haze, tributaries, spin, drift, camera height and distance.
Sundial's hour drives the light. **fly** / **hold still** and **somewhere
else** do what they say.

Three things it adds over `view3d.py`:

**Trees are geometry.** A sphere reads as a bobble sitting on the ground; a
four-sided cone reads as a tree, because at this distance the silhouette is the
whole of what you see. Six triangles each, so twenty thousand of them is
nothing next to the terrain.

**Water is coloured by its depth.** The surface stays flat, because a river IS
flat on top — but a single blue read as painted lino. Turquoise over sand at
the edges going dark where the channel is deep, so the deep channel shows as a
ribbon inside the shallows. One line of depth, and it does more than any
amount of shine.

**The drainage network is cut into the ground.** The tributaries the Rivers
page draws in two dimensions, brought down onto the terrain as real cuts, with
order setting depth and width — so an order-1 headwater is a scratch and an
order-6 branch is a gorge, in the 2:1 proportion the ruler gives.

## Still to do

- A real sky, rather than a background colour matched to the fog
- Trees that thin out at a treeline rather than stopping at a height
- Settlements as buildings rather than markers
- Water that moves, the way The Riverbank's does