Implement proper DSM-based roof plane segmentation + Google Building Insights API

**Major Breakthrough**: Replaced edge detection approach with proper geometric plane segmentation.

## What We Were Doing Wrong
- Using RGB edge detection (Hough lines, Canny) to find roof planes
- 2D image processing for a 3D geometry problem
- Getting "angry scribbling" with too many false lines

## The Proper Solution (Based on Research)
1. **Google Building Insights API**: Fetch pre-computed roof segments
- Returns pitch, azimuth, bounding box for each roof plane
- Available as baseline/comparison

2. **DSM Slope/Aspect Segmentation** (NEW):
- Compute surface normals from Digital Surface Model (slope + aspect)
- Region growing: pixels with similar normals = same roof plane
- This is the geometric method used by solar companies
- No edge detection needed - pure 3D geometry

## New Features
- `fetch_building_insights()`: Get Google's roof segments (pitch, azimuth, area)
- `compute_slope_aspect()`: Calculate surface normals from DSM
- `segment_roof_planes_dsm()`: Region growing based on normal similarity
- UI now defaults to "DSM" method (geometric) vs "Watershed" (DINOv3 features)

## Research References
- Google "Satellite Sunroof" paper (2024)
- RANSAC plane fitting for LiDAR point clouds
- Standard: slope/aspect clustering for roof plane detection

User can now choose:
- DSM (geometric, recommended)
- Watershed/SLIC/Felzenszwalb (DINOv3 semantic features)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

app.py

@@ -72,6 +72,50 @@ def geocode_address(address, api_key):
     return location["lat"], location["lng"], formatted_address
 
 
+def fetch_building_insights(lat, lng, api_key):
+    """Fetch Google's pre-computed roof segments from Building Insights API."""
+    url = "https://solar.googleapis.com/v1/buildingInsights:findClosest"
+    params = {
+        "location.latitude": lat,
+        "location.longitude": lng,
+        "requiredQuality": "HIGH",
+        "key": api_key
+    }
+
+    response = requests.get(url, params=params)
+
+    if response.status_code != 200:
+        # Try MEDIUM quality if HIGH fails
+        params["requiredQuality"] = "MEDIUM"
+        response = requests.get(url, params=params)
+
+    if response.status_code != 200:
+        print(f"⚠️ Building Insights API error: {response.status_code}")
+        return None
+
+    data = response.json()
+
+    # Extract roof segments
+    roof_segments = []
+    if "solarPotential" in data and "roofSegmentStats" in data["solarPotential"]:
+        for idx, segment in enumerate(data["solarPotential"]["roofSegmentStats"]):
+            roof_segments.append({
+                "segment_id": idx,
+                "pitch_degrees": segment.get("pitchDegrees", 0),
+                "azimuth_degrees": segment.get("azimuthDegrees", 0),
+                "center": segment.get("center", {}),
+                "bounding_box": segment.get("boundingBox", {}),
+                "plane_height_meters": segment.get("planeHeightAtCenterMeters", 0),
+                "area_sqm": segment.get("stats", {}).get("areaMeters2", 0)
+            })
+
+    return {
+        "roof_segments": roof_segments,
+        "building_bounds": data.get("boundingBox", {}),
+        "raw_data": data
+    }
+
+
 def fetch_geotiff(lat, lng, api_key, radius_meters=50):
     """Fetch RGB GeoTIFF and building mask from Google Solar API Data Layers."""
 
@@ -328,6 +372,185 @@ def detect_and_suppress_shadows(img_array):
     return img_corrected, shadow_mask
 
 
+def compute_slope_aspect(dsm_array, pixel_size_meters=0.1):
+    """
+    Compute slope and aspect (surface normal) from DSM.
+
+    This is the KEY to proper roof plane segmentation - pixels with similar
+    normals belong to the same roof plane.
+
+    Args:
+        dsm_array: Digital Surface Model (height map)
+        pixel_size_meters: Ground sampling distance
+
+    Returns:
+        slope: Slope angle in degrees (0-90)
+        aspect: Aspect angle in degrees (0-360, compass direction)
+        normal_x, normal_y, normal_z: Surface normal vectors (unit vectors)
+    """
+    # Compute gradients (height change per pixel)
+    dy, dx = np.gradient(dsm_array)
+
+    # Convert to slope (change in height per meter)
+    dx = dx / pixel_size_meters
+    dy = dy / pixel_size_meters
+
+    # Compute slope (angle from horizontal)
+    slope_rad = np.arctan(np.sqrt(dx**2 + dy**2))
+    slope = np.degrees(slope_rad)
+
+    # Compute aspect (compass direction of steepest descent)
+    # 0° = North, 90° = East, 180° = South, 270° = West
+    aspect_rad = np.arctan2(-dx, dy)  # Note: -dx because East is positive X
+    aspect = np.degrees(aspect_rad)
+    aspect = (aspect + 360) % 360  # Normalize to 0-360
+
+    # Compute surface normal vectors (unit vectors)
+    # Normal vector = (-dz/dx, -dz/dy, 1) normalized
+    normal_x = -dx
+    normal_y = -dy
+    normal_z = np.ones_like(dx)
+
+    # Normalize to unit vectors
+    magnitude = np.sqrt(normal_x**2 + normal_y**2 + normal_z**2)
+    normal_x = normal_x / magnitude
+    normal_y = normal_y / magnitude
+    normal_z = normal_z / magnitude
+
+    return slope, aspect, normal_x, normal_y, normal_z
+
+
+def segment_roof_planes_dsm(dsm_array, building_mask=None, pixel_size_meters=0.1,
+                             slope_tolerance=5.0, aspect_tolerance=15.0, min_area_pixels=100):
+    """
+    Segment roof planes based on DSM slope/aspect analysis.
+
+    This is the PROPER algorithm used by solar companies:
+    1. Compute surface normals (slope + aspect) from DSM
+    2. Cluster pixels with similar normals
+    3. Extract planar roof segments
+
+    Args:
+        dsm_array: Digital Surface Model
+        building_mask: Restrict to building footprint
+        pixel_size_meters: Ground sampling distance
+        slope_tolerance: Max slope difference for same plane (degrees)
+        aspect_tolerance: Max aspect difference for same plane (degrees)
+        min_area_pixels: Minimum segment size
+
+    Returns:
+        segments: Labeled segmentation map
+        plane_info: List of plane parameters for each segment
+    """
+    # Compute surface normals
+    slope, aspect, normal_x, normal_y, normal_z = compute_slope_aspect(dsm_array, pixel_size_meters)
+
+    # Apply building mask
+    if building_mask is not None:
+        if building_mask.shape != dsm_array.shape:
+            building_mask = cv2.resize(
+                building_mask.astype(np.uint8),
+                (dsm_array.shape[1], dsm_array.shape[0]),
+                interpolation=cv2.INTER_NEAREST
+            )
+        valid_mask = building_mask > 0
+    else:
+        valid_mask = np.ones_like(dsm_array, dtype=bool)
+
+    # Stack features for clustering: (slope, aspect, height, normal_x, normal_y, normal_z)
+    # Normalize features to similar scales
+    features = np.stack([
+        slope / 90.0,  # Normalize to 0-1
+        np.sin(np.radians(aspect)),  # Convert aspect to cyclic features
+        np.cos(np.radians(aspect)),
+        (dsm_array - dsm_array[valid_mask].min()) / (dsm_array[valid_mask].max() - dsm_array[valid_mask].min() + 1e-8),
+        normal_x,
+        normal_y,
+        normal_z
+    ], axis=-1)
+
+    # Region growing based on normal similarity
+    segments = np.zeros_like(dsm_array, dtype=np.int32)
+    segment_id = 1
+    visited = ~valid_mask  # Start with invalid pixels as visited
+
+    h, w = dsm_array.shape
+
+    # Find seed points (local maxima in height within building)
+    from scipy.ndimage import maximum_filter
+    local_max = maximum_filter(dsm_array, size=5)
+    seeds = (dsm_array == local_max) & valid_mask
+    seed_coords = np.argwhere(seeds)
+
+    # Region growing from seeds
+    for seed_y, seed_x in seed_coords:
+        if visited[seed_y, seed_x]:
+            continue
+
+        # Start new segment
+        stack = [(seed_y, seed_x)]
+        visited[seed_y, seed_x] = True
+        segment_pixels = []
+
+        seed_slope = slope[seed_y, seed_x]
+        seed_aspect = aspect[seed_y, seed_x]
+
+        while stack:
+            y, x = stack.pop()
+            segment_pixels.append((y, x))
+            segments[y, x] = segment_id
+
+            # Check 8-connected neighbors
+            for dy in [-1, 0, 1]:
+                for dx in [-1, 0, 1]:
+                    if dy == 0 and dx == 0:
+                        continue
+
+                    ny, nx = y + dy, x + dx
+
+                    if ny < 0 or ny >= h or nx < 0 or nx >= w:
+                        continue
+                    if visited[ny, nx]:
+                        continue
+                    if not valid_mask[ny, nx]:
+                        continue
+
+                    # Check if normal is similar (same roof plane)
+                    slope_diff = abs(slope[ny, nx] - seed_slope)
+                    aspect_diff = min(abs(aspect[ny, nx] - seed_aspect),
+                                     360 - abs(aspect[ny, nx] - seed_aspect))  # Handle wraparound
+
+                    if slope_diff < slope_tolerance and aspect_diff < aspect_tolerance:
+                        visited[ny, nx] = True
+                        stack.append((ny, nx))
+
+        # Keep segment if large enough
+        if len(segment_pixels) >= min_area_pixels:
+            segment_id += 1
+        else:
+            # Remove small segment
+            for y, x in segment_pixels:
+                segments[y, x] = 0
+
+    # Extract plane parameters for each segment
+    plane_info = []
+    for sid in range(1, segment_id):
+        mask = segments == sid
+        if not mask.any():
+            continue
+
+        plane_info.append({
+            "segment_id": sid,
+            "mean_slope": float(slope[mask].mean()),
+            "mean_aspect": float(aspect[mask].mean()),
+            "mean_height": float(dsm_array[mask].mean()),
+            "area_pixels": int(mask.sum()),
+            "area_sqm": float(mask.sum() * pixel_size_meters**2)
+        })
+
+    return segments, plane_info
+
+
 def extract_multiscale_features(image, target_size=518):
     """Extract multi-layer DINOv3 features for better roof plane detection."""
     original_size = image.size
@@ -778,6 +1001,24 @@ def process_address(address, segmentation_method, n_segments, selected_clusters,
     except Exception as e:
         return None, None, None, None, None, f"❌ Geocoding failed: {str(e)}"
 
+    # Fetch Google's pre-computed roof segments
+    google_roof_segments = None
+    try:
+        status += "Fetching Google's roof segments from Building Insights API...\n"
+        building_insights = fetch_building_insights(lat, lng, api_key)
+        if building_insights and building_insights["roof_segments"]:
+            google_roof_segments = building_insights["roof_segments"]
+            status += f"✓ Google detected {len(google_roof_segments)} roof segments:\n"
+            for seg in google_roof_segments[:5]:  # Show first 5
+                status += f"  - Segment {seg['segment_id']}: {seg['pitch_degrees']:.1f}° pitch, {seg['azimuth_degrees']:.0f}° azimuth, {seg['area_sqm']:.1f} m²\n"
+            if len(google_roof_segments) > 5:
+                status += f"  ... and {len(google_roof_segments) - 5} more\n"
+            status += "\n"
+        else:
+            status += "⚠️ No Google roof segments available (will use custom segmentation)\n\n"
+    except Exception as e:
+        status += f"⚠️ Building Insights API error: {str(e)}\n\n"
+
     try:
         status += "Fetching satellite imagery and building data...\n"
         geotiff_bytes, mask_bytes, dsm_bytes, layers_info = fetch_geotiff(lat, lng, api_key, radius_meters)
@@ -839,25 +1080,49 @@ def process_address(address, segmentation_method, n_segments, selected_clusters,
         return None, None, None, None, None, f"❌ Failed to fetch imagery: {str(e)}"
 
     try:
-        status += f"**Model:** {MODEL_NAME}\n"
-        status += f"Running {segmentation_method.upper()} segmentation with shadow suppression...\n"
-
-        seg_resized, img_array, edges, shadow_mask = segment_roof_planes(
-            image,
-            method=segmentation_method,
-            n_segments=int(n_segments),
-            dsm_array=dsm_array,
-            building_mask=cropped_mask,
-            hough_threshold=hough_threshold,
-            min_line_length=min_line_length,
-            dsm_threshold=dsm_threshold
-        )
+        # Choose segmentation method
+        if segmentation_method == "dsm" and dsm_array is not None:
+            # DSM-based slope/aspect segmentation (proper geometric method)
+            status += f"**Method:** DSM Slope/Aspect Analysis (geometric)\n"
+            status += f"Segmenting roof planes based on surface normals...\n"
 
-        status += f"✓ Detected {len(np.unique(seg_resized))} segments\n"
-        if shadow_mask is not None and shadow_mask.any():
-            shadow_pct = (shadow_mask.sum() / shadow_mask.size) * 100
-            status += f"✓ Shadow regions: {shadow_pct:.1f}% (suppressed)\n"
-        status += f"\n"
+            seg_resized, plane_info = segment_roof_planes_dsm(
+                dsm_array,
+                building_mask=cropped_mask,
+                pixel_size_meters=0.1
+            )
+
+            status += f"✓ Detected {len(plane_info)} roof planes:\n"
+            for plane in plane_info[:10]:
+                status += f"  - Plane {plane['segment_id']}: {plane['mean_slope']:.1f}° slope, {plane['mean_aspect']:.0f}° azimuth, {plane['area_sqm']:.1f} m²\n"
+            status += f"\n"
+
+            # Create dummy edge and shadow mask for visualization
+            img_array = np.array(image)
+            edges = np.zeros(img_array.shape[:2], dtype=np.uint8)
+            shadow_mask = None
+
+        else:
+            # DINOv3-based semantic segmentation (existing method)
+            status += f"**Model:** {MODEL_NAME}\n"
+            status += f"Running {segmentation_method.upper()} segmentation with shadow suppression...\n"
+
+            seg_resized, img_array, edges, shadow_mask = segment_roof_planes(
+                image,
+                method=segmentation_method,
+                n_segments=int(n_segments),
+                dsm_array=dsm_array,
+                building_mask=cropped_mask,
+                hough_threshold=hough_threshold,
+                min_line_length=min_line_length,
+                dsm_threshold=dsm_threshold
+            )
+
+            status += f"✓ Detected {len(np.unique(seg_resized))} segments\n"
+            if shadow_mask is not None and shadow_mask.any():
+                shadow_pct = (shadow_mask.sum() / shadow_mask.size) * 100
+                status += f"✓ Shadow regions: {shadow_pct:.1f}% (suppressed)\n"
+            status += f"\n"
 
         # Visualize segmentation
         colors = np.array([
@@ -1014,10 +1279,10 @@ with gr.Blocks(title="Roof Plane Segmentation - DINOv3", theme=gr.themes.Soft())
 
             with gr.Accordion("⚙️ Segmentation Settings", open=True):
                 segmentation_method = gr.Radio(
-                    choices=["slic", "watershed", "felzenszwalb"],
-                    value="watershed",
+                    choices=["dsm", "watershed", "slic", "felzenszwalb"],
+                    value="dsm",
                     label="Segmentation Algorithm",
-                    info="Watershed best for roof ridges/valleys"
+                    info="DSM = Slope/Aspect analysis (geometric, recommended). Watershed = DINOv3 features + height edges"
                 )
 
                 n_segments = gr.Slider(