---

name: rooftop-solar-inventory description: > Inventory building rooftop solar potential: available area, slope/aspect, shading, and PV capacity/energy yield/economic viability. Outputs building-level candidate rankings for solar deployment.

Rooftop Solar Inventory

Assesses building-level rooftop solar potential by extracting roof planes, computing slope/aspect and shading, deducting setbacks and obstacles, and estimating installed capacity, annual energy yield, and economics.

Trigger

Use when the user wants to:

• Calculate solar PV capacity for a portfolio of buildings
• Identify high-potential rooftops without shading issues
• Rank buildings by solar economic viability
• Generate rooftop solar candidate lists for feasibility studies
• Estimate annual energy yield and financial returns for rooftop PV

CLI Usage

# Basic analysis with synthetic demo data
python scripts/rooftop_solar_inventory.py --output-dir ./rsi-output

# With custom setback and panel type
python scripts/rooftop_solar_inventory.py \
  --setback 1.5 \
  --panel-type hjt_700w \
  --output-dir ./rsi-output

# With custom economic parameters
python scripts/rooftop_solar_inventory.py \
  --electricity-price 0.65 \
  --annual-ghi 1600 \
  --system-lifetime 30 \
  --output-dir ./rsi-output

# With building footprints file
python scripts/rooftop_solar_inventory.py \
  --buildings ./data/buildings.geojson \
  --dsm ./data/dsm.tif \
  --output-dir ./rsi-output

数据下载

本 skill 可自动从 Microsoft Planetary Computer + NASA POWER 下载数据 (无需 API key):

# 自动下载 MS Buildings 建筑足迹 + NASA POWER GHI 太阳辐射
python scripts/rooftop_solar_inventory.py \
    --bbox 116.38,39.90,116.42,39.94 \
    --date-range 2024-06-01,2024-06-30 \
    --output-dir ./rsi-auto

下载的内容:

• MS Buildings (ms-buildings collection on MPC) — 建筑足迹，替换 --buildings
• NASA POWER GHI (ALLSKY_SFC_SW_DWN) — 日均太阳辐照度，写入 nasa_power_ghi.csv，并自动计算 annual GHI 替换默认值

下载元数据（data_source, fetched_at, collection, nasa_power_path）会写入 output-manifest.json。

Parameters

Parameter	Default	Description
--buildings	None	Building footprints (GeoJSON/Shapefile)
--dsm	None	Digital Surface Model GeoTIFF
--point-cloud	None	Point cloud file (LAS/LAZ)
--setback	1.0	Edge setback in meters
--panel-type	mono_perc_540w	Panel type: mono_perc_540w, mono_perc_600w, hjt_700w
--min-contiguous-area	10.0	Minimum contiguous area in m2
--annual-ghi	1400	Annual Global Horizontal Irradiance in kWh/m2
--performance-ratio	0.82	System performance ratio
--electricity-price	0.55	Electricity price in CNY/kWh
--discount-rate	0.06	Discount rate for NPV calculation
--system-lifetime	25	System lifetime in years
--output-dir	./rsi-output	Output directory

Output

File	Description
roof_planes.geojson	Roof plane polygons with slope, aspect, area
solar_candidates.geojson	Candidate buildings with solar potential
building_potential.csv	Ranked building-level results table
shading.tif	Shading mask (requires DSM input)
request.json	Analysis request metadata
dataset-manifest.json	Dataset inventory
output-manifest.json	Output file inventory and statistics
qa.json	Quality assurance checks
run.log	Execution log

Quality Codes

Code	Name	Description
1	high	DSM-based segmentation, reliable geometry
2	medium	Mixed data sources, acceptable confidence
3	low	No DSM, assumed flat roof
4	invalid	Processing error or invalid geometry

Roof Type Codes

Code	Name	Description
0	flat	Slope < 5°
1	single_slope	Single inclined plane
2	gable	Two-slope gable roof
3	complex	Multi-plane or steep (>45°)

Key Algorithms

Roof Plane Extraction

Without DSM: assumes flat roof (single plane = building footprint), marked low confidence. With DSM: segments roof using slope/aspect clustering on connected components.

Slope and Aspect

Computed from DSM using numpy gradient method:

• slope = arctan(sqrt(gx^2 + gy^2))
• aspect = atan2(-gx, gy) mapped to 0-360°

Shading

Ray-casting from each pixel toward sun position. A pixel is shaded if terrain blocks the sun at the given azimuth/altitude. Supports multi-pass annual shading.

Usable Area

Subtracts edge setback (negative buffer), obstacles, and filters by minimum contiguous area. Handles MultiPolygon by taking largest component.

Solar Potential

• Capacity: n_panels = usable_area / (panel_area * (1 + spacing_ratio))
• Energy: E = capacity * GHI * PR * orientation_factor * (1 - shading)
• Economics: NPV, LCOE, payback period over system lifetime

Building Ranking

Composite score (0-1) based on:

• Installed capacity (40%)
• Economic NPV (30%)
• Specific yield (30%)

Exit Codes

Code	Meaning
0	Success
2	Argument error
3	Dependency missing
6	Data validation failure
7	Processing failure

Limitations

• Without DSM, all roofs assumed flat (low confidence)
• Shading computation is simplified (single sun position or coarse multi-pass)
• Structural suitability, roof loading, and ownership not assessed
• Economic results are indicative; actual costs vary by project
• Results are auxiliary analysis only; engineering decisions require manual review

References

• PVWatts Calculator (NREL)
• IEC 61724-1: Photovoltaic system performance monitoring
• China PV Industry Association (CPIA) annual reports

数据下载

本 skill 可自动从 Microsoft Planetary Computer 下载数据 (无需 API key):

python rooftop_solar_inventory.py --bbox 116,39,117,40 --date-range 2024-06-01,2024-06-30 --output-dir <tmp>

• --bbox W,S,E,N: WGS-84 边界框 (西, 南, 东, 北)
• --date-range START,END: 日期范围 (YYYY-MM-DD,YYYY-MM-DD)
• --aoi-file <path.geojson>: 替代 --bbox 的 GeoJSON 多边形
• --cache-dir <path>: 缓存目录 (默认 ~/.geoskill_cache)

当用户只给 --bbox + --date-range (没有 --buildings) 时，skill 自动下载数据。 当用户给 --buildings 时，走原文件路径 (向后兼容)。