IQ Voronoi (cellular noise) — F1 / F2 distance field

Math essence

For each query pixel p: snap to integer (ix, iy); for each (dx, dy) in {-1, 0, 1}^2 the neighbour cell's feature point is offset(ix + dx, iy + dy, jitter*hash). Two smallest Euclidean distances F1, F2 are kept. edge = clip(F2 - F1, 0, 1), cell_col = a + b*cos(2pi*(c*(hue(cell_id) + palette_offset) + d)). Optional in-cell rotation by t*rotate_speed animates the field.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/shader_legends_2/IQVoronoi/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


def _hash12(x: np.ndarray, y: np.ndarray) -> np.ndarray:
    """1-component hash on integer (x, y) → [0, 1). sin-based."""
    p = 127.1 * x + 311.7 * y
    return (np.sin(p) * 43758.5453123 - np.floor(np.sin(p) * 43758.5453123)).astype(np.float32)


def _hash22(x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    """2-component hash returning two [0,1) streams from one cell id."""
    a = _hash12(x, y)
    b = _hash12(x + 17.0, y + 31.0)
    return a, b


def _iq_voronoi(
    xv: np.ndarray,
    yv: np.ndarray,
    jitter: float,
    seed: int,
    rotate: float,
) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
    """Inigo Quilez's classic 2D Voronoi (cellular) noise.

    For each integer cell (ix, iy) we place one feature point at
    cell_centre + jitter*(hash-0.5).  For each query pixel we search
    the 3x3 ring of neighbour cells and keep the *two* smallest
    distances (F1, F2).  We also return the *cell id* of the winning
    point so callers can colourise per cell.
    """

    ix = np.floor(xv).astype(np.int64)
    iy = np.floor(yv).astype(np.int64)
    fx = (xv - ix).astype(np.float32)
    fy = (yv - iy).astype(np.float32)

    # Per-cell feature points are pre-hashed once so we don't pay a
    # sin() per neighbour.  We store them in arrays of shape
    # (ny_cells, nx_cells, 3 cells * 3 cells * 1 point each = 1).
    sx = int(seed * 17) & 0xFFFFF
    sy = int(seed * 31) & 0xFFFFF

    # Build cell index grids in the larger (3x3) search window
    best_d1 = np.full(xv.shape, np.inf, dtype=np.float32)
    best_d2 = np.full(xv.shape, np.inf, dtype=np.float32)
    best_id_x = np.zeros(xv.shape, dtype=np.int32)
    best_id_y = np.zeros(xv.shape, dtype=np.int32)

    cs = float(np.cos(rotate))
    sn = float(np.sin(rotate))

    # Pre-compute feature points relative to cell centres for the
    # surrounding cells we touch (3x3 ring).  We compute them inside
    # the loop using cheap integer hash, no need to materialise a
    # grid: 9 cells × 9 hash calls total — numpy is plenty fast.