The LuxLab handbook.

LuxLab turns a room, a set of real luminaire files and a work plane into a calculated lighting study in your browser. This handbook explains what each part of the workspace does, how the calculation is made, what the numbers mean, and where the limits are. It is written for both first-time visitors and practising lighting designers.

LuxLab is an engineering aid, not a certified lighting-design package. Use it to explore and compare designs, then verify anything that matters with an independent tool and the published standard.

Start here

You need a free account to open the tool. Sign in at /login/ or create an account at /signup/. The first administrator creates accounts from the admin dashboard.

The fastest way to see a complete result is the demo atelier:

1. Open the project lobby from the folder button in the header, or go to /tool/.
2. Choose Load demo. LuxLab builds a 6 x 4 x 3 m room with six 2,400 lm downlights, places them and calculates the work plane.
3. Read the warm core of the heatmap, the average lux and the uniformity in the Results panel.
4. Open the report button when the calculation is ready to download an A4 PDF of the study.

Projects belong to this browser and this account. They are stored in IndexedDB, not uploaded to the server. Export a project bundle if you want to move it to another browser or keep an archival copy.

Offline: the installed app opens and works with projects already saved in this browser. A cold start still needs a connection so the accounts service can check your session. See Troubleshooting.

The workspace

The workspace has six regions:

Drag the dividers beside the Room and lights and Results panels to resize them. Double-click a divider to reset it. The widths are stored in this browser. The Layout section of Settings has the same reset and shows the current widths.

The Plan/3D switch is in the top-left of the canvas. The tool rail is on the left of the plan; the zoom, grid and heatmap controls are on the right. On phones the rail keeps Select, Draw rectangle, Draw outline, Pan and More; marquee, snap, undo, redo, grid and heatmap live in More.

Settings holds the theme (Lab or OrbitX), the panel layout and the assistant switch. Theme choice is per browser, not per project. Printing and exported values are unaffected by the theme.

Rooms and the plan

LuxLab models one floor with one or more polygonal rooms. Rooms may share walls, but they may not overlap.

The tools

Snapping is on by default. Hold Alt while dragging to disable it for that gesture. The magnet button in the rail toggles it for the session.

Exact dimensions

Every wall label is editable in Edit outline mode. Click a wall length, type the exact value in metres and press Enter. Width, depth, area and the room name are also available in the Room and lights panel. For a stepped or angled room the width and depth describe the bounding box; use the wall labels and the outline points for the real geometry.

Editing a room

Choose Edit outline in the Room and lights panel or on the room chip at the bottom of the plan. Corner handles and wall labels appear. Drag a corner, drag a wall to move it, or double-click a wall to add a corner. Press Escape or choose Done to leave the edit session. Imported outlines with angled edges are read-only.

The whole room can be moved from Select mode. Moving or resizing a room keeps its luminaires inside the room, clamps them to the new work plane and never lets rooms overlap.

Deleting a room

The delete button is disabled when the floor has only one room. With more than one room it asks first, names the room, reports how many luminaires will go with it and reminds you that the study recalculates. Cancel or Escape leaves everything untouched, and Undo restores the room together with its luminaires. On the plan, pressing Delete or Backspace with no light selected opens the same confirmation for the active room.

Undo

The tool rail's Undo and Redo, and Cmd/Ctrl+Z, Shift+Cmd/Ctrl+Z and Ctrl+Y, cover the whole project: moving, aiming, renaming, adding, duplicating or deleting a light; drawing, resizing, moving, duplicating, renaming or deleting a room; the work plane, target, surfaces, bounces, maintenance and isolines; the project name; and an assistant edit batch. A pointer drag, a slider or a typing burst counts as one step, and the tooltip names the step ("Undo Move 2 lights"). The history holds the last 50 edits in memory and is cleared when you open, create, duplicate or import a project; it is not restored after a reload. The assistant also has its own one-step Undo in its transcript.

Luminaires and IES files

Choosing a profile

Choose Add in the Luminaires section to open the picker. Search by name, family or file, then pick a profile from your library or from a supplier catalogue. Library rows are already imported; catalogue rows are imported the first time you use them. The picker shows each profile's form, lumen output and photometric type.

OrbitX is the first catalogue brand, with 97 Type C profiles across 20 families. The catalogue travels with the app and is cached for offline use after the first load. Exact product meshes are still pending; the 3D preview uses dimensionally accurate family geometry.

Importing an IES file

Open the IES library from the header or the picker, then drop a .ies file on the drop zone or click to browse. LuxLab reads LM-63 Type C, TILT=NONE files, shows a polar preview and keeps the file in this browser. Type A and Type B files are listed but cannot be simulated, and the app says so before you rely on them.

Everything in the library is available to every project in this browser. Exported project bundles include the IES text they need.

Placing, aiming and editing

• Double-click the plan in Select mode to place a light where you clicked.
• Add in the Luminaires section places the active profile at the room centre.
• Select a light on the plan or in the list to open its inspector: name, profile, position, mounting height, aim, tilt and dimming.
• Arrow keys move the selected light by 0.1 m; Shift+Arrow moves it by 0.5 m.
• Use Select mode in the luminaire list to show a checkmark on every row, then select several lights. Drag any selected light on the plan to move the group. Delete or the Delete key opens one confirmation for the whole set.

The plan clamps positions to the room outline and to the room height. It does not model furniture, openings, blinds or object shadows, so a light position is a design decision, not a photometric guarantee.

Missing profiles

A light whose IES profile is missing from this browser is kept in the project but cannot be calculated. The Results panel reports how many lights are affected. Re-import the profile, or replace it in the light's inspector, then recalculate.

Calculate and read results

Calculations run in a Web Worker after each change. The status bar and the Calculation section show whether the result is ready, queued or failed. You do not need to press a button for a normal edit; Recalculate forces a run and is useful after an unusual state.

The calculation uses:

• the room polygon and ceiling height;
• the work plane height, default 0.75 m;
• the grid resolution (the standard 64 x N grid, or another preset);
• the IES photometry of every placed light, its position, mounting height, aim, tilt and dimming;
• direct illuminance plus up to four diffuse interreflection bounces;
• the maintenance method and factor;
• the surface reflectances.

Walls block light where the outline is not convex. Reflected light is diffuse; there is no specular reflection, furniture or daylight. Type C photometry only.

Heatmap modes

Total shows the maintained work-plane illuminance. Direct shows the direct component. Reflected shows the diffuse interreflection component. The heatmap keeps the same inferno scale in both themes. The scale at the bottom of the Results panel gives the minimum and maximum of the active mode.

While a new calculation is running, the previous result stays on screen so you can compare. LuxLab marks it as updating; do not treat those numbers as the current geometry.

Lux isolines

Each isoline has a level in lux and an on/off checkbox. The line is drawn where the work plane crosses that level. A level outside the calculated range has no crossing and is dimmed. The isolines belong to the project and travel with an exported bundle.

Target compliance

When a target illuminance is set, the Results panel reports the fraction of work-plane points at or above the target. Compliance is a property of the sampled grid, not of every possible point. Turn the target off if you do not want the comparison.

Grid resolution

The standard grid is 64 cells on the longer axis. A finer grid gives a smoother heatmap and more sample points but costs more time and memory. The panel shows the resulting point count and the approximate cell size. For a first pass use the standard grid; refine only when you need the detail.

Metrics and glossary

The 5 x 5 sample and the minimum and maximum positions in the assistant's project snapshot are coarse nearest-cell readings. They show where light is high or low; they are not exact values at arbitrary points.

Reports, export and storage

The PDF report

When a calculation is ready, the report button becomes available. The A4 report contains the 2D plan of every room, a 3D view of the active room, the settings and results, the fixture and luminaire schedules and the engine's limitations. It is generated in this browser; nothing is uploaded.

If the button is disabled, the calculation is not ready, there is no floor result, or the current result is being replaced. Wait for the status bar to say Ready, then try again.

Export and import

Export writes a self-contained .luxlab.json bundle: geometry, environment, luminaires, embedded IES text and the app's schema version. Import reads the same format and adds the project to this browser. A bundle keeps its geometry and numbers, but not the browser's theme or panel widths.

Storage

Projects and IES files are stored in IndexedDB for the signed-in account in this browser. Clearing site data, using a private window or choosing Clear local data in the account menu removes them. The save state in the header reports Saving, Saved locally or Session only. Session only means IndexedDB is unavailable and the project will disappear when the tab closes; export it.

Ask LuxLab

The Ask bar has two jobs.

New study turns a sentence into a modelled, calculated project. For example: "24 x 18 m open-plan office, 500 lx, 4 m ceiling." The server-side assistant reads the brief, picks a supported fixture, sizes the layout and the local engine calculates it. If you give a count, the assistant uses it; if you give a target, the solver finds the smallest count that meets it.

This project reads a bounded snapshot of the open project: rooms, light positions, fixture names, environment and the latest calculated metrics and sample. It can explain the result, answer what-if questions and, when you explicitly ask, return a small typed edit batch. The browser validates and applies the batch, recalculates and offers one-step Undo. It cannot create a new project from this mode; use New study for that.

Privacy: prompts go to the provider the administrator configured. In This project mode the project summary also goes to that provider. IES text and the full project stay in the browser. The transcript footer repeats the disclosure. Turn the assistant off in Settings if you do not want the bar at all.

Limits: six prompts per ten minutes, 40 per day per account and 80 per day shared. The limits protect the shared provider budget. The provider, model and key are administrator-owned; there is no per-user key.

The assistant never calculates a lux value. It reads the engine's numbers and, after an edit, LuxLab recalculates and shows the before and after. If a name is ambiguous, it should ask rather than guess.

Accounts and administration

Accounts have one of two roles: user or admin. The first admin is created on the server with the documented admin command. Admins see the dashboard at /tool/admin: users, sessions, usage, sign-up mode and the AI provider settings. The provider key is encrypted at rest or read from the server environment; it never reaches the browser.

The tool is gated: /tool/ requires a session. /login/, /signup/ and this handbook are public. If you are signed out you are redirected to /login/.

Change your password from the account menu. If an administrator created the account with a temporary password, LuxLab requires a change before the workspace opens. Signing out clears the local session and returns you to the sign-in page.

Method and limits

LuxLab computes direct illuminance from the IES intensity distribution and adds diffuse interreflection using a radiosity-style room-surface solution. Up to four bounces are available. The engine is deterministic and runs on the CPU in a Web Worker.

It does not model:

• furniture, partitions, objects, people or plants;
• windows, doors, blinds, daylight or views;
• specular or glossy reflections;
• non-diffuse surface finishes and measured BSDFs;
• emergency, circadian, glare (UGR) or colour metrics;
• control systems, occupancy or daylight dimming;
• outdoor or street lighting.

It supports LM-63 Type C, TILT=NONE photometry. Type A and Type B files are listed but cannot be simulated. A failed or unsupported profile is reported rather than silently replaced.

The results are only as good as the room geometry, work plane, maintenance factor and photometry you give it. The report records the inputs it used. Do not submit it as a compliance certificate; check the applicable standard and your assumptions independently.

Troubleshooting

The report button is disabled. Wait for the calculation to finish. It is also disabled if there is no floor result or the current result is being replaced. The status bar and Calculation section show the state.

A light says its IES profile is missing. Re-import the file in the IES library, or select another profile in the light's inspector. A project bundle includes the IES text, so importing the bundle usually restores it.

The calculation failed. Read the message in the Results panel and the status bar. Common causes are an unsupported photometric type, a malformed IES file, or a room with no valid grid. Fix the input and recalculate; the previous result stays visible until a new one succeeds.

Rooms overlap and will not move. LuxLab keeps rooms from overlapping. Move the other room first or leave a shared wall. The message names the conflict where it can.

Edit outline is disabled. Imported outlines with angled edges can be moved but not reshaped. Draw a new outline or use the imported room as a reference.

The workspace will not open offline. A cold start needs a connection to check the session. If the app is already open, it keeps working; saved projects stay in this browser. See the note in Start here.

Panels are missing on a phone. The Room and lights and Results panels are drawers below 1024 and 1280 px. Use the two icons at the top-right of the canvas, or the status bar, to open them.

The saved state says Session only. IndexedDB is unavailable, often because of a private window or a storage restriction. Export the project before closing the tab.

I cannot install the PWA. Installation needs a secure context (HTTPS) and a browser that supports it. The LAN HTTP address is intentionally not registered as a service worker. Use the public HTTPS address.

Keyboard shortcuts

On the plan, the selected light, corners and wall labels are focusable. Use Tab to reach them and the arrow keys to move a selected light. The status bar reports the current tool.

Releases

LuxLab is versioned and released from the repository. The landing page carries the current release notes and the GitHub releases page has the full history. This handbook is updated with each user-visible release; if a screenshot or a shortcut looks out of date, compare the version in the footer with the release notes.

The current release is stamped in the footer of this page. See the landing changelog at /#changelog and the repository releases.