pyworldgen 0.1.0__py3-none-any.whl

pyworldgen/__init__.py

@@ -0,0 +1,73 @@
+"""pyworldgen -- a unified procedural biome-generation library.
+
+It brings three previously separate code bases under one roof:
+
+* a chunked voxel *world* with a generation-pass framework (was ``procgen3d``);
+* pure-function *biome* generators -- caves, forests, landscapes (was
+  ``biomegen_lab``);
+* the streamed implicit *cave* with its cross-language hash.
+
+The unification rests on three shared ideas:
+
+1. **One deterministic, cross-language hash** (:mod:`pyworldgen.core.hash`)
+   drives every generator, so a world is reproducible from a seed on any
+   backend. This replaces three duplicated hash implementations (one of which
+   had a latent ``int64`` overflow).
+2. **A field abstraction** (:mod:`pyworldgen.fields`): a biome can be a pure
+   ``is_solid(x, y, z)`` function, and the same function can *fill chunks* in
+   the array-backed world -- so a streamed cave is meshed, saved and streamed
+   like hand-authored terrain.
+3. **Compact source, heavy views**: seeds/params/graphs are the source of
+   truth; meshes, point clouds and saved chunks are regenerable views.
+
+Quick start::
+
+    import pyworldgen as bf
+    bf.list_generators()
+    forest = bf.generate("forest", seed="grenoble", target_tree_count=60)
+    cave   = bf.generate("implicit_cave", seed="luxembourg", length=90.0)
+"""
+
+from . import (
+    biomes,
+    compose,
+    core,
+    fields,
+    generation,
+    io,
+    mesh,
+    noise,
+    pointcloud,
+    rendering,
+    roads,
+    runtime,
+    spatial,
+    voxel,
+    world,
+)
+from .registry import generate, get_info, list_generators, register
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "core",
+    "spatial",
+    "fields",
+    "voxel",
+    "world",
+    "mesh",
+    "noise",
+    "generation",
+    "runtime",
+    "biomes",
+    "pointcloud",
+    "rendering",
+    "roads",
+    "compose",
+    "io",
+    "generate",
+    "list_generators",
+    "get_info",
+    "register",
+    "__version__",
+]

pyworldgen/biomes/__init__.py

@@ -0,0 +1,60 @@
+"""Biome generators, all built on the shared core hash / field abstraction."""
+
+from .cave import (
+    CaveParams,
+    DenseVoxelVolume,
+    FusedCaveField,
+    ImplicitCave,
+    corridor_world_point,
+    sample_cave,
+)
+from .flat import FlatTerrain, FlatTerrainParams, flat_terrain_stats, generate_flat
+from .forest import (
+    ForestParams,
+    ForestWorld,
+    TreeGraph,
+    TreeSite,
+    forest_stats,
+    generate_forest,
+    validate_forest,
+)
+from .landscape import (
+    LandscapeParams,
+    LandscapeWorld,
+    Pond,
+    RiverSegment,
+    generate_landscape,
+    generate_river_network,
+    landscape_stats,
+)
+
+__all__ = [
+    # cave
+    "CaveParams",
+    "FusedCaveField",
+    "ImplicitCave",
+    "DenseVoxelVolume",
+    "sample_cave",
+    "corridor_world_point",
+    # flat terrain
+    "FlatTerrain",
+    "FlatTerrainParams",
+    "generate_flat",
+    "flat_terrain_stats",
+    # forest
+    "ForestParams",
+    "ForestWorld",
+    "TreeSite",
+    "TreeGraph",
+    "generate_forest",
+    "forest_stats",
+    "validate_forest",
+    # landscape
+    "LandscapeParams",
+    "LandscapeWorld",
+    "RiverSegment",
+    "Pond",
+    "generate_landscape",
+    "generate_river_network",
+    "landscape_stats",
+]

pyworldgen/biomes/cave.py

@@ -0,0 +1,353 @@
+"""Implicit streamed cave -- a pure function of position, no stored grid.
+
+Ported from the original ``cavegen`` field but re-based on the unified
+:mod:`pyworldgen.core.hash`, so it is bit-reproducible across Python / JS / GLSL
+and composes with the chunked world through :class:`~pyworldgen.fields`.
+
+Openness is the union (``max``) of three constructive fields, then a
+noise-perturbed wall and optional speleothems:
+
+1. **Corridor** -- a guaranteed, always-open wandering tube whose centreline
+   ``(corrX(z), corrY(z))`` depends only on the tunnel coordinate ``z``. Its
+   openness is strictly positive along the axis, so the whole (unbounded)
+   length stays navigable no matter how the other fields are tuned.
+2. **Worms** -- thin branching tunnels where two independent ridged fBm fields
+   are simultaneously near zero.
+3. **Caverns** -- rare low-frequency "cheese" rooms.
+4. **Wall** -- rock where openness ``<= ROUGH * signedNoise``, undulating the
+   surface instead of leaving a clean isosurface.
+5. **Speleothems** -- Worley-style stalactite/stalagmite cones inside the corridor.
+
+Coordinate bridge (spec vs world):
+
+* spec ``x`` = lateral (centred on 0), ``y`` = up, ``z`` = tunnel distance.
+* world (Z-up chunk world): ``spec_x = wx - XB``, ``spec_y = wz``, ``spec_z = wy``.
+
+:class:`ImplicitCave` applies that bridge so ``is_solid(wx, wy, wz)`` is a valid
+world-space :class:`SolidField3D` and can drive a chunk pass directly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field as dataclass_field
+from typing import Any
+
+import numpy as np
+
+from ..core.hash import fbm3, hashf, ridged_fbm3, seed_to_int, signed_fbm3
+
+
+@dataclass
+class CaveParams:
+    seed: int = 0
+
+    # Physical bounds in spec coordinates.
+    FLOOR: float = 0.0
+    CEIL: float = 54.0
+    XB: float = 58.0
+    CY0: float = 27.0
+
+    # Guaranteed main corridor.
+    CORR_R: float = 7.5
+    CORR_ROUGH: float = 3.5
+    CORR_X_FREQ: float = 0.016
+    CORR_X_AMP: float = 18.0
+    CORR_X_NOISE_FREQ: float = 0.010
+    CORR_X_NOISE_AMP: float = 12.0
+    CORR_Y_FREQ: float = 0.024
+    CORR_Y_AMP: float = 5.0
+    CORR_Y_NOISE_FREQ: float = 0.013
+    CORR_Y_NOISE_AMP: float = 4.0
+
+    # Ridged dual-fBm worm tunnels.
+    FW: float = 0.05
+    WORM_T: float = 0.085
+    WSCALE: float = 26.0
+
+    # Low-frequency caverns.
+    FC: float = 0.022
+    CAV_T: float = 0.60
+    CSCALE: float = 34.0
+
+    # Wall roughening.
+    ROUGH: float = 2.2
+    RFREQ: float = 0.13
+
+    # Speleothems.
+    SPELEO: bool = True
+    SPELEO_CELL: float = 6.0
+    SPELEO_SPAWN: float = 0.20
+
+    @classmethod
+    def from_seed(cls, seed: int | str, **overrides: Any) -> "CaveParams":
+        p = cls(seed=seed_to_int(seed))
+        for key, value in (overrides or {}).items():
+            if not hasattr(p, key):
+                raise KeyError(f"Unknown CaveParams field: {key}")
+            setattr(p, key, value)
+        return p
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+class FusedCaveField:
+    """Pure cave field in spec coordinates. ``density > 0`` means air."""
+
+    def __init__(self, params: CaveParams):
+        self.p = params
+
+    def corr_x(self, z):
+        p = self.p
+        return (
+            np.sin(z * p.CORR_X_FREQ) * p.CORR_X_AMP
+            + signed_fbm3(z * p.CORR_X_NOISE_FREQ, 5.2, 1.7, 2, p.seed + 11)
+            * p.CORR_X_NOISE_AMP
+        )
+
+    def corr_y(self, z):
+        p = self.p
+        y = (
+            p.CY0
+            + np.sin(z * p.CORR_Y_FREQ + 1.3) * p.CORR_Y_AMP
+            + signed_fbm3(z * p.CORR_Y_NOISE_FREQ, 9.1, 4.4, 2, p.seed + 17)
+            * p.CORR_Y_NOISE_AMP
+        )
+        return np.clip(y, p.FLOOR + p.CORR_R + 3.0, p.CEIL - p.CORR_R - 3.0)
+
+    def components(self, x, y, z) -> dict[str, np.ndarray]:
+        p = self.p
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64)
+        z = np.asarray(z, dtype=np.float64)
+
+        cx = self.corr_x(z)
+        cy = self.corr_y(z)
+        dist = np.hypot(x - cx, y - cy)
+
+        rad = p.CORR_R + p.CORR_ROUGH * signed_fbm3(
+            x * 0.05, y * 0.05, z * 0.05, 2, p.seed + 23
+        )
+        corridor = rad - dist
+
+        n1 = ridged_fbm3(x * p.FW, y * p.FW, z * p.FW, 3, p.seed + 31)
+        n2 = ridged_fbm3(
+            (x + 131.0) * p.FW, (y + 57.0) * p.FW, (z + 89.0) * p.FW, 3, p.seed + 37
+        )
+        worm = (p.WORM_T - np.maximum(n1, n2)) * p.WSCALE
+
+        cavern = (
+            fbm3(x * p.FC + 90.0, y * p.FC + 40.0, z * p.FC + 10.0, 2, p.seed + 41)
+            - p.CAV_T
+        ) * p.CSCALE
+        rough = p.ROUGH * signed_fbm3(
+            x * p.RFREQ, y * p.RFREQ, z * p.RFREQ, 2, p.seed + 43
+        )
+
+        return {
+            "center_x": cx,
+            "center_y": cy,
+            "radius": rad,
+            "dist_to_corridor": dist,
+            "corridor": corridor,
+            "worm": worm,
+            "cavern": cavern,
+            "rough": rough,
+        }
+
+    def density(self, x, y, z, *, include_speleothems: bool = True):
+        p = self.p
+        comp = self.components(x, y, z)
+        openness = np.maximum.reduce([comp["corridor"], comp["worm"], comp["cavern"]])
+        density = openness - comp["rough"]
+
+        y = np.asarray(y, dtype=np.float64)
+        x = np.asarray(x, dtype=np.float64)
+        hard_shell = (y <= p.FLOOR) | (y >= p.CEIL) | (x <= -p.XB) | (x >= p.XB)
+        density = np.where(hard_shell, -1.0, density)
+
+        if include_speleothems and p.SPELEO:
+            spikes = self.speleothem_mask(x, y, z, comp)
+            density = np.where(spikes & (density > 0), -1.0, density)
+        return density
+
+    def speleothem_mask(self, x, y, z, comp):
+        p = self.p
+        S = float(p.SPELEO_CELL)
+        x = np.asarray(x, dtype=np.float64)
+        y = np.asarray(y, dtype=np.float64)
+        z = np.asarray(z, dtype=np.float64)
+
+        gi = np.floor(x / S).astype(np.int64)
+        gk = np.floor(z / S).astype(np.int64)
+        hit = np.zeros(np.broadcast(x, y, z).shape, dtype=bool)
+
+        for dgi in (-1, 0):
+            for dgk in (-1, 0):
+                ci = gi + dgi
+                ck = gk + dgk
+                spawn = hashf(ci, ck, 3, seed=p.seed + 51) < p.SPELEO_SPAWN
+                sx = ci * S + hashf(ci, ck, 7, seed=p.seed + 53) * S
+                sz = ck * S + hashf(ci, ck, 1, seed=p.seed + 59) * S
+                da = np.hypot(x - sx, z - sz)
+
+                rad = comp["radius"]
+                cy = comp["center_y"]
+                h = 3.0 + hashf(ci, ck, 5, seed=p.seed + 61) * (rad * 0.85)
+                r_base = 0.6 + hashf(ci, ck, 9, seed=p.seed + 67) * 1.3
+                floor_y = cy - rad
+                ceil_y = cy + rad
+                is_stalactite = hashf(ci, ck, 4, seed=p.seed + 71) > 0.5
+
+                tip = ceil_y - h
+                cone_top = (
+                    (y <= ceil_y)
+                    & (y >= tip)
+                    & (da < r_base * (1.0 - (ceil_y - y) / np.maximum(h, 1e-6)))
+                )
+                top = floor_y + h
+                cone_bottom = (
+                    (y >= floor_y)
+                    & (y <= top)
+                    & (da < r_base * (1.0 - (y - floor_y) / np.maximum(h, 1e-6)))
+                )
+                hit |= spawn & np.where(is_stalactite, cone_top, cone_bottom)
+
+        near_corridor = comp["dist_to_corridor"] < comp["radius"] * 1.4
+        return hit & near_corridor
+
+
+class ImplicitCave:
+    """World-space :class:`SolidField3D` wrapping :class:`FusedCaveField`.
+
+    Applies the spec<->world coordinate bridge so the cave can fill chunks:
+    world axis 0 = lateral, axis 1 = tunnel, axis 2 = up.
+    """
+
+    def __init__(self, params: CaveParams):
+        self.params = params
+        self.field = FusedCaveField(params)
+
+    @classmethod
+    def from_seed(cls, seed: int | str, **overrides: Any) -> "ImplicitCave":
+        return cls(CaveParams.from_seed(seed, **overrides))
+
+    def density_world(self, wx, wy, wz):
+        p = self.params
+        spec_x = np.asarray(wx, dtype=np.float64) - p.XB
+        spec_y = np.asarray(wz, dtype=np.float64)
+        spec_z = np.asarray(wy, dtype=np.float64)
+        return self.field.density(spec_x, spec_y, spec_z)
+
+    def is_solid(self, wx, wy, wz):
+        return self.density_world(wx, wy, wz) <= 0.0
+
+
+@dataclass
+class DenseVoxelVolume:
+    """A finite sampled cave volume. ``occ=True`` is solid, ``occ=False`` is air.
+
+    Axis convention: axis 0 = lateral, axis 1 = tunnel, axis 2 = up (matches the
+    chunked world). This is a lightweight replacement for the original heavy
+    ``VoxelWorld``; it keeps just what the tests and exporters need.
+    """
+
+    occ: np.ndarray
+    resolution: float
+    name: str = "cave"
+    metadata: dict[str, Any] = dataclass_field(default_factory=dict)
+
+    @property
+    def shape(self):
+        return self.occ.shape
+
+    @property
+    def extent(self):
+        return np.asarray(self.occ.shape, dtype=float) * float(self.resolution)
+
+    def solid_fraction(self) -> float:
+        return float(self.occ.mean())
+
+    def surface_points(
+        self, max_points: int | None = 80_000, seed: int = 0
+    ) -> np.ndarray:
+        occ = self.occ
+        free = ~occ
+        exposed = np.zeros_like(occ)
+        exposed[1:, :, :] |= occ[1:, :, :] & free[:-1, :, :]
+        exposed[:-1, :, :] |= occ[:-1, :, :] & free[1:, :, :]
+        exposed[:, 1:, :] |= occ[:, 1:, :] & free[:, :-1, :]
+        exposed[:, :-1, :] |= occ[:, :-1, :] & free[:, 1:, :]
+        exposed[:, :, 1:] |= occ[:, :, 1:] & free[:, :, :-1]
+        exposed[:, :, :-1] |= occ[:, :, :-1] & free[:, :, 1:]
+        idx = np.argwhere(exposed)
+        pts = ((idx + 0.5) * self.resolution).astype(np.float32)
+        if max_points is not None and len(pts) > max_points:
+            rng = np.random.default_rng(seed)
+            pts = pts[rng.choice(len(pts), size=max_points, replace=False)]
+        return pts
+
+    def is_collision(self, world_point, radius: float = 0.5) -> bool:
+        p = np.asarray(world_point, dtype=float)
+        if np.any(p < 0.0) or np.any(p >= self.extent):
+            return True
+        cell = np.clip(
+            np.floor(p / self.resolution).astype(int), 0, np.asarray(self.shape) - 1
+        )
+        return bool(self.occ[cell[0], cell[1], cell[2]])
+
+
+def sample_cave(
+    *,
+    seed: int | str = "cave",
+    resolution: float = 1.5,
+    length: float = 110.0,
+    params: dict | None = None,
+) -> DenseVoxelVolume:
+    """Sample the implicit cave into a finite :class:`DenseVoxelVolume`.
+
+    The volume spans the full lateral/vertical bounds and *length* along the
+    tunnel. The guaranteed corridor ensures both air and rock always exist.
+    """
+    p = CaveParams.from_seed(seed, **(params or {}))
+    field = FusedCaveField(p)
+    res = float(resolution)
+    nx = int(round(2.0 * p.XB / res))
+    ny = int(round(float(length) / res))
+    nz = int(round(p.CEIL / res))
+
+    sx = (np.arange(nx) + 0.5) * res - p.XB
+    su = (np.arange(nz) + 0.5) * res
+    SX, SU = np.meshgrid(sx, su, indexing="ij")
+
+    occ = np.zeros((nx, ny, nz), dtype=bool)
+    for iy in range(ny):
+        tunnel_m = (iy + 0.5) * res
+        density = field.density(SX, SU, np.full_like(SX, tunnel_m))
+        occ[:, iy, :] = density <= 0.0
+
+    # Enclosure.
+    occ[0, :, :] = occ[-1, :, :] = True
+    occ[:, :, 0] = occ[:, :, -1] = True
+
+    return DenseVoxelVolume(
+        occ=occ,
+        resolution=res,
+        name="implicit_cave",
+        metadata={
+            "type": "implicit_cave",
+            "seed": p.seed,
+            "length": float(length),
+            "params": p.to_dict(),
+        },
+    )
+
+
+def corridor_world_point(params: CaveParams, tunnel_m: float) -> np.ndarray:
+    """Point on the guaranteed corridor centreline, in world coordinates."""
+    field = FusedCaveField(params)
+    z = np.array([float(tunnel_m)])
+    cx = float(field.corr_x(z)[0])
+    cy = float(field.corr_y(z)[0])
+    # world: lateral = spec_x + XB, tunnel = spec_z, up = spec_y
+    return np.array([cx + params.XB, float(tunnel_m), cy], dtype=float)

pyworldgen/biomes/flat.py

@@ -0,0 +1,110 @@
+"""Flat (default) terrain.
+
+The simplest terrain: a heightfield that is perfectly flat by default, with
+optional gentle tilt and undulation. It exposes the same ``height`` / ``x`` /
+``y`` / ``resolution`` interface as :class:`~pyworldgen.biomes.landscape.LandscapeWorld`,
+so anything that consumes a terrain -- the road generator, the terrain mesher,
+and (next) biome composition -- works on it unchanged.
+
+Defaults produce a genuinely flat plane (``undulation_amp = 0``, no tilt); it is
+meant as a neutral base to lay roads on and to blend biomes over.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import numpy as np
+
+from ..core.hash import seed_to_int, signed_fbm2
+
+
+@dataclass
+class FlatTerrainParams:
+    seed: int = 0
+    domain_size: tuple[float, float] = (120.0, 120.0)
+    resolution: float = 2.0
+    base_height: float = 8.0
+    slope_x: float = 0.0  # linear tilt per metre in x
+    slope_y: float = 0.0  # linear tilt per metre in y
+    undulation_amp: float = 0.0  # 0 -> perfectly flat
+    undulation_scale: float = 0.03
+
+    @classmethod
+    def from_seed(cls, seed: int | str, **overrides: Any) -> "FlatTerrainParams":
+        p = cls(seed=seed_to_int(seed))
+        for k, v in (overrides or {}).items():
+            if not hasattr(p, k):
+                raise KeyError(f"Unknown FlatTerrainParams field: {k}")
+            setattr(p, k, v)
+        return p
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["domain_size"] = list(self.domain_size)
+        return d
+
+
+@dataclass
+class FlatTerrain:
+    height: np.ndarray
+    water_depth: np.ndarray
+    x: np.ndarray
+    y: np.ndarray
+    resolution: float
+    domain_size: tuple[float, float]
+    name: str = "flat"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def shape(self):
+        return self.height.shape
+
+    @property
+    def water_surface(self):
+        return self.height + self.water_depth
+
+
+def generate_flat(
+    *, seed: int | str = "flat", params: dict | None = None
+) -> FlatTerrain:
+    p = FlatTerrainParams.from_seed(seed, **(params or {}))
+    W, H = p.domain_size
+    nx = int(round(W / p.resolution))
+    ny = int(round(H / p.resolution))
+    x = (np.arange(nx) + 0.5) * p.resolution
+    y = (np.arange(ny) + 0.5) * p.resolution
+    X, Y = np.meshgrid(x, y, indexing="xy")
+
+    height = np.full((ny, nx), float(p.base_height), dtype=np.float64)
+    if p.slope_x or p.slope_y:
+        height += p.slope_x * X + p.slope_y * Y
+    if p.undulation_amp:
+        height += p.undulation_amp * signed_fbm2(
+            X * p.undulation_scale, Y * p.undulation_scale, 4, p.seed + 7
+        )
+
+    return FlatTerrain(
+        height=height.astype(np.float32),
+        water_depth=np.zeros((ny, nx), dtype=np.float32),
+        x=x.astype(np.float32),
+        y=y.astype(np.float32),
+        resolution=float(p.resolution),
+        domain_size=(float(W), float(H)),
+        metadata={"type": "flat_terrain", "seed": p.seed, "params": p.to_dict()},
+    )
+
+
+def flat_terrain_stats(terrain: FlatTerrain) -> dict[str, Any]:
+    h = np.asarray(terrain.height)
+    return {
+        "type": terrain.metadata.get("type", "flat_terrain"),
+        "shape": list(terrain.shape),
+        "resolution": float(terrain.resolution),
+        "domain_size": [float(v) for v in terrain.domain_size],
+        "height_min": float(h.min()),
+        "height_max": float(h.max()),
+        "height_mean": float(h.mean()),
+        "is_flat": bool(np.ptp(h) < 1e-6),
+    }