# skaduz & Universal Solar Studio – Technische Gesamtdokumentation (v3.9.5 / v15.16) > 100 % clientseitiges Photovoltaik-Ökosystem unter freier MIT-Lizenz. > Beinhaltet die mobile Web-AR-Horizontmessung per Smartphone/Tablet und die sensorbasierte physikalische 3D-Balkonsimulation im DACH-Raum. > Alle Berechnungen laufen lokal im Browser-Arbeitsspeicher des Nutzers (Zero-Backend, vollständige Privatsphäre). > Domain: https://skaduz-merikerti.web.app/ > Scanner (App 1): https://skaduz-merikerti.web.app/scan/ > Solar Studio (App 2): https://skaduz-merikerti.web.app/studio/ > Index: https://skaduz-merikerti.web.app/llms.txt > Manifest: https://skaduz-merikerti.web.app/ai-manifest.json > Prompt Blueprint: https://skaduz-merikerti.web.app/AI_PROMPT_BLUEPRINT.md > Lizenz: MIT License (Open Source) --- # TEIL I: skaduz (v3.9.5) – Web-AR Horizont- & Sonnenbahn-Scanner URL: https://skaduz-merikerti.web.app/scan/ ## 1. Systemübersicht & Gelöste Probleme skaduz löst drei fundamentale messtechnische Hürden bei der Planung dezentraler Photovoltaik (Balkonkraftwerke, Fassadenanlagen, Terrassen-PV): ### Problem A: Magnetische Missweisung auf Balkonen Smartphones orientieren sich über Magnetfeldsensoren (Hall-Sensoren). Auf Balkonen und Terrassen wird das Erdmagnetfeld durch Bewehrungsstahl in Deckenplatten, massive Stahlgeländer und Mikrowechselrichter massiv verzerrt. Abweichungen von 15° bis 45° sind die Regel. *Lösung in skaduz:* Der **Sonnen- und Schatten-Anker**. skaduz berechnet aus Standort und Systemzeit den astronomisch exakten Sonnenstand. Durch kurzes Anvisieren der Sonne wird die Himmelsrichtung (Azimut) optisch absolut geeicht. Das gestörte Magnetometer wird vollständig umgangen. Der **Schatten-Anker** erlaubt alternativ das Anvisieren des Smartphoneschattens auf dem Boden (180°-Inversion des Sonnenazimuts), was bei hohem Sonnenstand oder starker Blendung ergonomischer ist. ### Problem B: Parallaxe und unzuverlässige Winkelschätzung Das menschliche Auge kann Höhenwinkel am Himmel nicht präzise schätzen; Hindernisse werden systematisch über- oder unterschätzt. *Lösung in skaduz:* Die Kamera wird mit dem **Erdbeschleunigungsvektor (Gravitations-Lot)** gekoppelt. Der physikalische 0°-Horizont wird mit Sub-Grad-Genauigkeit als Flight-Director-Linie eingeblendet. ### Problem C: Varianz der Smartphone-Linsen (Brennweitenfehler) Web-Browser verwehren aus Datenschutzgründen (Anti-Fingerprinting) den Zugriff auf die intrinsische Kameramatrix (Focal Length / FOV). Feste Annahmen führen zu 5–15 % Skalierungsfehlern bei Hindernishöhen. *Lösung in skaduz:* **Passive 1D-Skyline-Kreuzkorrelation**. Während des natürlichen Schwenks vergleicht die App die Pixelverschiebung markanter Dachkanten mit der Drehrate des Gyroskops und ermittelt das Sichtfeld (HFOV/VFOV) ohne jegliche Nutzereingabe. ### Problem D: Verdeckungen des Horizonts in Astronomie-Software skaduz exportiert den erfassten Horizont als `.zip`-Landschaftspaket für Stellarium, KStars und N.I.N.A., inklusive realer Panoramatextur und Polygonvektoren. --- ## 2. Mathematische & Physikalische Algorithmen ### 2.1 Himmelsmechanik (Spencer 1971 / DIN EN ISO 9488) Die Sonnenposition wird für Tag $d_n \in [1, 365]$ und UTC-Dezimalstunde $t_{\text{utc}}$ analytisch bestimmt: $$\Gamma_0 = \frac{2\pi (d_n - 1)}{365}$$ $$\delta = 0{,}006918 - 0{,}399912 \cos(\Gamma_0) + 0{,}070257 \sin(\Gamma_0) - 0{,}006758 \cos(2\Gamma_0) + 0{,}000907 \sin(2\Gamma_0) - 0{,}002697 \cos(3\Gamma_0) + 0{,}00148 \sin(3\Gamma_0)$$ $$\text{EoT} = 229{,}18 \cdot (0{,}000075 + 0{,}001868 \cos(\Gamma_0) - 0{,}032077 \sin(\Gamma_0) - 0{,}014615 \cos(2\Gamma_0) - 0{,}040849 \sin(2\Gamma_0))$$ $$\text{SolarTime} = t_{\text{utc}} + \frac{4 \cdot \lambda + \text{EoT}}{60}, \quad \omega = (\text{SolarTime} - 12) \cdot 15^\circ$$ $$\sin(\alpha_{\text{geo}}) = \sin(\delta) \sin(\phi) + \cos(\delta) \cos(\phi) \cos(\omega)$$ Atmosphärische Refraktionskorrektur nach Saemundsson (1986): $$\Delta\alpha_{\text{refr}} = \frac{1{,}02}{\tan\left(\alpha_{\text{geo}} + \frac{10{,}3}{\alpha_{\text{geo}} + 5{,}11}\right)} \quad [\text{Bogenminuten}], \quad \alpha_{\text{sun}} = \alpha_{\text{geo}} + \frac{\Delta\alpha_{\text{refr}}}{60^\circ}$$ ### 2.2 Pinhole-Projektion & Rückrechnung Für jeden Bildpunkt mit normierten Sensorkoordinaten $u \in [-0{,}5; +0{,}5]$ (horizontal) und $v \in [-0{,}5; +0{,}5]$ (vertikal, positiv nach oben): $$\Delta\alpha = \arctan\left(-v \cdot 2 \cdot \tan\left(\frac{\text{VFOV}}{2}\right)\right), \quad \text{Elevation} = \theta_{\text{pitch}} + \Delta\alpha$$ $$\Delta\psi = \frac{u \cdot \text{HFOV}}{\cos(\theta_{\text{pitch}})}, \quad \text{Azimut} = (\psi_{\text{heading}} + \Delta\psi + 360^\circ) \bmod 360^\circ$$ ### 2.3 Slit-Scan Panorama-Akkumulation Ein interner Canvas ($1440 \times 360\,\text{px}$) deckt ein vollständiges $360^\circ$-Zylinderpanorama von $+60^\circ$ bis $-30^\circ$ Elevation ab ($4\,\text{Pixel pro Grad}$). - Bei jedem Frame mit gültiger Drehrate ($\omega < 70^\circ/\text{s}$) wird ein schmaler vertikaler Bildstreifen mit Roll-Kompensation ($\mathbf{R}(-\phi_{\text{roll}})$) an Position $x_{\text{dest}} = (\psi / 360^\circ) \cdot 1440$ gestempelt. - Streifenhöhe: $\text{destH} = \operatorname{round}(\text{VFOV} \cdot 4\,\text{px/deg})$. ### 2.4 Dynamic-Programming Skyline-Extraktion Im verkleinerten Verarbeitungs-Puffer ($120 \times 160\,\text{px}$) durchläuft ein Viterbi-artiger Dynamic-Programming-Algorithmus das Bild von links nach rechts: $$C(x, y) = 210 - \Big(|\nabla L(x, y)| + 180 \cdot \max(0, \Delta \text{BlueRatio}) + 1{,}6 \cdot \text{Texture}(x, y)\Big)$$ $$\text{DP}(x, y) = C(x, y) + \min_{dy \in [-6, 6]} \Big(\text{DP}(x - 1, y + dy) + 2{,}5 \cdot |dy|\Big)$$ Der Pfad mit minimalen kumulierten Kosten liefert die exakte Konturlinie zwischen Himmel und Bauwerken/Bäumen. ### 2.5 Passive Zero-UI FOV-Autokalibrierung Zwischen zwei Frames mit Gyro-Drehwinkel $\Delta\psi \in [1{,}8^\circ; 6{,}0^\circ]$ wird die 1D-Skyline-Verschiebung $\Delta x$ via Sum of Squared Differences (SSD) minimiert: $$\Delta x = \operatorname{argmin}_{\delta} \sum_{x} \Big(\text{skyline}_t(x) - \text{skyline}_{t+\Delta t}(x + \delta)\Big)^2$$ $$\text{PPD} = \frac{|\Delta x|}{\Delta\psi} \cdot \left(\frac{W_{\text{real}}}{W_{\text{proc}}}\right) \implies \text{HFOV} = \frac{W_{\text{real}}}{\text{PPD}}, \quad \text{VFOV} = 2 \cdot \arctan\left(\frac{H_{\text{real}}}{W_{\text{real}}} \cdot \tan\left(\frac{\text{HFOV}}{2}\right)\right)$$ Die Werte durchlaufen einen 6-fach Medianfilter und werden auf physikalische Schranken ($38^\circ \le \text{HFOV} \le 88^\circ$) begrenzt. ### 2.6 Biomechanische Rumpf-Parallaxe Das Smartphone wird mit am Oberkörper fixierten Armen geführt ($r_{\text{arm}} \approx 25\text{--}30\,\text{cm}$ Drehachsenabstand). Bei typischen Hindernisdistanzen $D \ge 20\,\text{m}$ beträgt der Parallaxenfehler: $$\Delta\alpha_{\text{para}} \le \frac{r_{\text{arm}} \cdot \sin(\Delta\psi)}{D} \le \frac{0{,}28\,\text{m} \cdot \sin(2^\circ)}{20\,\text{m}} \approx 0{,}028^\circ \quad (< 1{,}4\,\% \text{ der Eigenrotation})$$ Die Bewegung ist zu $> 98{,}6\,\%$ eine reine Dreh-Homographie. --- ## 3. Datenformate & Schnittstellen-Spezifikation ### 3.1 Das PVGIS-Horizontformat (.hor) Textdatei mit 72 Zeilen à 5° Intervall (Standard für PVGIS, PV*SOL und Polysun): - Spalte 1: Azimut in Grad von $-180{,}0^\circ$ bis $+180{,}0^\circ$ ($0^\circ = \text{Süd}$, $-90^\circ = \text{Ost}$, $+90^\circ = \text{West}$, $\pm 180^\circ = \text{Nord}$). - Spalte 2: Elevationswinkel der Horizontsilhouette in Grad über dem mathematischen 0°-Horizont. - Trennzeichen: Tabulator (`\t`). Lücken werden durch zweiseitige Nachbarschafts-Interpolation geschlossen. ### 3.2 Das 3D-Zylinderkörper-Format (.glb) Binäre glTF-2.0-Datei (`model/gltf-binary`) für CAD-Software und 3D-Engines: - Geometrie: Zylindrisches Polygonnetz mit Radius $R = 18{,}0\,\text{m}$. * Unterkante: Fest auf Bodenniveau $Y = 0{,}0\,\text{m}$. * Oberkante: Abgeschnitten entlang der gemessenen Silhouette ($Y = R \cdot \tan(\alpha)$). * Dreiecksanzahl: 144 Dreiecke (72 Segmente à 2 Quads). - Texturierung: Vollständiges UV-Mapping auf das $1440 \times 360\,\text{px}$ Panoramabild (reale Fototextur). * Material: `MeshStandardMaterial`, beidseitig gerendert (`side: DoubleSide`), Textur im GLB eingebettet. - Metadaten (glTF `asset.extras` bzw. `nodes[0].userData`): ```json { "generator": "skaduz v3.9.5", "latitude": 51.312, "longitude": 9.491, "locationSource": "gps_approximate", "azimuthShift": 0.0, "facadeAzimuth": 180.0, "panelMountHeight": 0.95, "created": "2026-09-30T12:00:00.000Z" } ``` ### 3.3 Zero-Copy postMessage RAM-Transfer (Solar Studio Bridge) Protokoll zur verlustfreien Übergabe des Modells an Universal Solar Studio ohne Serverübertragung: 1. `skaduz` öffnet Ziel-URL synchron im Klick-Event: `const win = window.open('https://skaduz-merikerti.web.app/studio/#obstmode=scan&source=skaduz...', '_blank');` 2. `Solar Studio` sendet nach Boot-Abschluss: `window.opener.postMessage({ type: 'SOLAR_STUDIO_READY_FOR_GLB' }, '*');` 3. `skaduz` antwortet mit dem Binärpuffer: ```javascript win.postMessage({ type: 'TRANSFER_SKADUZ_GLB', buffer: glbArrayBuffer, metadata: { coords: { lat: 51.31, lon: 9.49 }, azimuthShift: 0.0, facadeAzimuth: 180.0, yOffset: 0.0 } }, 'https://skaduz-merikerti.web.app'); ``` 4. `Solar Studio` bestätigt den Empfang: `window.opener.postMessage({ type: 'SOLAR_STUDIO_GLB_ACK' }, '*');` --- ## 4. Plattform-Matrix & Betriebsmodi | Plattform | Eingabemodus | Sensorpfad | Besonderheiten | | :--- | :--- | :--- | :--- | | **iOS (iPhone)** | Portrait (Hochkant) | `DeviceOrientation` (Permission via Klick) | HFOV $44^\circ$, VFOV $56^\circ$, Zielneigung $+10^\circ$. | | **iPadOS (Tablet)** | Landscape (Querformat) | `DeviceOrientation` (Erkennung via `maxTouchPoints > 1`) | Achsentausch: HFOV $68^\circ$, VFOV $42^\circ$, Zielneigung $+14^\circ$, Daumen-Buttons seitlich. | | **Android Phone** | Portrait | `deviceorientationabsolute` (Primär) | Hardware-Zoom-Constraint für Ultraweitwinkel. | | **Android Tablet** | Landscape | `deviceorientationabsolute` | Adaptive Slit-Scan Streifenhöhe. | | **Desktop / PC** | Desktop-Maus | Watchdog fällt auf Demo-Modus zurück | Simuliert künstlichen Taghimmel und Test-Skyline ohne Kamera. | --- # TEIL II: Universal Solar Studio (v15.16) – 3D-Balkonsimulator URL: https://skaduz-merikerti.web.app/studio/ ## 1. Duale URL-Schnittstelle (#ai= und #cfg=) ### Format A: Das semantische Format (#ai=) – Für Chatbots, Assistenten & Deep-Links Kompakt, fehlertolerant und menschenlesbar. Fehlende Parameter werden automatisch durch bewährte DACH-Standardwerte ergänzt. Syntax: `https://skaduz-merikerti.web.app/studio/#ai=key:val;key:val;action:calc` ### Format B: Das verlustfreie Vollzustands-Format (#cfg=) – Für 1:1 Geometrie-Klone Nimmt ein vollständiges, URI-kodiertes JSON-Objekt entgegen. Ermöglicht es KI-Agenten, millimetergenaue Wandplatzierungen, 3D-Fotozylinder-Winkel und komplexe 3D-Scan-Transformationen absolut verlustfrei als Link zu teilen. Syntax: `https://skaduz-merikerti.web.app/studio/#cfg=%7B%22preset%22%3A%22balcony_south%22%2C...%7D` --- ## 2. Vollständige Parameter-Referenz für #ai= Trennzeichen ist das Semikolon (`;`). Schlüssel und Werte werden mit Doppelpunkt (`:`) getrennt. Zahlenwerte werden ohne Maßeinheiten übergeben. #### Standort & Meteorologie - `loc:`: DWD-Klimastützpunkt (2D-IDW-Interpolation über 20 Referenzstationen in Deutschland inkl. Mini-DEM Geländehöhe). * Gültige Kernwerte: `kassel` (Standard), `erfurt`, `frankfurt`, `norderney`, `rostock`, `hamburg`, `bremen`, `hannover`, `koeln`, `muenster`, `trier`, `berlin`, `leipzig`, `dresden`, `magdeburg`, `stuttgart`, `freiburg`, `nuernberg`, `muenchen`, `kempten`. * DACH-Aliase (z. B. `wien`, `graz`, `zuerich`, `basel`, `cologne`, `ruhrgebiet`, `augsburg`, `kiel`, `frankfurtoder`) werden automatisch aufgelöst. Alternativ Koordinaten: `loc:51.31,9.49` oder `lat:51.31;lon:9.49`. - `climate:`: Meteorologische Datengrundlage des Deutschen Wetterdienstes (DWD). * `norm`: DWD-Klimanormalperiode 1991–2020 (30-Jahres-Mittel der WMO). Aliase: `1991_2020`, `30y`. * `recent` (Standard): DWD-Messdatenreihe 2015–2024 (10-Jahres-Mittel aus CDC-Rasterdaten, +4,6 % Global Brightening). Aliase: `2015_2024`, `10y`. #### Geometrie-Presets - `preset:`: Lädt ein vollständiges Setup inklusive Wand-, Decken- und Ausrichtungsgeometrie: * `balcony_south`: 2 Module Querformat, 25° Süd, Standard-Geländer (0,90 m). * `balcony_vertical`: 2 Module Querformat, 90° Süd senkrecht an Reling. * `loggia_south`: 2 Module Hochkant, 25° Süd, Hitzestau (`therm:stau`), 3 geschlossene Wände und Deckenüberstand. * `east_west_split`: Ost-West-Satteldach, 15° Neigung, G1: 90° Ost, G2: 270° West. * `table_oso`: Solartisch 15° OSO, 1x 380 Wp Sicherheitsglas, 400 W AC, freistehend. * `garden_south`: 4 Module Hochkant, 30° Süd im Garten, freistehend (`therm:free`). #### Freier 4-Kanal-CAD-Editor (Modus 5) - `cad:<0|1>`: Aktiviert den CAD-Editor für unkonventionelle, asymmetrische Aufstellungen. - `m1..m4:`: Individuelle Parametrisierung jedes Kanals: * Format: `m1:1_L_-0.90_0.95_0.0_25_180_A` (1=aktiv, L=Landscape, X, Y, Z, Tilt, Azimut, Gruppe). * Autarke MPPTs: Jeder aktive Kanal regelt unabhängig; die Gesamtsumme wird gegen das AC-Limit abgeregelt. * OBB-SAT-Kollision: Verhindert räumliche Durchdringungen und Überlappungen von Modulen. #### Kinematik & Ausrichtung - `baz:<0-360>`: Fassaden-/Balkon-Ausrichtung in Grad (180 = Süd). Dreht das gesamte Bauwerk starr mit. - `az:<0-360>`: Modul-Ausrichtung in Grad (Standard: gekoppelt an `baz`). - `tilt:<0-90>`: Neigungswinkel in Grad (Standard: 25). - `h:<0.0-4.0>`: Montagehöhe der Modulunterkante über dem Balkonboden in Metern (Standard: 0.95). - `split:`: Aktiviert die getrennte Ausrichtung (Ost-West-Split). - `t1:<0-90>` / `a1:<0-360>`: Neigung und Azimut für Gruppe 1 (z. B. `t1:15;a1:85` für Ost). - `t2:<0-90>` / `a2:<0-360>`: Neigung und Azimut für Gruppe 2 (z. B. `t2:20;a2:265` für West). - `orient:`: * `landscape` (Querformat – Standard und Empfehlung für Brüstungen wegen horizontaler Bypass-Diodenstränge). * `portrait` (Hochkant – Standard für offene Gitter oder Freiflächen). * Geometrie-Aliase: `reling` (90° S), `split`, `loggia`, `table_oso`, `garden_south`. #### Hardware & Elektrik - `modp:`: Modultyp (`topcon_440` = 440 Wp TOPCon Bifazial; `classic_400` = 400 Wp PERC; `table_380` = 380 Wp Sicherheitsglas; `light_330` = Ultraleicht; `power_500` = 500 Wp XL). - `panels:<1|2|4>`: Modulanzahl (1 = Single/Tisch, 2 = Standard, 4 = Quad-Set bis 2.000 Wp nach Solarpaket 1). - `wp:<100-800>`: Nennleistung pro Modul in Watt-Peak (Standard: 440). - `inv:<400|600|800>`: Wechselrichter AC-Grenze in Watt (Standard: 800). - `therm:`: Belüftungssituation nach Faiman-Modell. - `bat:<0.0-15.0>`: LiFePO4-Speicherkapazität in kWh stufenlos (Standard: 0 = Direktnutzung; z. B. `bat:1.6`, `bat:2.0`, `bat:2.4`). - `bat_max_p:<100-800>`: Maximale AC-Entladeleistung des Batteriespeichers in Watt (Standard: 500). - `bat_bypass:<0-800>`: Feste Grundlast-Einspeisung / Standby-Abgabe in Watt (Standard: 0 = bedarfsorientiert). - `bat_mode:`: Speicherstrategie (smart = dynamischer Eigenbedarf; bypass = feste Grundabgabe). #### Haushalt, Lastprofil & Finanzen - `prof:`: Lastprofil nach VDI 4655 (`homeoffice`, `commuter`, `seniors`, `couple`, `family`, `smarthome`). - `kwh:<200-25000>`: Tatsächlicher Jahresstromverbrauch in kWh/a (überschreibt den Nennwert des Profils). - `base:<0-500>`: Dauerhafte Ruhelast / Standby-Grundlast des Haushalts in Watt (Standard: 20). - `price:`: Stromtarif in ct/kWh brutto (Standard: 31.48). - `capex:`: Anschaffungskosten des PV-Sets in Euro (Standard: 399). - `cost_bat:`: Anschaffungskosten des Speichers in Euro für die Amortisationsberechnung. - `feed:`: Einspeisevergütung in ct/kWh (Standard: 0.0). - `inflation:<0-10>`: Strompreissteigerung in %/a für die 10-Jahres-Barwertrechnung nach VDI 2067 (Standard: 2.0). - `degradation:<0-2>`: Modul-Degradation in %/a (Standard: 0.5). #### Wände & Decke (Modus 1) - `wall:`: Frontgeländer-Art (`solid` = Mauerwerk/Beton; `grid` = offene Streben; `none` = ohne Geländer). - `wall_front:` / `wf:`: Frontbrüstung mit Distanz und Höhe in Metern (z. B. `wall_front:0.95_0.90`). - `wall_back:` / `wb:`: Hauswand hinten mit Distanz und Höhe (z. B. `wall_back:1.30_2.80`). - `wall_left:>` / `wl:`: Seitenwand links (z. B. `wall_left:1.80_2.40`). - `wall_right:>` / `wr:`: Seitenwand rechts (z. B. `wall_right:1.80_2.40`). - `overhang:|>`: Deckenüberstand mit Ausladung und lichter Höhe (z. B. `overhang:1.20_2.60`). - Exakte Maße (optional als Tupel `[on,distanz,hoehe]`): * `wf:` (Frontbrüstung, z. B. `wf:true,0.95,1.10`) * `wb:` (Hauswand hinten, z. B. `wb:true,1.40,2.80`) * `wl:` (Linke Seitenwand) * `wr:` (Rechte Seitenwand) * `wt:` (Decke / Überstand: Tiefe und lichte Höhe) #### 360°-Horizont-Vorhang (Modus 2) - `shade_preset:`: * `clear`: Freihorizont (0 m Hindernishöhe). * `terraced`: Siedlung / Nachbardächer (9 m Firsthöhe auf SO, S, SW). * `tree_sw`: Großer Laubbaum im Südwesten (18 m Krone in 14 m Distanz). * `courtyard`: Enger Innenhof (13,5 m Kesselwand). - `shade:`: Benutzerdefinierte Hindernisse. Sektoren: `no`, `ono`, `oso`, `so`, `sso`, `sued`, `ssw`, `sw`, `wsw`, `wnw`, `nw`. Format: `__` (z. B. `shade:sw_15_12`). #### Aktionen & Zeitsteuerung - `action:`: * `calc`: Führt direkt nach Laden die 365-Tage-Jahresbilanz aus. * `optimize`: Startet die mathematische LOD-Suche nach dem wirtschaftlich optimalen Neigungswinkel. * `print`: Öffnet das druckfertige A4-Muster zur Vermieter-Voranfrage (§ 554 BGB / § 20 WEG). * `telemetry`: Öffnet den CSV-Messdaten-Importbereich für den Soll-Ist-Abgleich. * `verify`: Führt die interne 41-Punkte-Modellverifikation aus und zeigt den Audit-Bericht. - `hour:<3-21>`: Uhrzeit für die Sonnenstandssimulation (Dezimalstunden oder HH:MM). - `day:<1-365>`: Kalendertag des Jahres (z. B. 80 = Frühlings-Äquinoktium, 230 = 18. August). - `mode:`: Aktiver Hindernismodus. --- ## 3. Formale JSON-Schema-Definition (Draft-07) ```json { "$schema": "http://json-schema.org/draft-07/schema#", "title": "SolarStudioConfig", "description": "Parameter für die Universal Solar Studio 3D-Balkon-Photovoltaik-Planungshilfe (v15.16)", "type": "object", "properties": { "loc": { "type": "string", "default": "kassel", "description": "Standort oder Stadtname im DACH-Raum" }, "climatePeriod": { "type": "string", "enum": ["dwd_1991_2020", "dwd_2015_2024"], "default": "dwd_2015_2024" }, "preset": { "type": "string", "enum": ["balcony_south", "balcony_vertical", "loggia_south", "east_west_split", "table_oso", "garden_south"] }, "az": { "type": "number", "minimum": 0, "maximum": 360, "default": 180 }, "baz": { "type": "number", "minimum": 0, "maximum": 360, "default": 180 }, "tilt": { "type": "number", "minimum": 0, "maximum": 90, "default": 25 }, "h": { "type": "number", "minimum": 0.0, "maximum": 4.0, "default": 0.95 }, "split": { "type": "boolean", "default": false }, "t1": { "type": "number", "minimum": 0, "maximum": 90, "default": 20 }, "a1": { "type": "number", "minimum": 0, "maximum": 360, "default": 90 }, "t2": { "type": "number", "minimum": 0, "maximum": 90, "default": 20 }, "a2": { "type": "number", "minimum": 0, "maximum": 360, "default": 270 }, "orient": { "type": "string", "enum": ["landscape", "portrait", "sued", "sw", "so", "west", "ost", "reling", "split", "loggia", "table_oso", "garden_south"], "default": "landscape" }, "modp": { "type": "string", "enum": ["topcon_440", "classic_400", "table_380", "light_330", "power_500", "custom"], "default": "topcon_440" }, "panels": { "type": "integer", "enum": [1, 2, 4], "default": 2 }, "wp": { "type": "number", "minimum": 100, "maximum": 800, "default": 440 }, "inv": { "type": "integer", "enum": [400, 600, 800], "default": 800 }, "therm": { "type": "string", "enum": ["standard", "stau", "free"], "default": "standard" }, "wall": { "type": "string", "enum": ["solid", "grid", "glass", "none"], "default": "solid" }, "wall_left": { "type": "string", "default": "none" }, "wall_right": { "type": "string", "default": "none" }, "overhang": { "type": ["string", "number"], "default": "none" }, "shade": { "type": "string" }, "shade_preset": { "type": "string", "enum": ["clear", "terraced", "tree_sw", "courtyard"] }, "bat": { "type": "number", "minimum": 0.0, "maximum": 15.0, "default": 0 }, "bat_max_p": { "type": "integer", "minimum": 100, "maximum": 800, "default": 500 }, "bat_bypass": { "type": "number", "minimum": 0, "maximum": 800, "default": 0 }, "bat_mode": { "type": "string", "enum": ["smart", "bypass_100", "bypass_150"], "default": "smart" }, "prof": { "type": "string", "enum": ["homeoffice", "commuter", "seniors", "couple", "family", "smarthome"], "default": "homeoffice" }, "kwh": { "type": "integer", "minimum": 200, "maximum": 25000, "default": 1300 }, "base": { "type": "number", "minimum": 0, "maximum": 500, "default": 20 }, "price": { "type": "number", "minimum": 5.0, "maximum": 100.0, "default": 31.48 }, "capex": { "type": "number", "minimum": 0, "maximum": 5000, "default": 399 }, "cost_bat": { "type": "number", "minimum": 0, "maximum": 5000, "default": 0 }, "feed": { "type": "number", "minimum": 0.0, "maximum": 30.0, "default": 0.0 }, "inflation": { "type": "number", "minimum": 0.0, "maximum": 10.0, "default": 2.0 }, "degradation": { "type": "number", "minimum": 0.0, "maximum": 2.0, "default": 0.5 }, "hour": { "type": "number", "minimum": 3.0, "maximum": 21.0, "default": 10.0 }, "day": { "type": "integer", "minimum": 1, "maximum": 365, "default": 230 }, "obstMode": { "type": "string", "enum": ["walls", "panorama", "photo", "scan"], "default": "walls" }, "action": { "type": "string", "enum": ["calc", "optimize", "print", "telemetry", "verify"], "default": "calc" } }, "required": ["loc", "panels", "action"] } ``` --- ## 4. TypeScript-Typdefinitionen ```typescript export interface SolarStudioConfig { loc?: string; climatePeriod?: 'dwd_1991_2020' | 'dwd_2015_2024'; preset?: 'balcony_south' | 'balcony_vertical' | 'loggia_south' | 'east_west_split' | 'table_oso' | 'garden_south'; lat?: number; lon?: number; az?: number; baz?: number; tilt?: number; h?: number; split?: boolean; t1?: number; a1?: number; t2?: number; a2?: number; orient?: 'landscape' | 'portrait' | string; modp?: 'topcon_440' | 'classic_400' | 'table_380' | 'light_330' | 'power_500' | 'custom'; panels?: 1 | 2 | 4; count?: 1 | 2 | 4; wp?: number; inv?: 400 | 600 | 800; therm?: 'standard' | 'stau' | 'free'; wall?: 'solid' | 'grid' | 'glass' | 'none'; wall_left?: 'solid' | 'none' | string; wall_right?: 'solid' | 'none' | string; overhang?: 'deep' | 'small' | 'none' | number; wf?: [boolean, number, number]; wb?: [boolean, number, number]; wl?: [boolean, number, number]; wr?: [boolean, number, number]; wt?: [boolean, number, number]; shade?: string; shade_preset?: 'clear' | 'terraced' | 'tree_sw' | 'courtyard'; sky?: Array<[number, number]>; bat?: number; bat_max_p?: number; batMaxP?: number; bat_bypass?: number; batBypass?: number; bat_mode?: 'smart' | 'bypass_100' | 'bypass_150'; prof?: 'homeoffice' | 'commuter' | 'seniors' | 'couple' | 'family' | 'smarthome'; kwh?: number; base?: number; price?: number; capex?: number; costPv?: number; costBat?: number; feed?: number; inflation?: number; degradation?: number; hour?: number; day?: number; obstMode?: 'walls' | 'panorama' | 'photo' | 'scan'; photoLeftAz?: number; photoRightAz?: number; photoTopDeg?: number; photoBottomDeg?: number; photoOpacity?: number; scanCfg?: [number, number, number, number, number, boolean]; action?: 'calc' | 'optimize' | 'print' | 'telemetry' | 'verify'; } export interface SolarStudioSimulationResult { valid: boolean; version: string; timestamp: string; summary_for_llm: string; parse_report?: { applied_parameters: Record; warnings: string[]; }; metrics: { climate_period: string; annual_prod_kwh: number; self_consumption_kwh: number; grid_feed_kwh: number; battery_discharge_kwh: number; annual_savings_eur: number; autarky_pct: number; self_consumption_pct: number; usable_battery_wh: number; }; monthly: { prod_kwh: number[]; self_kwh: number[]; grid_kwh: number[]; }; waterfall_pct: { geometry_loss: number; shading_loss: number; thermal_iam_loss: number; inverter_loss: number; }; hints: string[]; share_url: string; } export interface SolarStudioOptimizeResult { valid: boolean; best_tilt_deg: number; payback_years: number; annual_savings_eur: number; annual_prod_kwh: number; self_consumption_kwh: number; autarky_pct: number; share_url: string; } ``` --- ## 5. Model Context Protocol (MCP) – Tool-Definition ```json { "name": "simulate_balcony_solar", "description": "Erzeugt eine physikalische 3D-Balkon-Photovoltaik-Planung mit Verschattungsberechnung, Lastprofil, DWD-Klimadaten, Neigungsoptimierung und Ertragsbilanz.", "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "Standort oder Stadt im DACH-Raum" }, "climate_period": { "type": "string", "enum": ["dwd_1991_2020", "dwd_2015_2024"] }, "facade_azimuth": { "type": "number", "description": "Ausrichtung der Fassade in Grad (180 = Süd, 90 = Ost, 270 = West)" }, "tilt_angle": { "type": "number", "description": "Neigungswinkel der Module (z. B. 25 oder 90)" }, "panel_count": { "type": "integer", "enum": [1, 2, 4], "description": "Anzahl der Solarmodule" }, "mounting_height": { "type": "number", "description": "Montagehöhe der Modulunterkante über Balkonboden in m" }, "module_orientation": { "type": "string", "enum": ["landscape", "portrait"] }, "balcony_wall_type": { "type": "string", "enum": ["solid", "grid", "glass", "none"] }, "roof_overhang": { "type": "string", "enum": ["deep", "small", "none"] }, "annual_kwh": { "type": "integer", "description": "Jahresstromverbrauch des Haushalts in kWh" }, "battery_kwh": { "type": "number", "minimum": 0.0, "maximum": 15.0, "description": "LiFePO4-Speicherkapazität in kWh" }, "load_profile": { "type": "string", "enum": ["homeoffice", "commuter", "family", "couple", "seniors", "smarthome"] }, "action": { "type": "string", "enum": ["calc", "optimize", "print"], "default": "calc" } }, "required": ["facade_azimuth", "panel_count"] } } ``` --- ## 6. Physikalische & Mathematische Berechnungsmodelle ### 6.1 DWD-Klimadaten & Geländehöhe (Mini-DEM) - Duale Datenbasis über 20 DWD-Stationen (2D-IDW-Interpolation): * `dwd_1991_2020`: WMO-Klimanormale (1.036 kWh/m²a Referenz Kassel). * `dwd_2015_2024`: 10-Jahres-Mittel aus CDC-Rasterdaten (1.044 kWh/m²a Referenz Kassel). - Bilineares Mini-DEM Geländemodell (47°N–55°N, 6°O–15°O) mit Lapse-Rate-Temperaturkorrektur ($-0{,}0065\ \text{K/m}$) und barometrischer ICAO-Druckanpassung. ### 6.2 Strahlungstransposition & Diffusmodell (Bimodales Perez 1990) - Erbs-Dekomposition in Direkt- und Diffusstrahlung. - Anisotrope 8-Bin Perez-Verteilung für zirkumsolare, horizontnahe und isotrope Anteile. - Bimodale Trennung jedes Stütztages in klare und bedeckte Stunden mit $k_t$-Gewichtung. - Temperaturabhängige Albedo ($\rho = 0{,}20$; Schneekopplung bei $T_{\text{amb}} \le 2\,^\circ\text{C}$). ### 6.3 Optik & Verschmutzung - Incident Angle Modifier nach Martin & Ruiz ($a_r = 0{,}16$). - Spektrale Airmass-Korrektur $f_{\text{spec}}(m)$ für N-Type TOPCon und c-Si. - Sky View Factor über 64 lambertsche Fibonacci-Halbkugelstrahlen. - Neigungsabhängige Selbstreinigung nach Kimber/IEC 61724-1 ($4{,}5\,\%$ bei $0^\circ$; $1{,}5\,\%$ bei $25^\circ$; $0{,}6\,\%$ bei $90^\circ$). ### 6.4 BIPV-Thermik (Faiman / DIN EN 61724-1) - Zelltemperatur: $T_{\text{cell}} = T_{\text{amb}} + \frac{G_{\text{POA}}}{u_0 + u_1 \cdot v}$ mit regionalem DWD-Windfeld. - Parameter: Hinterlüftet ($u_0=29, u_1=1.5$); Hitzestau ($u_0=15, u_1=0.0$); Freistehend ($u_0=31, u_1=2.8$). - Leistungskoeffizient: $\gamma = -0{,}35\,\%/\text{K}$ bezogen auf 25 °C STC. ### 6.5 Halbzellen-Raycasting & Dioden (DIN EN 50530) - 24-Punkte-Sampling (96 Strahlen im HQ-Scan) mit Penumbra-Halbschattenauflösung. - Modellierung von 3 Bypass-Dioden pro Modul mit Shockley-Thermalgang ($-2{,}0\ \text{mV/K}$). - Mindestspannungssperre: Bei $V_{\text{MPP}} < 16{,}0\ \text{V}$ schaltet der MPPT-Kanal ab. - Wechselrichterkennlinie nach DIN EN 50530 mit Leerlaufverlusten und NREL SAM Sub-Hourly Clipping-Modellierung. ### 6.6 Speicher & Haushaltslast (VDI 4655 / VDI 2067) - LiFePO4-Batteriemodell mit ca. 88 % Roundtrip-Wirkungsgrad und BMS-Standby. - Koinzidenter Eigenverbrauch über Minkowski-P-Norm ($\beta = 3{,}5$) mit VDI 4655 Lastprofilen. - 10-Jahres-Barwertrechnung (NPV) nach VDI 2067 mit Diskontierungszins ($2{,}0\,\%$) und Degradation ($0{,}5\,\%/\text{a}$). --- ## 7. Headless JavaScript API & IPC Das globale Objekt `window.SolarStudio` ermöglicht lokale Headless-Aufrufe: ```javascript // 1. Simulation durchführen: const sim = window.SolarStudio.simulate({ loc: "muenchen", climatePeriod: "dwd_2015_2024", baz: 180, tilt: 25, panels: 2, wp: 440, inv: 800, bat: 2.4, prof: "homeoffice", kwh: 2400 }); console.log(sim.metrics.annual_prod_kwh); // Jahresertrag in kWh/a console.log(sim.metrics.self_consumption_kwh); // Eigennutzung in kWh/a console.log(sim.metrics.annual_savings_eur); // Ersparnis in EUR/a // 2. Neigungs-Optimum ermitteln (LOD Golden Section Search): const opt = await window.SolarStudio.optimize({ loc: "koeln", panels: 2 }); console.log(opt.best_tilt_deg, opt.payback_years); // 3. System-Selbsttest ausführen (41 Prüfpunkte nach DIN/VDI): const audit = await window.SolarStudio.verify(); console.log(audit.meta.overallPassed, audit.meta.integrityChecksum); ``` --- ## 8. Rechtlicher Status & Haftungsausschluss - **Solarpaket 1 (EEG / VDE-AR-N 4105):** Bis zu 800 W AC Wechselrichterleistung und bis zu 2.000 Wp Modulleistung sind als Steckersolargerät gesetzlich geregelt. - **Unverbindliche Planungshilfe:** Die Berechnungen sind rechnerische Modell-Schätzungen auf Basis langjähriger DWD-Mittelwerte. Reale Erträge unterliegen wetter-, montage- und standortbedingten Schwankungen. - **Keine Rechts- oder Statikberatung:** Die Software und erzeugte PDF-Voranfragen für Vermieter/WEGs (§ 554 Abs. 1 BGB, § 20 Abs. 2 WEG) sind unverbindliche Orientierungshilfen. - **Open Source:** Bereitgestellt unter freier MIT-Lizenz ohne Mängelgewähr und ohne vertragliche Leistungsgarantien.