# Fixture definitions
A fixture definition describes one kind of lamp: where its LEDs sit, in which
order they take their DMX channels, how each LED is drawn, and which modes
group them. Every fixture you patch is an instance of a definition, so a
definition is drawn once and patched as often as the lamp is installed.
Definitions are assets like palettes and scenes. Open them with
`Assets` → `Fixture Definitions`, or from the `Add Fixtures` menu in the patch
editor (`Edit fixture definitions…`).
A fresh installation has no definitions. Create one with `+` in
`Assets` → `Fixture Definitions`: the `+` beside a folder of the tree offers
`Fixture Definition`. Then draw its LEDs. Lamps in the old SVG format are
converted on start, see [Old lamps and projects](#old-lamps-and-projects).
## Drawing LEDs
The canvas shows the lamp at its real size; one grid square is a centimetre.
The wheel zooms, the middle mouse button pans and `Fit view` shows the whole
lamp. Every LED carries its number in DMX order.
The tools above the canvas lay out many LEDs at once. Their keys switch to
them: V for `Select`, L, C and P for the drawing tools.
* **Line**: drag from the first LED to the last. Shift keeps the line to 15°
steps.
* **Circle**: drag from the centre to where the first LED goes. The LEDs run
clockwise.
* **Path**: click the corners. Click the first corner again to close the loop,
or double-click (or press Enter) to end an open path. Tick `smooth` to run a
curve through the corners instead of straight lines, for a bent strip.
Set how many LEDs the shape carries in the `LEDs` field, or with + and −
(ten at a time with shift). Or type the strip's pitch into `mm apart` and the
count follows: a strip with 60 LEDs per metre has them 16.7 mm apart. The
preview follows while you draw and while you change the count. Enter in a
field only confirms the value. `free ends` keeps half a pitch
free at both ends instead of an LED on each end point, as on a bar whose LEDs
sit in the middle of their segments. `Add` (or Enter) adds the LEDs after the
existing ones and selects them; Escape drops the shape, a second Escape goes
back to `Select`.
`Add` → `Along an SVG path…` takes the longest path of an SVG file, at the
size the file gives it, as the shape to spread the LEDs along: draw the curve
in Inkscape, load it, set the count and add.
`Add` → `Line…`, `Grid…` and `Ring…` do the same with typed-in values, for
exact dimensions. Their form opens in the corner of the canvas, so the preview
stays in sight while the numbers change; Enter adds and Escape closes it. A
grid can snake back and forth, as LED matrices usually do. Double-click an
empty spot to add a single LED there.
## Editing
With `Select`, click an LED to select it, shift-click to add one, cmd-click to
toggle and alt-click to remove. Drag a band to select several. Dragging a
selected LED moves the selection, the arrow keys move it by a millimetre
(ten with shift). The handles of the box around a selection scale it, the
handle above the box turns it.
The context menu (right click) and the keyboard offer:
| Select all | Ctrl+A |
| Duplicate | Ctrl+D |
| Delete | Delete or Backspace |
| Reverse the DMX order of the selection | |
| Make the selection the first in DMX order | |
| Group / ungroup the selection in the current mode | Ctrl+G / Ctrl+Shift+G |
| Undo / redo | Ctrl+Z / Ctrl+Shift+Z or Ctrl+Y |
| Clear the selection | Escape |
| Save | Ctrl+S |
The inspector on the right sets name, position, rotation, model and channel
order of the selected LEDs. With several selected, a value they differ in
shows `-`; setting it sets it for all of them. Each LED can take its channels
in any order of red, green and blue (GRB for most WS2812 strips).
## Modes
A mode decides which LEDs share a colour. `individual` gives every LED its
own. Add a mode, select LEDs and press `Group selection` to make them one
group; the canvas colours the groups of the selected mode, and the test
screen shows how an effect lights them.
## Models
A model is the drawing of an LED or of the fixture's outline: an SVG at a
physical size. `Add model` offers round and square LEDs, a tube segment and an
outline frame; `Load SVG…` takes your own drawing at the size the file gives it. Tick
`outline` for the model drawn around the fixture.
Under `Fixture`, the size is the fixture's frame: what the patch editor
selects, outlines and puts its handles on. `Fit size to pixels` sizes it to
the LEDs, `Fit size to photo` to the LEDs and the whole photo, so a cable
entry or mount drawn beside the LEDs lies inside the frame. `Centre pixels`
moves the LEDs, and the photo with them, around the origin, which is where
the patch editor places and turns the fixture.
A photo of the lamp, or a drawing of it, shows which way it hangs. `Choose…`
takes a PNG, JPEG or SVG file and fits it into the fixture; `Width`,
`Height`, `X` and `Y` place it exactly under the LEDs. It lies faintly under
the pixels, here and under every patched fixture in the patch editor, turned
and scaled with it. `Opacity` sets how strongly it shows, 10 % to start with.
Save with `Save` or Ctrl+S. Patched fixtures follow the saved definition at
once. `Save Copy` saves the edits as a new definition named after the old one
(`NanaTube copy`) and goes on editing the copy.
## In the patch editor
The yellow knob above the selected fixtures turns them about their common
centre; with Shift held it turns in steps of 15°. The `Rotation` field in the
inspector sets the angle exactly. A bar can also be turned and stretched at
once by dragging one of its ends.
Each chain, a string of lamps on one output, has a colour of its own while the
default mode is shown.
Clicking the blue label at the start of a chain shows its network output: the
universe it starts in and its DMX start. Universes go from 0 to 32767, the
whole Art-Net range; a chain that runs past the end of its universe continues
in the next one. Pixels are RGB triples, so a DMX start is 1, 4, 7, … 508. gled
renders up to 8192 different universes at once; a patch that uses more leaves
the highest ones dark and says so in the log.
## Old lamps and projects
gled converts what it finds from before fixture definitions when it starts,
before it loads the assets, and shows how far it is:
* A lamp drawn in the [old SVG format](svg/index.md) under `svg/` in the
data folder becomes a definition, named after its folder and file, unless a
definition of that name exists. It keeps the LED order, the channel order and
every group as a mode, and the drawing becomes its photo. A lamp that is not
a bar gets a frame holding its whole drawing. Parts of a drawing that number
their LEDs alike follow each other; a drawing with LEDs closer than 4 mm is
taken as not to scale and scaled to a 10 mm pitch; a lamp of more than 170
LEDs, where the old gled wrapped into the next universe, is cut into parts
(`Rad 1 of 2`, `Rad 2 of 2`) that share its centre and size.
* A project whose installation is an SVG drawing gets a patch. The old
projects are kept to look at their animations, so near enough is good
enough. Every lamp of the drawing becomes a fixture: a lamp drawn like an
installed definition uses it, a lamp about like one (its LED count and
shape within 10 %) takes it too, and only a lamp like none gets a definition
of its own, filed under `Converted` and shared by every lamp like it.
Fixtures sit where the drawing had them, with the page stretched onto the
scene as the old renderer did, so the animations look as before. Lamps the
drawing numbered one after the other in a universe form a chain. Universes
are renumbered so they fit, and the output routings follow; an old lamp that
straddled a universe moves whole to the next one, and where that would make
lamps share channels its chain moves to universes of its own. Every group
name the tiles and effects used becomes a selection: the whole patch, a mode
of the default layout, or a layout of the lamps it covers. A shape that
numbers itself but has no `count` is one LED, as gled took it before
November 2025.
The converted files are written into the data folder's git repository but not
committed: the staged changes show what the conversion did, and committing or
discarding them is up to you. What could not be converted is reported and left
as it was, and is tried again on the next start.
A lamp is converted whenever no definition carries its name, so a converted
definition that you delete, rename or move to another folder is converted
again from its drawing under `svg/` on the next start. Delete the drawing to
stop that.
Every asset file carries the version of its format (`"version": 1`). A newer
gled brings older files up to date when it starts, the same way; an older gled
refuses a file written by a newer one rather than losing what it does not know.