Skip to content

Commit

Permalink
[GCI] Standardised Core code comments (#1343)
Browse files Browse the repository at this point in the history 
* standardise comments

* fix

* fixes

* add docs links

* remove extra .

* ., this and other changes
  • Loading branch information
@harshkhandeparkar @jywarren
harshkhandeparkar authored and jywarren committed Dec 16, 2019
1 parent 0ce2cf9 commit 426733f
Show file tree
Hide file tree
Showing 2 changed files with 124 additions and 25 deletions.
125 changes: 108 additions & 17 deletions src/ImageSequencer.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@ if (typeof window !== 'undefined') { isBrowser = true; }
else { var isBrowser = false; }
require('./util/getStep.js');

/**
* @method ImageSequencer
* @param {Object|Float32Array} options Optional options
* @returns {Object}
*/
ImageSequencer = function ImageSequencer(options) {

var str = require('./Strings.js')(this.steps, modulesInfo, addSteps, copy);
Expand All @@ -14,13 +19,25 @@ ImageSequencer = function ImageSequencer(options) {
return Object.prototype.toString.call(object).split(' ')[1].slice(0, -1);
}

/**
* @method log
* @description Logs colored messages to the console using ASCII color codes
* @param {String} color ASCII color code
* @param {String} msg Message to be logged to the console
*/
function log(color, msg) {
if (options.ui != 'none') {
if (arguments.length == 1) console.log(arguments[0]);
else if (arguments.length == 2) console.log(color, msg);
}
}

/**
* @method copy
* @description Returns a clone of the input object.
* @param {Object|Float32Array} a The Object/Array to be cloned
* @returns {Object|Float32Array}
*/
function copy(a) {
if (!typeof (a) == 'object') return a;
if (objTypeOf(a) == 'Array') return a.slice();
Expand Down Expand Up @@ -53,22 +70,27 @@ ImageSequencer = function ImageSequencer(options) {
for (o in sequencer) {
modules[o] = sequencer[o];
}
sequences = JSON.parse(window.localStorage.getItem('sequences'));
sequences = JSON.parse(window.localStorage.getItem('sequences')); // Get saved sequences from localStorage
if (!sequences) {
sequences = {};
window.localStorage.setItem('sequences', JSON.stringify(sequences));
window.localStorage.setItem('sequences', JSON.stringify(sequences)); // Set the localStorage entry as an empty Object by default
}
}

// if in browser, prompt for an image
// if (options.imageSelect || options.inBrowser) addStep('image-select');
// else if (options.imageUrl) loadImage(imageUrl);

/**
* @method addSteps
* @description Adds one of more steps to the sequence.
* @return {Object}
*/
function addSteps() {
var this_ = (this.name == 'ImageSequencer') ? this : this.sequencer;
var args = [];
var json_q = {};
for (var arg in arguments) { args.push(copy(arguments[arg])); }
for (var arg in arguments) { args.push(copy(arguments[arg])); } // Get all the module names from the arguments
json_q = formatInput.call(this_, args, '+');

inputlog.push({ method: 'addSteps', json_q: copy(json_q) });
Expand All @@ -77,17 +99,28 @@ ImageSequencer = function ImageSequencer(options) {
return this;
}

/**
* @method removeStep
* @description Removes the step at the specified index from the sequence.
* @param {Object} ref ImageSequencer instance
* @param {Number} index Index of the step to be removed
* @returns {Null}
*/
function removeStep(ref, index) {
//remove the step from images[image].steps and redraw remaining images
// Remove the step from images[image].steps and redraw remaining images
if (index > 0) {
//var this_ = (this.name == "ImageSequencer") ? this : this.sequencer;
// var this_ = (this.name == "ImageSequencer") ? this : this.sequencer;
thisStep = ref.steps[index];
thisStep.UI.onRemove(thisStep.options.step);
ref.steps.splice(index, 1);
}
//tell the UI a step has been removed
}

/**
* @method removeSteps
* @description Removes one or more steps from the sequence
* @returns {Object}
*/
function removeSteps() {
var indices;
var this_ = (this.name == 'ImageSequencer') ? this : this.sequencer;
Expand All @@ -103,6 +136,11 @@ ImageSequencer = function ImageSequencer(options) {
return this;
}

/**
* @method insertSteps
* @description Inserts steps at the specified index
* @returns {Object}
*/
function insertSteps() {
var this_ = (this.name == 'ImageSequencer') ? this : this.sequencer;
var args = [];
Expand All @@ -118,8 +156,11 @@ ImageSequencer = function ImageSequencer(options) {
return this;
}

// Config is an object which contains the runtime configuration like progress bar
// information and index from which the sequencer should run
/**
* @method run
* @param {Object} config Object which contains the runtime configuration like progress bar information and index from which the sequencer should run.
* @returns {Boolean}
*/
function run(config) {
var progressObj, index = 0;
config = config || { mode: 'no-arg' };
Expand All @@ -137,7 +178,7 @@ ImageSequencer = function ImageSequencer(options) {
var callback = function() { };
for (var arg in args)
if (objTypeOf(args[arg]) == 'Function')
callback = args.splice(arg, 1)[0]; //callback is formed
callback = args.splice(arg, 1)[0]; // Callback is formed

var json_q = formatInput.call(this_, args, 'r');

Expand All @@ -146,6 +187,11 @@ ImageSequencer = function ImageSequencer(options) {
return true;
}

/**
* @method loadImages
* @description Loads an image via dataURL or normal URL. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for more info.
* @returns {Null}
*/
function loadImages() {
var args = [];
var prevSteps = this.getSteps().slice(1).map(step=>step.options.name);
Expand Down Expand Up @@ -182,17 +228,35 @@ ImageSequencer = function ImageSequencer(options) {

}

/**
* @method replaceImage
* @description Replaces the current image in the sequencer
* @param {String} selector DOM selector string for the image input
* @param {*} steps Current steps Object
* @param {Object} options
* @returns {*}
*/
function replaceImage(selector, steps, options) {
options = options || {};
options.callback = options.callback || function() { };
return require('./ReplaceImage')(this, selector, steps, options);
}

//returns the steps added
/**
* @method getSteps
* @description Returns the current sequence of steps
* @returns {Object}
*/
function getSteps(){
return this.steps;
}

/**
* @method setUI
* @description To set up a UI for ImageSequencer via different callback methods. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for more info.
* @param {Object} UI Object containing UI callback methods. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for more info.
* @returns {Null}
*/
function setUI(UI) {
this.events = require('./ui/UserInterface')(UI);
}
Expand All @@ -201,6 +265,12 @@ ImageSequencer = function ImageSequencer(options) {
return require('./ExportBin')(dir, this, basic, filename);
};

/**
* @method modulesInfo
* @description Returns information about the given module or all the available modules
* @param {String} name Module name
* @returns {Object}
*/
function modulesInfo(name) {
var modulesdata = {};
if (name == 'load-image') return {};
Expand All @@ -222,23 +292,30 @@ ImageSequencer = function ImageSequencer(options) {
return modulesdata;
}

/**
* @method loadNewModule
* @description Adds a new local module to sequencer. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/README.md) for mode info.
* @param {String} name Name of the new module
* @param {Object} options An Object containing path and info about the new module.
* @returns {Object}
*/
function loadNewModule(name, options) {

if (!options) {
return this;

} else if (Array.isArray(options)) {
// contains the array of module and info
// Contains the array of module and info
this.modules[name] = options;

} else if (options.func && options.info) {
// passed in options object
// Passed in options object
this.modules[name] = [
options.func, options.info
];

} else if (options.path && !this.inBrowser) {
// load from path(only in node)
// Load from path(only in node)
const module = [
require(`${options.path}/Module.js`),
require(`${options.path}/info.json`)
Expand All @@ -248,6 +325,13 @@ ImageSequencer = function ImageSequencer(options) {
return this;
}

/**
* @method saveNewModule
* @description Saves a new local module to ImageSequencer
* @param {String} name Name of the new module
* @param {String} path Path to the new module
* @returns {Null}
*/
function saveNewModule(name, path) {
if (options.inBrowser) {
// Not for browser context
Expand All @@ -258,6 +342,13 @@ ImageSequencer = function ImageSequencer(options) {
fs.writeFileSync('./src/Modules.js', mods);
}

/**
* @method saveSequence
* @description Saves a sequence on the browser localStorage.
* @param {String} name Name for the sequence
* @param {String} sequenceString Sequence data as a string
* @returns {Null}
*/
function saveSequence(name, sequenceString) { // 4. save sequence
const sequence = str.stringToJSON(sequenceString);
// Save the given sequence string as a module
Expand All @@ -276,7 +367,7 @@ ImageSequencer = function ImageSequencer(options) {
}

function loadModules() {
// This function loads the modules and saved sequences
// loadModules function loads the modules and saved sequences.
this.modules = require('./Modules');
if (options.inBrowser)
this.sequences = JSON.parse(window.localStorage.getItem('sequences'));
Expand All @@ -286,7 +377,7 @@ ImageSequencer = function ImageSequencer(options) {


return {
//literals and objects
// Literals and objects
name: 'ImageSequencer',
options: options,
inputlog: inputlog,
Expand All @@ -296,7 +387,7 @@ ImageSequencer = function ImageSequencer(options) {
steps: steps,
image: image,

//user functions
// User functions
loadImages: loadImages,
loadImage: loadImages,
addSteps: addSteps,
Expand Down Expand Up @@ -325,7 +416,7 @@ ImageSequencer = function ImageSequencer(options) {
loadModules: loadModules,
getSteps:getSteps,

//other functions
// Other functions
log: log,
objTypeOf: objTypeOf,
copy: copy,
Expand Down
24 changes: 16 additions & 8 deletions src/modules/_nomodule/PixelManipulation.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@
* General purpose per-pixel manipulation
* accepting a changePixel() method to remix a pixel's channels
*/

/**
* @method PixelManipulation
* @description Function for changing pixel values of the image via different callback functions. Read the docs(https://github.com/publiclab/image-sequencer/blob/main/CONTRIBUTING.md) for more info.
* @param {Object} image ndarray of pixels of the image
* @param {Object} options object containing callbacks for manipulating pixels.
* @returns {Null}
*/
module.exports = function PixelManipulation(image, options) {
// To handle the case where pixelmanipulation is called on the input object itself
// like input.pixelManipulation(options)
Expand Down Expand Up @@ -30,18 +38,18 @@ module.exports = function PixelManipulation(image, options) {
};
}

// iterate through pixels;
// Iterate through pixels
// TODO: this could possibly be more efficient; see
// https://github.com/p-v-o-s/infragram-js/blob/master/public/infragram.js#L173-L181


if (options.preProcess) pixels = options.preProcess(pixels); // Allow for preprocessing
if (options.preProcess) pixels = options.preProcess(pixels); // Allow for preprocessing of pixels.

function extraOperation() {
var res;
if (options.extraManipulation) res = options.extraManipulation(pixels, generateOutput);
// there may be a more efficient means to encode an image object,
// but node modules and their documentation are essentially arcane on this point
if (options.extraManipulation) res = options.extraManipulation(pixels, generateOutput); // extraManipulation is used to manipulate each pixel individually.
// There may be a more efficient means to encode an image object,
// but node modules and their documentation are essentially arcane on this point.
function generateOutput() {
var chunks = [];
var totalLength = 0;
Expand Down Expand Up @@ -80,7 +88,7 @@ module.exports = function PixelManipulation(image, options) {
env: {
consoleLog: console.log,
perform: function (x, y) {
let pixel = options.changePixel(
let pixel = options.changePixel( // changePixel function is run over every pixel.
pixels.get(x, y, 0),
pixels.get(x, y, 1),
pixels.get(x, y, 2),
Expand All @@ -95,7 +103,7 @@ module.exports = function PixelManipulation(image, options) {
}
};

function perPixelManipulation() { // pure JavaScript code
function perPixelManipulation() {
for (var x = 0; x < pixels.shape[0]; x++) {
for (var y = 0; y < pixels.shape[1]; y++) {
imports.env.perform(x, y);
Expand Down Expand Up @@ -145,4 +153,4 @@ module.exports = function PixelManipulation(image, options) {
}
}
});
};
};

0 comments on commit 426733f

Please sign in to comment.