Utility For Getting More Out Of 3D and Handling Multiple Holidays on One Layout


One of the most powerful elements in my 2021 Christmas show was whole-display effects. Patterns that wave across the entire layout in different directions in 3D are very engaging, especially in a display like ours where you can get up very close to the lights. Left/right and up/down are quite doable in 2D, but forward and backward in and out of the display need a different 3D camera angle.

In 2021, I only had one song with good 3D effects. Setting the camera angle on each effect takes time, but I was in such a hurry in 2021 and didn’t have much of it. I resolved to make better use of 3D for 2022. But, in the meantime, 3D had shown a significant drawback.

Because my house, like many, has a rectangular foundation shape, and a driveway, sidewalk, and fence that are squared against the street, the 3D view has a lot of stuff that shares the same X coordinate. With the default camera angle, this leads to a lot of effect renders that create streaks that are all the same color from front to back. See the video below, where the streaks are particularly pronounced on the side wall from 0:16-0:28 and again from 1:10 to 1:22.

Must Be Santa – Bob Dylan – Pixel Pro Displays

So, I was faced with a conundrum: Live with the streaks, drop down to 2D and lose the ability to do 3D effects, or do a lot of camera angle tweaking. (UPDATE: xLights will be getting default cameras per group. This should help a lot.)

Another thing that happened was that early in 2022 we decided I wanted to do a Halloween show. I had a lot of time invested in the 2021 Christmas layout, and a lot would be common, but I also didn’t want to delete a lot of stuff that would be used for Christmas 2022. I asked a few people with more experience than I have, and they all said to just make two directories and live with it.

I decided instead to make a script that would solve the 3D problem by rotating the layout so that the 2D camera result was nicer, and to also prune out props that didn’t fit the holiday.

3D Rotation

I applied a 3D transformation to my layout to rotate it 30 degrees around the Y axis. For comparison, here is the preview render of the same song with the rotation applied, which I feel to be marvelously better:

Same sequence, but layout rotated 30 degrees around Y…

Now, I am not mathematically inclined enough to work on the layout in its rotated form. Nor did I manually move and rotate everything… That was done by a python script:

python pyLayout.py

This script can do a few other coordinate transformations also: translate / shift the coordinates by adding an offset, or rotate around the other axes.

This is largely self-explanatory, but here are some other things to note:

  • Rotation around X sounded like a good idea at first, but caused icicles to point upwards sometimes. I did not continue to rotate on Z or X.
  • You do not need to render your sequences all on the same layout. As long as the channel map is the same, which it will be if all you do is rotate the layout, the fseq can be used in your original show directory.

Deleting Props and Inactivating Objects

To solve the case of multiple holidays on one layout, I wanted to delete props and inactivate some of the image objects in the layout. The script provides a way to delete items in one or more groups (or other selection criteria), so I made groups for Halloween- and Christmas-specific items, and then use the script to delete them out of the layout I use for rendering and show purposes:

python pyLayout.py


  • Some arguments must be quoted if entered on the command line.
  • Deleting props from xlights_rgbeffects.xml in this way does cause it to be potentially inconsistent with xlights_newtorks.xml if there were controller connections assigned to the deleted models. This is not a big problem; if you open xLights to the transformed directory and click “Save” on the controller tab it will write a new one. What you don’t want to do is launch xSchedule before doing this, as xSchedule trusts the outdated xlights_networks.xml and sends the wrong channels to the wrong place.

Other Features

The script can also:

  • Set the dimming curves on models (selected by wildcard or group); while setting the gamma to 2.2 manually on the whole display group is possible, this is a good way to automate and not forget.
  • Set the appearance on images (maybe to darken them for nicer preview videos)

Putting It All Together

My final command for Halloween 2022 was:

python LayoutUtils/pyLayout.py
  "--edit=Model=MainMatrix:dimcurveall:-60,2.5;Model=Arch Hedge.*:dimcurveall:-60,2.3"

By line:

  • Sets the input layout
  • Sets the output layout
  • Deletes models from the “OnlyForXmas” and “OnlyForFuture” group
  • Dims down the 3D objects that make up the house and yard
  • Sets dimming curve on all models to a gamma of 2.3, and sets the red down a bit on a 5V tree.
  • Sets the brightness down on the main matrix and large arches.
  • Translates and rotates the whole layout in 3D space

Good Luck

You can feel free to use my script, of course. There is a bit of command-line help in it, but if it gives you any trouble you can reach me by email any address on my domain, or often at AusChristmasLighting.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s