pygdtf 1.0.5

General Device Type Format (GDTF) library for Python

python-gdtf

Python library for General Device Type Format

GDTF specification as per https://gdtf.eu/gdtf/prologue/introduction/

See source code for documentation. Naming conventions, in general, are identical to that on the GDTF, CamelCase is replaced with underscore_delimiters.

Credits

Originally created by Jack Page. Friendly forked to Open-Stage by vanous. We continue publishing to pypi under the same pygdtf name with Jack's permission.

Used for example by BlenderDMX.

Source code

PyPi page

Installation

pip install pygdtf

To install latest version from this git repository, run pip:

python -m pip install https://codeload.github.com/open-stage/python-gdtf/zip/refs/heads/master

Usage

# import
import pygdtf

# parse a GDTF file
gdtf_fixture = pygdtf.FixtureType("BlenderDMX@[e-mail]")

# one can also parse just a description.xml file during development or testing
gdtf_fixture = pygdtf.FixtureType(dsc_file="description.xml")

# get info about DMX Modes:
pygdtf.utils.get_dmx_modes_info(gdtf_fixture)

[{'mode_id': 0,
  'mode_name': 'Default',
  'mode_dmx_channel_count': 5,
  'mode_virtual_channel_count': 0}]

# get list of DMX channels with geometries, channels functions for a DMX Mode named "Default"
pygdtf.utils.get_dmx_channels(gdtf_fixture, "Default")

[
    [
        {'dmx': 1, 'id': 'Dimmer', 'offset': [
                1
            ], 'default': 0, 'highlight': 255, 'geometry': 'Beam', 'break': 1, 'channel_functions': [
                {'name': 'Dimmer', 'attribute': 'Dimmer', 'real_fade': 0.0, 'physical_to': 1.0, 'physical_from': 0.0, 'channel_sets': ['Closed', '', 'Open'
                    ]
                }
            ]
        },
        {'dmx': 2, 'id': 'ColorAdd_R', 'offset': [
                2
            ], 'default': 0, 'highlight': 255, 'geometry': 'Beam', 'break': 1, 'channel_functions': [
                {'name': 'ColorAdd_R', 'attribute': 'ColorAdd_R', 'real_fade': 0.0, 'physical_to': 1.0, 'physical_from': 0.0, 'channel_sets': ['Min', '', 'Max'
                    ]
                }
            ]
        },
        {'dmx': 3, 'id': 'ColorAdd_G', 'offset': [
                3
            ], 'default': 0, 'highlight': 255, 'geometry': 'Beam', 'break': 1, 'channel_functions': [
                {'name': 'ColorAdd_G', 'attribute': 'ColorAdd_G', 'real_fade': 0.0, 'physical_to': 1.0, 'physical_from': 0.0, 'channel_sets': ['Min', '', 'Max'
                    ]
                }
            ]
        },
        {'dmx': 4, 'id': 'ColorAdd_B', 'offset': [
                4
            ], 'default': 0, 'highlight': 255, 'geometry': 'Beam', 'break': 1, 'channel_functions': [
                {'name': 'ColorAdd_B', 'attribute': 'ColorAdd_B', 'real_fade': 0.0, 'physical_to': 1.0, 'physical_from': 0.0, 'channel_sets': ['Min', '', 'Max'
                    ]
                }
            ]
        },
        {'dmx': 5, 'id': 'ColorAdd_W', 'offset': [
                5
            ], 'default': 0, 'highlight': None, 'geometry': 'Beam', 'break': 1, 'channel_functions': [
                {'name': 'ColorAdd_W', 'attribute': 'ColorAdd_W', 'real_fade': 0.0, 'physical_to': 1.0, 'physical_from': 0.0, 'channel_sets': ['Min', '', 'Max'
                    ]
                }
            ]
        }
    ]
]

#you can get the full info with channels and with channel functions at once:
pygdtf.utils.get_dmx_modes_info(gdtf_fixture, include_channels=True, include_channel_functions=True)

See BlenderDMX and tests for reference implementation and usage examples.

Usage principles

• for list of channels, use pygdtf.utils.get_dmx_channels as per example above, do not presume that plain layout of DMX Channels in a DMX Mode is defining the DMX footprint of the device. Geometry references are (frequently) used to re-use parts of the device. This means that a channel(s) defined once can be multiplied, over several times duplicated geometry (tree).

• do not use geometry names for anything related to function of the geometry (yoke, pan, tilt, head), use attached GDTF attributes ("Pan", "Tilt") to know what functions should the geometry perform

Status

• Many GDTF 1.2 features have been implemented
• Some GDTF 1.1 features have been kept in

Development

PRs appreciated. You can use uv to get the project setup by running:

uv sync

Typing

• We try to type the main library as well as the utils module, to test run:

mypy pygdtf/**py  --pretty

Format

• To format, use black or ruff

Testing

• to test, run: pytest
• to test typing with mypy run pytest:

pytest --mypy -m mypy pygdtf/**py