Models

A model in xLights defines the entire required characteristic about a single physical element of your display. Typically it will represent a common item such as an arch, a matrix, a straight line, flood light as well as more esoteric and custom made items such as singing trees, candy canes, a snowman etc.

It defines the type of lights(RGB, Single Channel, etc), the number of channels, and other characteristics required to render the sequence data. When a model is defined, it is retained in the xLights configuration "xlights_rgbeffects.xml" file in the show directory. It can be reused for all subsequent sequences.

Adding Models

At the top of the layout screen is a row of Model icons. If you hover the cursor on each icon, the model name will be displayed. The model icons represent an Arch, Candy Cane, Circle, Custom model, Icicles Matrix, Single Line, Spinner, Star, Tree, Window Frame, Wreath and Import Custom. The last icon labelled ‘Import’ Custom enables you to import and create a custom model that has been exported from another sequence.

To define a new Model, click on the Model icon that you wish to create once. The model icon will have a dark blue square around it. Then with your mouse left button click on the layout canvas , and keep your mouse button still held down. The model shape will appear on the canvas in yellow. If it does not , then left click on the canvas and drag slightly. At the same time , a model is created and displayed in the Model panel that is normally to the left of the Layout screen.

Depending on the type of model, it will either be bounded by four, three points or two points.

In this image, the Candy canes have three points. The bottom left is green and marks the beginning of the model, the bottom right is blue and marks the end of the model and the top center is blue and is used to rotate the model.

If you cannot locate your model after it has been created, click on the model name in the panel and the model image will be highlighted.

Note that the Preview window has the ‘Default’ preview displayed - indicating that the model that is being created will be assigned to and displayed on the default House Preview window.

By clicking and holding in the center of the model - you can drag the model to the required position. You can also use the three points to size the model on the layout.

When the model is aligned horizontally, a red horizontal line will be displayed.

When the model is aligned vertically, a blue vertical line will be displayed.

In this image, the Single Line model has two points. The bottom left is green and marks the beginning of the model, the bottom right is blue and marks the end of the model. The red superimposed red line indicates horizontal alignment.

If you double click on the Single Line model icon (instead of using a single click) , then you can draw a single line (say as part of the roof line), then click on the layout again and draw another segment from the end of the first segment - this will create another model and so on. Or you can use this technique to draw multiple arches at the same time. Click on the model icon again to deselect it.

On the left of the layout canvas is a window which displays the name of the model that has just been created and the settings of the model.

These are default values and you can then edit the values to suit your requirements - (change the name, start channel , number of nodes etc).

Click on the Preview attribute and change the Preview window if you so require. Set it to ’Unassigned’ if the model is not to be displayed in the House Preview window.

You can collapse or expand any of the windows of the model characteristics.

Deleting Models

To delete a model, highlight the model on the Layout canvas and press the Delete key or press Ctrl X. You can hold down the cursor and drag to form a rectangle around the model and then delete.

You can also Right Click on the Model name in the Model list panel. A ‘Delete’ pop up window will be displayed. Click on it to confirm and delete the model.

Undo

You can also use the Undo function i.e Ctrl-Z to remove the model that has just been added or undo the last model movement. The Undo function can be repeated.

Creating Multiple Model Instances

You can select the model image on the canvas, press Ctrl-C to copy and then Ctrl-V to paste. A new model instance will be created. You can also double-click on the Model icon that you wish to create. The model icon will have a grey/light blue square around it. Then with your mouse left button click on the layout canvas. The model shape will appear on the canvas (surrounded by five blue squares). A left click on the canvas again at the required location will create another instance of the model. And so on. To end the process, click on any of the model icons once.

Rename a Model

A model (name) can be renamed by simply changing the Model name.

Modify a Model

Details of a model configuration can be amended by updating the details in the relevant section of the model definition. Save the changes.

Copy a Model

Once a model has been defined, a quick way to duplicate definitions is to select the model in the Layout window, then use a Ctrl-C to copy it and a Ctrl V to paste it. Save the changes.

Overlap Checks

If the ‘Overlap checks enabled’ attribute is selected, when you click on the model name in the list, it will turn yellow in the layout display to the right. If there is a channel overlap with any other model, then the other model will turn red.

Right Click Menu

Reset

Resets the Current Window View to the default.

Correct Aspect Ratio

This will resize the model so the number of node in the vertical and horizontal direction are equally spaced.

Node Layout

The node layout window is then displayed. The s1, s2, etc. represent the string numbers, the n1,n2,n3,etc represent the node count.

Lock

Lock a model in place to prevent it from being moved. The Model handles will appear red when a model is locked.

Unlock

Unlock a model so a model can be moved.

Export as a Custom xLights Model

Create a Custom Model file from a built in Model Type. Use only if you wire your model in a non support format and a built in type will not work.

Wiring View

Displays a view of how to wire your model based on the Model properties. This can be saved or printed by right clicking on the dialog.

Export xLights Model

Export a Model as a .xmodel file and save to the local disk.

Replace a Model with a Model

"Swap" a new model with an existing model and kept the model name. Use this if want to change a model and keep the same name. This will prevent Model Groups and sequences from breaking.

Arches Model

The ‘# Arches’ value can be set to the number of arches that the model represents (normally one). Similarly you can set the nodes per arch and lights per node (normally 1). The Arc Degrees determines the portion of a circle's circumference the arches use. 180 degrees mean the arch is half the circumference of a circle and 90 would be one forth circumference of a circle. The Arch Tilt will tilt the arches "hops" left or right. This is useful for arches on a incline.

The example above will contain two arches of 25 pixels each, for a total of 50 pixels. Each pixel contains 3 LED per pixel so there are 3 lights per node.

Layered Arch

With Layered Arch enabled, a multi layered arch will be created. The Layers attribute value describe the concentric arches in the model. This will create node count settings for each layer. The sum of the node counts must add up to the number of nodes in the model. 'Hollow %' will set the space "under" the arch.

Model Settings

The model settings determine the physical properties of the model or prop. These setting are critical for how xLights determines the render sequence data, start channels, and controller connections.

Name

The name of the model. The Model name can be changed by clicking on the existing name and changing to a new value.

# Strings

The # of Strings corresponds to the physical number of strings for that model and is generally 1.

Nodes/String

Nodes per String denotes the number of nodes/pixels per string. If your model has 2 strings and 50 node per string, the total number of nodes is 100.

Lights/Node

Lights per Node denotes the number of physical lights per node. (i.e. for pixel strips with 3 LEDs per controller chip, this would be 3).

Lights/String

Lights per String denotes the number of lights per string. This will be used instead of the Nodes/String and Lights/Node settings.

Start Location

Location of the first pixel or first channel location. "Green Square" means the starting location is the green square on the layout and "Blue Square" means the starting location is the blue square.

Controller

xLights has two systems to define model start channel locations. If the controller dropdown is set to a controller name specified in the controller tab, the start channel will be auto generated based on the Controller Port and Model Chaining settings. This is the preferred method of configuring start channels.

Start Channel

The Start Channel corresponds to the starting channel of the first node for the model. xLights will automatically calculate the end channel based on the model settings.

If the controller dropdown is set to "Use Start Channel", by Default, xLights will "chain" all you models together, this means the start channels will just follow the previously model.

In this example, the Start Channel has been set to start immediately after the ‘Candy Canes-2’ model.

xLights will automatically calculate the start channel and end channels, and if the ‘Candy Canes-2’ model’s channels change, then the start and end channels for this model will automatically be recalculated.

Click the ellipse button (three periods) to edit the start channel.

Model Start Channel can use Absolute, Universe, Start/End of Model or Controller based addressing.

Individual Start Channels

For models with multiple strands or elements, you can specify the start channel for each strand individually if required. This is useful where the channel numbering is not contiguous.

Preview Display

The Preview setting controls whether the model is to appear in the House Preview screen and also which Preview layout screen. Click within the setting to open up a window which lists all the available Previews. If you have created additional Preview layouts, they will be listed in the window.

The ‘Default’ value represents the default preview window.

‘All Previews’ indicates that the Model is to be displayed in all Preview Windows.

‘Unassigned’ indicates that the model will not be displayed as it is not assigned to a Preview window

‘Unassigned’ is sometimes useful where the same physical item has been re-defined using more than one model definition for ease of programming the effects. One of them should have the Preview set to ‘Unassigned’ and the other should not.

The ‘2nd Preview’ is one that has been user created.

Strand / Node Names

Click the ellipse button (three periods) to edit the Strand / Node Names.

Each strand and node can have a name assigned to it. This is useful where for example you have single channel models that are grouped together (singing faces, tombstones or DMX props etc). On the sequencer, double clicking on the strand reveals the nodes with meaningful names against them.

Faces

This setting is used to specify the Faces definition for custom models that support Singing faces.

Click the ellipse button (three periods) to edit the Faces.

Functionality has been covered in the Singing Faces section.

Dimming Curves

The Dimming Curves setting can be used to change/reduce the brightness of the lights for a specific model. The intensity of the lights is accordingly changed/reduced from its default value of 100%. Use the "Brightness" slider where you can reduce (or increase, but 99% of the time, you reduce) the brightness of the model in the FSEQ. Change the gamma curve of each of the red, blue or green values.

You can select from the options to have a single gamma value or change individual gamma values. You can also select the values from a file, in which case you are prompted for the location of the file.

State

This setting is used to specify the State definition for custom models. Functionality has been covered in the State Effect section.

Sub-Models

This setting is used to specify parts of a model to be controlled as if it were its own model. This is used for example if you have a wire frame with 2 arm positions you then can sub model those and control them without the need for adding a 2nd or 3rd model.

Click the ellipse button (three periods) to edit the Sub-Models

You will find the sub-model listed as parent model name/sub model name. This can be added to groupings and added to sequencing as a stand alone model.

See the Sub-Models Section for more info.

Controller connection

The Controller Connection settings are used for the Upload to Controller Options in the Controller Tab. Port specify which output of the controller is being used by this model. Protocol is the pixel type or serial type. If a serial protocol is set i.e. DMX the Port setting sets which DMX Port is used on the controller. If the Protocol is set to a pixel protocol i.e. ws2811 the Port setting sets which pixel output is used on the controller board. The additional settings(Null Pixels, Brightness, Gamma, Color Order, etc) will override the setting in the controller if checked. Not all controllers support all settings and some controllers only support one setting per controller port.

Upload to Controller is covered under controller tab.

String properties

String Type

The String Type enables you to set or change the ‘RGB’ orientation of your nodes.

The first six options in the list below are used for Pixels - these can also be set in the hardware controller. Dumb pixels are set to either 3 Channel RGB or 4 channel RGB and single “A/C” or store bought fairy lights are set to single channel.

Color

The Color setting is used for Single Color/Node Single Color String types to define which color the string responds to. If set to White , then only when the White is on, on the sequence , will it light. If set to say Red , then it will light if Red is on (which is 255,0,0) or if White is on (because White sets 255,255,255 on).

RGBW Color Handling

Appearance

The Appearance setting is used to determine how a particular element is displayed when viewed in the Layout, House Preview and Model windows. By increasing the Pixel Size, the appearance of the element (a flood or any other small element) can be made to display a bigger size. The Transparency and Black Transparency values can be used to adjust how opaque or transparent the element is on the display. If the Active option is unchecked the model will not be shown in the layout screen.

Tag Color adds at color indicator before the model name in the sequence tab.

Size/Location

The size/location settings describes where on the Layout screen a model has been place, and its relative size to the model grid. XYZ are the center point of the model. ScaleXYZ determine the size of the model. If a model is locked it cannot be moved. Locked models will have red handles in the layout window.

These values "auto adjusts" as you move or change the size and orientation of the model image and normally does not have to be manually set or adjusted. Model can be locked and unlocked with the right click menu.

Channel Block Model

The Channel Block can be used to define an arbitrary amount of channels. It can be used to 'model' generic channel to be used or AC Lights, relays, smoke machines, etc.

# Channels

Number(#) of Channels defines the size of the channel block. These Individual channels can then be used to control specific channels on a device or controller.

Channel Color

Channel Color determines what color in the sequencer will "activate" this channel block channel. If set to 'White' all three RGB channel values will be use to set the output channel value. If set to 'Red' only the Red channel values will be use to set the output channel value.

Candy Cane model

The ‘# Canes’ value can be set to the number of canes that the model represents (normally one). Similarly you can set the nodes per cane and lights per node (normally 1). The angle of the cane can be adjusted by changing the Cane Rotation value, or grab and move the top of the cane clockwise or anti clockwise.

Select the Reverse attribute to set the the crock of the cane facing the opposite direction. Select the Sticks attribute to set the cane to be a straight line without the curved crock.

In this example, a Candy Cane model has three canes in one set. Each cane has 18 nodes in it.

The start channel address is 1 and it is has RGB pixel nodes so it will use 54 channels.

Alternate Nodes will skip every other hole to allow wiring up and down each candy cane and prevent wire splicing.

Automatic Start Channels

If Auto Layout Models is enabled in the Controller Tab, xLights will automatically calculate the Model Start and End Channels based on the controller settings.

First Set the Controller the model will be connecting to.

Then Set the Controller Port

If assigning multiple models to one controller port you must set the model chaining to determine the order of the models on the controller output.

Manually Changing Start Chanel

First Change the Controller Dropdown to "Use Start Channels" in the model settings.

Click within the Start Channel cell and then click on the highlighted box to open up The Start Chanel Window.

The 'Offset From' determines how the start address is calculated. If the offset is set to "None" the start channel is then used to define the absolute channel number.

However it is possible to use other definition setups:

If you select the ‘Universe Number’ option, the start channel for the model is calculated based on the “start channel” that is offset from this ‘Universe Number’.

If you have one controller setup on your controller tab with universes 10 through 14, all with 510 channels, for the model set as Start Channel “1”, From Universe “11”, its real absolute start channel in the FSEQ would be channel 511 (first channel of the Universe 11).

The “ANY” value indicates that the Universe is not specific to an IP address and therefore xLights searches for the universe number. (This is the recomended setting to use)

You can specify a specific IP address if you wish - in the unusual event that you have the same universes on different controllers on different IP addresses.

The start channel value can also be specified relative to other channels using the End of Model or Start of Model options. You can specify an offset from an output number or select the start channel to start from the end of another model or align with the start of another model (in the last two scenarios, the model name is to be selected from a drop down box).

This options works well if your models are reasonably static as the channel numbers are automatically calculated. If however, you delete models then it can break the chain . xLights will alert you to this , but the popup dialogs could be tricky to navigate through.

The ‘Controller’ option, uses the controller name to determine the start channel for the model. It is calculated based on the “start channel” that is offset from the Controller Start Channel in the Controller Tab. This option works well for P5 or P10 Panels running of a FPP controller.

Circle model

# of Strings

The # of Strings corresponds to the physical number of strings for that model. This should match the number of controller ports you plan to use.

Nodes/String or Lights/String

The Nodes per String or Lights per String represents the physical number of light nodes, bulbs or pixels in each string. If the # of Strings is set to 2 and the Nodes per String is 100, the model will contain 200 total nodes.

Center %

The Center % is used to indicate how much area the empty area of the circle occupies. Decreasing it will drop the circles inwards and increasing it will push the circles outwards.

Layers

The Layers attribute value describe the concentric rings in the circle. This will create node count settings for each layer. The sum of the node counts must add up to the number of nodes in the model.

Starting Location

The default starting pixel is at the bottom of the circle, go clockwise on the outside ring and then the next inner ring wired and so on. The Starting Location can be changed to start at the top of circle, or start on the inter ring or run counterclockwise if needed.

Cube Model

The Cube model is a 3D model that is used to model objects like Pixel/Peace Stakes, Boxes, or Grids. While the model is 3D, xLights renders the effects in 2D.

Stand Style

Layers All Start in Same Place

All the wiring for each layer will start in the same location. Bottom Left in the example above.

Example Configurations

3W x 3H x 3D, Front Bottom Left, Horizontal Left/Right, ZigZag

3W x 3H x 3D, Front Bottom Left, Vertical Left/Right, ZigZag

3W x 3H x 3D, Front Bottom Left, Horizontal Front/Back, ZigZag

3W x 3H x 3D, Front Bottom Left, Stacked Left/Right, ZigZag