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

Important changes

Version 1.1.0

⚠️ List of DMX Channels provided by dmx_mode.dmx_channels is now a complete list of all DMX channels calculated by obtaining DMX channels for geometries, Geometry References and so on, no need to use the .utils methods anymore.

⚠️ The list of channels as dictionaries can be obtained by dmx_mode.dmx_channels.as_dicts(), the "id" has been renamed to "attribute". DMX Channel now contains Logical Channels and then Channel Functions. The as_dict() is now also in dmx_modes, dmx_mode, dmx_channels and so on.

⚠️ Many of the .utils package methods have been moved directly to the main part of pygdtf. External usage of methods from .utils should not be needed anymore.

See CHANGELOG for details.

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@[email protected]")

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

# now access things like DMX modes, channels and so on
# get DMX Mode name
gdtf_fixture.dmx_modes[0].name
'Mode 1 - Standard 16 - bit'

# get number of DMX channels
gdtf_fixture.dmx_modes[0].dmx_channels_count
39

# get number of Virtual channels
gdtf_fixture.dmx_modes[0].virtual_channels_count
0

# get number of DMX breaks
gdtf_fixture.dmx_modes[0].dmx_breaks_count
1

# get DMX channels as objects gdtf_fixture.dmx_modes[0].dmx_channels
<pygdtf.DmxChannel object at 0x7f789c63bb60>, <pygdtf.DmxChannel object at
0x7f789c375590>, <pygdtf.DmxChannel object at 0x7f789c375a90>,...

# get DMX channels as dict
gdtf_fixture.dmx_modes[0].dmx_channels.as_dict()

[[{'dmx': 1, 'offset': [1, 2], 'id': 'Pan', 'default': 128, 'highlight': None,
'geometry': 'Yoke', 'break': 1, 'parent_name': 'Base', 'channel_functions':
[{'name': 'Pan', 'attribute': 'Pan', 'dmx_from': 0, 'dmx_to': 255, 'default':
128, 'real_fade': 1.833, 'physical_to': 270.0, 'physical_from': -270.0,
'channel_sets': ['', 'Center', '']}, ...

# see the source code for more methods

See BlenderDMX and tests for reference implementation and usage examples.

Usage principles

• 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