Palgen – Color Palette Generator for grandMA3

Palgen is a grandMA3 plugin that generates color palettes for fixture groups based on classic color harmony schemes (analogous, complementary, triad, etc.). It provides a custom UI to define the base color in HUE/Saturation, optional randomness, the group range, and how the palette is distributed across those groups.

Version: 1.0.0

---

Features

• 6 color harmony modes
  • Analogous
  • Monochromatic
  • Tone
  • Complementary
  • Triad
  • Quad (square)
• Base color in HUE / Saturation
  • HUE: 0–360°
  • Saturation: 0–100%
• Independent randomness controls
  • Random spread around HUE (degrees)
  • Random spread around Saturation (percentage)
• Group range and order
  • Apply the palette to a continuous group range (e.g. 101–109)
  • Option to randomize the group order in which colors are applied
• Custom UI window
  • Floating, movable setup window
  • Faders and numeric fields for all parameters
  • HUE fader label shows angle and a human-readable color name (e.g. HUE 120° Green)
• Macro workflow support
  • Button to save current values into a macro (for recalling Palgen settings)
  • Button to auto-generate helper macros (Generate, per-mode macros, and Setup)
  • Macros are color-coded using Appearances that match the selected HUE/Saturation
• Non-destructive macro/appearance handling
  • Uses the first free macro index and first free appearance index
  • Reuses existing appearances when labels match, instead of creating duplicates

---

Repository Contents

• generate_palette.lua
  Main engine that reads user variables, computes the color palette and applies RGB color values to the selected group range.

• setup_palgen.lua
  Custom UI for configuring Palgen, linking faders to Master Playbacks, and generating macros/appearances. This is the component you normally call as Plugin "Palgen".

• assets/stage.png
  Example of a complementary palette generated by Palgen on stage.

• assets/peramato_palgen.png
  Screenshot of the Palgen UI.

• assets/macros_palgen.png
  Screenshot of the generated macros and their appearances.

---

Requirements

• grandMA3 console or onPC
• A plugin called Palgen with:
  • The main component pointing to setup_palgen.lua (returns PalgenSetupDialog)
  • A secondary component named generate_palette pointing to generate_palette.lua (returns main)

The generated macros call:

• Plugin 'Palgen' – to open the setup UI
• Plugin 'Palgen'.'generate_palette' – to execute the palette generation with the current user variables

---

Installation

Option 1 – Standard installation (recommended)

1. Download the plugin bundle

   • Go to the Releases section of this repository.
   • Download the latest Palgen.zip from the Assets of the release you want to install.

2. Unzip the files

   • Extract Palgen.zip.
   • You should get (at least):
     • Palgen.xml
     • setup_palgen.lua
     • generate_palette.lua
     • (and any other Lua files included in the package, if present).

3. Copy to your grandMA3 plugin folder

   • On your USB drive or local grandMA3 user folder, create the following path if it does not exist:
     • grandMA3/gma3_library/datapools/plugins/Palgen/
   • Copy all extracted files (Palgen.xml and the .lua files) into this Palgen folder.

4. Import the plugin in grandMA3

   • Start grandMA3 (console or onPC) with the USB drive connected (if you are using one).
   • Open the Plugin Pool.
   • Select an empty plugin slot and press Edit.
   • Use Import and select Palgen from the plugin library.
   • Confirm to import the plugin.

5. Verify

   • In the Plugin Pool you should now see a plugin named “Palgen”.
   • Run the plugin to open the setup UI and confirm everything loads without errors.

---

Option 2 – Manual reconstruction from source (advanced)

If you prefer to rebuild the plugin directly inside grandMA3 from the Lua source files, you can do so with the following steps:

1. Copy the Lua files to a location accessible to you

   • From this repository or from Palgen.zip, make sure you have:
     • setup_palgen.lua
     • generate_palette.lua
   • You can keep them on your computer or USB drive just to copy/paste their contents.

2. Create the plugin container

   • In grandMA3, open the Plugin Pool.
   • Select an empty plugin slot and press Edit to create a new plugin.
   • Set the plugin name to: Palgen.

3. Create the first Lua component (setup)

   • In the plugin editor, create the first Lua component.
   • Set its component name to: setup_palgen.
   • Open the editor for this component and paste the full content of setup_palgen.lua.
   • Save/confirm the changes.

4. Create the second Lua component (engine)

   • Create the second Lua component.
   • Set its component name to: generate_palette.
   • Open the editor for this component and paste the full content of generate_palette.lua.
   • Save/confirm the changes.

5. Important: component order

   • The component order must be:
     1. setup_palgen (first component)
     2. generate_palette (second component)
   • Make sure this order is correct in the plugin editor, as the plugin logic depends on it.

6. Save and test

   • Close the plugin editor and return to the Plugin Pool.
   • Run the Palgen plugin to open the setup UI and test that the palette generation works as expected.

---

Master Playback linkage

At the top of setup_palgen.lua you will find four indices:

local HUE_MASTER_INDEX       = 47
local SAT_MASTER_INDEX       = 48
local RAND_HUE_MASTER_INDEX  = 49
local RAND_SAT_MASTER_INDEX  = 50

These indices are mapped to grandMA3 Master Playbacks and are used to drive:

• Base HUE
• Base Saturation
• Random HUE range
• Random Saturation range

You may change these indices to any free Master Playback numbers to avoid conflicts with your show or other plugins. If you set any of these values above 50, Palgen will no longer control a valid Master Playback with that fader (effectively disabling that link and avoiding interference with your show).

---

How Palgen works

Data model (User Variables)

Palgen stores its configuration in grandMA3 User Variables:

• PalGroupIni – First group number in the range (default: 101)
• PalGroupEnd – Last group number in the range (default: 109)
• PalSelectHue – Base HUE in degrees (0–360, default: 0)
• PalRandHueSize – Random spread around HUE in degrees (default: 0)
• PalSelectSat – Base saturation (0–100, default: 100)
• PalRandSatSize – Random spread around saturation (default: 0)
• PalPaletteMode – Palette mode (1=Analogous, 2=Monochromatic, 3=Tone, 4=Complementary, 5=Triad, 6=Quad)
• PalMoveGroups – "true" / "false" string flag to randomize or keep sequential group order

The main plugin (generate_palette.lua) reads these variables, applies a color theory algorithm to generate RGB values, and writes COLORRGB_R, COLORRGB_G, COLORRGB_B attributes for the fixtures in the configured groups.

Group range & validation

• You define a first group and last group.
• Palgen enforces that the last group is at least three numbers higher than the first one (GroupEnd >= GroupIni + 3). If not, it automatically adjusts the last group to meet that condition.
• Internally, it builds a list from PalGroupIni to PalGroupEnd and optionally shuffles this list if random group order is enabled.

Color generation

1. Palgen converts the base HUE into RGB using a custom HUE→RGB function.
2. Saturation is applied as a percentage to each channel via a dedicated saturation function.
3. For each palette mode, the plugin computes new HUE (and/or Saturation) values and converts them to RGB before applying to the current group.

Palette modes

For all modes, the first group always receives the base color (no randomness), and subsequent groups receive variants according to the selected mode.

• Analogous (1)
  Random HUE around the base angle and random Saturation around the base saturation.
• Monochromatic (2)
  Fixed HUE, random Saturation around the base saturation.
• Tone (3)
  Random HUE around the base angle, fixed Saturation.
• Complementary (4)
  Splits the group range in two parts:
  • First half near base HUE
  • Second half near base HUE + 180° (complementary)
• Triad (5)
  Splits the groups into three zones around:
  • Base HUE
  • Base HUE + 120°
  • Base HUE − 120°
• Quad (6)
  Splits the groups into four zones around:
  • Base HUE
  • Base HUE + 90°
  • Base HUE + 180°
  • Base HUE + 270°

Random spreads (PalRandHueSize, PalRandSatSize) are applied using math.random around the base values and clamped to valid ranges (HUE is normalized, Saturation is clamped to 0–100).

---

The Palgen UI

The UI is created by PalgenSetupDialog inside setup_palgen.lua. When you run Plugin "Palgen", it opens a floating, movable window containing:

1. Header

• Title bar with text "Peramato Palgen"
• Close button that simply closes the window.

2. Preview & faders

• HUE fader bound to HUE_MASTER_INDEX (Master Playback)
  • Label shows HUE in degrees and an approximate color name.
• Random HUE fader
• Saturation fader
• Random Saturation fader
• Two gradient preview areas for HUE and Saturation.

Moving these faders updates the corresponding user variables and vice versa. HUE values from the fader are internally mapped from 0–100 to 0–360°.

3. Numeric inputs

Six input lines:

• Color HUE (0–360)
• Color Saturation (0–100)
• Random HUE (0–360)
• Random Saturation (0–100)
• Select First Group
• Select Last Group

All inputs are numeric and validated/clamped in Lua (HUE to 0–360, Saturation to 0–100, groups to safe ranges).

4. Randomize groups & macro buttons

• Checkbox: Randomize groups order
  Toggles whether the groups receive colors sequentially or with randomized order.

• Button: "Create plugin macros"
  Creates the helper macros (see below) plus their appearances.

• Button: "SAVE values to macro"
  Creates a macro that restores the current Palgen settings (user variables) and assigns a color appearance that matches the selected HUE/Saturation.

5. Palette mode buttons

Six buttons in a row:

• Analogous, Monochromatic, Tone, Complementary, Triad, Quad

The selected mode is highlighted with a different background color. Clicking a button updates PalPaletteMode.

6. Generate button

• Button: "GENERATE PALETTE"
  • Saves all current values to user variables.
  • Calls Plugin "Palgen"."generate_palette" to compute and apply the palette.
  • The window stays open so you can iterate quickly.

---

Macros & Appearances

"SAVE values to macro"

Clicking "SAVE values to macro" will:

1. Find the first free macro index in the current DataPool.
2. Generate a set of commands to restore all Palgen user variables, for example:
   • SetUserVar 'PalGroupIni' <value>
   • SetUserVar 'PalGroupEnd' <value>
   • SetUserVar 'PalSelectHue' <value>
   • SetUserVar 'PalRandHueSize' <value>
   • SetUserVar 'PalSelectSat' <value>
   • SetUserVar 'PalRandSatSize' <value>
   • SetUserVar 'PalPaletteMode' <value>
   • SetUserVar 'PalMoveGroups' true/false
3. Store one macro line per command.
4. Label the macro with a generated name:
   "<HueName> <ModeName> <FirstGroup>-<LastGroup> PALGEN"
   (for example, Blue Complementary 101-109 PALGEN).
5. Create or reuse an Appearance based on the selected HUE and Saturation, using label:
   "<HueName> HUE <deg> SAT <sat> PALGEN".
6. Assign that appearance to the macro.

If an appearance with the same label already exists, Palgen will reuse it instead of creating a new one.

"Create plugin macros"

Clicking "Create plugin macros" will:

• Create (or reuse) three solid-color appearances:

  • PALGEN Generate (green)
  • PALGEN Modes (purple)
  • PALGEN Setup (magenta)

• Then create a sequence of macros in free slots:

  1. Generate Palette PALGEN
     • Command: Plugin 'Palgen'.'generate_palette'
     • Appearance: PALGEN Generate
  2. Analogous PALGEN
     • Commands:
       SetUserVar 'PalPaletteMode' 1
Plugin 'Palgen'.'generate_palette'
  3. Monochromatic PALGEN
     • Mode 2 + run plugin
  4. Tone PALGEN
     • Mode 3 + run plugin
  5. Complementary PALGEN
     • Mode 4 + run plugin
  6. Triad PALGEN
     • Mode 5 + run plugin
  7. Quad PALGEN
     • Mode 6 + run plugin
  8. Setup PALGEN
     • Command: Plugin 'Palgen'
     • Appearance: PALGEN Setup

Each macro is assigned the corresponding appearance. Existing macros are not overwritten; Palgen searches for empty indices.

---

Typical workflow

1. Prepare groups
   Create groups for your fixtures (e.g. 101–109) and make sure they contain fixtures with COLORRGB_* attributes.

2. Open Palgen

   • Run Plugin "Palgen" from the command line or Plugin pool.
   • Optionally click "Create plugin macros" once and then use the generated macros instead.

3. Configure the palette

   • Set the first and last group numbers.
   • Use the HUE and Saturation controls (faders or numeric input).
   • Define random HUE and random Saturation if needed.
   • Choose whether to randomize the group order.
   • Select one of the 6 palette modes.

4. Generate

   • Click "GENERATE PALETTE" or use one of the mode macros (e.g. Complementary PALGEN).
   • The plugin clears the selection, selects each group in turn and applies the computed RGB color.

5. Store your setup

   • Click "SAVE values to macro" to store your current settings as a macro for later recall.

---

License

This project is released under the MIT License. See the LICENSE file for details.