Models

• This page is still in development.

Models

Defining a Model

• A model in xLights/Nutcracker 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, the number of channels and other characteristics required to render the sequence data. When a model is defined, it is retained in an xLights/Nutcracker configuration .xml file in the show directory. It can be reused for all subsequent sequences – however it needs to be added to the sequence grid of each sequence as required in order for effects to then be sequenced against the model. A model is made up of one or more strands, and each strand is made up of one or more nodes. To define a model, after opening an existing sequence or creating a new one.

Model Lists

Click on the Models icon on the top row of the canvas or Click on the Models button on the Layout window Right click when in the sequencer window, select Edit Display Elements and then Add Models Clicking on the Models icon, the model list window will display any existing models that have already been defined.

New Model Definition

Click on New to define a new model. Specify a Model name and the type of model (Display as).

The Actual # of Strings corresponds to the physical number of strings for that model. Typically an arch or a candy cane will have one string, but models such as a mega tree or a matrix will have many strings. See the examples of a Mega tree and matrix below. •# of RGB Nodes per String represents the physical number of light nodes, bulbs or pixels. •# of Strands per String is usually 1, except in the scenario where a physical string has been folded in which case it can be 2, 3, 4 etc. •The Start Channel defines the starting channel number for the first node of the model. •The From Output in most cases is set to 1 as default and the start channel is then used to define the absolute channel number.

However it is possible to use a different definition setup wherein:

The start channel for the model is calculated based on the “start channel” that is offset from this ‘From Output’ number (default is 1). If you have 4 outputs setup on your setup tab being universes 1 through 4, all with 510 channels, for the model set as Start Channel “1”, From Output “2”, its real start channel in the fseq would be channel 511 (first channel of the second output). Sometimes keeping track on a “per universe” basis is easier than the raw count from the very first channel.

•Starting corner is used to define where the first node starts in a multidimensional model (i.e. a matrix or mega tree). See to the default value of Bottom Left if running from left to right or Bottom Right if running from right to left.

•Part of my display. Tick this option if this model is to appear on the Layout screen. In most circumstances, this should be selected. However, where the same physical item (spinner) has been defined using more than one model definition (spinner and spinner matrix) for ease of programming the effects, then one of them should have the attribute selected and the other should not.

•Model Brightness Adjustment. This 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 %.

•Individual Start Chans 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.

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 values can be used to adjust how opaque or transparent the element is on the display.

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 etc). On the sequencer, double clicking on the strand reveals the nodes with meaningful names against them.

Strands and Nodes

From the sequencer grid view, right click on a model name, and click on the Toggle Nodes option, to display all strands for the model.

With the strands view open (i.e. displayed), right click on a strand to either toggle the strands closed or to Toggle Nodes and display the nodes for a strand.

This is often useful to see how a particular effect has been rendered down to the node level.

Model groups

• Model Groups can be used to group a number of similar elements (Arch1 … Arch6), so that by dropping an effect at the group level, the effect will be applied to all models that are part of the group.

It can also be used to limit what you see on the display, by creating a group of selected models and then adding the group to the display on the Layout tab. Dropping an effect on a Model group will give different results to dropping the same model on all elements of the group (because in the former case the canvas is treated as a whole matrix and then the effect is applied to the models within it). Some effects work at the Group level better than others.

Creating a Model Group

• To create a Model Group, from the layout tab click on Select Model Groups.

From the Model Groups window, click on Edit Groups. Click on Add Group to create a new group and replace the name of the group in the Group Name. A list of all available defined models will be displayed in the left hand window. Use the arrows to add models to the Group). Click on Update Group when complete.

Modifying a Model Group

• To modify the models that form part of a group, click on the group name in the top right hand window.

The models that are currently in the group will be displayed in the ‘Models in Group’ window and the other models will be displayed in the ‘Add to Group’ window. Use the arrows to add or remove models as required and click on the Update Group when done.

Removing a Model Group

• To remove a Model Group, select the Model Group and click Remove Group. This will not change or remove any of the underlying models, however any effects that have been placed at the group level on the sequencer will be removed and the Model group will be removed from the Layout display if it has been added to that display.

• Tip: When on the sequencer tab, If you right click on a Model group, the window will display a ‘Toggle Models’ option which will display all the models under the Model group (or hide them if you select the option again). You can also double click on the Model Group to obtain the same results.