symbios-tensor

Tensor-field-driven procedural urban layout generator for terrain-aware road networks and building lots.

Roads follow the natural topography of a heightmap: major roads trace elevation contours while minor roads run along the gradient, producing organic street grids that adapt to hills and valleys. On flat terrain the field falls back to an axis-aligned Manhattan grid.

Pipeline

1. Road generation (generate_roads) — Seeds streamlines on a jittered grid and traces them bidirectionally through a TensorField using RK2 (midpoint) integration. Traces snap to existing nodes and split edges via a spatial hash, forming T-junctions and 4-way intersections. Orthogonal branches are spawned at configurable intervals.

2. Graph rationalization (rationalize_graph) — Rewrites the raw tracer output into clean, civil-engineered geometry. Traces continuous arteries through intersections (by forward-vector alignment), applies Ramer-Douglas-Peucker decimation to remove unnecessary intermediate points, and replaces sharp bends with smooth quadratic Bézier fillet arcs. Elevation profiles are smoothed with global Laplacian passes and clamped to a maximum grade. Side-streets severed by moved intersection nodes are automatically reconnected.

3. Block extraction (extract_blocks) — Walks the planar road graph with a minimum-angle (left-most turn) algorithm to enumerate every bounded interior face as a CityBlock polygon. The unbounded exterior face is filtered out by winding direction.

4. Lot subdivision (extract_lots) — Recursively splits each block perpendicular to its longest edge (through the centroid) until sub-polygons fall below a configurable area threshold. A street-aligned inscribed rectangle is computed for each piece, with front/side/rear setbacks applied to produce BuildingLot footprints.

5. Terrain carving (carve_roads, carve_lots) — Flattens the heightmap under roads and building foundations with smooth embankment blending at the edges. carve_roads takes a road_width (total width of the flat road surface) and a blend_radius that controls how far the embankment zone extends beyond the road edge — larger values produce wider, gentler slopes on steep terrain. carve_lots similarly accepts a blend_radius for foundation embankments. carve_roads returns a boolean road-surface mask so that carve_lots can avoid overwriting already-flattened pavement. A two-pass road carving approach prevents embankments from overwriting previously flattened pavement at intersections. Road elevations use the rationalized (smoothed) node heights rather than raw terrain, so roads cut through hills and bridge dips.

6. Road pruning (prune_unused_roads) — Optionally removes roads that do not serve any building lot. Uses Dijkstra-based Steiner tree construction to keep only the minimal connected sub-network that reaches every lot's frontage edge, preferring major roads over minor ones.

7. 3D mesh generation (generate_road_meshes) — Produces engine-agnostic ProceduralMesh vertex buffers for intersection hubs (flat N-gon polygons with embankment skirts) and street ribbons (extruded strips with flanking skirt meshes), using rationalized node elevations for correct height.

Quick start

use symbios_ground::HeightMap;
use symbios_tensor::*;

let heightmap = HeightMap::new(128, 128, 4.0);
let config = TensorConfig::default();

// 1. Generate road network
let mut graph = generate_roads(&heightmap, &config).expect("invalid config");

// 2. Rationalize: straighten, fillet, and smooth elevations
rationalize_graph(&mut graph, &heightmap, &RationalizeConfig::default());

// 3. Extract city blocks
extract_blocks(&mut graph);

// 4. Subdivide blocks into building lots
let mut hm = heightmap;
let lot_config = LotConfig {
    water_level: config.water_level,
    ..LotConfig::default()
};
let lots = extract_lots(&graph, &mut hm, &lot_config);

// 5. Carve roads and lots into terrain
let road_mask = carve_roads(&graph, &mut hm, &RoadMeshConfig::default(), 4.0);
carve_lots(&lots, &mut hm, 2.0, Some(&road_mask));

// 6. (Optional) Prune roads that don't serve any lot
prune_unused_roads(&mut graph, &lots);

// 7. Generate 3D road meshes
let meshes = generate_road_meshes(&graph, &hm, &RoadMeshConfig::default());
// meshes.hubs    — intersection polygons
// meshes.ribbons — street ribbon strips
// meshes.skirts  — embankment skirt meshes

End-to-end example

For the canonical walkthrough of every stage, see examples/full_city.rs:

cargo run --release --example full_city

It builds a 96×96 heightmap with topographical variety, runs the complete pipeline, and writes hand-rolled outputs in the working directory:

• full_city_graph.ppm — top-down RGB view of roads + lot footprints
• full_city_roads.obj — Wavefront OBJ of the 3D road meshes
• full_city_lots.svg — SVG diagram of building lot footprints

The example completes in well under a second on a typical laptop and prints stage timings, so it doubles as a smoke test.

Streaming for large worlds

For 10×10 km open-world regions where the entire road graph won't fit in memory, use CityStreamer. The streamer divides the world into square tiles, generates each on demand from a heightmap callback, caches results, and provides query / eviction APIs. Per-tile seeds are derived deterministically from a base seed so the same input always produces the same world. Cross-tile seamless tracing is not implemented — tile boundaries currently produce visible seams.

Configuration

TensorConfig

LotConfig

RationalizeConfig

RoadMeshConfig

SkirtConfig

Module overview

Dependencies

• symbios-ground — heightmap terrain (HeightMap)
• glam — 2D/3D math (Vec2, Vec3)
• rand + rand_pcg — deterministic RNG for seed jitter
• serde — serialization for configs, graph, and lots

Known limitations

• Flat terrain blocks: On perfectly flat heightmaps the tracer produces mostly parallel streamlines that form degenerate zero-area slivers rather than enclosed blocks. Real enclosed blocks require terrain with slopes so that major and minor directions cross at non-trivial angles.

License

MIT