Merge pull request #1 from phial3/develop

add convert for AVFrame, Mat, Image

Author: phial3

.github/workflows/ci.yml

@@ -72,14 +72,14 @@ jobs:
 
       - name: Setup ffmpeg env
         run: |
-          # 设置 FFmpeg 环境变量
+          # set env
           export FFMPEG_BUILD_DIR=${PWD}/tmp/ffmpeg_build
           echo "FFMPEG_DIR=${FFMPEG_BUILD_DIR}" >> $GITHUB_ENV
           echo "FFMPEG_INCLUDE_DIR=${FFMPEG_BUILD_DIR}/include" >> $GITHUB_ENV
           echo "FFMPEG_LIB_DIR=${FFMPEG_BUILD_DIR}/lib" >> $GITHUB_ENV
           echo "PKG_CONFIG_PATH=${FFMPEG_BUILD_DIR}/lib/pkgconfig:$PKG_CONFIG_PATH" >> $GITHUB_ENV
           echo "LD_LIBRARY_PATH=${FFMPEG_BUILD_DIR}/lib:$LD_LIBRARY_PATH" >> $GITHUB_ENV
-          # 验证环境变量
+          # check env
           echo "FFmpeg build directory: $FFMPEG_BUILD_DIR"
           echo "FFmpeg include directory: $FFMPEG_INCLUDE_DIR"
           echo "FFmpeg library directory: $FFMPEG_LIB_DIR"

README.md

@@ -1,22 +1,85 @@
 # cv-convert
 Convert computer vision data types in Rust
 
-Type conversions among famous Rust computer vision libraries. It
-supports the following crates:
-
-reference:
-https://github.com/jerry73204/rust-cv-convert
-
-## sys related
-- [opencv](https://crates.io/crates/opencv)
-- [tch](https://crates.io/crates/tch)
-- [rsmpeg](https://crates.io/crates/rsmpeg)
+reference: [jerry73204](https://github.com/jerry73204/rust-cv-convert)
+
+## Concept
+
+```mermaid
+graph LR
+%% 核心节点定义
+AF[AVFrame<br><i>视频原始数据</i>]:::avframe
+MA[Mat<br><i>OpenCV矩阵</i>]:::mat
+IM[Image<br><i>通用图像</i>]:::image
+ND[ndarray<br><i>数值数组</i>]:::ndarray
+TE[Tensor<br><i>深度学习张量</i>]:::tensor
+
+%% 转换路径矩阵
+AF <-.->|FFmpeg sws_scale| MA
+AF <-.->|YUV2RGB转换| IM
+AF <-.->|planes_to_3darray| ND
+AF <-.->|CUDA内存映射| TE
+
+MA <-.->|Mat::from_slice| ND
+MA <-.->|imencode/imdecode| IM
+MA <-.->|Mat::to_gpu| TE
+
+IM <-.->|image::buffer| ND
+IM <-.->|image_to_tensor| TE
+IM <-.->|save_to_avframe| AF
+
+ND <-.->|ndarray_to_tensor| TE
+ND <-.->|reshape_to_mat| MA
+ND <-.->|as_image_buffer| IM
+
+TE <-.->|to_ndarray| ND
+TE <-.->|tensor_to_mat| MA
+TE <-.->|render_to_avframe| AF
+
+classDef avframe fill:#FFEBEE,stroke:#FF5252;
+classDef mat fill:#FFF3E0,stroke:#FFB300;
+classDef image fill:#E3F2FD,stroke:#2196F3;
+classDef ndarray fill:#E8F5E9,stroke:#4CAF50;
+classDef tensor fill:#F3E5F5,stroke:#9C27B0;
+```
 
-## lib
-- [image](https://crates.io/crates/image)
-- [imageproc](https://crates.io/crates/imageproc)
-- [nalgebra](https://crates.io/crates/nalgebra)
-- [ndarray](https://crates.io/crates/ndarray)
+> 异常处理矩阵：
+> 
+| 转换路径 |	可能异常	|解决方案 |
+|---------  | ------- | ------ |
+AVFrame→Mat	    | 色彩空间不匹配	|自动插入sws_scale转换上下文
+Image→ndarray   | 通道顺序差异(RGB vs BGR)	| 提供convert_channels特性方法
+Mat→Tensor	    | 内存对齐问题	| 使用aligned_alloc分配器
+
+
+```mermaid
+graph TD
+Start{选择起点} --> A[AVFrame]
+Start --> B[Mat]
+Start --> C[Image]
+Start --> D[ndarray]
+Start --> E[Tensor]
+
+A -->|实时流处理| F[保持AVFrame]
+A -->|视觉分析| G[转Mat]
+A -->|AI推理| H[转Tensor]
+
+B -->|算法优化| I[保持Mat]
+B -->|持久化存储| J[转Image]
+B -->|数值计算| K[转ndarray]
+
+C -->|编辑处理| L[保持Image]
+C -->|视频合成| M[转AVFrame]
+C -->|模型训练| N[转Tensor]
+
+D -->|科学计算| O[保持ndarray]
+D -->|可视化| P[转Mat]
+D -->|深度学习| Q[转Tensor]
+
+E -->|推理结果| R[保持Tensor]
+E -->|结果可视化| S[转Mat]
+E -->|视频编码| T[转AVFrame]
+```
 
 ## Usage
 
@@ -25,27 +88,22 @@ https://github.com/jerry73204/rust-cv-convert
 cv-convert = { git = "https://github.com/phial3/cv-convert", branch = "main" }
 ```
 
-The minimum supported `rustc` is 1.81. You may use older versions of
-the crate (>=0.6) in order to use `rustc` versions that do not support
-const-generics.
-
-## Cargo Features
+## Features
 - `default`: enable `image` + `imageproc` + `nalgebra` + `ndarray`
-- `tch`
-- `opencv`
-- `rsmpeg`
+- `tch`: optional,  (System Required installation: [tch](https://crates.io/crates/tch))
+- `opencv`: optional, (System Required installation: [opencv](https://crates.io/crates/opencv))
+- `rsmpeg`: optional, (System Required installation: [rsmpeg](https://crates.io/crates/rsmpeg))
 - `full` : enable `tch` + `opencv` + `rsmpeg`
-- `image`
-- `imageproc`
-- `nalgebra`
-- `ndarray`
-
+- `image`: optional, enable [image](https://crates.io/crates/image)
+- `imageproc`: optional, enable [imageproc](https://crates.io/crates/imageproc)
+- `nalgebra`: optional, enable [nalgebra](https://crates.io/crates/nalgebra)
+- `ndarray`: optional, enable [ndarray](https://crates.io/crates/ndarray)
 
-## Usage
+## Examples
 
 The crate provides `FromCv`, `TryFromCv`, `IntoCv`, `TryIntoCv` traits, which are similar to standard library's `From` and `Into`.
 
-```rust
+```rust,ignore,no_run
 use cv_convert::{FromCv, IntoCv, TryFromCv, TryIntoCv};
 use nalgebra as na;
 use opencv as cv;
@@ -69,25 +127,6 @@ let cv_mat: cv::core::Mat = na_mat.try_into_cv()?;
 
 ## Contribute to this Project
 
-### Add a new dependency version
-
-To add the new version of nalgebra 0.32 for cv-convert for example,
-open `cv-convert-generate/packages.toml` in the source repository. Add
-a new version to the list like this.
-
-```toml
-[package.nalgebra]
-versions = ["0.26", "0.27", "0.28", "0.29", "0.30", "0.31", "0.32"]
-use_default_features = true
-features = []
-```
-
-Run `make generate` at the top-level directory. It modifies Rust
-source files automatically. One extra step is to copy the snipplet in
-`cv-convert/generated/Cargo.toml.snipplet` and paste it to
-`cv-convert/Cargo.toml`.
-
-
 ### Add a new type conversion
 
 To add a new type conversion, take `image::DynamicImage` and

src/lib.rs

@@ -226,21 +226,21 @@ pub mod with_nalgebra;
 pub mod with_ndarray;
 
 /// 工具库组合模块
+#[cfg(all(feature = "image", feature = "nalgebra"))]
+pub mod with_image_nalgebra;
+
 #[cfg(all(feature = "imageproc", feature = "nalgebra"))]
 pub mod with_imageproc_nalgebra;
 
 #[cfg(all(feature = "imageproc", feature = "ndarray"))]
 pub mod with_imageproc_ndarray;
 
-#[cfg(all(feature = "nalgebra", feature = "image"))]
-pub mod with_nalgebra_image;
-
-#[cfg(all(feature = "nalgebra", feature = "ndarray"))]
-pub mod with_nalgebra_ndarray;
-
 #[cfg(all(feature = "ndarray", feature = "image"))]
 pub mod with_ndarray_image;
 
+#[cfg(all(feature = "ndarray", feature = "nalgebra"))]
+pub mod with_ndarray_nalgebra;
+
 /// OpenCV 相关模块
 #[cfg(feature = "opencv")]
 pub mod with_opencv;
@@ -297,25 +297,3 @@ pub mod with_tch_nalgebra;
 
 #[cfg(all(feature = "tch", feature = "ndarray"))]
 pub mod with_tch_ndarray;
-
-/// Re-exports for convenience
-#[cfg(feature = "image")]
-pub use image;
-
-#[cfg(feature = "imageproc")]
-pub use imageproc;
-
-#[cfg(feature = "nalgebra")]
-pub use nalgebra;
-
-#[cfg(feature = "ndarray")]
-pub use ndarray;
-
-#[cfg(feature = "opencv")]
-pub use opencv;
-
-#[cfg(feature = "rsmpeg")]
-pub use rsmpeg;
-
-#[cfg(feature = "tch")]
-pub use tch;

src/with_nalgebra_image.rs renamed to src/with_image_nalgebra.rs

@@ -1,7 +1,8 @@
 use crate::{FromCv, IntoCv, TryFromCv, TryIntoCv};
 use anyhow::{Error, Result};
 use half::f16;
-use opencv::{core as cv_core, prelude::*};
+use opencv::core as cv_core;
+use opencv::prelude::*;
 
 pub use element_type::*;
 mod element_type {

src/with_nalgebra_ndarray.rs renamed to src/with_ndarray_nalgebra.rs

@@ -1,7 +1,9 @@
 use crate::{FromCv, IntoCv, TryFromCv, TryIntoCv};
 use anyhow::{Error, Result};
 use nalgebra::geometry;
-use opencv::{calib3d, core as cv_core, prelude::*};
+use opencv::calib3d;
+use opencv::core as cv_core;
+use opencv::prelude::*;
 
 /// NOTE: for future maintainers: Since the matrixes need to accommodate any size Matrix, we are using nalgebra::OMatrix instead of SMatrix.
 ///