<properties>
    <java.version>17</java.version>
    <opencv.version>4.7.0-0</opencv.version>
</properties>
<dependencies>
    <dependency>
        <groupId>org.openpnp</groupId>
        <artifactId>opencv</artifactId>
        <version>${opencv.version}</version>
    </dependency>
</dependencies>

import nu.pattern.OpenCV;
import org.opencv.core.Core;

OpenCV.loadLocally();
System.out.println("OpenCV version = " + Core.VERSION);

models/haarcascade_frontalface_default.xml

Mat src = Imgcodecs.imread("D:/in.jpg");   // 讀圖，失敗返回 empty Mat
if (src.empty()) { /* 處理讀取失敗 */ }
boolean ok = Imgcodecs.imwrite("D:/out.png", src);  // 寫圖，返回是否成功

Mat gray = new Mat();
Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);   // BGR -> 灰度
Imgproc.cvtColor(src, dst, Imgproc.COLOR_BGR2HSV);    // BGR -> HSV（常用于顏色分割）

Imgproc.GaussianBlur(src, dst, new Size(5, 5), 0);

Mat edges = new Mat();
Imgproc.Canny(gray, edges, 100, 200);   // 雙閾值(低,高)，結(jié)果二值圖
int edgePoints = Core.countNonZero(edges);  // 統(tǒng)計(jì)邊緣像素?cái)?shù)

// 固定閾值
Imgproc.threshold(gray, binary, 127, 255, Imgproc.THRESH_BINARY);
// OTSU 自動(dòng)閾值（返回實(shí)際閾值）
double t = Imgproc.threshold(gray, binary, 0, 255,
        Imgproc.THRESH_BINARY | Imgproc.THRESH_OTSU);

List<MatOfPoint> contours = new ArrayList<>();
Mat hierarchy = new Mat();
Imgproc.findContours(binary, contours, hierarchy,
        Imgproc.RETR_EXTERNAL, Imgproc.CHAIN_APPROX_SIMPLE);  // 入?yún)⒈仨毷嵌祱D
Imgproc.drawContours(src, contours, -1, new Scalar(0, 0, 255), 2);  // -1 畫全部輪廓

for (MatOfPoint c : contours) {
    Rect r = Imgproc.boundingRect(c);     // 外接矩形
    double area = Imgproc.contourArea(c); // 面積
    // 外接圓
    Point center = new Point();
    float[] radius = new float[1];
    Imgproc.minEnclosingCircle(new MatOfPoint2f(c.toArray()), center, radius);
}

Scalar red = new Scalar(0, 0, 255);     // BGR：紅
Imgproc.rectangle(canvas, new Point(30, 30), new Point(170, 130), red, 3);  // 線寬3
Imgproc.rectangle(canvas, new Point(30,30), new Point(170,130), red, -1);   // 線寬-1=實(shí)心填充
Imgproc.circle(canvas, new Point(300, 200), 60, new Scalar(0, 255, 0), -1); // 綠圓實(shí)心
Imgproc.line(canvas, new Point(20, 260), new Point(380, 260), new Scalar(0,0,255), 2);
Imgproc.putText(canvas, "Hello OpenCV", new Point(60, 290),
        Imgproc.FONT_HERSHEY_SIMPLEX, 1.0, new Scalar(0,0,0), 2);

CascadeClassifier cascade = new CascadeClassifier("models/haarcascade_frontalface_default.xml");
MatOfRect faces = new MatOfRect();
cascade.detectMultiScale(gray, faces);   // 輸入灰度圖
for (Rect r : faces.toArray()) {
    Imgproc.rectangle(src, r, new Scalar(0, 255, 0), 2);  // 給每張臉畫綠框
}

Mat canvas = new Mat(300, 400, CvType.CV_8UC3, new Scalar(255, 255, 255)); // 白底 400x300

Mat src = Imgcodecs.imread(in);
try {
    Mat dst = new Mat();
    Imgproc.cvtColor(src, dst, Imgproc.COLOR_BGR2GRAY);
    Imgcodecs.imwrite(out, dst);
    dst.release();
} finally {
    src.release();
}

Mat src = Imgcodecs.imread("D:/in.jpg");
Mat gray = new Mat();
try {
    Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
    Imgcodecs.imwrite("D:/gray.jpg", gray);
} finally {
    src.release(); gray.release();
}

Mat src = Imgcodecs.imread("D:/in.jpg");
Mat gray = new Mat();
Mat edges = new Mat();
try {
    Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
    Imgproc.GaussianBlur(gray, gray, new Size(3, 3), 0); // 先降噪效果好
    Imgproc.Canny(gray, edges, 100, 200);
    Imgcodecs.imwrite("D:/edges.png", edges);
    System.out.println("邊緣點(diǎn)數(shù)=" + Core.countNonZero(edges));
} finally {
    src.release(); gray.release(); edges.release();
}

Mat canvas = new Mat(300, 400, CvType.CV_8UC3, new Scalar(255, 255, 255));
Imgproc.rectangle(canvas, new Point(30,30), new Point(170,130), new Scalar(255,0,0), 3);
Imgproc.putText(canvas, "OpenCV", new Point(60,290),
        Imgproc.FONT_HERSHEY_SIMPLEX, 1.0, new Scalar(0,0,0), 2);
Imgcodecs.imwrite("D:/draw.png", canvas);
canvas.release();

opencvDemo/
├── pom.xml
├── models/                          # 可選：haarcascade_frontalface_default.xml
├── src/main/java/com/badao/demo/
│   ├── DemoApplication.java
│   ├── config/OpenCvConfig.java     # 啟動(dòng)時(shí)預(yù)加載 native
│   ├── service/OpenCvService.java   # 圖像處理能力
│   └── controller/OpenCvController.java
└── src/test/java/com/badao/demo/OpenCvAllFeatureTest.java

package com.badao.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

package com.badao.demo.config;

import lombok.extern.slf4j.Slf4j;
import nu.pattern.OpenCV;
import org.opencv.core.Core;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Slf4j
@Configuration
public class OpenCvConfig {
    @Bean
    public Object openCvInitializer() {
        try {
            OpenCV.loadLocally();
            log.info("OpenCV native 已加載，版本 = {}", Core.VERSION);
        } catch (Exception | UnsatisfiedLinkError e) {
            log.warn("OpenCV native 加載失?。x線環(huán)境將無法運(yùn)行圖像處理）: {}", e.getMessage());
        }
        return new Object();
    }
}

package com.badao.demo.service;

import nu.pattern.OpenCV;
import org.opencv.core.Core;
import org.opencv.core.CvType;
import org.opencv.core.Mat;
import org.opencv.core.MatOfPoint;
import org.opencv.core.MatOfRect;
import org.opencv.core.Point;
import org.opencv.core.Rect;
import org.opencv.core.Scalar;
import org.opencv.core.Size;
import org.opencv.imgcodecs.Imgcodecs;
import org.opencv.imgproc.Imgproc;
import org.opencv.objdetect.CascadeClassifier;
import org.springframework.stereotype.Service;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

@Service
public class OpenCvService {

    private static final String FACE_CASCADE = "models/haarcascade_frontalface_default.xml";

    private void ensureLoaded() {
        try {
            OpenCV.loadLocally();
        } catch (Exception | UnsatisfiedLinkError e) {
            throw new IllegalStateException("OpenCV native 加載失敗，需聯(lián)網(wǎng)下載原生庫(kù): " + e.getMessage(), e);
        }
    }

    public String version() {
        ensureLoaded();
        return Core.VERSION;
    }

    /** 灰度化 */
    public String grayscale(String inPath, String outPath) {
        Mat src = read(inPath);
        Mat dst = new Mat();
        try {
            Imgproc.cvtColor(src, dst, Imgproc.COLOR_BGR2GRAY);
            boolean ok = Imgcodecs.imwrite(outPath, dst);
            return String.format("灰度化完成 -> %s (寫入%s, 尺寸=%dx%d)",
                    outPath, ok ? "成功" : "失敗", dst.cols(), dst.rows());
        } finally {
            src.release(); dst.release();
        }
    }

    /** Canny 邊緣檢測(cè) */
    public String canny(String inPath, String outPath) {
        Mat src = read(inPath);
        Mat gray = new Mat();
        Mat edges = new Mat();
        try {
            Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
            Imgproc.GaussianBlur(gray, gray, new Size(3, 3), 0);
            Imgproc.Canny(gray, edges, 100, 200);
            boolean ok = Imgcodecs.imwrite(outPath, edges);
            return String.format("Canny 邊緣檢測(cè)完成 -> %s (寫入%s, 邊緣點(diǎn)數(shù)=%d)",
                    outPath, ok ? "成功" : "失敗", Core.countNonZero(edges));
        } finally {
            src.release(); gray.release(); edges.release();
        }
    }

    /** 輪廓提取 + 繪制 */
    public String contours(String inPath, String outPath) {
        Mat src = read(inPath);
        Mat gray = new Mat();
        Mat binary = new Mat();
        Mat hierarchy = new Mat();
        try {
            Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
            Imgproc.threshold(gray, binary, 127, 255, Imgproc.THRESH_BINARY);
            List<MatOfPoint> contours = new ArrayList<>();
            Imgproc.findContours(binary, contours, hierarchy,
                    Imgproc.RETR_EXTERNAL, Imgproc.CHAIN_APPROX_SIMPLE);
            Imgproc.drawContours(src, contours, -1, new Scalar(0, 0, 255), 2);
            boolean ok = Imgcodecs.imwrite(outPath, src);
            return String.format("輪廓提取完成(共%d個(gè)輪廓) -> %s (寫入%s)",
                    contours.size(), outPath, ok ? "成功" : "失敗");
        } finally {
            src.release(); gray.release(); binary.release(); hierarchy.release();
        }
    }

    /** 圖形繪制（不依賴輸入圖片，必定可跑） */
    public String drawShapes(String outPath) {
        ensureLoaded();
        Mat canvas = new Mat(300, 400, CvType.CV_8UC3, new Scalar(255, 255, 255));
        try {
            Imgproc.rectangle(canvas, new Point(30, 30), new Point(170, 130), new Scalar(255, 0, 0), 3);
            Imgproc.circle(canvas, new Point(300, 200), 60, new Scalar(0, 255, 0), -1);
            Imgproc.line(canvas, new Point(20, 260), new Point(380, 260), new Scalar(0, 0, 255), 2);
            Imgproc.putText(canvas, "Hello OpenCV", new Point(60, 290),
                    Imgproc.FONT_HERSHEY_SIMPLEX, 1.0, new Scalar(0, 0, 0), 2);
            boolean ok = Imgcodecs.imwrite(outPath, canvas);
            return String.format("繪制圖形完成 -> %s (寫入%s, 畫布=400x300)",
                    outPath, ok ? "成功" : "失敗");
        } finally {
            canvas.release();
        }
    }

    /** 人臉檢測(cè)（需 haarcascade 權(quán)重） */
    public String faceDetect(String inPath, String outPath) {
        Path xml = Path.of(FACE_CASCADE);
        if (!Files.exists(xml)) {
            throw new IllegalStateException(
                    "缺少人臉檢測(cè)權(quán)重 " + FACE_CASCADE + "，可從 OpenCV 倉(cāng)庫(kù)下載放入 ./models/");
        }
        Mat src = read(inPath);
        Mat gray = new Mat();
        CascadeClassifier cascade = new CascadeClassifier(xml.toString());
        try {
            Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
            MatOfRect faces = new MatOfRect();
            cascade.detectMultiScale(gray, faces);
            for (Rect r : faces.toArray()) {
                Imgproc.rectangle(src, r, new Scalar(0, 255, 0), 2);
            }
            boolean ok = Imgcodecs.imwrite(outPath, src);
            return String.format("人臉檢測(cè)完成(命中%d張臉) -> %s (寫入%s)",
                    faces.toArray().length, outPath, ok ? "成功" : "失敗");
        } finally {
            src.release(); gray.release();
        }
    }

    private Mat read(String inPath) {
        ensureLoaded();
        Mat mat = Imgcodecs.imread(inPath);
        if (mat.empty()) {
            throw new IllegalArgumentException("無法讀取圖片: " + inPath);
        }
        return mat;
    }
}

package com.badao.demo.controller;

import com.badao.demo.service.OpenCvService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/opencv")
public class OpenCvController {

    @Autowired
    private OpenCvService openCvService;

    @GetMapping("/version")
    public Map<String, Object> version() {
        return wrap(() -> openCvService.version());
    }

    @GetMapping("/grayscale")
    public Map<String, Object> grayscale(@RequestParam String in, @RequestParam String out) {
        return wrap(() -> openCvService.grayscale(in, out));
    }

    @GetMapping("/canny")
    public Map<String, Object> canny(@RequestParam String in, @RequestParam String out) {
        return wrap(() -> openCvService.canny(in, out));
    }

    @GetMapping("/contours")
    public Map<String, Object> contours(@RequestParam String in, @RequestParam String out) {
        return wrap(() -> openCvService.contours(in, out));
    }

    @GetMapping("/draw")
    public Map<String, Object> draw(@RequestParam String out) {
        return wrap(() -> openCvService.drawShapes(out));
    }

    @GetMapping("/face")
    public Map<String, Object> face(@RequestParam String in, @RequestParam String out) {
        return wrap(() -> openCvService.faceDetect(in, out));
    }

    private Map<String, Object> wrap(Op op) {
        Map<String, Object> resp = new HashMap<>();
        try {
            resp.put("success", true);
            resp.put("message", op.run());
        } catch (Exception e) {
            resp.put("success", false);
            resp.put("message", e.getMessage());
        }
        return resp;
    }

    @FunctionalInterface
    private interface Op { String run(); }
}

cd opencvDemo
mvn compile
mvn spring-boot:run          # 端口 998

# 調(diào)用（首次會(huì)聯(lián)網(wǎng)下載 native，請(qǐng)耐心等待）
curl "http://localhost:998/opencv/version"
curl "http://localhost:998/opencv/draw?out=./out/draw.png"
curl "http://localhost:998/opencv/grayscale?in=D:/t.jpg&out=./out/gray.png"
curl "http://localhost:998/opencv/canny?in=D:/t.jpg&out=./out/canny.png"
curl "http://localhost:998/opencv/contours?in=D:/shapes.png&out=./out/contours.png"
curl "http://localhost:998/opencv/face?in=D:/faces.jpg&out=./out/faces.png"

mvn test

public Mat normalizeIdPhoto(String inPath) {
    Mat src = Imgcodecs.imread(inPath);
    Mat gray = new Mat();
    Mat binary = new Mat();
    try {
        Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
        // 自動(dòng)閾值 -> 找前景輪廓 -> 取最大外接矩形裁邊
        Imgproc.threshold(gray, binary, 0, 255, Imgproc.THRESH_BINARY_INV | Imgproc.THRESH_OTSU);
        List<MatOfPoint> contours = new ArrayList<>();
        Mat hier = new Mat();
        Imgproc.findContours(binary, contours, hier, Imgproc.RETR_EXTERNAL, Imgproc.CHAIN_APPROX_SIMPLE);
        Rect best = null;
        for (MatOfPoint c : contours) {
            Rect r = Imgproc.boundingRect(c);
            if (best == null || r.area() > best.area()) best = r;
        }
        Mat crop = new Mat(src, best != null ? best : new Rect(0, 0, src.cols(), src.rows()));
        Mat resized = new Mat();
        Imgproc.resize(crop, resized, new Size(295, 413)); // 標(biāo)準(zhǔn)一寸照
        return resized;
    } finally {
        src.release(); gray.release(); binary.release();
    }
}

public boolean isDefect(String partPath, double stdArea, double tol) {
    Mat src = Imgcodecs.imread(partPath);
    Mat gray = new Mat(), edges = new Mat(), binary = new Mat(), hier = new Mat();
    try {
        Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
        Imgproc.GaussianBlur(gray, gray, new Size(5, 5), 0);
        Imgproc.Canny(gray, edges, 50, 150);
        Imgproc.threshold(edges, binary, 0, 255, Imgproc.THRESH_BINARY | Imgproc.THRESH_OTSU);
        List<MatOfPoint> contours = new ArrayList<>();
        Imgproc.findContours(binary, contours, hier, Imgproc.RETR_EXTERNAL, Imgproc.CHAIN_APPROX_SIMPLE);
        double area = contours.stream().mapToDouble(Imgproc::contourArea).sum();
        return Math.abs(area - stdArea) > stdArea * tol; // 偏離閾值即判定缺陷
    } finally {
        src.release(); gray.release(); edges.release(); binary.release(); hier.release();
    }
}

public List<Mat> detectFaces(String photoPath) {
    CascadeClassifier cascade = new CascadeClassifier("models/haarcascade_frontalface_default.xml");
    Mat src = Imgcodecs.imread(photoPath);
    Mat gray = new Mat();
    List<Mat> faces = new ArrayList<>();
    try {
        Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY);
        MatOfRect rects = new MatOfRect();
        cascade.detectMultiScale(gray, rects);
        for (Rect r : rects.toArray()) {
            faces.add(new Mat(src, r)); // 裁剪出每張臉
        }
        return faces;
    } finally {
        src.release(); gray.release();
    }
}

// 關(guān)鍵步驟：找最大輪廓 -> 求外接四邊形四點(diǎn) -> warpPerspective 矯正
// 此處給出骨架，findContours + 多邊形逼近 + getPerspectiveTransform 即可實(shí)現(xiàn)。
Mat doc = Imgcodecs.imread("D:/doc.jpg");
Mat gray = new Mat(), binary = new Mat();
Imgproc.cvtColor(doc, gray, Imgproc.COLOR_BGR2GRAY);
Imgproc.threshold(gray, binary, 0, 255, Imgproc.THRESH_BINARY | Imgproc.THRESH_OTSU);
List<MatOfPoint> contours = new ArrayList<>(); Mat hier = new Mat();
Imgproc.findContours(binary, contours, hier, Imgproc.RETR_EXTERNAL, Imgproc.CHAIN_APPROX_SIMPLE);
// 取面積最大的輪廓，近似多邊形（Imgproc.approxPolyDP），若 4 個(gè)頂點(diǎn)則可用
// Core.getPerspectiveTransform(srcPts, dstPts) + Imgproc.warpPerspective(...) 完成矯正。
doc.release(); gray.release(); binary.release(); hier.release();

// 借助 video 模塊的背景減除器
// BackgroundSubtractorMOG2 mog = Video.createBackgroundSubtractorMOG2();
// mog.apply(frame, fgMask);  -> fgMask 即前景（運(yùn)動(dòng)區(qū)域）二值圖
// 再對(duì) fgMask 做 findContours + 面積過濾即可定位移動(dòng)目標(biāo)。

// 假設(shè)模型返回 detections: List<Detection{x,y,w,h,label}>
Mat img = Imgcodecs.imread("D:/scene.jpg");
for (Detection d : detections) {
    Rect r = new Rect(d.x, d.y, d.w, d.h);
    Imgproc.rectangle(img, r, new Scalar(0, 255, 0), 2);
    Imgproc.putText(img, d.label, new Point(d.x, d.y - 5),
            Imgproc.FONT_HERSHEY_SIMPLEX, 0.6, new Scalar(0, 255, 0), 2);
}
Imgcodecs.imwrite("D:/detected.jpg", img);
img.release();

            ┌─────────────────────┐
            │  你的業(yè)務(wù)系統(tǒng)(Spring) │
            └──────────┬──────────┘
                       │
        ┌──────────────┼───────────────────┐
        │              │                   │
  OpenCV(圖像處理)   DJL(張量/推理引擎)   SmartJavaAI(封裝好的 AI 能力)
   像素級(jí)原語         NDArray + 模型推理     人臉識(shí)別/ OCR/ 檢測(cè)…
        │              │                   │
        └──────┬───────┴───────────────────┘
               │  SmartJavaAI 底層大量調(diào)用 OpenCV 做預(yù)處理/畫框
               ▼
          OpenCV 是它們的「畫筆與手術(shù)刀」

Mat src = Imgcodecs.imread(in);
try {
    Mat dst = new Mat();
    Imgproc.cvtColor(src, dst, Imgproc.COLOR_BGR2GRAY);
    Imgcodecs.imwrite(out, dst);
    dst.release();
} finally {
    src.release();   // OpenCV 的 Mat 不會(huì)自動(dòng)關(guān)閉，務(wù)必 release
}