From 426733f625207c2f50cef8b74857b458aed8e827 Mon Sep 17 00:00:00 2001 From: Harsh Khandeparkar <34770591+HarshKhandeparkar@users.noreply.github.com> Date: Mon, 16 Dec 2019 17:56:03 +0000 Subject: [PATCH] [GCI] Standardised Core code comments (#1343) * standardise comments * fix * fixes * add docs links * remove extra . * ., this and other changes --- src/ImageSequencer.js | 125 ++++++++++++++++++--- src/modules/_nomodule/PixelManipulation.js | 24 ++-- 2 files changed, 124 insertions(+), 25 deletions(-) diff --git a/src/ImageSequencer.js b/src/ImageSequencer.js index f980efb75f..723690e643 100644 --- a/src/ImageSequencer.js +++ b/src/ImageSequencer.js @@ -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); @@ -14,6 +19,12 @@ 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]); @@ -21,6 +32,12 @@ ImageSequencer = function ImageSequencer(options) { } } + /** + * @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(); @@ -53,10 +70,10 @@ 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 } } @@ -64,11 +81,16 @@ ImageSequencer = function ImageSequencer(options) { // 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) }); @@ -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; @@ -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 = []; @@ -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' }; @@ -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'); @@ -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); @@ -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); } @@ -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 {}; @@ -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`) @@ -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 @@ -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 @@ -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')); @@ -286,7 +377,7 @@ ImageSequencer = function ImageSequencer(options) { return { - //literals and objects + // Literals and objects name: 'ImageSequencer', options: options, inputlog: inputlog, @@ -296,7 +387,7 @@ ImageSequencer = function ImageSequencer(options) { steps: steps, image: image, - //user functions + // User functions loadImages: loadImages, loadImage: loadImages, addSteps: addSteps, @@ -325,7 +416,7 @@ ImageSequencer = function ImageSequencer(options) { loadModules: loadModules, getSteps:getSteps, - //other functions + // Other functions log: log, objTypeOf: objTypeOf, copy: copy, diff --git a/src/modules/_nomodule/PixelManipulation.js b/src/modules/_nomodule/PixelManipulation.js index 6bcf176585..3ad6223b6b 100644 --- a/src/modules/_nomodule/PixelManipulation.js +++ b/src/modules/_nomodule/PixelManipulation.js @@ -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) @@ -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; @@ -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), @@ -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); @@ -145,4 +153,4 @@ module.exports = function PixelManipulation(image, options) { } } }); -}; \ No newline at end of file +};