DCV Color Primitives - dcp
DCV Color Primitives is a library to perform image color model conversion.
Design guidelines
- Aware of the underlying hardware and supplemental cpu extension sets (up to avx2)
- Support data coming from a single buffer or coming from multiple image planes
- Support non-tightly packed data
- Support images greater than 4GB (64 bit)
- Support ARM (aarch64)[*]
- Support WebAssembly[*]
[*]: Supplemental cpu extension sets not yet supported.
Image format conversion
The library is currenty able to convert the following pixel formats:
Source pixel format | Destination pixel formats |
---|---|
ARGB | I420, I444, NV12 |
BGR | I420, I444, NV12 |
BGRA | I420, I444, NV12, RGB |
I420 | BGRA |
I444 | BGRA |
NV12 | BGRA |
RGB | BGRA |
Color models
The supported color models are:
- YCbCr, ITU-R Recommendation BT.601 (standard video system)
- YCbCr, ITU-R Recommendation BT.709 (CSC systems)
Requirements
- Rust stable (at least 1.39)
- Python3 and Fractions module (needed only if you want to execute the benchmark)
Windows
- Install rustup: https://www.rust-lang.org/tools/install
- If you want to execute the benchmark:
- Install Python 3: https://www.python.org/downloads/
- Install fraction module:
pip install Fraction
Linux
- Install rustup (see https://forge.rust-lang.org/infra/other-installation-methods.html)
curl https://sh.rustup.rs -sSf | sh
- If you want to execute the benchmark:
- Install Python 3 (example for Ubuntu):
apt install python3
- Install fraction module:
pip install Fraction
- Install Python 3 (example for Ubuntu):
You may require administrative privileges.
Building
Open a terminal inside the library root directory.
To build for debug experience:
cargo build
To build an optimized library:
cargo build --release
Run unit tests:
cargo test
Run benchmark:
python benches/geninput.py
cargo bench
WebAssembly
Install the needed dependencies:
rustup target add wasm32-unknown-unknown
To build for debug experience:
cargo build --target wasm32-unknown-unknown
To test, ensure you have installed wasm-pack. Then:
wasm-pack test --node
Usage
Initialize the library
This function has to be called before any other library function call:
use dcv_color_primitives as dcp;
Image conversion
Convert an image from bgra to nv12 (single plane) format containing yuv in BT601:
use dcv_color_primitives as dcp;
use ;
Error Handling
The library functions return a Result
describing the operation outcome:
Result | Description |
---|---|
Ok(()) |
The operation succeeded |
Err(ErrorKind::NotInitialized) |
The library is not initialized |
Err(ErrorKind::InvalidValue) |
One or more parameters have invalid values for the called function |
Err(ErrorKind::InvalidOperation) |
The combination of parameters is unsupported for the called function |
Err(ErrorKind::NotEnoughData) |
One or more buffers are not correctly sized |
In the following example, result
will match Err(ErrorKind::InvalidValue)
, because ColorSpace::Bt709
color space is not compatible with PixelFormat::Bgra
:
use dcv_color_primitives as dcp;
use ;
Even better, you might want to propagate errors to the caller function or mix with some other error types:
use dcv_color_primitives as dcp;
use ;
use error;
Buffer size computation
So far, buffers were sized taking into account the image pixel format and dimensions; However, you can use a function to compute how many bytes are needed to store an image of a given format and size:
use dcv_color_primitives as dcp;
use ;
use error;
Image planes
If your data is scattered in multiple buffers that are not necessarily contiguous, you can provide image planes:
use dcv_color_primitives as dcp;
use ;
use error;
Stride support
To take into account data which is not tightly packed, you can provide image strides:
use dcv_color_primitives as dcp;
use ;
use error;
See documentation for further information.
C bindings
DCV Color Primitives provides C bindings. A static library will be automatically generated for the default build.
In order to include DCV Color Primitives inside your application library, you need to:
- Statically link to dcv_color_primitives
- Link to ws2_32.lib and userenv.lib, for Windows
- Link to dl, for Linux
The API is slightly different than the rust one. Check dcv_color_primitives.h for examples and further information.
A meson build system is provided in order to build the static library and install it together with include file and a pkgconfig file. There are also some unit tests written in C, to add some coverage also for the bindings. Minimal instructions are provided below, refer to meson's help for further instructions:
-
Windows Visual Studio is required. At least the following packages are required:
- MSBuild
- MSVC - C++ build tools
- Windows 10 SDK
Install meson, you can choose one of the following methods:
- Using meson msi installer
- Download from https://github.com/mesonbuild/meson/releases
- Install both Meson and Ninja
- Install meson through pip
- Download and install python3: https://www.python.org/downloads/
- Install meson and ninja:
pip install meson ninja
All build commands have to be issued from Native Tools Command Prompt for VS (x86 or x64 depending on what platform you want to build)
-
Linux The following example is for Ubuntu:
#install python3 apt install python3 #install meson. See https://mesonbuild.com/Getting-meson.html for details or if you want to install through pip. apt install meson #install ninja apt install ninja-build
You may require administrative privileges.
-
Build Move inside the library root directory:
cd `dcv_color_primitives_root_dir`
Then:
meson --buildtype release builddir ninja -C builddir
-
Run the tests
cd builddir meson test -t 10
A timeout scale factor of 10 is required because some tests take longer than default 30 seconds to complete.
-
Install
ninja -C builddir install
License
This library is licensed under the MIT-0 License. See the LICENSE file.