image.js

/**
 * @module Image
 * @submodule Image
 * @for p5
 * @requires core
 */

/**
 * This module defines the p5 methods for the <a href="#/p5.Image">p5.Image</a> class
 * for drawing images to the main display canvas.
 */
import p5 from '../core/main';
import omggif from 'omggif';

/**
 * Creates a new <a href="#/p5.Image">p5.Image</a> object. The new image is
 * transparent by default.
 *
 * `createImage()` uses the `width` and `height` paremeters to set the new
 * <a href="#/p5.Image">p5.Image</a> object's dimensions in pixels. The new
 * <a href="#/p5.Image">p5.Image</a> can be modified by updating its
 * <a href="#/p5.Image/pixels">pixels</a> array or by calling its
 * <a href="#/p5.Image/get">get()</a> and
 * <a href="#/p5.Image/set">set()</a> methods. The
 * <a href="#/p5.Image/loadPixels">loadPixels()</a> method must be called
 * before reading or modifying pixel values. The
 * <a href="#/p5.Image/updatePixels">updatePixels()</a> method must be called
 * for updates to take effect.
 *
 * @method createImage
 * @param  {Integer} width  width in pixels.
 * @param  {Integer} height height in pixels.
 * @return {p5.Image}       new <a href="#/p5.Image">p5.Image</a> object.
 * @example
 * <div>
 * <code>
 * let img = createImage(66, 66);
 * img.loadPixels();
 * for (let x = 0; x < img.width; x += 1) {
 *   for (let y = 0; y < img.height; y += 1) {
 *     img.set(x, y, 0);
 *   }
 * }
 * img.updatePixels();
 * image(img, 17, 17);
 *
 * describe('A black square drawn in the middle of a gray square.');
 * </code>
 * </div>
 *
 * <div>
 * <code>
 * let img = createImage(66, 66);
 * img.loadPixels();
 * for (let x = 0; x < img.width; x += 1) {
 *   for (let y = 0; y < img.height; y += 1) {
 *     let a = map(x, 0, img.width, 0, 255);
 *     let c = color(0, a);
 *     img.set(x, y, c);
 *   }
 * }
 * img.updatePixels();
 * image(img, 17, 17);
 *
 * describe('A square with a horizontal color gradient that transitions from gray to black.');
 * </code>
 * </div>
 *
 * <div>
 * <code>
 * let img = createImage(66, 66);
 * img.loadPixels();
 * let d = pixelDensity();
 * let halfImage = 4 * (d * img.width) * (d * img.height / 2);
 * for (let i = 0; i < halfImage; i += 4) {
 *   // Red.
 *   img.pixels[i] = 0;
 *   // Green.
 *   img.pixels[i + 1] = 0;
 *   // Blue.
 *   img.pixels[i + 2] = 0;
 *   // Alpha.
 *   img.pixels[i + 3] = 255;
 * }
 * img.updatePixels();
 * image(img, 17, 17);
 *
 * describe('A black square drawn in the middle of a gray square.');
 * </code>
 * </div>
 */
p5.prototype.createImage = function(width, height) {
  p5._validateParameters('createImage', arguments);
  return new p5.Image(width, height);
};

/**
 *  Saves the current canvas as an image. The browser will either save the
 *  file immediately or prompt the user with a dialogue window.
 *
 *  @method saveCanvas
 *  @param  {p5.Framebuffer|p5.Element|HTMLCanvasElement} selectedCanvas   reference to a
 *                                                          specific HTML5 canvas element.
 *  @param  {String} [filename]  file name. Defaults to 'untitled'.
 *  @param  {String} [extension] file extension, either 'jpg' or 'png'. Defaults to 'png'.
 *
 *  @example
 * <div class='norender'>
 * <code>
 * function setup() {
 *   createCanvas(100, 100);
 *   background(255);
 *   saveCanvas();
 * }
 * </code>
 * </div>
 *
 * <div class='norender'>
 * <code>
 * function setup() {
 *   createCanvas(100, 100);
 *   background(255);
 *   saveCanvas('myCanvas.jpg');
 * }
 * </code>
 * </div>
 *
 * <div class='norender'>
 * <code>
 * function setup() {
 *   createCanvas(100, 100);
 *   background(255);
 *   saveCanvas('myCanvas', 'jpg');
 * }
 * </code>
 * </div>
 *
 * <div class='norender'>
 * <code>
 * function setup() {
 *   let cnv = createCanvas(100, 100);
 *   background(255);
 *   saveCanvas(cnv);
 * }
 * </code>
 * </div>
 *
 * <div class='norender'>
 * <code>
 * function setup() {
 *   let cnv = createCanvas(100, 100);
 *   background(255);
 *   saveCanvas(cnv, 'myCanvas.jpg');
 * }
 * </code>
 * </div>
 *
 * <div class='norender'>
 * <code>
 * function setup() {
 *   let cnv = createCanvas(100, 100);
 *   background(255);
 *   saveCanvas(cnv, 'myCanvas', 'jpg');
 * }
 * </code>
 * </div>
 */
/**
 *  @method saveCanvas
 *  @param  {String} [filename]
 *  @param  {String} [extension]
 */
p5.prototype.saveCanvas = function() {
  p5._validateParameters('saveCanvas', arguments);

  // copy arguments to array
  const args = [].slice.call(arguments);
  let htmlCanvas, filename, extension, temporaryGraphics;

  if (arguments[0] instanceof HTMLCanvasElement) {
    htmlCanvas = arguments[0];
    args.shift();
  } else if (arguments[0] instanceof p5.Element) {
    htmlCanvas = arguments[0].elt;
    args.shift();
  } else if (arguments[0] instanceof p5.Framebuffer) {
    const framebuffer = arguments[0];
    temporaryGraphics = this.createGraphics(framebuffer.width,
      framebuffer.height);
    temporaryGraphics.pixelDensity(pixelDensity());
    framebuffer.loadPixels();
    temporaryGraphics.loadPixels();
    temporaryGraphics.pixels.set(framebuffer.pixels);
    temporaryGraphics.updatePixels();

    htmlCanvas = temporaryGraphics.elt;
    args.shift();
  } else {
    htmlCanvas = this._curElement && this._curElement.elt;
  }

  if (args.length >= 1) {
    filename = args[0];
  }
  if (args.length >= 2) {
    extension = args[1];
  }

  extension =
    extension ||
    p5.prototype._checkFileExtension(filename, extension)[1] ||
    'png';

  let mimeType;
  switch (extension) {
    default:
      //case 'png':
      mimeType = 'image/png';
      break;
    case 'jpeg':
    case 'jpg':
      mimeType = 'image/jpeg';
      break;
  }

  htmlCanvas.toBlob(blob => {
    p5.prototype.downloadFile(blob, filename, extension);
    if(temporaryGraphics) temporaryGraphics.remove();
  }, mimeType);
};

// this is the old saveGif, left here for compatibility purposes
// the only place I found it being used was on image/p5.Image.js, on the
// save function. that has been changed to use this function.
p5.prototype.encodeAndDownloadGif = function(pImg, filename) {
  const props = pImg.gifProperties;

  //convert loopLimit back into Netscape Block formatting
  let loopLimit = props.loopLimit;
  if (loopLimit === 1) {
    loopLimit = null;
  } else if (loopLimit === null) {
    loopLimit = 0;
  }
  const buffer = new Uint8Array(pImg.width * pImg.height * props.numFrames);

  const allFramesPixelColors = [];

  // Used to determine the occurrence of unique palettes and the frames
  // which use them
  const paletteFreqsAndFrames = {};

  // Pass 1:
  //loop over frames and get the frequency of each palette
  for (let i = 0; i < props.numFrames; i++) {
    const paletteSet = new Set();
    const data = props.frames[i].image.data;
    const dataLength = data.length;
    // The color for each pixel in this frame ( for easier lookup later )
    const pixelColors = new Uint32Array(pImg.width * pImg.height);
    for (let j = 0, k = 0; j < dataLength; j += 4, k++) {
      const r = data[j + 0];
      const g = data[j + 1];
      const b = data[j + 2];
      const color = (r << 16) | (g << 8) | (b << 0);
      paletteSet.add(color);

      // What color does this pixel have in this frame ?
      pixelColors[k] = color;
    }

    // A way to put use the entire palette as an object key
    const paletteStr = [...paletteSet].sort().toString();
    if (paletteFreqsAndFrames[paletteStr] === undefined) {
      paletteFreqsAndFrames[paletteStr] = { freq: 1, frames: [i] };
    } else {
      paletteFreqsAndFrames[paletteStr].freq += 1;
      paletteFreqsAndFrames[paletteStr].frames.push(i);
    }

    allFramesPixelColors.push(pixelColors);
  }

  let framesUsingGlobalPalette = [];

  // Now to build the global palette
  // Sort all the unique palettes in descending order of their occurrence
  const palettesSortedByFreq = Object.keys(paletteFreqsAndFrames).sort(function(
    a,
    b
  ) {
    return paletteFreqsAndFrames[b].freq - paletteFreqsAndFrames[a].freq;
  });

  // The initial global palette is the one with the most occurrence
  const globalPalette = palettesSortedByFreq[0]
    .split(',')
    .map(a => parseInt(a));

  framesUsingGlobalPalette = framesUsingGlobalPalette.concat(
    paletteFreqsAndFrames[globalPalette].frames
  );

  const globalPaletteSet = new Set(globalPalette);

  // Build a more complete global palette
  // Iterate over the remaining palettes in the order of
  // their occurrence and see if the colors in this palette which are
  // not in the global palette can be added there, while keeping the length
  // of the global palette <= 256
  for (let i = 1; i < palettesSortedByFreq.length; i++) {
    const palette = palettesSortedByFreq[i].split(',').map(a => parseInt(a));

    const difference = palette.filter(x => !globalPaletteSet.has(x));
    if (globalPalette.length + difference.length <= 256) {
      for (let j = 0; j < difference.length; j++) {
        globalPalette.push(difference[j]);
        globalPaletteSet.add(difference[j]);
      }

      // All frames using this palette now use the global palette
      framesUsingGlobalPalette = framesUsingGlobalPalette.concat(
        paletteFreqsAndFrames[palettesSortedByFreq[i]].frames
      );
    }
  }

  framesUsingGlobalPalette = new Set(framesUsingGlobalPalette);

  // Build a lookup table of the index of each color in the global palette
  // Maps a color to its index
  const globalIndicesLookup = {};
  for (let i = 0; i < globalPalette.length; i++) {
    if (!globalIndicesLookup[globalPalette[i]]) {
      globalIndicesLookup[globalPalette[i]] = i;
    }
  }

  // force palette to be power of 2
  let powof2 = 1;
  while (powof2 < globalPalette.length) {
    powof2 <<= 1;
  }
  globalPalette.length = powof2;

  // global opts
  const opts = {
    loop: loopLimit,
    palette: new Uint32Array(globalPalette)
  };
  const gifWriter = new omggif.GifWriter(buffer, pImg.width, pImg.height, opts);
  let previousFrame = {};

  // Pass 2
  // Determine if the frame needs a local palette
  // Also apply transparency optimization. This function will often blow up
  // the size of a GIF if not for transparency. If a pixel in one frame has
  // the same color in the previous frame, that pixel can be marked as
  // transparent. We decide one particular color as transparent and make all
  // transparent pixels take this color. This helps in later in compression.
  for (let i = 0; i < props.numFrames; i++) {
    const localPaletteRequired = !framesUsingGlobalPalette.has(i);
    const palette = localPaletteRequired ? [] : globalPalette;
    const pixelPaletteIndex = new Uint8Array(pImg.width * pImg.height);

    // Lookup table mapping color to its indices
    const colorIndicesLookup = {};

    // All the colors that cannot be marked transparent in this frame
    const cannotBeTransparent = new Set();

    allFramesPixelColors[i].forEach((color, k) => {
      if (localPaletteRequired) {
        if (colorIndicesLookup[color] === undefined) {
          colorIndicesLookup[color] = palette.length;
          palette.push(color);
        }
        pixelPaletteIndex[k] = colorIndicesLookup[color];
      } else {
        pixelPaletteIndex[k] = globalIndicesLookup[color];
      }

      if (i > 0) {
        // If even one pixel of this color has changed in this frame
        // from the previous frame, we cannot mark it as transparent
        if (allFramesPixelColors[i - 1][k] !== color) {
          cannotBeTransparent.add(color);
        }
      }
    });

    const frameOpts = {};

    // Transparency optimization
    const canBeTransparent = palette.filter(a => !cannotBeTransparent.has(a));
    if (canBeTransparent.length > 0) {
      // Select a color to mark as transparent
      const transparent = canBeTransparent[0];
      const transparentIndex = localPaletteRequired
        ? colorIndicesLookup[transparent]
        : globalIndicesLookup[transparent];
      if (i > 0) {
        for (let k = 0; k < allFramesPixelColors[i].length; k++) {
          // If this pixel in this frame has the same color in previous frame
          if (allFramesPixelColors[i - 1][k] === allFramesPixelColors[i][k]) {
            pixelPaletteIndex[k] = transparentIndex;
          }
        }
        frameOpts.transparent = transparentIndex;
        // If this frame has any transparency, do not dispose the previous frame
        previousFrame.frameOpts.disposal = 1;
      }
    }
    frameOpts.delay = props.frames[i].delay / 10; // Move timing back into GIF formatting
    if (localPaletteRequired) {
      // force palette to be power of 2
      let powof2 = 1;
      while (powof2 < palette.length) {
        powof2 <<= 1;
      }
      palette.length = powof2;
      frameOpts.palette = new Uint32Array(palette);
    }
    if (i > 0) {
      // add the frame that came before the current one
      gifWriter.addFrame(
        0,
        0,
        pImg.width,
        pImg.height,
        previousFrame.pixelPaletteIndex,
        previousFrame.frameOpts
      );
    }
    // previous frame object should now have details of this frame
    previousFrame = {
      pixelPaletteIndex,
      frameOpts
    };
  }

  previousFrame.frameOpts.disposal = 1;
  // add the last frame
  gifWriter.addFrame(
    0,
    0,
    pImg.width,
    pImg.height,
    previousFrame.pixelPaletteIndex,
    previousFrame.frameOpts
  );

  const extension = 'gif';
  const blob = new Blob([buffer.slice(0, gifWriter.end())], {
    type: 'image/gif'
  });
  p5.prototype.downloadFile(blob, filename, extension);
};

/**
 * Captures a sequence of frames from the canvas that can be used to create a
 * movie. Frames are downloaded as individual image files by default.
 *
 * The first parameter, `filename`, sets the prefix for the file names. For
 * example, setting the prefix to `'frame'` would generate the image files
 * `frame0.png`, `frame1.png`, and so on. The second parameter, `extension`,
 * sets the file type to either `'png'` or `'jpg'`.
 *
 * The third parameter, `duration`, sets the duration to record in seconds.
 * The maximum duration is 15 seconds. The fourth parameter, `framerate`, sets
 * the number of frames to record per second. The maximum frame rate value is
 * 22. Limits are placed on `duration` and `framerate` to avoid using too much
 * memory. Recording large canvases can easily crash sketches or even web
 * browsers.
 *
 * The fifth parameter, `callback`, is optional. If a function is passed,
 * image files won't be saved by default. The callback function can be used
 * to process an array containing the data for each captured frame. The array
 * of image data contains a sequence of objects with three properties for each
 * frame: `imageData`, `filename`, and `extension`.
 *
 * @method saveFrames
 * @param  {String}   filename  prefix of file name.
 * @param  {String}   extension file extension, either 'jpg' or 'png'.
 * @param  {Number}   duration  duration in seconds to record. This parameter will be constrained to be less or equal to 15.
 * @param  {Number}   framerate number of frames to save per second. This parameter will be constrained to be less or equal to 22.
 * @param  {function(Array)} [callback] callback function that will be executed
                                  to handle the image data. This function
                                  should accept an array as argument. The
                                  array will contain the specified number of
                                  frames of objects. Each object has three
                                  properties: `imageData`, `filename`, and `extension`.
 * @example
 * <div>
 * <code>
 * function draw() {
 *   let r = frameCount % 255;
 *   let g = 50;
 *   let b = 100;
 *   background(r, g, b);
 *
 *   describe('A square repeatedly changes color from blue to pink.');
 * }
 *
 * function keyPressed() {
 *   if (key === 's') {
 *     saveFrames('frame', 'png', 1, 5);
 *   }
 * }
 * </code>
 * </div>
 *
 * <div>
 * <code>
 * function draw() {
 *   let r = frameCount % 255;
 *   let g = 50;
 *   let b = 100;
 *   background(r, g, b);
 *
 *   describe('A square repeatedly changes color from blue to pink.');
 * }
 *
 * function mousePressed() {
 *   saveFrames('frame', 'png', 1, 5, data => {
 *     // Prints an array of objects containing raw image data,
 *     // filenames, and extensions.
 *     print(data);
 *   });
 * }
 * </code>
 * </div>
 */
p5.prototype.saveFrames = function(fName, ext, _duration, _fps, callback) {
  p5._validateParameters('saveFrames', arguments);
  let duration = _duration || 3;
  duration = p5.prototype.constrain(duration, 0, 15);
  duration = duration * 1000;
  let fps = _fps || 15;
  fps = p5.prototype.constrain(fps, 0, 22);
  let count = 0;

  const makeFrame = p5.prototype._makeFrame;
  const cnv = this._curElement.elt;
  let frames = [];
  const frameFactory = setInterval(() => {
    frames.push(makeFrame(fName + count, ext, cnv));
    count++;
  }, 1000 / fps);

  setTimeout(() => {
    clearInterval(frameFactory);
    if (callback) {
      callback(frames);
    } else {
      for (const f of frames) {
        p5.prototype.downloadFile(f.imageData, f.filename, f.ext);
      }
    }
    frames = []; // clear frames
  }, duration + 0.01);
};

p5.prototype._makeFrame = function(filename, extension, _cnv) {
  let cnv;
  if (this) {
    cnv = this._curElement.elt;
  } else {
    cnv = _cnv;
  }
  let mimeType;
  if (!extension) {
    extension = 'png';
    mimeType = 'image/png';
  } else {
    switch (extension.toLowerCase()) {
      case 'png':
        mimeType = 'image/png';
        break;
      case 'jpeg':
        mimeType = 'image/jpeg';
        break;
      case 'jpg':
        mimeType = 'image/jpeg';
        break;
      default:
        mimeType = 'image/png';
        break;
    }
  }
  const downloadMime = 'image/octet-stream';
  let imageData = cnv.toDataURL(mimeType);
  imageData = imageData.replace(mimeType, downloadMime);

  const thisFrame = {};
  thisFrame.imageData = imageData;
  thisFrame.filename = filename;
  thisFrame.ext = extension;
  return thisFrame;
};

export default p5;