To use lighting control software like QLC+, DMXControl or e:cue, you need fixture definition files that describe your lighting hardware. Since one software can usually only understand its own fixture definition format, switching between different programs can be difficult.
The Open Fixture Library (open-fixture-library.herokuapp.com) tries to solve this problem by collecting fixture definitions and making them downloadable in various formats. Internally, it uses a JSON format that tries to bundle as much information as possible for all the different output formats.
If you are a user and want to help, head over to the Fixture Editor and add your favorite fixture that is not yet included in our library!
If you are a developer, read on :)
The project is still in a very early stage, but we're happy to see new issues or pull requests anyway!
Pushing to the master
branch here on GitHub deploys a new version on Heroku each time. So we have to make sure that the master
branch is always clean and ready to deploy. Thus, we will make heavy use of pull requests (so, do always create feature branches git checkout -b new-feature
) and let Travis CI check that everything new is passing all tests.
- Clone this repository (or a fork of it).
- Run
npm install
after first cloning or every time new dependencies are added in package.json in order to install the needed Node dependencies. (You can identify missing dependencies when the error "Cannot find module" is given.) - To start the server locally at localhost:5000, run
npm start
ornpm run watch
(to restart the server everytime a file is changed).
Ideally, just use the Fixture Editor and submit it from there (however, some features are still missing, see #77; add such information in a comment in the resulting pull request). Please try to include as much information as possible!
If you have to manually edit fixtures, see README.md in the fixtures
directory and use the existing fixtures as a reference.
You can also import existing fixture definitions using import plugins. See cli/import-fixture.js for that. In the future, this will be integrated into the Fixture Editor.
See cli/fixture-features/README.md.
A fixture is internally modeled in the Fixture class. An object (parsed from the JSON file) provides additional functionalities to ease the handling and to avoid code duplication. See the files in the lib/model
directory to see possible functions.
A plugin is a module that handles import from and/or export to a fixture format. To add a plugin, create a new subdirectory in the plugins
directory containing the following files:
README.md
: A markdown file with a short explanation about the fixture format. If applicable, please include:- a link to the software that uses this format
- how to import fixtures into the software
- a place where fixtures of this format can be obtained from
export.js
if export is supported.module.exports.name = 'Plugin Name'; module.exports.version = '0.0.3'; // semantic versioning of export plugin module.exports.export = function exportPluginName(fixtures, options) { /* * fixtures: array of Fixture objects * * options: { * baseDir: '...', * // maybe more * } */ let outfiles = []; // ... // multiple files will automatically be zipped together outfiles.push({ name: 'filename.ext', content: 'file content', mimetype: 'text/plain' }); // ... return outfiles; };
import.js
if import is supported.module.exports.name = 'Plugin Name'; module.exports.version = '0.1.0'; // semantic versioning of import plugin module.exports.import = function importPluginName(str, filename, resolve, reject) { /* * str: 'import file contents' * filename: 'importFilename.ext' * resolve: function to call if everything goes right, see below * reject: function to call if something goes wrong, see below */ let out = { manufacturers: {}, // like in manufacturers.json fixtures: {}, // key: 'manufacturer-key/fixture-key', value: like in a fixture JSON warnings: {} // key: 'manufacturer-key/fixture-key' to which a warning belongs, value: string }; // ... // example const manKey = 'cameo'; const fixKey = 'thunder-wash-600-rgb' if (couldNotParse) { return reject(`Could not parse '${filename}'.`); } // Add warning if a necessary property is not included in parsed file out.warnings[manKey + '/' + fixKey].push('Could not parse categories, please specify them manually.'); out.fixtures[manKey + '/' + fixKey] = fixtureObject; resolve(out); };
You can try plugins from the command line:
node cli/import-fixture.js <plugin> <filename>
node cli/export-fixture.js -p <plugin name> <fixture> [<more fixtures>]
Static files are located in the static
directory (surprise!), the dynamic stuff is in views
.
The views/stylesheets
subfolder contains the SASS stylesheets. Try to keep them organized, feel free to add a new file if needed.
We use Express to handle and delegate web requests to the respective page modules. Those templates reside in the views/pages
subdirectory. A template module has to export a single function that returns a string which will be treated as HTML. The function receives a single options
parameter. See main.js for the guaranteed options.
Every time a new commit is pushed to GitHub, Travis CI runs all the tests in the tests
directory (configured by .travis.yml). That helps spotting bugs early.
Additionally, Codacy helps with static code analysis.
We want to ensure good code style and fixture validity, so if you have an idea for a new test or on how to improve an existing one – awesome!