Metadata-Version: 2.4
Name: aigcqa
Version: 0.1.0
Summary: Production-grade quality gate for AIGC videos — not a benchmark
Author: AIGCQA Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/aigcqa/aigcqa
Project-URL: Repository, https://github.com/aigcqa/aigcqa
Keywords: aigc,video quality,iqa,vqa,quality assessment,computer vision,aigc quality
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0
Requires-Dist: opencv-python>=4.8
Requires-Dist: torch>=2.0
Requires-Dist: torchvision>=0.15
Requires-Dist: lpips>=0.1.4
Requires-Dist: IQA-pytorch>=0.1
Requires-Dist: mediapipe>=0.10
Requires-Dist: jinja2>=3.1
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Provides-Extra: light
Requires-Dist: piq>=0.8; extra == "light"
Requires-Dist: open-clip-torch>=2.0; extra == "light"
Provides-Extra: full
Requires-Dist: transformers>=4.37; extra == "full"
Requires-Dist: accelerate; extra == "full"
Requires-Dist: piq>=0.8; extra == "full"
Requires-Dist: open-clip-torch>=2.0; extra == "full"
Dynamic: license-file

# AIGCQA

**中文** | [English](README_EN.md)

> AIGC 视频生产级质量门控 —— 不是学术基准，是工程工具。

AIGCQA 填补了学术基准（VBench、EvalCrafter —— 慢、重、仅限研究）与生产质量门控（快速、轻量、可组合）之间的空白。

[![PyPI version](https://img.shields.io/pypi/v/aigcqa)](https://pypi.org/project/aigcqa/)
[![Python](https://img.shields.io/pypi/pyversions/aigcqa)](https://pypi.org/project/aigcqa/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 核心特性

- **4 个可组合指标**：人脸质量、时序一致性、手部质量、技术质量
- **3 档后端**：`fast`（无需 GPU）/ `light`（消费级 GPU，CLIP-IQA + open_clip）/ `full`（LMM）
- **可解释输出**：不只是一个数字，精确定位到哪一帧有什么问题
- **多格式输出**：JSON / HTML（含雷达图 + 帧时间轴）
- **多接入方式**：CLI、Python API、ComfyUI 节点

---

## 安装

```bash
pip install aigcqa                # fast 后端（无需 GPU）
pip install aigcqa[light]         # + piq CLIP-IQA + open_clip 时序分析
pip install aigcqa[full]          # + LMM 解释器（Qwen2.5-1.5B-Instruct）
```

---

## 快速开始

```python
from aigcqa import quick_assess

result = quick_assess("video.mp4")
print(result.passed)           # True / False
print(result.overall_score)    # 例如 82.4
print(result.recommendation)   # "建议重新生成 frames 30-67"
result.to_html("report.html")  # 含雷达图 + 帧时间轴的 HTML 报告
```

---

## 完整流水线

```python
from aigcqa import QualityPipeline, FaceMetric, TemporalMetric, HandMetric, TechnicalMetric

pipe = QualityPipeline(
    metrics=[
        FaceMetric(backend="light"),
        TemporalMetric(backend="light"),
        HandMetric(backend="fast"),
        TechnicalMetric(backend="light"),
    ],
    threshold=80.0,
    weights={"face": 0.3, "temporal": 0.3, "hand": 0.2, "technical": 0.2},
)
report = pipe.run("output.mp4")
report.to_html("report.html")
print(report.to_json())
```

---

## CLI

```bash
# 基础评测
aigcqa assess video.mp4

# light 后端，自定义阈值，输出 HTML
aigcqa assess video.mp4 --backend light --threshold 80 --output report.html

# JSON 输出
aigcqa assess video.mp4 --format json

# 使用 LMM 解释器
aigcqa assess video.mp4 --explainer lmm --lmm-model Qwen/Qwen2.5-1.5B-Instruct

# 批量评测整个目录
aigcqa batch ./outputs/

# 查看所有指标
aigcqa list-metrics
```

---

## 指标说明

| 指标 | fast 后端 | light 后端 | full 后端 |
|------|-----------|------------|-----------|
| `face` | OpenCV Haar + 拉普拉斯清晰度 | + CLIP 零样本人脸质量 | Qwen2-VL |
| `temporal` | LPIPS 帧间差异 | + open_clip 身份漂移检测 | T2VQA |
| `hand` | MediaPipe 手部检测 | + 骨架几何规则校验 | HandEval + CLIP |
| `technical` | 亮度/曝光分析 | piq CLIP-IQA | FAST-VQA |

### 后端对比

| 后端 | 速度 | 是否需要 GPU | 精度 | 适用场景 |
|------|------|-------------|------|----------|
| `fast` | <0.5s/帧 | 否 | 基础 | CI 流水线、快速过滤 |
| `light` | ~1s/帧 | 消费级 GPU | 中等 | 日常生产工作流 |
| `full` | ~3s/帧 | 多卡 | 最高 | 最终质量验收 |

---

## 输出格式

```json
{
  "overall_score": 68.4,
  "passed": false,
  "threshold": 75.0,
  "source": "output.mp4",
  "metrics": {
    "face": {"score": 82.1, "issues": [...], "meta": {...}},
    "temporal": {"score": 41.3, "issues": [...], "meta": {...}}
  },
  "explanation": {
    "backend": "rule",
    "summary": "视频时序一致性存在明显问题",
    "recommendation": "建议重新生成 frames 30-45",
    "detail": "时序一致性 41分（较差）；人脸质量 82分（良好）"
  }
}
```

---

## LMM 解释器

```python
from aigcqa import QualityPipeline, TechnicalMetric, FaceMetric, LMMExplainer

pipe = QualityPipeline(
    metrics=[TechnicalMetric(backend="light"), FaceMetric(backend="light")],
    explainer=LMMExplainer(model_name="Qwen/Qwen2.5-1.5B-Instruct"),
)
report = pipe.run("video.mp4")
print(report.explanation.summary)  # 自然语言质量分析
```

---

## ComfyUI 集成

将 `examples/comfyui_node.py` 复制到 `ComfyUI/custom_nodes/aigcqa_node.py`。

注册两个节点：
- **AIGCQA Quality Gate**：输入 IMAGE batch → 输出分数、是否通过、报告 JSON
- **AIGCQA Report Renderer**：输入报告 JSON → 输出 HTML

---

## 学术背景

- **DOVER** (ICCV 2023)：分离式目标视频质量评估，美学 + 技术双分支
- **HandEval** (arXiv 2510.08978, 2025)：首篇生成图像手部质量评估论文
- **NTIRE 2025 XGC Challenge**：说话人头部质量评估，直接验证数字人质量市场需求
- **VQAThinker** (2025)：具备推理能力的可解释 VQA
- **AgenticIQA** (2025)：可解释图像质量评估的智能体框架

---

## Roadmap

| 版本 | 状态 | 功能 |
|------|------|------|
| v0.1.0 | ✅ 已发布 | 4 指标全后端（fast/light）、规则/LMM 解释器、CLI、HTML+JSON、ComfyUI |
| v1.0 | 规划中 | full 后端（FAST-VQA、LLaVA）、REST API 服务 |

---

## License

MIT — 详见 [LICENSE](LICENSE)
