image-js 1.6.2 → 1.7.0

package/src/featureMatching/keypoints/getEigenvaluesForScore.ts

@@ -1,51 +1,53 @@
-import { EigenvalueDecomposition, Matrix, WrapperMatrix1D } from 'ml-matrix';
+import { EigenvalueDecomposition, Matrix } from 'ml-matrix';
 
 import type { Image } from '../../Image.ts';
+import { rawDirectConvolution } from '../../filters/convolution.ts';
 import type { Point } from '../../index_full.ts';
 import { SOBEL_X, SOBEL_Y } from '../../utils/constants/kernels.js';
-
 /**
  * A function that calculates eigenvalues to calculate feature score for Harris and Shi-Tomasi algorithms.
  * @param image - Image take data from.
  * @param origin - Center of the window, where the corner should be.
- * @param windowSize - Size of the window, where data should be scanned.
+ * @param cropSize - Size of the window, where data should be scanned.
  * @returns Array of two eigenvalues.
  */
 export function getEigenvaluesForScore(
   image: Image,
   origin: Point,
-  windowSize = 7,
+  cropSize = 5,
 ) {
-  if (!(windowSize % 2)) {
+  if (!(cropSize % 2)) {
     throw new TypeError('windowSize must be an odd integer');
   }
-
+  const kernelRadius = (SOBEL_X.length - 1) / 2;
+  const windowRadius = (cropSize - 1) / 2;
+  const padded = cropSize + 2 * kernelRadius;
   const cropOrigin = {
-    row: origin.row - (windowSize - 1) / 2,
-    column: origin.column - (windowSize - 1) / 2,
+    row: origin.row - windowRadius - kernelRadius,
+    column: origin.column - windowRadius - kernelRadius,
   };
   const window = image.crop({
     origin: cropOrigin,
-    width: windowSize,
-    height: windowSize,
-  });
-  const xDerivative = window.gradientFilter({ kernelX: SOBEL_X });
-  const yDerivative = window.gradientFilter({ kernelY: SOBEL_Y });
-
-  const xMatrix = new WrapperMatrix1D(xDerivative.getRawImage().data, {
-    rows: xDerivative.height,
+    width: padded,
+    height: padded,
   });
-  const yMatrix = new WrapperMatrix1D(yDerivative.getRawImage().data, {
-    rows: yDerivative.height,
-  });
-
-  const xx = xMatrix.mmul(xMatrix);
-  const xy = yMatrix.mmul(xMatrix);
-  const yy = yMatrix.mmul(yMatrix);
-
-  const xxSum = xx.sum();
-  const xySum = xy.sum();
-  const yySum = yy.sum();
+  const xDerivative = rawDirectConvolution(window, SOBEL_X);
+  const yDerivative = rawDirectConvolution(window, SOBEL_Y);
+
+  let xxSum = 0;
+  let xySum = 0;
+  let yySum = 0;
+
+  for (let i = kernelRadius; i < window.height - kernelRadius; i++) {
+    for (let j = kernelRadius; j < window.width - kernelRadius; j++) {
+      const idx = i * window.width + j;
+      const gx = xDerivative[idx];
+      const gy = yDerivative[idx];
+      xxSum += gx * gx;
+      xySum += gx * gy;
+      yySum += gy * gy;
+    }
+  }
 
   const structureTensor = new Matrix([
     [xxSum, xySum],

package/src/featureMatching/keypoints/getFastKeypoints.ts

@@ -41,6 +41,10 @@ export interface GetFastKeypointsOptions extends IsFastKeypointOptions {
    * @default `'FAST'`
    */
   scoreAlgorithm?: 'HARRIS' | 'FAST' | 'TOMASI';
+  /**
+   * Value between 0 and 1 that signifies a percentage from maximum score found in the image. Points can be filtered based on this relative maximum score.
+   */
+  qualityThreshold?: number;
   /**
    * Options for the Harris score computation.
    */
@@ -72,7 +76,7 @@ export function getFastKeypoints(
   options: GetFastKeypointsOptions = {},
 ): FastKeypoint[] {
   const { fastRadius = 3, scoreAlgorithm = 'FAST', scoreOptions } = options;
-
+  const windowSize = scoreOptions?.windowSize ?? 7;
   const circlePoints = getCirclePoints(fastRadius);
   const compassPoints = getCompassPoints(fastRadius);
 
@@ -81,6 +85,7 @@ export function getFastKeypoints(
     nbContiguousPixels = (3 / 4) * circlePoints.length,
     threshold = 20,
     nonMaxSuppression = true,
+    qualityThreshold = 0,
   } = options;
 
   checkProcessable(image, {
@@ -108,13 +113,14 @@ export function getFastKeypoints(
     .with('TOMASI', () => tomasiScore)
     .exhaustive();
 
+  const padding = scoreAlgorithm === 'FAST' ? 0 : (windowSize + 1) / 2;
   const allKeypoints: FastKeypoint[] = [];
 
   const scoreArray = new Float64Array(image.size).fill(
     Number.NEGATIVE_INFINITY,
   );
-  for (let row = 0; row < image.height; row++) {
-    for (let column = 0; column < image.width; column++) {
+  for (let row = padding; row < image.height - padding; row++) {
+    for (let column = padding; column < image.width - padding; column++) {
       const corner = { row, column };
       if (
         isFastKeypoint(corner, image, circlePoints, compassPoints, {
@@ -157,8 +163,20 @@ export function getFastKeypoints(
       }
     }
   }
+  let maxScore = -Infinity;
+  for (const k of keypoints) {
+    if (k.score > maxScore) maxScore = k.score;
+  }
+  const filtered: FastKeypoint[] = [];
+  // threshold by default negative infinity
+  const filterThreshold = qualityThreshold * maxScore;
 
-  keypoints.sort((a, b) => b.score - a.score);
+  for (const k of keypoints) {
+    if (k.score >= filterThreshold) {
+      k.score /= maxScore;
+      filtered.push(k);
+    }
+  }
 
-  return keypoints.slice(0, maxNbFeatures);
+  return filtered.toSorted((a, b) => b.score - a.score).slice(0, maxNbFeatures);
 }

package/src/featureMatching/keypoints/getHarrisScore.ts

@@ -24,7 +24,7 @@ export function getHarrisScore(
   origin: Point,
   options: GetHarrisScoreOptions = {},
 ): number {
-  const { harrisConstant = 0.04, windowSize } = options;
+  const { harrisConstant = 0.04, windowSize = 5 } = options;
   const eigenValues = getEigenvaluesForScore(image, origin, windowSize);
 
   return (

package/src/featureMatching/keypoints/getShiTomasiScore.ts

@@ -4,11 +4,10 @@ import type { Point } from '../../index_full.ts';
 import { getEigenvaluesForScore } from './getEigenvaluesForScore.js';
 
 export interface GetShiTomasiScoreOptions {
-  qualityLevel?: number;
   /**
    * Size of the window to compute the Harris score.
    * Should be an odd number so that the window can be centered on the corner.
-   * @default `7`
+   * @default `5`
    */
   windowSize?: number;
 }
@@ -29,7 +28,7 @@ export function getShiTomasiScore(
   origin: Point,
   options: GetShiTomasiScoreOptions = {},
 ): number {
-  const { windowSize = 7 } = options;
+  const { windowSize = 5 } = options;
 
   const eigenValues = getEigenvaluesForScore(image, origin, windowSize);
   return Math.min(eigenValues[0], eigenValues[1]);

package/src/featureMatching/visualize/drawKeypoints.ts

@@ -1,5 +1,7 @@
 import type { Image } from '../../Image.js';
 import type { Point } from '../../geometry/index.js';
+import type { DrawTextOptions } from '../../index_full.ts';
+import { drawText } from '../../index_full.ts';
 import { sum } from '../../utils/geometry/points.js';
 import { getOutputImage } from '../../utils/getOutputImage.js';
 import type { GetColorsOptions } from '../featureMatching.types.js';
@@ -47,7 +49,7 @@ export interface DrawKeypointsOptions {
   /**
    * Options for the coloring of the keypoints depending on their score (useful if showScore = true).
    */
-  showScoreOptions?: GetColorsOptions;
+  showScoreOptions?: GetColorsOptions & DrawTextOptions;
 }
 
 export interface DrawOrientedKeypointsOptions extends DrawKeypointsOptions {
@@ -89,7 +91,8 @@ export function drawKeypoints(
   } = options;
   let { maxNbKeypoints = keypoints.length } = options;
   const { strokeColor = [255, 0, 0] } = options;
-
+  const fontColor = showScoreOptions?.fontColor ?? [0, 0, 255];
+  const font = showScoreOptions?.font ?? '20px Helvetica';
   if (maxNbKeypoints > keypoints.length) {
     maxNbKeypoints = keypoints.length;
   }
@@ -118,6 +121,7 @@ export function drawKeypoints(
       strokeColor: keypointColor,
       out: newImage,
     });
+
     if (
       isOrientedFastKeypoint(keypoint) &&
       (options as DrawOrientedKeypointsOptions).showOrientation
@@ -135,7 +139,20 @@ export function drawKeypoints(
       });
     }
   }
-
+  if (showScore) {
+    drawText(
+      newImage,
+      keypoints.map((k) => ({
+        content: (k.score * 100).toFixed(2),
+        position: sum(k.origin, origin),
+        font,
+        fontColor: [...fontColor, 255],
+      })),
+      {
+        out: newImage,
+      },
+    );
+  }
   return newImage;
 }
 

package/src/maskAnalysis/getContourMoore.ts

@@ -55,9 +55,10 @@ export function getContourMoore(mask: Mask): Point[] {
   const [row, col] = getCoordsFromIndex(index, mask.width);
   const startingPoint = { column: col, row };
   let currentPoint = startingPoint;
-
-  visited[index] = 1;
-  contour.push(currentPoint);
+  if (!visited[index]) {
+    visited[index] = 1;
+    contour.push(currentPoint);
+  }
 
   const firstNext = findNextPoint(mask, currentPoint, { column: col - 1, row });
   if (!firstNext) {

package/src/maskAnalysis/getConvexityDefects.ts

@@ -0,0 +1,105 @@
+import type { Point } from '../index_full.ts';
+
+export interface ConvexityDefectsOptions {
+  /**
+   * Depth threshold to remove smaller convexity defaults.
+   * @default 0
+   */
+  depthThreshold?: number;
+}
+
+/**
+ * Find border points that are farthest from its convex hull lines. Inspired by openCV's convexityDefects.
+ * @param borderPoints - Mask's border points.
+ * @param hullPoints - Mask's convex hull points.
+ * @param options - Convexity defects options.
+ * @returns Array of convexity defects.
+ */
+export function getConvexityDefects(
+  borderPoints: Point[],
+  hullPoints: Point[],
+  options: ConvexityDefectsOptions = {},
+): Point[] {
+  const { depthThreshold = 0 } = options;
+  const defects = [];
+
+  if (hullPoints.length === 0) {
+    throw new RangeError(
+      'No hull points were defined for convexity defects detection.',
+    );
+  }
+  if (borderPoints.length === 0) {
+    throw new RangeError(
+      'No border points were defined for convexity defects detection.',
+    );
+  }
+
+  const lastHullPoint = hullPoints.at(-1) as Point;
+
+  let currBorderIndex = borderPoints.findIndex((bp) =>
+    limitReached(bp, lastHullPoint),
+  );
+
+  if (currBorderIndex === -1) {
+    throw new RangeError(
+      'Could not find a border point matching the convex hull endpoint.',
+    );
+  }
+  for (let i = hullPoints.length - 1; i >= 0; i--) {
+    const currHullPoint = hullPoints.at(i);
+    const nextHullPoint = hullPoints.at(i - 1);
+    if (!currHullPoint || !nextHullPoint) continue;
+    const v0x = nextHullPoint.column - currHullPoint.column;
+    const v0y = nextHullPoint.row - currHullPoint.row;
+    const edgeLenSq = v0x * v0x + v0y * v0y;
+    let maxDepth = 0;
+    let maxDepthIndex = -1;
+    const segmentStart = currBorderIndex;
+    let reached = false;
+    for (let j = 0; j < borderPoints.length; j++) {
+      const checkIndex = (segmentStart + j) % borderPoints.length;
+      const bp = borderPoints[checkIndex];
+      if (limitReached(bp, nextHullPoint)) {
+        currBorderIndex = (checkIndex + 1) % borderPoints.length;
+        reached = true;
+        break;
+      }
+
+      const v1x = bp.column - currHullPoint.column;
+      const v1y = bp.row - currHullPoint.row;
+
+      const t = Math.max(0, Math.min(1, (v1x * v0x + v1y * v0y) / edgeLenSq));
+      const closestX = currHullPoint.column + t * v0x;
+      const closestY = currHullPoint.row + t * v0y;
+      const depth = Math.hypot(bp.column - closestX, bp.row - closestY);
+      if (depth > maxDepth) {
+        maxDepth = depth;
+        maxDepthIndex = checkIndex;
+      }
+    }
+    if (!reached) {
+      throw new RangeError(
+        'Could not reach the next hull point while scanning border points; hull and border may be inconsistent.',
+      );
+    }
+    if (maxDepth > depthThreshold) {
+      const defectPoint = borderPoints[maxDepthIndex];
+      if (defectPoint) defects.push(defectPoint);
+    }
+  }
+
+  return defects;
+}
+/**
+ * Checks if borderPoint reached convex hull's point.
+ * @param borderPoint - Border point.
+ * @param hullPoint - Endpoint of convex hull segment.
+ * @returns whether endpoint is reached.
+ */
+function limitReached(borderPoint: Point, hullPoint: Point): boolean {
+  const tolerance = 1;
+  return (
+    Math.abs(borderPoint.column - hullPoint.column) <= tolerance &&
+    Math.abs(borderPoint.row - hullPoint.row) <= tolerance
+  );
+}

package/src/maskAnalysis/index.ts

@@ -1 +1,2 @@
 export * from './maskAnalysis.types.js';
+export * from './getConvexityDefects.ts';