FixtureForge User Manual

The complete guide to creating, editing, and managing professional GDTF and grandMA3 fixture files with FixtureForge.

What is FixtureForge?

FixtureForge is a professional desktop application for creating and editing lighting fixture definition files used in the entertainment industry. It supports two major formats:

• GDTF (General Device Type Format) - The open standard for describing lighting fixtures, supported by major lighting consoles and visualizers.
• grandMA3 Library - The proprietary format used by MA Lighting's grandMA3 console series.

Whether you're a lighting designer needing to create custom fixtures, a manufacturer building official fixture profiles, or a programmer maintaining a fixture library, FixtureForge provides all the tools you need in one powerful application.

Installation

System Requirements

Installation Steps

First Steps

Welcome Dashboard

When you launch FixtureForge, you'll be greeted by the Welcome Dashboard. This is your starting point for all operations:

The Welcome Dashboard - Your gateway to all FixtureForge features

Creating Your First Fixture

Interface Overview

FixtureForge features a modern, dark-themed interface designed for professional use. The main editor view is divided into several key areas:

Main Editor Layout

Navigation

Use the sidebar tabs to navigate between different sections of the fixture editor:

• General - Basic fixture information and metadata
• Geometry - Physical structure and 3D models
• DMX Modes - Channel definitions and modes
• Wheels - Color wheels, gobo wheels, and animation wheels
• Physical - Physical properties, emitters, and connectors

What is GDTF?

GDTF (General Device Type Format) is an open file format for describing lighting fixtures and related devices. It was created by the GDTF Group, a consortium including MA Lighting, Robe, and Vectorworks.

Why GDTF?

• Universal Compatibility - Supported by major consoles (grandMA3, Hog4, Eos, etc.) and visualizers (Vectorworks, Capture, WYSIWYG, etc.)
• Complete Description - Includes DMX definition, physical properties, 3D models, and images in one file
• Open Standard - Free to use and implement, with publicly available specifications
• Manufacturer Support - Official files available from fixture manufacturers

GDTF vs Traditional Fixture Libraries

GDTF File Structure

A GDTF file (.gdtf) is actually a ZIP archive with a specific structure. Understanding this structure helps when troubleshooting or manually editing files.

File Naming Convention

<Manufacturer>@<FixtureName>@<OptionalComment>.gdtf

Examples:
Robe@Robin_600@v2.gdtf
Ayrton@Ghibli@Standard.gdtf
Clay_Paky@Sharpy_Plus.gdtf

Archive Contents

fixture.gdtf (ZIP archive)
├── description.xml          # REQUIRED - Main fixture definition
├── thumbnail.png            # Optional - Fixture thumbnail (max 1024×1024)
├── thumbnail.svg            # Optional - Vector thumbnail
├── wheels/                  # Wheel slot images
│   ├── gobo1_slot1.png
│   ├── gobo1_slot2.png
│   └── ...
└── models/                  # 3D models
    ├── gltf/               # Primary format (glTF/GLB)
    │   ├── base.glb
    │   ├── yoke.glb
    │   └── head.glb
    ├── 3ds/                # Legacy 3DS format
    └── svg/                # 2D representations

Key Components

description.xml

The heart of the GDTF file, containing all fixture metadata, DMX definitions, geometry structure, and references to media files.

3D Models

FixtureForge supports glTF/GLB format (recommended) and legacy 3DS format. Models should be exported with proper origins and orientations.

Wheel Images

PNG images for gobo slots, color wheels, etc. Recommended size is 256×256 pixels with transparency.

XML Specification

The description.xml file follows a specific schema defined by the GDTF specification. Here's an overview of the main elements:

Root Structure

<?xml version="1.0" encoding="UTF-8"?>
<GDTF DataVersion="1.2">
    <FixtureType
        Name="MyFixture"
        Manufacturer="MyCompany"
        FixtureTypeID="12345678-1234-1234-1234-123456789ABC">

        <AttributeDefinitions>...</AttributeDefinitions>
        <Wheels>...</Wheels>
        <PhysicalDescriptions>...</PhysicalDescriptions>
        <Models>...</Models>
        <Geometries>...</Geometries>
        <DMXModes>...</DMXModes>
        <Revisions>...</Revisions>

    </FixtureType>
</GDTF>

Main Sections

Data Types

General Information

The General tab contains the basic fixture metadata. These fields identify your fixture in lighting consoles and libraries.

General tab showing fixture metadata, thumbnail, and identifiers

Required Fields

Optional Fields

Geometries

Geometries define the physical structure of your fixture. They form a hierarchical tree that represents how different parts of the fixture relate to each other (e.g., a head that moves on a yoke that sits on a base).

Geometry editor with 3D visualization and axis controls

Geometry Tree

The geometry tree shows the parent-child relationships between fixture parts. Each geometry can have a position (4×4 transformation matrix), an optional 3D model, and type-specific properties.

Base (Geometry)
├── Yoke (Axis - Pan)
│   └── Head (Axis - Tilt)
│       ├── Lens (Beam)
│       ├── ColorWheel (FilterColor)
│       └── GoboWheel (FilterGobo)
└── PowerConnector (WiringObject)

Geometry Types

GDTF supports 18 different geometry types:

Adding a Geometry

DMX Modes

DMX Modes define how the fixture responds to DMX data. A fixture can have multiple modes with different channel counts and configurations.

DMX Modes editor showing channels, functions, and 16-bit configuration

Mode Structure

DMX Mode "Standard"
├── DMX Channel 1: Dimmer (8-bit)
├── DMX Channel 2: Pan (8-bit)
├── DMX Channel 3: Pan Fine (16-bit fine)
├── DMX Channel 4: Tilt (8-bit)
├── DMX Channel 5: Tilt Fine (16-bit fine)
├── DMX Channel 6: Color Wheel
│   ├── Function: Open (0-10)
│   ├── Function: Red (11-20)
│   ├── Function: Blue (21-30)
│   └── ...
└── DMX Channel 7: Gobo

Creating a DMX Mode

Channel Properties

Channel Functions

Channel functions define what happens at different DMX ranges:

Wheels & Gobos

Wheels define rotating elements in your fixture like color wheels, gobo wheels, prisms, and animation wheels.

Wheels editor with visual gobo wheel representation and slot properties

Wheel Types

• Color Wheel - Fixed color filters
• Gobo Wheel - Static or rotating gobos
• Prism - Beam multiplication optics
• Animation Wheel - Rotating effects (fire, water, etc.)

Creating a Wheel

Slot Properties

Importing Gobo Images

For gobo wheels, you can import images to visualize each slot:

• Format: PNG with transparency (alpha channel)
• Size: 256×256 pixels recommended
• Color: White on transparent background for best visualization

Physical Properties

Physical properties describe the real-world characteristics of your fixture including weight, power consumption, and optical properties.

Physical properties including weight, power, and operating temperature

Physical Descriptions

Emitters

Define the light sources in your fixture:

• Name - Emitter identifier
• Color - CIE color temperature or RGB values
• Dominant Wavelength - For LED sources (nm)
• Luminous Flux - Light output (lumens)

Connectors

Define electrical and data connections:

• Type - Connector type (PowerCon, XLR5, RJ45, etc.)
• Gender - Input or Output
• DMX Break - For multi-universe fixtures

Filters

Define optical filters with their color modification properties:

• Name - Filter identifier
• Color - CIE color modification

3D Viewer

The integrated 3D viewer allows you to visualize your fixture's geometry in real-time. It displays the hierarchical structure and helps verify positions and orientations.

Navigation Controls

3D Model Import

FixtureForge supports the following 3D formats:

• glTF/GLB - Recommended format, best compatibility
• 3DS - Legacy support

Model Guidelines

• Export with Y-up coordinate system
• Center the model on its rotation axis
• Use meters as the unit (1 unit = 1 meter)
• Optimize polygon count for performance
• Include materials and textures as needed

grandMA3 Support

FixtureForge provides comprehensive support for grandMA3 fixture files, allowing you to edit existing fixtures and convert between MA3 and GDTF formats.

MA3 Fixture Editor showing Robe Robin Pointe configuration

MA3 vs GDTF

Opening MA3 Files

FixtureForge can directly open grandMA3 fixture files. The file format uses a binary header followed by XML data.

grandMA3 Library Browser

FixtureForge includes the complete grandMA3 fixture library with over 31,000 fixtures from 586 manufacturers.

grandMA3 Library Browser with search and manufacturer filtering

Browsing Robe Lighting fixtures (693 fixtures available)

Features

• 31,151 fixtures from 586 manufacturers
• Real-time search with instant filtering
• Manufacturer filter for quick navigation
• Preview details before opening
• Direct opening in GDTF or MA3 editor

Using the Library

Format Conversion

FixtureForge can convert fixtures between GDTF and grandMA3 formats in both directions.

MA3 → GDTF Conversion

When converting from MA3 to GDTF:

• ✅ All DMX data is preserved
• ✅ Channel functions and sets are converted
• ✅ Basic geometry is created
• ⚠️ No 3D models (MA3 doesn't include them)
• ⚠️ No wheel images (MA3 doesn't include them)

GDTF → MA3 Conversion

When converting from GDTF to MA3:

• ✅ DMX data is preserved
• ✅ Attributes are mapped to MA equivalents
• ⚠️ 3D models are NOT included (MA3 format limitation)
• ⚠️ Wheel images are NOT included (MA3 format limitation)
• ⚠️ Complex geometry hierarchy is simplified

Attribute Mapping

FixtureForge automatically maps between GDTF and MA3 attributes:

Fixture Finder

The Fixture Finder helps you locate fixtures in the library by building a DMX channel sequence. This is useful when you know how a fixture's channels are laid out but don't know the fixture name.

Fixture Finder - Search by DMX attribute sequence with 100 results found

How It Works

Search Modes

• Strict - Exact match of your sequence
• Flexible - Allows some variation in order
• Partial - Matches fixtures containing your sequence

Batch Converter

The Batch Converter allows you to convert multiple fixtures at once between GDTF and MA3 formats.

Fixture Converter with bidirectional GDTF ↔ MA3 conversion

Features

• Convert entire folders of fixtures
• Bidirectional: GDTF ↔ MA3
• Progress tracking with detailed logs
• Skip or overwrite existing files
• Organize output by manufacturer

Using the Batch Converter

Options

GDTF Share Integration

GDTF Share is the official cloud library for GDTF fixture files. FixtureForge integrates directly with this service.

GDTF Share login screen - Connect to the official cloud library

GDTF Share browser with fixture details, version info, and ratings

Features

• Browse 923+ manufacturers
• Search thousands of fixtures
• View community ratings and reviews
• One-click download and import
• Access revision history

Connecting to GDTF Share

GDTF Share access works with or without an account:

• Without account - Browse and download public fixtures
• With account - Access additional features, upload your own fixtures

General Settings

Access settings through the gear icon in the top-right corner or press Ctrl + ,.

Settings panel with language, units, and version information

General Options

Themes

FixtureForge includes multiple premium themes to customize your workspace.

Appearance settings with HUE slider and Premium theme options

Theme Options

• Dark (Default) - Professional dark theme with teal accent
• RGB Matrix - LED-inspired colorful theme
• Custom Hue - Adjust the global hue (0-360°) to create your perfect color scheme

Hue Adjustment

Use the hue slider to shift all interface colors while maintaining contrast and readability. This allows you to match FixtureForge to your personal preference or studio branding.

Language

FixtureForge is available in multiple languages:

• 🇬🇧 English (Default)
• 🇫🇷 Français

To change the language:

1. Open Settings (Ctrl + ,)
2. Go to the General section
3. Select your preferred language from the dropdown
4. The interface will update immediately

Standard Attributes

GDTF defines standard attributes for fixture control. Using these ensures compatibility across consoles and visualizers.

Position

Dimmer

Shutter

Color

Beam

Gobo

Prism

Effects

Control

Geometry Types Reference

Complete reference for all 18 GDTF geometry types:

Keyboard Shortcuts

File Operations

Edit Operations

Navigation

3D Viewer

Frequently Asked Questions