Biblioteca Independiente para Detección de AprilTag

Este es un paquete de herramientas para la detección de AprilTag basado en la biblioteca pupil-apriltags, diseñado para identificar y rastrear marcadores AprilTag en cámaras.

Dependencias

Python 3.6+
OpenCV
NumPy
pupil-apriltags

Instalación

Asegúrese de tener instalado Python
Instale las dependencias necesarias:

pip install opencv-python numpy pupil-apriltags

Modo de Uso

Uso Básico

import cv2
from apriltag import Detector, DetectorOptions

# 创建检测器
options = DetectorOptions(
    families="tag36h11",  # 标签家族
    border=1,             # 标签边框大小
    nthreads=4,           # 线程数量
    quad_decimate=1.0,    # 图像下采样系数
    quad_blur=0.0,        # 高斯模糊系数
    refine_edges=True     # 是否精细化边缘
)
detector = Detector(options)

# 读取图像
img = cv2.imread("test_image.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# 检测AprilTag
detections = detector.detect(gray)

# 显示检测结果
for detection in detections:
    print(f"标签家族: {detection.tag_family}, ID: {detection.tag_id}")
    print(f"位置: {detection.center}")
    print(f"角点: {detection.corners}")

Visualización de Resultados

import numpy as np
from apriltag import draw_detection_results

# 相机内参矩阵和畸变系数
K = np.array([[800, 0, 320], [0, 800, 240], [0, 0, 1]], dtype=np.float32)
D = np.zeros((4, 1), dtype=np.float32)

# 绘制检测结果
result_img = draw_detection_results(img, detections, K, D, tag_size=0.1)

# 显示结果
cv2.imshow("AprilTag检测", result_img)
cv2.waitKey(0)

Ejecución de Script de Prueba

Se incluye un script de prueba sencillo para verificar la funcionalidad de detección de AprilTag:

python test_apriltag.py

Esto activará la cámara predeterminada y detectará AprilTags en tiempo real. Presione "q" para salir.

Familias de Etiquetas Soportadas

La biblioteca pupil-apriltags soporta las siguientes familias de etiquetas:

tag36h11 (predeterminado)
tag25h9
tag16h5
tagCircle21h7
tagCircle49h12
tagStandard41h12
tagStandard52h13
tagCustom48h12

Consideraciones

Para mejor rendimiento, ajuste los parámetros en DetectorOptions
En dispositivos con recursos limitados, considere aumentar quad_decimate para reducir complejidad computacional
Asegúrese que el tamaño de los marcadores AprilTag coincida con el parámetro tag_size en el código
La visualización de ejes 3D requiere parámetros de cámara precisos

Características Principales

Soporte para detección en tiempo real con cámaras USB
Cálculo y visualización de pose 3D (posición y orientación)
Capacidad para guardar imágenes originales y marcadas
Configuración personalizable y parámetros de cámara
Herramientas completas de calibración de cámara
Versión independiente en Python puro, sin dependencias de ROS

Pasos de Instalación

1. Instalar la Biblioteca C de AprilTag

La biblioteca C de AprilTag es obligatoria. Siga estos pasos:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y libapriltag-dev

Windows:

Usuarios de Windows deben compilar manualmente o descargar binarios precompilados, asegurando que apriltag.dll esté en el PATH del sistema o en el directorio actual.

2. Instalar Dependencias de Python

pip install -r requirements.txt  -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
pip install pupil-apriltags -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

Instrucciones de Uso

Inicio Rápido (Recomendado)

La forma más sencilla es usar la herramienta integrada con menú interactivo:

python apriltag_tool.py

Opciones del menú:

Generar patrón de calibración
Calibrar cámara
Detección de AprilTag
Ver documentación

Calibración de Cámara

Se recomienda calibrar la cámara antes de usar AprilTag:

# 首先生成棋盘格标定板
python create_chessboard.py --size 9x6 --square 100 --output chessboard.png --dpi 300

# 打印棋盘格并测量实际方格大小，然后进行标定
python camera_calibration.py --size 9x6 --square 0.025 --output config/camera/HSK_200W53_1080P.yaml

Parámetros:

Generador de Patrón (create_chessboard.py):

--size: Número de esquinas internas (ancho x alto, predeterminado: 9x6)
--square: Tamaño de cuadro en píxeles (predeterminado: 100)
--output: Ruta de salida (predeterminado: chessboard.png)
--dpi: DPI de la imagen (predeterminado: 300), afecta tamaño de impresión

Programa de Calibración (camera_calibration.py):

--size: Esquinas internas (ancho x alto)
--square: Tamaño real de cuadro en metros
--output: Archivo de salida (predeterminado: config/camera/HSK_200W53_1080P.yaml)
--camera: ID de dispositivo (predeterminado: 0)
--width: Resolución de captura (ancho)
--height: Resolución de captura (alto)
--samples: Número de muestras requeridas (predeterminado: 20)
--preview: Vista previa después de calibración

Proceso:

Generar e imprimir patrón de calibración
Medir tamaño real de cuadros (en metros)
Ejecutar calibración, mover patrón frente a cámara
El programa detectará automáticamente el patrón
Presione 's' para guardar frames manualmente
Con suficientes muestras, se calculan parámetros y guardan

Detección de AprilTag

Tras calibración, ejecute:

python apriltag_detector.py

Uso Avanzado

python apriltag_detector.py [配置文件路径] --camera 相机ID --width 宽度 --height 高度 --camera_info 相机参数文件

Parámetros:

Ruta de configuración: Archivo de configuración (predeterminado: config/vision/tags_36h11_all.json)
--camera: ID de cámara
--camera_info: Archivo de parámetros intrínsecos
--width: Ancho de captura
--height: Alto de captura

Controles

q: Salir

Configuración

Todos los ajustes pueden modificarse en config/vision/table_setup.json:

{
    "AprilTagConfig": {
        "family": "tag36h11",      // 标签家族
        "size": 0.05,              // 标签物理尺寸（单位：米）
        "threads": 2,              // 处理线程数
        "max_hamming": 0,          // 最大汉明距离
        "z_up": true,              // Z轴朝上
        "decimate": 1.0,           // 图像下采样系数
        "blur": 0.8,               // 模糊系数
        "refine_edges": 1,         // 是否精细化边缘
        "debug": 0                 // 是否打开调试
    },

    "Camera": {
        "device_id": 0,            // 相机设备ID
        "width": 1280,             // 相机宽度分辨率
        "height": 720,             // 相机高度分辨率
        "camera_info_path": "config/camera/HSK_200W53_1080P.yaml"  // 相机标定参数文件
    },

    "Archive": {
        "enable": true,            // 是否启用数据存档
        "preview": true,           // 是否显示预览窗口
        "save_raw": false,         // 是否保存原始图像
        "save_pred": false,        // 是否保存预测图像
        "path": "./data/table_tracking"  // 数据保存路径
    },

    "TableConfig": {
        "reference_tags": [0, 1, 2, 3],      // 参考标签ID列表
        "moving_tags": [4, 5, 6],            // 移动标签ID列表
        "require_initialization": true,       // 是否需要初始化
        "tag_positions": {                    // 预设标签位置（如果有）
            "0": [0.0, 0.0, 0.0],
            "1": [0.5, 0.0, 0.0],
            "2": [0.5, 0.5, 0.0],
            "3": [0.0, 0.5, 0.0]
        }
    }
}

Opciones configurables:

Parámetros del detector AprilTag
Configuración de cámara (ID, resolución, archivo de parámetros)
Opciones de almacenamiento de datos
Personalización de IDs de etiquetas de referencia y móviles
Control de inicialización (require_initialization)
Posiciones predefinidas de etiquetas

Modo de Uso

Inicio simple:

python table_tracking.py

Con archivo personalizado:

python table_tracking.py --config 自定义配置文件路径

Presione 'i' para inicialización manual durante operación.

Preguntas Frecuentes

Error al encontrar biblioteca aprilTag

Verifique instalación correcta y ubicación de archivos.
Cámara no se abre

Confirme ID correcto y que no esté en uso.
Detección imprecisa

Asegure calibración adecuada y tamaño correcto en configuración.

Estructura de Archivos

apriltag_standalone/
├── apriltag.py              # AprilTag检测库核心代码
├── apriltag_detector.py     # AprilTag检测主程序
├── apriltag_tool.py         # 集成工具启动菜单
├── camera_calibration.py    # 相机标定程序
├── create_chessboard.py     # 棋盘格生成工具
├── configs.py               # 配置文件处理
├── config/                  # 配置目录
│   ├── camera/              # 相机配置
│   │   └── HSK_200W53_1080P.yaml  # 相机参数
│   └── vision/              # 视觉配置
│       └── tags_36h11_all.json # AprilTag配置
├── README.md                # 说明文档
└── requirements.txt         # Python依赖

Detalles Técnicos

Versión independiente del paquete ROS AprilTag, manteniendo funcionalidad principal. Tecnologías utilizadas:

OpenCV: Procesamiento de imágenes, calibración y estimación de pose
Biblioteca C AprilTag: Detección de etiquetas
SciPy: Conversión de matrices de rotación y cuaterniones

Licencia

Proyecto bajo licencia MIT

Nuevas Funcionalidades

Seguimiento Múltiple y Manejo de Oclusiones

Nuevas capacidades:

Inicialización por captura: Registra relaciones posicionales entre:
- Etiquetas de referencia fijas (ID 0-3)
- Etiquetas móviles (IDs 4,5,6 por defecto)
Manejo de oclusiones:
- Si se ocluyen etiquetas de referencia, estima posiciones usando otras visibles
- Para etiquetas móviles ocluidas, estima mediante relaciones conocidas
Seguimiento múltiple: Rastrea varias etiquetas móviles simultáneamente
- Posiciones relativas fijas permiten estimar etiquetas ocluidas
- IDs personalizables en configuración

Configuración

Ajustes en config/vision/table_setup.json:

{
    "TableConfig": {
        "reference_tags": [0, 1, 2, 3],      // 参考标签ID列表
        "moving_tags": [4, 5, 6],            // 移动标签ID列表
        "require_initialization": true,       // 是否需要初始化
        "tag_positions": {                    // 预设标签位置（如果有）
            "0": [0.0, 0.0, 0.0],
            "1": [0.5, 0.0, 0.0],
            "2": [0.5, 0.5, 0.0],
            "3": [0.0, 0.5, 0.0]
        }
    }
}

Personalización de:

IDs de etiquetas de referencia y móviles
Requerimiento de inicialización (require_initialization)
Posiciones predefinidas

Modo de Uso

Inicio con configuración predeterminada:
```
python table_tracking.py
```

Con archivo personalizado:

python table_tracking.py --config ruta_personalizada

Inicialización manual: Tecla 'i' durante operación

Requisitos

Todas las etiquetas deben ser visibles durante inicialización para establecer relaciones posicionales. Posteriormente, el sistema estimará posiciones incluso con oclusiones parciales.