Metadata-Version: 2.4
Name: pyworldgen
Version: 0.1.6
Summary: Deterministic procedural world generation: biomes, noise, roads, and smooth multi-biome composition.
Author-email: YOUR NAME <you@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YOUR-GH-USER/pyworldgen
Project-URL: Repository, https://github.com/YOUR-GH-USER/pyworldgen
Project-URL: Issues, https://github.com/YOUR-GH-USER/pyworldgen/issues
Project-URL: Changelog, https://github.com/YOUR-GH-USER/pyworldgen/blob/main/CHANGELOG.md
Keywords: procedural-generation,worldgen,noise,perlin,simplex,terrain,voxel,biomes
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: pillow>=9.0
Requires-Dist: imageio>=2.0
Provides-Extra: render
Requires-Dist: pyvista>=0.43; extra == "render"
Provides-Extra: fps
Requires-Dist: fpsample>=1.0; extra == "fps"
Provides-Extra: viz
Requires-Dist: scikit-image>=0.20; extra == "viz"
Provides-Extra: geometry
Requires-Dist: shapely>=2; extra == "geometry"
Requires-Dist: trimesh>=4; extra == "geometry"
Requires-Dist: mapbox-earcut>=1; extra == "geometry"
Provides-Extra: all
Requires-Dist: pyworldgen[fps,geometry,render,viz]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: opensimplex>=0.4; extra == "dev"

# pyworldgen

A unified, deterministic procedural biome-generation library. A seed plus
parameters *is* the world — voxel grids, meshes, point clouds and saved chunks
are all regenerable views of that compact source.

## What's in it

- **Biomes** — implicit caves, Voronoi forests, river landscapes, and a
  neutral flat terrain.
- **Composition** — blend several biomes into one coherent world with smooth
  transitions.
- **Roads** — weighted anisotropic least-cost paths (Galin et al. 2010) over
  any terrain, with bridges and terrain grading.
- **Chunked voxel world** — block storage, generation-pass scheduler,
  streaming, deferred edits, sunlight.
- **Geometry views** — voxel meshers, surface point-cloud sampling with
  farthest-point downsampling, OBJ / MagicaVoxel `.vox` / PLY / XYZ export.
- **Rendering** — pure-numpy pinhole camera and software renderer, plus
  PyVista and matplotlib backends, with PNG / GIF / MP4 output.
- **Spatial toolkit** — spatial hash grid, BVH, KD-tree, R-tree, quad/octree,
  voxel DDA, graph + Dijkstra, farthest point sampling.

Everything shares one cross-language deterministic hash, so the same seed
reproduces the same world bit-for-bit across Python, JavaScript and GLSL.

## Quick start

```python
import pyworldgen as bf

bf.list_generators()
# ['composite', 'flat', 'forest', 'implicit_cave', 'landscape', 'roads']

forest = bf.generate("forest",        seed="grenoble",   target_tree_count=60)
cave   = bf.generate("implicit_cave", seed="luxembourg", length=90.0)
land   = bf.generate("landscape",     seed="rhine")
world  = bf.generate("composite",     seed="atlas")
```

Export a biome as voxels, mesh, and a downsampled point cloud:

```python
from pyworldgen.mesh import volume_to_mesh
from pyworldgen.pointcloud import sample_mesh_surface
from pyworldgen.io import volume_to_vox, mesh_to_obj, write_ply

volume_to_vox("cave.vox", cave)
mesh = volume_to_mesh(cave)
mesh_to_obj("cave.obj", mesh)

cloud = sample_mesh_surface(mesh, 40_000, seed=1)
write_ply("cave_points.ply", cloud.farthest_point_downsample(4_096))
```

Render a turntable fly-through:

```python
import pyworldgen.rendering as rr

frames = rr.render_turntable(cloud, n_frames=48, elevation=18)
rr.save_gif(frames, "cave_orbit.gif", fps=20)
```

## Installation

```bash
pip install -e .          # runtime
pip install -e ".[dev]"   # + pytest
```

Runtime dependencies: `numpy`, `scipy`, `fpsample`, `matplotlib`, `pillow`,
`imageio`, `pyvista`. Optional extras: `[viz]` (`scikit-image`) and
`[geometry]` (`shapely`, `trimesh`, `mapbox-earcut`).

## Visualization scripts

```bash
python scripts/visualize_all.py --quick --out sample_visualizations
python scripts/render_biome.py composite --seed atlas --quick
```

## Where to look next

- `algo_specs/` — per-biome algorithm specs (cave, landscape, tree, flat).
- `CITATIONS.md` — paper-level references per source file.
- Module docstrings (`pyworldgen.biomes.*`, `pyworldgen.roads`,
  `pyworldgen.compose`, `pyworldgen.noise`, …) — the authoritative
  description of each layer, including scope and honest gaps versus the
  cited papers.
- `tests/` — invariants and reproducibility checks worth reading as usage
  examples.
