CircadianLab — AI & Developer Guide

Build, score, optimize, and view lighting designs by describing them. For AIs (Claude / ChatGPT / agents) and developers.

Base URL https://www.innerscene.com · JSON version of this doc: /api/eml-calc/ai/spec

Start here — using this with your AI (for people)

This page is written for AI assistants, so you don’t have to read it. Open Claude or ChatGPT, paste one of the prompts below, and edit the [bracketed] parts. The assistant reads this guide and does the rest.

A. Describe your space in words

CopyRead the CircadianLab AI guide at https://www.innerscene.com/api/eml-calc/ai/guide and use it to help me design lighting. My space: [a 24 x 18 ft open office, 9 ft ceiling, four workstations]. Goals: [at least 30 footcandles on the desks, 250 mel-EDI facing each desk for circadian benefit, and glare under UGR 25]. Recommend a Circadian Sky layout and give me a link I can open to view it.

B. From an annotated drawing — attach a floor plan or reflected ceiling plan (image or PDF) with dimensions and fixtures. Use a vision-capable model: Claude Opus 4.8 (or Sonnet 4.6), or ChatGPT (GPT-4o or later).

CopyRead the CircadianLab AI guide at https://www.innerscene.com/api/eml-calc/ai/guide. I’m attaching a drawing of my space — a [reflected ceiling plan] with dimensions and a fixture schedule. Read it to work out the room size and ceiling height, the fixture types, and where each one goes; anchor the scale on a known dimension or fixture size. Then build a matching CircadianLab model: use the Circadian Sky presets for any circadian fixtures. For the other fixtures in the schedule — downlights, linear strip or cove lights, troffers — use the fixture-library search (filter by wattage, CCT, and type, e.g. type=Downlight or type=Linear) to find a real product that matches the spec, fetch its IES with /fixtures/lookup, and add it as a customFixture so illuminance and glare are accurate. Give me a link to view it, and list the fixtures you picked and any assumptions you made. Goals for the space: [30 fc on the work areas, 250 mel-EDI for occupants, glare under UGR 25].

What you get back: an agent that can browse or call APIs (e.g. Claude Code) returns a link you open directly. A chat-only assistant returns a small block of room JSON — open the Import window in CircadianLab, paste it, and click Open (or use the standalone Import page). The most you ever do is paste text and click a link — no terminal, code, or installs.

In action — an agent session

A real exchange in an agentic assistant (e.g. Claude Code). The assistant makes the HTTP calls itself; the user just talks.

User

I've got a 24×18 ft open office with 4 workstations. I need at least 30 fc on the desks, 250 mel-EDI facing each desk, and glare under UGR 25. What Circadian Sky layout works?

Assistant

I'll optimize a Circadian Sky layout against those three targets.

POST /api/eml-calc/ai/optimize { "units":"ft", "room":{"width":24,"depth":18,"height":9}, "furniture":[{"x":6,"y":5,"width":4,"depth":2},{"x":18,"y":5,"width":4,"depth":2}, {"x":6,"y":13,"width":4,"depth":2},{"x":18,"y":13,"width":4,"depth":2}], "occupants":[{"x":6,"y":5},{"x":18,"y":5},{"x":6,"y":13},{"x":18,"y":13}], "targets":{"deskFc":30,"melEDI":250,"ugr":25}, "optimize":{"fixture":"CS24"}, "view":{"mode":"2d","metric":"illuminance","units":"imperial"} } ← 200 { ok:true, design:{preset:"CS24",count:4,cct:40000,dim:1,watts:300}, score:{ pass:true, occupants:[…] }, url:"…/tools/circadian-lab?share=abc" }

Done. 4× Circadian Sky 2×4 at their 40000 K daytime peak (~300 W total) meet all three targets at every workstation — desk ≥30 fc, mel-EDI ≥250 facing, UGR <25. That is the daytime setting; each fixture then ramps itself to warm, dim light in the evening, so no separate night layout is needed. The optimizer raised CCT to 40000 K first (each fixture delivers roughly twice the mel-EDI it would at a neutral white), so 4 panels suffice where ~7 neutral-white (5000 K) ones would be needed. Open it: the model →. Want a rendered preview, or a warmer CCT with more fixtures?

User

show me the footcandle coverage on the floor

Assistant

GET /api/eml-calc/ai/render?share=abc&w=1200&h=850 // share view: 2D, illuminance, iso-lines on ← 200 image/png

Here's the horizontal footcandle plan with iso-lines. Each panel sits directly over a workstation, so all four desks read ~43 fc — comfortably above the 30 fc target (the green marker on the scale below is the 30 fc office line). Want the mel-EDI view instead, or a warmer 5000 K look?

The figures in this exchange (~43 fc, the pass/fail marks) are illustrative, not a computed result for any specific room — reproduce them only by calling /score or /optimize, or by letting the browser compute after the user opens the link. Below: the full reference behind those calls — schema, presets, the fixture library, endpoints, and more examples.

1. When to use it

The user describes a space and lighting goals in words or from a drawing — e.g. “a 20×10 ft room with 3 Circadian Sky 2×4s” or “an office that hits 30 fc on desks, 250 mel-EDI at each workstation, glare under 25 UGR.” You turn that into a room, validate or optimize it, and return a link they can open.

createscore / validateoptimize to targetsview (share link + PNG)

2. Coordinates & units

Origin is the south-west floor corner. X = east (width), Y = north (depth), Z = up (height). Set "units":"ft" (default) or "m"; it applies to every length and to fixture / occupant x/y/z.

3. The room schema circadian-lab/room@1

One JSON object. Top-level fields:

room

Non-rectangular rooms: the engine is rectangular, so a polygon (or walls) is modeled as the bounding-box room with each edge as an interior wall that blocks + reflects light — carving out L-shapes, alcoves, etc. Coordinates can use any origin (everything is shifted to the box corner), and if you omit width/depth they’re taken from the polygon’s extent. Place fixtures/occupants explicitly for shaped rooms (auto-grid fills the whole box, including any notch).

fixtures[] — explicit placement

Or pass fixtures as a single object { "preset":"CS24", "count":6, "cct":5000, "dim":1 } to auto-place an even ceiling grid of N (add tilt/aimAzimuth/rotation to aim the whole grid).

Don't overlap footprints. Each ceiling fixture is recessed and cuts a hole its full size (the Size m (w×d) in §4 — e.g. CS24 = 0.63 × 1.24 m). When you place fixtures explicitly, keep centers at least one footprint apart — a full width in x and a full depth in y (accounting for rotation) — so the cut-outs don't collide. Overlapping troffers can't be installed and render as one oversized dark hole; /score and /import return an overlap warning naming the offending pairs, so read the warnings and nudge fixtures apart if any appear.

Aiming a fixture: leave tilt off for a normal downlight. To graze a wall, set tilt (e.g. 30–60) and aimAzimuth toward that wall. Note a fixture at the default ceiling height is treated as flush-recessed, so its upward light is clipped by the ceiling — that's fine for washing down a wall; to throw light up onto the upper wall, drop z a little (e.g. z = ceiling − 0.3 m) so it hangs below the ceiling like an adjustable/pendant. Counter-intuitively, aiming light sideways often raises UGR (more luminance in the viewing zone, dimmer overall room), so verify with /score rather than assuming it lowers glare.

Wall-mounted fixtures — Circadian Sky as a window

Give a fixture a wall instead of x/y and it mounts flush on that wall, emitting horizontally into the room. In this form a Circadian Sky panel reads as a backlit sky window — most often a standing-height window (center ≈ 1.4 m / 4.5 ft) or a clerestory band set high on the wall.

⚠ Watch UGR with wall windows. A wall panel sits in the occupants' field of view, so it delivers strong vertical mel-EDI (excellent circadian dose) but can drive glare (UGR) high — a bright standing-height window directly in front of someone can read UGR > 30 (intolerable). Mitigate by mounting it high (clerestory) rather than at eye level, placing it on a wall occupants don't face head-on, dimming it, and always checking UGR with /score. Never assume a window is comfortable — verify.

Lay-in (drywall deep regress) — Circadian Sky recessed into a coffer

Give a Circadian Sky fixture a regress depth and it becomes a lay-in install: the panel lays into a drywall coffer from above (like a ceiling tile), so its luminous window sits regress above the finished ceiling and the room sees it through an opening — reading as a true architectural skylight rather than a flush troffer. The engine models the coffer with real geometry (a ceiling aperture plus white bounce walls), so the physics is faithful: the coffer walls progressively cut off high-angle light, and what they catch bounces back out of the cavity via radiosity.

Photometric consequences — always verify with /score. The coffer vignettes high-angle light (full output at nadir, tapering to a hard cutoff at ≈ atan(window ÷ regress) off vertical). That trades the two circadian metrics against each other: UGR drops for oblique observers (the window disappears from view at shallow angles — often the point of a lay-in), but vertical eye-level mel-EDI also drops versus the same panel flush-mounted, because near-horizontal light is exactly what reaches a standing occupant's eyes. Directly under the fixture, illuminance is nearly unchanged. Rules of thumb: a 4″ regress is mild; 8–12″ is a strong architectural effect with a real dose penalty — compensate with output, count, or CCT and re-score.

Placement rules. Butt lay-ins exactly (use count, or place centers one footprint apart — within 1/8″ reads as continuous, so no coffer wall is built between them) or keep them clearly separate; anything in between builds an unbuildably thin drywall strip between the slots. The overlap warning from /score / /import applies to lay-ins too. Lay-in adds real surfaces to the scene, so calcs run somewhat slower than flush fixtures — normal.

Cove / uplight — indirect ceiling wash

Give a fixture a cove (a wall name) instead of x/y and it becomes a linear LED strip run along that wall, near the ceiling, aimed up. The engine bounces the light off the ceiling (radiosity), so the whole ceiling glows as a soft, low-glare "sky." This is true indirect / cove lighting, the most comfortable way to deliver circadian light to someone lying down and looking up (a patient), because there is no bright source anywhere in the upward view. The bright ceiling is counted as a glare source, so the reported UGR is real (low, not zero). Note a cove is a genuine LED strip, which tops out near 6500 K — so a cove alone delivers only a modest dose (~117 mel-EDI for a two-wall 400 lm/ft cove). To reach a 250 circadian target, pair the cove with a dimmed Circadian Sky panel (the hybrid in the hint below); do not fake a high-CCT "circadian sky strip," no such product exists.

A cove expands into a line of upward-aimed point sources carrying a real linear-strip IES. Because it is priced per foot (a strip), not per panel, it is a different cost basis from the Circadian Sky panels. Put a cove on two opposite walls for an even ceiling wash.

Design hints for someone lying down (patient rooms), some counter-intuitive. A supine occupant looks straight up, so any bright fixture overhead sits dead-center in their gaze — the worst place. These were verified in CircadianLab; always confirm with /score in the direction:"horizontal" (looking-up) view.

• Position beats brightness. An overhead panel that meets the dose still reads UGR 30+ (intolerable) looking up; move the bright surface out of the upward gaze — a cove, or a panel on the headwall (behind the head) or footwall (at the foot of the bed) — and the same dose drops to UGR 8–18.
• Strips can't carry the circadian dose alone. A real cove tops out near 6500 K and reaches only ~117 mel-EDI; the best patient design is a hybrid: a real-strip cove (soft sky, near-zero glare) plus a heavily-dimmed Circadian Sky panel that tops the dose to 250 — ~254 mel-EDI at UGR ~8, the most comfortable option that meets target.
• Counter-intuitive: mount the added panel LOW, not high. At a fixed dose, a panel close to the head (behind the headboard, ~4.5 ft, dimmed to ~14%) reads lower glare than the same panel high/clerestory, because glare scales with luminance² — a close panel meets the dose while barely on, a far one must run brighter. Don't reflexively mount high.
• Cove geometry: lowering the cove (larger coveDepth) cuts glare with roughly flat output; a wider shelf does not help (optimum ~0.15 m); keep the lip just tall enough to hide the strip — taller only steals output.
• Footwall vs headwall: a panel at the foot of the bed sits in the patient's forward gaze (like a wall TV) and is the lowest-glare spot, but that wall usually holds the door — so a low, dimmed headwall panel is the practical pick.

occupants[]

Bed position changes everything. Evaluate a patient at recline 0, 45 and 90. Two things move with the bed: glare (an overhead source is worst flat and vanishes as they sit up) and circadian dose (highest lying flat facing the source, and it falls as they sit up and face away — most designs drop well under 250 mel-EDI sitting upright). Report the worst case across all three.

Daylight — real windows, skylights, sun & sky

Add windows (apertures) plus a daylight scene (a place, date and time) and the engine solves real daylight in the same radiosity pass as the electric fixtures: direct sun, diffuse sky, and inter-reflection are added to every workplane point. Daylight is spectrally rich, so it contributes strongly to mel-EDI (treated as ≈ 6500 K) — by day, windows can carry much of the circadian dose. Daylight only enters through apertures, so a daylight scene does nothing without at least one window or skylight.

windows[] — windows & skylights

daylight — the sun & sky scene

Evaluating different times of day and year: keep the room and windows fixed and re-score with different daylight.date / daylight.time. Since /score is GET-able, fire one call per time — e.g. a matrix of 9:00 / 12:00 / 15:00 × Jun 21 / Dec 21, plus an overcast case, to see the full swing. Report the daylight-inclusive fc / mel-EDI / UGR at each, and note where electric light must fill in (early/late, overcast, deep-plan points far from glazing).

Orientation matters a lot. A south window takes strong direct sun — and the low winter sun drives far more vertical light (and glare) deep into the room than the high summer sun; north gives steady soft diffuse light; east/west spike at sunrise/sunset; a skylight gives even overhead daylight with the least glare. Direct-sun cases can read tens of thousands of lux / mel-EDI right at the glazing — great circadian dose, but check UGR and consider shading.

targets, optimize, view

4. Fixture presets

Circadian Sky presets are CCT-tunable; higher CCT delivers more mel-EDI per fixture (melanopic ratio rises with CCT, peaking near 40000 K = the default), so raising CCT is the cheapest way to hit a circadian target before adding hardware. LED / fluorescent presets are fixed at 3500 K.

Circadian Sky — detailed reference

Five sizes, all in the same recessed troffer housing: 89 mm (3.5″) deep, tuning 2200–200000 K (default 40000 K). Pick the size that fits the ceiling grid and the lumen budget; use CCT to dial circadian dose.

All CS sizes are 89 mm (3.5″) deep. Emission = the lit aperture (drives glare + soft-shadow behavior); housing = the cut-out footprint.

Melanopic ratio & light output vs CCT

The Circadian Sky spectrum shifts with CCT, so two things change at once (measured values, from the ATMOS 4-chip SPD):

• Melanopic ratio (M/P) — mel-EDI per photopic lux. Rises monotonically with CCT.
• Relative light output — the fixture emits more/fewer lux at different CCTs, peaking ~4600 K (1.0× = the 6500 K spec-sheet lumens above).
• Relative mel-EDI per fixture = ratio × output (÷ the 4000 K value). This is what matters for a circadian target — it peaks near 40000 K, then dips at 200000 K as output falls faster than the ratio climbs.
• Colour rendering (Ra, R9) — CIE 13.3-1995 general CRI and deep-red R9 (published datasheet). Peaks ~5000 K (Ra 97.5 / R9 98) and stays high through ~15000 K. At the coolest, blue-sky-like settings (above ~20000 K) CRI is no longer defined (shown n/a) — the spectrum sits far enough off the white locus that the metric doesn't score it, as it wouldn't for a clear blue sky — so 40000 K and 200000 K carry no colour-rendering figure.

How to use this — circadian dose vs colour: to hit a mel-EDI target with the fewest fixtures, push CCT toward 40000 K (≈1.9× the mel-EDI of the same fixture at 4000 K); to maximize desk footcandles, stay near 4600–5000 K where light output peaks. /optimize applies that ordering (raise CCT before adding hardware), and the 40000 K default — a cool, blue-sky-like white — is a good daytime choice for offices, circulation, and wellness spaces valued for circadian dose and a daylight feel. Where accurate colour judgement matters, prefer a warmer setting — but only for colour judged under the room's own light: medical exam & dermatology (skin/tissue), retail, print / paint / art, food, and the macroscopic bench reads in a lab (colony colour & morphology, haemolysis on blood agar, chromogenic media, reagent/indicator colour). Keep CRI high there — ~5000 K peaks (Ra 97.5 / R9 98), ≤6500 K stays strong; set optimize.cctLadder to end there or fix cct. A task with its own dedicated light source is not governed by the ceiling — a microscope's illuminator (stained slides), a colour-viewing booth, or a task lamp set the colour there, so those don't require capping the overhead CCT. So in a microbiology lab the overhead serves the people and the by-eye bench reads (cap it warm), while slide microscopy rides the scope's own light. The Circadian Sky still delivers a solid circadian dose at 5000 K, so capping costs only modest mel-EDI. Mention the CCT you chose, and why, when you report a colour-critical room.

Dimming

Dimming is constant-CCT and linear: the melanopic ratio does not change with the dim level, and both mel-EDI and illuminance scale directly with it. So a CS24 at 40000 K and dim: 0.5 delivers half the mel-EDI and half the lux of the same fixture at dim: 1.0 — the M/P ratio stays 1.39 either way.

Automated daily circadian schedule

Circadian Sky is not a fixed-CCT luminaire you set once. Every fixture runs a built-in automated 24-hour program: through the day it drives high CCT and high melanopic output (a bright blue-white sky) to support daytime alertness and circadian entrainment, and in the evening and night it automatically lowers CCT and dims to a warm, low-melanopic scene that protects melatonin onset and sleep. This modulation is part of the product; it needs no external controls, astronomical clock, or extra wiring.

What this means when you design: CircadianLab models one static instant, so you design for the daytime peak, which is the hardest case for a mel-EDI target. A layout that reaches 250 mel-EDI at 40000 K represents that daytime high point. The same fixtures deliver a warm, dim, low-mel-EDI scene automatically after hours, so you do not need a second night-time model or a warmer alternate layout to be circadian-friendly in the evening. When you present a recommendation, state that the CCT and output are the daytime setting and note that the fixtures ramp themselves down in the evening. Do not suggest the user must hold a high CCT all day, or that a warmer look requires more hardware; warmth arrives on its own at night.

5. Fixture library & custom fixtures

Beyond the presets above, CircadianLab ships a large third-party IES library you can search and pull real photometry from — use it whenever a design specifies a particular downlight, linear, troffer, etc. (a real IES gives trustworthy illuminance and glare; a placeholder does not).

Searching the library — GET /api/eml-calc/fixtures/search

Two modes:

• Text: ?q=… — multi-term match on name / manufacturer / brand / catalog / type. Returns one result per product family.
• Structured: any numeric or type filter switches to variant-level filtering and returns the best-matching variant per family — each with a variantId (feed to /lookup) and its exact watts / cct / lumens. Use this to resolve e.g. “10W linear 4000K” deterministically; plain text can’t (watts isn’t a text field, so q=10W finds nothing).

Structured results: [{ variantId, name, manufacturer, type, watts, cct, lumens, beamAngle, url }], ranked by closeness to the requested watts/CCT.

What's in the library

243,546 product families across 177 manufacturers (433,003 IES variants). By form-factor:

— 10W linear @ 4000K, general-bright (a "C1" downlight-strip spec)
GET /fixtures/search?type=Linear&wattsMin=8&wattsMax=12
    &cct=4000&lumensMin=1000

— 2×4 troffers near 3500K, 3000+ lm
GET /fixtures/search?type=Troffer&cct=3500&lumensMin=3000

— narrow-beam accent downlights, ≤15W
GET /fixtures/search?type=Downlight&wattsMax=15&beamMax=40

— 3500K spot downlights, best 2 per manufacturer
GET /fixtures/search?type=Downlight&cct=3500&beamMax=30
    &perManufacturer=2

— free-text by brand / product line
GET /fixtures/search?q=lithonia+wall+wash

— then fetch the IES for a chosen result
GET /fixtures/lookup?id=<variantId>
    → { fixture:{watts,cct,lumens,…}, iesContent }

Using a found (or uploaded) fixture — customFixtures

Drop the fetched IES into a customFixtures entry, or upload a file with POST /api/eml-calc/ies/upload and reference the returned iesHash. IES files carry no CCT, so you must supply cct plus sourceType (standard_led | fluorescent | circadian_sky) or a measured customDER — otherwise the mel-EDI will be wrong.

"customFixtures": [
  { "iesContent": "<from /lookup>", "cct": 4000, "sourceType": "standard_led", "x": 4, "y": 5 }
]

6. Endpoints & workflow

MCP server: native tools instead of raw HTTP

If your client speaks the Model Context Protocol (Claude Code, Claude Desktop, Cursor, and other MCP-capable agents), you can skip hand-building HTTP calls entirely. The @innerscene/circadian-lab-mcp server wraps this exact API as typed, validated tools: same engine, same share links.

# Claude Code
claude mcp add circadian-lab -- npx -y @innerscene/circadian-lab-mcp

# Claude Desktop and other MCP clients (claude_desktop_config.json)
{ "mcpServers": { "circadian-lab": {
    "command": "npx", "args": ["-y", "@innerscene/circadian-lab-mcp"] } } }

Tools: score_room, optimize_room, create_design, render_scene (returns the scene PNG as an image the assistant can actually see), search_fixtures, lookup_fixture, get_design_reference; plus this spec and the presets as MCP resources, and two starter prompts. One extra convenience over raw HTTP: inside customFixtures you can reference a library fixture as {"iesId": "<variantId from search_fixtures>"} and the server fetches and injects the IES text for you, so the assistant never carries raw photometry. Requires Node 18+. Set CIRCADIAN_LAB_BASE_URL to point it at a different host.

GET-only: links & compute (no POST needed)

Many chat assistants can follow or fetch a URL (GET) but cannot POST. Every write in this API is reachable over GET too, so a POST is never required.

1 · A one-click link that opens the design

GET /api/eml-calc/ai/import takes the room in the query string and 302-redirects to the finished share. You do not have to call it yourself — just give the user the link. Their browser runs the GET when they click and lands on the model. Two encodings:

ChatGPT / Python — build either link:
  import json, gzip, base64, urllib.parse
  room = { "schema":"circadian-lab/room@1", "units":"ft", "room":{"width":24,"depth":18,"height":9},
           "fixtures":[{"preset":"CS24","count":6,"cct":40000}], "occupants":[...], "targets":{...} }
  raw  = json.dumps(room, separators=(",",":")).encode()
  # PREFERRED — robust + inspectable, use whenever it fits (up to ~8 KB):
  link = "https://www.innerscene.com/api/eml-calc/ai/import?room=" + urllib.parse.quote(json.dumps(room))
  # compact FALLBACK for very large rooms only — opaque; reproduce byte-exact or it won't decompress:
  link = "https://www.innerscene.com/api/eml-calc/ai/import?room64=" + base64.urlsafe_b64encode(gzip.compress(raw)).decode().rstrip("=")

The same works from any language: percent-encode the JSON for room, or gzip → base64url for room64.

⚠ If a link doesn't open: a long room64 blob is easily corrupted when a chat UI wraps the URL or the user re-copies it — a single changed character means it can't be decompressed, and the page shows an import error. Don't try to repair the blob. Regenerate the link as plain ?room= if it fits, or simply give the user the room JSON in a code block to paste into the Import window — that path can't be broken by URL handling.

2 · Compute real numbers over GET

The identical ?room= / ?room64= query also drives /score and /optimize, which return JSON. If you can make GET requests, call these to report computed results (real fc / mel-EDI / UGR and a share url) instead of estimates — never quote numbers you didn't compute.

• GET /api/eml-calc/ai/optimize?room64=… → runs the solver, returns { ok, design, score, trace, url }.
• GET /api/eml-calc/ai/score?room64=… → returns room stats + per-occupant fc / mel-EDI / UGR + pass/fail.
• GET /api/eml-calc/ai/render?room64=… (or ?share=<id>) → a PNG of the scene you can show the user. Add &metric=… via the room's view (e.g. footcandle plan vs mel-EDI). Renders are queued server-side; on a 429, wait a moment and retry.
• GET /api/eml-calc/fixtures/search?… → already GET; find real fixtures and their IES (see §5).

3 · Rooms too big for a URL — paste JSON or a ZIP

A safe URL is about 2,000 characters; ~8,000 is the practical server ceiling. Preset rooms fit with room to spare (a six-panel office is ~420 chars as room64). What does not fit is customFixtures with embedded IES text (tens of KB each). For those, don't force it into a link — hand the user files for the Import window:

• Paste + drop: the room JSON (with customFixtures, each naming its file via iesFile) plus the .ies/.ldt files dropped alongside — the Import window embeds them by filename.
• ZIP bundle: one .zip containing the room .json and the referenced .ies files. The Import window unpacks it and wires each iesFile to its fixture. (CircadianLab's own Export → Scene bundle writes this same layout, so an exported bundle re-imports cleanly.)

Rule of thumb: preset-only design → a GET link; custom photometry → paste JSON or a ZIP.

7. Metric reference

8. Examples

{
  "schema": "circadian-lab/room@1",
  "units": "ft",
  "room": {
    "width": 20,
    "depth": 10,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS24",
      "count": 3
    }
  ],
  "occupants": [
    {
      "x": 10,
      "y": 5,
      "facing": "north",
      "posture": "standing"
    }
  ]
}

{
  "units": "ft",
  "room": {
    "width": 20,
    "depth": 12,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS24",
      "count": 6
    }
  ],
  "occupants": [
    {
      "x": 6,
      "y": 4,
      "facing": "north",
      "posture": "sitting"
    },
    {
      "x": 14,
      "y": 8,
      "facing": "north",
      "posture": "sitting"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 25
  }
}

{
  "units": "ft",
  "room": {
    "width": 24,
    "depth": 18,
    "height": 9
  },
  "occupants": [
    {
      "x": 6,
      "y": 5
    },
    {
      "x": 18,
      "y": 5
    },
    {
      "x": 6,
      "y": 13
    },
    {
      "x": 18,
      "y": 13
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 25
  },
  "optimize": {
    "fixture": "CS24"
  }
}

{
  "units": "ft",
  "room": {
    "width": 12,
    "depth": 10,
    "height": 9
  },
  "customFixtures": [
    {
      "iesContent": "<paste raw IES text here>",
      "cct": 4000,
      "sourceType": "standard_led",
      "x": 4,
      "y": 5
    },
    {
      "iesContent": "<same>",
      "cct": 4000,
      "sourceType": "standard_led",
      "x": 8,
      "y": 5
    }
  ],
  "occupants": [
    {
      "x": 6,
      "y": 5,
      "facing": "north"
    }
  ]
}

{
  "units": "ft",
  "room": {
    "width": 24,
    "depth": 12,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS22",
      "count": 8
    }
  ],
  "partitions": [
    {
      "x1": 12,
      "y1": 0,
      "x2": 12,
      "y2": 8,
      "height": 6
    }
  ],
  "furniture": [
    {
      "x": 6,
      "y": 3,
      "width": 4,
      "depth": 2
    },
    {
      "x": 18,
      "y": 3,
      "width": 4,
      "depth": 2
    }
  ],
  "occupants": [
    {
      "x": 6,
      "y": 4,
      "facing": "south",
      "posture": "sitting"
    },
    {
      "x": 18,
      "y": 4,
      "facing": "south",
      "posture": "sitting"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 22
  }
}

{
  "units": "ft",
  "room": {
    "width": 20,
    "depth": 10,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS24",
      "count": 3
    }
  ],
  "view": {
    "mode": "2d",
    "metric": "illuminance",
    "units": "imperial",
    "contours": true
  }
}

{
  "units": "ft",
  "room": {
    "height": 9,
    "polygon": [
      [
        0,
        0
      ],
      [
        30,
        0
      ],
      [
        30,
        20
      ],
      [
        10,
        20
      ],
      [
        10,
        10
      ],
      [
        0,
        10
      ]
    ]
  },
  "fixtures": [
    {
      "preset": "CS24",
      "count": 6
    }
  ],
  "occupants": [
    {
      "x": 5,
      "y": 5
    },
    {
      "x": 20,
      "y": 15
    }
  ]
}

{
  "units": "ft",
  "room": {
    "width": 20,
    "depth": 14,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS24",
      "count": 4
    },
    {
      "preset": "CS22",
      "x": 10,
      "y": 12.5,
      "tilt": 50,
      "aimAzimuth": 0
    },
    {
      "preset": "CS22",
      "x": 18.5,
      "y": 7,
      "tilt": 50,
      "aimAzimuth": 90
    }
  ],
  "occupants": [
    {
      "x": 10,
      "y": 6,
      "facing": "north"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 25
  }
}

{
  "units": "ft",
  "room": {
    "width": 24,
    "depth": 16,
    "height": 10
  },
  "fixtures": [
    {
      "preset": "CS24",
      "wall": "south",
      "count": 4,
      "heightFromCeiling": 1.5,
      "orientation": "landscape"
    }
  ],
  "occupants": [
    {
      "x": 12,
      "y": 9,
      "facing": "south"
    }
  ],
  "targets": {
    "deskFc": 20,
    "melEDI": 250,
    "ugr": 25
  }
}

{
  "units": "ft",
  "room": {
    "width": 24,
    "depth": 18,
    "height": 10
  },
  "fixtures": [
    {
      "preset": "CS24",
      "x": 8,
      "y": 8,
      "rotation": 90
    },
    {
      "preset": "CS24",
      "x": 12,
      "y": 8,
      "rotation": 90
    },
    {
      "preset": "CS24",
      "x": 16,
      "y": 8,
      "rotation": 90
    },
    {
      "preset": "CS24",
      "x": 8,
      "y": 10,
      "rotation": 90
    },
    {
      "preset": "CS24",
      "x": 12,
      "y": 10,
      "rotation": 90
    },
    {
      "preset": "CS24",
      "x": 16,
      "y": 10,
      "rotation": 90
    },
    {
      "preset": "CS22",
      "wall": "south",
      "count": 4,
      "heightFromCeiling": 1,
      "orientation": "landscape",
      "dim": 0.6
    }
  ],
  "occupants": [
    {
      "x": 8,
      "y": 12,
      "facing": "south",
      "posture": "sitting"
    },
    {
      "x": 16,
      "y": 12,
      "facing": "south",
      "posture": "sitting"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 25
  }
}

{
  "units": "ft",
  "room": {
    "width": 24,
    "depth": 16,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS12",
      "regress": 0.33,
      "count": 6,
      "axis": "x",
      "x": 12,
      "y": 8,
      "cct": 6500
    }
  ],
  "occupants": [
    {
      "x": 12,
      "y": 11,
      "facing": "north",
      "posture": "sitting"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 19
  }
}

{
  "units": "ft",
  "room": {
    "width": 20,
    "depth": 15,
    "height": 9
  },
  "fixtures": [
    {
      "preset": "CS24",
      "count": 4,
      "dim": 0.5
    }
  ],
  "windows": [
    {
      "wall": "south",
      "width": 10,
      "height": 5,
      "sill": 2.5,
      "glazing": "clear"
    }
  ],
  "daylight": {
    "lat": 40.7,
    "lon": -74,
    "tz": "America/New_York",
    "date": "2026-06-21",
    "time": "12:00",
    "sky": "clear",
    "orientation": 0
  },
  "occupants": [
    {
      "x": 10,
      "y": 6,
      "facing": "south",
      "posture": "sitting"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 25
  }
}

{
  "units": "ft",
  "room": {
    "width": 18,
    "depth": 18,
    "height": 11
  },
  "windows": [
    {
      "wall": "ceiling",
      "width": 6,
      "height": 6,
      "glazing": "double"
    }
  ],
  "daylight": {
    "lat": 34,
    "lon": -118.2,
    "tz": "America/Los_Angeles",
    "date": "2026-09-21",
    "time": "10:00",
    "sky": "clear"
  },
  "occupants": [
    {
      "x": 9,
      "y": 9,
      "facing": "north"
    }
  ],
  "targets": {
    "deskFc": 30,
    "melEDI": 250,
    "ugr": 25
  }
}

9. Limits & running locally

Server-compute caps apply only to /score and /optimize, which run the engine on a shared box: room ≤ 400 m², ≤ 500 fixtures, ≤ 50 occupants. Oversized or malformed input returns HTTP 400/413 with an error message — fix and resend. A warnings array in a success response is non-fatal (e.g. a CCT clamped to a preset’s range, or an unknown preset skipped).

No limits in the browser

CircadianLab’s photometric engine runs client-side, so those caps exist to protect the server — not the calculation. For a design bigger than the caps (a warehouse, hundreds of fixtures, a very fine grid, high bounce counts), /import still accepts it — up to generous storage ceilings (50,000 m², 2000 fixtures) — and returns a share url. When the user, or an agent driving a local / headless browser, opens that url, the full-resolution calculation runs on their machine with no limits. So: use /score and /optimize to validate or solve within the server envelope, and open the share to compute and view arbitrarily large scenes locally.

CircadianLab · Innerscene. Machine-readable spec: /api/eml-calc/ai/spec