Operational Guide

This section contains step-by-step instructions for setting up a Protopixel Mapping Tool project, connecting controllers, adding different lighting fixtures, and mapping media content.

Creating a new Lighting Project

Whenever Protopixel Mapping Tool is started, it creates a new (and empty) project. Alternatively, you can create a new project by clicking on the new project icon in the toolbar, or alternatively with Project ‣ New (⌘ -N ).

Navigating the Workspace

As you probably have noticed, items get created in the center of the Workspace. To navigate through it you can right-click and drag, use the trackpad, or use the mouse wheel. To zoom in and out, use the pinch gesture or hold the Ctrl key while scrolling vertically.

Workspace Element Interaction

Workspace elements such as fixtures and content can be selected individually or in groups to perform batch operations. Multiple selection is supported using ⌘ + click or by dragging a selection box across the workspace.

Once selected, elements can be manipulated using a gizmo tool to move, rotate (with ⇧ for 15° increments), and scale them. Their properties are shown in the Inspector panel, and multiple elements can be edited together.

Elements can also be aligned and distributed using alignment tools for horizontal and vertical positioning, based on a selected reference group.

Finally, elements can be copied and duplicated using standard shortcuts (⌘+C / ⌘+V or ⌘+D), with duplicates retaining original properties and being automatically offset and selected.

For further details on this topic please refer to the article available here.

Creating a Fixture

To create a new Fixture, you can click on the Fixture tool in the toolbar, and this will present you with the different Fixture alternatives to be created. Click on the desired fixture type to create it. The new Fixture will appear in the Workspace, selected. Alternatively, you can use Workspace ‣ New Fixture… ‣ Fixture Type.

The Fixture will have a default name derived from its type. You should change its name to be descriptive as it will identify the fixture in other parts of the program. You can do that in the inspector panel.
 

Configuring Fixture Properties

When a fixture is added, an Inspector panel becomes available, allowing you to configure how that fixture behaves and interprets lighting data in Protopixel.

This panel includes basic setup options such as size, shape, and connection type, as well as output controls like on/off state, intensity, DMX/channel mapping, and pixel ordering.

It also provides color processing settings including gamma correction, dithering, white function, and color modes, along with transition timing and naming/grouping options.

Overall, the Inspector panel defines both the physical configuration of the fixture and how it renders incoming lighting content.

For further details on this topic please refer to the article available here.

Custom Ordering

If your specific LED strip profile is not listed in the default options, select "Custom" and proceed to the "Custom Ordering" field.

 For further details on this topic please refer to the article available here.

Configuring a Controller and Fixtures

To configure a Protopixel Controller, first create a controller in the Controllers panel and assign fixtures to its outlets according to the physical installation. If multiple fixtures share an outlet, define their order to match the real-world wiring.

Next, connect the controller to a physical device on the same network. The system automatically detects available devices, and you can pair the controller by selecting the correct one.

This ensures that fixture layout and device communication match the physical lighting setup

For further details on this topic please refer to the article available here.

Adding Content

Once fixtures are mapped in the workspace, content can be created and assigned to them using the Content menu or Workspace → New Content. Some content types can also be added by dragging files directly into the workspace (e.g. images, videos, scripts).

Protopixel includes several built-in content types: Color, Image, Video, Script, Syphon, NDI, and Test. All content types support an Alpha parameter for transparency, and some include additional alignment options.

• Color: Displays a solid color with adjustable tone and temperature
• Image: Imports and displays supported image formats (e.g. PNG, JPG, TIFF)
• Video: Plays and maps video content, with controls for playback, loop, and volume (recommended format: MP4/H.264, ≤1280×720)
• Test: Provides a rotating RGB pattern for quick system verification
• Syphon / NDI: Imports live external content from other applications (local or network-based) for real-time mapping
• Script: Uses Python-based scripting to generate interactive or procedural content, with support for external editing and live reloading

For further details on this topic please refer to the article available here.

Exporting your Project

Protopixel projects come in two formats: a bare project and a bundled project.

A bare project (.ppxproj) is created when saving a project and contains only the essential data needed to run it on the current computer.

A bundled project (.ppxexp) is created when exporting a project and includes all required assets (such as videos and scripts), making it portable across different computers. This format is also required for uploading to Protopixel Brain Experience.

For further details on this topic please refer to the article available here.