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

---

## 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, and obstacles (chimneys, poles, cylinders) to the 3D scene. These objects cast and receive shadows, letting you study how landscaping and rooftop features affect solar panel performance.

### 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, and Obstacles.
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 |

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

---

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

### Free Account

- Save and load projects
- SD quality models
- Full shadow simulation
- Solar panel analysis with PVGIS data

### Pro Subscription ($9/month)

- HD photorealistic models
- Partner API access
- Embeddable 3D viewer (iframe)
- Priority support
- Commercial use license

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

---

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