Models

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.
• 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.
  1. 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.

Custom Model definition

• xLights/Nutcracker enables you to define models that do not fit into the concept of predesigned common shapes. For example, a snowman outline, reindeer outline, a singing face, etc.

• In order to define such a model:

create a new model, select the ‘Display As’ attribute as Custom and select a layout size (width and height).

• A custom model grid will be displayed in which you enter numbers in the grid representing your model. If your model is a candy cane with 12 nodes, you could have a grid 4 columns wide and 10 rows high. Place the numbers 1-9 up the right hand side, 10 and 11 in the middle cells in the top row and 12 would go in column A row 2

• If you enter a number and wish to erase it, enter 0 in the cell. It will be removed when the grid is saved and reopened. You can use the ‘+’ and ‘-‘ keys to make zoom in and out. You can also enter the same data in Excel, copy the cells from Excel and then use the paste icon to paste the data into the cell in row 1 column 1. Save the model.

Rename a Model

• A model (name) can be renamed by selecting the model name from the Model List window and clicking on the Rename button. Enter a new name when requested.

• Note: If the model is already part of a Model group, you should update the Model Group definition. If you don’t then xLights/Nutcracker will subsequently provide an option to delete or select the new model name when the application is loaded again.

Modify a Model

• Details of a model configuration can be amended by selecting the model name from the Model List window and clicking on the Modify button.

Copy a Model

• Once a model has been defined, a quick way to duplicate definitions is to select the model name from the Model List window and clicking on the Copy button. The existing details are copied into a new window. Change the name as required and amend any other details such as the Start channel number and Save the changes.

Node layout

• Clicking on the Node Layout button opens a window, which then displays how the nodes are laid out in the model within each string.

Export csv

• Clicking on the Export CSV button, enables details of one or all models to be output to a csv file (highlight the models required). You will be prompted to specify a location and filename.
• A single row is created for each model and includes the model name, ‘display as name’ attribute, string type, string count, node count, start channel, start node, ‘part of my display’, model brightness adjustment value.

Play Model

• If the Model Preview window is open, you can play the model effects in the window by right clicking to the left of the sequencer grid and selecting Play Model. The sequencer will start playing and the effects in this window will focus on the selected window.
• You can also achieve the same result by clicking on an effect against the model in the grid and then selecting Play.

Export Model

• This function is used if you wish to export effects from your model to another sequencer, such as LOR, LSP, Vixen, HLS.
• It can also be used to export an eseq (effect sequence) to the Raspberry Pi Falcon Player . Effect files are .fseq format files with an .eseq extension. These special sequence files contain only the channels for a specific effect and always start at channel 1 in the sequence file. The actual starting channel offset for the Effect is specified when you run it or configure the Effect in an Event on the FP.

• Right click to the left of the sequencer grid and select Export Model.

You will then be presented with a window where you can select the target sequencer type and the filename to be created. Press OK when done.

• Status messages will be displayed on the last line of your sequencer as the model is exported. The file will be created in your show directory.

• Tip: Eseq (effect sequences) can be played on the FP any time while a main fseq sequence is running and you can have as many effect sequences running as you want on different elements of your display.xlights-tip.JPG. You can use this functionality to export a models effects to the Falcon Player and then use the effect to run a continuous background sequence such as a “Tune to” sign, independently of sequences running in via the fseq file.

Import Model

• There is no functionality to directly import an xLights/Nutcracker model that someone else has created. However, since models are defined using xml, you can copy them into your xlights_rgbeffects xml file in the models section. Then update the channel assignment to your setup.

• Tip: Use an editor that works well with XML. Notepad++ is a free editor than can be used.

Ensure that after you paste the xml, that the </models> end tag is returned to its original position on a new line. If you leave that end tag at the end of the last model line, it won't work.

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.

Sequencer

• 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.

Render All

The ‘Render All’ icon is used to force a render of all effects ­ that have either been created within xLights/Nutcracker, imported via the Import Effects function or has been imported as a Data layer.

Rendering order

The Data Layer order renders bottom to top. Therefore what is on the top layer will be done last – much like painting – the last brush strokes are on the top.

Model layers also render bottom to top. Therefore the bottom layer will be rendered first, then the layer above it and do on until the top layer is rendered last.

However, the Models themselves render top to bottom based on how they are laid out in the Master View of the sequence. So the top model is rendered first, then the next lower model until the last model is reached.

This is important to keep in mind when you have multiple models or model groups mapped to the same channels such as whole house model group and regular models.

Tip: You can change the order of data layers by moving them up or down. You can similarly change the order of layers within a model . And you can also change the order of models in the master view.