Build a CityJSON Geometry Template Instantiator for Urban Assets — implementation

## Build
Parse CityJSON geometry-templates to instantiate repeating urban assets. Validate template vertex decompression and local transformation positioning before generating explicit geometries for simulation environments.

## User
Urban simulation developer

## Workflow
1. Extract the geometry-templates object and identify reusable vertex arrays from a CityJSON payload.
2. Locate CityObjects referencing templates and extract their local transformation matrices.
3. Apply scaling and translation to project template vertices into world coordinates using the provided transforms.
4. Export explicit geometries and generate a summary report of successfully instantiated objects.

## Interface
Command-line tool or simple web interface accepting a CityJSON file and returning instantiated 3D geometries and an instantiation report.

## Data
Use open-source CityJSON samples or generate synthetic CityJSON payloads containing geometry-templates and template-referencing CityObjects.
Starter examples below are synthetic. They are not downloaded records.

## Source
[CityJSON](https://www.cityjson.org/specs/2.0.1/)
Implements CityJSON Section 3.4 Geometry templates functionality for implicit geometry instantiation.

## Tools
pydantic-ai, fastapi, numpy, pytest.
Pydantic AI enforces type-safe parsing of complex hierarchical CityJSON structures and geometry templates.
Fast hosted instruction-tuned LLM capable of structured JSON generation and schema validation.

## Deliverables
Submit runnable source, pinned dependencies, setup commands, a working interface, example outputs, and a recorded end-to-end demo. Include tests and an action log.

## Acceptance
- Successfully extracts and decompresses template vertices from the geometry-templates object.
- Correctly applies local transformation matrices to template vertices.
- Identifies and handles missing or invalid template references gracefully.
- Produces a valid report detailing the world coordinates of instantiated assets.

## Starter Examples
```json
[
  {
    "input": {
      "type": "CityJSON",
      "version": "2.0",
      "transform": {
        "scale": [
          1,
          1,
          1
        ],
        "translate": [
          0,
          0,
          0
        ]
      },
      "geometry-templates": {
        "templates": [
          {
            "type": "GeometryInstance",
            "template": 0,
            "vertices-template": [
              [
                0,
                0,
                0
              ],
              [
                0,
                0,
                5
              ]
            ]
          }
        ],
        "vertices-templates": [
          [
            0,
            0,
            0
          ],
          [
            0,
            0,
            5
          ]
        ]
      },
      "CityObjects": {
        "streetlight-1": {
          "type": "CityFurniture",
          "geometry": [
            {
              "type": "GeometryInstance",
              "template": 0,
              "transformationMatrix": [
                1,
                0,
                0,
                100,
                0,
                1,
                0,
                200,
                0,
                0,
                1,
                0,
                0,
                0,
                0,
                1
              ]
            }
          ]
        }
      },
      "vertices": []
    },
    "expected_output": {
      "instantiated_objects": [
        {
          "object_id": "streetlight-1",
          "template_id": 0,
          "world_vertices": [
            [
              100,
              200,
              0
            ],
            [
              100,
              200,
              5
            ]
          ],
          "status": "SUCCESS"
        }
      ],
      "failed_instantiations": [],
      "note": "Simplified synthetic app records, not complete official schema files."
    }
  },
  {
    "input": {
      "type": "CityJSON",
      "version": "2.0",
      "transform": {
        "scale": [
          1,
          1,
          1
        ],
        "translate": [
          0,
          0,
          0
        ]
      },
      "geometry-templates": {
        "templates": [],
        "vertices-templates": []
      },
      "CityObjects": {
        "tree-1": {
          "type": "PlantCover",
          "geometry": [
            {
              "type": "GeometryInstance",
              "template": 99,
              "transformationMatrix": [
                1,
                0,
                0,
                50,
                0,
                1,
                0,
                50,
                0,
                0,
                1,
                0,
                0,
                0,
                0,
                1
              ]
            }
          ]
        }
      },
      "vertices": []
    },
    "expected_output": {
      "instantiated_objects": [],
      "failed_instantiations": [
        {
          "object_id": "tree-1",
          "template_id": 99,
          "reason": "FAILED_MISSING_TEMPLATE"
        }
      ],
      "note": "Simplified synthetic app records, not complete official schema files."
    }
  }
]
```

## Safety
Operates strictly on synthetic or open-source municipal data templates without impacting physical urban infrastructure.
Use mock external writes. Require human review before any real deployment.