image-js 1.4.0 → 1.6.0

package/dist/image-js.umd.js

@@ -1,15 +1,15 @@
 /*
- * image-js v1.4.0
+ * image-js v1.6.0
  * Image processing and manipulation in JavaScript
  * https://github.com/image-js/image-js#readme
  *
  * Licensed under the MIT license.
  */
 (function (global, factory) {
-	typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
-	typeof define === 'function' && define.amd ? define(['exports'], factory) :
-	(global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.IJS = {}));
-})(this, (function (exports) { 'use strict';
+	typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports, require('node:assert')) :
+	typeof define === 'function' && define.amd ? define(['exports', 'node:assert'], factory) :
+	(global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.IJS = {}, global.assert$1));
+})(this, (function (exports, assert$1) { 'use strict';
 
 	var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 	function getDefaultExportFromCjs (x) {
@@ -13966,6 +13966,287 @@ ${indent}columns: ${matrix.columns}
 	  return Math.abs(area / 2);
 	}
 
+	/**
+	 * Gets point's row and column from their index and mask width.
+	 * @param index - point's index.
+	 * @param maskWidth - mask width.
+	 * @returns array of point's row and column.
+	 */
+	function getCoordsFromIndex(index, maskWidth) {
+	  return [Math.floor(index / maskWidth), index % maskWidth];
+	}
+	/**
+	 * Safely get the bit value at the given column and row in the mask, returning 0 if out of bounds.
+	 * @param mask - Mask to get the bit from.
+	 * @param col - Column index.
+	 * @param row - Row index.
+	 * @returns the bit value.
+	 */
+	function getBitSafe(mask, col, row) {
+	  if (!isInBounds(mask, col, row)) return 0;
+	  return mask.getBit(col, row);
+	}
+	/**
+	 * Checks if the given column and row are within the bounds of the mask.
+	 * @param mask - Mask to check against.
+	 * @param col - Column index.
+	 * @param row - Row index.
+	 * @returns whether the given column and row are within the bounds of the mask.
+	 */
+	function isInBounds(mask, col, row) {
+	  return col >= 0 && col < mask.width && row >= 0 && row < mask.height;
+	}
+
+	/**
+	 * Possible directions.
+	 */
+	const directions = [{
+	  dc: -1,
+	  dr: 0
+	},
+	// left
+	{
+	  dc: -1,
+	  dr: -1
+	},
+	// up-left
+	{
+	  dc: 0,
+	  dr: -1
+	},
+	// up
+	{
+	  dc: 1,
+	  dr: -1
+	},
+	// up-right
+	{
+	  dc: 1,
+	  dr: 0
+	},
+	// right
+	{
+	  dc: 1,
+	  dr: 1
+	},
+	// down-right
+	{
+	  dc: 0,
+	  dr: 1
+	},
+	// down
+	{
+	  dc: -1,
+	  dr: 1
+	} // down-left
+	];
+	// Lookup table for directions' index.
+	const directionIndexLookup = new Int8Array(9).fill(-1);
+	for (let i = 0; i < directions.length; i++) {
+	  const {
+	    dc,
+	    dr
+	  } = directions[i];
+	  directionIndexLookup[(dr + 1) * 3 + (dc + 1)] = i;
+	}
+	/**
+	 * Return an array with the coordinates of the pixels that are on the border of the mask using Moore's tracing algorithm.
+	 * The reference is the top-left corner of the ROI.
+	 * @param mask - Mask to process.
+	 * @returns The array of border pixels.
+	 */
+	function getContourMoore(mask) {
+	  let index = 0;
+	  const contour = [];
+	  const visited = new Uint8Array(mask.width * mask.height);
+	  while (mask.getBitByIndex(index) !== 1 && index !== mask.size) {
+	    index++;
+	  }
+	  if (index === mask.size) return contour;
+	  const [row, col] = getCoordsFromIndex(index, mask.width);
+	  const startingPoint = {
+	    column: col,
+	    row
+	  };
+	  let currentPoint = startingPoint;
+	  visited[index] = 1;
+	  contour.push(currentPoint);
+	  const firstNext = findNextPoint(mask, currentPoint, {
+	    column: col - 1,
+	    row
+	  });
+	  if (!firstNext) {
+	    return contour;
+	  }
+	  let startingBacktrackPoint = firstNext.prevPoint;
+	  let backtrackPoint = firstNext.prevPoint;
+	  currentPoint = firstNext.currPoint;
+	  while (true) {
+	    index = currentPoint.row * mask.width + currentPoint.column;
+	    if (!visited[index]) {
+	      visited[index] = 1;
+	      contour.push(currentPoint);
+	    }
+	    const next = findNextPoint(mask, currentPoint, backtrackPoint);
+	    assert$1.ok(next, 'Next border point is undefined.');
+	    backtrackPoint = next.prevPoint;
+	    currentPoint = next.currPoint;
+	    if (currentPoint.column === startingPoint.column && currentPoint.row === startingPoint.row) {
+	      if (backtrackPoint.column === startingBacktrackPoint.column && backtrackPoint.row === startingBacktrackPoint.row) {
+	        break;
+	      } else {
+	        startingBacktrackPoint = backtrackPoint;
+	      }
+	    }
+	  }
+	  return contour;
+	}
+	/**
+	 * Finds next point to trace.
+	 * @param mask - Mask in check.
+	 * @param current - Current border point.
+	 * @param previous - Last non-border point to start search from.
+	 * @returns Object with new border point and last non-border point.
+	 */
+	function findNextPoint(mask, current, previous) {
+	  let prevPoint = previous;
+	  // Vector from current back to previous
+	  const backDc = previous.column - current.column;
+	  const backDr = previous.row - current.row;
+	  const startIndex = directionIndexLookup[(backDr + 1) * 3 + (backDc + 1)];
+	  // Scan clockwise starting from that index.
+	  for (let i = 0; i < directions.length; i++) {
+	    const {
+	      dc,
+	      dr
+	    } = directions.at((startIndex + i) % directions.length);
+	    const newCol = current.column + dc;
+	    const newRow = current.row + dr;
+	    if (getBitSafe(mask, newCol, newRow) === 1) {
+	      // Stores found border point and last non-border point that
+	      // was found. Will be used as a starting point in the next
+	      // iteration.
+	      return {
+	        prevPoint,
+	        currPoint: {
+	          column: newCol,
+	          row: newRow
+	        }
+	      };
+	    } else {
+	      prevPoint = {
+	        column: newCol,
+	        row: newRow
+	      };
+	    }
+	  }
+	  // Is triggered only if the point has no neighbours. So it is undefined
+	  // only if mask is made of one pixel.
+	  return undefined;
+	}
+
+	const DR = [-1, 0, 1, 0];
+	const DC = [0, 1, 0, -1];
+	function turnLeft(d) {
+	  return (d + 3) % 4;
+	}
+	function turnRight(d) {
+	  return (d + 1) % 4;
+	}
+	/**
+	 * Return an array with the coordinates of the pixels that are on the
+	 * external border of the mask using Theo Pavlidis's tracing algorithm.
+	 * The reference is the top-left corner of the ROI.
+	 * @param mask - Mask to process.
+	 * @returns The array of external border pixels.
+	 */
+	function getContourPavlidis(mask) {
+	  let index = 0;
+	  while (index < mask.size && mask.getBitByIndex(index) !== 1) {
+	    index++;
+	  }
+	  if (index === mask.size) return [];
+	  const [row, col] = getCoordsFromIndex(index, mask.width);
+	  return traceFrom(mask, col, row);
+	}
+	/**
+	 * Traces contour using Pavlidis algorithm.
+	 * @param mask - Mask in check.
+	 * @param startCol - Starting column.
+	 * @param startRow - Starting row.
+	 * @returns Array of contour points.
+	 */
+	function traceFrom(mask, startCol, startRow) {
+	  let row = startRow;
+	  let column = startCol;
+	  let dir = 2;
+	  let inPlaceTurns = 0;
+	  const seen = new Uint8Array(mask.width * mask.height);
+	  const contour = [];
+	  let visits = 0;
+	  while (true) {
+	    const idx = row * mask.width + column;
+	    if (!seen[idx]) {
+	      seen[idx] = 1;
+	      contour.push({
+	        row,
+	        column
+	      });
+	    } else if (row === startRow && column === startCol) {
+	      if (visits === 2) {
+	        break;
+	      } else {
+	        visits++;
+	      }
+	    }
+	    const left = turnLeft(dir);
+	    const right = turnRight(dir);
+	    const c1r = row + DR[left];
+	    const c1c = column + DC[left];
+	    const c2r = row + DR[dir];
+	    const c2c = column + DC[dir];
+	    const c3r = row + DR[right];
+	    const c3c = column + DC[right];
+	    if (getBitSafe(mask, c1c, c1r) === 1) {
+	      dir = left;
+	      row = c1r;
+	      column = c1c;
+	      inPlaceTurns = 0;
+	    } else if (getBitSafe(mask, c2c, c2r) === 1) {
+	      row = c2r;
+	      column = c2c;
+	      inPlaceTurns = 0;
+	    } else if (getBitSafe(mask, c3c, c3r) === 1) {
+	      dir = right;
+	      row = c3r;
+	      column = c3c;
+	      inPlaceTurns = 0;
+	    } else {
+	      dir = right;
+	      inPlaceTurns++;
+	      if (inPlaceTurns >= 4) break;
+	    }
+	  }
+	  return contour;
+	}
+
+	/**
+	 * Finds external contour of the mask.
+	 * @param mask - Mask to find contours from.
+	 * @param options - GetExternalContourOptions.
+	 * @returns Array of contour points.
+	 */
+	function getExternalContour$1(mask, options = {}) {
+	  const {
+	    allowCorners = false
+	  } = options;
+	  if (allowCorners) {
+	    return getContourPavlidis(mask);
+	  } else {
+	    return getContourMoore(mask);
+	  }
+	}
+
 	/**
 	 * Get the pixels that surround an ROI. The pixels include the top and left borders,
 	 * but extend the right and bottom one by one pixel.
@@ -13975,10 +14256,7 @@ ${indent}columns: ${matrix.columns}
 	 * @returns - The array of points.
 	 */
 	function getExtendedBorderPoints(mask) {
-	  const borderPoints = mask.getBorderPoints({
-	    allowCorners: true,
-	    innerBorders: false
-	  });
+	  const borderPoints = getExternalContour$1(mask);
 	  const result = [];
 	  for (const point of borderPoints) {
 	    result.push(point, {
@@ -15608,6 +15886,15 @@ ${indent}columns: ${matrix.columns}
 	  getBorderPoints(options) {
 	    return getBorderPoints$1(this, options);
 	  }
+	  /**
+	   * Returns external contour of the mask. Unlike border points, returned points
+	   * follow the shape of the mask.
+	   * @param options - Get external contour options.
+	   * @returns Array of contour points.
+	   */
+	  getExternalContour(options) {
+	    return getExternalContour$1(this, options);
+	  }
 	  /**
 	   * Get the vertices of the convex Hull polygon of a mask.
 	   * @returns Array of the vertices of the convex Hull in clockwise order.
@@ -23211,13 +23498,22 @@ ${indent}columns: ${matrix.columns}
 	let CanvasCtorNode;
 	/**
 	 * Returns a 2D canvas context for rendering on the browser or Node.js.
+	 * On Node.js this requires the optional `skia-canvas` package to be installed.
 	 * @param width - Width of the canvas.
 	 * @param height - Height of the canvas.
 	 * @returns The initialised canvas context.
 	 */
 	function getCanvasContext(width, height) {
 	  if (isNode()) {
-	    CanvasCtorNode ??= getRequireFn()('skia-canvas').Canvas;
+	    if (!CanvasCtorNode) {
+	      try {
+	        CanvasCtorNode = getRequireFn()('skia-canvas').Canvas;
+	      } catch (error) {
+	        throw new Error('drawText on Node.js requires the optional "skia-canvas" package. Install it with: npm install skia-canvas', {
+	          cause: error
+	        });
+	      }
+	    }
 	    return new CanvasCtorNode(width, height).getContext('2d');
 	  } else {
 	    CanvasCtorBrowser ??= globalThis.OffscreenCanvas;
@@ -26557,6 +26853,17 @@ ${indent}columns: ${matrix.columns}
 	  return mask.getBorderPoints(options);
 	}
 
+	/**
+	 * Finds external contour of the roi from its mask.
+	 * @param roi - roi to find contour from.
+	 * @param options - GetExternalContourOptions.
+	 * @returns Array of contour points.
+	 */
+	function getExternalContour(roi, options) {
+	  const mask = roi.getMask();
+	  return mask.getExternalContour(options);
+	}
+
 	/**
 	 * Generate a mask of an ROI.
 	 * @param roi - The ROI to generate a mask for.
@@ -26760,6 +27067,14 @@ ${indent}columns: ${matrix.columns}
 	  getBorderPoints(options) {
 	    return getBorderPoints(this, options);
 	  }
+	  /**
+	   * Finds external contour of the roi from its mask.
+	   * @param options - GetExternalContourOptions.
+	   * @returns Array of contour points.
+	   */
+	  getExternalContour(options) {
+	    return getExternalContour(this, options);
+	  }
 	  /**
 	   * Returns an array of ROIs IDs that are included in the current ROI.
 	   * This will be useful to know if there are some holes in the ROI.