{"id":51133486,"url":"https://github.com/hollako/home-assistant-3d-floorplan","last_synced_at":"2026-06-25T15:01:24.054Z","repository":{"id":358553537,"uuid":"1241811982","full_name":"Hollako/Home-Assistant-3D-Floorplan","owner":"Hollako","description":"A Home Assistant Lovelace card for placing entities on an interactive 3D Floorplan","archived":false,"fork":false,"pushed_at":"2026-05-30T17:03:28.000Z","size":2211,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T18:17:07.720Z","etag":null,"topics":["3d","custom-card","floorplan","hacs","home-assistant","lovelace"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hollako.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T21:03:11.000Z","updated_at":"2026-05-30T17:03:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Hollako/Home-Assistant-3D-Floorplan","commit_stats":null,"previous_names":["hollako/home-assistant-3d-floorplan"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Hollako/Home-Assistant-3D-Floorplan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hollako%2FHome-Assistant-3D-Floorplan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hollako%2FHome-Assistant-3D-Floorplan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hollako%2FHome-Assistant-3D-Floorplan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hollako%2FHome-Assistant-3D-Floorplan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hollako","download_url":"https://codeload.github.com/Hollako/Home-Assistant-3D-Floorplan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hollako%2FHome-Assistant-3D-Floorplan/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34780126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","custom-card","floorplan","hacs","home-assistant","lovelace"],"created_at":"2026-06-25T15:01:23.352Z","updated_at":"2026-06-25T15:01:24.044Z","avatar_url":"https://github.com/Hollako.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Home Assistant 3D Floorplan\n\n![Home Assistant 3D Floorplan preview](images/preview.png)\n\nA Lovelace custom card for placing Home Assistant entities on a 3D model and rendering physically-based lighting directly in the browser. Load a `.glb`, switch to Edit Mode, select an entity from the sidebar, click the model to place it, then configure lighting zones and light types for a realistic room render.\n\nThe card element is `custom:home-assistant-3d-floorplan`.\n\n## Install\n\nAdd this JavaScript resource in Home Assistant:\n\n```yaml\nurl: /local/Home-Assistant-3D-Floorplan.js\ntype: module\n```\n\nIf installed through HACS:\n\n```yaml\nurl: /hacsfiles/Home-Assistant-3D-Floorplan/Home-Assistant-3D-Floorplan.js\ntype: module\n```\n\n## Basic Card\n\n```yaml\ntype: custom:home-assistant-3d-floorplan\ntitle: 3D Floorplan\nmodel: /local/floorplans/home.glb\nview_mode: \"3d\"\nmarkers: []\n```\n\n## Coordinate System\n\nThe card uses the standard Three.js / GLTF coordinate convention:\n\n- **X** - east/west floor axis\n- **Y** - vertical (height)\n- **Z** - north/south floor axis\n\nThis matches `.glb` files exported from Blender with the default Y-up orientation. No `coordinate_map` override is needed for standard exports.\n\n## Markers\n\nMarker colors reflect live entity state:\n\n- Red: unavailable or unknown\n- Yellow: active / on / open / detected\n- Dark: inactive / off / closed / clear\n- Green: available neutral state\n\nDefault press actions:\n\n```yaml\nmarker_tap_action: auto\nmarker_hold_action: auto\nedit_marker_tap_action: select\nedit_marker_hold_action: move\nmarker_hold_ms: 650\n```\n\n`auto` uses domain defaults - lights and switches toggle on tap; sensors, binary sensors, and climate entities open more-info. Edit Mode is shown only when `hass.user.is_admin === true`.\n\nMarkers export as:\n\n```yaml\nmarkers:\n  - entity: light.kitchen\n    name: Kitchen Light\n    icon: mdi:lightbulb\n    tap_action: toggle\n    hold_action: more-info\n    light_intensity: 100\n    light_type: spot\n    light_radius: 120\n    x: 850.0000\n    y: 230.0000\n    z: 610.0000\n```\n\nTemperature and humidity sensors show their live value on the marker. Use **Marker display** in Edit Mode to force icon or value display:\n\n```yaml\nmarker_display: value   # auto | icon | value\n```\n\n## Edit Mode\n\nSwitch to Edit Mode to place and configure markers.\n\n**Sidebar** - lists all HA entities. Placed markers show a **Remove** button. Unplaced markers show **Add**; clicking it then clicking the 3D model places the marker at that surface point.\n\n**Floating panel** - selecting a placed marker opens a panel on the right with:\n- Icon picker\n- Marker display setting\n- Tap / Hold actions\n- Light intensity, type, radius, and render parameters (for `light.*` entities in Positional zones)\n- XYZ coordinates\n- Move / Delete buttons\n\n\u003cimg src=\"images/Marker%20Settings.png\" alt=\"Marker settings panel\" width=\"350\" /\u003e\n\n**Axes gizmo** - a small XYZ orientation indicator appears in the top-left corner in Edit Mode, showing how the model axes relate to the camera.\n\n**Export YAML** - the sidebar exports the full card YAML with current marker positions, zone definitions, and presets. Press **Copy YAML** to copy it to the clipboard.\n\n## Camera Views\n\nThe compass in the corner provides:\n\n- **Top** - straight top-down view\n- **N / E / S / W** - 45-degree angled side views\n\nIn Edit Mode, **Save Home** stores the current camera position as the startup view. The saved view is stored per-floor and is written to the YAML export:\n\n```yaml\ndefault_view:\n  position: [6.2500, 4.5000, 8.7500]\n  target: [0.0000, 0.8000, 0.0000]\n  zoom: 1.0000\n```\n\n## Brightness Areas (Lighting Zones)\n\nEdit Mode can define room polygons that drive the 3D lighting render. Press **Add Area**, then **Draw**, and click the floor to trace the room boundary.\n\n### Lighting Modes\n\nEach zone has two modes, selectable in the zone settings:\n\n**Area (zone-wide glow)** - a single flat ambient fill covers the whole floor polygon. Suitable for zones with diffuse overhead lighting or when no individual light positions are needed.\n\n![Area glow mode](images/Area_Glow.png)\n\n**Positional (per-light pools)** - each `light.*` marker placed inside the zone creates its own floor pool, wall glow, ceiling glow, and GI bounce based on its position and light type.\n\n![Positional lighting mode](images/Positional.png)\n\n### Zone Settings\n\n```yaml\nbrightness_zones:\n  - id: living-room\n    name: Living Room\n    color: \"#f8d66d\"\n    height: 280\n    day_opacity: 0.50\n    night_opacity: 1.00\n    lighting_mode: positional\n    illuminance_enabled: true\n    illuminance_entity: sensor.living_room_lux\n    show_lux: true\n    points:\n      - x: 100.0000\n        y: -300.0000\n      - x: 900.0000\n        y: -300.0000\n      - x: 900.0000\n        y: -1100.0000\n```\n\n**Illuminance sensor** - when enabled, the shade is driven dynamically by a lux sensor. Low lux approaches night shade; 300 lux reaches day shade; brighter reduces shade further. The sensor is selected from a searchable dropdown of all `sensor.*` and `input_number.*` entities. Falls back to `sun.sun` day/night when disabled or sensor is unavailable.\n\n## Light Types (Positional Mode)\n\nEach `light.*` marker in a Positional zone has a **Light type** that controls how the glow is rendered on floors, walls, and ceilings.\n\n| Type | Description |\n|---|---|\n| **Spot** | Ceiling downlight. Renders a cone on the wall with inner/outer angle, a bright floor hotspot, and GI bounce. Supports tilt X/Y to aim off-center. |\n| **Cove** | Indirect ceiling bounce. Produces a top-heavy wall wash that fades downward and a soft uniform floor fill centered on the zone. |\n| **Linear** | LED strip. Elongated floor pool; wall wash runs the length of the strip path. |\n| **Lamp** | Floor or table lamp. Tight floor pool, soft wall glow radiating outward. |\n\nSet **Light radius** to override the auto-computed pool size (in model units). Leave blank for automatic sizing based on mount height and zone dimensions.\n\n### Light Paths (Linear / Cove)\n\nLinear and Cove lights support a drawn path that distributes sample points along the strip:\n\n- **Draw line** - click the 3D model to add path points one by one\n- **Rectangle** - define width, depth, and rotation; the card generates a closed 4-corner loop automatically. The marker position becomes the rectangle center.\n\n### Sub-spots (Spot)\n\nA spot marker can contain multiple render-only sub-spots - extra light positions that share the parent entity state but each have their own XYZ position and render parameters. Useful for a single HA entity that controls a row of ceiling spots.\n\n## Render Parameters\n\nEvery light marker has a full set of render parameters accessible in the **Advanced** section of the floating panel. Parameters are grouped into four sections:\n\n### Core\n| Param | Description |\n|---|---|\n| `intensity` | Overall brightness multiplier |\n| `distance` | How far the light reaches - affects wall reach and floor pool size |\n| `decay` | Falloff speed. Low = soft wide wash. High = sharp tight edge |\n\n### Light Shape\n| Param | Applies to | Description |\n|---|---|---|\n| `angle` | Spot | Cone half-angle in radians. Smaller = narrower beam |\n| `penumbra` | Spot | Softness of cone edge. 0 = hard cut, 1 = fully feathered |\n| `tilt_x` | Spot, Linear, Cove | Tilts the light in the X floor direction |\n| `tilt_y` | Spot, Linear, Cove | Tilts the light up/down |\n| `width` | Linear, Cove | Width of the rectangular light source |\n| `height` | Linear, Cove | Height of the rectangular light source |\n\n### Floor Pool\n| Param | Description |\n|---|---|\n| `floor_hotspot_size` | Size of the bright core relative to the main pool. Most effective on Spot, Lamp |\n| `floor_saturation` | Color saturation of the floor glow. 0 = grey, 1.5 = vivid |\n| `floor_outer_size` | Radius multiplier of the wide ambient scatter layer |\n| `floor_outer_brightness` | Brightness of the outer scatter layer |\n| `gi_brightness` | GI bounce intensity - secondary soft floor fill. 0 = disabled |\n| `gi_radius` | Radius multiplier of the GI bounce mesh |\n| `gi_warmth` | Warms the GI bounce color to simulate warm floor reflection |\n\n### Wall Glow\n| Param | Description |\n|---|---|\n| `wall_intensity_scale` | Multiplier for overall wall glow brightness |\n| `wall_height_limit` | Fraction of zone height the wall mesh covers. 1.0 = full wall |\n| `wall_lower_bias` | Shifts glow center down the wall. 0 = near fixture, 1 = near floor |\n\nHovering over any parameter value shows a tooltip with a description and which light types it is most effective on.\n\n### Presets\n\nParameter sets can be saved as named presets and reused across lights:\n\n- **Save as preset** - prompts for a name and stores the current resolved values\n- **Reset** - clears all per-light overrides and returns to type defaults\n- **Export** - downloads the resolved parameters as a `.json` file\n- **Import** - loads a previously exported `.json` and applies it to the current light\n\nPresets are saved to `localStorage` and survive JavaScript file updates. The YAML export also includes the `light_presets:` block so they can be committed to the card config:\n\n```yaml\nlight_presets:\n  narrow_spot:\n    angle: 0.25\n    penumbra: 0.3\n    wall_intensity_scale: 1.2\n```\n\nPer-light overrides and preset assignments export with the marker:\n\n```yaml\nmarkers:\n  - entity: light.hallway_spot\n    light_type: spot\n    light_preset: narrow_spot\n    render_params:\n      tilt_x: 15\n      wall_lower_bias: 0.2\n    x: 500.0000\n    y: 230.0000\n    z: 400.0000\n```\n\n## Floor and Ceiling Glow Clipping\n\nAll floor pools, ceiling glows, and GI bounce meshes are clipped to the zone polygon boundary. Light cannot bleed through walls into adjacent rooms regardless of pool radius.\n\n## Multiple Floors\n\n```yaml\ntype: custom:home-assistant-3d-floorplan\ntitle: Home Floorplan\nview_mode: \"3d\"\nfloors:\n  - id: ground\n    name: Ground Floor\n    model: /local/floorplans/ground-floor.glb\n    markers: []\n    brightness_zones: []\n  - id: first\n    name: First Floor\n    model: /local/floorplans/first-floor.glb\n    markers: []\n    brightness_zones: []\n```\n\n## Offline / Three.js Setup\n\n### What is and isn't local by default\n\nWhen you install via HACS or manually, the card file (`Home-Assistant-3D-Floorplan.js`) is stored locally on your Home Assistant instance. Your `.glb` model is also served from your local `/www/` folder.\n\nHowever, **Three.js (the 3D engine) is not bundled by default**. The card fetches it from the external CDN `esm.sh` on first load:\n\n```yaml\nthree_url: \"https://esm.sh/three@0.165.0\"   # default - requires internet\n```\n\nThis means an internet connection is required on every page load unless you take the extra step below.\n\n### Making it fully offline (recommended)\n\nThe repository includes a pre-built bundle at `dist/three.bundle.min.js`. Copy it to your Home Assistant `www` folder:\n\n```\n/config/www/three.bundle.min.js\n```\n\nThen point the card at it:\n\n```yaml\ntype: custom:home-assistant-3d-floorplan\ntitle: 3D Floorplan\nmodel: /local/floorplans/home.glb\nthree_bundle_url: /local/three.bundle.min.js\n```\n\nWith this in place, **everything runs 100% offline** - no external requests, no CDN dependency. This also fixes loading issues in the Home Assistant Companion App on iOS/Android, which can block remote module imports.\n\n### Alternative - host individual Three.js files\n\nIf you prefer to host the individual modules rather than the bundle:\n\n```yaml\nthree_url: /local/vendor/three/three.module.js\ngltf_loader_url: /local/vendor/three/GLTFLoader.js\nobj_loader_url: /local/vendor/three/OBJLoader.js\norbit_controls_url: /local/vendor/three/OrbitControls.js\n```\n\nUse matching files from Three.js release `0.165.0`.\n\n## Performance Notes\n\n- Use `.glb` format - single file, browser-optimised, carries geometry, materials, and textures together\n- Zone polygon complexity affects floor pool rendering - simpler polygons with fewer vertices render faster\n- Increase `light_radius` and reduce sample count for Linear/Cove lights covering large areas\n- The GI bounce (`gi_brightness`) is disabled by default; enable only where the extra ambient fill is visible\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhollako%2Fhome-assistant-3d-floorplan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhollako%2Fhome-assistant-3d-floorplan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhollako%2Fhome-assistant-3d-floorplan/lists"}