feat: Add comprehensive Topaz Video AI filter combinations and model management

cargos/tvai/docs/FILTER_COMBINATIONS_GUIDE.md

@@ -0,0 +1,318 @@
+# Topaz Video AI 滤镜组合使用指南
+
+## 概述
+
+Topaz Video AI 滤镜组合库提供了一套易用的高级 API，封装了复杂的 TVAI 滤镜参数，让您能够轻松地进行各种视频和图片处理任务。
+
+## 快速开始
+
+### 基本用法
+
+```rust
+use tvai::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // 创建处理器
+    let topaz_path = detect_topaz_installation().unwrap();
+    let config = TvaiConfig::builder()
+        .topaz_path(topaz_path)
+        .use_gpu(true)
+        .build()?;
+    
+    let processor = TvaiProcessor::new(config)?;
+    let mut filter_processor = FilterProcessor::new(processor);
+
+    // 视频超分辨率放大
+    let combination = FilterCombination::Upscale {
+        model: UpscaleModel::Iris3,
+        scale: 2.0,
+        quality: QualityLevel::High,
+    };
+
+    let result = filter_processor.apply_to_video(
+        Path::new("input.mp4"),
+        Path::new("output.mp4"),
+        combination,
+        ProcessOptions::default(),
+        None,
+    ).await?;
+
+    println!("处理完成！时间: {:?}", result.processing_time);
+    Ok(())
+}
+```
+
+### 快速函数
+
+对于简单的处理任务，可以使用快速函数：
+
+```rust
+use tvai::filters::quick;
+
+// 快速视频放大
+let result = quick::upscale_video(
+    Path::new("input.mp4"),
+    Path::new("output.mp4"),
+    2.0,
+).await?;
+
+// 快速慢动作处理
+let result = quick::slow_motion(
+    Path::new("input.mp4"),
+    Path::new("output.mp4"),
+    2.0,
+).await?;
+
+// 快速视频稳定化
+let result = quick::stabilize_video(
+    Path::new("input.mp4"),
+    Path::new("output.mp4"),
+    1.0,
+).await?;
+```
+
+## 滤镜组合类型
+
+### 1. 超分辨率放大 (Upscale)
+
+```rust
+let combination = FilterCombination::Upscale {
+    model: UpscaleModel::Iris3,  // AI 模型
+    scale: 2.0,                  // 放大倍数
+    quality: QualityLevel::High, // 质量等级
+};
+```
+
+**可用模型**:
+- `Iris3`: 通用最佳模型
+- `Ahq12`: 高质量模型
+- `Nyx3`: 人像优化模型
+- `Ghq5`: 游戏/CG 内容模型
+- `Prob4`: 问题视频修复模型
+
+### 2. 慢动作处理 (SlowMotion)
+
+```rust
+let combination = FilterCombination::SlowMotion {
+    factor: 2.0,                 // 慢动作倍数
+    quality: QualityLevel::High,
+};
+```
+
+### 3. 视频稳定化 (Stabilize)
+
+```rust
+let combination = FilterCombination::Stabilize {
+    strength: 1.0,               // 稳定化强度 (0.0-2.0)
+    quality: QualityLevel::High,
+};
+```
+
+### 4. 完整增强 (FullEnhance)
+
+```rust
+let combination = FilterCombination::FullEnhance {
+    upscale_factor: 2.0,         // 放大倍数
+    stabilize: true,             // 是否启用稳定化
+    quality: QualityLevel::High,
+};
+```
+
+### 5. 老视频修复 (RestoreOldVideo)
+
+```rust
+let combination = FilterCombination::RestoreOldVideo {
+    upscale_factor: 2.0,         // 放大倍数
+    denoise_level: 0.3,          // 降噪等级 (0.0-1.0)
+    quality: QualityLevel::High,
+};
+```
+
+### 6. 游戏录像优化 (GameFootage)
+
+```rust
+let combination = FilterCombination::GameFootage {
+    upscale_factor: 1.5,         // 放大倍数
+    sharpen: true,               // 是否启用锐化
+    quality: QualityLevel::High,
+};
+```
+
+## 构建器模式
+
+使用构建器模式可以更灵活地配置处理参数：
+
+```rust
+use tvai::{FilterCombinationBuilder, quick_builders};
+
+// 详细配置
+let (combination, options) = FilterCombinationBuilder::new()
+    .upscale(UpscaleModel::Ahq12, 2.0)
+    .quality(QualityLevel::Maximum)
+    .output_format("mp4".to_string())
+    .output_resolution(3840, 2160)
+    .vram_limit(0.8)
+    .keep_audio(true)
+    .device(0)  // 指定 GPU 0
+    .build()?;
+
+// 快速构建器
+let (combination, options) = quick_builders::upscale_hq(2.0)
+    .output_format("mov".to_string())
+    .build()?;
+```
+
+### 可用的快速构建器
+
+- `quick_builders::upscale(scale)` - 标准放大
+- `quick_builders::upscale_hq(scale)` - 高质量放大
+- `quick_builders::slow_motion(factor)` - 慢动作
+- `quick_builders::stabilize()` - 视频稳定化
+- `quick_builders::full_enhance()` - 完整增强
+- `quick_builders::restore_old_video()` - 老视频修复
+- `quick_builders::game_footage()` - 游戏录像优化
+- `quick_builders::social_media()` - 社交媒体优化
+- `quick_builders::portrait()` - 人像优化
+- `quick_builders::animation()` - 动画优化
+
+## 预设系统
+
+### 内置预设
+
+```rust
+use tvai::PresetType;
+
+// 使用内置预设
+let preset = PresetType::Gaming;
+let combination = preset.get_filter_combination();
+let options = preset.get_process_options();
+
+println!("预设描述: {}", preset.description());
+```
+
+**可用预设**:
+- `SocialMedia` - 社交媒体优化
+- `FilmRestoration` - 电影修复
+- `Gaming` - 游戏录像
+- `Surveillance` - 监控视频
+- `Animation` - 动画内容
+- `Portrait` - 人像视频
+- `Landscape` - 风景视频
+- `QuickPreview` - 快速预览
+
+### 自定义预设
+
+```rust
+use tvai::CustomPreset;
+
+// 创建自定义预设
+let preset = CustomPreset::builder("我的预设".to_string())
+    .with_combination(FilterCombination::Upscale {
+        model: UpscaleModel::Iris3,
+        scale: 2.0,
+        quality: QualityLevel::High,
+    })
+    .with_options(ProcessOptions {
+        output_format: Some("mp4".to_string()),
+        keep_audio: true,
+        ..Default::default()
+    })
+    .with_description("自定义高质量放大预设".to_string())
+    .build()?;
+
+// 保存预设
+preset.save_to_file(Path::new("my_preset.json"))?;
+
+// 加载预设
+let loaded_preset = CustomPreset::load_from_file(Path::new("my_preset.json"))?;
+```
+
+## 处理选项
+
+```rust
+let options = ProcessOptions {
+    output_format: Some("mp4".to_string()),    // 输出格式
+    keep_audio: true,                          // 保留音频
+    output_resolution: Some((1920, 1080)),     // 输出分辨率
+    device: -2,                                // 设备 (-2=自动, -1=CPU, 0+=GPU)
+    vram_limit: 1.0,                          // VRAM 使用限制 (0.1-1.0)
+    enable_progress: true,                     // 启用进度回调
+};
+```
+
+## 质量等级
+
+- `QualityLevel::Fast` - 快速处理
+- `QualityLevel::Balanced` - 平衡质量和速度
+- `QualityLevel::High` - 高质量
+- `QualityLevel::Maximum` - 最高质量
+
+## 进度回调
+
+```rust
+let progress_callback = Box::new(|progress: f32| {
+    let percentage = (progress * 100.0) as u32;
+    println!("处理进度: {}%", percentage);
+});
+
+let result = filter_processor.apply_to_video(
+    input_path,
+    output_path,
+    combination,
+    options,
+    Some(&progress_callback),
+).await?;
+```
+
+## 智能推荐
+
+系统可以根据视频特征自动推荐最适合的滤镜组合：
+
+```rust
+let recommended = filter_processor.get_recommended_combination(
+    Path::new("input.mp4")
+).await?;
+
+println!("推荐的组合: {:?}", recommended);
+```
+
+## 错误处理
+
+```rust
+match result {
+    Ok(process_result) => {
+        println!("处理成功！");
+        println!("输出文件: {}", process_result.output_path.display());
+        println!("处理时间: {:?}", process_result.processing_time);
+    }
+    Err(TvaiError::TopazNotFound(path)) => {
+        eprintln!("未找到 Topaz Video AI: {}", path);
+    }
+    Err(TvaiError::FileNotFound(path)) => {
+        eprintln!("文件不存在: {}", path);
+    }
+    Err(TvaiError::FfmpegError(msg)) => {
+        eprintln!("FFmpeg 错误: {}", msg);
+    }
+    Err(e) => {
+        eprintln!("其他错误: {}", e);
+    }
+}
+```
+
+## 最佳实践
+
+1. **选择合适的模型**: 根据内容类型选择最适合的 AI 模型
+2. **合理设置质量等级**: 平衡处理时间和输出质量
+3. **监控 VRAM 使用**: 避免显存不足导致的处理失败
+4. **使用进度回调**: 为长时间处理提供用户反馈
+5. **批量处理**: 对多个文件使用相同配置时，重用处理器实例
+6. **错误处理**: 妥善处理各种可能的错误情况
+
+## 性能优化
+
+- 使用 GPU 加速可显著提升处理速度
+- 调整 `vram_limit` 以优化内存使用
+- 对于快速预览，使用 `QualityLevel::Fast`
+- 批量处理时重用 `FilterProcessor` 实例