ppu-ocv 1.3.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/image-processor.d.ts

@@ -14,7 +14,14 @@ export declare class ImageProcessor {
      * @param source Source image as Canvas or cv.Mat
      */
     constructor(source: Canvas | cv.Mat);
+    /**
+     * Convert array buffer to canvas
+     */
     static prepareCanvas(file: ArrayBuffer): Promise<Canvas>;
+    /**
+     * Convert canvas to array buffer
+     */
+    static prepareBuffer(canvas: Canvas): Promise<ArrayBuffer>;
     /**
      * Initialize OpenCV runtime, this is recommended to be called before any image processing
      */

package/image-processor.js

@@ -1 +1 @@
-export class ImageProcessor{img;width;height;constructor(source){if(source instanceof Canvas){let ctx=source.getContext("2d");let imageData=ctx.getImageData(0,0,source.width,source.height);this.img=cv.matFromImageData(imageData);this.width=source.width;this.height=source.height}else if(source instanceof cv.Mat){this.img=source;this.width=source.cols;this.height=source.rows}else{throw new Error("Invalid source type. Must be either Canvas or cv.Mat.")}}static async prepareCanvas(file){let img=await loadImage(file);let canvas=createCanvas(img.width,img.height);let ctx=canvas.getContext("2d");ctx.drawImage(img,0,0);return canvas}static async initRuntime(){return new Promise((res)=>{if(cv&&cv.Mat){res()}else{cv["onRuntimeInitialized"]=()=>{res()}}})}execute(operationName,options){if(!registry.hasOperation(operationName)){throw new Error(`Operation "${operationName}" not found`)}try{let result=executeOperation(operationName,this.img,options);this.img=result.img;this.width=result.width;this.height=result.height}catch(error){console.error(`Error executing operation "${operationName}":`,error);throw error}return this}grayscale(options={}){return this.execute("grayscale",options)}invert(options={}){return this.execute("invert",options)}border(options={}){return this.execute("border",options)}blur(options={}){return this.execute("blur",options)}threshold(options={}){return this.execute("threshold",options)}adaptiveThreshold(options={}){return this.execute("adaptiveThreshold",options)}canny(options={}){return this.execute("canny",options)}morphologicalGradient(options={}){return this.execute("morphologicalGradient",options)}erode(options={}){return this.execute("erode",options)}dilate(options={}){return this.execute("dilate",options)}resize(options){return this.execute("resize",options)}warp(options){return this.execute("warp",options)}rotate(options){return this.execute("rotate",options)}convert(options){return this.execute("convert",options)}destroy(){this.img.delete()}toMat(){return this.img}toCanvas(){let canvas=createCanvas(this.width,this.height);let ctx=canvas.getContext("2d");let imgData=ctx.createImageData(this.width,this.height);if(this.img.channels()===1){let data=imgData.data;let gray=new Uint8Array(this.img.data);for(let i=0;i<gray.length;i++){data[i*4]=gray[i];data[i*4+1]=gray[i];data[i*4+2]=gray[i];data[i*4+3]=255}}else{imgData.data.set(new Uint8ClampedArray(this.img.data))}ctx.putImageData(imgData,0,0);return canvas}}import{Canvas,createCanvas,cv,loadImage}from"./index";import{executeOperation,registry}from"./index";
+export class ImageProcessor{img;width;height;constructor(source){if(source instanceof Canvas){let ctx=source.getContext("2d");let imageData=ctx.getImageData(0,0,source.width,source.height);this.img=cv.matFromImageData(imageData);this.width=source.width;this.height=source.height}else if(source instanceof cv.Mat){this.img=source;this.width=source.cols;this.height=source.rows}else{throw new Error("Invalid source type. Must be either Canvas or cv.Mat.")}}static async prepareCanvas(file){if(file instanceof Canvas)return file;let img=await loadImage(file);let canvas=createCanvas(img.width,img.height);let ctx=canvas.getContext("2d");ctx.drawImage(img,0,0);return canvas}static async prepareBuffer(canvas){if(canvas instanceof ArrayBuffer)return canvas;if(typeof canvas.toBuffer==="function"){let buffer=canvas.toBuffer("image/png");let arrayBuffer=new ArrayBuffer(buffer.byteLength);new Uint8Array(arrayBuffer).set(new Uint8Array(buffer));return arrayBuffer}if(typeof canvas.toDataURL==="function"){let dataURL=canvas.toDataURL("image/png");let base64Data=dataURL.replace(/^data:image\/png;base64,/,"");let buffer=Buffer.from(base64Data,"base64");let arrayBuffer=new ArrayBuffer(buffer.byteLength);new Uint8Array(arrayBuffer).set(new Uint8Array(buffer));return arrayBuffer}let ctx=canvas.getContext("2d");let imageData=ctx.getImageData(0,0,canvas.width,canvas.height);let canvasBuffer=new ArrayBuffer(imageData.data.byteLength);new Uint8Array(canvasBuffer).set(new Uint8Array(imageData.data.buffer,imageData.data.byteOffset,imageData.data.byteLength));return canvasBuffer}static async initRuntime(){return new Promise((res)=>{if(cv&&cv.Mat){res()}else{cv["onRuntimeInitialized"]=()=>{res()}}})}execute(operationName,options){if(!registry.hasOperation(operationName)){throw new Error(`Operation "${operationName}" not found`)}try{let result=executeOperation(operationName,this.img,options);this.img=result.img;this.width=result.width;this.height=result.height}catch(error){console.error(`Error executing operation "${operationName}":`,error);throw error}return this}grayscale(options={}){return this.execute("grayscale",options)}invert(options={}){return this.execute("invert",options)}border(options={}){return this.execute("border",options)}blur(options={}){return this.execute("blur",options)}threshold(options={}){return this.execute("threshold",options)}adaptiveThreshold(options={}){return this.execute("adaptiveThreshold",options)}canny(options={}){return this.execute("canny",options)}morphologicalGradient(options={}){return this.execute("morphologicalGradient",options)}erode(options={}){return this.execute("erode",options)}dilate(options={}){return this.execute("dilate",options)}resize(options){return this.execute("resize",options)}warp(options){return this.execute("warp",options)}rotate(options){return this.execute("rotate",options)}convert(options){return this.execute("convert",options)}destroy(){this.img.delete()}toMat(){return this.img}toCanvas(){let canvas=createCanvas(this.width,this.height);let ctx=canvas.getContext("2d");let imgData=ctx.createImageData(this.width,this.height);if(this.img.channels()===1){let data=imgData.data;let gray=new Uint8Array(this.img.data);for(let i=0;i<gray.length;i++){data[i*4]=gray[i];data[i*4+1]=gray[i];data[i*4+2]=gray[i];data[i*4+3]=255}}else{imgData.data.set(new Uint8ClampedArray(this.img.data))}ctx.putImageData(imgData,0,0);return canvas}}import{Canvas,createCanvas,cv,loadImage}from"./index";import{executeOperation,registry}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.3.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",
@@ -37,6 +37,7 @@
     "eslint": "latest",
     "eslint-plugin-jsdoc": "latest",
     "mitata": "latest",
+    "prettier": "^3.6.2",
     "tsx": "latest",
     "typescript": "latest",
     "typescript-eslint": "latest",