# SunTrace3D

> Free browser-based 3D solar analysis tool. Simulate shadows, place solar panels, calculate energy yield, and analyze sunlight for any location on Earth. No installation or sign-up required. Works on desktop and mobile. Available in 18 languages.

SunTrace3D uses photorealistic 3D city models (Google 3D Tiles) combined with satellite irradiance data from the European Commission (PVGIS) to provide accurate shadow analysis and solar energy calculations. Professional-grade tools that competing products charge EUR 2,000-10,000/year for -- starting free.

## Quick Start

- [Open the 3D Viewer](https://suntrace3d.com/viewer): Free interactive 3D viewer -- loads instantly for any location worldwide. Search any address.
- [View a specific location](https://suntrace3d.com/viewer?lat=48.8566&lng=2.3522&q=Paris): Add lat/lng coordinates to the URL to jump to any location (example: Paris).
- [User Guide](https://suntrace3d.com/docs): Complete documentation with 49 feature sections.
- [API Documentation](https://suntrace3d.com/docs/api): REST API for 3D model generation and solar calculations.

## How to Use

1. Open [suntrace3d.com/viewer](https://suntrace3d.com/viewer)
2. Type your address in the search bar -- a 3D model of your building loads
3. Drag the time slider at the bottom to watch shadows move throughout the day
4. Change the date to see how shadows differ in summer vs winter
5. Click the solar panel button (or press P) and click on your roof to place panels
6. The system instantly shows: annual energy yield (kWh), shading loss per panel, installation cost estimate, payback period

### Share a Specific Location

Use this URL format: `https://suntrace3d.com/viewer?lat=LATITUDE&lng=LONGITUDE`

Examples:
- Paris: `https://suntrace3d.com/viewer?lat=48.8566&lng=2.3522`
- New York: `https://suntrace3d.com/viewer?lat=40.7128&lng=-74.0060`
- Tokyo: `https://suntrace3d.com/viewer?lat=35.6762&lng=139.6503`
- Sydney: `https://suntrace3d.com/viewer?lat=-33.8688&lng=151.2093`

### Keyboard Shortcuts

- N: Navigate mode (pan/rotate/zoom)
- P: Place solar panels
- B: Build mode (add custom buildings)
- W: Open Solar Panel Wizard (Pro)
- R: Rectangle placement tool
- E: Eraser tool
- G: Ground mount mode (Pro)
- 2 / 3: Plan mode (top-down orthographic 2D) / back to 3D
- Ctrl+Z: Undo last action
- Ctrl+Y: Redo last undone action
- Shift+Click: Multi-select panels or scene objects
- Ctrl+C / Ctrl+V: Copy and paste selected items
- Delete: Remove selected item(s)

## Core Features (Free -- No Account Required)

- [Shadow Simulation](https://suntrace3d.com/docs#4-shadow-simulation): Scrub through 24 hours on any date to watch shadows sweep across buildings. Accurate sun positions based on latitude, longitude, date, and time.
- [Solar Panel Placement](https://suntrace3d.com/docs#6-solar-panel-placement): Place virtual solar panels on any rooftop. Adjust tilt, azimuth, area, and efficiency. Up to 6 panels on the free tier.
- [Energy Yield Analysis](https://suntrace3d.com/docs#8-energy-yield-analysis): Annual kWh estimates using PVGIS satellite data. Monthly breakdown, peak power, specific yield, and per-panel shading loss factor.
- [Sun Path Visualization](https://suntrace3d.com/docs#5-sun-path-visualization): See the sun's complete trajectory arc for any date at any location.
- [Shadow Analysis](https://suntrace3d.com/docs#7-shadow-analysis): Per-panel shadow analysis using 154 annual sun positions. See exactly which panels get shaded and when.
- [Building Configurator](https://suntrace3d.com/docs#11-building-placement-build-mode): Place custom buildings with configurable dimensions and roof types to study shadow impact of proposed construction.
- [Scene Objects & Landscaping](https://suntrace3d.com/docs#12-scene-objects--landscaping): Add trees, fences, pergolas, obstacles, and event infrastructure. All cast and receive accurate shadows.
- [Sunlight Heatmap](https://suntrace3d.com/docs#14-sunlight-heatmap): Color-coded visualization of daily sun hours across ground areas.
- [Garden Planner](https://suntrace3d.com/docs#15-garden-planner): 50+ plants with sun-compatibility analysis based on actual heatmap data.
- [Measurement Tool](https://suntrace3d.com/docs#21-measurement-tool): Measure distances and heights in the 3D scene.
- [Climate Data](https://suntrace3d.com/docs#16-climate-data): Local temperature, precipitation, and sun hours for the selected location.
- [Installation Cost Calculator](https://suntrace3d.com/docs#17-installation-cost--get-quote): Regional pricing, payback period, government incentives, and ROI analysis.
- [PDF Site Report](https://suntrace3d.com/docs#19-site-report): Generate a professional PDF with 3D views, system specs, energy analysis, financial breakdown, and shadow diagrams.
- [Compass & Orientation](https://suntrace3d.com/docs#10-compass--orientation): Interactive compass overlay showing true north and building orientation.
- [Plan Mode](https://suntrace3d.com/docs#plan-mode): True top-down orthographic 2D view with a scale bar, project north rotation (view only) and contours sampled from the loaded 3D model.

## Pro Features (EUR 9/month)

- [HD 3D Models](https://suntrace3d.com/docs#9-sd--hd-quality-modes): Photorealistic high-definition models with maximum geometric and texture detail.
- [Solar Panel Wizard](https://suntrace3d.com/docs#33-solar-wizard): Automated panel placement -- click a roof and the AI detects the surface boundary, estimates shading, and places an optimized layout. Goals: maximize energy, cover your bill, best ROI, or go green.
- [Ground Mount Placement](https://suntrace3d.com/docs#ground-mount): Draw ground-mounted solar array boundary polygons and generate optimized panel layouts with configurable tilt, azimuth, and ground coverage ratio.
- [Engineering Tools](https://suntrace3d.com/docs#module-inverter-catalog): Full PV design suite -- module & inverter catalog (CEC-certified), automatic string planning with 3D color-coded panels, single-line diagrams, cable sizing, self-consumption analysis, battery storage simulation, energy system dashboard with real-time power flows, bill of materials (CSV export), and PVsyst-compatible data export. 3D-placeable inverter, battery, and meter objects with wiring visualization and savings counter.
- [Weather Forecast](https://suntrace3d.com/docs#weather-forecast): 7-day weather-driven output forecast -- what the system will actually produce this week, from the real hourly forecast rather than long-term averages. Models cloud, cell heating with wind cooling, soiling between rain events, snow cover and inverter clipping, and compares each day against the 22-year seasonal normal for that exact location. Includes anomaly alerts (snow on the array, multi-day slumps, heat derate, storm wind, free rain cleaning) and day-by-day advice on when to run flexible loads. 14 days on Business, 16 on Enterprise. Optional email alerts when the week ahead is materially above or below normal, led by a 3D render of your own roof. One-minute demo video: https://youtu.be/qxIGLmt2Dx8
- [Weekly Forecast by Email and Notification](https://suntrace3d.com/docs#weekly-digest): The same forecast delivered once a week without opening the app -- by email, by browser/mobile push notification, or both. Email: the week against the seasonal normal, a bar per day, best and weakest day, the best window for flexible loads, up to four actions. Notification: the week's verdict and the best day (with a picture of the week on Chrome; iPhone/iPad need SunTrace3D added to the Home Screen first). Sent at an hour learned from the reader's own activity in their time zone, never at night; backs off to monthly after 4 ignored sends and pauses after 7. Available to every account with a real location -- subscribers get their own saved system, free accounts a reference rooftop at the same place. Settings under Account -> Preferences. One-minute demo (vertical): https://www.youtube.com/shorts/naRCWKGY_zg
- [Right-to-Light Compliance](https://suntrace3d.com/docs#27-right-to-light-compliance): Shadow studies for planning permission. BRE 209 guidelines, EU Directive compliance.
- [Urban Heat Analysis](https://suntrace3d.com/docs#28-urban-heat-analysis): Thermal comfort analysis for urban areas. Heat island assessment.
- [Film & Photography Tools](https://suntrace3d.com/docs#29-film--photography-tools): Golden hour calculator, sun position for any date/time, natural light simulation for location scouting.
- [3D Model Import](https://suntrace3d.com/docs#26-importing-3d-models): Upload GLB/GLTF files to add custom 3D buildings and structures.
- [Save Projects](https://suntrace3d.com/docs#25-project-management): Save and restore complete scenes including panels, buildings, objects, and camera views.
- Up to 20 solar panels, 20 scene objects, 15 custom buildings

## Business Features (EUR 99/month)

- [Partner API](https://suntrace3d.com/docs/api): REST API for programmatic 3D model generation and solar energy calculations.
- [Embeddable Viewer](https://suntrace3d.com/docs/api#embeddable-viewer): Embed an interactive 3D solar viewer on your website via iframe.
- [Lead Capture](https://suntrace3d.com/solutions/installers): Capture customer leads from embedded viewers for solar installation businesses.
- Unlimited solar panels, scene objects, and custom buildings
- Commercial use rights

## Site Planning (Business -- EUR 99/month)

Feasibility studies for land and development, solved live on real 3D terrain. In the app this is the "Site Planning" vertical; it is unrelated to the solar PDF "Site Report".

- [Overview](https://suntrace3d.com/docs#site-planning): Draw a parcel, set constraints, choose what to build, and see units, FAR, floor area, parking, cost and a zoning check update with every change. Organised as deals > schemes > sites; duplicate a scheme to compare alternatives.
- [Guided Start](https://suntrace3d.com/docs#site-guided-start): Four questions (site, zoning district, typology and floors, yield) ending on a solved scheme.
- [Parcel & Setbacks](https://suntrace3d.com/docs#site-parcel-setbacks): Draw the parcel or take it from the model. Edges are auto-labelled front/side/rear from real OpenStreetMap streets, each with its own setback and a per-edge override.
- [Regions](https://suntrace3d.com/docs#site-regions): Building areas, easements, open space and infill; pin and link regions.
- [Typologies & Unit Mix](https://suntrace3d.com/docs#site-typologies): Six typologies -- double-loaded bar, residential over podium, garden walk-up, wrap around parking, industrial big box, data centre. Unit mix with share, area and rent; cost rates feed a pro forma (yield on cost).
- [Parking & Circulation](https://suntrace3d.com/docs#site-parking-circulation): Surface, structured or below-grade parking at 90/60/45 degrees with ADA stalls; drives enter from the frontage through curb cuts, reserve their ground before parking is packed, and report any bay they cannot reach.
- [Zoning & Results](https://suntrace3d.com/docs#site-zoning-results): Tabulation, quantity takeoff with indicative costs, a zoning checker with generic district presets (R-1, R-3, mixed use, C-2, I-2, data centre campus), and an errors list.
- [Options, Data Layers & Export](https://suntrace3d.com/docs#site-options-export): Generate up to 60 options (floors, setbacks, stall angle) ranked by an objective; free FEMA flood (USA only) and OpenStreetMap utilities/wetlands layers; 3D massing; DXF, SVG and CSV export.
- Direct link: `https://suntrace3d.com/viewer?lat=38.889&lng=-77.026&vertical=site`

What it does NOT do: it never changes the design to satisfy zoning or parking (it reports failures instead); zoning presets are generic North American archetypes, not a municipality's code, and zoning is not looked up automatically; there is no split 2D/3D view; circulation is a spine with branches, so very large sites may leave bays unreached; industrial parking demand is not modelled; Site Planning is not available through AI agent sessions.

## CRM Platform (Business -- EUR 99/month)

- [CRM for Solar Installers](https://suntrace3d.com/crm/installers): Territory-based lead generation for solar installation companies. Draw service areas, auto-detect rooftops, score every building for solar potential, run outreach campaigns.
- [CRM for Real Estate](https://suntrace3d.com/crm/real-estate): Property solar scoring for real estate professionals. Evaluate sun exposure and solar potential across neighborhoods.
- Territory Drawing: Draw polygon boundaries on an interactive map to define your service area
- Automatic Roof Detection: Detects every building using satellite-derived footprint data, filters sheds/garages, classifies residential vs commercial
- Solar Scoring: Per-building estimates -- roof area, panel count, kWp capacity, annual kWh yield, solar grade (A-F), estimated deal value
- Pipeline Management: 10-stage journey from Identified to Installed with drag-and-drop stage progression
- Campaign Engine: Generate personalized print and email materials from real 3D models of each prospect's building
- QR Response Tracking: Each mailer includes a unique QR code linking to the prospect's building in the 3D viewer -- scans are tracked and auto-advance the prospect's journey stage
- Physical Mail: Export print-ready CSV for Stannp mail-merge, with delivery tracking per piece
- Territory Dashboard: Funnel visualization, total installable potential (kWp/MWh), activity feed with 30-second polling
- Free Playground: Anyone can try the CRM -- draw a small region and preview detected rooftops with real solar scores (3 prospects shown, no account required)

## AI Agent Integration

AI agents (chatbots, virtual assistants, MCP tools) can guide users through solar panel analysis by creating sessions via the API. No API key required.

- **Create a session**: `POST https://suntrace3d.com/api/mcp-sessions` with location and wizard goal
- **Send the viewer URL** from the response to the user
- **Or construct a URL directly**: `https://suntrace3d.com/viewer?lat=48.8566&lng=2.3522&wizard=maximize_energy`

Full integration guide: [LLM Agent Integration Guide](https://suntrace3d.com/llms-agent.txt)

## Industry Solutions

- [Homeowners](https://suntrace3d.com/solutions/homeowners): Check if your roof gets enough sun for solar panels. Free solar roof analysis with energy yield and cost estimates.
- [Solar Installers](https://suntrace3d.com/solutions/installers): Remote site assessment, proposal generation, embeddable solar calculator for your website, lead capture.
- [Architects](https://suntrace3d.com/solutions/architects): Shadow study tool for planning permission. Sun path diagrams, right-to-light assessment, BRE 209 compliance.
- [Property Developers](https://suntrace3d.com/solutions/developers): Pre-construction solar feasibility and shadow impact studies for new developments.
- [Site Planning](https://suntrace3d.com/solutions/site-planning): Site feasibility and test-fit software: parcel yield, typologies, parking and circulation, zoning check, takeoff and DXF export on real 3D terrain.
- [Energy Consultants](https://suntrace3d.com/solutions/energy-consultants): Professional solar analysis API, feasibility report generation, bulk calculations.
- [Real Estate](https://suntrace3d.com/solutions/real-estate): Property solar potential and sun exposure analysis for listings. Solar premium valuation.
- [Garden & Landscape](https://suntrace3d.com/solutions/garden-landscape): Shade mapping, sun hours calculator, 50+ plant compatibility planning based on actual sunlight data.
- [Urban Planners](https://suntrace3d.com/solutions/urban-planners): Overshadowing assessment, pedestrian shadow comfort, BRE 209 compliance for developments.
- [Film & Photography](https://suntrace3d.com/solutions/film-photography): Golden hour calculator, location scouting, natural light direction planning for any date and time.
- [Agriculture](https://suntrace3d.com/solutions/agriculture): Crop sunlight analysis, greenhouse light planning, growing season solar assessment.
- [Live Events](https://suntrace3d.com/solutions/live-events): Event shade planning, stage sun position, tent and canopy placement for outdoor venues.

## Pricing

- **Free (Homeowner)**: 3D viewer, shadow simulation, up to 6 solar panels, energy yield estimates, garden planner, sunlight heatmap, PDF site reports, climate data, measurement tool. No sign-up required.
- **Pro (Personal) -- EUR 9/month**: Everything in Free plus HD models, Solar Panel Wizard, ground mount, engineering tools (module/inverter catalog, string planning, cable sizing, self-consumption, battery simulation, BOM, SLD), 20 panels, 7-day weather forecast, right-to-light compliance, urban heat analysis, film & photography tools, 3D model import, save projects.
- **Business (Professional) -- EUR 99/month**: Everything in Pro plus REST API, embeddable viewer, lead capture, CRM, Site Planning (parcel yield, typologies, parking, zoning check, DXF export), 14-day weather forecast, commercial use rights, unlimited panels and objects.
- **Enterprise -- Contact sales**: Custom API quotas, SSO, 16-day weather forecast, dedicated support, SLA.

## Technical Details

- Works in any modern browser (Chrome, Firefox, Edge, Safari) with WebGL support
- No plugins, downloads, or installation required
- 3D models powered by Google 3D Tiles (photorealistic)
- Solar data from PVGIS (European Commission satellite irradiance database)
- Seasonal baselines from NASA POWER (22-year climatology)
- Hourly weather forecasts from Open-Meteo, used under CC BY 4.0
- Covers every location on Earth
- Available in 18 languages: English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Czech, Croatian, Hungarian, Greek, Japanese, Chinese, Korean, Arabic, Russian, Romanian
- Supports 29 currencies for cost calculations

## Documentation

- [LLM Product Overview](https://suntrace3d.com/llms.txt): This file
- [LLM Agent Integration Guide](https://suntrace3d.com/llms-agent.txt): How AI agents can integrate with SunTrace3D to create solar analysis sessions
- [LLM Documentation (full)](https://suntrace3d.com/llms-full.txt): Complete user guide + API reference + agent integration in a single file
- [API Reference (Markdown)](https://suntrace3d.com/docs/api-reference.md): Full API documentation including Partner API
- [User Guide (Markdown)](https://suntrace3d.com/docs/user-guide.md): Complete user guide (including Site Planning, sections 54-62)
- [Interactive API Docs](https://suntrace3d.com/docs/api): Interactive API documentation with code examples


---

# SunTrace3D -- AI Agent Integration Guide

> This document explains how AI agents (chatbots, virtual assistants, MCP tools) can integrate with SunTrace3D to create solar panel analysis sessions for users. No API key required.

## Overview

AI agents can guide users through solar panel analysis by creating sessions that pre-configure the Solar Panel Wizard. The agent creates a session via API, receives a viewer URL, and sends it to the user. When the user opens the link, a 3D model generates (~1-2 minutes, loading animation shown) and the wizard opens with pre-configured settings.

## How It Works

1. **Agent creates a session** via `POST https://suntrace3d.com/api/mcp-sessions` with location, wizard goal, and optional roof coordinates
2. **Agent sends the `viewerUrl`** from the response to the user
3. User clicks the link -> model generates (~1-2 min) -> wizard opens with pre-configured settings

## Quick Start (Python)

```python
import requests

data = requests.post("https://suntrace3d.com/api/mcp-sessions", json={
    "agentName": "MyBot",
    "latitude": 48.8566,
    "longitude": 2.3522,
    "wizardGoal": "maximize_energy",
    "roofLat": 48.8568,
    "roofLng": 2.3520,
}).json()

print(f"Send to user: {data['viewerUrl']}")
```

## Quick Start (JavaScript)

```javascript
const res = await fetch("https://suntrace3d.com/api/mcp-sessions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    agentName: "MyBot",
    latitude: 48.8566,
    longitude: 2.3522,
    wizardGoal: "maximize_energy",
    roofLat: 48.8568,
    roofLng: 2.3520,
  }),
});
const data = await res.json();
console.log(`Send to user: ${data.viewerUrl}`);
```

## Simplest Integration (No API Call)

Construct a URL directly -- no session creation needed:

`https://suntrace3d.com/viewer?lat=48.8566&lng=2.3522&wizard=maximize_energy`

This skips session tracking but still opens the viewer with the wizard pre-configured.

## API Reference

### Create Session

`POST https://suntrace3d.com/api/mcp-sessions`

**Request Body (JSON):**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agentName` | string | Yes | Your agent/bot name (max 100 chars) |
| `latitude` | number | Yes | Location center latitude |
| `longitude` | number | Yes | Location center longitude |
| `wizardGoal` | string | No | `maximize_energy`, `cover_bill`, `maximize_roi`, `environmental` |
| `wizardKwh` | number | No | Monthly kWh consumption (required when `wizardGoal` is `cover_bill`) |
| `roofLat` | number | No | Precise roof latitude for auto-click |
| `roofLng` | number | No | Precise roof longitude for auto-click |

**Response (JSON):**

| Field | Description |
|-------|-------------|
| `sessionId` | Unique session identifier |
| `viewerUrl` | Full URL to send to the user |
| `status` | `created` or `model_ready` (if SD model already cached) |
| `modelStatus` | `not_generated`, `processing`, or `ready` |
| `agentName` | Your agent name (echoed back) |
| `detectedPlatform` | Detected AI platform (e.g. `openai`, `anthropic`, `unknown`) |

**Response Headers:**

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests per window |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |

### Check Session Status

`GET https://suntrace3d.com/api/mcp-sessions/{sessionId}`

Returns the current session state including `status`, `modelStatus`, panel data (if placed), and energy results (if calculated).

## Wizard Goals

| Goal | Behavior |
|------|----------|
| `maximize_energy` | Fill the entire roof surface with panels for maximum annual kWh |
| `cover_bill` | Place enough panels to match the user's monthly electricity consumption (`wizardKwh` required) |
| `maximize_roi` | Place panels optimizing for fastest payback period |
| `environmental` | Maximize CO2 offset |

## Rate Limits

Requests are rate-limited per IP address. Known AI platform IPs (OpenAI, Anthropic) receive higher limits.

| Tier | Limit | Who |
|------|-------|-----|
| Whitelisted | 100/hr | Requests from known AI platform IP ranges (OpenAI, Anthropic) |
| Standard | 10/hr | Requests with recognized AI User-Agent but unverified IP |
| Unknown | 5/hr | All other requests |

When the rate limit is exceeded, the API returns HTTP 429 with `X-RateLimit-*` headers indicating when to retry.

## Important Notes

- **No pre-generation**: The 3D model generates when the user opens the link (~1-2 min). Pro users automatically get HD quality; free users get SD.
- **Pro tier required**: The Solar Panel Wizard requires a Pro subscription (EUR 9/mo). Free users see an upgrade prompt when the wizard tries to open.
- **Auto-click**: When `roofLat`/`roofLng` are provided, the system auto-detects the roof surface. If detection misses, the user clicks manually.
- **Session expiry**: Sessions expire after 48 hours.
- **No API key**: The MCP sessions endpoint does not require authentication -- only rate limiting applies.
- **Weekly forecast after the session**: A user who signs in and keeps the location can receive the week-ahead forecast for that roof every week by email and/or browser push notification, timed to their own activity, without opening the app again (Account -> Preferences; see https://suntrace3d.com/docs#weekly-digest). Agents cannot subscribe a user to it -- the user turns it on themselves.
- **Site Planning is not an agent session**: Sessions only drive the Solar Panel Wizard. For site feasibility (parcel yield, parking, zoning check), send the user a viewer link with `vertical=site`, e.g. `https://suntrace3d.com/viewer?lat=38.889&lng=-77.026&vertical=site`. It opens the Site Planning panel (Business plan or higher; others see an upgrade prompt) and the user draws the parcel. See https://suntrace3d.com/docs#site-planning.

## Documentation

- [LLM Product Overview](https://suntrace3d.com/llms.txt): What SunTrace3D is and what it can do
- [LLM Agent Integration Guide](https://suntrace3d.com/llms-agent.txt): This file
- [LLM Documentation (full)](https://suntrace3d.com/llms-full.txt): Complete user guide + API reference + agent integration in a single file
- [API Reference (Markdown)](https://suntrace3d.com/docs/api-reference.md): Full API documentation including Partner API
- [Interactive API Docs](https://suntrace3d.com/docs/api): Interactive API documentation with code examples


---

# Complete User Guide

# SunTrace3D User Guide

> Machine-readable documentation for SunTrace3D — a browser-based 3D solar analysis tool.
> Interactive version: [https://suntrace3d.com/docs](https://suntrace3d.com/docs)

---

## Table of Contents

### Getting Started
1. [Getting Started](#1-getting-started)
2. [3D Navigation Controls](#2-3d-navigation-controls)
3. [Searching for Locations](#3-searching-for-locations)

### Sun & Shadows
4. [Shadow Simulation](#4-shadow-simulation)
5. [Sun Path Visualization](#5-sun-path-visualization)

### Solar Panels
6. [Solar Panel Placement](#6-solar-panel-placement)
7. [Shadow Analysis](#7-shadow-analysis)
8. [Energy Yield Analysis](#8-energy-yield-analysis)
71. [Weather Forecast](#71-weather-forecast)
73. [Weekly Forecast by Email and Notification](#73-weekly-forecast-by-email-and-notification)

### Quality & Views
9. [SD & HD Quality Modes](#9-sd--hd-quality-modes)
10. [Compass & Orientation](#10-compass--orientation)
23. [Standard & Realistic Models](#23-standard--realistic-models)
52. [Ambient Life](#52-ambient-life)

### Build Mode
11. [Building Placement](#11-building-placement-build-mode)
12. [Scene Objects & Landscaping](#12-scene-objects--landscaping)
13. [Bulldozer Tool](#13-bulldozer-tool)
51. [Draw a House](#51-draw-a-house)

### Garden & Heatmap
14. [Sunlight Heatmap](#14-sunlight-heatmap)
15. [Garden Planner](#15-garden-planner)

### Analysis & Reports
16. [Climate Data](#16-climate-data)
17. [Installation Cost & Get Quote](#17-installation-cost--get-quote)
18. [Solar Impact](#18-solar-impact)
19. [Site Report](#19-site-report)

### Tools & Navigation
20. [Keyboard Shortcuts](#20-keyboard-shortcuts)
21. [Measurement Tool](#21-measurement-tool)
22. [Points of Interest](#22-points-of-interest)
50. [Undo, Redo & Multi-Select](#50-undo-redo--multi-select)

### Account & Projects
24. [Account & Subscription](#24-account--subscription)
25. [Project Management](#25-project-management)
26. [Importing 3D Models](#26-importing-3d-models)
53. [Share for Review](#53-share-for-review)
63. [Team Workspace](#63-team-workspace)
64. [Branded Proposals](#64-branded-proposals)
65. [Electronic Signature](#65-electronic-signature)
66. [From Feedback to Signature](#66-from-feedback-to-signature)

### Industry Verticals
27. [Right-to-Light Compliance](#27-right-to-light-compliance)
28. [Urban Heat Analysis](#28-urban-heat-analysis)
29. [Film & Photography Tools](#29-film--photography-tools)
30. [Real Estate Analysis](#30-real-estate-analysis)
31. [Agriculture & Crop Planning](#31-agriculture--crop-planning)
32. [Live Events & Outdoor Hospitality](#32-live-events--outdoor-hospitality)

### Automated Design
33. [Solar Wizard](#33-solar-wizard)
34. [Ground Mount Arrays](#34-ground-mount-arrays)
35. [Draw Tool](#35-draw-tool)
36. [3D Model Library](#36-3d-model-library)

### Engineering & Design
37. [Module & Inverter Catalog](#37-module--inverter-catalog)
38. [String Planning](#38-string-planning)
39. [Single-Line Diagram](#39-single-line-diagram)
40. [Cable Sizing](#40-cable-sizing)
41. [Self-Consumption Analysis](#41-self-consumption-analysis)
42. [Battery Storage Simulation](#42-battery-storage-simulation)
43. [Bill of Materials](#43-bill-of-materials)
44. [PVsyst Export](#44-pvsyst-export)

### Performance Visualization
45. [Panel Irradiance Heatmap](#45-panel-irradiance-heatmap)
46. [Loss Waterfall Chart](#46-loss-waterfall-chart)
47. [Energy System Dashboard](#47-energy-system-dashboard)

### Business Tools
48. [CRM Platform](#48-crm-platform)
49. [PDF Quotes](#49-pdf-quotes)
67. [From Prospect to Signed Deal](#67-from-prospect-to-signed-deal)

### Regulatory
68. [German Regulatory Pack](#68-german-regulatory-pack)
69. [Grid Compliance Pre-Check](#69-grid-compliance-pre-check)
70. [Tenant Electricity (Mieterstrom)](#70-tenant-electricity-mieterstrom)

### Site Planning
54. [Plan Mode (2D)](#54-plan-mode-2d)
55. [Site Planning Overview](#55-site-planning-overview)
56. [Guided Start](#56-guided-start)
57. [Parcel & Setbacks](#57-parcel--setbacks)
58. [Regions & Schemes](#58-regions--schemes)
59. [Typologies & Unit Mix](#59-typologies--unit-mix)
60. [Parking & Circulation](#60-parking--circulation)
61. [Zoning & Results](#61-zoning--results)
62. [Options, Data Layers & Export](#62-options-data-layers--export)

---

## 1. Getting Started

SunTrace3D is a browser-based 3D solar analysis tool. No installation, plugins, or sign-up is required.

### Quick Start

1. **Open the Viewer** — Navigate to `/viewer`. The default demo location (Pula, Croatia) loads automatically with a photorealistic 3D model.
2. **Search a Location** — Use the search bar in the header to find any address worldwide. The 3D model updates instantly.
3. **Explore Shadows** — Use the time slider at the bottom to see how shadows change throughout the day. Pick any date with the date picker in the header.

### System Requirements

- Modern web browser with WebGL support (Chrome, Firefox, Edge, Safari)
- No plugins or extensions required
- Works on desktop and mobile devices

---

## 2. 3D Navigation Controls

### Desktop (Mouse)

| Action | Control |
|--------|---------|
| Orbit / rotate camera | Left click + drag |
| Pan camera (move sideways/up-down) | Right click + drag |
| Zoom in/out | Scroll wheel |

### Mobile (Touch)

| Action | Control |
|--------|---------|
| Orbit / rotate camera | One finger drag |
| Pan camera | Two finger drag |
| Zoom in/out | Pinch gesture |

> **Tip:** Press `N` to switch to Navigate mode at any time. In Navigate mode, clicking the scene orbits the camera rather than placing objects.

---

## 3. Searching for Locations

The location search bar in the header converts addresses to coordinates. Type any address, city name, or landmark and the system finds the location instantly.

### How to Search

1. Type an address, city name, or landmark (e.g., "Colosseum, Rome" or "221B Baker Street, London")
2. Select a result from the dropdown suggestions
3. The 3D model loads instantly for the selected location
4. The URL updates with coordinates — shareable and bookmarkable

### URL Format

Locations can be shared via URL parameters:
```
https://suntrace3d.com/viewer?lat=44.8699&lng=13.8420
```

---

## 4. Shadow Simulation

SunTrace3D calculates accurate sun positions based on latitude, longitude, date, and time.

### Controls

- **Time Slider** — Horizontal slider at the bottom of the viewer. Scrub through 24 hours to watch shadows sweep across buildings.
- **Date Picker** — In the header. Select any date to see seasonal shadow changes.
- **Sun Animation** — Press the play button or hit `Space` to animate shadows through the day automatically.

### Understanding Shadows

- Shadow length and direction depend on the sun's altitude (height above horizon) and azimuth (compass bearing)
- In the Northern Hemisphere, shadows point north at solar noon
- Shadows are longest at sunrise and sunset, shortest at solar noon
- In winter, shadows are longer because the sun stays lower in the sky

---

## 5. Sun Path Visualization

The sun path arc shows the complete trajectory of the sun across the sky for the selected date.

### Visual Elements

| Element | Description |
|---------|-------------|
| Yellow circle | Current sun position marker |
| Orange arc | Sun's path from sunrise (east) to sunset (west) |
| Blue pin | Center marker of your selected location |
| Directional light | Casts shadows opposite to the sun position |

---

## 6. Solar Panel Placement

Place virtual solar panels on any rooftop in the 3D model to calculate energy yield.

### Steps

1. **Activate panel mode** — Click the solar panel button in the toolbar (bottom-left) or press `P`
2. **Click on a rooftop** — A virtual solar panel appears at the clicked location
3. **Adjust tilt** — Use the tilt slider in the sidebar to set the panel angle
4. **Set orientation** — Adjust the azimuth to face the optimal direction
5. **Configure size** — Set the panel area (m²) and efficiency in the sidebar
6. **View estimates** — The solar dashboard automatically calculates annual energy yield

### Orientation Tip

In the Northern Hemisphere, south-facing panels (azimuth 180°) receive the most sunlight. Use the compass overlay to verify your panel orientation.

### Rectangle Array Placement

Fill an entire roof section with a grid of panels in one click.

1. **Activate rectangle mode** — Press `R` or click the grid icon in the panel toolbar
2. **Define the area** — Click two opposite corners of the rectangle you want to fill
3. **Adjust spacing** — Use the gap slider to control the spacing between panels in the array
4. **Remove panels** — Use eraser mode (`E`) to remove individual panels from the array

---

## 7. Shadow Analysis

SunTrace3D automatically analyzes shading from surrounding buildings for every solar panel you place. The system simulates approximately 154 sun positions throughout the year to calculate how much each panel is blocked by nearby geometry.

### How Shadow Analysis Works

1. **Automatic detection** — Shadow analysis begins automatically when you place or move a panel. A spinning indicator shows while the calculation runs.
2. **Annual sun sampling** — The system simulates sun positions every 15 days throughout the year, sampling every 2 hours during daylight hours — approximately 154 positions in total.
3. **3D raycasting** — For each sun position, a ray is cast from the panel toward the sun. If a building or other geometry blocks the ray, that time slot is counted as shaded.
4. **Weighted calculation** — Higher sun positions contribute more weight because the sun delivers more energy at steeper angles. Midday shading therefore impacts the result more than dawn or dusk shading.

### How Shading Affects Energy Yield

The shading loss percentage is applied as a direct multiplier to the energy yield: a panel with 25% shading loss produces 25% less energy than an identical unshaded panel. Monthly estimates also reflect this — winter months may show higher losses when the sun is lower and more easily blocked by buildings.

### Shading Indicators

| Color | Meaning |
|-------|---------|
| Green (0–10%) | Minimal shading, excellent placement |
| Amber (10–30%) | Moderate shading, consider repositioning |
| Red (>30%) | Heavy shading, significantly reduced yield |

---

## 8. Energy Yield Analysis

Energy yield is estimated using PVGIS (Photovoltaic Geographical Information System), a satellite-based solar irradiance database maintained by the European Commission.

### Calculated Values

- **Annual energy yield** (kWh)
- **Peak power output** (kW)
- **Specific yield** (kWh/kWp)
- **Monthly energy production** breakdown (12 values)
- **Shading loss factor**
- **System losses** (inverter + wiring, default 14%)

### Input Parameters

| Parameter | Range | Description |
|-----------|-------|-------------|
| Tilt angle | 0° – 90° | Panel tilt from horizontal |
| Azimuth | 0° – 360° | Compass direction (0=North, 180=South) |
| Panel area | m² | Total panel surface area |
| Efficiency | 0.0 – 1.0 | Panel conversion efficiency (typically 0.18–0.22) |
| Location | auto | Latitude/longitude from selected location |

### Data Source

PVGIS uses satellite imagery and meteorological data averaged over many years. It accounts for typical weather patterns, cloud cover, and atmospheric conditions. The solar constant used is 1361 W/m².

---

## 9. SD & HD Quality Modes

### Standard Detail (SD) — Free

- Available without an account
- Moderate geometric and texture detail
- Loads instantly — no generation wait time

### High Definition (HD) — Pro ($9/month)

- Requires Pro subscription
- Photorealistic models with maximum texture and geometric detail
- Individual building features, vegetation, and street-level detail visible

---

## 10. Compass & Orientation

The compass overlay shows true north relative to your current camera angle.

### Key Facts

- The compass rotates as you orbit the 3D model, always pointing toward true north
- In the Northern Hemisphere, south-facing panels (azimuth=180°) receive the most sunlight
- Use the compass to verify panel azimuth when placing solar panels

---

## 11. Building Placement (Build Mode)

Place procedural buildings into the 3D scene to study shadow impact from proposed developments. Buildings cast and receive shadows just like real-world models.

### How to Use

1. **Activate Build mode** — Click the Build button in the toolbar or press `B`. The sidebar opens automatically.
2. **Choose a building type** — Select from: House, Apartment, Commercial, Townhouse, Warehouse.
3. **Configure dimensions** — Adjust floors, floor height, width, and depth with the sliders.
4. **Select roof type** — Choose Flat, Gable, Hip, or Mansard with pitch control (15–60°).
5. **Set colors and place** — Pick wall and roof colors, then click on the ground in the 3D scene to place.

### Building Types

| Type | Default Floors | Default Size | Default Roof |
|------|---------------|-------------|-------------|
| House | 2 | 10 × 8 m | Gable 35° |
| Apartment | 5 | 20 × 12 m | Flat |
| Commercial | 3 | 25 × 15 m | Flat |
| Townhouse | 3 | 6 × 12 m | Gable 40° |
| Warehouse | 1 | 30 × 20 m | Flat |

### Dimension Ranges

| Parameter | Min | Max | Step |
|-----------|-----|-----|------|
| Floors | 1 | 20 | 1 |
| Floor Height | 2.5 m | 4.0 m | 0.1 m |
| Width | 4 m | 50 m | 1 m |
| Depth | 4 m | 50 m | 1 m |
| Roof Pitch | 15° | 60° | 1° |

### Roof Types

| Type | Description |
|------|-------------|
| Flat | No pitch, flat top with parapet |
| Gable | Classic two-slope "A" shape |
| Hip | Four slopes, all sides descend from ridge |
| Mansard | Steep lower slope with shallow upper section |

### Selected Building Controls

| Control | Range | Step |
|---------|-------|------|
| Y-offset | -10 m to +10 m | 0.5 m |
| Rotation | 0° to 345° | 15° |

---

## 12. Scene Objects & Landscaping

Build mode includes a Scene Objects panel for adding trees, fences, pergolas, obstacles (chimneys, poles, cylinders), and event assets (stages, tents, chairs, tables, speakers, LED walls, trusses, barriers) to the 3D scene. These objects cast and receive shadows, letting you study how landscaping, rooftop features, and event infrastructure affect solar panel performance and shade coverage.

### How to Place

1. **Enter Build mode** — Click the Build button in the toolbar or press `B`. The sidebar shows category tabs at the top: Buildings, Trees, Fences, Pergolas, Obstacles, and Events.
2. **Choose a category and style** — Click a category tab, then select a shape or style.
3. **Adjust dimensions and color** — Use the sliders to set height, width, depth, or canopy diameter. Pick a color from the swatch palette. Trees can be set as deciduous (seasonal leaf loss) or evergreen.
4. **Click to place** — Click on the ground or on a building surface to place the object. Once placed, click to select it, then drag to reposition, use `[` `]` to rotate, or press `Delete` to remove.

### Object Categories

| Category | Shapes/Styles | Key Parameters |
|----------|--------------|----------------|
| Trees | Round, Oval, Conifer, Palm, Columnar | Height, canopy diameter, trunk height, deciduous/evergreen |
| Fences | Wood, Brick, Concrete, Hedge | Length, height, thickness |
| Pergolas | Flat, Louvered, Awning | Width, depth, height, tilt |
| Obstacles | Box, Cylinder, Chimney, Pole | Width, depth, height |
| Events | Pop-up Tent, Stage, Chair, Table, Speaker Stack, LED Wall, Lighting Truss, Barrier | Width, depth, height |

### Shadow Interaction

All scene objects participate in the shadow simulation. Trees and fences cast realistic shadows that affect solar panels — the shadow analysis automatically accounts for these obstructions when calculating shading loss.

### Building & Object Attachment

Objects placed on a building surface automatically attach to that building. When you rotate or move the building, attached objects move with it. Drag an object off the building to detach it.

Objects can also attach to other scene objects. For example, placing speakers on a stage causes them to move and rotate with the stage when it is repositioned. Deleting a parent object also removes all attached children.

---

## 13. Bulldozer Tool

The Bulldozer tool lets you clear vegetation, trees, and other unwanted geometry from the 3D scene. This is useful for creating clean building sites or removing obstructions that block your view or shadow analysis.

### How to Use

1. **Activate Bulldozer** — Click the Shovel button in the sidebar toolbar. The button turns red when active.
2. **Choose a shape** — Select Circle or Rectangle for the clearing zone shape.
3. **Set dimensions** — Adjust the radius (5–50 m for circles) or width/depth (5–80 m for rectangles), height (5–200 m), and rotation (rectangles only).
4. **Click to place** — Click on the ground in the 3D scene to place a bulldozer zone. The zone appears as a semi-transparent volume that clips away 3D Tiles geometry inside it.

### Circle Zones

Circle zones clear a cylindrical area defined by radius and height. Use these for clearing individual trees or small clusters of vegetation around a specific point.

### Rectangle Zones

Rectangle zones clear a box-shaped area defined by width, depth, height, and rotation angle. Use these for clearing larger building sites or creating clean corridors.

### Managing Zones

- **Toggle zones** — Enable or disable individual zones without deleting them
- **Delete zones** — Remove specific zones from the scene
- **Clear all** — Remove all bulldozer zones at once

> **Tip:** The Bulldozer tool only affects the streamed 3D map geometry. It does not remove manually placed buildings, trees, or other scene objects.

> **Note:** Bulldozer zones are included in energy yield calculations. When you clear terrain beneath or near solar panels, the energy estimate automatically accounts for the changed shading environment.

---

## 14. Sunlight Heatmap

The Sunlight Heatmap visualizes how many hours of direct sunlight reach different areas of the ground throughout the day. This helps identify the best spots for solar panels, garden beds, or outdoor living areas.

### How to Use

1. **Open the Heatmap panel** — Click the grid icon (Sunlight Heatmap) in the sidebar toolbar. Set the grid width and depth to define the analysis area.
2. **Toggle the heatmap on** — Click "Show Heatmap" to start the computation. The system calculates sun exposure for each grid cell by simulating sun positions throughout the day.
3. **Adjust settings** — Use the month selector to view sun hours for a specific month or annual average. Adjust opacity to see through the heatmap overlay.

### Color Scale

| Color | Meaning |
|-------|---------|
| Purple (#4A148C) | Full shade — less than 1 hour of direct sun |
| Blue (#1565C0) | Partial shade — approximately 3 hours of sun |
| Green (#2E7D32) | Moderate sun — approximately 6 hours of sun |
| Yellow (#F9A825) | Full sun — 8+ hours of direct sunlight |

### Grid Size

- **Free users**: Grid size up to 20 × 20 meters
- **Pro users**: Grid size up to 100 × 100 meters for comprehensive site analysis

---

## 15. Garden Planner

The Garden Planner helps you choose the right plants for your garden beds based on actual sunlight data from the heatmap. It cross-references sun exposure at each bed location with plant requirements to determine compatibility.

### How to Use

1. **Enable the heatmap first** — The Garden Planner needs sun exposure data. Open the Sunlight Heatmap panel and toggle the heatmap on.
2. **Browse the plant database** — Search through 50+ plants organized into 5 categories: Vegetables, Herbs, Fruits, Flowers, and Shrubs. Each plant shows its sun requirements (hours/day).
3. **Select a bed shape** — Choose Rectangle, Circle, or L-shape for your garden bed. Adjust width, depth, and height (raised bed height) with the sliders.
4. **Place and check compatibility** — Click on the ground to place a garden bed. The system automatically queries the heatmap data at the bed location and shows sun compatibility feedback.

### Plant Categories

| Category | Examples |
|----------|---------|
| Vegetables | Tomatoes, peppers, lettuce, carrots, zucchini |
| Herbs | Basil, rosemary, thyme, mint, parsley |
| Fruits | Strawberries, blueberries, raspberries |
| Flowers | Sunflowers, lavender, marigolds, roses |
| Shrubs | Hydrangea, boxwood, holly |

### Compatibility Levels

| Level | Color | Meaning |
|-------|-------|---------|
| Ideal | Green | The bed receives enough sun for this plant to thrive |
| Acceptable | Amber | The plant may grow but could struggle — borderline sun hours |
| Not Suitable | Red | The bed does not receive enough (or receives too much) sunlight for this plant |

### Sun Zones

The system classifies each bed into a sun zone based on daily sun hours:
- **Full Sun** (6+ hours) — Most vegetables, fruits, and sun-loving flowers
- **Partial Shade** (3–6 hours) — Herbs, leafy greens, some flowers
- **Full Shade** (<3 hours) — Shade-tolerant plants only

---

## 16. Climate Data

The Climate Data panel shows location-specific weather and atmospheric conditions that affect solar panel performance. It appears in the Solar Analysis sidebar once you have panels placed in the scene.

### Metrics

| Metric | Card Color | Description |
|--------|-----------|-------------|
| Cloud Loss | Blue | Percentage of solar energy lost to cloud cover at this location. Lower is better for solar. |
| Average Temperature | Orange | Mean annual temperature in °C. Extreme heat can reduce panel efficiency. |
| Heat Loss | Red | Estimated efficiency loss due to panel overheating above 25°C (the standard test condition). |

### Monthly Clearness Sparkline

A bar chart shows the monthly clearness index (Kc) across all 12 months (Jan–Dec). Bar colors indicate sky conditions:
- **Green bars** — Clear skies (Kc > 0.5)
- **Yellow bars** — Mixed/partly cloudy (Kc 0.3–0.5)
- **Blue bars** — Cloudy (Kc < 0.3)

### Data Source

Climate data is sourced from NASA POWER (CERES SYN1deg + MERRA-2 reanalysis), providing satellite-derived long-term averages for any location on Earth.

---

## 17. Installation Cost & Get Quote

When you place solar panels, SunTrace3D automatically estimates the installation cost, annual electricity savings, and payback period based on regional pricing data.

### Cost Breakdown

The Installation Cost section in the sidebar shows a detailed breakdown including panel cost, installation labor, and inverter/balance-of-system costs. Prices are adjusted to your region and displayed in your selected currency.

### Annual Savings & Payback

Based on the estimated annual energy yield and local electricity prices, SunTrace3D calculates your annual savings and the number of years until the system pays for itself.

### Government Incentives

Where available, the calculator shows estimated government subsidies, tax credits, or feed-in tariffs that reduce your effective cost and shorten the payback period.

### Request a Quote

Scroll to the foot of the Solar sidebar and click "Get Free Solar Quotes" to submit your solar analysis to local installers. The form pre-fills with your system specs, location, and estimated costs for a personalized proposal.

The button beside "Site Report" (and at the top of the Solar sidebar) is "Get Weekly Forecast": one click subscribes this browser to the [weekly forecast notification](#73-weekly-forecast-by-email-and-notification) for the roof on screen.

---

## 18. Solar Impact

The Solar Impact section visualizes the environmental benefits of your solar panel system. It appears in the sidebar whenever you have panels placed in the scene.

### CO₂ Offset

See how many kilograms of CO₂ your system would avoid annually. This is calculated from your estimated energy yield and regional grid emission factors.

### Appliances Powered

A visual grid of 9 common household items shows which appliances your system can power — from light bulbs and laptops to refrigerators, air conditioning, and electric vehicles. Powered items light up in green.

### Shading & Orientation Ratings

Color-coded badges indicate your system's shading status and orientation quality:

| Badge | Meaning |
|-------|---------|
| Green | No shading detected, excellent sun exposure |
| Amber | Moderate shading (10–30%), consider repositioning panels |
| Red | Heavy shading (over 30%), panels may underperform |

---

## 19. Site Report

Generate a professional PDF site report summarizing your entire solar analysis. The report includes 3D views, system specifications, energy yield estimates, financial analysis, and environmental impact — ready to share with clients or installers.

### How to Generate

1. **Place solar panels** — Set up your solar panel installation in the 3D viewer. The report button appears once you have panels placed with energy yield results.
2. **Click "Site Report"** — Click the blue Site Report button at the bottom of the viewer. Sign in if prompted — a free account is required.
3. **Fill in details** — Optionally enter your company name, client name, upload a company logo, and add notes. You can also adjust the total investment amount.
4. **Generate and download** — Click "Generate PDF Report". The system captures 3D views of your scene, builds the report, and offers a PDF download.

### What's in the Report

- 3D perspective and top-down views of the solar installation
- System summary: panel count, peak power, annual yield, orientation, shading loss
- Detailed system specs: panel type, efficiency, dimensions, tilt, azimuth
- Monthly energy production chart
- Financial analysis: cost breakdown, payback period, government incentives
- Household appliances the system can power
- Custom branding with company logo and installer details

### Custom Branding

Upload your company logo and enter your company name to create branded reports. The logo appears in the report header alongside the SunTrace3D branding — perfect for solar installers sending proposals to clients.

---

## 20. Keyboard Shortcuts

Keyboard shortcuts work when the viewer is focused and no text input is active.

### Mode Switching & Time

| Key | Action |
|-----|--------|
| `N` | Navigate mode |
| `P` | Place Panels mode |
| `B` | Build mode |
| `H` | Draw a House mode |
| `D` | Draw tool |
| `M` | Measurement tool |
| `W` | Solar Wizard (Pro+) |
| `Space` | Play / pause time animation |
| `←` `→` | Skip time back/forward 15 minutes |

### Build Mode (selected building/object)

| Key | Action |
|-----|--------|
| `[` | Rotate selected building -15° |
| `]` | Rotate selected building +15° |
| `Delete` / `Backspace` | Remove selected building |
| `↑` Arrow Up | Raise selected building +0.5 m |
| `↓` Arrow Down | Lower selected building -0.5 m |

### Panel Mode (selected panel)

| Key | Action |
|-----|--------|
| `[` | Rotate selected panel -15° |
| `]` | Rotate selected panel +15° |
| `Delete` / `Backspace` | Remove selected panel |
| `R` | Toggle Rectangle placement mode |
| `E` | Toggle Eraser mode |

> **Tip:** On mobile and touch devices, all building and panel controls (rotation, vertical offset, delete) are available as sliders and buttons in the sidebar.

---

## 21. Measurement Tool

Measure real-world distances directly in the 3D scene. The measurement tool calculates the straight-line distance between any two points you click.

### How to Measure Distances

1. **Activate measurement mode** — Click the ruler button in the sidebar toolbar (or press M). Your cursor changes to a crosshair.
2. **Place the first point** — Click anywhere on the 3D scene to set the starting point. A cyan marker appears.
3. **Place the second point** — Click a second location. A line connects the two points with the distance displayed in meters.
4. **Add more measurements** — Keep clicking to add additional measurements. Click on any measurement to select it, then press Delete to remove it.

### Measurement Tips

- Measurements work on terrain, buildings, and rooftops
- Press Escape to cancel a pending measurement point
- Use the Clear button to remove all measurements at once

---

## 22. Points of Interest

Toggle Points of Interest (POI) to discover nearby amenities and landmarks overlaid on the 3D map.

### How to Use

1. **Toggle POI on** — Click the map pin button in the toolbar to enable POI markers. Nearby locations load automatically based on your current map center.
2. **Browse markers** — Markers appear at real-world positions in the 3D scene. Zoom in to see names and details; zoom out and they simplify to compact icons.
3. **Click to highlight** — Click any POI marker to highlight it and see more details. Click again to deselect.

### Available Categories

Education, Healthcare, Shopping, Transport, Recreation, Dining, and Services — covering schools, hospitals, supermarkets, bus stops, parks, restaurants, and more.

---

## 23. Standard & Realistic Models

SunTrace3D offers two types of 3D models. The model type toggle in the viewer toolbar lets you switch between them. Switching regenerates the model for your current location.

### Standard 3D Model

Block-style buildings with flat roofs extruded from footprint data. Loads quickly and provides accurate building placement and shadows for solar analysis.

### Realistic 3D Model

Detailed building geometry with accurate roof pitches, chimneys, and textured facades. Provides the most lifelike representation of your site.

### Automatic fallback

If the realistic model is unavailable for your location, the standard model is shown automatically. A small indicator appears next to the toggle when this happens.

---

## 24. Account & Subscription

SunTrace3D works without an account for basic shadow simulation and solar analysis. Create a free account to save your work, upgrade to Pro for HD models and unlimited tools, or choose Business for API access and embeddable viewers.

### Free Account

- SD quality models
- Full shadow simulation
- Up to 8 solar panels
- Up to 5 scene objects
- Up to 3 custom buildings

### Pro ($9/month)

- HD photorealistic models
- Unlimited panels, objects & buildings
- Save projects & import 3D models
- Compliance reports & photo export
- Commercial use license (no watermark)

### Business ($99/month)

- Everything in Pro, plus:
- Export the full 3D scene as GLB/OBJ (terrain, panels, buildings, objects, imported models)
- Embeddable 3D viewer
- Lead capture & routing
- API access (500 models/month)
- Real estate scoring

### Enterprise (custom pricing)

- Everything in Business, plus:
- Custom API volume
- White-label branding
- CRM integrations
- Dedicated support & SLA

### Subscription Management

Access account settings and the subscription portal via the user menu in the viewer header.

---

## 25. Project Management

Save and load complete scene setups. Requires a free account.

### What's Saved

- Location (latitude, longitude, and display name)
- Quality mode (SD or HD)
- All solar panels (position, tilt, azimuth, area, efficiency)
- All placed buildings (position, rotation, Y-offset, type, dimensions, colors)
- All scene objects (trees, fences, pergolas, obstacles, event assets)
- Imported 3D models (position, rotation, scale)
- Date and time of day

### How to Save

1. Sign in to your account
2. Open the sidebar (sun icon, top-right)
3. Scroll to the "Projects" section
4. Click "Save current scene" and enter a project name

### How to Load

1. Open the sidebar
2. Find the project in the list
3. Click the project name or the folder icon to load
4. All scene state is restored automatically

### Deleting Projects

Hover over a project in the list and click the trash icon to delete it permanently.

### Unsaved Changes Guard

When you have unsaved changes (moved panels, added buildings, etc.) and try to navigate away or load a different project, a confirmation dialog appears warning you about unsaved work. You can choose to save your current scene, discard changes, or cancel the navigation.

---

## 26. Importing 3D Models

Import custom 3D models into your scene to accurately represent existing structures, machinery, or any object that affects shading on your solar panels.

### How to Import

1. **Switch to Build mode** — Press `B` or click the Build button in the toolbar to enter Build mode.
2. **Open the Import tab** — Click the Import tab (upload icon) in the Build panel sidebar.
3. **Upload your GLB file** — Drag and drop a `.glb` file onto the upload area, or click to browse. Maximum file size is 50 MB.
4. **Position the model** — The model appears at the scene origin. Use the Move, Rotate, and Scale buttons in the panel to switch gizmo modes, then drag the handles in the 3D view to position it precisely.
5. **Fine-tune with numbers** — Enter exact values in the Position (m), Rotation (°), and Scale fields for precise placement.

### File Requirements

Only `.glb` (binary glTF) files are supported. Maximum 50 MB per file. Models are stored securely in the cloud and load automatically when you reopen a saved project.

### Transform Gizmos

| Gizmo | Usage |
|-------|-------|
| Move | Drag the coloured arrows to reposition along X, Y, or Z axis |
| Rotate | Drag the rings to spin the model around each axis |
| Scale | Drag the handles to resize uniformly or per-axis |

> **Note:** 3D model import is a Pro feature. Upgrade to Pro to unlock custom model placement.

---

## 27. Right-to-Light Compliance

The Right-to-Light panel helps architects and urban planners assess whether a proposed development meets daylight access standards. Based on BRE 209 (Site Layout Planning for Daylight and Sunlight), it analyzes how much skylight and sunlight reaches neighboring windows.

### How to run a compliance check

1. **Switch to the Compliance vertical** — Select "Right-to-Light" from the industry dropdown in the top-left corner of the viewer.
2. **Add windows to analyze** — Click on building facades to place window markers. Each window is checked against BRE 209 vertical sky component (VSC) and annual probable sunlight hours (APSH) thresholds.
3. **Review compliance indicators** — Windows are color-coded: green (passes), amber (marginal), red (fails). The sidebar shows detailed metrics for each window.
4. **Generate a compliance report** — Export a PDF report with window-by-window analysis, compliance status, and 3D visualizations for planning submissions.

### Key Metrics

- **Vertical Sky Component (VSC):** Measures the amount of visible sky from a window point. BRE 209 recommends a minimum of 27% VSC for adequate daylight. Windows below this threshold are flagged.
- **Annual Probable Sunlight Hours (APSH):** Measures the percentage of annual sunlight hours a window receives compared to an unobstructed location. BRE 209 recommends at least 25% annual and 5% winter APSH.

> **Best practice:** Run compliance checks early in the design process. Small changes to building height, setback, or orientation can significantly improve daylight access to neighboring properties.

---

## 28. Urban Heat Analysis

The Urban Heat panel maps thermal exposure across urban areas. It analyzes how shade coverage, surface materials, and building geometry affect surface temperatures and pedestrian thermal comfort.

### How to analyze urban heat

1. **Switch to the Thermal vertical** — Select "Urban Heat" from the industry dropdown in the viewer toolbar.
2. **Enable the thermal overlay** — Toggle the heat map overlay to see color-coded surface temperature estimates across the scene, based on shade coverage and material albedo.
3. **Analyze pedestrian corridors** — Mark pedestrian paths to see shade coverage along walking routes. The panel shows the percentage of each corridor that is shaded during peak heat hours.

### Key Concepts

- **Material Albedo:** Different surfaces absorb and reflect heat differently. The material palette lets you assign albedo values (reflectivity) to roofs, pavements, and green spaces to model their thermal impact.
- **Thermal Comfort Zones:** The heat map identifies areas of thermal stress based on combined sun exposure, shade coverage, and wind exposure. Red zones indicate areas where pedestrians may experience heat discomfort during summer.

> **Mitigation strategies:** Use the scene objects tool to add trees and shade structures, then re-run the thermal analysis to see their cooling effect. Even small increases in shade coverage can significantly reduce surface temperatures.

---

## 29. Film & Photography Tools

The Film & Photography panel provides tools for planning shoots around natural light. Calculate golden hour and blue hour times, preview camera angles through virtual lenses, and bookmark lighting setups for location scouting.

### How to plan a shoot

1. **Switch to the Camera vertical** — Select "Film & Photo" from the industry dropdown in the viewer toolbar.
2. **Check golden hour times** — The sidebar shows exact golden hour and blue hour start/end times for the current date and location. Use the date picker to plan for future shoot dates.
3. **Place a virtual camera** — Click the camera placement button and click in the scene to position a virtual camera. Choose a focal length (24mm–200mm) to preview the frame.
4. **Bookmark your setup** — Save camera positions and lighting conditions as bookmarks. Jump between scouted viewpoints when comparing angles or planning multi-camera setups.

### Key Features

- **Lens Simulation:** The virtual camera previews the field of view for common focal lengths: 24mm (wide), 35mm (street), 50mm (standard), 85mm (portrait), and 200mm (telephoto). The preview updates in real-time as you reposition the camera.
- **Moon Position:** For night scene planning, the moon tracker shows moonrise, moonset, and current position. Useful for planning moonlit exterior shots or understanding ambient light conditions after sunset.

> **Location scouting workflow:** Search your location, set the date to your planned shoot day, scrub through the time slider to find the best lighting window, place your camera, and save the bookmark. On shoot day, reload the project to reference your planned angles.

---

## 30. Real Estate Analysis

The Real Estate panel provides tools for showcasing property sunlight exposure. Analyze window views, calculate balcony sun hours, and generate solar scores that quantify a property's energy potential for buyers.

### How to analyze a property

1. **Switch to the Real Estate vertical** — Select "Real Estate" from the industry dropdown in the viewer toolbar.
2. **Run a window view analysis** — Click on windows to preview the view from inside. The panel shows what residents will see, including surrounding buildings, vegetation, and sky exposure.
3. **Calculate balcony sun hours** — Mark balcony positions to see how many hours of direct sunlight they receive across different seasons. Great for marketing south-facing apartments.
4. **Generate a property sun score** — The solar score summarizes total sun exposure, shade risk, energy potential, and environmental benefits in a single shareable metric for property listings.

### Key Features

- **Window View Preview:** The view-from-window feature renders what residents will actually see from each window. This helps buyers understand sight lines, privacy, and natural light before visiting the property.
- **Balcony Calculator:** The balcony calculator shows monthly direct sunlight hours for any outdoor space. Summer vs. winter comparison helps buyers understand seasonal sun exposure for balconies, terraces, and patios.

> **Listing enhancement:** Include the property's solar score and sunlight metrics in your listing description. Properties with quantified sun exposure data generate more interest and can justify higher asking prices.

---

## 31. Agriculture & Crop Planning

The Agriculture panel provides tools for planning crop placement and greenhouse positioning based on actual sunlight data. Map sun exposure across your land, check crop suitability, and model light levels inside greenhouses.

### How to plan your farm layout

1. **Switch to the Agriculture vertical** — Select "Agriculture" from the industry dropdown in the viewer toolbar.
2. **Enable the sunlight heatmap** — Toggle the heatmap to see color-coded sun exposure across your land. Use the monthly view to track seasonal changes from planting through harvest.
3. **Check crop suitability** — Open the crop selector and choose a crop type. The suitability map highlights which areas of your property match the crop's sunlight and climate requirements.
4. **Configure greenhouses** — Place greenhouses in the scene, set glass transmission (30–95%), and see realistic interior light levels on the heatmap. Position them for maximum growing-season sunlight.

### Key Features

- **Slope & Aspect Analysis:** The terrain analysis shows slope angle and aspect direction across your property. South-facing slopes receive more sunlight, while steep north-facing slopes may be unsuitable for sun-loving crops.
- **Crop Suitability System:** Select a crop from the database (50+ species) to see a color-coded suitability map. Green zones have ideal sunlight and climate conditions, amber zones are acceptable, and red zones are unsuitable for that crop.

> **Seasonal planning:** Use the monthly heatmap to compare spring vs. summer sun exposure. Areas that get full sun in July may be partially shaded in April when you're starting seedlings — plan your layout around growing-season sunlight, not just midsummer.

---

## 32. Live Events & Outdoor Hospitality

The Live Events vertical helps event planners, festival producers, and venue managers design outdoor event layouts with accurate sun and shade simulation. Position stages, seating, tents, and production equipment in 3D, then scrub through the timeline to see exactly where shadows fall during every hour of the event.

### How to plan an event layout

1. **Switch to the Live Events vertical** — Select "Live Events" from the industry dropdown in the viewer toolbar, or visit the `/solutions/live-events` landing page and click "Try it now."
2. **Enter Build mode** — Click Build, then select the Events tab. Choose from 8 asset types: Pop-up Tent, Stage, Chair, Dining Table, Speaker Stack, LED Wall, Lighting Truss, or Barrier.
3. **Place and configure assets** — Adjust width, depth, and height with sliders. Pick a color from the swatch palette (white, black, wood, gold, red). Click on the ground or on another object to place.
4. **Stack objects** — Place speakers on a stage or lights on a truss. Stacked objects automatically move and rotate with their parent when repositioned.
5. **Check shadows throughout the day** — Use the time slider to scrub through the event day. Add timeline bookmarks at key moments (ceremony start, reception, golden hour) for quick comparison.

### Event Asset Types

| Asset | Default Size | Typical Use |
|-------|-------------|-------------|
| Pop-up Tent | 3 × 3 × 2.5 m | Guest shade, vendor booths |
| Stage | 6 × 4 × 1.2 m | Performances, presentations |
| Chair | 0.45 × 0.45 × 0.9 m | Guest seating |
| Dining Table | 1.8 × 0.75 × 0.75 m | Reception dining |
| Speaker Stack | 0.6 × 0.5 × 1 m | PA system, sound reinforcement |
| LED Wall | 4 × 0.3 × 2.5 m | Video screens, stage backdrops |
| Lighting Truss | 6 × 0.3 × 0.3 m | Overhead lighting rigs |
| Barrier | 2.2 × 0.4 × 1.1 m | Crowd control, perimeter fencing |

### Shadow Planning for Events

Use the shadow simulation to identify potential issues before the event day:

- **Guest comfort** — Check whether seating areas will be in direct sun during the event. Position tents over exposed seating or adjust layout timing.
- **Stage glare** — Verify that the sun won't be directly behind the audience (blinding performers) or behind the stage (washing out LED screens).
- **Golden hour** — Bookmark sunset time for photography-friendly moments. The sun path arc shows exactly where the sun will be.

> **Object stacking:** Speakers placed on a stage, lights hung from a truss, or any object placed on another object will automatically move and rotate together. Delete the parent to remove all attached children.

---

## 33. Solar Wizard

The Solar Wizard automatically detects roof surfaces and places an optimized solar panel layout with a single click. It analyzes shading across the year, avoids obstructed areas, and positions panels for maximum energy production — or to match your specific goal.

### How to Use

1. **Open the Wizard** — Switch to Place mode, then click "Solar Wizard" in the placement dropdown or press `W`. The wizard requires a paid plan (Pro or higher).
2. **Choose Your Goal** — Select from four optimization strategies: Maximize Energy fills the roof, Cover My Bill matches your monthly usage, Best ROI optimizes payback period, and Go Green maximizes environmental impact.
3. **Click a Roof Surface** — Click anywhere on a roof. The wizard automatically detects the surface boundary and scans the area — you'll see golden cells appear as the detection progresses.
4. **Watch the Placement** — Panels are placed one by one with a cinematic animation. The wizard selects positions with the lowest shading and groups them together for a clean, professional layout.
5. **Review & Keep** — Review the estimated annual yield, CO₂ offset, and bill coverage. Click "Keep Layout" to accept or "Start Over" to try a different roof or goal.
6. **Select Equipment** — After panel placement, the wizard guides you through equipment selection. An inverter is automatically sized to match your array's DC capacity — for larger systems, multiple inverters are recommended with balanced string distribution. Optionally add a battery, with capacity recommended based on your energy profile and plan tier.
7. **Final System Summary** — The final results screen shows your complete system at a glance: panel count, annual energy yield, selected inverter(s), battery capacity, CO₂ offset, and estimated bill coverage percentage. Click "Keep Layout" to commit the design or "Start Over" to try again.

### Optimization Goals

| Goal | Description |
|------|-------------|
| Maximize Energy | Places as many panels as possible on the detected surface for maximum annual energy generation |
| Cover My Bill | Enter your monthly electricity usage in kWh, and the wizard places just enough panels to offset it |
| Best ROI | Focuses on the least-shaded positions for the fastest return on investment |
| Go Green | Maximizes the number of panels to achieve the highest CO₂ offset and environmental impact |

### Automatic Equipment Sizing

The wizard auto-selects inverters from the CEC-certified catalog based on your panel array's total DC output. For systems exceeding a single inverter's capacity, it recommends multiple units with even string distribution. Battery recommendations are tier-gated — higher plans unlock larger storage options.

> **Tip:** After the wizard places panels, you can still manually adjust individual panels — drag them, rotate with `[` and `]` keys, or delete with the eraser tool.

---

## 34. Ground Mount Arrays

Ground mount arrays let you design solar installations on open terrain rather than rooftops. Draw a boundary polygon on the ground, configure tilt, azimuth, and row spacing, then instantly preview the panel layout before committing.

### How to Use

1. **Select Ground Mount mode** — Click the Ground Mount tool (`G`) in the toolbar to enter drawing mode. The configuration panel opens in the sidebar.
2. **Draw the boundary** — Click on the ground to place polygon vertices defining the array area. Close the shape by clicking near the first point — a yellow indicator appears within 3 meters.
3. **Configure array parameters** — Adjust tilt angle, azimuth, GCR (ground coverage ratio), panel orientation (landscape/portrait), and intra-row gap using the sidebar sliders. The row pitch updates in real time.
4. **Confirm placement** — Review the preview layout showing valid (cyan) and invalid (red) panel positions within your boundary. Click Confirm to place the array.
5. **Manage arrays** — View array details in the sidebar including panel count, peak power, tilt, azimuth, GCR, and row pitch. Use the Redraw button to reshape an array with preserved settings, or delete it entirely.

### Tier Requirements

Ground mount arrays require a Pro plan or higher. Pro allows up to 2 arrays with 20 panels total. Business and Enterprise plans include unlimited ground mount arrays.

---

## 35. Draw Tool

Annotate your 3D scene with freehand drawings that follow the terrain and building surfaces. Use colored strokes to mark areas of interest, add text labels, and measure enclosed areas. Drawings are saved with your project.

### How to Use

1. **Activate draw mode** — Click the pencil button in the sidebar toolbar (or press `D`). Your cursor changes to a crosshair and the Draw panel opens.
2. **Draw a stroke** — Click and drag on the 3D scene to create a freehand stroke. The stroke follows the terrain and building geometry. Release the mouse button to finalize.
3. **Close a loop for area measurement** — Draw back to the starting point to close the loop. The enclosed area is automatically calculated and displayed in square meters with a semi-transparent fill.
4. **Customize and manage strokes** — Change stroke color, width, and style (solid, dashed, arrow) in the Draw panel. Click a stroke to select it and add a text label. Press `Delete` to remove selected strokes.

### Tips

- Strokes follow terrain, buildings, and rooftops — they snap to scene geometry automatically
- Close a loop by drawing back to the start point to see the enclosed area in m²
- Press `Escape` to cancel a stroke in progress or exit draw mode

---

## 36. 3D Model Library

The Model Library provides over 750 ready-to-use 3D models organized into seven categories — suburban buildings, vehicles, commercial buildings, characters, nature, building parts, and trains. Browse, search, and place models directly into your scene for realistic shadow analysis and urban planning.

### How to Use

1. **Open the Library** — Enter Build mode by clicking the Build button or pressing `B`. Select the Library tab at the top of the sidebar panel.
2. **Browse or search** — Use the category pills to filter by type (Buildings, Vehicles, Nature, etc.) or type in the search bar to find models by name or tag.
3. **Place a model** — Click a thumbnail to arm click-to-place mode, then click anywhere in the scene. Or drag a thumbnail directly from the library onto the scene.
4. **Adjust and manage** — Click a placed model to select it. Use the transform controls to move, rotate, or scale. Press `Delete` to remove a model from the scene.

### Model Categories

| Category | Description |
|----------|-------------|
| Suburban Buildings | Houses, garages, fences, and pathways for residential neighborhood scenes |
| Vehicles | Cars, trucks, ambulances, fire trucks, and other vehicles for street-level detail |
| Commercial Buildings | Offices, shops, and commercial structures for urban planning scenarios |
| Characters | Human figures for scale reference and scene composition |
| Nature | Trees, bushes, rocks, and natural elements for landscaping |
| Building Parts | Modular walls, doors, windows, and structural components |
| Trains | Trains, railroad tracks, and railway infrastructure |

### Drag & Drop

Drag any thumbnail directly from the library panel onto the 3D scene. The model will be placed where you release the mouse. Models are preloaded when you hover over a thumbnail for instant placement.

### Automatic Scaling

Models are automatically scaled to realistic proportions when placed. Houses appear at building scale, vehicles at street scale, and characters at human scale — no manual resizing needed.

### Access by Plan

Registered free users can place up to 5 models per category. Pro and higher plans unlock the full library of over 750 models.

---

## 37. Module & Inverter Catalog

SunTrace3D includes a built-in catalog of real CEC-certified solar modules and inverters from leading manufacturers such as LONGi, JA Solar, Canadian Solar, SMA, Fronius, and more. Select specific equipment to unlock accurate string planning, cable sizing, and energy analysis based on real electrical specifications.

### How to Use

1. **Open the Module Catalog** — In the solar sidebar, expand the "Module Catalog" section. A searchable list of solar modules appears with manufacturer, model, wattage, and efficiency.
2. **Select a module** — Click any module to select it. A summary card shows the full electrical specifications: open-circuit voltage (Voc), max power voltage (Vmp), short-circuit current (Isc), max power current (Imp), and temperature coefficients.
3. **Choose an inverter** — Expand the "Inverter Catalog" section and select an inverter. The summary shows MPPT count, voltage range, maximum input voltage, rated AC output, and European efficiency.

> **Tip:** Module and inverter selections are saved with your project. When you load a saved project, the equipment choices are automatically restored.

---

## 38. String Planning

String planning automatically groups your solar panels into electrical strings based on temperature-corrected voltage limits, shading similarity, and panel orientation. The algorithm respects inverter MPPT input constraints and generates warnings when voltage or current limits are violated.

### How to Use

1. **Select equipment first** — Choose a module and inverter from the catalogs. The string planner needs their electrical specifications (Voc, Vmp, MPPT ranges) to compute valid string configurations.
2. **Set design temperatures** — Enter the minimum and maximum expected temperatures for your location. These are used to calculate temperature-corrected Voc (cold) and Vmp (hot) voltages that determine safe string lengths.
3. **Run planning** — Click "Run Planning". The algorithm clusters panels by orientation and shading profile, then packs them into strings that stay within the inverter's voltage window. Each string is assigned a distinct color.
4. **Review results** — Each string card shows module count, temperature-corrected Voc and Vmp, estimated mismatch loss, and MPPT assignment. Warnings appear if any string exceeds inverter limits.

> **Tip:** Panels in the 3D viewer are color-coded by string group, making it easy to visually verify the grouping.

---

## 39. Single-Line Diagram

The single-line diagram (SLD) is an auto-generated electrical schematic of your PV system. It shows the flow from module groups through strings and MPPT inputs to the inverter, AC disconnect, meter, and grid connection — the standard format required for permit applications.

### How to Use

1. **Complete string planning** — The SLD is generated automatically once a valid string plan exists. It reads the string configuration, MPPT assignments, and inverter specifications.
2. **View the diagram** — Expand the "Single-Line Diagram" section. The SVG diagram shows module groups on the left, connected through strings to MPPT inputs, then to the inverter, AC disconnect, meter, and grid.
3. **Download as SVG** — Click the SVG button to download the diagram as a vector file. This can be included in permit applications or engineering documentation.

> **Tip:** The SLD is automatically included in PDF site reports when you generate one.

---

## 40. Cable Sizing

Cable sizing calculates the recommended conductor cross-section for each DC string run, ensuring voltage drop stays within the allowable limit (typically 2%). It supports both copper and aluminum conductors and accounts for derating factors.

### How to Use

1. **Enter cable run lengths** — For each string, enter the one-way cable length in meters from the panels to the inverter. If you have measurements from the Measure Tool, these can be used as reference.
2. **Select conductor material** — Choose between copper (lower resistance, standard residential) or aluminum (lighter, common in commercial installations).
3. **Review recommendations** — The calculator shows the recommended cable size in mm² and AWG, the calculated voltage drop in both volts and percentage, and a clear Pass/Fail indicator against the maximum allowable drop.

> **Tip:** The voltage drop formula uses Vdrop = 2 × I × L × resistivity / area, iterating through standard cross-sections until the drop is within limits.

---

## 41. Self-Consumption Analysis

Self-consumption analysis models the interaction between your solar production and household electricity usage throughout the year. It calculates how much solar energy you consume on-site versus export to the grid, using realistic hourly load profiles based on household size.

### How to Use

1. **Select a household preset** — Choose from four load profiles: Small (2,500 kWh/year), Medium (4,500 kWh/year), Large (6,500 kWh/year), or EV Owner (8,500 kWh/year). Each has a realistic hourly consumption shape with morning and evening peaks.
2. **Adjust annual consumption** — Fine-tune the total annual consumption in kWh. The hourly profile shape stays the same but scales to match your target.
3. **Read the results** — Two key metrics are displayed: Self-Consumption (percentage of solar production used on-site) and Self-Sufficiency (percentage of total consumption covered by solar). A monthly stacked bar chart shows the breakdown of self-consumed, exported, and imported energy.

> **Tip:** Higher self-consumption means more value from your solar investment. Adding battery storage (see next section) significantly increases self-consumption by storing daytime surplus for evening use.

---

## 42. Battery Storage Simulation

Battery storage simulation models how a home battery system changes your self-consumption and grid dependence. It includes an auto-sizing recommendation that finds the optimal capacity based on your production and consumption patterns.

### How to Use

1. **Auto-size the battery** — Click "Recommend" to run a capacity sweep from 1 to 20 kWh. The algorithm finds the knee point where adding more capacity yields diminishing returns in self-consumption improvement.
2. **Or configure manually** — Enter a specific battery capacity in kWh and click "Simulate". You can also adjust depth of discharge, round-trip efficiency, and max charge/discharge power for detailed modeling.
3. **Compare with and without** — Results show the new self-consumption and self-sufficiency percentages with battery, the uplift compared to no-battery, estimated annual charge/discharge cycles, and updated grid import/export figures.

> **Tip:** The greedy dispatch algorithm charges the battery with surplus solar during the day and discharges during evening peak consumption. Round-trip efficiency losses (typically 8–10%) are accounted for in all calculations.

---

## 43. Bill of Materials

The Bill of Materials aggregates all components needed for your PV installation into a single table. It includes modules, inverter, mounting hardware, DC and AC cables, disconnects, and optional battery — providing a quick material checklist for procurement.

### How to Use

1. **Automatic generation** — The BOM is generated automatically from your panel layout, selected equipment, string plan, and cable sizing results. No manual input needed.
2. **Review line items** — The table groups items by category: modules, inverter, mounting (rails and clamps), cable (per cross-section from cable sizing), battery (if configured), and electrical components (DC and AC disconnects).
3. **Export to CSV** — Click the CSV button to download the complete bill of materials as a spreadsheet-compatible file for import into procurement or ERP systems.

> **Tip:** The BOM is also included in PDF site reports. Mounting hardware quantities are estimated using standard heuristics: 2 rails per panel row, clamps at each panel edge plus shared mid-clamps.

---

## 44. PVsyst Export

Export your shading analysis data in PVsyst-compatible formats for detailed simulation in external software. Three export options are available: a horizon profile (.hor), a per-panel shading summary (.csv), and a comprehensive ZIP archive containing all data files.

### Export Options

1. **Download horizon profile** — The .hor file contains azimuth-elevation pairs describing the horizon obstruction profile as seen from the center of your panel array. This is the standard input format for PVsyst near-shading analysis.
2. **Download shading CSV** — The .csv file lists each panel with its tilt, azimuth, shading loss percentage, and annual yield estimate. If string planning has been run, the string assignment is included.
3. **Download full export ZIP** — The comprehensive ZIP archive bundles all export files: system summary, panel layout with per-panel kWh, monthly yield data, string configuration, horizon profile, and shading analysis. This is the recommended option for a complete PVsyst import package.

> **Tip:** The horizon profile is computed by casting rays from the array centroid at 5-degree azimuth steps across the full 360-degree range, finding the highest obstruction elevation angle at each step.

---

## 45. Panel Irradiance Heatmap

Visualize energy performance across your entire panel array with a color-coded heatmap. Each panel is shaded from red (low annual yield) through yellow (mid-range) to green (high yield), making it easy to spot underperforming panels at a glance.

### How to Use

1. **Place solar panels** — Place one or more solar panels on the 3D model and wait for the energy calculation to complete.
2. **Open the heatmap toggle** — In the Solar sidebar, click the "Panel Heatmap" button. It appears below the Smart Suggestions section once panels are placed and energy has been calculated.
3. **Read the gradient legend** — A color legend appears in the bottom-left corner of the viewer showing the min and max annual kWh values. Red panels produce the least energy; green panels produce the most.
4. **Toggle off** — Click the heatmap button again to return panels to their default color scheme.

### Shadow-Aware Analysis

The heatmap reflects real shading conditions. Panels blocked by nearby buildings, trees, or imported 3D models will show lower yield and warmer colors.

### Color Gradient

Red indicates the lowest annual yield in the array. Yellow marks mid-range performance. Green marks the highest-performing panels. The gradient automatically scales to your array's min/max values.

> **Tip:** Use the heatmap to compare panels with different orientations or shading conditions. Panels facing away from the sun or in heavy shadow will appear red, helping you optimize your layout.

---

## 46. Loss Waterfall Chart

The Loss Waterfall Chart in the PDF site report provides a detailed visual breakdown of energy losses from gross solar potential to net delivered energy. Each loss category is shown as a colored bar segment, making it easy to identify the largest efficiency drains in your system.

### How to Use

1. **Place panels and calculate energy** — Place solar panels on the 3D model and wait for the energy calculation to complete.
2. **Generate the PDF site report** — Click the "Site Report" button in the Solar sidebar to generate a PDF report. The loss waterfall chart is included automatically in the report.
3. **Review loss categories** — The chart shows gross energy on the left and net energy on the right, with each loss category displayed as a labeled bar segment in between.

### Measured Losses

Shading, cloud cover (Kc factor), temperature degradation, panel mismatch, and cable losses are computed from your actual site data and panel configuration.

### Industry Defaults

Inverter efficiency, DC/AC wiring losses, soiling, light-induced degradation (LID), and system availability use standard industry reference values when site-specific measurements are not available.

> **Tip:** The waterfall replaces the old flat 14% system loss estimate with a transparent, itemized breakdown. Measured losses are site-specific; industry defaults use conservative reference values.

---

## 47. Energy System Dashboard

The Energy System Dashboard is a real-time 2D overlay that shows how electricity flows between your solar panels, inverter, battery, meter, and house. It appears automatically when you run a self-consumption analysis and updates live as you scrub the time slider. Click any component to fly the 3D camera to that object in the scene.

### How to Use

1. **Run self-consumption analysis** — Place solar panels, add an inverter and meter, then run the self-consumption analysis from the engineering sidebar. The dashboard appears automatically.
2. **Read the live energy flows** — The dashboard shows real-time power values (kW) for solar production, battery charge/discharge, grid import/export, and house consumption. Animated arrows indicate the direction of energy flow between components.
3. **Click to navigate** — Click any component box (Solar, Inverter, Battery, Meter, House) to fly the 3D camera to that object in the scene. The camera zooms in close enough to inspect the equipment.
4. **Scrub the time slider** — Move the time slider to see how energy flows change throughout the day. At noon, solar production peaks and excess charges the battery or exports to grid. At night, the battery discharges and the grid supplies remaining demand.

### Real-Time Monitoring

Live power values update as you move the time slider. See solar production, battery state of charge, grid import/export, and house consumption at any time of day.

### Click to Navigate

Each component in the schematic is clickable. Click Solar to fly to the panel array, click Battery to zoom to the storage unit, or click Meter to inspect the grid connection.

> **Tip:** The dashboard also shows summary metrics — self-consumption percentage (how much solar you use directly) and self-sufficiency percentage (how much of your demand is met by solar + battery). On mobile devices, the dashboard automatically switches to a compact grid layout.

---

## 48. CRM Platform

The CRM Platform lets solar professionals and businesses manage territories, detect rooftop prospects automatically, and run targeted outreach campaigns — all from within SunTrace3D. Draw a polygon on the map, and the system scans every building inside it, scores their solar potential, and presents them in a sortable prospect grid. Available on Business plans and above; a free playground lets anyone try it with limited results.

### How to Use

1. **Access the CRM** — Navigate to the CRM section from the main menu. Business and Enterprise subscribers see the full CRM app. Free and Pro users can try the interactive playground, which scans a small area and reveals details for up to 3 prospects.
2. **Draw a territory** — Click on the map to draw a polygon boundary around your target area. The system calculates the polygon area and validates it against your plan's territory size limit. Once confirmed, a region scan begins automatically.
3. **Review detected prospects** — The scan detects every building within your territory, classifies them by type (residential, commercial, industrial), estimates usable roof area, and calculates a solar score based on panel count, annual yield, and local climate data. Results appear in a sortable, filterable grid.
4. **Create campaigns** — Select prospects and create outreach campaigns with personalized materials — mail templates, email content, and print assets with QR codes. Each QR code tracks engagement and automatically advances the prospect through your sales pipeline.
5. **Track results on the dashboard** — The CRM dashboard shows your sales funnel, territory potential in kWp, recent activity, and conversion metrics. Data refreshes automatically so you always have the latest picture of your pipeline.

### Territory Scanning

Building detection uses satellite-derived footprint data to find every building in your territory. Each one is automatically classified, measured, and scored without any manual data entry.

### Solar Scoring

Each prospect receives a solar grade (A+ to D) based on estimated roof area, panel capacity, annual energy yield, and local irradiance. Scores help you prioritize the highest-value opportunities.

### Industry Verticals

The CRM supports multiple industry verticals from a single workspace. Each vertical brings its own enrichment fields, scoring logic, pipeline stages, and grid columns. Switch verticals per campaign — a single customer can have both rooftop solar and real estate campaigns.

### Real Estate Vertical

Score properties by sun exposure, estimate property values from country-level price defaults, calculate neighborhood amenity proximity (schools, transit, parks, shops), and compute real estate commissions. Each prospect shows living area, estimated floors, year built, and a 100-point amenity score.

### It Ends in a Signature

A scanned roof opens as a real design, the design becomes a branded proposal, and the signature closes the deal — each step moving the prospect along its pipeline by itself. Section 67 follows one roof the whole way, from a pin on a territory map to a signed contract and a number on the dashboard.

### Prospect Journey & Pipeline

Track each prospect through a 10-stage pipeline from Identified to Installed. The journey drawer shows an append-only activity timeline — every stage change, note, and QR scan is logged. Edit stages inline from the prospect grid, or let QR code scans auto-advance the journey.

### Real-Time Dashboard

The CRM dashboard shows your funnel by stage, remaining territory potential in kWp that shrinks as prospects convert, campaign performance metrics, and a live activity feed. Data refreshes automatically every 30 seconds so you always see the latest pipeline state.

### Interactive Territory Map

Draw polygon boundaries on an interactive map with click-to-draw tools. Building footprints render on a canvas overlay with choropleth coloring — shade prospects by solar grade, deal value, or pipeline stage. Click any footprint to open the prospect detail.

### Free Playground

Anyone can try the CRM without signing up at /crm. Draw a small region (up to 0.25 km²) and the system scans every building, scores solar potential, and reveals full details for 3 sample prospects. The rest are blurred with an upgrade prompt — no account required to explore.

> **Tip:** The CRM automatically detects every building in your territory, classifies it by type, and scores its solar potential — no manual data entry required.

---

## 49. PDF Quotes

Generate professional PDF quotes to send to prospective clients. Each quote includes system specifications, investment breakdown, projected savings, payback period, warranty terms, and applicable financial incentives — all populated automatically from your solar analysis.

### How to Generate a Quote

1. **Complete your solar design** — Place solar panels on the 3D model and wait for the energy calculation to complete. The quote pulls data from your panel layout, selected equipment, and energy yield results.
2. **Open the report modal** — Click the report button in the Solar sidebar to open the report generation dialog. You will see options for both site reports and client quotes.
3. **Configure quote settings** — Enter client details, adjust system pricing, electricity rates, and any applicable incentives or rebates. The quote preview updates in real time as you change parameters.
4. **Download the PDF** — Click Generate to create a branded PDF document. The quote includes a cover page, system overview, financial analysis with payback chart, warranty terms, and next steps — ready to email or print for your client.

### Financial Projections

The quote calculates total investment, annual savings, cumulative savings over the system lifetime, and payback period. It also factors in local electricity price escalation and panel degradation rates.

### Professional Formatting

Quotes are generated as multi-page A4 PDF documents with consistent branding, clear section headings, and a professional layout suitable for client presentations.

> **Tip:** Quotes use the same solar analysis data as site reports but present it in a client-facing format focused on investment return rather than technical specifications. You can generate both a technical site report and a client quote from the same design.

---

## 50. Undo, Redo & Multi-Select

Undo and redo any action, select multiple objects at once, and copy/paste them — all with familiar keyboard shortcuts. These tools work across solar panels, scene objects (trees, fences, pergolas, etc.), buildings, and measurements.

### Undo & Redo

Press Ctrl+Z to undo your last action, or Ctrl+Y to redo it. Every placement, deletion, move, rotation, and property change is tracked. The undo history supports batch operations — for example, the Solar Wizard's panel placement can be undone in one step.

### Multi-Select

Hold Shift and click on panels or scene objects to add or remove them from your selection. Selected items are highlighted in blue. You can Shift+click in both Navigate and Build modes.

### Copy & Paste

With one or more items selected, press Ctrl+C to copy and Ctrl+V to paste. Pasted items appear offset to the right. You can paste multiple times — each paste offsets further. This works for both solar panels and scene objects.

### Batch Delete

Select multiple items with Shift+click, then press Delete to remove them all at once. The deletion can be undone with Ctrl+Z.

> **Tip:** Undo and redo work across all object types — panels, buildings, scene objects, and measurements. If you undo a wizard placement, all panels placed by the wizard are removed in one step.

---

## 51. Draw a House

Draw custom building footprints directly on the terrain by clicking to create a polygon outline. SunTrace3D automatically converts your polygon into one or more 3D buildings that you can place solar panels on, analyze for shadows, and include in energy calculations.

Video: [Draw a Building on an Empty Lot and Design Its Solar in 40 Seconds](https://www.youtube.com/watch?v=tHomI97Dkpg)

### How to Draw

1. **Activate Draw a House** — Click the house icon in the sidebar toolbar or press `H`. An animated tutorial shows how the tool works.
2. **Click to place points** — Click on the terrain to place corner points of your building footprint. You need at least 3 points.
3. **Close the polygon** — Click near the first point, double-click, or press `Enter` to close the shape. The camera automatically transitions to show a 3D preview of your buildings.
4. **Configure the building** — Adjust the number of floors (1–20), floor height, roof type (flat or pitched), roof pitch angle (15–60°), wall color, and roof color using the sliders and color pickers.
5. **Confirm placement** — Click "Place Buildings" to add the buildings to your scene. They become fully interactive — you can place solar panels on them, move, rotate, or delete them.

### Building Configuration

- **Floors** — Set the number of stories (1–20). Total building height = floors × floor height.
- **Floor Height** — Height per floor in meters (2.5–4 m). Adjust for commercial vs. residential buildings.
- **Roof Type** — Choose flat or pitched. Pitched roofs default to 30° and are more realistic for residential buildings.
- **Roof Pitch** — Angle of the roof slope (15–60°). Only available when pitched roof is selected.
- **Wall & Roof Color** — Pick colors for the building facade and roof.

### When No Buildings Are Detected

If you load a location where no buildings are detected near the center marker, a helpful prompt appears suggesting you draw your own building. Click "Draw a House" in the prompt to jump straight into drawing mode.

> **Tip:** The total footprint area and number of generated buildings are shown in the configuration panel. Complex polygons may be decomposed into multiple rectangular buildings to fit the outline.

---

## 52. Ambient Life

The 3D scene includes animated vehicles and pedestrians that move along real roads, bringing the environment to life. Low-poly cars, buses, and pedestrians travel along actual road networks, making it easier to judge scale and get a realistic sense of the surroundings.

### Key Features

- **Automatic** — Ambient life loads automatically when the scene and road data are ready. No setup required.
- **Real road networks** — Vehicles follow actual road paths from the map data, not random paths.
- **Scale reference** — The animated figures provide an intuitive sense of scale when assessing building heights, panel sizes, and shadow lengths.
- **Zero performance impact** — The system uses efficient rendering techniques to keep frame rates smooth.

> **Tip:** Ambient life is automatically hidden during screenshot captures and video recordings to keep outputs clean and deterministic.

---

## 53. Share for Review

Share your complete solar design with clients, colleagues, or partners. The share button in the viewer toolbar offers two sharing modes.

### Share View

Click the Share button and select "Share View" to copy a link to your current location. The link preserves the latitude, longitude, and quality setting. Anyone with the link can open the 3D viewer at the same location — no account required.

### Share for Review (Business+)

Select "Share for Review" to share your complete saved project, including all solar panels, buildings, scene objects, and design decisions. Recipients see the full 3D scene and can **pin comments where they belong, then approve the design or ask for changes** — see [section 66](#66-from-feedback-to-signature).

- Requires a Business plan or higher
- Requires an active saved project (save your scene first)
- Recipients see the full 3D scene with all your modifications
- No account needed — the link is the access

> **Tip:** Use "Share View" for quick location sharing, and "Share for Review" when you need a client to look properly and give you an answer. Send a proposal alongside the review and approving it takes them straight to signing.

---

## 63. Team Workspace

A workspace makes your company the owner of its work rather than one person's account. It holds the brand every client-facing document is rendered in, the seats your colleagues sign in with, and the designs you choose to share. Available on Professional and Enterprise.

### Setting up your workspace

1. **Open your workspace** — Go to Account and choose Team workspace. One is created for you the first time you open it, named after your account; rename it to your company.
2. **Fill in your company details** — Company name, address, country and currency. These appear on proposals and, in Germany, on the regulatory paperwork generated from a design.
3. **Set your brand** — Upload a logo and pick your two colours. The preview shows exactly what a client sees at the top of a proposal.
4. **Invite your colleagues** — Enter an email and send an invite. They do not need an account first; the invite creates one when they accept. If the email does not arrive, copy the link and send it yourself.

### Your brand, not ours

Proposals, PDFs and the pages you share with clients carry your logo, your colours and your contact details.

- **Primary colour** — the proposal header. White text sits on it.
- **Accent colour** — links and buttons, on a white page.
- Both are checked for contrast as you pick them (WCAG AA, 4.5:1). A colour that would make the text on it unreadable cannot be saved, and the measured ratio is shown so you know how far off it is.
- Logo: PNG, JPG or WebP, up to 5 MB.

### Seats

| Plan | Seats |
|---|---|
| Homeowner | — |
| Personal | 1 |
| Professional | 5 |
| Enterprise | Unlimited |

An invite occupies a seat from the moment you send it, so the count tells you how many people can still be added rather than how many happen to have clicked the link already. Invites expire after 30 days and can only be accepted from the address they were sent to.

### Sharing designs

Designs stay private by default, including ones saved before you had a workspace. Share one and everyone with a seat can open and edit it; only its owner can delete it or make it private again. In the project panel a colleague's design is labelled with their name.

### Roles

| Role | Can |
|---|---|
| **Owner** | Everything: company details, brand, seats, and sharing or deleting their own designs. The account the subscription belongs to. |
| **Admin** | Change company details and brand, invite or remove colleagues. Cannot delete designs belonging to someone else. |
| **Member** | Open and edit every shared design, and create their own. Cannot change company settings or manage seats. |

> **Tip:** Move your existing designs in from the Shared designs card on the workspace page. It only moves designs you own, and you can make any of them private again afterwards from the project panel.

---

## 64. Branded Proposals

A proposal is a page your client opens from an email — on a phone, usually — showing the system, the price and what it saves, in your brand rather than ours. It carries the same figures as the PDF quote, and the client can accept it there and then. Available on Professional and Enterprise.

### Sending a proposal

1. **Set your brand once** — Account → Team workspace. Logo, colours, contact details. Every proposal afterwards uses them.
2. **Design the system and open Report** — choose **Proposal** instead of Full report or Quote. Prices, warranties and payment terms are the same fields you fill in for a quote.
3. **Add the client and create it** — name and email. Creating the proposal freezes the figures and renders the PDF.
4. **Send it, or copy the link** — Send to client emails it for you; the link works anywhere.

### Frozen at the moment you send it

A proposal is a snapshot, not a live view. If you change the design tomorrow, the client still sees exactly what you sent — which is also what makes a signature mean something. To offer different figures, send a new proposal.

### Staying in control

| Control | Effect |
|---|---|
| **Validity period** | The proposal expires after the number of days you set. An expired proposal stops showing its price. |
| **Revoke** | Kills the link at any time before signing. A revoked proposal shows nothing at all — not even that it once existed. |
| **Passcode** | An optional PIN the client must enter before the proposal opens. |
| **Open tracking** | You can see whether the client has opened it, and when. |

> **Tip:** If the link has not been opened after a few days, the email may have gone to spam — copy the link and send it another way rather than resending the same mail.

---

## 65. Electronic Signature

A client accepts a proposal by signing it on the page — drawing a signature with a finger or mouse, or typing their name. Both of you receive the signed PDF immediately, with a certificate page recording what was signed and by whom.

### What this signature is, and what it is not

**It is** a simple electronic signature under Regulation (EU) 910/2014 (eIDAS), Article 25(1). A signature of this kind is admissible as evidence across the EU and cannot be denied legal effect merely because it is electronic. It is the same class of signature used by the other major solar proposal platforms.

**It is not** an advanced (AdES) or qualified (QES) electronic signature. Those require a qualified trust service provider and identity verification that we do not perform. We will never describe this signature as qualified or certified, and neither should you when talking to a client.

**Jurisdiction:** some contracts carry a statutory written-form requirement that a simple electronic signature does not satisfy — certain consumer construction contracts in Germany among them. Where that applies to the work you sell, treat a signed proposal as a clear record of acceptance and follow it with whatever form the law requires.

### What gets recorded

A simple electronic signature carries no cryptographic identity, so its weight comes entirely from the record kept around it. That record is printed on the certificate page of the signed PDF.

| Recorded | Why it matters |
|---|---|
| Name and email | Who said they were accepting, and where they can be reached. |
| Time of signing (UTC) | When acceptance happened, in a timezone that cannot be argued about. |
| IP address | Where the signature came from. Recorded as `unknown` rather than guessed if it cannot be determined. |
| The exact consent wording | Stored word for word, in the language the signer read, with a version marker. The wording changes between releases; what matters is what *this* signer agreed to. |
| Document fingerprint (SHA-256) | Identifies the exact file that was signed. Change one character and the fingerprint no longer matches, so "this is what was signed" is a fact anyone can check. |

> **Tip:** A proposal can only be signed once. If a client signs and then wants changes, send a new proposal rather than reopening the old one — the signed copy stays as the record of what was agreed the first time.

---

## 66. From Feedback to Signature

Sharing a design for review used to end in a conversation. A client could pin comments on the model and then there was nothing to press — no way to say yes, and no way for you to find out that someone was waiting on you. Now a review ends in an answer, and an approved one hands the client straight to signing your proposal.

### The loop end to end

1. **Share the design, and send a proposal with it** — create the review session, then create a proposal for the same design. They link themselves: the proposal offers the client a way to walk the model in 3D, and approving the review takes them to the proposal.
2. **Your client looks, and answers** — they pin comments where they want them, then either approve or ask for changes. Either answer emails you.
3. **You see what is waiting in one place** — Account → Team workspace → Client reviews.
4. **Change the design and send an update** — edit the saved design, then press Send an update on that review.

### The two answers

| Answer | What happens |
|---|---|
| **Approve and continue** | Closes the review and, if a proposal is attached, opens it at the signature — the client says yes and signs in the same minute. Approval is **final**; a client who then wants changes needs a new review. |
| **Ask for changes** | Keeps the review open and puts it at the top of your inbox with the number of comments waiting for an answer. Your client sees that the message got through. |

### Versions, and why old comments stay

Sending an update bumps the review to the next version and reopens it. The earlier comments are **not deleted** — they are marked against the version they were written about, and shown as answered.

Deleting them would erase the record of why the design changed. Quietly re-labelling them would be worse: a pin that said "move this panel" would look like it was pointing at the panel that replaced it.

> **Tip:** Send the proposal at the same time as the review, not after it. The value of *Approve and continue* is that there is something to continue to — without a proposal attached, approving simply closes the review and you still have to follow up.

---

## 67. From Prospect to Signed Deal

Scanning a territory tells you which roofs are worth a visit. This is the part where one of them becomes a customer. Opening a scanned roof as a design creates a real project in your workspace, seeded with what the scan already measured, and carries the prospect with it — so the proposal you produce at the end belongs to that person, and the CRM knows it happened without anyone updating a card.

### From a scanned roof to a signed contract

1. **Open the roof as a design** — in the prospect drawer press **Design this roof**. A project is created for your workspace, named after the address and shared with your team, and the prospect moves into the pipeline. Pressing it again re-opens the same design rather than creating a second one — two designs for one roof would be two places to make every change.
2. **Design from what the scan already knows** — the viewer opens on that roof with a banner naming the prospect, the stage and the estimated value. Open the solar wizard and the scan's own estimate is waiting: the panel count it found, and a monthly usage target already filled in. Change anything you like; the scan is a starting point, not an answer.
3. **Turn the design into a proposal** — **Create proposal** in the banner opens the proposal form with the client already named, in your branding and with your standard terms (section 64).
4. **Send it** — the prospect moves to the stage your vertical calls *quoted*, and takes the proposal total as its deal value, to the cent.
5. **They sign** — the prospect moves to *won*, the signed PDF and its certificate are stored (section 65), and the dashboard counts it.

### What moves a prospect, and where

Each vertical names these milestones in its own language. Movement is forward only: a proposal sent after one was already signed will not drag a won deal backwards, and a prospect you marked lost or do-not-contact is left where you put it.

| What happened | Solar installer | Estate agent |
|---|---|---|
| A design was opened for the roof | Site assessment | Viewing |
| A proposal was sent | Quoted, with the proposal total as the deal value | Offer, with the proposal total as the deal value |
| The client signed | Won | Sold |
| The client declined | Lost | Lost |

### A scan is not permission to write

The client email is never filled in for you from a scanned contact, and a proposal cannot be sent without an address you entered yourself. Under GDPR a roof appearing in a territory scan is not consent to be contacted — and a signed proposal is not consent to be marketed to. The campaign email channel applies the same rule: it sends only to contacts with a recorded opt-in.

### Potential, and what came of it

Every figure the dashboard could show used to be an estimate of what a territory *might* be worth, which made it impressive and impossible to check. The **Realised** block is the other half: proposals sent, proposals signed, the conversion rate between them, and the value actually won — each in the currency the proposal was written in. Remaining potential drops as deals close, so the two halves always agree.

> **Tip:** Stages only ever move forward, and terminal ones (won, lost, do not contact) are left alone by every automatic step. If you mark a prospect lost, opening its design again will not quietly reopen the deal — only you can do that.

---

## 68. German Regulatory Pack

Germany is the most regulation-dense residential solar market in Europe, and tools built for the US leave the paperwork to you. When a site is in Germany, a **Tariffs & Compliance** panel appears in the viewer: the feed-in tariff for this system on its commissioning date, the VAT the law puts on it, a grid-connection pre-check, and the registration sheet pre-filled from the design. Everything carries a date and a link to the source it came from.

### Using the pack

1. **Design the system as usual** — the panel appears once the site is in a country we have a pack for, and reads the capacity straight off the panels on the roof.
2. **Tell it the three things the roof cannot** — the commissioning date (which fixes the tariff for twenty years), the inverter rating in kVA and the number of phases (which is what the grid rules are written in), and who will own the plant (which is what the register asks for).
3. **Enter your own rates once** — where a published rate has gone past its verification date we do not show it; we ask you for yours. Entered once, it is used for every quote in your workspace and shown as your figure with ours beside it.
4. **Send the proposal** — a German proposal carries a *Compliance and filings* section into the page and the PDF: VAT and its statute, the tariff and its source, the grid standard, the register, and the disclaimer — in German on a German document.

### How much to trust a number

Rates change by publication and law changes by amendment, and nobody here is watching either for you. So every figure states its own condition.

| What you see | What it means |
|---|---|
| A figure with a date | Checked against its source within the last 90 days. The source link is beside it. |
| A figure with an amber warning | More than 90 days since it was last checked. Still shown, with its age, and the same warning goes into the PDF. |
| No figure at all | More than 180 days since a market rate was checked: withheld rather than quoted, and you are asked for yours. A dead tariff inside a twenty-year payback is wrong for twenty years. |
| A figure marked as yours | Your own value, used across your workspace, with our last figure and its date beside it so any divergence is visible. |

### VAT that knows the threshold

§12(3) UStG zero-rates residential PV up to 30 kW (peak). The proposal form applies it automatically and warns when a system is over the line — a quote that stays silently at 0% above it is a tax error you carry.

### Registration, pre-filled

Every German plant must be in the Marktstammdatenregister within a month of commissioning. We fill the sheet from the design; you file it. Nothing is submitted automatically, no account of yours is used, and the operator named is the client who will own the plant — never your own company.

> **What this is not:** indicative figures to design and quote from, not tax or legal advice, and not a substitute for the current Bundesnetzagentur publications or the legislation in force. No figure here has been reviewed by a German energy lawyer or tax adviser — which is exactly why every one of them carries its source, its date and its own warning.

---

## 69. Grid Compliance Pre-Check

VDE-AR-N 4105 governs how a generating plant connects to the low-voltage grid. Its limits are easy to miss while a design is still moving — and expensive to discover at the connection appointment. The pre-check compares the design on screen against them and names the clause for each result.

| Check | Limit | Why it matters |
|---|---|---|
| Low-voltage connection | 135 kVA | Above it the plant needs a medium-voltage connection, or splitting. |
| Unbalanced load | 4.6 kVA single-phase | A single-phase inverter above this cannot be connected as drawn. Use three phases, or split the array across them. |
| Grid protection (NA-Schutz) | 30 kVA | Below it the inverter's integrated protection is enough; above it a central NA-Schutz with an accessible switch is required. |
| Reactive power | 3.68 kVA | Above it the plant must provide reactive power on demand — check the inverter's cos φ range. |
| Operator notification | Always | The network operator must be notified and must commission the plant before it feeds in. |

> **A pre-check, not a certification.** This tests a design against published thresholds. It is not a declaration of conformity, it does not replace the application to your network operator, and the connecting installer remains responsible for the installation and its documentation.

---

## 70. Tenant Electricity (Mieterstrom)

Mieterstrom is a German model with no US equivalent: a landlord generates on the roof of a multi-unit building and supplies the tenants inside it below the price they would pay a utility, collecting a supplement per kWh for doing so. It is the reason a block of flats that would never buy a rooftop system can be sold one.

1. **Enter the units and the local tariff** — the number of dwelling units, and what a tenant there pays their current supplier per kWh.
2. **Read the cap** — the most you may charge is 90% of that local basic supply tariff (§42a EnWG). The panel shows the cap in ct/kWh and prices the model at it.
3. **Check both sides** — tenant saving and landlord revenue per year, with the split between what tenants consume and what is exported. Where we have no verified supplement rate it is left out of the revenue rather than guessed, which understates the scheme.

If the numbers do not work, the panel says so instead of showing a saving of nothing as a benefit.

> **Tip:** the supplement and the feed-in tariff are separate payments and degress separately. If your supplement figure is more current than ours, enter it once in the panel and it is used for every scheme in your workspace.

---

## 71. Weather Forecast

One-minute demo video: https://youtu.be/qxIGLmt2Dx8

The annual yield figure answers "what will this roof make in a normal year". The weather forecast answers a different question: **what will it make this week**. It runs the real hourly weather forecast for your location through the same irradiance and shading model, and adds the effects that only matter over days rather than decades — cloud, cell heating, dust between rain events, snow cover and inverter clipping.

### How to use it

1. **Place your panels.** The forecast runs against the layout on screen — real tilts, real azimuths, and the per-panel shading losses the shadow analysis already worked out. Move a panel and the numbers update immediately, with no round trip to the server.
2. **Open Solar Analysis → Weather Forecast.** One bar per day. The dashed line across each bar is the seasonal normal for that date at that location.
3. **Tap a day.** It expands to expected kWh, peak power and the hour it happens, the temperature range, the best window for flexible loads, and what heat, soiling and clipping cost you that day.

### What the numbers mean

Three figures sit behind every day:

| Figure | Meaning |
|---|---|
| Expected | AC energy after shading, system losses, temperature derate, soiling, snow and clipping |
| Clear-sky ceiling | The same system under a cloudless sky |
| Seasonal normal | That ceiling scaled by the 22-year NASA POWER clear-sky index for your location |

"18% below normal" compares the first against the third. Both are ratios against the *same* clear-sky model, so the model's own calibration cancels out — which is what makes the comparison a statement about the weather rather than about our maths.

### Alerts and advice

The panel flags what is worth knowing rather than listing everything: snow that will cover the array, a multi-day slump, heat quietly costing several percent, storm-force wind worth a mounting check afterwards, inverter clipping, and rain that will clean the panels for free.

Those turn into actions — the best three-hour window for the washing machine or the EV, which day to pre-charge a battery, which day to go easy because you will be importing, and when clearing snow is worth the trip up a ladder.

### Plan availability

| Plan | Horizon |
|---|---|
| Free | Weekly summary for your area by email |
| Personal | 7 days |
| Professional | 14 days |
| Enterprise | 16 days |

Above 8 days the chart switches to a compact form — weekday initials and no inline numbers — because at sixteen columns a number and a day name collide into an unreadable run of digits. The numbers are all still there in the day detail.

### Forecast emails

If the week ahead is materially different from normal for your saved system, we can tell you by email rather than waiting for you to open the viewer: what is coming, which day is weakest, which day is best, and when to run the heavy loads. Paid accounts get it led by a 3D render of their own roof with their own panels on it. Free accounts get the shape of the week for their area.

There is also a scheduled weekly version of this, delivered by email, by browser notification, or both. See [Weekly Forecast by Email and Notification](#73-weekly-forecast-by-email-and-notification).

> **The seasonal-normal line is the useful one.** A cloudy week in June still out-produces a bright week in December, so raw kWh alone will not tell you whether something is wrong. If a day reads far below normal and the weather does not explain it, look at the shading analysis — that is usually where the answer is.

> **Weather data by Open-Meteo.com**, used under CC BY 4.0.

---

## 72. Export the 3D Scene

Download everything in the scene as a single 3D file and carry on in the tool you already use. The export contains the generated terrain and buildings, every solar panel you placed, ground-mount arrays with their posts, custom and detected buildings, placed objects such as trees and fences, and any model you imported — in the same positions and orientations you see in the viewer. Included in the Business plan and above.

### How to export

1. **Open the Projects panel.** Load a location and build your design as usual. The *Export scene* block sits at the bottom of the Projects panel in the sidebar.
2. **Choose GLB or OBJ.** GLB is one binary file with textures and materials — it opens directly in Blender, SketchUp, Rhino, Unity, Unreal, Three.js viewers and most CAD packages. OBJ is geometry only, with no textures, for older tools that cannot read GLB.
3. **Download.** The file is built in your browser from the live scene, so whatever is on screen at that moment is what you get — including changes you have not saved yet. Large HD models can take a few seconds.

### What is in the file

| Group | Contents |
|---|---|
| Terrain | The generated 3D model (Google 3D Tiles, SRTM/OSM or Google Solar reconstruction) with its textures |
| Buildings | Custom, house-drawn and detected buildings |
| SceneObjects | Trees, fences, pergolas, obstacles, garden beds, greenhouses, inverters, batteries, meters |
| ImportedModels | Models you uploaded and library models you placed |
| GroundMountStructure | Mounting posts of ground-mount arrays |
| SolarPanels | Every placed panel as its own mesh (`SolarPanel_1`, `SolarPanel_2`, …), rooftop and ground-mount alike |

Editing helpers — selection outlines, drag handles, the sun path, heatmaps, measurement lines — are never exported.

### Units and orientation

Metres, Y up, with +X east and +Z south, matching the viewer. The origin is the centre of the generated model, not a geographic coordinate, so combine the export with the project location if you need to georeference it.

### Plan availability

| Plan | Scene export |
|---|---|
| Free | Shown, upgrade to use |
| Personal | Shown, upgrade to use |
| Business | Included |
| Enterprise | Included |

> **Export after you save.** The download reflects the scene exactly as it is on screen, so saving first means the file and the project match, and a colleague opening either sees the same design.

---

## 73. Weekly Forecast by Email and Notification

The [Weather Forecast](#71-weather-forecast) panel tells you about the week ahead while you are in the app. The weekly forecast brings it to you instead. Once a week you get the same numbers for your own roof — by email, by browser notification, or both — so a bad week does not surprise you and a good one does not go unused.

Video: [Your Solar Week, Before It Happens — The Weekly Forecast on Your Phone](https://www.youtube.com/shorts/naRCWKGY_zg) (one minute, vertical: a real array is built on a Dublin roof, the week's real weather is run through it, and the result arrives as a phone notification and an email)

### Turning it on

1. **Accept the offer, or use Account → Preferences.** A small card offers browser notifications once you are signed in. It appears once, in the app, never over a sign-up or payment dialog, and three dismissals end it for good. You can also turn either channel on at any time under Account → Preferences. The email is on by default; notifications are always opt-in.
2. **Give us a roof to forecast.** The forecast is for a real place: a saved project, a model you generated, or a location you looked at. Demo locations and landmarks are never used, so nobody receives a forecast for somewhere they have never been.
3. **Open it and land on your roof.** Clicking the email or the notification opens the viewer on your own project with the forecast panel already open. Without a saved layout it opens your location with a card repeating the week you were just sent.

### What arrives

| Channel | Contents |
|---|---|
| Email | The week against the seasonal normal, a bar for each day, the best day, the weakest day, the best window for the washing machine or the car, and up to four things worth doing |
| Browser notification | The week's verdict and the best day; on Chrome it also carries a picture of the week |

Subscribers see their own saved layout. Everyone else sees a reference rooftop for their location, with the full per-panel detail behind the upgrade.

### When it is sent

Not a fixed Monday morning for everyone. The send time is learned from when you use the app and open mail, in your own time zone, and never lands in the middle of the night. A missed slot is picked up on the next daylight run rather than skipped.

### It stops if you stop reading

| Ignored in a row | What happens |
|---|---|
| 4 | Drops to monthly |
| 7 | Pauses entirely |

Opening one, clicking one, or simply using the app again resets it. A paused forecast is only ever restarted by your own activity, never by another email.

### iPhone and iPad

Safari only delivers notifications to an installed app, so add SunTrace3D to your Home Screen first, then turn notifications on from there. Until you do, the email covers you. Apple does not show a picture on web notifications, so the notification carries text only on iOS.

### Plan availability

| Plan | Weekly forecast |
|---|---|
| Free | Reference rooftop for your location |
| Personal | Your own saved system |
| Professional | Your own saved system |
| Enterprise | Your own saved system |

> **The two channels are independent.** If you want it only as a notification, turn the email off under Account → Preferences; if you only want the email, never grant notification permission. Stopping the weekly email never affects anything else we send you, and every email carries its own one-click stop link that touches this forecast alone.

---

## 54. Plan Mode (2D)

Plan mode turns the viewer into a true top-down drawing. It uses an orthographic camera, so there is no perspective: building sides disappear, distances read the same everywhere on screen, and a site plan can be measured rather than just looked at.

### How to Use

1. **Switch to 2D** — Click 2D in the view toggle at the top left, or press `2`. Press `3` or click 3D to return; your 3D viewpoint is restored exactly where you left it.
2. **Read the drawing** — A scale bar in the corner resizes as you zoom. Pan by dragging and zoom with the mouse wheel; the view stays locked flat.
3. **Rotate to project north** — Drag the project north slider to align the drawing with your site. It rotates the view only — coordinates, measurements and exports are never changed.
4. **Show or hide contours** — Contour lines are generated from the loaded terrain at an automatic interval. Use the contours button to turn them off or back on.

### Notes

- **Framed around your panels** — When a side panel is open, the plan is fitted to the part of the screen you can actually see.
- **Contours from the real model** — Contours are sampled from the loaded 3D model, not from a separate elevation source.
- There is no split 2D/3D view; switch between the two with `2` and `3`.

---

## 55. Site Planning Overview

Site Planning is a feasibility tool for land and development. Draw a parcel, set its constraints, choose what to build, and see immediately what the site yields: units, floor area, parking, cost and whether it meets the zoning you checked it against. Every change re-solves the scheme in real time.

Video: [Test-Fit a Development Site in 60 Seconds — Site Planning](https://www.youtube.com/watch?v=xRozgKQwSqY)

In the app the vertical is labelled "Site Planning". It is unrelated to the solar "Site Report" PDF (section 19).

### Access

- Available on **Business and Enterprise** plans. Free and Pro accounts can open the panel and upgrade from inside it.
- Open it from the industry dropdown at the top left of the viewer by choosing Site Planning, or link straight to it: `https://suntrace3d.com/viewer?lat=38.889&lng=-77.026&vertical=site`.
- Site Planning is not available through AI agent sessions (`/api/mcp-sessions`); agents can link users to the viewer with `vertical=site`, and the user works in the panel.

### How a Scheme Is Solved

Every solve runs one way: hard constraints (parcel, setbacks, easements) shape the buildable envelope; buildings, parking and drives are packed into it; the result is measured; and only then is it checked against zoning and priced.

**It reports, it never corrects.** A failing zoning rule, a parking shortfall or a bay the drive cannot reach is shown — it is never fixed by quietly shrinking a building or deleting stalls.

### Deals, Schemes and Sites

Work is organised as a deal containing one or more schemes, each with a site. Duplicate a scheme to compare alternatives without losing the original.

---

## 56. Guided Start

The guided start asks the four questions a feasibility study begins with and ends on a solved scheme. It writes an ordinary document: everything it sets can be changed afterwards in the panel.

1. **Where is it?** — Take the boundary from the extent of the loaded model, or draw it on the ground. You cannot continue until there is a parcel.
2. **What is it zoned?** — Pick the closest district preset, or skip. Its rules are only checked; its setbacks change the design, so they are offered as a separate tick box.
3. **What are you building?** — Choose a typology and a number of floors, and whether to solve parking and circulation.
4. **What does it yield?** — The scheme is solved and its headline figures are shown: units, FAR, stalls and height.

If the site has no unit mix yet, a typical four-type mix is added. When parking is requested, the lot is laid out as a band between the street frontage and the building, with its aisles along the frontage and room for the drive to turn; a long frontage gets more than one curb cut.

> **Tip:** Choose "Empty deal" to start from nothing — the guided start is optional.

---

## 57. Parcel & Setbacks

The parcel is the boundary everything else is measured from. Setbacks carve the buildable envelope out of it, edge by edge.

1. **Draw parcel or From model** — Click points on the ground, or take the extent of the loaded model.
2. **Close the shape** — Click the first point, double-click, or press `Enter`. `Backspace` removes the last point; `Escape` cancels.
3. **Set the setbacks** — Enter a default setback, then optional front, side and rear distances. A blank class field follows the default.
4. **Override single edges** — The edge list shows every parcel edge, its class and the distance it actually received. Type a value against any edge to override it.

### Automatic Edge Labels

Edges are classified front, side or rear from the real streets around the site (OpenStreetMap roads). An edge with no road near enough stays unclassified and takes the default. Tick **Ignore roads** to treat every edge as the default. The **landscape buffer** adds a uniform band inside the setback line; **Reset setbacks** clears every override.

---

## 58. Regions & Schemes

Regions divide the parcel into what gets built and what does not.

| Region kind | What the solve does with it |
|------|-------------|
| Building area | Packed with buildings by the typology chosen in its properties |
| Easement | Kept clear (e.g. a utility corridor); subtracted from the buildable envelope |
| Open space | Parks, plazas and other ground kept free of buildings |
| Infill | Builds only on ground left over between buildings already solved |

- **Pin** — A pinned region keeps the parameters it was pinned with while the rest of the site follows the site settings.
- **Link** — Linked regions of the same kind share their configuration; their geometry stays separate.
- **Schemes** — Add, duplicate or delete schemes from the bar at the top of the panel. Each is a complete, independent alternative.

---

## 59. Typologies & Unit Mix

A typology is the rule set that turns a building area into buildings. Each family has its own logic.

| Typology | Logic |
|------|-------------|
| Double-loaded bar | Parallel residential bars with a central corridor, separated for light and air |
| Residential over podium | Structured parking fills the base; homes sit on the deck above, set back from its edge |
| Garden walk-up | A grid of small stair-served buildings with parking courts between them, limited to walk-up height |
| Wrap around parking | A continuous band of homes on all four sides around a structured parking deck |
| Industrial big box | One large warehouse sized after a truck court is reserved; reports clear height and dock doors |
| Data centre | Halls sized by power; reports IT capacity against a target load, and facility load at a chosen PUE |

Each family reports its own figures in the region properties. Industrial and data centre schemes place no dwellings, so unit counts, density and residential parking demand read zero.

### Unit Mix and Rates

In **Unit mix**, list unit types with share, target area (m²) and monthly rent, or start from a typical mix. Shares are relative; the total is shown and flagged when it is not 1.00. In **Rates**, set land and build cost per m², rent per m² per year and cap rate. The pro forma is priced from the quantities the scheme actually solves to. Rates are indicative benchmarks.

---

## 60. Parking & Circulation

- **Parking** — Turn on Solve parking to fill the remaining envelope with stalls and aisles. The bay direction is chosen for the most stalls, accessible stalls are added by the ADA ratio, and you can choose a surface lot, a structured deck or below-grade parking with a number of levels. Stall angles: 90°, 60° or 45°.
- **Circulation** — Turn on Solve circulation. The drive enters from the frontage (the parcel edge nearest a road) through one or more curb cuts, runs into the site stopping short of buildings, and branches to the parking aisles. A long dead end gets a turnaround.
- **Drives reserve their ground** — The drive takes its space before parking is packed, so stalls are never drawn under the carriageway.
- **Readout** — Drive length, paved area and how many bays are served. An unreachable bay is reported, not removed; a turnaround that does not fit is drawn in red.

**Limitation:** circulation is a spine with branches. On a very large site some bays may stay out of reach; add curb cuts or split the site into regions. Parking demand for industrial uses is not modelled.

---

## 61. Zoning & Results

The results tabs at the bottom of the panel update with every change.

| Tab | Contents |
|------|-------------|
| Tabulation | Units, FAR, site area, net rentable area, efficiency, DU/AC, stalls provided vs required, parking ratio, building coverage, yield on cost |
| Takeoff | Gross area, facade length, paving and stalls measured from the geometry, priced into hard and total cost (costs indicative) |
| Zoning | Every rule in the profile by name, with its limit and a green (pass) or red (fail) chip. Checked only — never changes the design |
| Errors | Parking shortfalls, unreachable bays, turnarounds that do not fit, loads the site cannot hold |

### District Presets

In step 2 (or the Zoning tab) pick a district — single family, townhouse, multifamily, mixed use, commercial, industrial or data centre campus — to fill the checker in one step. A district also sets what the site builds: R-1 Single family fills the land with detached houses on their own plots (with the district's front and side yards as the plot's), R-2 with terraces, R-3 with walk-ups, MU with a podium block, I-2 with a warehouse and the data-centre district with data halls. The panel says so under the select, and you can still pick another building type in step 3. In the Zoning tab, apply the setbacks separately with "Also apply its setbacks".

For a housing district the Buildings step shows the house mix. "Homes are" chooses detached, semi-detached, terraced or **Mixed**, where every home type says what it is — detached, a semi-detached pair (the pair shares a wall) or a bungalow (one floor). "Add a home type" offers the usual forms in one click. The **Plot use** bar shows how much of a typical plot is house, front yard, side gaps and rear garden, and "Rear garden depth" sets the garden directly by deepening the plot.

The results tray — Summary, Quantities, Zoning check, Issues — is docked at the foot of the panel and stays in view while the settings above it scroll. Click its header to fold it down to one line.

> **Warning:** Presets are generic archetypes with typical North American values, not any municipality's code. Replace them with the real zoning before relying on the result. SunTrace3D does not look up zoning automatically.

---

## 62. Options, Data Layers & Export

- **Generate options** — Choose an objective (most units, highest FAR, best yield on cost, most parking, lowest cost) and sweep floors, setbacks and stall angle. Up to 60 options are ranked; each leads with the figure it was ranked by. Apply one to make it the live scheme.
- **Data layers** — Fetch free public layers for the parcel: FEMA flood hazard, and utilities and wetlands from OpenStreetMap. High-risk flood zones and wetlands can be added as easements in one click. Flood data covers the USA only, and the FEMA service may refuse connections from outside the USA; OpenStreetMap coverage varies. "Unavailable" means the service could not be reached; a count of 0 means it answered and found nothing.
- **See it in 3D** — Switch to 3D to see the solved buildings extruded to their height on the real ground of the model.
- **Export** — Download the plan as DXF (parcel, envelope, buildings and parking on named layers), SVG for documents, and the takeoff as CSV.

---

## Links

- **Interactive User Guide**: [/docs](https://suntrace3d.com/docs)
- **API Documentation**: [/docs/api](https://suntrace3d.com/docs/api)
- **API Reference (Markdown)**: [/docs/api-reference.md](https://suntrace3d.com/docs/api-reference.md)
- **3D Viewer**: [/viewer](https://suntrace3d.com/viewer)
- **Partner Portal**: [/partner](https://suntrace3d.com/partner)


---

# Complete API Reference

# SunTrace3D API Reference

> Machine-readable API documentation for the SunTrace3D Partner API (v1).
> Interactive version: [https://suntrace3d.com/docs/api](https://suntrace3d.com/docs/api)

> **AI Agents**: For a concise product overview, see [/llms.txt](https://suntrace3d.com/llms.txt). For agent integration (session API, parameters, rate limits), see [/llms-agent.txt](https://suntrace3d.com/llms-agent.txt). For the full documentation (user guide + API reference), see [/llms-full.txt](https://suntrace3d.com/llms-full.txt). For AI agent session integration details, jump to [AI Agent Integration](#ai-agent-integration).

---

## Overview

The SunTrace3D Partner API is a RESTful service for programmatic access to 3D city model generation and solar energy calculations.

- **Base URL**: `https://suntrace3d.com/api/v1`
- **Authentication**: Bearer token (API key)
- **Format**: JSON request/response
- **All generated models are HD quality**

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/api/v1/models` | Required | Generate a new HD 3D model |
| `GET` | `/api/v1/models/:id` | Required | Check model generation status |
| `POST` | `/api/solar/calculate` | None | Calculate solar energy yield |
| `GET` | `/api/solar/forecast` | Session (paid tier) | 7-16 day weather-driven output forecast |
| `GET` | `/embed` | API key in query | Embeddable 3D viewer (iframe) |
| `GET` | `/api/health` | None | Health check |

---

## Authentication

All API requests (except `/api/solar/calculate` and `/api/health`) require a Bearer token in the `Authorization` header.

```
Authorization: Bearer st_live_abc123def456...
```

### Getting an API Key

1. Create an account at `/auth/signup`
2. Upgrade to a Business subscription (€99/month)
3. Visit the Partner Portal at `/partner`
4. Click "Create Key" — copy the key immediately (it won't be shown again)

> **Warning:** Keep your API key secret. Do not expose it in client-side code. Use server-side requests or environment variables.

---

## POST /api/v1/models

Generate an HD 3D city model for a geographic location. Models are generated asynchronously — poll the status endpoint to check when ready.

### Request

```http
POST /api/v1/models
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "latitude": 44.8699,
  "longitude": 13.8420,
  "radiusKm": 0.3
}
```

### Request Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `latitude` | number | Yes | Latitude of center point (-90 to 90) |
| `longitude` | number | Yes | Longitude of center point (-180 to 180) |
| `radiusKm` | number | No | Radius of area to model in km (default: 0.3) |

### Response (new generation)

```json
{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "pending"
}
```

### Response (cache hit)

If a model for the same location and radius already exists, the API returns the cached result immediately:

```json
{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "ready",
  "modelUrl": "https://s3.eu-central-1.amazonaws.com/suntrace-models/hd_44.8699_13.8420_0.3/scene.glb"
}
```

> **Tip:** Always check the `status` field in the POST response. If it is `"ready"`, you can skip polling entirely.

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique model identifier for status polling |
| `status` | string | `"pending"` \| `"processing"` \| `"ready"` \| `"failed"` |
| `modelUrl` | string \| null | URL to the GLB model file (non-null when status is `"ready"`) |
| `progress` | number \| null | Generation progress 0-100 (non-null when status is `"processing"` or `"ready"`) |
| `step` | string \| null | Current generation step description |

### Example (curl)

```bash
curl -X POST https://suntrace3d.com/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 44.8699, "longitude": 13.8420, "radiusKm": 0.3}'
```

---

## GET /api/v1/models/:id

Check the status of a model generation request.

### Request

```http
GET /api/v1/models/hd_44.8699_13.8420_0.3
Authorization: Bearer YOUR_API_KEY
```

### Response (processing)

```json
{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "processing",
  "progress": 65,
  "step": "Generating textures..."
}
```

### Response (ready)

```json
{
  "id": "hd_44.8699_13.8420_0.3",
  "status": "ready",
  "modelUrl": "https://s3.eu-central-1.amazonaws.com/suntrace-models/hd_44.8699_13.8420_0.3/scene.glb",
  "progress": 100,
  "step": null
}
```

### Status Values

| Status | Description |
|--------|-------------|
| `pending` | Job is queued, waiting for a worker |
| `processing` | Model is being generated (check `progress` for %) |
| `ready` | Model is ready — `modelUrl` contains the download URL |
| `failed` | Generation failed — retry by creating a new request |

### Polling Recommendation

Poll every 5-10 seconds. Typical generation times are 30-120 seconds.

---

## POST /api/solar/calculate

Calculate annual solar energy yield for a panel configuration and location. Uses PVGIS satellite irradiance data.

**No authentication required.**

### Request

```http
POST /api/solar/calculate
Content-Type: application/json

{
  "latitude": 44.8699,
  "longitude": 13.8420,
  "tiltDeg": 35,
  "azimuthDeg": 180,
  "panelAreaM2": 20,
  "panelEfficiency": 0.20,
  "shadingLossFraction": 0.05
}
```

### Request Body Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `latitude` | number | Yes | Location latitude |
| `longitude` | number | Yes | Location longitude |
| `tiltDeg` | number | Yes | Panel tilt angle in degrees (0-90) |
| `azimuthDeg` | number | Yes | Panel azimuth (0=North, 180=South) |
| `panelAreaM2` | number | Yes | Total panel area in m² |
| `panelEfficiency` | number | Yes | Efficiency (0.0-1.0, typically 0.18-0.22) |
| `shadingLossFraction` | number | No | Shading loss (0.0-1.0, default: 0) |

### Response

```json
{
  "annualYieldKwh": 4982,
  "peakPowerKw": 4.0,
  "specificYield": 1246,
  "monthlyKwh": [248, 305, 412, 465, 522, 548, 562, 530, 445, 368, 280, 232],
  "source": "pvgis"
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `annualYieldKwh` | number | Estimated annual energy yield in kWh |
| `peakPowerKw` | number | Peak power output in kW |
| `specificYield` | number | Specific yield in kWh/kWp |
| `monthlyKwh` | number[] | Array of 12 monthly kWh values (Jan-Dec) |
| `source` | string | Data source identifier (`"pvgis"`) |

### Calculation Method

```
peakPowerKw = (panelAreaM2 * panelEfficiency * 1000) / 1000
annualYieldKwh = peakPowerKw * annualGTI * (1 - shadingLossFraction) * (1 - systemLosses)
```

Where `systemLosses = 0.14` (14% for inverter + wiring) and `annualGTI` is the annual Global Tilted Irradiation from PVGIS.

---

## GET /api/solar/forecast

Weather-driven output forecast for the days ahead, as opposed to the long-run average `/api/solar/calculate` returns. Uses the real hourly forecast (irradiance, temperature, wind, precipitation, snow) for the location and adds cell heating, soiling, snow cover and inverter clipping.

**Requires a signed-in session on a paid plan.** This is not part of the API-key Partner API — it reads the tier from the session, and performs no database query.

### Request

```http
GET /api/solar/forecast?lat=45.55&lon=18.69&days=7&arrays=30,180,23.4,0.21,-0.35,0.06
```

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `lat` | number | Yes | Latitude (-90 to 90) |
| `lon` | number | Yes | Longitude (-180 to 180) |
| `days` | number | No | Days to return (default 7). Clamped to the plan's maximum |
| `arrays` | string | No | Panel groups, `;`-separated. Each is `tilt,azimuth,areaM2,efficiency[,tempCoeffPct][,shadingFraction]`. Max 24 groups. Omit to get the raw weather back instead |
| `panels` | number | No | Module count, for display (default: number of groups) |
| `losses` | number | No | Balance-of-system losses, 0-0.6 (default 0.14) |
| `acKw` | number | No | Inverter AC limit in kW — enables clipping |
| `batteryKwh` | number | No | Usable battery capacity — enables storage advice |
| `consumptionKwh` | number | No | Household annual consumption — enables surplus/deficit advice |
| `tariff` | number | No | Price per kWh, for the cost of a shortfall |
| `currency` | string | No | ISO currency for `tariff` (default `EUR`) |

### Response (with `arrays`)

```json
{
  "tier": "business",
  "maxDays": 14,
  "forecast": {
    "totalKwh": 136.4,
    "clearSkyKwh": 168.1,
    "typicalKwh": 145.2,
    "vsTypicalPct": -6,
    "utcOffsetSeconds": 7200,
    "attribution": "Weather data by Open-Meteo.com",
    "days": [
      {
        "index": 0,
        "date": "2026-09-21",
        "kwh": 16.5,
        "clearSkyKwh": 21.2,
        "typicalKwh": 18.4,
        "vsTypicalPct": -10,
        "condition": "partly",
        "peakKw": 4.1,
        "peakHour": 13,
        "minTempC": 14,
        "maxTempC": 26,
        "bestWindow": { "startHour": 11, "endHour": 14, "kwh": 7.9 },
        "heatLossKwh": 0.6,
        "soilingLossKwh": 0.2,
        "clippingLossKwh": 0
      }
    ],
    "alerts": [
      { "id": "peak_2026-09-27", "kind": "peak_day", "severity": "good",
        "titleKey": "peakDayTitle", "bodyKey": "peakDayBody",
        "params": { "kwh": 25.5, "vsTypicalPct": "+12", "peakHour": "13:00" } }
    ],
    "advice": []
  }
}
```

### Response (without `arrays`)

Returns `{ tier, maxDays, weather }` — the normalised hourly weather only, so a client that already holds the panel layout can run the physics itself without a round trip per edit. This is what the viewer does.

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `tier` | string | The caller's plan |
| `maxDays` | number | Days this plan may request (Personal 7, Professional 14, Enterprise 16) |
| `forecast.totalKwh` | number | Predicted AC production over the window |
| `forecast.clearSkyKwh` | number | Same system under a cloudless sky |
| `forecast.typicalKwh` | number | Clear-sky ceiling × the NASA POWER monthly clear-sky index |
| `forecast.vsTypicalPct` | number | Predicted vs seasonal normal, signed |
| `days[].condition` | string | `sunny` \| `partly` \| `cloudy` \| `rain` \| `snow` |
| `days[].bestWindow` | object\|null | Best contiguous window for flexible loads |
| `alerts[]` | array | Anomalies, as i18n `titleKey`/`bodyKey` plus `params` — never rendered text |
| `advice[]` | array | Suggested actions, same key+params shape |

### Status Codes

| Code | Meaning |
|------|---------|
| `200` | OK |
| `400` | Invalid coordinates |
| `401` | Not signed in |
| `403` | Plan has no forecast access — body carries `upgradeTo` |
| `429` | Rate limited (20 requests per minute per IP) |
| `503` | Weather provider unreachable |

### Notes

- Responses are `Cache-Control: private, max-age=900`.
- The weather behind them is cached server-side per ~5.5 km cell for an hour, so many users in one town cost one upstream call.
- Alerts return translation keys, not sentences, so the same detector serves the viewer, the email and any client you build.

---

## Embed Viewer

Embed an interactive 3D solar viewer on your website using an iframe.

### URL Format

```
https://suntrace3d.com/embed?lat={LATITUDE}&lng={LONGITUDE}&key={API_KEY}
```

### URL Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `lat` | number | Yes | Latitude of location to display |
| `lng` | number | Yes | Longitude of location to display |
| `key` | string | Yes | Your API key |

### Basic Embed Code

```html
<iframe
  src="https://suntrace3d.com/embed?lat=44.8699&lng=13.8420&key=YOUR_API_KEY"
  width="100%"
  height="500"
  frameborder="0"
  allow="fullscreen"
  style="border-radius: 12px; border: 1px solid #e5e7eb;">
</iframe>
```

### Responsive Embed (recommended)

```html
<div style="position: relative; width: 100%; padding-bottom: 56.25%; overflow: hidden; border-radius: 12px;">
  <iframe
    src="https://suntrace3d.com/embed?lat=44.8699&lng=13.8420&key=YOUR_API_KEY"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
    allow="fullscreen">
  </iframe>
</div>
```

### Embed Features

- Interactive 3D orbit, pan, and zoom
- Time slider for shadow simulation
- Responsive — works on mobile
- Google 3D Tiles photorealistic models
- No additional JavaScript required
- Fullscreen support

### Lead Capture in Embeds

If lead capture is enabled in your Partner Portal profile, the embedded viewer will display a lead capture form to visitors. When a visitor submits the form:

1. The lead is saved to your Partner Portal dashboard
2. You receive a notification email with the contact details and system configuration
3. The homeowner receives a confirmation email

Enable lead capture in the Partner Portal at `/partner` by toggling "Lead Capture" on and setting a notification email.

---

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| `POST /api/v1/models` | 10 requests per hour per API key |
| `GET /api/v1/models/:id` | No limit |
| `POST /api/solar/calculate` | No limit (public) |
| `GET /embed` | No limit |

### Rate Limit Exceeded Response (429)

```json
{
  "error": "Rate limit exceeded. Maximum 10 generations per hour."
}
```

---

## Error Handling

All error responses include a JSON body with an `error` field.

### HTTP Status Codes

| Code | Description |
|------|-------------|
| `200` | Success |
| `400` | Bad Request — missing or invalid parameters |
| `401` | Unauthorized — missing or invalid API key |
| `404` | Not Found — model ID does not exist |
| `429` | Too Many Requests — rate limit exceeded |
| `503` | Service Unavailable — PVGIS or external service is down (response includes `useLocalFallback: true` when client-side fallback is available) |

### Error Response Examples

```json
{"error": "latitude and longitude are required"}
```

```json
{"error": "Missing Authorization header"}
```

```json
{"error": "Invalid or revoked API key"}
```

```json
{"error": "Rate limit exceeded. Maximum 10 generations per hour."}
```

```json
{"error": "Model not found"}
```

---

## Webhooks

> **Coming Soon** — Webhook support is planned for a future release. Webhooks will allow you to receive HTTP POST notifications when model generation completes, eliminating the need to poll for status updates.

---

## Full Examples

### Bash — Generate model and wait for completion

```bash
#!/bin/bash
API_KEY="YOUR_API_KEY"
BASE_URL="https://suntrace3d.com"

# 1. Request model generation
echo "Requesting model generation..."
RESPONSE=$(curl -s -X POST "$BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"latitude": 44.8699, "longitude": 13.8420, "radiusKm": 0.3}')

MODEL_ID=$(echo $RESPONSE | jq -r '.id')
STATUS=$(echo $RESPONSE | jq -r '.status')
echo "Model ID: $MODEL_ID (status: $STATUS)"

# 2. Poll until ready
while [ "$STATUS" != "ready" ] && [ "$STATUS" != "failed" ]; do
  sleep 5
  RESPONSE=$(curl -s "$BASE_URL/api/v1/models/$MODEL_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo $RESPONSE | jq -r '.status')
  PROGRESS=$(echo $RESPONSE | jq -r '.progress // 0')
  echo "Status: $STATUS ($PROGRESS%)"
done

# 3. Get the model URL
if [ "$STATUS" = "ready" ]; then
  MODEL_URL=$(echo $RESPONSE | jq -r '.modelUrl')
  echo "Model ready: $MODEL_URL"
else
  echo "Generation failed"
fi
```

### JavaScript / Node.js

```javascript
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://suntrace3d.com';

async function generateModel(lat, lng) {
  // 1. Request generation
  const res = await fetch(`${BASE_URL}/api/v1/models`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ latitude: lat, longitude: lng }),
  });

  const { id, status, modelUrl } = await res.json();

  // If already cached, return immediately
  if (status === 'ready') return { id, modelUrl };

  // 2. Poll until ready
  return pollStatus(id);
}

async function pollStatus(modelId) {
  while (true) {
    await new Promise(r => setTimeout(r, 5000)); // Wait 5s

    const res = await fetch(`${BASE_URL}/api/v1/models/${modelId}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` },
    });

    const data = await res.json();
    console.log(`Status: ${data.status} (${data.progress || 0}%)`);

    if (data.status === 'ready') return data;
    if (data.status === 'failed') throw new Error('Generation failed');
  }
}

// Usage
generateModel(44.8699, 13.8420)
  .then(data => console.log('Model URL:', data.modelUrl))
  .catch(err => console.error(err));
```

### Python

```python
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://suntrace3d.com"

def generate_model(lat: float, lng: float) -> dict:
    """Generate an HD 3D model and wait for completion."""
    # Request generation
    res = requests.post(
        f"{BASE_URL}/api/v1/models",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"latitude": lat, "longitude": lng, "radiusKm": 0.3},
    )
    data = res.json()

    if data["status"] == "ready":
        return data

    # Poll until ready
    model_id = data["id"]
    while True:
        time.sleep(5)
        res = requests.get(
            f"{BASE_URL}/api/v1/models/{model_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        data = res.json()
        print(f"Status: {data['status']} ({data.get('progress', 0)}%)")

        if data["status"] == "ready":
            return data
        if data["status"] == "failed":
            raise Exception("Generation failed")

def calculate_solar(lat: float, lng: float, tilt: float = 35, azimuth: float = 180) -> dict:
    """Calculate solar energy yield for a panel configuration."""
    res = requests.post(
        f"{BASE_URL}/api/solar/calculate",
        json={
            "latitude": lat,
            "longitude": lng,
            "tiltDeg": tilt,
            "azimuthDeg": azimuth,
            "panelAreaM2": 20,
            "panelEfficiency": 0.20,
        },
    )
    return res.json()

# Usage
model = generate_model(44.8699, 13.8420)
print(f"Model URL: {model['modelUrl']}")

solar = calculate_solar(44.8699, 13.8420)
print(f"Annual yield: {solar['annualYieldKwh']} kWh")
print(f"Monthly: {solar['monthlyKwh']}")
```

---

## AI Agent Integration

AI agents (chatbots, virtual assistants) can create sessions to redirect users to SunTrace3D with pre-configured Solar Wizard settings and optional automatic roof detection. No API key is required — sessions use the public MCP Sessions API.

Agent sessions do not pre-generate 3D models. When the user clicks the viewer URL, the SD model generates on demand (about 1-2 minutes depending on location — the user sees a loading animation). If the user has a Pro subscription, the viewer automatically generates an HD model instead.

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| `POST` | `/api/mcp-sessions` | None | Create an agent session with wizard parameters |
| `GET` | `/api/mcp-sessions/:id` | None | Check session status |

### POST /api/mcp-sessions

Create a session that pre-configures the Solar Wizard for the user.

#### Request

```http
POST /api/mcp-sessions
Content-Type: application/json

{
  "latitude": 44.8699,
  "longitude": 13.8420,
  "agentName": "ChatGPT",
  "wizardGoal": "cover_bill",
  "wizardKwh": 350,
  "roofLat": 44.8701,
  "roofLng": 13.8418
}
```

#### Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `latitude` | number | Yes | Location center latitude |
| `longitude` | number | Yes | Location center longitude |
| `agentName` | string | Yes | Agent identifier (e.g., "ChatGPT", "Claude", "MyBot"). Max 100 chars. |
| `radiusKm` | number | No | Radius in km (default: 0.3) |
| `wizardGoal` | string | No | `maximize_energy`, `cover_bill`, `maximize_roi`, `environmental` |
| `wizardKwh` | number | No | Monthly kWh target (required when wizardGoal is `cover_bill`) |
| `roofLat` | number | No | Precise roof latitude for auto-click (requires `roofLng`) |
| `roofLng` | number | No | Precise roof longitude for auto-click (requires `roofLat`) |

#### Response

```json
{
  "sessionId": "clxyz...",
  "viewerUrl": "https://suntrace3d.com/viewer?session=clxyz...&lat=44.869900&lng=13.842000&wizard=cover_bill&wizardKwh=350&roofLat=44.8701000&roofLng=13.8418000",
  "status": "created",
  "modelStatus": "not_generated",
  "agentName": "ChatGPT"
}
```

### GET /api/mcp-sessions/:id

Check session status and retrieve session details. The `modelStatus` reflects whether an SD model has been previously generated for this location (by any user visiting it). For new locations, this will be `"not_generated"` until a user opens the viewer link.

#### Response

```json
{
  "sessionId": "clxyz...",
  "status": "created",
  "modelStatus": "not_generated",
  "latitude": 44.8699,
  "longitude": 13.8420,
  "quality": "sd",
  "agentName": "ChatGPT",
  "wizardGoal": "cover_bill",
  "wizardKwh": 350,
  "roofLat": 44.8701,
  "roofLng": 13.8418,
  "createdAt": "2025-01-15T10:30:00Z",
  "expiresAt": "2025-01-17T10:30:00Z"
}
```

### Recommended Workflows

#### Workflow 1: With Roof Coordinates (Best UX)

Provide precise roof coordinates for automatic panel placement.

```
1. POST /api/mcp-sessions
   { agentName, latitude, longitude, wizardGoal, wizardKwh, roofLat, roofLng }
2. Send viewerUrl to user
3. User clicks link → model generates (~1-2 min, loading animation shown) →
   wizard opens → auto-clicks on roof → panels placed → results shown
4. If auto-click misses: user sees "Click on roof" and clicks manually
```

#### Workflow 2: Manual Roof Selection

Let the user pick the exact roof location.

```
1. POST /api/mcp-sessions
   { agentName, latitude, longitude, wizardGoal }
2. Send viewerUrl to user
3. User clicks link → model generates (~1-2 min) → wizard opens → user clicks roof
```

#### Workflow 3: Direct URL (No API)

Simplest integration. Construct the viewer URL directly.

```
https://suntrace3d.com/viewer?lat=44.87&lng=13.84&wizard=maximize_energy
```

No session tracking, no agent identification. Model generates on-the-fly when the user arrives.

### URL Parameters (viewer)

These parameters are used in the viewer URL (included automatically in `viewerUrl` from the API, or constructed manually for Workflow 3).

| Parameter | Type | Description |
|-----------|------|-------------|
| `wizard` | string | Pre-select wizard goal (`maximize_energy`, `cover_bill`, `maximize_roi`, `environmental`) |
| `wizardKwh` | number | Monthly kWh for `cover_bill` goal |
| `roofLat` | number | Auto-click roof latitude |
| `roofLng` | number | Auto-click roof longitude |
| `session` | string | MCP session ID (auto-included by API) |
| `lat` | number | Location latitude |
| `lng` | number | Location longitude |

### Important Notes

- **Agent identification**: `agentName` is required. Every session is tagged with the agent name for analytics.
- **No pre-generation**: Agent sessions do not trigger model generation. The 3D model generates when the user opens the viewer link (~1-2 minutes, loading animation shown). Pro users automatically get HD quality; free/non-Pro users get SD.
- **Auto-click precision**: `roofLat`/`roofLng` should point to the CENTER of the desired roof surface. The system raycasts downward at that GPS point. If it hits a roof, placement is automatic. If it misses (ground, wrong building), the user clicks manually.
- **User can always redo**: If auto-placed panels are on the wrong surface, the user clicks "Start Over" to remove them and pick a different roof.
- **Pro tier required**: The Solar Wizard requires a Pro subscription (€19/mo). Free users see a sign-up/upgrade prompt.
- **Session expiry**: Sessions expire after 48 hours.
- **Rate limit**: 10 sessions per hour per IP address.

### Full Example (Python)

```python
import requests

def create_solar_link(lat, lng, roof_lat=None, roof_lng=None, monthly_kwh=None):
    """Create an agent session and return the viewer URL to send to the user."""
    payload = {
        "agentName": "MySolarBot",
        "latitude": lat,
        "longitude": lng,
        "wizardGoal": "cover_bill" if monthly_kwh else "maximize_energy",
    }
    if monthly_kwh:
        payload["wizardKwh"] = monthly_kwh
    if roof_lat is not None and roof_lng is not None:
        payload["roofLat"] = roof_lat
        payload["roofLng"] = roof_lng

    res = requests.post("https://suntrace3d.com/api/mcp-sessions", json=payload)
    res.raise_for_status()
    return res.json()["viewerUrl"]

# Usage — send this link to the user
url = create_solar_link(
    lat=44.8699, lng=13.8420,
    roof_lat=44.8701, roof_lng=13.8418,
    monthly_kwh=350,
)
print(f"Send this to your user: {url}")
# User clicks → sees loading animation (~1-2 min) → wizard auto-opens → panels placed
```

---

## Links

- **Interactive User Guide**: [/docs](https://suntrace3d.com/docs)
- **Interactive API Docs**: [/docs/api](https://suntrace3d.com/docs/api)
- **User Guide (Markdown)**: [/docs/user-guide.md](https://suntrace3d.com/docs/user-guide.md)
- **LLM Product Overview (concise)**: [/llms.txt](https://suntrace3d.com/llms.txt)
- **LLM Agent Integration Guide**: [/llms-agent.txt](https://suntrace3d.com/llms-agent.txt)
- **LLM Documentation (full)**: [/llms-full.txt](https://suntrace3d.com/llms-full.txt)
- **3D Viewer**: [/viewer](https://suntrace3d.com/viewer)
- **Partner Portal**: [/partner](https://suntrace3d.com/partner)
- **Health Check**: [/api/health](https://suntrace3d.com/api/health)