Java中集成OpenCV的操作教程

<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);   // 双阈值(低,高)，结果二值图
int edgePoints = Core.countNonZero(edges);  // 统计边缘像素数

// 固定阈值
Imgproc.threshold(gray, binary, 127, 255, Imgproc.THRESH_BINARY);
// OTSU 自动阈值（返回实际阈值）
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);  // 入参必须是二值图
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=实心填充
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);

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("边缘点数=" + 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     # 启动时预加载 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 加载失败（离线环境将无法运行图像处理）: {}", 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 加载失败，需联网下载原生库: " + 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 边缘检测 */
    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 边缘检测完成 -> %s (写入%s, 边缘点数=%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个轮廓) -> %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();
        }
    }

    /** 人脸检测（需 haarcascade 权重） */
    public String faceDetect(String inPath, String outPath) {
        Path xml = Path.of(FACE_CASCADE);
        if (!Files.exists(xml)) {
            throw new IllegalStateException(
                    "缺少人脸检测权重 " + FACE_CASCADE + "，可从 OpenCV 仓库下载放入 ./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("人脸检测完成(命中%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

# 调用（首次会联网下载 native，请耐心等待）
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);
        // 自动阈值 -> 找前景轮廓 -> 取最大外接矩形裁边
        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)); // 标准一寸照
        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();
    }
}

// 关键步骤：找最大轮廓 -> 求外接四边形四点 -> warpPerspective 矫正
// 此处给出骨架，findContours + 多边形逼近 + getPerspectiveTransform 即可实现。
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 个顶点则可用
// Core.getPerspectiveTransform(srcPts, dstPts) + Imgproc.warpPerspective(...) 完成矫正。
doc.release(); gray.release(); binary.release(); hier.release();

// 借助 video 模块的背景减除器
// BackgroundSubtractorMOG2 mog = Video.createBackgroundSubtractorMOG2();
// mog.apply(frame, fgMask);  -> fgMask 即前景（运动区域）二值图
// 再对 fgMask 做 findContours + 面积过滤即可定位移动目标。

// 假设模型返回 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();

            ┌─────────────────────┐
            │  你的业务系统(Spring) │
            └──────────┬──────────┘
                       │
        ┌──────────────┼───────────────────┐
        │              │                   │
  OpenCV(图像处理)   DJL(张量/推理引擎)   SmartJavaAI(封装好的 AI 能力)
   像素级原语         NDArray + 模型推理     人脸识别/ OCR/ 检测…
        │              │                   │
        └──────┬───────┴───────────────────┘
               │  SmartJavaAI 底层大量调用 OpenCV 做预处理/画框
               ▼
          OpenCV 是它们的「画笔与手术刀」

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 不会自动关闭，务必 release
}