OpenCV 4.8.0 setMouseCallback 实战：3种图像标注工具实现与性能对比

在计算机视觉项目的开发过程中，图像标注是不可或缺的基础环节。无论是目标检测、图像分割还是关键点识别，高质量的标注数据直接决定了模型的上限。而作为OpenCV的核心交互功能之一，setMouseCallback为开发者提供了快速构建标注工具的能力。本文将带你从零实现三种主流标注模式（矩形、多边形、关键点），并通过量化测试揭示不同模式的性能差异。

1. 环境准备与基础架构

1.1 安装OpenCV 4.8.0

推荐使用conda创建纯净环境：

conda create -n annotation python=3.8 conda activate annotation pip install opencv-python==4.8.0 numpy pandas

1.2 标注工具基础类设计

我们先构建一个可扩展的基类，封装通用功能：

import cv2 import numpy as np from time import perf_counter class BaseAnnotator: def __init__(self, window_name="Annotation Tool"): self.window_name = window_name self.image = None self.clone = None self.annotations = [] self.current_anno = None self.colors = { 'rectangle': (0, 255, 0), 'polygon': (255, 0, 0), 'keypoint': (0, 0, 255) } def load_image(self, image_path): self.image = cv2.imread(image_path) if self.image is None: raise FileNotFoundError(f"无法加载图像: {image_path}") self.clone = self.image.copy() def reset_image(self): self.clone = self.image.copy() def draw_annotations(self): """由子类实现具体绘制逻辑""" raise NotImplementedError def save_annotations(self, save_path): """保存标注数据到文件""" with open(save_path, 'w') as f: for anno in self.annotations: f.write(f"{anno['type']}|{anno['points']}\n")

2. 矩形标注工具实现

2.1 核心交互逻辑

矩形标注是最基础的标注形式，通过记录对角两点确定区域：

class RectangleAnnotator(BaseAnnotator): def __init__(self): super().__init__("Rectangle Annotation") self.drawing = False self.start_point = None def draw_annotations(self): for anno in self.annotations: if anno['type'] == 'rectangle': cv2.rectangle(self.clone, anno['points'][0], anno['points'][1], self.colors['rectangle'], 2) if self.current_anno: cv2.rectangle(self.clone, self.current_anno['points'][0], self.current_anno['points'][1], self.colors['rectangle'], 2) def mouse_callback(self, event, x, y, flags, param): if event == cv2.EVENT_LBUTTONDOWN: self.drawing = True self.start_point = (x, y) self.current_anno = { 'type': 'rectangle', 'points': [(x, y), (x, y)] } elif event == cv2.EVENT_MOUSEMOVE: if self.drawing: self.current_anno['points'][1] = (x, y) elif event == cv2.EVENT_LBUTTONUP: self.drawing = False if (abs(x - self.start_point[0]) > 10 and abs(y - self.start_point[1]) > 10): # 过滤误触 self.annotations.append(self.current_anno) self.current_anno = None

2.2 使用示例

rect_annotator = RectangleAnnotator() rect_annotator.load_image("sample.jpg") cv2.namedWindow(rect_annotator.window_name) cv2.setMouseCallback(rect_annotator.window_name, rect_annotator.mouse_callback) while True: rect_annotator.reset_image() rect_annotator.draw_annotations() cv2.imshow(rect_annotator.window_name, rect_annotator.clone) key = cv2.waitKey(1) & 0xFF if key == ord('s'): rect_annotator.save_annotations("rect_annotations.txt") elif key == ord('q'): break cv2.destroyAllWindows()

3. 多边形标注工具实现

3.1 核心交互逻辑

多边形标注适用于不规则物体，通过连续点击构成闭合区域：

class PolygonAnnotator(BaseAnnotator): def __init__(self): super().__init__("Polygon Annotation") self.drawing = False self.temp_points = [] def draw_annotations(self): for anno in self.annotations: if anno['type'] == 'polygon': pts = np.array(anno['points'], np.int32) cv2.polylines(self.clone, [pts], True, self.colors['polygon'], 2) if len(self.temp_points) > 1: pts = np.array(self.temp_points, np.int32) cv2.polylines(self.clone, [pts], False, self.colors['polygon'], 2) for point in self.temp_points: cv2.circle(self.clone, point, 3, (0, 255, 255), -1) def mouse_callback(self, event, x, y, flags, param): if event == cv2.EVENT_LBUTTONDOWN: self.temp_points.append((x, y)) self.drawing = True elif event == cv2.EVENT_RBUTTONDOWN and self.drawing: if len(self.temp_points) >= 3: # 至少三个点构成多边形 self.annotations.append({ 'type': 'polygon', 'points': self.temp_points.copy() }) self.temp_points = [] self.drawing = False elif event == cv2.EVENT_MBUTTONDOWN and self.drawing: self.temp_points.pop() # 中键撤销上一个点

4. 关键点标注工具实现

4.1 核心交互逻辑

关键点标注用于标记特定部位位置，如人脸特征点：

class KeypointAnnotator(BaseAnnotator): def __init__(self): super().__init__("Keypoint Annotation") self.current_type = 0 self.keypoint_types = ['eye', 'nose', 'mouth'] def draw_annotations(self): for anno in self.annotations: if anno['type'] == 'keypoint': cv2.circle(self.clone, anno['point'], 3, self.colors['keypoint'], -1) cv2.putText(self.clone, anno['label'], (anno['point'][0]+5, anno['point'][1]+5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, self.colors['keypoint'], 1) def mouse_callback(self, event, x, y, flags, param): if event == cv2.EVENT_LBUTTONDOWN: self.annotations.append({ 'type': 'keypoint', 'point': (x, y), 'label': self.keypoint_types[self.current_type] }) elif event == cv2.EVENT_MOUSEWHEEL: if flags > 0: # 滚轮上滑 self.current_type = (self.current_type + 1) % len(self.keypoint_types) else: # 滚轮下滑 self.current_type = (self.current_type - 1) % len(self.keypoint_types)

5. 三合一标注工具与模式切换

5.1 整合实现

class UniversalAnnotator(BaseAnnotator): MODES = ['rectangle', 'polygon', 'keypoint'] def __init__(self): super().__init__("Universal Annotation Tool") self.current_mode = 0 self.temp_poly_points = [] self.drawing_rect = False self.rect_start = None def draw_annotations(self): # 绘制已有标注 for anno in self.annotations: color = self.colors[anno['type']] if anno['type'] == 'rectangle': cv2.rectangle(self.clone, anno['points'][0], anno['points'][1], color, 2) elif anno['type'] == 'polygon': pts = np.array(anno['points'], np.int32) cv2.polylines(self.clone, [pts], True, color, 2) elif anno['type'] == 'keypoint': cv2.circle(self.clone, anno['point'], 3, color, -1) cv2.putText(self.clone, anno['label'], (anno['point'][0]+5, anno['point'][1]+5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 1) # 绘制当前临时标注 current_mode = self.MODES[self.current_mode] if current_mode == 'rectangle' and self.drawing_rect: cv2.rectangle(self.clone, self.rect_start, self.current_rect_end, self.colors['rectangle'], 2) elif current_mode == 'polygon' and self.temp_poly_points: pts = np.array(self.temp_poly_points, np.int32) cv2.polylines(self.clone, [pts], False, self.colors['polygon'], 2) for pt in self.temp_poly_points: cv2.circle(self.clone, pt, 3, (0, 255, 255), -1) # 显示当前模式 cv2.putText(self.clone, f"Mode: {current_mode}", (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 255), 2) def mouse_callback(self, event, x, y, flags, param): current_mode = self.MODES[self.current_mode] if current_mode == 'rectangle': if event == cv2.EVENT_LBUTTONDOWN: self.drawing_rect = True self.rect_start = (x, y) self.current_rect_end = (x, y) elif event == cv2.EVENT_MOUSEMOVE and self.drawing_rect: self.current_rect_end = (x, y) elif event == cv2.EVENT_LBUTTONUP and self.drawing_rect: self.drawing_rect = False if (abs(x - self.rect_start[0]) > 10 and abs(y - self.rect_start[1]) > 10): self.annotations.append({ 'type': 'rectangle', 'points': [self.rect_start, (x, y)] }) elif current_mode == 'polygon': if event == cv2.EVENT_LBUTTONDOWN: self.temp_poly_points.append((x, y)) elif event == cv2.EVENT_RBUTTONDOWN and self.temp_poly_points: if len(self.temp_poly_points) >= 3: self.annotations.append({ 'type': 'polygon', 'points': self.temp_poly_points.copy() }) self.temp_poly_points = [] elif event == cv2.EVENT_MBUTTONDOWN and self.temp_poly_points: self.temp_poly_points.pop() elif current_mode == 'keypoint': if event == cv2.EVENT_LBUTTONDOWN: self.annotations.append({ 'type': 'keypoint', 'point': (x, y), 'label': f"KP-{len(self.annotations)+1}" }) def switch_mode(self): self.current_mode = (self.current_mode + 1) % len(self.MODES) self.temp_poly_points = [] self.drawing_rect = False

5.2 性能优化技巧

1. 双缓冲技术：始终在clone图像上绘制，避免直接修改原图
2. 局部刷新：对于大规模图像，只重绘变化区域
3. 事件过滤：添加最小移动阈值，避免频繁重绘
4. 数据结构优化：使用numpy数组存储点集，提高绘制效率

6. 性能对比与量化分析

6.1 测试方法设计

我们设计以下测试场景：

def benchmark_annotator(annotator_class, test_image, num_annotations): annotator = annotator_class() annotator.load_image(test_image) # 模拟用户操作 start_time = perf_counter() if annotator_class == RectangleAnnotator: # 模拟矩形标注 for i in range(num_annotations): x1, y1 = np.random.randint(0, 800, 2) x2, y2 = x1 + np.random.randint(50, 200), y1 + np.random.randint(50, 200) annotator.annotations.append({ 'type': 'rectangle', 'points': [(x1, y1), (x2, y2)] }) elif annotator_class == PolygonAnnotator: # 模拟多边形标注 for _ in range(num_annotations): points = [] center = np.random.randint(100, 700, 2) for _ in range(np.random.randint(3, 8)): # 3-7边形 angle = np.random.uniform(0, 2*np.pi) radius = np.random.randint(30, 100) x = int(center[0] + radius * np.cos(angle)) y = int(center[1] + radius * np.sin(angle)) points.append((x, y)) annotator.annotations.append({ 'type': 'polygon', 'points': points }) elif annotator_class == KeypointAnnotator: # 模拟关键点标注 for i in range(num_annotations): point = np.random.randint(0, 800, 2) annotator.annotations.append({ 'type': 'keypoint', 'point': tuple(point), 'label': f"KP-{i+1}" }) # 测量绘制性能 draw_times = [] for _ in range(100): annotator.reset_image() start_draw = perf_counter() annotator.draw_annotations() draw_times.append(perf_counter() - start_draw) total_time = perf_counter() - start_time return { 'total_time': total_time, 'avg_draw_time': np.mean(draw_times), 'max_draw_time': np.max(draw_times), 'min_draw_time': np.min(draw_times) }

6.2 性能对比数据

测试环境：Intel i7-11800H, 32GB RAM, NVIDIA RTX 3060

6.3 性能优化前后对比

优化措施：

1. 将点列表转换为numpy数组
2. 使用cv2.polylines替代多个cv2.line
3. 实现局部刷新机制

7. 高级功能扩展

7.1 标注编辑与撤销

class AdvancedAnnotator(UniversalAnnotator): def __init__(self): super().__init__() self.history = [] def save_state(self): """保存当前状态到历史记录""" self.history.append({ 'annotations': [anno.copy() for anno in self.annotations], 'temp_points': self.temp_poly_points.copy(), 'drawing_rect': self.drawing_rect, 'rect_start': self.rect_start, 'current_rect_end': self.current_rect_end }) # 限制历史记录数量 if len(self.history) > 20: self.history.pop(0) def undo(self): if self.history: state = self.history.pop() self.annotations = state['annotations'] self.temp_poly_points = state['temp_points'] self.drawing_rect = state['drawing_rect'] self.rect_start = state['rect_start'] self.current_rect_end = state['current_rect_end'] def mouse_callback(self, event, x, y, flags, param): self.save_state() super().mouse_callback(event, x, y, flags, param)

7.2 标注导出与导入

支持常见格式导出：

def export_to_coco(self, save_path): """导出为COCO格式""" coco_data = { "images": [{ "id": 1, "file_name": os.path.basename(self.image_path), "width": self.image.shape[1], "height": self.image.shape[0] }], "annotations": [], "categories": [{"id": 1, "name": "object"}] } for i, anno in enumerate(self.annotations): if anno['type'] == 'rectangle': x1, y1 = anno['points'][0] x2, y2 = anno['points'][1] width, height = abs(x2 - x1), abs(y2 - y1) coco_data["annotations"].append({ "id": i + 1, "image_id": 1, "category_id": 1, "bbox": [min(x1, x2), min(y1, y2), width, height], "area": width * height, "iscrowd": 0 }) # 其他类型标注处理... with open(save_path, 'w') as f: json.dump(coco_data, f, indent=2)

7.3 多图像批处理

class BatchAnnotator: def __init__(self, image_folder): self.image_files = [f for f in os.listdir(image_folder) if f.lower().endswith(('.jpg', '.png'))] self.current_index = 0 self.annotator = UniversalAnnotator() self.load_current_image() def load_current_image(self): self.annotator.load_image( os.path.join(image_folder, self.image_files[self.current_index]) ) def next_image(self): if self.current_index < len(self.image_files) - 1: self.current_index += 1 self.load_current_image() return True return False def prev_image(self): if self.current_index > 0: self.current_index -= 1 self.load_current_image() return True return False