Build a CityJSON 2.0 Implicit Geometry Tree Canopy Calculator — implementation

## Build
Analyze CityJSON 2.0 geometry-templates and SolitaryVegetationObject instances across municipal neighborhoods. Calculate urban tree canopy coverage and shade potential to assist municipal climate adaptation teams.

## User
Urban climate and forestry planner

## Workflow
1. Ingest CityJSON 2.0 models containing geometry-templates and vegetation instances.
2. Resolve implicit geometry template matrices to calculate real-world canopy bounding envelopes.
3. Aggregate total neighborhood canopy surface area and cross-reference with municipal land parcels.
4. Produce an urban canopy density scorecard highlighting areas deficient in thermal shade.

## Interface
Municipal GIS web map showing tree point clouds, canopy footprints, and heat risk neighborhood overlays.

## Data
Acquire open CityJSON 2.0 municipal sample datasets containing vegetation objects or construct mock CityJSON template dictionaries.
Starter examples below are synthetic. They are not downloaded records.

## Source
[CityJSON](https://www.cityjson.org/specs/2.0.1/)
Leverages CityJSON Section 1 geometry-templates definition for implicit geometries reused by City Objects.

## Tools
qdrant, shapely, fastapi.
Qdrant enables high-performance spatial nearest-neighbor search to identify heat-island parcels lacking tree coverage.
Standard hosted model for structuring GIS spatial reports and summarizing environmental compliance metrics.

## 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
- Resolves template geometries using CityJSON transform scales and translation matrices.
- Calculates cumulative canopy surface area in square meters per neighborhood zone.
- Correctly handles files with empty geometry-templates by falling back to explicit geometries.

## Starter Examples
```json
[
  {
    "input": {
      "neighborhood": "Sector-4",
      "geometry_templates": {
        "templates": [
          {
            "lod": "1",
            "type": "Solid",
            "canopy_radius_m": 4
          }
        ]
      },
      "vegetation_objects": [
        {
          "id": "Tree-01",
          "template_index": 0,
          "anchor": [
            100,
            200,
            5
          ]
        },
        {
          "id": "Tree-02",
          "template_index": 0,
          "anchor": [
            115,
            200,
            5
          ]
        }
      ]
    },
    "expected_output": {
      "neighborhood": "Sector-4",
      "total_trees": 2,
      "estimated_canopy_area_sqm": 100.53,
      "shade_coverage_rating": "ADEQUATE",
      "warnings": []
    }
  },
  {
    "input": {
      "neighborhood": "Sector-9",
      "geometry_templates": {
        "templates": []
      },
      "vegetation_objects": [
        {
          "id": "Tree-99",
          "template_index": 0,
          "anchor": [
            50,
            50,
            0
          ]
        }
      ]
    },
    "expected_output": {
      "neighborhood": "Sector-9",
      "total_trees": 0,
      "estimated_canopy_area_sqm": 0,
      "shade_coverage_rating": "DEFICIENT",
      "warnings": [
        "Referenced template_index 0 not found in geometry-templates"
      ]
    }
  }
]
```

## Safety
Produces theoretical urban environmental assessments; does not authorize physical tree pruning or urban forestry removal.
Use mock external writes. Require human review before any real deployment.