Skip to content

Latest commit

 

History

History
491 lines (358 loc) · 17.9 KB

CONTRIBUTING.md

File metadata and controls

491 lines (358 loc) · 17.9 KB
Raw

Contributing to Image Sequencer

Happily accepting pull requests; to edit the core library, modify files in ./src/. To build, run npm install followed by grunt build.

On ARM based devices, the gl module may require some libraries to be re-installed:

sudo apt-get install -y build-essential xserver-xorg-dev libxext-dev libxi-dev libglu1-mesa-dev libglew-dev pkg-config -- see https://github.com/stackgl/headless-gl#ubuntudebian for more.

Most contribution (we imagine) would be in the form of API-compatible modules, which need not be directly included.

Jump To

Contribution-ideas

See this issue for a range of ideas for new contributions and links to possibly helpful libraries, or you can solve an existing issue. Also see the new features issues list.

Bugs

If you find a bug please list it here, and help us develop Image Sequencer by opening an issue!

Contributing modules

Most contributions can happen in modules, rather than to core library code. Modules and their corresponding info files are included into the library in this file: https://github.com/publiclab/image-sequencer/blob/main/src/Modules.js#L5-L7

Module names, descriptions, and parameters are set in the info.json file -- see below.

Any module must follow this basic format:

module.exports = function ModuleName(options,UI) {

  var output;
  // Module requirements have been simplified in version 3, see https://github.com/publiclab/image-sequencer/blob/master/CONTRIBUTING.md#contributing-modules

  function draw(input,callback) {

    var output = function(input){
      /* do something with the input */
      return input;
    }

    this.output = output(input); // run the output and assign it to this.output
    callback();
  }

  return {
    options: options,
    draw: draw,
    output: output,
    UI: UI
  }
}

Image Sequencer modules are designed to be run either in the browser or in a Node.js environment. For dynamically loaded modules, that means that any uses of require() to include an external library must be compiled using a system like browserify or webpack to ensure browser compatibility. An example of this can be found here:

https://github.com/tech4gt/image-sequencer

Browser/node compatibility

If you wish to offer a module without browser-compatibility, please indicate this in the returned info object as:

module.exports = [ ModuleName, { only: ['node'] } ];

If you believe that full cross-compatibility is possible, but need help, please open an issue on your module's issue tracker requesting assistance (and potentially link to it from an inline comment or the module description).

Any Independent Module Must follow this basic format

function ModuleName(options,UI) {

  var output;

  function draw(input,callback) {

    var output = function(input){
      /* do something with the input */
      return input;
    }

    this.output = output(input); // run the output and assign it to this.output
    callback();
  }

  return {
    options: options,
    draw: draw,
    output: output,
    UI: UI
  };
}

  module.exports = [ModuleName,{
      "name": "ModuleName",
      "description": "",
      "inputs": {
        // inputs here
      }
      /* Info can be defined here or imported from a json file */
      // require('./info.json') This only works in node
      // In a module compiled with browserify or webpack, a require() can be used to
      // load a standard info.json file.
      ];

Running a browser-only module in node

If your module has browser specific code or you are consuming a dependency which does the gl-context API. We designed this api especially for web-based modules but since it runs the module in a headless browser, it supports all browser specific APIs.

The API must be used in the following format

var step = this;

    if (!options.inBrowser) {
      require('../_nomodule/gl-context')(input, callback, step, options);
    }
    else {
      /* Browser specific code */
    }

options

The object options stores some important information. This is how you can accept input from users. If you require a variable "x" from the user and the user passes it in, you will be able to access it as options.x.

Options also has some in-built properties. The options.inBrowser boolean denotes whether your module is being run on a browser.

draw()

To add a module to Image Sequencer, it must have a draw method; you can wrap an existing module to add them:

  • module.draw(input, callback)

The draw method should accept an input parameter, which will be an object of the form:

input = {
  src: "datauri of an image here",
  format: "jpeg/png/etc",
  // utility functions
  getPixels: "function to get Image pixels. Wrapper around https://npmjs.com/get-pixels",
  savePixels: "function to save Image pixels. Wrapper around https://npmjs.com/save-pixels",
  lodash: "wrapper around lodash library, https://github.com/lodash",
  dataUriToBuffer: "wrapper around https://www.npmjs.com/package/data-uri-to-buffer",
  pixelManipulation: "general purpose pixel manipulation API, see https://github.com/publiclab/image-sequencer/blob/master/src/modules/_nomodule/PixelManipulation.js"
}

For example usage of pixelManipulation see https://github.com/publiclab/image-sequencer/blob/main/src/modules/Invert/Module.js

The module is included in the browser inside a script tag and since the code runs directly in the browser if any other module is required apart from the apis available on the input object, it should be either bundled with the module code and imported in es6 format or the module code must be browserified before distribution for browser

The draw method is run every time the step is run using sequencer.run(). So any calculations must go into the draw() method's definition.

What is not in the draw method, but is in the module.exports is executed only when the step is added. So whatever external npm modules are to be loaded, or constant definitions must be done outside the draw() method's definition.

draw() receives two arguments - input and callback :

  • input is an object which is essentially the output of the previous step. 
    input = {
  src: "<$DataURL>",
  format: "<png|jpeg|gif>"
}
  • callback is a function which is responsible to tell the sequencer that the step has been "drawn".

When you have done your calculations and produced an image output, you are required to set this.output to an object similar to what the input object was, call callback(), and set options.step.output equal to the output DataURL

  • progressObj is an optional additional Object that can be passed in the format draw(input, callback, progressObj), which handles the progress output; see Progress reporting below.

UI Methods

The module is responsible for emitting various events for the UI to capture.

There are four events in all:

  • UI.onSetup(options.step) must be emitted when the module is added. So it must be emitted outside the draw method's definition as shown above.
  • UI.onDraw(options.step) must be emitted whenever the draw() method is called. So it should ideally be the first line of the definition of the draw method.
  • UI.onComplete(options.step) must be emitted whenever the output of a draw call is ready. An argument, that is the DataURL of the output image must be passed in.
  • UI.onRemove(options.step) is emitted automatically and the module should not emit it.
  • UI.notify(msg,id) must be emitted when a notification has to be produced.

Name and description

For display in the web-based demo UI, set the name and description fields in the info.json file for the module.

Info file

All module folders must have an info.json file which looks like the following:

{
  "name": "Name of Module to be displayed",
  "description": "Optional longer text explanation of the module's function",
  "url": "Optional link to module's source code or documentation",
  "inputs": {
    "var1": {
      "type": "text",
      "default": "default value"
    }
  },
  "outputs": {
    "out1": {
      "type": "text"
    }
  }
}

Types may be one of "text", "integer", "float", "select". Integer and Float types should also specify minimum and maximum values like this:

"var1": {
  "type": "integer",
  "min": 0,
  "max": 4,
  "default": 1
}

Similarly, "Select" type inputs should have a values array.

Also, A module may have output values. These must be defined as shown above.

Progress reporting

The default "loading spinner" can be optionally overridden with a custom progress object to draw progress on the CLI, following is a basic module format for the same:

module.exports = function ModuleName(options,UI) {

  var output;

  function draw(input,callback,progressObj) {

    /* If you wish to supply your own progress bar you need to override progressObj */
    progressObj.stop() // Stop the current progress spinner

    progressObj.overrideFlag = true; // Tell image sequencer that you will supply your own progressBar

    /* Override the object and give your own progress Bar */
    progressObj = /* Your own progress Object */

    var output = function(input){
      /* do something with the input */
      return input;
    };

    this.output = output();
    callback();
  }

  return {
    options: options,
    draw: draw,
    output: output,
    UI: UI
  }
}

The progressObj parameter of draw() is not consumed unless a custom progress bar needs to be drawn, for which this default spinner should be stopped with progressObj.stop() and image-sequencer is informed about the custom progress bar with progressObj.overrideFlag = true; following which this object can be overridden with custom progress object.

Module example

See existing module channel for an example: https://github.com/publiclab/image-sequencer/blob/main/src/modules/Channel/Module.js

The channel module is included into the core modules here: https://github.com/publiclab/image-sequencer/blob/main/src/Modules.js#L5-L7

For help integrating, please open an issue.

Meta Module

IMAGE SEQUENCER supports "meta modules" -- modules made of other modules. The syntax and structure of these meta modules is very similar to standard modules. Sequencer can also generate meta modules dynamically with the function createMetaModule which can be called in the following ways

/* Mapping function is a function which gets the inputs of the module as argument
*  and returns an array with steps mapped to their options
*  See https://github.com/publiclab/image-sequencer/blob/main/src/modules/Colorbar/Module.js for example
*/

/* Module options is an object with the following keys
*  infoJson: the info.json object for the module
*/
sequencer.createMetaModule(mappingFunction,moduleOptions)

/* createMetaModule returns an array of module function and info just like normal
*  modules. These can also be loaded into sequencer dynamically like other modules
*/

A Meta module can also be contributed like a normal module with an info and a Module.js. A basic Meta module shall follow the following format

// Module.js
  module.exports = require('../../util/createMetaModule.js')(
    function mapFunction(options) {

        return [
            { 'name': 'module-name', 'options': {} },
            { 'name': 'module-name', 'options': {} },
        ];
    }, {
        infoJson: require('./info.json')
    }
)[0];
// Info
{
  "name": "meta-moduleName",
  "description": "",
  "inputs": {
  }
}
//index.js
module.exports = [
  require('./Module.js'),
  require('./info.json')
]

All of the above can also be combined together to form a single file module.

// MetaModule.js
module.exports =
  sequencer.createMetaModule(
    function mapFunction(options) {

        return [
            { 'name': 'module-name', 'options': {} },
            { 'name': 'module-name', 'options': {} },
        ];
    }, {
        infoJson: {
            "name": "meta-moduleName",
            "description": "",
            "inputs": {
            }
        }
    });

Linting

We are now using eslint and husky to help lint and format our code each time we commit. Eslint defines coding standards and helps in cleaning up the code. To run eslint for checking errors globally or within a specific file run:

npx eslint .

npx eslint <file path>

And to fix those errors globally or in a file, run these in your terminal:

npx eslint . --fix

npx eslint <file path> --fix

Be sure to not include the angular brackets(<>).

Husky ensures automation of the above steps with git-hooks(eg. git add, git commit..). However we don't want to check and fix changes of the entire codebase with each commit and that the fixes made by eslint appear unstaged and require us to commit them again and that is where lint-staged helps.

If we want husky to not verify the commit and push it anyway, use git commit -m "message" --no-verify.

Grunt Tasks

This repository has different grunt tasks for different uses. The source code is in the Gruntfile.

The following command is used for running the tasks: grunt [task-name]. Here [task-name] should be replaced by the name of the task to be run. To run the default task run grunt without any options.

Tasks

  1. compile: Compiles/Browserifies the dist files in /dist/image-sequencer.js and /dist/image-sequencer-ui.js.
  2. build: Compiles the files as in the compile task and minifies/uglifies dist files in /dist/image-sequencer.min.js and /dist/image-sequencer-ui.min.js.
  3. watch: Checks for any changes in the source code and runs the compile task if any changes are found.
  4. serve: Compiles the dist files as in the compile task and starts a local server on localhost:3000 to host the demo site in /examples/ directory. Also runs the watch task.
  5. production: Compiles and minifies dist files in /dist/image-sequencer.js and /dist/image-sequencer-ui.js without the .min.js extension to include minified files in the demo site. This script should only be used in production mode while deploying.
  6. default: Runs the watch task as default.

UI Helper Methods

scopeQuery

Path: /examples/lib/scopeQuery.js

The method returns a scoped jQuery object which only searches for elements inside a given scope (a DOM element).

To use the method,

  • import the scopeSelector and scopeSelectorAll methods from lib/scopeQuery.js
  • call the methods with scope as a parameter
var scopeQuery = require('./scopeQuery');

var $step = scopeQuery.scopeSelector(scope),
    $stepAll = scopeQuery.scopeSelectorAll(scope);

This will return an object with a constructor which returns a jQuery object (from inside the scope) but with new elem and elemAll methods.

Methods of the Returned Object

  • elem(): Selects an element inside the scope.
  • elemAll(): Selects all the instances of a given element inside the scope.
  • getScope(): Returns the scope as a DOM element.
  • getDomElem(): Returns the scoped element as a DOM element instead of a jquery object.

Example

//The scope is a div element with id=“container“ and there are three divs in it
//with ids „1“, „2“, and „3“, and all of them have a „child“ class attribute

var $step = require('./scopeQuery').scopeSelector(document.getElementById('container'));

$step('#1'); // returns the div element with id=“1“
$step('#1').hide().elemAll('.child').fadeOut(); // abruptly hides the div element with id=“1“ and fades out all other div elements

These two methods are chainable and will always return elements from inside the scope.

Usage

Instead of using

$(step.ui.querySelector('query')).show().hide();
$(step.ui.querySelectorAll('q2')).show().hide();

The following code can be used

$step('query').show().hide();
$stepAll('q2').show().hide();

Scripts

The following shell scripts are present in the scripts/ directory.

  • update-gh-pages: This script can be used to update the gh-pages branch of this repo or a fork. This script is not meant to be used directly as it runs in the current working directory. If you run it on your primary local clone, it can delete the local changes. This script is made to be used in a github action or in a temporary directory via another script, such as update-demo.

    Arguments:

    1. Repo(to use as upstream) url in the form username/repo (default: publiclab/image-sequencer) NOTE: Github only
    2. Branch to pull from eg: main or stable (default: stable)
    3. CNAME URL (default: none)
    4. Set the fourth argument to anything to bypass the warning. You will have to set this argument if you want to run this script in another script without needing user interaction, such as in a github action.

  • update-demo: A safe, interactive script that can be used to update the gh-pages branch of any image-sequencer fork. This script is safe to use directly because it separately clones the repo in a temporary directory.

    Arguments: None since it is a an interactive script, ie it asks the user for input.

Comments

  1. Methods must be described using JSDoc comments
  2. Misc code comments should be inline unless it is a long sentence.
  3. No use of continuous tenses, no pronouns.
  4. No redundant comments.
  5. Each comment should start with an uppercase letter and end with a full stop.