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.

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.

Model Setup:

• Define most of the parameters the way you would for the existing moving head 3D model

• Use the "Orient to Zero" parameters to get the pan/tilt positions in layout to make the head look like it does when its commanded to 0 which is usually the bootup position.

• We want to define a Common starting position with the head point Up and facing Forward. All commands will be relative to that starting position I call the "Home" position. So we have a Zero position and a Home position.

• You define the Zero position by viewing the layout and you define the Home position by creating a blank sequence and dropping a Moving Head Effect on the head. Click the center of the position grid so that it will latch a Pan=0 Tilt=0 command into the heads settings. If the head is not pointing Up and Forward then you need to adjust the degrees in the Orient Forward and Orient Up parameters for the pan/tilt motors. Just change the settings and come back and click on the effect to see it change. If you use an old school effect to position the head you should see how it points to the Zero position when commanded to Zero whereas the Moving Head Effect should apply the Home position offset.

Parameters:

• Fixture: You need to set the fixture position for each head MH1 through MH8. This teaches xLights where each head is positioned so that when you tell it to do a Fan it know how to space out the heads. You can assign more than one head to a position if desired.

• PanMotor: Channel (Coarse): Required.....define the main pan channel Channel (Fine): For 16 bit heads. The Fine channel is optional and can be set to 0 to disable. Min Limit (deg): Limit how many degrees the head will pan to the left starting from facing forward Max Limit (deg): Limit how many degrees the head will pan to the right starting from facing forward Range of Motion: How many total degrees does the head pan when commanded from 0 to 255 Orient to Zero: Number of degrees to spin the head so it matches the position when commanded to 0 Orient Forward: Number of degrees to spin the head from its Zero position so it faces forward Slew Limit (deg/sec): Number of degrees your head can move per second to try to make the screen match reality Reverse: Check this box if your head moves counter-clockwise when commanded from 0 to 255 Upside Down: Check this box if you head is mounted inverted

• TiltMotor: Channel (Coarse): Required.....define the main tilt channel Channel (Fine): For 16 bit heads. The Fine channel is optional and can be set to 0 to disable. Min Limit (deg): Limit how many degrees the head will tilt backwards from facing up Max Limit (deg): Limit how many degrees the head will tilt forwards from facing up Range of Motion: How many total degrees does the head tilt when commanded from 0 to 255 Orient to Zero: Number of degrees to spin the head so it matches the position when commanded to 0 Orient Up: Number of degrees to spin the head from its Zero position so it faces up Slew Limit (deg/sec): Number of degrees your head can move per second to try to make the screen match reality Reverse: Check this box if your head moves counter-clockwise when commanded from 0 to 255 Upside Down: Check this box if you head is mounted inverted

• Most other properties are similar to the previous moving heads

• BaseMesh, YokeMesh, HeadMesh: These can be used to change the OBJ objects used to draw the head.

Custom Model Creation

xLights 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 by selecting the Create new Custom Model icon. Select an area on the Layout screen and drag the mouse across. Note that there won't be anything displayed in the box as the custom model layout has not yet been defined. A new Custom Model will be created with an initial model name of ‘Custom’ or similar. You can rename it to something more suitable. Click within the Model Data box to enter the Custom Model setup window.

A custom model grid will be displayed in which you enter numbers in the grid representing the nodes/channels in your model.

Change the width and height values to increase the size of the grid to fit the layout.

The Right Click Menu Allows you to Flip, Rotate, Compress, Trim Unusued Space, and Shrink Space.

For example, to model a custom 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. This is shown below.

Click on the Wiring View Button to open a window which will display the nodes and wires as they would be installed in the actual model, based on the layout entered in the grid. Note that the wiring view is shown from the reverse view (back side of the model) below. This is the view as if the pixels are being pushed in from the backside. Right clicking on the wiring view will provide options for changing the background color, font side, and viewing from the front or backside, as well as a few others.

The Right Click on the Custom Menu grid gives options to Flip, Rotate, Compress, Trim Unusued Space, and Shrink Space.

Click on the Horizontal Flip or Vertical Flip buttons to shift the nodes in the grid horizontally or vertically, which will also change the output of the Wiring View if selected.

The following image is an example of a Singing Face custom model on a 50 by 50 grid.

To erase a number in a cell, selected the cell and press the Delete key.

You can delete multiple cells by drawing a box around them and then pressing Delete.

You can use the ‘+’ and ‘-‘ keys to make zoom in and out, respectively.

Click OK to save the model.

Custom Model Creation Using A Background Image

From the Layout screen, click on the custom model icon and drag and draw a custom model, as described above. Click on the ... button at the far right of the Background Image Row. A window will open to prompt for the location of an image file. Browse to and select the image.

Alternatively, open the Model Data window to open the Custom Model Window and select the file using the Browse button.

Click on the Model Data attribute. This will open up a window with the image in the background which will fill the grid size. Adjust the size of the grid by increasing the width and height values. Click on the ‘+’ and ‘-’ buttons to Zoom in and out of the grid.

The Background image slider can be used to adjust the brightness of the background so that the image is just visible. This will enable you to more easily see the numbers on the image and around the outline. Slide to the left for 100% brightness and to the right for 0% brightness. The magnifying glass at the right side of the slider will toggle the image on and off.

You can then start typing the numbers in the positions that the pixels would be located. In this example, it would be around the edges of the snowman and hat.

To erase a number in a cell, selected the cell and press the Delete key.

You can delete multiple cells by drawing a box around them and then pressing Delete.

If you select the Auto Numbering setting to be active, the channel number that is shown in the Channel number box will be added at any cells selected.

If the Auto Increment setting is set to be active, then after each selection, the number is automatically incremented. This is typically the case for smart strings of pixels.

Click on OK to return to the layout screen at any time to view the Custom Model that has been created.

To edit the custom model, select the Model Data the same as was done with the initial setup. This can be done at any time to edit the model.

Export Custom Model

A custom model can be exported so that it can be shared with others, used in different layout, or for adding additional copies of the model to this layout.

To export a Custom Model, select the model and right click. Select Export xLights Model.

You will be prompted to specify a location and filename. Enter the filename click on Save. Note that the xLights custom models use a ".xmodel" file extension.

The export process includes the faces and state definitions, as well as custom models, so these don’t need to be redefined when imported.

Import Custom Model

This function enables you to create a custom model from a previously exported custom model file (xmodel). This can be previously created by you or shared from another user or vendor.

Click on the ‘Create new Custom model’ icon and then click on the canvas where the new custom model is to be located. You will be prompted for the name and location of the custom model file (xmodel) to import.

Select the file name and a model will be created using information from the custom model file. The model name or other attributes can be edited as needed.

The model will be located at the point selected, and can be resized or moved using the blue connectors similar to any other model.

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.

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.

Image Model

The Image Model is used to represent single channel props like blow-molds, inflatables or incandescent cutouts/wire-frames. You load a picture of the prop and xLights will illuminate the picture based on the channel value. The Off brightness can be set to a value above zero(10% in the example) so it is still visible in the layout when the channel is off. This Model only works with Single Channel or Single Channel Intensity string types not RGB lights or pixels.

Icicles Model

The # of Strings would normally be 1.

The Lights per String represents the physical number of light nodes, bulbs or pixels.

You can drag the green or top blue pixel to hang the icicles at an angle and then drag the lower blue pixel to cause the drop to sheer and hand vertically shear.

The drop pattern indicates how the pixels are arranged on each drop and how many.

So, if the total lights on the string is 80 and the drop pattern is 3,4,5,4, this indicates that the first drop has 3 nodes, the next 4 , then 5 then 4.

This pattern is then repeated until 80 nodes have been accounted for.

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

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.

Layout

The layout tab displays a full preview of your show and provides a view of how all the models will appear. In addition you can :

• Define new Models or change existing Model definitions.

• Define new Model Groups or change existing Model Group definitions.

• Select which Models, or Model Groups are be displayed on the Layout.

• Select and adjust the layout background.

• Specify, position and adjust the model size, orientation and location on the layout.

• Check whether any models have overlapping channels.

• Review or change the detailed characteristics of a model’s attributes

• Create Additional Preview layout windows

• Assign Models to one or more Preview Layouts

• Assign Models to Specific Controller Connection

• Assign the Model Start Channels

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

Matrix Model

The direction can be defined as horizontal (the most common) or vertical. The ‘# Strings’ refers to the number of controller connections of the matrix. The Nodes/String refers to the number of nodes in each string. The 'Strands/String' is the number of 'rows' or zigzags per string. With AC lights ‘# Strings’ is the number of channels the Lights/string is the lights per string.

The starting location indicates where the matrix is connected to the controller (or where channel 1 of the matrix is).

Above is an example of a horizontal matrix with 16 rows and 50 pixels per row.

If the Strands/String is set to '2' it will add a zigzag and there will be 32 rows with 25 pixels per row.

Alternate Nodes will "hop" every other node down and back to have the string start and stop at the same location.

DMX model

The DMX model has a number of different styles and each has a different model representation.

After selecting the DMX Mode, a list of Sub Types will display.

General

Used to define any generic DMX Fixture. Can be used for 3/4 Channel RGBW lights or devices like Fog or smoke machines.

Floodlight/ Area Flood

Used for multichannel Flood lights. The Single Line Model can all be used for DMX Floodlights.

Moving Head/ Moving Head 3D

For DMX Moving Heads. Supports Shutter control, RGBW channels, Color Wheel, etc.

Servo

Induvial Servo Control, Supports 16 bit servos.

Skull

For Skulls with servos embedded in them. Skulltronix Skulls are also supported.

PolyLine Model

The Poly Line model enables several straight line or curved segments to be drawn as one model (rather than having to draw them as individual models).

This model is useful for the roof line, rafters, fences, etc where the lines are at an angle to each other.

To draw, select this model and drag on the layout as usual. At the end of each segment, click once with the mouse left button, then draw another segment. Left mouse button Click to end the segment.

At the end press the ESC key (after the Click) to deselect the drawing action. You can then grab any of the blue or green pixels and move it around to change the shape of the model image.

The # of Nodes defines the total number of nodes for the entire model, the Lights/Node is normally one and the Starting location can be the Green Square(Left) or Blue Square(Right).

Strings is the number of physical connections i.e ports to the controller.

The drop pattern allows the polyline to be used as icicles, this indicates how the pixels are arranged on each drop and how many.

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

Enabling the Individual Segments attribute selecting will present the different segments that form the poly line model.

You may end up with some in-between lines you don't want. So then check Indiv Segments and start clicking on each segment line in the property grid. It will highlight each segment as you click on them. Once you get to one of the "in-between" lines you don't want just type in a "0" for segment size and it will disappear from the drawing

You can change the number of nodes in each segment.

You can also name all your line segments.

Adding Segments

To add a segment to an existing model, right click on a segment of the poly line model; the segment color will change to red.

Then select Add Point and a point will be added to the segment. The number of segments will increase by one. You can then work with the new segment and change the number of nodes via the panel.

Segment Curves

If you Right click on a segment, the segment color will change to red.

You can then modify the straight line segment into a curved segment by selecting Define Curve. Grab one edge of the segment and drag it in the direction that you want the line to curve. Then select the other end of the segment and drag it in the direction you want to form a curve. Note the pink dots that denote the end of the curve that you are working with.

Click on the curved line and two straight red bars will be displayed from either end. You can then grab the end of the bar and drag it in any direction to stretch or move the curve.

Star Model

The # Strings is normally set to 1 and the Lights/String denotes the total number of nodes on the model. The # of Points describes the points of the star and the startling location indicates where the first node is and which direction it progressive.

Starting Location is where the string start location is set to begin.

Outer to Inner Ratio describes the "wideness" of star points.

The Layers attribute value describe the concentric layers in the star. 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.

Single Line Model

The ‘# Strings’ is almost always set to 1 .

The Nodes / String indicates how many nodes the string has and the Starting Location indicates whether it runs from left to right or vice versa.

In this example, the single strand model has ten nodes and starts at channel 7240. It runs from left to right.

In the case if you have a vertical setup , then the first channel should match the node connected to the controller or end of the previous model.

Accordingly change the orientation of the model to match that. You can however, reverse the orientation in many hardware controllers as well.

Spinner Model

The number of Strings is normally set to 1.

The Arms/String represents the number of Spokes and the Lights/Arm represents the number of nodes on each arm.

The Hollow % is used to control the gap at the base (ie center) of the spinner model.

The Arc can be used to denote whether the model is a 360 degrees spinner or say a 180 (sem circular spinner) or anything in between.

The Starting Location, besides indicating which is the first channel of the model, is also used to denote how it is wired. There are 6 definitions supported (wired from the center, wired from the outside, alternate first/last node and for either whether the nodes move clockwise or counterclockwise ).

When wired from the centre, the starting location must be as indicated with the red rectangle and the pixel direction is outwards on all arms.

When wired at the edge, the starting location must be as indicated with the green rectangle and the pixel direction is inwards on all arms.

The zig zag attribute is to be selected if the wiring is say - inwards on one arm and then outwards on the next and then inwards etc or outwards on one arm and then inwards on the next and then outwards etc.

Sphere Model

Tree Model

Type

The type of tree can either be Round, Flat, or Ribbon. A Round Tree is "classic" tree with a round style base. A Flat Tree will have a flat base and is intended for trees against a wall. A Ribbon Tree is the same as a flat tree but the top is tapered to a single point. Flat and Ribbon Tree are always 180 degrees.

Degrees

The Degrees attribute indicates whether the tree is a full (360), half (180) or three quarters (270) tree or any other value. This property is only available for Round Trees.

#/Strings

The # 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. 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 of lights. A 8 string tree with 100 Nodes per String would have 800 total lights.

Strands/String

The Strands per String represents the number of "folds" in each string of lights. If the string of lights will go up once and terminate, the Strands per String is 1. If the string will go up once and return to the bottom the Strands per String is 2.

Spiral Wraps

The Spiral Wraps attribute defines many times a strand is wrapped around the tree. 1.0=one full wrap, 2.5 = 2 1/2 wraps from bottom to top. For spiral tree the # of Strings can be set to 1 and then this can be used to "Spiral Wrap" the tree.

Bottom/Top Ratio

The Bottom/Top Ratio determines the angle of the tree strands. A ratio of 6 will have a bottom 6 times larger than the top. A ratio of 1 will create a straight vertical cylinder. This can be used to adjust the cone shape of the tree.

Starting Location

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

In this example, a 360 degree Mega Tree visually has 15 strings of 50 pixels on each string, with 2 Strands per String. This will "fold" the strings once causing the tree to be 30 strands wide and have strands of 25 pixels long.

Each string starts from the bottom, goes up to the top of the tree and loops back down. So half the number of physical strings are required.

The first node is in the front bottom left and starts from channel address 9200.

Wreath Model

The # Strings is the physical number of strings connected to the controller. Nodes/String is the nodes/pixels per light string.

Model Groups

A Model Group defines a collection of models. It is an optional entity, but very useful, in that many effects can be sequenced against the Model Group and xLights will then generate effects on all the Models in the group.

A Model can belong to more than one Model Group. An an example a model ‘Arch1’ can belong to the ‘All Models Group’ Model group as well as the ‘Arches Group’

You can also have models that do not belong to a Model Group - for example a matrix that you wish to sequence effects on separately such that dropping an effect on the” All Models” group does not affect the matrix.

Add Group

To create a Model Group, from the layout tab right click within the Model list window. Click on Add Group, enter a Model Group name in the resultant window and click Ok.

In the layout windows, a Model Group can be added by highlight multiple models, right click, and select 'Create Group'.

In xLights, Model Groups are sequenced against an internal grid representation.

The Default Layout Mode and Max Grid Size provides options on how the ‘internal grid’ is to be calculated when effects run across a model group.

If ‘Grid as per preview’ is selected , then the buffer used will be exactly as to how the the house preview appears i.e will be quite large.

If ‘Minimal Grid’ is selected then the buffer area will be an area just surrounding the model group.

Modify Group

To modify the models that form part of a group, click on the group name.

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

Delete Group

To remove a Model Group, select the Model Group from the model list, right click and select Delete Group. This will not change or remove any of the underlying models, however any effects that have been placed at that 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.

Rename Group

To rename a Model Group, select the Model Group from the same list , right click and select Rename Group. Enter the new name for the Model Group. 'Clone Group' will create a copy of the current group with the same models. 'Delete Empty Groups' will delete Model Group with containing no models.

Clone Group

Create a copy or clone of the currently selected group.

Delete Empty Groups

Delete any model group that is empty and contains no models or groups.

Layout Previews

You can select which models you wish to see on your Layout Preview. This is done by first selecting the Preview that you want to be active from the Preview selection window.

There are three built in preview options: ‘Default’, ‘All Models’ and ‘Unassigned’. You also have the ability to create new preview windows.

Default

If you only plan on having one preview, which is what most people will have, then this is the one to use.

Select the default ‘Default’ preview which will then display the models where either:

• The Preview attribute against the model definition has been set to ‘Default’.

• The Model is part of a Model Group where the Preview attribute has been set to ‘Default’.

Download/Import Models

Import Model

After Selecting the Import Model Button, You must click on the layout preview and drag out a box and release, to represent the imported model location.

Then select the local .xmodel file with the File Select Window

The imported model will be the same model type it was exported as. If the .xmodel file contains a custom Model, the imported model will also be a custom model.

Download Model

After Selecting the Download Model button, You must click and drag out a box and release on the layout screen to represent the downloaded model location.

The Model Dialog will appear where you can select the desired model you would like to insert.

Click Insert and Model will be added to your layout.

Moving Objects Around

For a single object, you can left click on the object, (it turns yellow) and with the mouse button still held down, drag it around.

To move more than one object around together, press the Control key first and then left click on each object that you want to move as a group (holding down the control key all the time).

Then at the last object, drag to move all the selected objects around together. If you release the Control key at any time, the objects will not move as a group.

Another way is to Hold down shift, draw a box around the models to move, then let go of shift, and hold down alt, then move the group of models.

Aligning Objects

Select a group of objects, right click and select Align (top, bottom etc) to align the selected objects. Which object should they all align to ?

The object you selected first i.e. which will have the blue dots is the key object that others will align to.

When selecting a group, you can press shift, a box opens and you can drag the mouse around the objects to select the group to align.

Editing Preview Layouts

The Preview Window displays the available preview windows, enables you to select a different view and also enables you to create additional Preview Layout windows. To create a new Preview Layout, select the <Create New Preview> option from the window.

Enter the name for the Preview Layout and click Ok.

The new preview window will be created and the image that has been used for the default Preview will be selected.

Click on the Background Image attributes to browse for and select a different image if required. Otherwise, adjust the fill attribute value and the brightness value.

The image size has to be the same as the default image and as such, it is not available to change. Click on the Save button to save it.

The preview window can now be used to create Models or Model Groups against similar to the Default Preview layout. Models can be reassigned to the different Preview by changing the "Preview" Model Setting.

If you wish to delete the preview , right click within the window and click on the ‘Delete this Preview’ option.

When a Preview is Deleted, All the Models currently assigned to it will become unassigned and need to be reassigned to another preview.

When an additional Preview is created, a ‘Previews’ option to select and open it on your sequencer will be available on the View menu. Click on the preview name to open the Preview window. This option is not available if only the Default preview exists.

Window Frame Model

This model is used to represent window frames and door outlines. The # Lights Top is the number of light across the top of the window frame. The # Lights Left/Right is the number of lights per side. xLight will assume the sides are the same length and use this number for both sides. The # Lights Bottom is the number of light across the bottom. This can be set to zero for Door Frames. Direction specified the wiring direction. Starting Location is the location of the first node.

2D Background Image

The Background image to the layout section i.e your house/yard can be set or changed via the Background Image setting section.

Click where indicated and browse to and select the background image. Change the file type if required.

Adjust the width, height and brightness attributes to your preference. The width and height depends on your screen size and resolution. If unsure, start with a .jpg or .bmp image with a resolution of around 1100 * 500 and adjust the width and height for the best fit. The ‘fill’ attribute will scale the image to best fit your window. Click on the Save button to save the Layout settings.

3D Objects

Mesh

In 3D Mode, Meshes/Renders of your house or other object can be added to the Layout. OBJ file type is currently supported. OBJ files normally require a MTL Materials files that also must be put next to the OBJ file. It is recommended to put both files in your show folder and also remove any spaces from the file name.

Click Add OBJ button and Select the Mesh dropdown.

Click the Ellipsis(three dots) Button to select a OBJ file.

Once selected, the OBJ will be displayed in xLights.

Grid

In 3D Mode, Grids can be added to help align models. The grids can be rotated and moved to the desired location.

Pictures

In 3D Mode, Multiple Pictures can be added to the Layout. Images can be placed on the ground and also used as the house backdrop.

Click the Ellipsis(three dots) Button to select a image file.

The file name will appear after a image is selected.

Node Range SubModels

This setting allows the user to specify parts of a model to be controlled as if it were its own model. For example, you could defined the horizontal and vertical section of a windows frame.

Click Add to create a new submodel. Then add the nodes that will be included in the submodel. On the right side you will see the model and selected nodes will be highlighted.

On the right side, the model will be displayed with the selected nodes highlighted. If the user clicks the row header(Top or Bottom), the display will highlight only the nodes in the selected row. If the user clicks the "Node Ranges" column header, all the nodes from all the rows will be highlighted.

The Node Ranges 'Grid' represents the submodels render buffer. A grid five row high with five nodes listed per row will create a 5x5 Render buffer.

Empty Commas(,) can be used to create empty spaces in the render buffer. The example below will create 5x5 a outline with a 3x3 'hole' in the middle.

To graphically select the nodes, double click the row header or row cell and select the desired nodes. This option will only populate one row at a time.

Draw Model

To Draw a model, like a Cross, across the whole model click the Draw Model Button.

Click and drag to select nodes(blue highlight). The selected node will turn grey once selected. Double clicking on a node number also toggles between selected and not selected. 'Select All' will select all the nodes. 'Select None' will deselect all the nodes. The 'Ordered Selection' checkbox enables a single select mode that disables 'Click and Drag'(blue highlight) Mode. 'Ordered Selection' is used to select the individual nodes in a specific order to be used by the underlying buffer.

The "From Model" button allows the user to select nodes based on the custom model "shape". For Example, you can import a snowflake model file to overlay it on a matrix.

Hold the 'Ctrl'/'Cmd' Key highlight the cells and press Ctrl+C to copy them. Ctrl+V can then be used to paste the cells. This data can also be copied to and from Excel.

Click Ok to Close the select window.

SubBuffer SubModel

The SubBuffer tab allows the user to select sections of the buffer instead of the nodes. This can be used to divide mega trees/matrices into slices for singing face or individual effects.

Click The Action Button and Select Generate Slices to automatically generate different size slices.

Vertical Slices will create 'count' number of vertical slices that are equal size.

Delete

Delete the currently selected submodel(s).

Copy

Copy the currently selected submodel.

Action

Generate Slices

Select Generate Slices to automatically generate Subbuffer style Submodels.

Flip All SubModels Vertical

This will flip all the node number rows, top to bottom, bottom to top.

Flip All SubModels Horizontial

This will flip all the node number row values, left to right, right to left.

Shift All Nodes in All SubModels

This will Shift all the submodels nodes numbering 1->21, 100->120

Reverse All Nodes in All SubModels

This will reverse all the submodels nodes numbering. 1->100, 100->1.

Import

Import SubModels from Model

This allows the user to 'copy' submodels from another similar model. Example, if multiple mini-trees, are defined in your layout, only create the sub-models on one tree and then use this option to import the sub-models on all the other trees.

Import SubModels from File

This allows the user to 'copy' submodels from a XModel file.

Import Custom Model Overlay

This option will use a custom model file(.xmodel) to create submodels based on X/Y location of the node locations. The height and width of the custom model file must be smaller than the matrix height and width. This will also import the singing face and model state defines.

Export

Export SubModels as CSV

This exports all the submodel definitions as a CSV file for viewer with Excel or other spreadsheet software.

Export SubModel as xModel

This generates a Custom Model xModel file of the currently selected submodel.