feat: 完成 tvai 库测试和文档 (阶段六) - 项目完成
集成测试套件 - 创建完整的集成测试 (integration_tests.rs) - 测试库初始化和配置管理 - 测试 GPU 检测和优化功能 - 测试性能监控和基准测试 - 测试错误处理和用户友好消息 - 测试配置文件持久化 - 测试模型和参数验证 - 测试临时文件管理 - 所有测试通过 性能基准测试 - 创建完整的基准测试套件 (performance_benchmarks.rs) - GPU 检测性能: ~193ms - 设置保存/加载: ~1.56ms - 预设查找: ~29ns (超快) - 临时文件管理: ~96μs - 参数验证: ~3.6ns (极快) - 错误消息生成: ~266ns - 模型操作: ~1.9ns (极快) - 系统检测: 24μs - 30ms 完整 API 文档 - 创建详细的 API 文档 (docs/API.md) - 核心组件使用指南 - 所有方法和参数说明 - 代码示例和最佳实践 - 错误处理指南 - 性能优化建议 用户指南 - 创建完整的用户指南 (docs/USER_GUIDE.md) - 快速入门教程 - 常见用例和场景 - 配置管理指南 - 模型选择指南 - 性能优化技巧 - 故障排除指南 更新项目文档 - 更新主 README.md - 标记项目为 100% 完成 - 添加文档链接和使用指南 - 添加性能和测试信息 - 添加开发设置说明 - 添加变更日志 测试结果总结 - 单元测试: 6/6 通过 - 集成测试: 10/10 通过 - 文档测试: 1/1 通过 - 基准测试: 13/13 完成 - 所有示例运行成功 最终项目统计 - **总代码行数**: 4,127行 - **模块文件**: 25个 - **示例文件**: 6个 - **测试文件**: 2个 (单元 + 集成) - **基准测试**: 1个 (13项基准) - **文档文件**: 3个 (API + 用户指南 + README) 功能完整性 (100%) - 视频处理 (超分辨率 + 插值) - 图片处理 (超分辨率 + 批量) - 格式转换 (视频 图片序列) - 便捷接口 (一键处理函数) - 配置管理 (全局设置 + 预设) - 性能优化 (GPU检测 + 监控) - 错误处理 (用户友好消息) - 文档和测试 (完整覆盖) 项目状态: 完成 (COMPLETE) 所有六个开发阶段已完成，tvai 库已准备好用于生产环境！
This commit is contained in:
imeepos
422
cargos/tvai/docs/USER_GUIDE.md
Normal file
422
cargos/tvai/docs/USER_GUIDE.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# TVAI Library User Guide
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Installation
|
||||
|
||||
Add TVAI to your `Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
tvai = "0.1.0"
|
||||
```
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Topaz Video AI** - Download and install from [Topaz Labs](https://www.topazlabs.com/topaz-video-ai)
|
||||
2. **GPU Drivers** - Latest NVIDIA or AMD drivers for GPU acceleration
|
||||
3. **Rust 1.70+** - For building the library
|
||||
|
||||
### Quick Start
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
// Quick 2x video upscaling
|
||||
quick_upscale_video(
|
||||
std::path::Path::new("input.mp4"),
|
||||
std::path::Path::new("output.mp4"),
|
||||
2.0,
|
||||
).await?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Video Enhancement
|
||||
|
||||
#### Upscaling Old Videos
|
||||
|
||||
```rust
|
||||
use tvai::*;
|
||||
|
||||
let params = VideoUpscaleParams::for_old_video();
|
||||
let mut processor = create_processor().await?;
|
||||
|
||||
let result = processor.upscale_video(
|
||||
Path::new("old_video.mp4"),
|
||||
Path::new("restored_video.mp4"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("Enhanced in {:?}", result.processing_time);
|
||||
```
|
||||
|
||||
#### Creating Slow Motion
|
||||
|
||||
```rust
|
||||
let params = InterpolationParams::for_slow_motion(30, 4.0); // 30fps -> 120fps
|
||||
let result = processor.interpolate_video(
|
||||
Path::new("normal_speed.mp4"),
|
||||
Path::new("slow_motion.mp4"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
#### Complete Enhancement
|
||||
|
||||
```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("input.mp4"),
|
||||
Path::new("enhanced.mp4"),
|
||||
enhance_params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
### 2. Image Enhancement
|
||||
|
||||
#### Batch Photo Enhancement
|
||||
|
||||
```rust
|
||||
let image_paths = vec![
|
||||
PathBuf::from("photo1.jpg"),
|
||||
PathBuf::from("photo2.jpg"),
|
||||
PathBuf::from("photo3.jpg"),
|
||||
];
|
||||
|
||||
let params = ImageUpscaleParams::for_photo();
|
||||
let results = processor.batch_upscale_images(
|
||||
&image_paths,
|
||||
Path::new("output_dir"),
|
||||
params,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("Processed {} images", results.len());
|
||||
```
|
||||
|
||||
#### Directory Processing
|
||||
|
||||
```rust
|
||||
let results = processor.upscale_directory(
|
||||
Path::new("input_photos"),
|
||||
Path::new("output_photos"),
|
||||
ImageUpscaleParams::for_photo(),
|
||||
true, // recursive
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
### 3. Format Conversion
|
||||
|
||||
#### Image Sequence to Video
|
||||
|
||||
```rust
|
||||
let image_paths = collect_image_sequence("frames/")?;
|
||||
processor.images_to_video(
|
||||
&image_paths,
|
||||
Path::new("output.mp4"),
|
||||
30.0, // fps
|
||||
QualityPreset::HighQuality,
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
```
|
||||
|
||||
#### Video to Image Sequence
|
||||
|
||||
```rust
|
||||
let image_paths = processor.video_to_images(
|
||||
Path::new("input.mp4"),
|
||||
Path::new("frames/"),
|
||||
"png",
|
||||
95, // quality
|
||||
Some(&progress_callback),
|
||||
).await?;
|
||||
|
||||
println!("Extracted {} frames", image_paths.len());
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Global Settings
|
||||
|
||||
Set up global configuration for consistent behavior:
|
||||
|
||||
```rust
|
||||
use tvai::config::global_settings;
|
||||
|
||||
let settings = global_settings();
|
||||
|
||||
// Configure defaults
|
||||
settings.set_default_use_gpu(true)?;
|
||||
settings.set_max_concurrent_jobs(2)?;
|
||||
|
||||
// Save settings
|
||||
settings.save_to_file()?;
|
||||
|
||||
// Create processor from global settings
|
||||
let config = settings.create_config()?;
|
||||
let processor = TvaiProcessor::new(config)?;
|
||||
```
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
```rust
|
||||
let config = TvaiConfig::builder()
|
||||
.topaz_path("/custom/path/to/topaz")
|
||||
.use_gpu(true)
|
||||
.temp_dir("/fast/ssd/temp")
|
||||
.force_topaz_ffmpeg(true)
|
||||
.build()?;
|
||||
|
||||
let processor = TvaiProcessor::new(config)?;
|
||||
```
|
||||
|
||||
## Model Selection Guide
|
||||
|
||||
### Upscaling Models
|
||||
|
||||
| Model | Best For | Scale | Description |
|
||||
|-------|----------|-------|-------------|
|
||||
| Iris v3 | General purpose | 1-4x | Best overall quality |
|
||||
| Nyx v3 | Portraits | 1-4x | Face-optimized |
|
||||
| Theia Fidelity v4 | Old content | 2x | Restoration focused |
|
||||
| Gaia HQ v5 | Games/CG | 1-4x | Sharp details |
|
||||
| Proteus v4 | Problem footage | 1-4x | Artifact repair |
|
||||
|
||||
### Interpolation Models
|
||||
|
||||
| Model | Best For | Description |
|
||||
|-------|----------|-------------|
|
||||
| Apollo v8 | High quality | Best overall interpolation |
|
||||
| Chronos v2 | Animation | Cartoon/anime content |
|
||||
| Apollo Fast v1 | Speed | Faster processing |
|
||||
| Chronos Fast v3 | Fast animation | Quick animation processing |
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### GPU Optimization
|
||||
|
||||
```rust
|
||||
use tvai::utils::GpuManager;
|
||||
|
||||
// Check GPU suitability
|
||||
if GpuManager::is_gpu_suitable_for_ai() {
|
||||
println!("GPU is suitable for AI processing");
|
||||
|
||||
// Get detailed info
|
||||
let gpu_info = GpuManager::detect_detailed_gpu_info();
|
||||
println!("Recommended memory limit: {:?} MB",
|
||||
gpu_info.recommended_settings.memory_limit_mb);
|
||||
}
|
||||
```
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
```rust
|
||||
use tvai::utils::{PerformanceMonitor, optimize_for_system};
|
||||
|
||||
// Create optimized settings
|
||||
let settings = optimize_for_system();
|
||||
let mut monitor = PerformanceMonitor::new(settings);
|
||||
|
||||
// Process with monitoring
|
||||
let _permit = monitor.acquire_slot().await?;
|
||||
// ... perform processing ...
|
||||
|
||||
// Get recommendations
|
||||
let summary = monitor.get_summary();
|
||||
for recommendation in summary.recommendations {
|
||||
println!("💡 {}", recommendation);
|
||||
}
|
||||
```
|
||||
|
||||
### Memory Management
|
||||
|
||||
```rust
|
||||
// Use smaller chunk sizes for limited memory
|
||||
let settings = PerformanceSettings {
|
||||
chunk_size_mb: 50, // Smaller chunks
|
||||
max_concurrent_ops: 1, // Single operation
|
||||
processing_mode: ProcessingMode::MemoryEfficient,
|
||||
..Default::default()
|
||||
};
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Comprehensive Error Handling
|
||||
|
||||
```rust
|
||||
match processor.upscale_video(input, output, params, None).await {
|
||||
Ok(result) => {
|
||||
println!("✅ Success: {:?}", result.processing_time);
|
||||
}
|
||||
Err(error) => {
|
||||
eprintln!("❌ Error: {}", error.category());
|
||||
eprintln!("{}", error.user_friendly_message());
|
||||
|
||||
if error.is_recoverable() {
|
||||
eprintln!("💡 This error might be recoverable with different settings");
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Solutions
|
||||
|
||||
#### Topaz Not Found
|
||||
```
|
||||
Error: Topaz Video AI not found
|
||||
Solution: Install Topaz Video AI or set correct path
|
||||
```
|
||||
|
||||
#### GPU Errors
|
||||
```
|
||||
Error: CUDA out of memory
|
||||
Solution: Reduce quality settings or disable GPU
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```
|
||||
Error: Cannot write to output directory
|
||||
Solution: Run as administrator or check permissions
|
||||
```
|
||||
|
||||
## Progress Tracking
|
||||
|
||||
### Simple Progress Bar
|
||||
|
||||
```rust
|
||||
use std::io::{self, Write};
|
||||
|
||||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||||
let percentage = (progress * 100.0) as u32;
|
||||
print!("\rProgress: [");
|
||||
for i in 0..50 {
|
||||
if i < percentage / 2 {
|
||||
print!("=");
|
||||
} else {
|
||||
print!(" ");
|
||||
}
|
||||
}
|
||||
print!("] {}%", percentage);
|
||||
io::stdout().flush().unwrap();
|
||||
});
|
||||
```
|
||||
|
||||
### Detailed Progress Tracking
|
||||
|
||||
```rust
|
||||
let progress_callback: ProgressCallback = Box::new(|progress| {
|
||||
let percentage = (progress * 100.0) as u32;
|
||||
let eta = estimate_time_remaining(progress);
|
||||
println!("Progress: {}% - ETA: {:?}", percentage, eta);
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. File Management
|
||||
|
||||
```rust
|
||||
// Always validate input files
|
||||
processor.validate_input_file(input_path)?;
|
||||
processor.validate_output_path(output_path)?;
|
||||
|
||||
// Use temporary files for intermediate processing
|
||||
let temp_path = processor.create_unique_temp_path("intermediate.mp4");
|
||||
// ... process to temp file ...
|
||||
std::fs::rename(temp_path, final_output)?;
|
||||
```
|
||||
|
||||
### 2. Resource Management
|
||||
|
||||
```rust
|
||||
// Use RAII for automatic cleanup
|
||||
{
|
||||
let mut processor = TvaiProcessor::new(config)?;
|
||||
// Processing happens here
|
||||
// Processor automatically cleans up when dropped
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Batch Processing
|
||||
|
||||
```rust
|
||||
// Process in batches to avoid memory issues
|
||||
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?;
|
||||
|
||||
// Process results or save state
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Error Recovery
|
||||
|
||||
```rust
|
||||
// Implement retry logic for recoverable errors
|
||||
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!("Attempt {} failed, retrying...", attempts);
|
||||
tokio::time::sleep(Duration::from_secs(1)).await;
|
||||
}
|
||||
Err(error) => break Err(error),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Slow Processing**
|
||||
- Enable GPU acceleration
|
||||
- Use faster models (Apollo Fast, Chronos Fast)
|
||||
- Reduce quality settings
|
||||
|
||||
2. **Out of Memory**
|
||||
- Reduce chunk size
|
||||
- Lower quality preset
|
||||
- Process smaller files
|
||||
|
||||
3. **Poor Quality Results**
|
||||
- Use appropriate model for content type
|
||||
- Adjust compression and blend parameters
|
||||
- Use higher quality presets
|
||||
|
||||
4. **File Format Issues**
|
||||
- Convert to supported formats first
|
||||
- Check file corruption
|
||||
- Verify file permissions
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Check error messages and suggestions
|
||||
2. Review the API documentation
|
||||
3. Run the examples to verify setup
|
||||
4. Check system requirements and GPU drivers
|
||||
Reference in New Issue
Block a user