docs: 添加完整的中文文档支持
中文版用户指南 - 创建详细的中文用户指南 (docs/用户指南.md) - 包含快速开始、常见使用场景 - 配置管理和模型选择指南 - 性能优化和错误处理 - 进度跟踪和最佳实践 - 故障排除和获取帮助 中文版 API 文档 - 创建完整的中文 API 文档 (docs/API文档.md) - 核心组件和方法说明 - 配置管理和 AI 模型介绍 - 快速开始函数和性能优化 - 错误处理和系统检测 - 参数详解和质量预设 中文版 README - 创建中文版主说明文档 (README_CN.md) - 主要特性和快速开始 - 支持的 AI 模型详细列表 - 使用场景和配置管理 - 性能监控和错误处理 - 系统要求和开发状态 文档链接更新 - 更新主 README 添加中文文档链接 - 分别提供英文和中文文档入口 - 完整的文档资源导航 文档完整性 - 英文文档: API.md + USER_GUIDE.md + README.md - 中文文档: API文档.md + 用户指南.md + README_CN.md - 双语支持，内容完全对应 - 适合中文开发者使用 国际化支持 - 完整的中英文双语文档 - 中文技术术语准确翻译 - 符合中文开发者阅读习惯 - 提供本地化的使用示例 项目文档现已完全国际化，支持中英文双语！
This commit is contained in:
imeepos
@@ -195,8 +195,16 @@ match quick_upscale_video(input, output, 2.0).await {
|
||||
|
||||
## Documentation
|
||||
|
||||
### English
|
||||
- 📖 [API Documentation](docs/API.md) - Complete API reference
|
||||
- 📚 [User Guide](docs/USER_GUIDE.md) - Comprehensive usage guide
|
||||
|
||||
### 中文文档
|
||||
- 📖 [API 文档](docs/API文档.md) - 完整 API 参考
|
||||
- 📚 [用户指南](docs/用户指南.md) - 详细使用指南
|
||||
- 📋 [中文 README](README_CN.md) - 中文版说明文档
|
||||
|
||||
### Resources
|
||||
- 🔧 [Examples](examples/) - Working code examples
|
||||
- 🧪 [Tests](tests/) - Integration tests
|
||||
- 📊 [Benchmarks](benches/) - Performance benchmarks
|
||||
|
||||
344
cargos/tvai/README_CN.md
Normal file
344
cargos/tvai/README_CN.md
Normal file
@@ -0,0 +1,344 @@
|
||||
# TVAI - Topaz Video AI Rust 库
|
||||
|
||||
[](https://www.rust-lang.org)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
|
||||
一个功能完整的 Rust 库，为 [Topaz Video AI](https://www.topazlabs.com/topaz-video-ai) 提供编程接口，支持 AI 驱动的视频和图像超分辨率、帧插值等功能。
|
||||
|
||||
## ✨ 主要特性
|
||||
|
||||
### 🎬 视频处理
|
||||
- **AI 超分辨率** - 使用 16 种专业 AI 模型进行视频放大
|
||||
- **帧插值** - 创建流畅的慢动作效果，支持 4 种插值模型
|
||||
- **组合增强** - 同时应用超分辨率和插值
|
||||
- **格式转换** - 视频与图像序列互转
|
||||
- **批量处理** - 高效处理多个文件
|
||||
|
||||
### 🖼️ 图像处理
|
||||
- **AI 超分辨率** - 智能图像放大和增强
|
||||
- **批量处理** - 处理整个目录的图像
|
||||
- **格式转换** - 支持 PNG、JPG、TIFF、BMP
|
||||
- **预设优化** - 针对不同内容类型的优化预设
|
||||
|
||||
### ⚡ 性能优化
|
||||
- **GPU 加速** - 支持 CUDA 和硬件编码
|
||||
- **并发处理** - 可配置的并行操作
|
||||
- **内存管理** - 高效的临时文件处理
|
||||
- **智能缓存** - 智能资源利用
|
||||
- **性能监控** - 实时性能跟踪
|
||||
|
||||
### 🛠️ 便捷功能
|
||||
- **全局配置** - 持久化设置管理
|
||||
- **预设系统** - 14 种内置处理预设
|
||||
- **错误处理** - 用户友好的错误消息
|
||||
- **进度跟踪** - 实时处理进度
|
||||
- **自动检测** - 智能系统和 GPU 检测
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 安装
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tvai = "0.1.0"
|
||||
tokio = { version = "1.0", features = ["full"] }
|
||||
```
|
||||
|
||||
### 基础使用
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// 快速 2 倍视频放大
|
||||
quick_upscale_video(
|
||||
std::path::Path::new("输入.mp4"),
|
||||
std::path::Path::new("输出.mp4"),
|
||||
2.0,
|
||||
).await?;
|
||||
|
||||
println!("视频增强完成！");
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 高级使用
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// 创建配置
|
||||
let config = TvaiConfig::builder()
|
||||
.topaz_path("/path/to/topaz")
|
||||
.use_gpu(true)
|
||||
.build()?;
|
||||
|
||||
// 创建处理器
|
||||
let mut processor = TvaiProcessor::new(config)?;
|
||||
|
||||
// 使用预设进行老视频修复
|
||||
let params = VideoUpscaleParams::for_old_video();
|
||||
|
||||
// 带进度跟踪的处理
|
||||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||||
println!("进度: {:.1}%", progress * 100.0);
|
||||
});
|
||||
|
||||
let result = processor.upscale_video(
|
||||
std::path::Path::new("老视频.mp4"),
|
||||
std::path::Path::new("修复后.mp4"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("处理完成，耗时: {:?}", result.processing_time);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## 📚 支持的 AI 模型
|
||||
|
||||
### 超分辨率模型 (16 种)
|
||||
|
||||
| 模型 | 最适合 | 倍数 | 描述 |
|
||||
|------|--------|------|------|
|
||||
| **Iris v3** | 通用 | 1-4x | 最佳整体质量，推荐首选 |
|
||||
| **Nyx v3** | 人像 | 1-4x | 面部和人像优化 |
|
||||
| **Theia Fidelity v4** | 老内容 | 2x | 老视频和损坏内容修复 |
|
||||
| **Gaia HQ v5** | 游戏/CG | 1-4x | 游戏录像和 CG 内容 |
|
||||
| **Proteus v4** | 问题素材 | 1-4x | 修复严重伪影和问题 |
|
||||
| **Artemis LQ v13** | 低质量 | 1-4x | 极低质量内容增强 |
|
||||
| **Artemis MQ v13** | 中等质量 | 1-4x | 中等质量内容优化 |
|
||||
| **Artemis HQ v13** | 高质量 | 1-4x | 高质量内容精细化 |
|
||||
| **Theia Detail v3** | 细节 | 2x | 细节保持和增强 |
|
||||
| **Theia Fidelity v3** | 保真度 | 2x | 高保真度处理 |
|
||||
| **Dione DV v2** | DV 素材 | 2x | DV 摄像机素材 |
|
||||
| **Dione TV v2** | 电视 | 2x | 电视广播内容 |
|
||||
| **Dione Robust v2** | 鲁棒性 | 2x | 各种质量内容 |
|
||||
| **Dione Robust Detail v2** | 鲁棒细节 | 2x | 细节保持的鲁棒处理 |
|
||||
| **Rhea v1** | 实验性 | 1-4x | 实验性高质量模型 |
|
||||
| **Dione RD v1** | 研发 | 2x | 研发测试模型 |
|
||||
|
||||
### 插值模型 (4 种)
|
||||
|
||||
| 模型 | 最适合 | 描述 |
|
||||
|------|--------|------|
|
||||
| **Apollo v8** | 高质量 | 最佳整体插值质量 |
|
||||
| **Chronos v2** | 动画 | 卡通和动漫内容优化 |
|
||||
| **Apollo Fast v1** | 速度 | 快速处理，质量略低 |
|
||||
| **Chronos Fast v3** | 快速动画 | 快速动画内容处理 |
|
||||
|
||||
## 🎯 使用场景
|
||||
|
||||
### 视频增强
|
||||
```rust
|
||||
// 老视频修复
|
||||
let result = quick_upscale_video(input, output, 2.0).await?;
|
||||
|
||||
// 自动智能增强
|
||||
let result = auto_enhance_video(input, output).await?;
|
||||
|
||||
// 创建慢动作效果
|
||||
let params = InterpolationParams::for_slow_motion(30, 4.0);
|
||||
let result = processor.interpolate_video(input, output, params, None).await?;
|
||||
```
|
||||
|
||||
### 图像处理
|
||||
```rust
|
||||
// 批量照片增强
|
||||
let results = batch_upscale_directory(
|
||||
Path::new("照片目录"),
|
||||
Path::new("输出目录"),
|
||||
2.0,
|
||||
true // 递归处理
|
||||
).await?;
|
||||
|
||||
// 单张图片增强
|
||||
let result = quick_upscale_image(input, output, 2.0).await?;
|
||||
```
|
||||
|
||||
### 格式转换
|
||||
```rust
|
||||
// 视频转图片序列
|
||||
let frames = processor.video_to_images(
|
||||
Path::new("视频.mp4"),
|
||||
Path::new("帧/"),
|
||||
"png",
|
||||
95
|
||||
).await?;
|
||||
|
||||
// 图片序列转视频
|
||||
processor.images_to_video(
|
||||
&frame_paths,
|
||||
Path::new("输出.mp4"),
|
||||
30.0,
|
||||
QualityPreset::HighQuality
|
||||
).await?;
|
||||
```
|
||||
|
||||
## 🔧 配置管理
|
||||
|
||||
### 全局设置
|
||||
```rust
|
||||
use tvai::config::global_settings;
|
||||
|
||||
let settings = global_settings();
|
||||
settings.set_default_use_gpu(true)?;
|
||||
settings.set_max_concurrent_jobs(2)?;
|
||||
settings.save_to_file()?; // 自动保存到用户配置目录
|
||||
```
|
||||
|
||||
### 预设管理
|
||||
```rust
|
||||
use tvai::config::global_presets;
|
||||
|
||||
let presets = global_presets();
|
||||
let preset_manager = presets.lock().unwrap();
|
||||
|
||||
// 使用内置预设
|
||||
let video_preset = preset_manager.get_video_preset("old_video_restore");
|
||||
let image_preset = preset_manager.get_image_preset("photo_2x");
|
||||
```
|
||||
|
||||
## 📊 性能监控
|
||||
|
||||
```rust
|
||||
use tvai::utils::{PerformanceMonitor, optimize_for_system};
|
||||
|
||||
// 自动优化系统设置
|
||||
let settings = optimize_for_system();
|
||||
let mut monitor = PerformanceMonitor::new(settings);
|
||||
|
||||
// 监控处理性能
|
||||
let _permit = monitor.acquire_slot().await?;
|
||||
// ... 执行处理 ...
|
||||
|
||||
// 获取性能建议
|
||||
let summary = monitor.get_summary();
|
||||
for recommendation in summary.recommendations {
|
||||
println!("💡 {}", recommendation);
|
||||
}
|
||||
```
|
||||
|
||||
## 🛡️ 错误处理
|
||||
|
||||
库提供用户友好的错误消息和解决建议：
|
||||
|
||||
```rust
|
||||
match result {
|
||||
Ok(output) => println!("✅ 处理成功"),
|
||||
Err(error) => {
|
||||
println!("❌ 错误类型: {}", error.category());
|
||||
println!("🔄 可恢复: {}", error.is_recoverable());
|
||||
println!("💡 解决建议:\n{}", error.user_friendly_message());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📋 系统要求
|
||||
|
||||
### 必需
|
||||
- **Rust 1.70+** - 用于编译
|
||||
- **Topaz Video AI** - 主程序 ([下载地址](https://www.topazlabs.com/topaz-video-ai))
|
||||
|
||||
### 推荐
|
||||
- **NVIDIA GPU** - 支持 CUDA 的显卡 (GTX 1060+ 或更好)
|
||||
- **16GB+ RAM** - 处理大文件
|
||||
- **SSD 存储** - 更快的临时文件处理
|
||||
|
||||
### 支持的平台
|
||||
- ✅ Windows 10/11
|
||||
- ✅ macOS 10.15+
|
||||
- ✅ Linux (Ubuntu 18.04+)
|
||||
|
||||
## 📖 文档
|
||||
|
||||
- 📚 [用户指南](docs/用户指南.md) - 详细使用指南
|
||||
- 📖 [API 文档](docs/API文档.md) - 完整 API 参考
|
||||
- 🔧 [示例代码](examples/) - 工作示例
|
||||
- 🧪 [测试](tests/) - 集成测试
|
||||
- 📊 [基准测试](benches/) - 性能基准
|
||||
|
||||
## 🧪 测试
|
||||
|
||||
运行完整测试套件：
|
||||
|
||||
```bash
|
||||
# 单元测试和集成测试
|
||||
cargo test
|
||||
|
||||
# 性能基准测试
|
||||
cargo bench
|
||||
|
||||
# 运行示例
|
||||
cargo run --example basic_usage
|
||||
cargo run --example video_processing
|
||||
cargo run --example image_processing
|
||||
```
|
||||
|
||||
## 📈 开发状态
|
||||
|
||||
✅ **完成** - 所有核心功能已实现并测试！
|
||||
|
||||
- [x] 基础项目结构
|
||||
- [x] FFmpeg 管理
|
||||
- [x] 核心处理器框架
|
||||
- [x] 视频超分辨率实现 (16 种 AI 模型)
|
||||
- [x] 帧插值实现 (4 种 AI 模型)
|
||||
- [x] 图像超分辨率实现
|
||||
- [x] 批量处理 (视频和图像)
|
||||
- [x] 进度回调和监控
|
||||
- [x] 全局配置管理
|
||||
- [x] 预设管理系统
|
||||
- [x] 性能优化
|
||||
- [x] 增强错误处理
|
||||
- [x] 全面测试 (单元 + 集成 + 基准)
|
||||
- [x] 完整文档 (API + 用户指南)
|
||||
|
||||
## 📊 项目统计
|
||||
|
||||
- **总代码行数**: 4,127 行
|
||||
- **模块文件**: 25 个
|
||||
- **示例文件**: 6 个
|
||||
- **测试覆盖**: 17 个测试 + 13 个基准
|
||||
- **文档**: 完整的中英文文档
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎贡献！请随时提交 Pull Request。
|
||||
|
||||
### 开发设置
|
||||
|
||||
1. 安装 Rust 1.70+
|
||||
2. 安装 Topaz Video AI
|
||||
3. 克隆仓库
|
||||
4. 运行测试: `cargo test`
|
||||
5. 运行示例: `cargo run --example basic_usage`
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
MIT 许可证 - 详见 LICENSE 文件。
|
||||
|
||||
## 🔄 更新日志
|
||||
|
||||
### v0.1.0 (当前版本)
|
||||
|
||||
- ✅ 完整的视频处理 (超分辨率 + 插值)
|
||||
- ✅ 完整的图像处理 (超分辨率 + 批量操作)
|
||||
- ✅ 16 种 AI 超分辨率模型 + 4 种插值模型
|
||||
- ✅ 全局配置和预设管理
|
||||
- ✅ 性能监控和优化
|
||||
- ✅ 增强错误处理和用户友好消息
|
||||
- ✅ 全面文档和示例
|
||||
- ✅ 完整测试覆盖 (单元 + 集成 + 基准)
|
||||
|
||||
## 🌟 致谢
|
||||
|
||||
感谢 [Topaz Labs](https://www.topazlabs.com/) 开发了出色的 Topaz Video AI 软件。
|
||||
|
||||
---
|
||||
|
||||
**🎯 项目完成度: 100%** - 所有功能已实现并可用于生产环境！
|
||||
375
cargos/tvai/docs/API文档.md
Normal file
375
cargos/tvai/docs/API文档.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# TVAI 库 API 文档
|
||||
|
||||
## 概述
|
||||
|
||||
TVAI 库为 Topaz Video AI 提供了全面的 Rust 接口，通过 AI 驱动的超分辨率和帧插值实现视频和图像增强。
|
||||
|
||||
## 核心组件
|
||||
|
||||
### TvaiProcessor
|
||||
|
||||
所有视频和图像操作的主处理器。
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
// 创建配置
|
||||
let config = TvaiConfig::builder()
|
||||
.topaz_path("/topaz/路径")
|
||||
.use_gpu(true)
|
||||
.build()?;
|
||||
|
||||
// 创建处理器
|
||||
let mut processor = TvaiProcessor::new(config)?;
|
||||
```
|
||||
|
||||
#### 视频处理方法
|
||||
|
||||
- `upscale_video()` - AI 驱动的视频超分辨率
|
||||
- `interpolate_video()` - 慢动作帧插值
|
||||
- `enhance_video()` - 组合超分辨率和插值
|
||||
- `images_to_video()` - 图像序列转视频
|
||||
- `video_to_images()` - 从视频提取帧
|
||||
|
||||
#### 图像处理方法
|
||||
|
||||
- `upscale_image()` - AI 驱动的图像超分辨率
|
||||
- `batch_upscale_images()` - 处理多张图像
|
||||
- `upscale_directory()` - 处理整个目录
|
||||
- `convert_image_format()` - 格式转换
|
||||
- `resize_image()` - 传统几何缩放
|
||||
|
||||
### 配置管理
|
||||
|
||||
#### TvaiConfig
|
||||
|
||||
处理器的主配置。
|
||||
|
||||
```rust
|
||||
let config = TvaiConfig::builder()
|
||||
.topaz_path("/topaz/路径")
|
||||
.use_gpu(true)
|
||||
.temp_dir("/自定义/临时目录")
|
||||
.force_topaz_ffmpeg(true)
|
||||
.build()?;
|
||||
```
|
||||
|
||||
#### 全局设置
|
||||
|
||||
持久化的全局配置。
|
||||
|
||||
```rust
|
||||
use tvai::config::global_settings;
|
||||
|
||||
let settings = global_settings();
|
||||
settings.set_default_use_gpu(true)?;
|
||||
settings.set_max_concurrent_jobs(2)?;
|
||||
```
|
||||
|
||||
### AI 模型
|
||||
|
||||
#### 超分辨率模型
|
||||
|
||||
- `Iris3` - 最佳通用模型
|
||||
- `Nyx3` - 人像优化
|
||||
- `Thf4` - 老内容修复
|
||||
- `Ghq5` - 游戏/CG 内容
|
||||
- `Prob4` - 问题素材修复
|
||||
- 以及 11 个其他专业模型
|
||||
|
||||
#### 插值模型
|
||||
|
||||
- `Apo8` - 高质量插值
|
||||
- `Chr2` - 动画内容
|
||||
- `Apf1` - 快速处理
|
||||
- `Chf3` - 快速动画
|
||||
|
||||
### 参数预设
|
||||
|
||||
#### 视频预设
|
||||
|
||||
```rust
|
||||
// 内置预设
|
||||
let old_video = VideoUpscaleParams::for_old_video();
|
||||
let game_content = VideoUpscaleParams::for_game_content();
|
||||
let animation = VideoUpscaleParams::for_animation();
|
||||
let portrait = VideoUpscaleParams::for_portrait();
|
||||
|
||||
// 插值预设
|
||||
let slow_motion = InterpolationParams::for_slow_motion(30, 2.0);
|
||||
let animation_interp = InterpolationParams::for_animation(24, 2.0);
|
||||
```
|
||||
|
||||
#### 图像预设
|
||||
|
||||
```rust
|
||||
// 内置预设
|
||||
let photo = ImageUpscaleParams::for_photo();
|
||||
let artwork = ImageUpscaleParams::for_artwork();
|
||||
let screenshot = ImageUpscaleParams::for_screenshot();
|
||||
let portrait = ImageUpscaleParams::for_portrait();
|
||||
```
|
||||
|
||||
### 预设管理
|
||||
|
||||
```rust
|
||||
use tvai::config::global_presets;
|
||||
|
||||
let presets = global_presets();
|
||||
let preset_manager = presets.lock().unwrap();
|
||||
|
||||
// 获取预设
|
||||
if let Some(preset) = preset_manager.get_video_preset("general_2x") {
|
||||
// 使用预设参数
|
||||
}
|
||||
|
||||
// 列出所有预设
|
||||
let video_presets = preset_manager.list_video_presets();
|
||||
let image_presets = preset_manager.list_image_presets();
|
||||
```
|
||||
|
||||
## 快速开始函数
|
||||
|
||||
### 视频处理
|
||||
|
||||
```rust
|
||||
// 快速 2 倍放大
|
||||
quick_upscale_video(
|
||||
Path::new("输入.mp4"),
|
||||
Path::new("输出.mp4"),
|
||||
2.0
|
||||
).await?;
|
||||
|
||||
// 自动增强
|
||||
auto_enhance_video(
|
||||
Path::new("输入.mp4"),
|
||||
Path::new("增强后.mp4")
|
||||
).await?;
|
||||
```
|
||||
|
||||
### 图像处理
|
||||
|
||||
```rust
|
||||
// 快速 2 倍放大
|
||||
quick_upscale_image(
|
||||
Path::new("照片.jpg"),
|
||||
Path::new("照片_2x.png"),
|
||||
2.0
|
||||
).await?;
|
||||
|
||||
// 自动增强
|
||||
auto_enhance_image(
|
||||
Path::new("照片.jpg"),
|
||||
Path::new("增强后.png")
|
||||
).await?;
|
||||
|
||||
// 批量目录处理
|
||||
batch_upscale_directory(
|
||||
Path::new("输入目录"),
|
||||
Path::new("输出目录"),
|
||||
2.0,
|
||||
true // 递归
|
||||
).await?;
|
||||
```
|
||||
|
||||
## 性能和优化
|
||||
|
||||
### GPU 检测
|
||||
|
||||
```rust
|
||||
use tvai::utils::GpuManager;
|
||||
|
||||
// 详细的 GPU 信息
|
||||
let gpu_info = GpuManager::detect_detailed_gpu_info();
|
||||
println!("CUDA 可用: {}", gpu_info.cuda_available);
|
||||
println!("设备数量: {}", gpu_info.devices.len());
|
||||
|
||||
// 检查 AI 适用性
|
||||
let suitable = GpuManager::is_gpu_suitable_for_ai();
|
||||
|
||||
// 基准测试性能
|
||||
let benchmark = GpuManager::benchmark_gpu_performance().await?;
|
||||
```
|
||||
|
||||
### 性能监控
|
||||
|
||||
```rust
|
||||
use tvai::utils::{PerformanceMonitor, optimize_for_system};
|
||||
|
||||
// 创建优化设置
|
||||
let settings = optimize_for_system();
|
||||
let mut monitor = PerformanceMonitor::new(settings);
|
||||
|
||||
// 监控操作
|
||||
let _permit = monitor.acquire_slot().await?;
|
||||
let operation_monitor = monitor.start_operation("upscale", 100.0);
|
||||
|
||||
// ... 执行处理 ...
|
||||
|
||||
let metrics = operation_monitor.finish(200.0);
|
||||
monitor.record_metrics(metrics);
|
||||
|
||||
// 获取性能摘要
|
||||
let summary = monitor.get_summary();
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 错误类型
|
||||
|
||||
库提供了带有用户友好消息的全面错误处理：
|
||||
|
||||
```rust
|
||||
match result {
|
||||
Ok(output) => println!("成功: {:?}", output),
|
||||
Err(error) => {
|
||||
println!("错误类别: {}", error.category());
|
||||
println!("可恢复: {}", error.is_recoverable());
|
||||
println!("用户消息:\n{}", error.user_friendly_message());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误类别
|
||||
|
||||
- `installation` - 找不到 Topaz/FFmpeg
|
||||
- `processing` - 处理失败
|
||||
- `parameter` - 无效参数
|
||||
- `gpu` - GPU 相关错误
|
||||
- `format` - 不支持的格式
|
||||
- `resources` - 资源不足
|
||||
- `permission` - 权限被拒绝
|
||||
- `io` - 文件 I/O 错误
|
||||
|
||||
## 系统检测
|
||||
|
||||
### 自动检测
|
||||
|
||||
```rust
|
||||
// 检测 Topaz 安装
|
||||
let topaz_path = detect_topaz_installation();
|
||||
|
||||
// 检测 FFmpeg 可用性
|
||||
let ffmpeg_info = detect_ffmpeg();
|
||||
|
||||
// 检测 GPU 支持
|
||||
let gpu_info = detect_gpu_support();
|
||||
```
|
||||
|
||||
### 文件信息
|
||||
|
||||
```rust
|
||||
// 获取视频信息
|
||||
let video_info = get_video_info(Path::new("视频.mp4")).await?;
|
||||
println!("时长: {:?}", video_info.duration);
|
||||
println!("分辨率: {}x{}", video_info.width, video_info.height);
|
||||
|
||||
// 获取图像信息
|
||||
let image_info = get_image_info(Path::new("图像.jpg"))?;
|
||||
println!("尺寸: {}x{}", image_info.width, image_info.height);
|
||||
```
|
||||
|
||||
## 进度跟踪
|
||||
|
||||
```rust
|
||||
// 创建进度回调
|
||||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||||
println!("进度: {:.1}%", progress * 100.0);
|
||||
});
|
||||
|
||||
// 与处理函数一起使用
|
||||
processor.upscale_video(
|
||||
input,
|
||||
output,
|
||||
params,
|
||||
Some(&progress_callback)
|
||||
).await?;
|
||||
```
|
||||
|
||||
## 临时文件管理
|
||||
|
||||
```rust
|
||||
use tvai::utils::TempFileManager;
|
||||
|
||||
let mut temp_manager = TempFileManager::new(None)?;
|
||||
|
||||
// 创建临时文件
|
||||
let temp_path = temp_manager.create_temp_path("操作", "临时.mp4");
|
||||
let unique_path = temp_manager.create_unique_temp_path("输出.png");
|
||||
|
||||
// 清理
|
||||
temp_manager.cleanup_operation("操作")?;
|
||||
temp_manager.cleanup_all()?;
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **使用预设** 处理常见场景
|
||||
2. **启用 GPU** 获得更好性能
|
||||
3. **监控进度** 处理长时间操作
|
||||
4. **优雅处理错误** 使用用户友好消息
|
||||
5. **使用全局设置** 保持一致配置
|
||||
6. **验证参数** 在处理前
|
||||
7. **清理** 处理后的临时文件
|
||||
8. **检查系统要求** 开始前
|
||||
|
||||
## 示例
|
||||
|
||||
查看 `examples/` 目录获取完整的工作示例：
|
||||
|
||||
- `basic_usage.rs` - 简单入门示例
|
||||
- `advanced_usage.rs` - 高级功能演示
|
||||
- `video_processing.rs` - 全面的视频处理
|
||||
- `image_processing.rs` - 全面的图像处理
|
||||
- `convenience_and_optimization.rs` - 便捷功能和优化
|
||||
|
||||
## 参数详解
|
||||
|
||||
### VideoUpscaleParams
|
||||
|
||||
```rust
|
||||
pub struct VideoUpscaleParams {
|
||||
pub scale_factor: f32, // 缩放倍数 (1.0-4.0)
|
||||
pub model: UpscaleModel, // AI 模型
|
||||
pub compression: f32, // 压缩设置 (-1.0 到 1.0)
|
||||
pub blend: f32, // 混合设置 (0.0 到 1.0)
|
||||
pub quality_preset: QualityPreset, // 质量预设
|
||||
}
|
||||
```
|
||||
|
||||
### ImageUpscaleParams
|
||||
|
||||
```rust
|
||||
pub struct ImageUpscaleParams {
|
||||
pub scale_factor: f32, // 缩放倍数 (1.0-4.0)
|
||||
pub model: UpscaleModel, // AI 模型
|
||||
pub compression: f32, // 压缩设置 (-1.0 到 1.0)
|
||||
pub blend: f32, // 混合设置 (0.0 到 1.0)
|
||||
pub output_format: ImageFormat, // 输出格式
|
||||
}
|
||||
```
|
||||
|
||||
### InterpolationParams
|
||||
|
||||
```rust
|
||||
pub struct InterpolationParams {
|
||||
pub input_fps: u32, // 输入帧率
|
||||
pub multiplier: f32, // 倍数 (1.0-8.0)
|
||||
pub model: InterpolationModel, // 插值模型
|
||||
pub target_fps: Option<u32>, // 目标帧率 (可选)
|
||||
}
|
||||
```
|
||||
|
||||
## 质量预设
|
||||
|
||||
- `HighQuality` - 高质量 (慢速)
|
||||
- `Balanced` - 平衡 (中等速度)
|
||||
- `Fast` - 快速 (低质量)
|
||||
- `Custom` - 自定义设置
|
||||
|
||||
## 图像格式
|
||||
|
||||
- `Png` - PNG 格式 (无损)
|
||||
- `Jpg` - JPEG 格式 (有损)
|
||||
- `Tiff` - TIFF 格式 (专业)
|
||||
- `Bmp` - BMP 格式 (未压缩)
|
||||
422
cargos/tvai/docs/用户指南.md
Normal file
422
cargos/tvai/docs/用户指南.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# TVAI 库用户指南
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 安装
|
||||
|
||||
在您的 `Cargo.toml` 中添加 TVAI：
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tvai = "0.1.0"
|
||||
```
|
||||
|
||||
### 前置要求
|
||||
|
||||
1. **Topaz Video AI** - 从 [Topaz Labs](https://www.topazlabs.com/topaz-video-ai) 下载并安装
|
||||
2. **GPU 驱动** - 最新的 NVIDIA 或 AMD 驱动程序以支持 GPU 加速
|
||||
3. **Rust 1.70+** - 用于构建库
|
||||
|
||||
### 快速开始
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// 快速 2 倍视频放大
|
||||
quick_upscale_video(
|
||||
std::path::Path::new("输入.mp4"),
|
||||
std::path::Path::new("输出.mp4"),
|
||||
2.0,
|
||||
).await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## 常见使用场景
|
||||
|
||||
### 1. 视频增强
|
||||
|
||||
#### 老视频修复
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
let params = VideoUpscaleParams::for_old_video();
|
||||
let mut processor = create_processor().await?;
|
||||
|
||||
let result = processor.upscale_video(
|
||||
Path::new("老视频.mp4"),
|
||||
Path::new("修复后视频.mp4"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("增强完成，耗时 {:?}", result.processing_time);
|
||||
```
|
||||
|
||||
#### 创建慢动作效果
|
||||
|
||||
```rust
|
||||
let params = InterpolationParams::for_slow_motion(30, 4.0); // 30fps -> 120fps
|
||||
let result = processor.interpolate_video(
|
||||
Path::new("正常速度.mp4"),
|
||||
Path::new("慢动作.mp4"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
#### 完整增强
|
||||
|
||||
```rust
|
||||
let enhance_params = VideoEnhanceParams {
|
||||
upscale: Some(VideoUpscaleParams::for_old_video()),
|
||||
interpolation: Some(InterpolationParams::for_slow_motion(24, 2.0)),
|
||||
};
|
||||
|
||||
let result = processor.enhance_video(
|
||||
Path::new("输入.mp4"),
|
||||
Path::new("增强后.mp4"),
|
||||
enhance_params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
### 2. 图片增强
|
||||
|
||||
#### 批量照片增强
|
||||
|
||||
```rust
|
||||
let image_paths = vec![
|
||||
PathBuf::from("照片1.jpg"),
|
||||
PathBuf::from("照片2.jpg"),
|
||||
PathBuf::from("照片3.jpg"),
|
||||
];
|
||||
|
||||
let params = ImageUpscaleParams::for_photo();
|
||||
let results = processor.batch_upscale_images(
|
||||
&image_paths,
|
||||
Path::new("输出目录"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("处理了 {} 张图片", results.len());
|
||||
```
|
||||
|
||||
#### 目录批量处理
|
||||
|
||||
```rust
|
||||
let results = processor.upscale_directory(
|
||||
Path::new("输入照片"),
|
||||
Path::new("输出照片"),
|
||||
ImageUpscaleParams::for_photo(),
|
||||
true, // 递归处理子目录
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
### 3. 格式转换
|
||||
|
||||
#### 图片序列转视频
|
||||
|
||||
```rust
|
||||
let image_paths = collect_image_sequence("帧/")?;
|
||||
processor.images_to_video(
|
||||
&image_paths,
|
||||
Path::new("输出.mp4"),
|
||||
30.0, // 帧率
|
||||
QualityPreset::HighQuality,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
#### 视频转图片序列
|
||||
|
||||
```rust
|
||||
let image_paths = processor.video_to_images(
|
||||
Path::new("输入.mp4"),
|
||||
Path::new("帧/"),
|
||||
"png",
|
||||
95, // 质量
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("提取了 {} 帧", image_paths.len());
|
||||
```
|
||||
|
||||
## 配置管理
|
||||
|
||||
### 全局设置
|
||||
|
||||
设置全局配置以保持一致的行为：
|
||||
|
||||
```rust
|
||||
use tvai::config::global_settings;
|
||||
|
||||
let settings = global_settings();
|
||||
|
||||
// 配置默认值
|
||||
settings.set_default_use_gpu(true)?;
|
||||
settings.set_max_concurrent_jobs(2)?;
|
||||
|
||||
// 保存设置
|
||||
settings.save_to_file()?;
|
||||
|
||||
// 从全局设置创建处理器
|
||||
let config = settings.create_config()?;
|
||||
let processor = TvaiProcessor::new(config)?;
|
||||
```
|
||||
|
||||
### 自定义配置
|
||||
|
||||
```rust
|
||||
let config = TvaiConfig::builder()
|
||||
.topaz_path("/自定义/topaz/路径")
|
||||
.use_gpu(true)
|
||||
.temp_dir("/快速/ssd/临时目录")
|
||||
.force_topaz_ffmpeg(true)
|
||||
.build()?;
|
||||
|
||||
let processor = TvaiProcessor::new(config)?;
|
||||
```
|
||||
|
||||
## 模型选择指南
|
||||
|
||||
### 超分辨率模型
|
||||
|
||||
| 模型 | 最适合 | 倍数 | 描述 |
|
||||
|------|--------|------|------|
|
||||
| Iris v3 | 通用 | 1-4x | 最佳整体质量 |
|
||||
| Nyx v3 | 人像 | 1-4x | 面部优化 |
|
||||
| Theia Fidelity v4 | 老内容 | 2x | 专注修复 |
|
||||
| Gaia HQ v5 | 游戏/CG | 1-4x | 锐利细节 |
|
||||
| Proteus v4 | 问题素材 | 1-4x | 伪影修复 |
|
||||
|
||||
### 插值模型
|
||||
|
||||
| 模型 | 最适合 | 描述 |
|
||||
|------|--------|------|
|
||||
| Apollo v8 | 高质量 | 最佳整体插值 |
|
||||
| Chronos v2 | 动画 | 卡通/动漫内容 |
|
||||
| Apollo Fast v1 | 速度 | 更快处理 |
|
||||
| Chronos Fast v3 | 快速动画 | 快速动画处理 |
|
||||
|
||||
## 性能优化
|
||||
|
||||
### GPU 优化
|
||||
|
||||
```rust
|
||||
use tvai::utils::GpuManager;
|
||||
|
||||
// 检查 GPU 适用性
|
||||
if GpuManager::is_gpu_suitable_for_ai() {
|
||||
println!("GPU 适合 AI 处理");
|
||||
|
||||
// 获取详细信息
|
||||
let gpu_info = GpuManager::detect_detailed_gpu_info();
|
||||
println!("推荐内存限制: {:?} MB",
|
||||
gpu_info.recommended_settings.memory_limit_mb);
|
||||
}
|
||||
```
|
||||
|
||||
### 性能监控
|
||||
|
||||
```rust
|
||||
use tvai::utils::{PerformanceMonitor, optimize_for_system};
|
||||
|
||||
// 创建优化设置
|
||||
let settings = optimize_for_system();
|
||||
let mut monitor = PerformanceMonitor::new(settings);
|
||||
|
||||
// 带监控的处理
|
||||
let _permit = monitor.acquire_slot().await?;
|
||||
// ... 执行处理 ...
|
||||
|
||||
// 获取建议
|
||||
let summary = monitor.get_summary();
|
||||
for recommendation in summary.recommendations {
|
||||
println!("💡 {}", recommendation);
|
||||
}
|
||||
```
|
||||
|
||||
### 内存管理
|
||||
|
||||
```rust
|
||||
// 为有限内存使用较小的块大小
|
||||
let settings = PerformanceSettings {
|
||||
chunk_size_mb: 50, // 较小的块
|
||||
max_concurrent_ops: 1, // 单个操作
|
||||
processing_mode: ProcessingMode::MemoryEfficient,
|
||||
..Default::default()
|
||||
};
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 全面的错误处理
|
||||
|
||||
```rust
|
||||
match processor.upscale_video(input, output, params, None).await {
|
||||
Ok(result) => {
|
||||
println!("✅ 成功: {:?}", result.processing_time);
|
||||
}
|
||||
Err(error) => {
|
||||
eprintln!("❌ 错误: {}", error.category());
|
||||
eprintln!("{}", error.user_friendly_message());
|
||||
|
||||
if error.is_recoverable() {
|
||||
eprintln!("💡 此错误可能可以通过不同设置恢复");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 常见错误解决方案
|
||||
|
||||
#### 找不到 Topaz
|
||||
```
|
||||
错误: 找不到 Topaz Video AI
|
||||
解决方案: 安装 Topaz Video AI 或设置正确路径
|
||||
```
|
||||
|
||||
#### GPU 错误
|
||||
```
|
||||
错误: CUDA 内存不足
|
||||
解决方案: 降低质量设置或禁用 GPU
|
||||
```
|
||||
|
||||
#### 权限被拒绝
|
||||
```
|
||||
错误: 无法写入输出目录
|
||||
解决方案: 以管理员身份运行或检查权限
|
||||
```
|
||||
|
||||
## 进度跟踪
|
||||
|
||||
### 简单进度条
|
||||
|
||||
```rust
|
||||
use std::io::{self, Write};
|
||||
|
||||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||||
let percentage = (progress * 100.0) as u32;
|
||||
print!("\r进度: [");
|
||||
for i in 0..50 {
|
||||
if i < percentage / 2 {
|
||||
print!("=");
|
||||
} else {
|
||||
print!(" ");
|
||||
}
|
||||
}
|
||||
print!("] {}%", percentage);
|
||||
io::stdout().flush().unwrap();
|
||||
});
|
||||
```
|
||||
|
||||
### 详细进度跟踪
|
||||
|
||||
```rust
|
||||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||||
let percentage = (progress * 100.0) as u32;
|
||||
let eta = estimate_time_remaining(progress);
|
||||
println!("进度: {}% - 预计剩余时间: {:?}", percentage, eta);
|
||||
});
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 文件管理
|
||||
|
||||
```rust
|
||||
// 始终验证输入文件
|
||||
processor.validate_input_file(input_path)?;
|
||||
processor.validate_output_path(output_path)?;
|
||||
|
||||
// 为中间处理使用临时文件
|
||||
let temp_path = processor.create_unique_temp_path("中间.mp4");
|
||||
// ... 处理到临时文件 ...
|
||||
std::fs::rename(temp_path, final_output)?;
|
||||
```
|
||||
|
||||
### 2. 资源管理
|
||||
|
||||
```rust
|
||||
// 使用 RAII 进行自动清理
|
||||
{
|
||||
let mut processor = TvaiProcessor::new(config)?;
|
||||
// 处理在这里进行
|
||||
// 处理器在丢弃时自动清理
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 批量处理
|
||||
|
||||
```rust
|
||||
// 分批处理以避免内存问题
|
||||
let chunk_size = 10;
|
||||
for chunk in image_paths.chunks(chunk_size) {
|
||||
let results = processor.batch_upscale_images(
|
||||
chunk,
|
||||
output_dir,
|
||||
params.clone(),
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
// 处理结果或保存状态
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 错误恢复
|
||||
|
||||
```rust
|
||||
// 为可恢复错误实现重试逻辑
|
||||
let mut attempts = 0;
|
||||
let max_attempts = 3;
|
||||
|
||||
loop {
|
||||
match processor.upscale_video(input, output, params.clone(), None).await {
|
||||
Ok(result) => break Ok(result),
|
||||
Err(error) if error.is_recoverable() && attempts < max_attempts => {
|
||||
attempts += 1;
|
||||
eprintln!("尝试 {} 失败，重试中...", attempts);
|
||||
tokio::time::sleep(Duration::from_secs(1)).await;
|
||||
}
|
||||
Err(error) => break Err(error),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **处理缓慢**
|
||||
- 启用 GPU 加速
|
||||
- 使用更快的模型 (Apollo Fast, Chronos Fast)
|
||||
- 降低质量设置
|
||||
|
||||
2. **内存不足**
|
||||
- 减少块大小
|
||||
- 降低质量预设
|
||||
- 处理较小的文件
|
||||
|
||||
3. **质量结果差**
|
||||
- 为内容类型使用适当的模型
|
||||
- 调整压缩和混合参数
|
||||
- 使用更高质量预设
|
||||
|
||||
4. **文件格式问题**
|
||||
- 首先转换为支持的格式
|
||||
- 检查文件损坏
|
||||
- 验证文件权限
|
||||
|
||||
### 获取帮助
|
||||
|
||||
1. 检查错误消息和建议
|
||||
2. 查看 API 文档
|
||||
3. 运行示例以验证设置
|
||||
4. 检查系统要求和 GPU 驱动程序
|
||||
Reference in New Issue
Block a user