YOLO Java SDK

基于 ONNX Runtime 的 YOLO 系列全任务 Java 封装库。

✅ 目标检测 (Detect) — YOLOv5/v8/v11
✅ 姿态估计 (Pose) — YOLOv8/v11-pose
✅ 实例分割 (Segment) — YOLOv8/v11-seg
✅ 图像分类 (Classify) — YOLOv8/v11-cls

快速开始

1. 安装依赖

<dependency>
    <groupId>com.yolo</groupId>
    <artifactId>yolo-detector</artifactId>
    <version>1.0.0</version>
</dependency>

2. 导出 ONNX 模型

from ultralytics import YOLO

# 目标检测
YOLO("yolov8n.pt").export(format="onnx")

# 姿态检测
YOLO("yolov8n-pose.pt").export(format="onnx")

# 实例分割
YOLO("yolov8n-seg.pt").export(format="onnx")

# 图像分类
YOLO("yolov8n-cls.pt").export(format="onnx")

3. 使用

// ===== 目标检测 =====
try (YoloDetector detector = new YoloDetector("yolov8n.onnx")) {
    DetectionResult result = detector.detect("photo.jpg");
    result.getDetections().forEach(System.out::println);
}

// ===== 姿态检测 =====
try (YoloPoseDetector detector = new YoloPoseDetector("yolov8n-pose.onnx")) {
    PoseResult result = detector.detect("person.jpg");
    for (PoseDetection pose : result.getPoses()) {
        for (KeyPoint kp : pose.getKeyPoints()) {
            if (kp.isVisible()) {
                System.out.printf("%s: (%.1f, %.1f)%n", kp.getName(), kp.getX(), kp.getY());
            }
        }
    }
}

// ===== 实例分割 =====
try (YoloSegmentDetector detector = new YoloSegmentDetector("yolov8n-seg.onnx")) {
    SegmentationResult result = detector.detect("photo.jpg");
    for (SegmentationDetection det : result.getDetections()) {
        System.out.printf("%s: mask area=%.1f%%%n", det.getClassName(), det.getMaskAreaRatio() * 100);
    }
}

// ===== 图像分类 =====
try (YoloClassifier classifier = new YoloClassifier("yolov8n-cls.onnx")) {
    ClassificationResult result = classifier.classify("photo.jpg");
    System.out.println("Top-1: " + result.getTop1());
    result.getTopK(5).forEach(System.out::println);
}

API 概览

检测器一览

检测器	用途	模型文件	输出
YoloDetector	目标检测	yolov8n.onnx	DetectionResult
YoloPoseDetector	姿态估计	yolov8n-pose.onnx	PoseResult
YoloSegmentDetector	实例分割	yolov8n-seg.onnx	SegmentationResult
YoloClassifier	图像分类	yolov8n-cls.onnx	ClassificationResult

YoloConfig（通用配置）

YoloConfig config = YoloConfig.defaults()
    .inputSize(640)              // 模型输入尺寸
    .confidenceThreshold(0.5f)   // 置信度阈值
    .iouThreshold(0.45f)         // NMS IoU 阈值
    .maxDetections(300)          // 最大检测数
    .useGpu(true)                // GPU 加速
    .gpuDeviceId(0)              // GPU 设备 ID
    .labelsPath("my_classes.txt"); // 自定义标签

可视化（统一接口）

// 目标检测
YoloVisualizer.drawAndSave("input.jpg", detectionResult, "output.jpg");

// 姿态检测 — 自动绘制骨架 + 关键点
YoloVisualizer.drawAndSave("input.jpg", poseResult, "output.jpg");

// 实例分割 — 半透明掩码叠加
YoloVisualizer.drawAndSave("input.jpg", segmentationResult, "output.jpg");

// 图像分类 — Top-5 标签
YoloVisualizer.drawAndSave("input.jpg", classificationResult, "output.jpg");

姿态关键点

COCO 17 关键点，自动检测和绘制：

ID	名称	ID	名称
0	nose	9	left_wrist
1	left_eye	10	right_wrist
2	right_eye	11	left_hip
3	left_ear	12	right_hip
4	right_ear	13	left_knee
5	left_shoulder	14	right_knee
6	right_shoulder	15	left_ankle
7	left_elbow	16	right_ankle
8	right_elbow

骨架连接和关键点可见性判断均内置。

项目结构

src/main/java/com/yolo/detector/
├── BaseYoloRunner.java            # 基类（预处理/推理/NMS 共享）
├── YoloDetector.java              # 目标检测
├── YoloVisualizer.java            # 可视化（全任务）
├── YoloConfig.java                # 配置
├── pose/
│   └── YoloPoseDetector.java      # 姿态检测
├── segment/
│   └── YoloSegmentDetector.java   # 实例分割
├── classify/
│   └── YoloClassifier.java        # 图像分类
└── model/
    ├── Detection.java             # 检测结果
    ├── DetectionResult.java       # 检测结果集
    ├── PoseDetection.java         # 姿态结果（含关键点定义）
    ├── PoseResult.java            # 姿态结果集
    ├── SegmentationDetection.java # 分割结果（含掩码）
    ├── SegmentationResult.java    # 分割结果集
    └── ClassificationResult.java  # 分类结果（Top-K）
src/main/resources/
└── imagenet_classes.txt           # ImageNet 1000 类标签

性能参考

环境	模型	任务	推理速度
CPU i7	YOLOv8n	检测	~50-100ms
RTX 3060	YOLOv8n	检测	~5-10ms
CPU i7	YOLOv8n	姿态	~80-150ms
CPU i7	YOLOv8n	分割	~100-200ms
CPU i7	YOLOv8n	分类	~20-40ms

注意事项

1. 模型格式: 必须使用 ONNX 格式，通过 Ultralytics 导出
2. OpenCV: 使用 openpnp/opencv 自动加载 native 库
3. GPU: 需替换依赖为 onnxruntime_gpu 并安装 CUDA
4. 标签: 检测/姿态内置 COCO 80 类，分类内置 ImageNet 1000 类，均可自定义
5. JDK: 需要 Java 17+

License

MIT