**Historical design note (2026-09).** Written before the implementation; the code has moved on.
See `book/src/fixture-definitions.md`.
# Goals
## Design philosophy
- Learning curve should be a sigmoid wrt. to required experience vs expressivity of the tool. this can roughly be
divided into 3 phases:
1. the user gets to know the tool and is able to do first rudimentary shows, complexity is mostly out of sight for him
2. the user is about to learn about more advanced concepts as he plays around / tries to achieve more sophisticated setups
3. he masters the tool. He has a complete mental model of the tool and knows how to implement his ideas with the given concepts
- The concepts should "organically" represent the "language" in which a user imagines a light show. At this point
gled becomes slightly opinionated, as its vocabulary slightly appeals to a certain style of doing things
- Usability aspects to optimize / balance
- speed / efficiency
- mental load
- experience gain / intuitiveness
- expressivity
# Implementation
The following is (hopefully) in line with the stated goals and tries to implement them
## Concepts
- Topology
- default layout + how the fixture are connected to ports and in which order
- one topology per project
- Layout
- contains a subset of all fixtures in a user definable 2d layout
- contains a default mode + additional user added modes
- every "layout" mode contains for every fixture, which individual mode should be used
- the default mode uses for every fixture the respective fixture-definitions default mode
- (Virtual-) mode
- A mode is a left-unique relation between pixels <-> pixel group
- modes live inside fixture definition, every fixture def. has a default mode "individual"
- pixels
- fixture
- a instance of a fixture profile
- fixture definition
- contains all relevant information about a physical lamp which may be installed
- contains modes, pixels, preview graphics, color profiles, artnet 2 pixel mapping, etc...
## Editor
- on the left side: the layout stack. a layout can be selected here for editing, like layers in photoshop
- instead of selecting a layout, the topology can be selected for editing
- on the right side: the editor itself. fixtures can be spatially layouted and a background image can be selected here
for reference
- if the topology layout is selected, also the node connections are shown and may be edited
- the topology layout is the default layout. Its name cannot be changed. in the code its not part of the layout collection
but lives in an extra variable
- the default layout is visually not part of the stack, but lives visually above it, as the usual operations like
delete, copy, rename dont apply to it. this must be represented, how the default layout element is semantically presented
to the user
- above the layout stack on the left side is the inspector. it can inspect individual fixtures. here also the per
fixture mode is selected
- multiselection of fixtures is possible. Similar to how this would work in other software, if many fixtures are selected
their attributes can be set to one value. if an attribute is different among the multiselection the preview adapts dynamically
- if a property is different the preview shows "-". a change here will set a common value
- if different fixtures have different properties, they are not shown in the multiselect inspector
- the fixtures in layouts apart from the default layout are not added, but "selected". That means, that they are
either included in a layout or not. The topology will still show in the non default layout editors, but not have the
handles to be edited here.
- instead of "+Fixture", the button for selecting fixtures to be included or not, is in the editors for non-topology layouts.
Opening it reveals an overlay, where individual fixtures can be selected and deselected. Selection here is different from
the layout editors selection itself, fixtures are not selected exclusively on click, but are added or subtracted in the selection
the same applies for the box selection. The user might also benefit from the alt+ mouse drag box selection, which
deselects
- also in this overlay are two lists, where fixtures items can be moved between the included, not included list, for
cases when the user prefers a workflow based on the attributes / names instead of the visual positions. In the list,
the following attributes of each fixture are shown: name, fixture type, universe+dmx address
- a selected fixture in the layout is visually indicated with a green outline instead of a white one like in the editor
- the mouse drag box select + the alt mouse drag deselect shall also exist in the editors. however there is also shift + drag
select, for additive box selection (similar to shift click select works)
- in the top left, above the inspector exists a test screen, which is similar to the live preview in the main window,
it displays the output of a test tile on the layout, so that the user can instantly see the what the layout and mode
which he currently selects, can be seen instead of having to switch to the main window, and patching a test tile there
- the current mode which is being edited in the layout editor of a selected layout is chosen in the top bar (where
the add fixtures button also lives)
- If a node has the blue network output element attached to it, because it is the start of a chain, the network output
can also be selected and its options will be shown in the editor. Here the artnet start universe can be chosen
- optionally also dmx start address can be chosen
- the editor reacts in an intuitive and workflow support way to changes to the network output.
- if a new parent nodes is attached to the chain, the network output options wander onto the new network output
- the network output also previews its dmx starting universe visually on it in the editor, if a custom dmx start address
is set, that will also be shown.
- The top bar contains the button for adding or selecting fixtures. In the topology view, when the add button is clicked
the user shall be able to choose from the different fixtures. for that a list shall be shown which shall for each fixture
preview: the name of the fixture, the amount of dmx channels, a preview image of the fixture visualization, a preview image of the actual
lamp itself if available
### Perspective Transform
- The transforms which are applied to fixtures in the editor should represent 3D spatial transforms but be constrained
with degrees of freedom which make sense wrt. their respective fixture definition. This is to achieve two goals
- give the user the ability represent the actual spatial situation in a room from the perspective of a given reference image.
this should have priority wrt. the way which gui elements for transformation are presented to the user
- give the user the ability distort the scales of a fixture, which is counterintuitive to the physical world, but for
artistic effect.
Examples to give meaning to the above
- A bar only two handles. One at each side. The length and endings of the bar can be defined this way. The wideness
of a pixel bar should follow the proportions of the fixture as its size is defined by its length. The reason for this is
that there is no benefit in scaling a bar horizontally, if all pixels lie on a straight vertical line
- A structure like a pixel array should scalable along a choosable axis even in counterfactual way to the physical reality
(i.e. even if the transformation is not representable anymore with a perspective deformation), as this might be used for
artistic effect
- in the editors cmd/ctrl + A is usable to select all. cmd/ctrl +C, V, X additionally are , copy, paste, cut fixtures in the topology editor.
these operations can also be invoked via the context menu
## Preview
- the fixture definitions have different svgs for preview.
- for the show preview, the pixels have polygons representing pixels respectively. These pixels shall in the live preview
be rendered in their respective color
- there shall be an svg for the editor outline
- in the editor the pixel polygons can just be drawn black
## Assigning layouts
every tile should have a layout and mode selection, with the default
selected. each fx should have the same two selections, but by default be set to just inherit by the tile. the selection itself must be a 2 step context menu. first
press the button for the layout, the list drops down and a layout is hovered, now, the layout may just be clicked, resulting in the default mode being chosen.
additionally on the hover a sublist is shown to the right, where a list of modes for the layout appears and may be clicked. similar to how sometimes dropdown
menubar entries sometimes have submenus, usually with something like a triangle pointing to the right. This submenu should only exist for layouts which have more
then the default mode
## The fixture editor
- the fixture editor is a window type. it can be opened from the main menu bar via "Project" -> "Patch Fixtures"