Open Fixture Library

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.

Contribute

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.

Local installation

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 or npm run watch (to restart the server everytime a file is changed).

New fixtures

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.

Fixture features

See cli/fixture-features/README.md.

Model

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.

Plugins

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>]

UI

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.

Tests

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!

novasfronteiras / open-fixture-library