osmWorkflow/.trellis/tasks/archive/2026-08/08-03-design-feature-registry/prd.md

Design feature registry

Goal

Introduce a conservative Blender feature registry so generate_scene.py no longer hard-codes every OSM feature dispatch branch, while keeping generated .blend / .glb / scene metadata and stdout contracts unchanged.

The user value is maintainability: adding or moving a Blender feature should become a registration-level edit plus a feature module implementation, not a new branch woven through the main scene builder.

Background

• P2 module extraction is now complete for current feature assembly modules: water.py, grass.py, scrub.py, tree.py, fountain.py, building.py, and roads.py exist under blender/osmassets/.
• .trellis/spec/guides/artifact-parity-guide.md records the remaining P2 gap as the missing features/ registry.
• blender/generate_scene.py still owns the orchestration sequence: material creation, OSM way dispatch, road GeoJSON/fallback dispatch, tree collection/fallback, fountain point dispatch, camera focus points, scene metadata, save/render, and SCENE_DONE.
• Artifact parity is mandatory because this is intended as a pure refactor.

Requirements

1. Add a new Blender-side registry module under blender/osmassets/, expected path blender/osmassets/features.py.
2. Replace the inline OSM way if / elif feature dispatch in generate_scene.py with registry-driven dispatch while preserving exact behavior and order:
   • water before grass;
   • grass before scrub;
   • scrub before tree-row collection;
   • tree-row collection before building;
   • first matching handler wins, as the current elif chain does.
3. Make the current feature phases explicit in code:
   • OSM way feature phase;
   • road GeoJSON / OSM fallback phase;
   • tree placement phase;
   • point prop phase for fountains.
4. Keep generate_scene.py responsible for high-level scene contracts:
   • CLI parsing and tree-style validation;
   • collection creation and collection order;
   • material creation order;
   • counts, road_counts, tree counts, and focus_points ownership;
   • catalog.check_layers() and exact Layer catalog warning: print text;
   • scene custom properties;
   • SCENE_DONE marker and JSON shape.
5. Do not change current feature module assembly signatures unless the change is a mechanical adapter around the same behavior.
6. Do not reorder catalog.MATERIALS, catalog.ROAD_LAYERS, collection creation, object creation phases, or SCENE_DONE fields.
7. Do not introduce a second list of osm2streets road layer ids. Road layer iteration must still derive from catalog.ROAD_LAYERS.
8. Do not fix unrelated known defects D1-D3 in this task.

Acceptance Criteria

• blender/osmassets/features.py exists and contains the registry / dispatcher contract for Blender feature phases.
• generate_scene.py uses the registry for OSM way feature dispatch; the previous inline if / elif way feature chain is removed or reduced to small handler callbacks.
• Current generated object names, mesh names, material creation order, collection order, scene properties, and SCENE_DONE JSON remain unchanged.
• road_counts, counts, tree counts, and focus_points continue to be owned by generate_scene.py or by explicit objects passed from it, not hidden in global module state.
• catalog.check_layers() warning behavior remains in generate_scene.py with the exact Layer catalog warning: text.
• python3 -m py_compile blender/osmassets/features.py passes.
• python3 -m py_compile blender/generate_scene.py passes.
• python3 -m unittest blender/tests/test_pure.py passes.
• Blender/Cesium parity before/after is run for nantaizi-lake-innovation-valley and hanyang-block; expected compare result is identical for both.

Out Of Scope

• Changing feature behavior, geometry, z values, material definitions, material order, or catalog declarations.
• Moving material creation into feature modules.
• Moving scene metadata / SCENE_DONE construction out of generate_scene.py.
• Reworking tree model loading, procedural tree fallback, grass tuft loading, scrub bush loading, or camera focus logic beyond adapter-level plumbing.
• Adding new rendered feature types.
• Changing parity ignore lists or stdout marker parsing.

Open Questions

None.