ppu-ocv 1.4.0 → 1.5.0

package/README.md

@@ -165,6 +165,42 @@ See: [How to extend ppu-ocv operations](./docs/how-to-extend-ppu-ocv-operations.
 | `getCornerPoints`       | Canvas, contour | Get four corner points for a given contour. Useful for perspective transformation (warp). |
 | `destroy`               |                 | Destroy & clean-up the memory from the contours                                           |
 
+#### `FaceDetector`
+
+Singleton class for face and eye detection using Haar Cascade classifiers.
+
+| Method        | Args                        | Description                                                            |
+| ------------- | --------------------------- | ---------------------------------------------------------------------- |
+| `getInstance` |                             | Get the singleton instance of FaceDetector                             |
+| `detectFace`  | Canvas, options             | Detect faces in the given canvas, returns `{ faces: BoundingBox[] }`   |
+| `detectEye`   | Canvas, options             | Detect eyes in the given canvas, returns `{ eyes: { left, right }[] }` |
+| `alignFace`   | Canvas, [leftEye, rightEye] | Align face based on eye positions, returns aligned Canvas              |
+
+**Usage Example:**
+
+```ts
+import { FaceDetector, ImageProcessor } from "ppu-ocv";
+
+await ImageProcessor.initRuntime();
+const file = Bun.file("./image.jpg");
+const canvas = await ImageProcessor.prepareCanvas(await file.arrayBuffer());
+
+const faceDetector = await FaceDetector.getInstance();
+
+// Detect faces
+const faceResult = await faceDetector.detectFace(canvas);
+console.log(`Found ${faceResult.faces.length} faces`);
+
+// Detect eyes
+const eyeResult = await faceDetector.detectEye(canvas);
+
+// Align face if eyes detected
+if (eyeResult.eyes.length > 0) {
+  const { left, right } = eyeResult.eyes[0];
+  const alignedCanvas = await faceDetector.alignFace(canvas, [left, right]);
+}
+```
+
 #### `ImageAnalysis`
 
 Just a collection of utility functions for analyzing image properties.

package/face-detector.d.ts

@@ -0,0 +1,70 @@
+import { Canvas } from "./index";
+import type { BoundingBox, EyesDetectorResult, FaceDetectorResult } from "./index.interface";
+export declare class FaceDetector {
+    private static instance;
+    private frontalFaceCascade;
+    private eyeCascade;
+    private eyeGlassCascade;
+    /**
+     * Private constructor to prevent direct instantiation
+     */
+    private constructor();
+    /**
+     * Get the singleton instance of FaceDetector
+     * @returns The singleton instance
+     * @example
+     * const faceDetector = await FaceDetector.getInstance();
+     */
+    static getInstance(): Promise<FaceDetector>;
+    /**
+     * Detect faces in the given canvas
+     * @param canvas Source canvas containing the image
+     * @param options Detection options
+     * @returns Promise resolving to detected faces
+     * @example
+     * const result = await faceDetector.detectFace(canvas);
+     * console.log(`Found ${result.faces.length} faces`);
+     */
+    detectFace(canvas: Canvas, options?: {
+        scaleFactor?: number;
+        minNeighbors?: number;
+        minSize?: {
+            width: number;
+            height: number;
+        };
+    }): Promise<FaceDetectorResult>;
+    /**
+     * Detect eyes in the given canvas
+     * @param canvas Source canvas containing the image
+     * @param options Detection options
+     * @returns Promise resolving to detected eyes
+     * @example
+     * const result = await faceDetector.detectEye(canvas);
+     * console.log(`Found ${result.eyes.length} eye pairs`);
+     */
+    detectEye(canvas: Canvas, options?: {
+        scaleFactor?: number;
+        minNeighbors?: number;
+        minSize?: {
+            width: number;
+            height: number;
+        };
+        useFallback?: boolean;
+    }): Promise<EyesDetectorResult>;
+    /**
+     * Detect eyes with glasses/sunglasses
+     * @param gray Grayscale cv.Mat image
+     * @param options Detection options
+     * @returns Detected eyes result
+     */
+    private detectEyeSunglass;
+    /**
+     * Align face based on eye positions
+     * @param canvas Source canvas containing the face
+     * @param eyes Tuple of left and right eye bounding boxes
+     * @returns Promise resolving to aligned face canvas
+     * @example
+     * const aligned = await faceDetector.alignFace(canvas, [leftEye, rightEye]);
+     */
+    alignFace(canvas: Canvas, eyes: [BoundingBox, BoundingBox]): Promise<Canvas>;
+}

package/face-detector.js

@@ -0,0 +1 @@
+export class FaceDetector{static instance=null;frontalFaceCascade;eyeCascade;eyeGlassCascade;constructor(){let basePath=join(process.cwd(),"src");let frontalFaceData=readFileSync(join(basePath,"haarcascade_frontalface_default.xml"));let eyeData=readFileSync(join(basePath,"haarcascade_eye.xml"));let eyeGlassData=readFileSync(join(basePath,"haarcascade_eye_tree_eyeglasses.xml"));cv.FS.writeFile("haarcascade_frontalface_default.xml",frontalFaceData);cv.FS.writeFile("haarcascade_eye.xml",eyeData);cv.FS.writeFile("haarcascade_eye_tree_eyeglasses.xml",eyeGlassData);this.frontalFaceCascade=new cv.CascadeClassifier;this.eyeCascade=new cv.CascadeClassifier;this.eyeGlassCascade=new cv.CascadeClassifier;this.frontalFaceCascade.load("haarcascade_frontalface_default.xml");this.eyeCascade.load("haarcascade_eye.xml");this.eyeGlassCascade.load("haarcascade_eye_tree_eyeglasses.xml")}static async getInstance(){await ImageProcessor.initRuntime();if(!FaceDetector.instance){FaceDetector.instance=new FaceDetector}return FaceDetector.instance}async detectFace(canvas,options={}){const{scaleFactor=1.1,minNeighbors=3,minSize={width:30,height:30}}=options;let processor=new ImageProcessor(canvas);let faces=new cv.RectVector;let minSizeMat=new cv.Size(minSize.width,minSize.height);let detectedFaces=[];try{let grayScaled=processor.grayscale().toMat();this.frontalFaceCascade.detectMultiScale(grayScaled,faces,scaleFactor,minNeighbors,0,minSizeMat);for(let i=0;i<faces.size();i++){let face=faces.get(i);detectedFaces.push({x0:face.x,y0:face.y,x1:face.x+face.width,y1:face.y+face.height})}}catch(error){}finally{faces.delete();processor.destroy()}return{faces:detectedFaces}}async detectEye(canvas,options={}){const{scaleFactor=1.05,minNeighbors=3,minSize={width:10,height:10},useFallback=true}=options;let processor=new ImageProcessor(canvas);let grayscaled=processor.grayscale().toMat();let eyes=new cv.RectVector;let minSizeMat=new cv.Size(minSize.width,minSize.height);let result;try{this.eyeCascade.detectMultiScale(grayscaled,eyes,scaleFactor,minNeighbors,0,minSizeMat);if(eyes.size()===0&&useFallback){let eyesWithGlasses=this.detectEyeSunglass(grayscaled,{scaleFactor,minNeighbors,minSize});result=eyesWithGlasses}else{let detectedEyes=[];let eyeArray=[];for(let i=0;i<eyes.size();i++){let eye=eyes.get(i);eyeArray.push({x0:eye.x,y0:eye.y,x1:eye.x+eye.width,y1:eye.y+eye.height})}eyeArray.sort((a,b)=>a.x0-b.x0);for(let i=0;i<eyeArray.length-1;i+=2){detectedEyes.push({left:eyeArray[i],right:eyeArray[i+1]})}result={eyes:detectedEyes}}}catch(error){console.error(`[detectEyes error]: `,error);result={eyes:[]}}finally{eyes.delete();processor.destroy()}return result}detectEyeSunglass(grayscale,options){const{scaleFactor,minNeighbors,minSize}=options;let eyes=new cv.RectVector;let minSizeMat=new cv.Size(minSize.width,minSize.height);this.eyeGlassCascade.detectMultiScale(grayscale,eyes,scaleFactor,minNeighbors,0,minSizeMat);let detectedEyes=[];let eyeArray=[];for(let i=0;i<eyes.size();i++){let eye=eyes.get(i);eyeArray.push({x0:eye.x,y0:eye.y,x1:eye.x+eye.width,y1:eye.y+eye.height})}eyeArray.sort((a,b)=>a.x0-b.x0);for(let i=0;i<eyeArray.length-1;i+=2){detectedEyes.push({left:eyeArray[i],right:eyeArray[i+1]})}return{eyes:detectedEyes}}async alignFace(canvas,eyes){const[leftEye,rightEye]=eyes;let leftEyeCenter={x:(leftEye.x0+leftEye.x1)/2,y:(leftEye.y0+leftEye.y1)/2};let rightEyeCenter={x:(rightEye.x0+rightEye.x1)/2,y:(rightEye.y0+rightEye.y1)/2};let deltaX=rightEyeCenter.x-leftEyeCenter.x;let deltaY=rightEyeCenter.y-leftEyeCenter.y;let angle=Math.atan2(deltaY,deltaX)*(180/Math.PI);let centerX=(leftEyeCenter.x+rightEyeCenter.x)/2;let centerY=(leftEyeCenter.y+rightEyeCenter.y)/2;let center=new cv.Point(centerX,centerY);let processor=new ImageProcessor(canvas);let rotated=processor.rotate({angle,center}).toCanvas();return rotated}}import{readFileSync}from"fs";import{join}from"path";import{cv,ImageProcessor}from"./index";

package/index.d.ts

@@ -2,10 +2,11 @@ import cv from "@techstark/opencv-js";
 export { cv };
 export { Canvas, createCanvas, ImageData, loadImage } from "@napi-rs/canvas";
 export type { SKRSContext2D } from "@napi-rs/canvas";
-export type { BoundingBox, Coordinate, Points } from "./index.interface";
+export type { BoundingBox, Coordinate, Points, EyesDetectorResult, FaceDetectorResult } from "./index.interface";
 export { executeOperation, OperationRegistry, registry } from "./pipeline";
 export { CanvasToolkit } from "./canvas-toolkit";
 export { Contours } from "./contours";
 export { calculateMeanGrayscaleValue, calculateMeanNormalizedLabLightness, type CalculateMeanLightnessOptions, } from "./image-analysis";
 export { ImageProcessor } from "./image-processor";
+export { FaceDetector } from "./face-detector";
 export type { AdaptiveThresholdOptions, BlurOptions, BorderOptions, CannyOptions, DilateOptions, ErodeOptions, GrayscaleOptions, InvertOptions, MorphologicalGradientOptions, OperationFunction, OperationName, OperationOptions, OperationResult, PartialOptions, RegisteredOperations, RequiredOptions, ResizeOptions, RotateOptions, ThresholdOptions, WarpOptions, } from "./pipeline";

package/index.interface.d.ts

@@ -14,3 +14,12 @@ export interface BoundingBox {
     x1: number;
     y1: number;
 }
+export interface FaceDetectorResult {
+    faces: BoundingBox[];
+}
+export interface EyesDetectorResult {
+    eyes: {
+        left: BoundingBox;
+        right: BoundingBox;
+    }[];
+}

package/index.js

@@ -1 +1 @@
-import cv from"@techstark/opencv-js";export{cv};export{Canvas,createCanvas,ImageData,loadImage}from"@napi-rs/canvas";export{executeOperation,OperationRegistry,registry}from"./pipeline";export{CanvasToolkit}from"./canvas-toolkit";export{Contours}from"./contours";export{calculateMeanGrayscaleValue,calculateMeanNormalizedLabLightness}from"./image-analysis";export{ImageProcessor}from"./image-processor";
+import cv from"@techstark/opencv-js";export{cv};export{Canvas,createCanvas,ImageData,loadImage}from"@napi-rs/canvas";export{executeOperation,OperationRegistry,registry}from"./pipeline";export{CanvasToolkit}from"./canvas-toolkit";export{Contours}from"./contours";export{calculateMeanGrayscaleValue,calculateMeanNormalizedLabLightness}from"./image-analysis";export{ImageProcessor}from"./image-processor";export{FaceDetector}from"./face-detector";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppu-ocv",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A type-safe, modular, chainable image processing library built on top of OpenCV.js with a fluent API leveraging pipeline processing.",
   "keywords": [
     "open-cv",