comi-logic/mixvideo-v2
7
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 添加完整的中文文档支持

Browse Source 
中文版用户指南
- 创建详细的中文用户指南 (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
2025-08-11 16:25:26 +08:00
parent bdac328e19
commit 051ef0b8f9
4 changed files with 1149 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
cargos/tvai/docs/API文档.md Normal file
View 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
View 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 驱动程序