Metadata-Version: 2.1
Name: aitoolkit_base
Version: 2.0
Summary: 一个面向中学生的简单AI工具包，提供人脸分析、人体分析、相机工具和图像分析功能
Home-page: https://github.com/haitao926/aitoolkit_base
Author: AIToolkit Team
Author-email: your.email@example.com
Project-URL: Documentation, https://haitao926.github.io/aitoolkit_base_docs/
Project-URL: Bug Tracker, https://github.com/haitao926/aitoolkit_base/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: mediapipe >=0.10.0
Requires-Dist: opencv-python >=4.8.0
Requires-Dist: numpy >=1.24.0
Requires-Dist: aiortc >=1.3.2
Requires-Dist: websockets >=10.3
Requires-Dist: av >=9.2.0

# AIToolkit Base

一个面向中学生的简单AI工具包，基于MediaPipe封装，提供简单易用的人脸检测、人脸关键点检测、手部关键点检测、人体姿态检测、手势识别和物体检测功能。

## 功能特点

- 简单易用的API设计
- 统一的接口风格
- 中文注释和文档
- 自动的可视化功能
- 实时处理支持
- 自动帧率控制和跳帧技术
- 智能资源管理

## 1.0版本固化功能

### 人脸分析
- **人脸检测**：提升多人脸检测稳定性
- **人脸关键点**：优化478点精确定位

### 人体分析
- **手部关键点**：提升21点3D坐标准确性
- **人体姿态**：优化33点检测与多人跟踪
- **手势识别**：扩展更多手势类型识别

### 相机工具
- **相机工具**：增强实时处理功能
- 支持cv2，web api 等多种网页端显示功能
- **迭代器支持**：可使用`for frame in camera:`语法直接遍历视频帧

### 图像分析
- **物体检测**：提升检测速度与精度

## 性能优化技术

- **同步检测技术**：所有检测器都采用统一的同步检测技术，实现零延迟视频处理，消除异步模式的图像不同步问题
- **自动跳帧控制**：根据设定的目标帧率自动跳过某些帧的处理，确保稳定输出
- **线程安全设计**：所有操作都使用锁保护，确保多线程环境下安全运行
- **智能资源释放**：使用上下文管理器自动释放资源，避免内存泄漏
- **统一错误处理**：标准化的错误类型和提示信息
- **帧处理控制**：内置帧率限制逻辑，确保处理频率适中，避免过度占用系统资源

## 安装说明

### Windows系统

1. 下载或克隆本仓库
2. 进入项目目录：`cd aitoolkit_base`
3. 运行安装脚本：`build_wheel.bat`

### Linux/Mac系统

1. 下载或克隆本仓库
2. 进入项目目录：`cd aitoolkit_base`
3. 添加执行权限：`chmod +x build_wheel.sh`
4. 运行安装脚本：`./build_wheel.sh`

### 手动安装

如果安装脚本不起作用，可以手动安装：

1. 创建模型目录：
```bash
mkdir -p aitoolkit_base/models
```

2. 复制模型文件（从mediapipe-samples目录）到 `aitoolkit_base/models/`

3. 安装依赖：
```bash
pip install -r requirements.txt
```

4. 安装包：
```bash
pip install -e .
```

## 使用方法

### 1. 人脸检测

```python
from aitoolkit_base import FaceDetector
import cv2

# 创建检测器
detector = FaceDetector()

# 读取图像
image = cv2.imread('test.jpg')

# 运行检测
faces = detector.run(image)

# 绘制结果
result = detector.draw(image, faces)
```

### 2. 手势识别

```python
from aitoolkit_base import GestureRecognizer
import cv2

# 创建识别器
recognizer = GestureRecognizer()

# 读取图像
image = cv2.imread('test.jpg')

# 运行识别
gestures = recognizer.run(image)

# 绘制结果
result = recognizer.draw(image, gestures)
```

### 3. 相机实时处理

```python
from aitoolkit_base import Camera, HandLandmarker
import cv2

# 创建相机和检测器
camera = Camera()
detector = HandLandmarker()

# 实时检测循环
while True:
    ret, frame = camera.read()
    if not ret:
        break
        
    # 同步检测，无延迟处理
    hands = detector.run(frame)
    
    # 绘制结果
    result = detector.draw(frame, hands)
    
    # 显示FPS和检测信息
    fps = detector.get_fps()
    cv2.putText(result, f"FPS: {fps:.1f}", (10, 30), 
               cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
    
    cv2.imshow("手部检测", result)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

camera.release()
cv2.destroyAllWindows()
```

### 4. 相机迭代器用法

```python
from aitoolkit_base import Camera, FaceDetector
import cv2

# 创建相机和检测器
camera = Camera()
detector = FaceDetector()

# 使用迭代器语法直接遍历视频帧
for frame in camera:
    # 处理每一帧
    faces = detector.run(frame)
    result = detector.draw(frame, faces)
    
    # 显示结果
    cv2.imshow("人脸检测", result)
    
    # 按q键退出
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break
        
# 释放资源
camera.release()
cv2.destroyAllWindows()
```

### 示例：手部关键点检测

```python
import cv2
from aitoolkit_base import HandLandmarker

# 初始化手部关键点检测器
with HandLandmarker() as landmarker:
    # 从文件读取图片
    image = cv2.imread("test_image.jpg")
    if image is None:
        print("无法读取图片")
        exit()

    # 检测并绘制结果
    result_image = landmarker.run(image)

    # 显示结果
    cv2.imshow("Hand Landmarks", result_image)
    cv2.waitKey(0)
    cv2.destroyAllWindows()
```

### 示例：人脸检测

```python
import cv2
from aitoolkit_base import FaceDetector

# 初始化人脸检测器
with FaceDetector() as detector:
    # 打开默认摄像头
    cap = cv2.VideoCapture(0)
    if not cap.isOpened():
        print("无法打开摄像头")
        exit()

    while True:
        # 读取帧
        ret, frame = cap.read()
        if not ret:
            break

        # 检测人脸并绘制结果
        result_frame = detector.run(frame)

        # 显示结果
        cv2.imshow("Face Detection", result_frame)

        # 按 'q' 退出
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break

    # 释放资源
    cap.release()
    cv2.destroyAllWindows()
```

## 实时处理示例

查看 `examples` 目录获取更多实时处理的示例代码。

## 常见问题

1. 模型文件找不到
   - 确保模型文件已正确复制到 `aitoolkit_base/models/` 目录
   - 检查模型文件名是否正确

2. 实时处理速度慢
   - 尝试降低输入图像分辨率
   - 使用 `ImageUtils.resize_image()` 调整图像大小
   - 考虑使用性能更好的硬件

3. 检测不准确
   - 调整 `min_detection_confidence` 参数
   - 确保光线充足
   - 保持适当的距离 
