[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-76312":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":39,"readmeContent":40,"aiSummary":41,"trendingCount":16,"starSnapshotCount":16,"syncStatus":42,"lastSyncTime":43,"discoverSource":44},76312,"Helios","ReikanYsora\u002FHelios","ReikanYsora","☀️ 3D solar card for Home Assistant: live sun, clouds, PV production + forecast, battery, and LiDAR-cast shadows on your home.","https:\u002F\u002Fgithub.com\u002FReikanYsora\u002FHelios#readme",null,"TypeScript",326,7,1,17,0,77,79,261,231,2.71,"MIT License",false,"main",[26,27,28,29,30,31,32,33,34,35,36,37,38],"custom-card","hacs","hacs-default","home-assistant","homeassistant","lovelace","lovelace-card","maplibre","maptiler","photovoltaic","solar","solar-energy","weather","2026-06-12 02:03:41","# ☀️ HELIOS\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![hacs_badge](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHACS-Custom-orange.svg)](https:\u002F\u002Fgithub.com\u002Fhacs\u002Fintegration)\n[![HA-CustomCard](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHome%20Assistant-Custom%20Card-blue)](https:\u002F\u002Fgithub.com\u002Fcustom-cards\u002Fboilerplate-card)\n[![Buy Me a Coffee](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuy%20Me%20a%20Coffee-Donate-orange?style=flat-square&logo=buy-me-a-coffee)](https:\u002F\u002Fwww.buymeacoffee.com\u002Freikanysora)\n\n**HELIOS** is a custom [Home Assistant](https:\u002F\u002Fwww.home-assistant.io\u002F) Lovelace card that visualises solar conditions at your home in real time.\n\nIt pulls weather forecasts from **Open-Meteo** (no key needed), reads the optional production sensor of your photovoltaic install from your HA states, and stitches them together onto an interactive 3D map powered by **MapLibre GL** with vector tiles served by **[OpenFreeMap](https:\u002F\u002Fopenfreemap.org\u002F)** (free, no key, no signup). The whole map, sun arc, sun disc, incidence ray, cloud cover, building extrusions and cast shadows, irradiance graph, PV graph, reflects the timeline cursor; scrub it 2 days into the past or 2 days into the future and watch every layer follow.\n\n---\n\n## At a glance\n\n* **Sun arc**, the sun's full daily trajectory, projected with depth onto your home. Below-horizon segments render as discreet dots behind the home so the underground portion of the arc reads as a calm background, while the daylight portion + sun disc + irradiance readout always stack on top of every chip.\n* **Live sun disc with irradiance-driven halo**, pinned on the arc; the inner fill scales with live W\u002Fm², a soft sun-coloured halo fades cleanly from 100 % at the centre to 0 % at the rim, with peak alpha driven by the same irradiance reading.\n* **Incidence ray**, dashed line from sun to PV chip, animated to flow at a speed proportional to live irradiance. The stronger the sun, the faster it pulses.\n* **Cloud cover disc**, translucent disc on the ground, scaled by live cloud-cover %, outlined in the configured cloud colour. A fixed black ring marks the 100 % reference. Hover for the low\u002Fmid\u002Fhigh breakdown.\n* **PV production chip** *(optional)*, pin above the home, shows the **instantaneous** production in W\u002FkW. Cumulative-energy sensors (kWh) are differentiated automatically over a rolling 60 s window.\n* **PV → home animated leader**, a vertical dashed line in the configured PV colour from the production chip down to a small anchor bead on the home; when you set the installation's peak power (kWp) in the editor, dashes flow toward the home at a speed proportional to current production over that peak. Static and arrow-less when production is zero.\n* **PV production overlay + forecast** *(optional)*, when a PV entity is configured, the card surfaces the current production as a chip below the home and a dedicated graph above the timeline. If you also enter your installation's peak power (kWp) in the editor, a dotted forecast line based on the Haurwitz \u002F Kasten-Czeplak clear-sky model + live cloud cover overlays the past observation, and the chip switches to a predicted value (italicised, prefixed `≈`) when scrubbing into the future.\n* **Home battery overlay** *(optional)*, two independent chips flank the PV chip on the same horizontal axis: State of Charge on the left, signed instantaneous power on the right. Each chip is connected to PV by a short static dotted L-leader. Either entity is independently optional; the corresponding chip only renders when its entity is set.\n* **Detail dashboard**, click the home to dive into a chip-styled overlay with four compact sections that fade in one after the other: today's produced kWh + projected end-of-day total + peak time, a 7-day \"bottles\" chart of recent production, tomorrow's forecast headline (estimated kWh + peak hour), and a battery vessel showing live SoC + the day's charge \u002F discharge totals. Click anywhere outside to exit.\n* **Hover home glow**, hovering the home triggers a soft sun-coloured halo underneath the silhouette so the focal building reads as interactive before you click. Halo colour tracks the configured sun colour.\n* **Auto-rotation** *(opt-in)*, when enabled, the camera slowly orbits the home in the opposite direction to the sun's apparent motion (~1°\u002Fs) after a few seconds of inactivity. Any pinch \u002F drag pauses it instantly and it resumes after a fresh idle window.\n* **Timeline**, 5 days wide (2 past + today + 2 forecast). Dual-area chart with irradiance on top and cloud cover below. A second graph appears above when a PV entity is configured. Click or drag anywhere on the timeline to scrub; the whole map snaps to the selected instant.\n* **Multilingual**, English, French, German, Spanish, Italian, Dutch, Portuguese, Norwegian. Adapts to your Home Assistant language.\n\n---\n\n## Screenshots\n\n![HELIOS PREVIEW 01](https:\u002F\u002Fraw.githubusercontent.com\u002FReikanYsora\u002FHelios\u002Fmain\u002Fimages\u002Fpreview_01.png)\n![HELIOS PREVIEW 02](https:\u002F\u002Fraw.githubusercontent.com\u002FReikanYsora\u002FHelios\u002Fmain\u002Fimages\u002Fpreview_02.png)\n![HELIOS PREVIEW 02](https:\u002F\u002Fraw.githubusercontent.com\u002FReikanYsora\u002FHelios\u002Fmain\u002Fimages\u002Fpreview_03.png)\n\n*HELIOS displaying current solar exposure, cloud coverage and live PV production for the user's home.*\n\n---\n\n## Installation via HACS\n\n### Custom repository (recommended for now)\n\n1. Open HACS → click the three-dot menu → **Custom repositories**.\n2. Add this repository: `https:\u002F\u002Fgithub.com\u002FReikanYsora\u002FHelios`\n3. Set category to **Dashboard**.\n4. Install **HELIOS** from the dashboard list.\n5. Reload your browser.\n6. Add the card to your dashboard:\n   ```yaml\n   type: custom:helios-card\n   ```\n\n### Manual installation\n\n1. Download `helios.js` from the latest [release](https:\u002F\u002Fgithub.com\u002FReikanYsora\u002FHelios\u002Freleases).\n2. Copy it to `\u003Cconfig>\u002Fwww\u002Fcommunity\u002Fhelios\u002F`.\n3. Add the resource to your dashboard:\n   ```yaml\n   url: \u002Flocal\u002Fcommunity\u002Fhelios\u002Fhelios.js\n   type: module\n   ```\n\n---\n\n## Configuration\n\nNo API key required. The basemap is served by [OpenFreeMap](https:\u002F\u002Fopenfreemap.org\u002F) (free, no signup, no rate limits) and weather comes from Open-Meteo (also free, no key).\n\nThe visual editor exposes every option. Minimal config:\n\n```yaml\ntype: custom:helios-card\n```\n\nEvery option below is editable visually:\n\n| Key | Type | Default | Description |\n|---|---|---|---|\n| `map-style` | `'streets' \\| 'minimal'` | `'streets'` | Basemap style. `streets` resolves to OpenFreeMap's [Liberty](https:\u002F\u002Ftiles.openfreemap.org\u002Fstyles\u002Fliberty) (full-colour OpenMapTiles look); `minimal` resolves to [Positron](https:\u002F\u002Ftiles.openfreemap.org\u002Fstyles\u002Fpositron) (muted grey, very sober). Both flip to OpenFreeMap's [Dark](https:\u002F\u002Ftiles.openfreemap.org\u002Fstyles\u002Fdark) when `card-theme` is `'dark'`. |\n| `card-theme` | `'light' \\| 'dark'` | `'light'` | Card chrome skin (chips, charts, buttons, tooltips, scrub overlay) AND the 3D map basemap flip between a light surface (white plate) and a dark surface (near-black `#191a1b` plate), so the card sits cleanly inside light or dark Home Assistant dashboards. |\n| `pixel-ratio` | `'auto' \\| '1x'` | `'auto'` | WebGL canvas pixel density. `auto` uses the device's native devicePixelRatio (capped at 2 on desktop, 1.25 on mobile). `1x` forces 1.0, the cheapest per-frame fragment workload, useful on low-end devices or for long sessions where battery \u002F heat matters more than crispness. |\n| `auto-rotate-enabled` | boolean | `false` | When `true`, the camera orbits the home slowly during idle. Any pinch \u002F drag \u002F wheel pauses it for 5 s and it resumes from the user's bearing. Off by default; enable for kiosk \u002F always-on dashboards. |\n| `show-labels` | boolean | `true` | Show street names, building numbers, POIs and place names on the basemap. |\n| `building-radius` | meters | `100` | Distance around the home within which surrounding buildings are rendered in 3D. Buildings outside the radius are not drawn, the perf win in dense urban areas. Range: 20–1000 m. |\n| `building-cluster-radius` | meters | `0` | Distance around the home within which every building joins the home group at full opacity. Use this to attach verandas, garages and sheds to the main house. Range: 0–100 m. |\n| `building-opacity` | 0–1 | `0.25` | Opacity of the surrounding buildings. The home (and its cluster) always stays at full opacity so it reads as the focal point. |\n| `building-color` | hex | `#d2d2d7` | Base colour for every rendered building, modulated by sun altitude across the day. |\n| `shadows-enabled` | boolean | `true` | Master toggle for cast ground shadows. When `false`, no shadows are projected. When `true`, the source is picked automatically: a LiDAR provider when one covers the home (buildings AND vegetation), OpenFreeMap building footprints otherwise (buildings only). All shadows are clipped to the building visibility radius for consistency with the rendered surroundings. See [LiDAR coverage](#lidar-coverage). |\n| `lidar-precision` | `'low' \\| 'medium' \\| 'high'` | `'medium'` | LiDAR raster size when a provider covers the home. Higher = finer shadow contours but a bigger payload. `low` 256², `medium` 512², `high` 1024² (close to IGN native sampling). No effect out of coverage. |\n| `shadow-opacity` | 0–1 | `0.32` | Opacity of the cast ground shadows. |\n| `sun-color` | hex | `#EF9F27` | Sun disc + arc + timeline irradiance area. |\n| `cloud-color` | hex | `#5A8DC4` | On-ground disc + timeline cloud area. |\n| `pv-power-entity` | entity_id | - | Optional. Power (W\u002FkW) or cumulative energy (Wh\u002FkWh) sensor. |\n| `pv-peak-kwp` | number | - | Optional. Installed peak power in kilowatts-peak. When set, drives the dotted clear-sky forecast line on the PV chart and paces the PV → home animated leader against your installation. Leave empty to hide the forecast (live observation + today's peak still display). |\n| `pv-tilt` | degrees | `0` | Optional. Tilt angle of your panels from horizontal: 0 for a flat install, 90 for fully vertical (e.g. balcony). When greater than 0, the forecast model switches from a horizontal-panel assumption to a Liu-Jordan transposition so steep-roof and balcony installs stop seeing a flat-roof prediction (typically a 3–4× overshoot). Leave at 0 to keep the legacy behaviour. |\n| `pv-azimuth` | degrees | `180` | Optional. Compass bearing your panels face, clockwise from north: 0 = north, 90 = east, 180 = south, 270 = west. Only used when `pv-tilt > 0`. |\n| `pv-color` | hex | `#27B36B` | PV chip border + text + leader + dedicated graph. |\n| `battery-soc-entity` | entity_id | - | Optional. Battery State-of-Charge sensor (`%`, usually `device_class: battery`). Renders as a chip on the LEFT of the PV chip showing the live percentage. |\n| `battery-power-entity` | entity_id | - | Optional. Battery power sensor (W\u002FkW). Signed: positive is interpreted as charging. Renders as a chip on the RIGHT of the PV chip showing the signed reading verbatim. |\n| `battery-color` | hex | `#FF5252` | Battery colour reused on both battery chips' borders + text + the static dotted leaders that connect each to the PV chip. |\n| `date-format` | string | `mm-dd` | Tokens: `yyyy`, `yy`, `mm`, `dd`. |\n| `time-format` | `'12h' \\| '24h'` | `'24h'` | Clock display in the top-right chip. |\n\nThe PV entity picker filters to sensors that look like a power or energy reading (`device_class: power|energy` OR a unit in `W\u002FkW\u002FMW\u002FWh\u002FkWh\u002FMWh`). Both kinds work; the card auto-detects whether to display the entity's state directly (power sensor) or differentiate it on the fly (cumulative energy).\n\n---\n\n## How it works\n\n* **Solar position**, simplified declination + equation of time, with a hour-angle normalisation so longitudes far from Greenwich (NYC, Tokyo, Sydney) stay correct. Validated against the NOAA SPA reference (mean altitude error 0.30°, mean azimuth error 0.36° across 376 sample points).\n* **Clear-sky GHI**, Haurwitz (1945), `1098 · cos(z) · exp(-0.059 \u002F cos(z))` W\u002Fm². MAE ~62 W\u002Fm² versus PVGIS \u002F NREL benchmarks.\n* **Cloud attenuation**, Kasten-Czeplak (1980) cubic, `1 - 0.75 · (cloud\u002F100)^3.4`.\n* **Multi-model weather**, every fetch queries one global model (ECMWF IFS 0.25°) plus the most accurate national\u002Fregional model for your home location (AROME-France, UKMO UK, DWD ICON-D2, ItaliaMeteo, MET Nordic, NOAA HRRR, KMA LDPS, JMA MSM, BOM ACCESS-G, or ECMWF + GFS elsewhere). Per-timestep median fusion absorbs single-model outliers.\n* **Effective cloud cover**, the card replaces Open-Meteo's raw `cloud_cover` (satellite-view total) with `low + 0.6·mid + 0.2·high` (capped at 100 %), matching ground perception and shortwave attenuation.\n* **PV instantaneous rate**, for cumulative-energy sensors, the card maintains a 5-minute rolling buffer of state samples and differentiates over a ~60 s window, giving a real \"what's being produced right now\" reading instead of a misleading lifetime total.\n* **PV forecast (optional)**, when `pv-peak-kwp` is set, the card multiplies the live `effective_cover` by Haurwitz \u002F Kasten-Czeplak per timestamp and scales by the installed peak power, painting a dotted prediction curve on the PV chart that the live observation tracks against. Scrubbing into the future flips the PV chip to the predicted figure (italicised, prefixed `≈`).\n\nFull algorithm + architecture details: see [ARCHITECTURE.md](.\u002FARCHITECTURE.md).\n\n---\n\n## LiDAR coverage\n\nWhen `shadows-enabled` is on, HELIOS picks between two shadow sources automatically:\n\n* **LiDAR**, only when a provider covers your home. With LiDAR, cast shadows reflect real **buildings AND vegetation** (trees, hedges, etc.) captured by aerial scans.\n* **OpenFreeMap building footprints**, everywhere else. Buildings only, no vegetation.\n\nLiDAR coverage today:\n\n| Country | Provider | Coverage | Format | Note |\n| :--- | :--- | :--- | :--- | :--- |\n| France | **IGN LiDAR HD** | Metropolitan France + Corsica | BIL float32 | Pre-computed nDSM, single fetch |\n| England | **Environment Agency LiDAR Composite** | ~99% of England | GeoTIFF float32 | Two fetches (DSM + DTM), subtracted client-side |\n| Spain | **IGN España PNOA-LiDAR (MDSn)** | Peninsular Spain + Balearics | GeoTIFF float32 | Two coverages (vegetation + buildings), merged via MAX. Canarias not covered |\n| Netherlands | **PDOK AHN4** | Mainland NL | GeoTIFF float32 | Two coverages (DSM + DTM), subtracted client-side. Caribbean Netherlands not covered |\n| Norway | **Kartverket NHM** | Mainland Norway + Svalbard | GeoTIFF float32 (ArcGIS) | Two services (DOM + DTM), subtracted client-side |\n\nOther national LiDAR programmes were probed and not yet integrated:\n\n* **Wales (Natural Resources Wales)** , per-tile ZIP downloads only, no live raster query endpoint.\n* **Switzerland (swisstopo)** , published WMS only carries pre-rendered PNG hillshade, not raw heights. Raw `swissALTI3D` rasters are downloadable as files only.\n* **Slovakia (ZBGIS)** , DMR (terrain) is available as GeoTIFF, but DMP (surface) is only published as cached PNG visualisations.\n* **Denmark (Datafordeler DHM)** , WCS GeoTIFF exists but requires a per-user API key \u002F OAuth signup, integration parked until that friction is reduced.\n\nIf your country publishes a usable LiDAR HD endpoint (raw float heights via WMS or WCS, CORS-friendly, no per-user authentication) and you'd like to see it integrated, open an issue. The provider plug-in shape is documented in [ARCHITECTURE.md](.\u002FARCHITECTURE.md) (`helios-lidar.ts` interface + `.\u002Fhelios-lidar\u002Fproviders\u002F` registry).\n\nOut of coverage the card still renders shadows from OpenFreeMap building footprints, so the visual works worldwide, the LiDAR layer is a precision upgrade where available.\n\n---\n\n## Technical stack\n\n| Component | Technology |\n| :--- | :--- |\n| **Frontend** | [Lit](https:\u002F\u002Flit.dev\u002F) 3, TypeScript |\n| **Mapping** | [MapLibre GL JS](https:\u002F\u002Fmaplibre.org\u002F) 5 + [OpenFreeMap](https:\u002F\u002Fopenfreemap.org\u002F) vector tiles (free, no key, OpenMapTiles schema) |\n| **GeoTIFF** | [geotiff.js](https:\u002F\u002Fgithub.com\u002Fgeotiffjs\u002Fgeotiff.js) for parsing the Float32 LiDAR rasters from UK \u002F ES \u002F NL \u002F NO providers |\n| **Weather data** | [Open-Meteo API](https:\u002F\u002Fopen-meteo.com\u002F) (free, no key) |\n| **Solar math** | NOAA-validated (mean altitude error 0.30°, mean azimuth error 0.36°) |\n| **Build** | Vite 5 |\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run dev        # local dev server\nnpm run typecheck  # strict TS\nnpm run build      # produces dist\u002Fhelios.js\n```\n\nSource layout:\n\n| File | Purpose |\n| :--- | :--- |\n| `src\u002Fhelios-card.ts`        | Top-level Lit card, render(), state, lifecycle |\n| `src\u002Fhelios-card-css.ts`    | Card styles |\n| `src\u002Fhelios-config.ts`      | Visual editor + color picker + config helpers |\n| `src\u002Fhelios-engine.ts`      | MapLibre orchestration, layers, projections |\n| `src\u002Fhelios-buildings.ts`   | Self-sourced building tile fetch + radius \u002F cluster filter |\n| `src\u002Fhelios-shadows.ts`     | Ground-projected shadow polygons (flat-opacity raster pipeline) |\n| `src\u002Fhelios-lidar.ts`       | `LidarSource` interface + provider registry |\n| `src\u002Fhelios-lidar\u002Fhelios-lidar-pipeline.ts` | Shared height-raster → shadow-polygon pipeline (flood fill + convex hull) |\n| `src\u002Fhelios-lidar\u002Fhelios-lidar-geotiff.ts`  | Float32 GeoTIFF fetch + decode + DSM-DTM math helpers |\n| `src\u002Fhelios-lidar\u002Fproviders\u002F` | One file per country (`helios-lidar-fr.ts`, `-uk`, `-es`, `-nl`, `-no`) |\n| `src\u002Fhelios-sun.ts`         | Solar position + Haurwitz \u002F Kasten-Czeplak math |\n| `src\u002Fhelios-weather.ts`     | Open-Meteo multi-model fetch + cache |\n| `src\u002Fi18n\u002F`                 | 8-locale strict-typed translations (en\u002Ffr\u002Fde\u002Fes\u002Fit\u002Fnl\u002Fpt\u002Fno) |\n\n---\n\n## Credits & data sources\n\nHELIOS depends on several open data services. None require an account or API key.\n\n* **[OpenFreeMap](https:\u002F\u002Fopenfreemap.org\u002F)** — free vector basemap tiles + styles (Liberty, Positron, Dark) built from OpenStreetMap data via the OpenMapTiles schema. The buildings, labels and the basemap itself all come from here. Big thank you to the OpenFreeMap project for hosting a public, no-key, no-rate-limit instance — without it, HELIOS would still be hostage to a paid map provider.\n* **[OpenStreetMap](https:\u002F\u002Fwww.openstreetmap.org\u002Fcopyright)** — the underlying map data behind every OpenFreeMap tile. © OpenStreetMap contributors.\n* **[Open-Meteo](https:\u002F\u002Fopen-meteo.com\u002F)** — weather forecasts (cloud cover, irradiance, etc.). Free, no key, multi-model fusion under the hood.\n* **National LiDAR providers** — IGN (France), Environment Agency (England), IGN España (Spain), PDOK (Netherlands), Kartverket (Norway). See [LiDAR coverage](#lidar-coverage) for the per-country credits.\n* **[MapLibre GL JS](https:\u002F\u002Fmaplibre.org\u002F)** — the WebGL map engine that draws every frame.\n* **[geotiff.js](https:\u002F\u002Fgithub.com\u002Fgeotiffjs\u002Fgeotiff.js)** — GeoTIFF Float32 decoder used by the UK \u002F ES \u002F NL \u002F NO LiDAR providers.\n\n---\n\n## About me\n\nI build bridges between data and reality. To me, development is more than a profession; it is the tool I have used since childhood to try and decode the complexity of the world around us. I learn every day, fully aware that total understanding is an infinite horizon I will likely never reach, but the journey is worth it.\n\n---\n\n## Support my work\n\nIf you find this project useful and want to support its development, feel free to buy me a coffee (or another battery ;-))!\n\n\u003Ca href=\"https:\u002F\u002Fwww.buymeacoffee.com\u002Freikanysora\">\u003Cimg src=\"https:\u002F\u002Fimg.buymeacoffee.com\u002Fbutton-api\u002F?text=+1 W\u002Fm² of motivation&emoji=☀️&slug=reikanysora&button_colour=5F7FFF&font_colour=ffffff&font_family=Inter&outline_colour=000000&coffee_colour=FFDD00\" \u002F>\u003C\u002Fa>\n\n---\n\n## License\n\nThis project is licensed under the MIT License, see the [LICENSE](LICENSE) file for details.\n","HELIOS 是一个专为 Home Assistant 设计的 Lovelace 自定义卡片，用于实时可视化家庭太阳能状况。该项目利用 MapLibre GL 和 Open-Meteo 提供的数据，在3D地图上展示太阳轨迹、光照强度、云层覆盖以及光伏系统发电情况等信息。其核心功能包括动态显示太阳弧线、实时更新的太阳光盘及其辐射强度、从太阳到光伏板的入射光线动画、基于当前云量百分比调整透明度的云层覆盖圆盘、可选的光伏生产芯片及预测图等。适合拥有或计划安装家用光伏发电系统的用户使用，帮助他们更直观地理解并优化太阳能资源利用效率。",2,"2026-06-11 03:54:56","CREATED_QUERY"]