Dreamscape Field (Refik Anadol — Dreams / Nature Dreams)

Math essence

Each step: v = v*drag + F(pos, t); pos += v with toroidal wrap. F is two octaves of Perlin gradient noise sampled at independent (scale, drift) parameters per octave. The canvas fades geometrically each step and agents additively splat with an HSV rainbow tied to a per-agent phase plus the shared time-drift.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/anadol_webgpu/dreamscapeField/reference.py

"""dreamscapeField — Refik Anadol inspired dream flow field.

Inspired by Refik Anadol Studio's *Dreams* series (*Nature Dreams*,
*Urban Dreams*, *Space Dreams*, the *Dreams — F* installation): a
smooth low-frequency noise field drives a global slow drift of agents,
while a high-frequency noise layer adds turbulent detail.  Agents
deposit a fading trail on the canvas — the viewer sees a fluid
"data-pigment" landscape like Anadol's GPU-accelerated fluid
simulations, but generated here with cheap numpy.

The mathematical backbone is two-octave Perlin-like gradient noise:
    F(x, y, t) = A1 * n1(x*s1 + dx(t), y*s1 + dy(t))
              +  A2 * n2(x*s2 + dx(t), y*s2 + dy(t))
where ``n1`` is a coarse 2D Perlin noise (smooth base flow) and ``n2``
is a finer noise (perturbation layer).  At each step we advance N
agents with v += F(p, t), v *= drag, p += v.

Reference:
- https://www.nvidia.com/en-us/research/ai-art-gallery/artists/refik-anadol/
  (Nature Dreams, Space Dreams — fluid-dynamics inspired work)
- https://refikanadol.com/works/coraldreams/  (Fluid Dreams algorithm)
"""
from __future__ import annotations

from typing import ClassVar

import numpy as np


def _fade(t: np.ndarray) -> np.ndarray:
    # Perlin's fade curve: 6t^5 - 15t^4 + 10t^3
    return t * t * t * (t * (t * 6 - 15) + 10)


def _perlin2(perm: np.ndarray, x: np.ndarray, y: np.ndarray) -> np.ndarray:
    """Fast 2D Perlin noise (vectorised) for arrays of (x, y) positions.

    Parameters
    ----------
    perm : (512,) array of ints in [0, 255]
        Doubled permutation table (Perlin's classic trick).
    x, y : (...) arrays of float coordinates (any shape).
    Returns
    -------
    (...) array of float values in roughly [-1, 1].
    """
    xi = np.floor(x).astype(np.int64) & 255
    yi = np.floor(y).astype(np.int64) & 255
    xf = x - np.floor(x)
    yf = y - np.floor(y)

    u = _fade(xf)
    v = _fade(yf)

    # Hash function of Perlin: choose a gradient (8 directions on 2D).
    def grad(hashval: np.ndarray, x: np.ndarray, y: np.ndarray) -> np.ndarray:
        h = hashval & 7
        # map to one of 8 directions on the unit circle
        dirs = np.array(
            [(1, 1), (1, 0), (1, -1), (0, -1), (-1, -1), (-1, 0), (-1, 1), (0, 1)],