# 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 €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 32 feature sections
- [API Documentation](https://suntrace3d.com/docs/api): REST API for 3D model generation and solar calculations
- [Explore Directory](https://suntrace3d.com/explore): Browse pre-generated 3D models by country and city

## How to Use

### Check if your roof gets enough sun for solar panels

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`

Replace LATITUDE and LONGITUDE with decimal coordinates. 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)

## 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 (house, apartment, commercial, townhouse, warehouse) 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. Full shade (blue) to full sun (red).
- [Garden Planner](https://suntrace3d.com/docs#15-garden-planner): 50+ plants with sun-compatibility analysis. Place plants and see if they get enough sunlight 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.

## Pro Features (€9/month)

- [HD 3D Models](https://suntrace3d.com/docs#9-sd--hd-quality-modes): Photorealistic high-definition models with maximum geometric and texture detail. Much sharper rooftops and building edges.
- [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 across 16 annual sun positions, and places an optimized layout. Choose 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 automatically generate optimized panel layouts with configurable tilt, azimuth, and ground coverage ratio.
- [Right-to-Light Compliance](https://suntrace3d.com/docs#27-right-to-light-compliance): Shadow studies for planning permission. BRE 209 guidelines, EU Directive compliance, sun hours analysis for proposed developments.
- [Urban Heat Analysis](https://suntrace3d.com/docs#28-urban-heat-analysis): Thermal comfort analysis for urban areas. Heat island assessment and pedestrian comfort metrics.
- [Film & Photography Tools](https://suntrace3d.com/docs#29-film--photography-tools): Golden hour calculator, sun position for any date/time, camera placement planning, 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 to the scene.
- [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 (€99/month)

- [Partner API](https://suntrace3d.com/docs/api): REST API for programmatic 3D model generation and solar energy calculations. Base URL: https://suntrace3d.com/api/v1
- [Embeddable Viewer](https://suntrace3d.com/docs/api#embeddable-viewer): Embed an interactive 3D solar viewer on your website via iframe. Domain-restricted API keys.
- [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

## 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.
- [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) — €9/month**: Everything in Free plus HD models, Solar Panel Wizard, ground mount placement, 20 panels, right-to-light compliance, urban heat analysis, film & photography tools, 3D model import, save projects.
- **Business (Professional) — €99/month**: Everything in Pro plus REST API, embeddable viewer, lead capture, commercial use rights, unlimited panels and objects.
- **Enterprise — Contact sales**: Custom API quotas, SSO, 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)
- Covers every location on Earth
- Available in 18 languages: English, German, French, Spanish, Italian, Portuguese, Dutch, Polish, Swedish, Japanese, Chinese, Korean, Vietnamese, Turkish, Arabic, Russian, Indonesian, Thai
- Supports 29 currencies for cost calculations

## Optional

- [User Guide (Markdown)](https://suntrace3d.com/docs/user-guide.md): Complete 32-section user guide in machine-readable Markdown format
- [API Reference (Markdown)](https://suntrace3d.com/docs/api-reference.md): Full API documentation in Markdown format
- [Full Documentation](https://suntrace3d.com/llms-full.txt): Complete user guide + API reference in a single file


---

# 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)

### Quality & Views
9. [SD & HD Quality Modes](#9-sd--hd-quality-modes)
10. [Compass & Orientation](#10-compass--orientation)

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

### 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)
23. [Explore Directory](#23-explore-directory)

### Account & Projects
24. [Account & Subscription](#24-account--subscription)
25. [Project Management](#25-project-management)
26. [Importing 3D Models](#26-importing-3d-models)

### 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)

---

## 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 uses the Nominatim geocoding service (powered by OpenStreetMap) to convert addresses to coordinates.

### 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 using the SunCalc library, which computes solar altitude and azimuth 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
- Shadow rendering uses PCFSoftShadowMap with 4096x4096 resolution

---

## 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
- Models stream via Google 3D Tiles (LOD4, errorTarget=24)
- Moderate geometric and texture detail
- Loads instantly — no generation wait time

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

- Requires Pro subscription
- Photorealistic models (LOD6, errorTarget=6)
- Maximum texture and geometric detail
- Individual building features, vegetation, and street-level detail visible

### Technical Details

- 3D models are streamed using the `3d-tiles-renderer` library (v0.4.23)
- LOD (Level of Detail) gating is controlled by the `errorTarget` parameter
- HD models may be pre-generated via the Blender worker using the Blosm addon

---

## 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 Google 3D Tiles in the 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 Google 3D Tiles geometry. It does not remove manually placed buildings, trees, or other scene objects.

---

## 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

Click "Get Quote" to submit your solar analysis to local installers. The form pre-fills with your system specs, location, and estimated costs for a personalized proposal.

---

## 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 |
| `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. Explore Directory

The Explore page lets you browse all available 3D solar models organized by country and city. Discover locations worldwide that already have generated models ready to view.

### Interactive Map

An interactive world map shows markers for every available model. Click any marker to jump directly to that location in the 3D viewer.

### Country & City Directory

Browse a searchable grid of countries, each showing the number of available models and cities covered. Click a country to see its cities, then click a city to open its model.

### Search & Filter

Use the search bar to quickly find a specific country or city by name.

---

## 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:
- 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

Subscriptions are managed through Stripe. 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.

---

## 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.

---

## Technical Stack

| Technology | Purpose |
|------------|---------|
| Next.js 14 | React framework (App Router) |
| React Three Fiber | 3D rendering (Three.js wrapper) |
| drei | React Three Fiber helpers |
| 3d-tiles-renderer | Google 3D Tiles streaming |
| SunCalc | Sun position calculations |
| PVGIS | Solar irradiance data (EU JRC) |
| Zustand | State management |
| Tailwind CSS | Styling |
| Prisma | Database ORM (PostgreSQL) |
| NextAuth v5 | Authentication (credentials) |
| Stripe | Subscription payments |

---

## 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)

---

## 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` | `/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.

---

## 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']}")
```

---

## 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)
- **3D Viewer**: [/viewer](https://suntrace3d.com/viewer)
- **Partner Portal**: [/partner](https://suntrace3d.com/partner)
- **Health Check**: [/api/health](https://suntrace3d.com/api/health)