View source for Creating Custom Fixtures

[[ru:Создание пользовательских приборов]] [[en:Creating Custom Fixtures]]
'''Creating Custom Fixtures''' is the in-program description of a fixture that isn't in the ready-made sections of the [[Fixture Library]], or of a fixture operating in a different DMX mode than its factory description. In essence, a custom description is the fixture's channel table from its datasheet, transferred into the program: how many channels the fixture occupies, what each of them means, and how the fixture lights up in the '''3D View''' window.

Custom fixtures are stored in the '''My Fixtures''' section — only they can be edited; the factory sections are protected from editing. The library is tied to the program, not to the project, so a fixture created once is available in every project on this computer.

== When a Custom Description Is Needed ==

* The needed model isn't in either the '''LED Fixtures''' section or the '''Manufacturers''' section.
* The model exists in the library, but the fixture itself is set to a different DMX mode — with a different number of channels or a different channel order.
* The fixture has a non-standard color order, and with the factory description it lights up the wrong color.
* The program shouldn't touch some of the fixture's channels.
* The ready-made description matches the channels, but the fixture needs to light up differently in 3D — a different beam type or a different size.

For an ordinary pixel strip, bar, or string, a custom description isn't needed — a standard fixture from the '''LED Fixtures''' section will do (see [[Fixture Kinds and Types]]).

== What to Find Out in Advance ==

The description is built from the fixture's datasheet, so before you start it's worth knowing:

* which DMX mode is set on the fixture itself — a single model usually has several;
* how many channels this mode occupies;
* what each channel does, in order, starting from the first;
* for moving-head fixtures — the '''Pan''' and '''Tilt''' rotation limits in degrees.

If the mode on the fixture changes later, the description will have to be redone: the program reads channels exactly as they're written in the description.

== Creating a Fixture From Scratch ==

# Open '''Settings → Fixture Library'''.
# Select '''Create → Fixture'''. A template named '''RGB''' will appear in the '''My Fixtures''' section: three channels — red, green, blue — and the '''Pixel''' kind. The template is selected immediately, and its description opens on the right, with all fields available for editing.
# Set the name in the field at the very top of the right-hand panel. The name is visible in the library tree and in fixture properties, so it's best written so that both the model and the mode can be guessed, for example ''Model 12ch''.
# In the '''3D Preview''' block, choose the '''Beam Type''' and the beam dimensions.
# Below, in the '''DMX Settings''' block, set '''Channel Count''' — as many as the chosen DMX mode occupies.
# In the channel table, set the assignment for each channel: click a row and choose a value from the list.
# Run '''File → Save Library'''. Until the library is saved, the fixture exists only in the open window.

Now the fixture can be assigned: select fixtures on the mapping and click '''Select Fixture''' in the bottom-right corner of the library window — see the [[Fixture Library]] article for details.

== Channels ==

The channel table is the main part of the description. The number in the '''#''' column is the channel's offset from the fixture's address: the first row goes to the fixture's address, the second to the next address, and so on. That's why the row order must exactly match the channel order in the datasheet.

What can be chosen in the assignment list:

{| class="wikitable"
! Assignment !! What the program sends to the channel
|-
| '''red''', '''green''', '''blue''' || The red, green, and blue color components from the fixture's point on the '''Mapping''' field
|-
| '''white min''', '''white average''' || The white component: the smallest or the average of the three color components
|-
| '''red-min(rgb)''', '''green-min(rgb)''', '''blue-min(rgb)''' || The color component minus the white component. Used together with a white channel on fixtures where a white LED replaces the gray part of the color
|-
| '''pan''', '''tilt''' and the fine '''panfine''', '''tiltfine''' || The rotation angles of a moving-head fixture
|-
| '''strob''', '''shuttern''', '''gobo''', '''focus''', '''zoom''', '''frost''', '''movementspeed''', '''reset''' || Service channels of “smart” fixtures. The program doesn't change them on its own — the value is set by the '''Set Channel Values''' and '''Channel Animation''' effects
|-
| '''other''', '''other 1'''…'''other 10''' || Channels whose purpose isn't spelled out in the description: dimmer, macros, color-wheel selection, and so on
|-
| '''color white 5 bit''' || A special white channel found on certain models. Not used in ordinary descriptions
|-
| '''Empty''' || A channel the fixture occupies, but the program writes nothing to it
|}

A few rules that are easiest to trip over:

* '''One assignment — one channel.''' If two channels in the description are marked the same way (for example, two '''red''' channels), only the last one will receive data. So every channel you intend to control must have a different assignment — that's exactly what '''other 1'''…'''other 10''' are for.
* '''Extra channels can't be skipped.''' If the fixture's mode occupies 12 channels but only the first three are needed, still set the channel count to 12 and mark the rest as '''Empty''' — it can be assigned to any number of rows in a row, since the program writes nothing to such channels. Otherwise the next fixture on the port will end up at the wrong address.
* '''Increasing the channel count copies the last channel.''' Added rows repeat the assignment of the last row and need to be reassigned — otherwise you get those very same duplicate channels.
* '''Decreasing the channel count removes rows from the end''', but their values are remembered: if you immediately set the previous number back, the assignments are restored exactly as they were.

The program calculates the values of color and white channels itself, frame by frame. The remaining channels hold zero until an effect sets them. For more on what channels mean and how addresses and universes are built from them, see [[Fixture Kinds and Types]].

== 3D Preview Settings ==

The '''3D Preview''' block is only responsible for how the fixture looks and lights up in the '''3D View''' window. It doesn't affect the DMX data, but it determines how closely the preview resembles the real object.

{| class="wikitable"
! Beam Type !! How It Lights !! Size Fields !! Default Values
|-
| '''Pixel''' || Glows by itself, like a point; no beam || No beam dimensions — the size of the point itself is set on the fixture in the 3D scene || —
|-
| '''Linear''' || Fills a surface with a wide beam along the body || '''Length''', '''Angle°''', '''Depth''' || 100, 30, 600
|-
| '''Spotlight''' || Produces a directed cone of light || '''Angle°''', '''Height''' || 30, 500
|}

The set of fields changes immediately when the beam type is switched, and unused fields are hidden. '''Angle°''' is the beam spread, '''Depth''' and '''Height''' are how far the beam reaches, and '''Length''' is the length of the glowing part of the body.

These dimensions are a template for new fixtures. For a fixture already placed in the 3D scene, the beam is set up separately, in its properties (see [[Fixture Kinds and Types]]).

== Fixture Image ==

Next to the '''3D Preview''' fields the fixture's picture is shown — the same picture is also displayed as a small icon to the left of the name in the library tree. For a custom fixture it can be replaced: click the '''Change Image''' link and choose a '''JPG''', '''BMP''', '''GIF''' or '''PNG''' file.

The image isn't embedded in the library — only the path to the file is remembered. The selection dialog opens directly in the program's folder for fixture images: if you place the picture there and don't delete it, the image will stay in place even after a restart. If the file is later moved or deleted, the picture simply stops displaying — this doesn't affect the fixture's operation.

== Moving-Head Fixtures ==

For fixtures with rotating mechanics there's a separate template: '''Create → Moving Head'''. It's created with the name '''Move head''', four rotation channels — '''pan''', '''panfine''', '''tilt''', '''tiltfine''' — and the '''Moving Fixture''' checkbox already enabled, with '''Pan''' limits of 0–540° and '''Tilt''' limits of 0–180°. The template is added to the end of the '''My Fixtures''' section: find it and select it to configure.

From there the description is built the same way as an ordinary one: the channel count is brought up to the number of channels in the mode, and the channels are arranged according to the datasheet. If the fixture has no fine rotation channels, the '''panfine''' and '''tiltfine''' rows are reassigned or removed.

The '''Moving Fixture''' checkbox can also be enabled on an ordinary fixture — this opens the '''Pan, min''' / '''max''' and '''Tilt, min''' / '''max''' fields. Enter the fixture's full rotation range in degrees from the datasheet: the '''PAN TILT Animation''' effect uses them to convert the set angle into a channel value. If the range is entered incorrectly, the fixture will turn to the wrong position relative to what the effect shows.

Clearing the checkbox removes the rotation limits from the description. If it's checked again, the fields will hold the same values as before it was cleared, and for a fixture that wasn't a moving fixture before, they'll be 0–540° and 0–180°.

== A Fixture Based on a Factory One ==

When the needed description nearly matches an existing one, it's faster to copy it rather than build it from scratch. Select a fixture in any section and click '''Copy to Personal''' — a copy will appear in the '''My Fixtures''' section with ''Copy'' added to the name, it will be selected immediately, and it can then be edited.

This is a convenient way to make descriptions for neighboring DMX modes of the same model: copy it, rename it, and adjust the channel count and assignments.

The copy is an independent fixture, not a reference to the original: edits to it don't affect project fixtures that are assigned the original description. For the copy to take effect in the project, it needs to be assigned to the fixtures again using the '''Select Fixture''' button.

== Saving and Applying ==

Everything done in the library window exists only there at first. '''File → Save Library''' commits the changes. The program will also remind you to save: when closing the window with unsaved edits it will ask '''Save Library?''' — answering '''No''' returns the library to the state it was in when the window was opened. Clicking '''Select Fixture''' also prompts the program to offer saving the library before making the selection.

When saved, the new description is applied to every project fixture that already has this fixture assigned. What this means in practice:

* if the channel count has changed, the fixtures will occupy a different number of addresses, while the addresses of neighboring fixtures on the port stay the same — creating an overlap or a gap. Addresses can be recalculated via right-click on the port, the '''Recalculate Fixture Addresses''' item, or set manually — see [[Patching Fixtures]];
* if the channel assignments have changed, the picture on the real object will change too — the colors will be rearranged;
* the beam parameters of fixtures in the 3D scene are taken from the description again. If you customized the beam for individual fixtures in the '''3D View''' window, those settings will revert to what's recorded in the library fixture.

A custom fixture can only be deleted from the '''My Fixtures''' section: select it and press '''Delete''' or '''Backspace''', or choose '''Delete''' via right-click. The program will ask for confirmation. Projects where the fixture is already assigned won't be affected by the deletion: its description is also stored inside the project itself.

== How to Check a Description ==

# Assign the new fixture to one fixture on the mapping and patch it to the device's port. In the '''Fixtures''' window, check the address of the next fixture in the '''Address''' column: the difference should equal the channel count.
# Put a simple solid-color fill in the composition and turn on '''Art-Net'''. If the fixture lights up green or blue instead of red, the order of the color channels is mixed up.
# Service channels are checked with the '''Set Channel Values''' effect: it shows the channels of the selected fixtures by name, each channel is turned on with the '''On''' button, and the value is set with a slider — you can immediately see what the real fixture does.
# Rotation is checked with the '''PAN TILT Animation''' effect: set the extreme angles and compare them to where the fixture actually turns.

== Frequently Asked Questions ==

* '''The fields on the right are grayed out, nothing can be changed.''' A fixture from a protected section is selected. Only what's in '''My Fixtures''' can be edited: copy the fixture there using the '''Copy to Personal''' button.
* '''After restarting the program, the fixture is gone.''' The library wasn't saved. Only '''File → Save Library''', or answering '''Yes''' to the prompt when closing the window, commits the changes.
* '''One of the channels doesn't respond.''' Most likely another row in the table has the same assignment. Of two channels with the same assignment, only the last one works.
* '''The fixture itself lights up correctly, but the neighboring ones don't.''' The channel count in the description doesn't match the real DMX mode, and every subsequent fixture on the port is shifted. Check the channel count against the datasheet and recalculate the addresses — via right-click on the port, '''Recalculate Fixture Addresses'''.
* '''I changed the description, but nothing changed in the project.''' Changes are applied when the library is saved. If nothing changed even after saving, the project's fixtures are assigned a different description — for example the original instead of the copy; assign the needed fixture using the '''Select Fixture''' button.
* '''How to make several modes of the same model.''' With a separate description for each mode: copy an existing one and adjust the channel count and assignments. It's convenient to include the mode number in the name to avoid confusing them when selecting.
* '''The fixture is needed on another computer.''' The library isn't transferred together with the project, but the description of a fixture in use is stored in the project file: open the project on the other computer, find the fixture in the '''Used in Project''' section, and click '''Copy to Personal''' — it will go into '''My Fixtures''' on that computer.