75 lines
2.8 KiB
Markdown
75 lines
2.8 KiB
Markdown
# Design
|
|
|
|
## Architecture
|
|
|
|
`roads.py` will join the bpy-layer feature modules under
|
|
`blender/osmassets/`. It may import `os`, `json`, `MeshBatch`, `add_polyline`,
|
|
and geometry helpers required by current road assembly:
|
|
|
|
```python
|
|
from osmassets.geom import clip_polygon, feature_in_bounds, geometry_rings
|
|
from osmassets.mesh import MeshBatch, add_polyline
|
|
```
|
|
|
|
The module will expose two functions:
|
|
|
|
```python
|
|
def assemble_geojson_layer(path, layer_id, projector, collection, material, z):
|
|
...
|
|
|
|
def assemble_osm_fallback(ways, projector, collection, material):
|
|
...
|
|
```
|
|
|
|
`assemble_geojson_layer()` returns the same count as the current
|
|
`add_geojson_layer()`. `assemble_osm_fallback()` returns no count because the
|
|
current fallback also leaves `road_counts` unchanged.
|
|
|
|
## Boundaries
|
|
|
|
- `generate_scene.py` keeps catalog ownership: `road_mats`, `ROAD_LAYERS`
|
|
iteration, `check_layers()` warnings, `road_counts`, scene metadata, and
|
|
stdout markers.
|
|
- `roads.py` owns only object/mesh construction for already chosen road inputs.
|
|
- `catalog.py` and `scripts/lib/scene-layers.js` remain untouched; road layer
|
|
collection/order is not part of this task.
|
|
- No new pure-Python logic is introduced. Existing geometry helpers are reused.
|
|
|
|
## Data Flow
|
|
|
|
1. `generate_scene.py` creates `road_mats` from `catalog.ROAD_LAYERS` and
|
|
`catalog.road_material_specs()`.
|
|
2. If `geojson_dir` exists, `generate_scene.py` runs `catalog.check_layers()`
|
|
and prints warnings exactly as before.
|
|
3. For each `catalog.ROAD_LAYERS` entry, `generate_scene.py` calls
|
|
`roads.assemble_geojson_layer(...)` and stores the returned count under the
|
|
layer id in `road_counts`.
|
|
4. If `road_counts.get("road_surface", 0) == 0`, `generate_scene.py` calls
|
|
`roads.assemble_osm_fallback(...)` with OSM ways and the road surface
|
|
material.
|
|
5. `generate_scene.py` writes `road_counts` into scene metadata and `SCENE_DONE`.
|
|
|
|
## Compatibility
|
|
|
|
The move must preserve road object names, mesh names, geometry clipping,
|
|
feature counting, layer iteration order, warning behavior, fallback trigger,
|
|
fallback widths, z values, material assignments, and metadata JSON. Cesium
|
|
export consumes the resulting `.blend`, so parity should see no non-ignored
|
|
contract difference.
|
|
|
|
## Trade-Offs
|
|
|
|
`catalog.check_layers()` intentionally stays in `generate_scene.py`. Moving it
|
|
into `roads.py` would mix cross-language catalog validation with object
|
|
assembly and increase the blast radius of this refactor.
|
|
|
|
The full feature registry remains deferred. Roads are the last high-risk
|
|
assembly extraction; registry design should be evaluated after this commit when
|
|
the remaining `generate_scene.py` responsibilities are clearer.
|
|
|
|
## Rollback
|
|
|
|
Rollback is mechanical: move `assemble_geojson_layer()` and
|
|
`assemble_osm_fallback()` logic back into `generate_scene.py`, restore the
|
|
direct call sites, remove the `roads.py` import, and delete the module.
|