Skip to content

README.md

Latest commit

 

History

History
307 lines (236 loc) · 17.9 KB

README.md

File metadata and controls

307 lines (236 loc) · 17.9 KB
Raw

OpenVX

rustVX

OpenVX Conformance License: MIT Rust

An OpenVX 1.3.1 implementation written in Rust. rustVX provides the complete OpenVX Vision Feature Set through a standard C API (libopenvx_ffi), enabling existing OpenVX applications to use a memory-safe, portable backend with no source changes.

Conformance Status

rustVX passes the full Khronos OpenVX 1.3.1 Conformance Test Suite for all required profiles:

Profile Required tests Passing Status
OpenVX baseline 5551 5551 / 5551 ✅
Vision conformance profile 5923 5923 / 5923 ✅
Enhanced Vision conformance profile 1235 1235 / 1235 ✅
User Data Object extension 14 14 / 14 ✅
Pipelining extension 81 81 / 81 ✅
Total 6867 6867 / 6867 ✅ 100%

All implemented kernels are exercised in CI with -DOPENVX_CONFORMANCE_VISION=ON -DOPENVX_USE_ENHANCED_VISION=ON -DOPENVX_USE_USER_DATA_OBJECT=ON -DOPENVX_USE_PIPELINING=ON.

Latest CTS run results are published on each push and pull request via the Actions tab.

Project Structure

rustVX/
├── openvx-core/       # Core framework: context, graph, node, types, C API
├── openvx-image/      # Image data object and channel operations
├── openvx-buffer/     # Generic buffer for intermediate data
├── openvx-vision/     # All vision kernels (filters, geometric, features, etc.)
├── openvx-ffi/        # C shared library (cdylib) exporting the full OpenVX API
├── include/VX/        # Standard OpenVX C headers
└── OpenVX-cts/        # Khronos Conformance Test Suite (git submodule)

The workspace compiles into a single shared library (libopenvx_ffi.so / .dylib / .dll) that any OpenVX application can link against.

Prerequisites

Tool Version
Rust stable
C compiler gcc, clang, or MSVC
CMake 3.10+
Make or Ninja for building the CTS

Build

# Clone with submodules
git clone --recurse-submodules https://github.com/kiritigowda/rustVX.git
cd rustVX

# Build the library
cargo build --release

The shared library is produced at:

Platform Path
Linux target/release/libopenvx_ffi.so
macOS target/release/libopenvx_ffi.dylib
Windows target/release/openvx_ffi.dll

The standard OpenVX 1.3 C headers are bundled in include/VX/ and can be passed to your C/C++ build directly.

Cargo features

Both openvx-core (host of the C-API kernel callbacks the OpenVX graph executor invokes) and openvx-vision (host of the public Rust API kernels) expose a matching opt-in feature set:

Feature Effect
simd Enables architecture-neutral SIMD code paths
sse2 / avx2 x86_64 SIMD back-ends (imply simd)
neon AArch64 SIMD back-end (implies simd)
parallel (openvx-vision only) Enables Rayon-based multi-threaded kernels

Build with the matching pair on each crate so the FFI graph path and the direct Rust API path both pick up the SIMD kernels:

cargo build --release -p openvx-ffi \
  --features "openvx-core/sse2 openvx-core/avx2 openvx-vision/sse2 openvx-vision/avx2"

Hardware acceleration

Performance work targets AMD Zen (Ryzen / EPYC, Zen 2+) — that's what CI measures and what the Benchmark & compare numbers come from. Intel and ARM aren't penalised; the runtime dispatcher reads CPU flags, not vendor strings, so any host whose flags match the same gate runs the same path:

  • AMD Zen 2+ (Ryzen 3000+, Threadripper 3000+, EPYC Rome / Milan / Genoa) → AVX2 kernels + -C target-cpu=x86-64-v3 auto-vec.
  • Intel Haswell and later → same AVX2 path, parity with Zen.
  • Older x86_64 (pre-AVX2) → SSE2 kernels + -C target-cpu=x86-64-v2.
  • AArch64 (Apple Silicon, AWS Graviton, etc.) → NEON path.
  • Anything else / no features → scalar slice loop (still ~50× faster than the original per-pixel kernels).

Dispatch lives in openvx-core::simd_kernels (FFI graph path) and openvx-vision::x86_64_simd (Rust API). CI auto-detects host flags; for a manual Zen-targeted build:

RUSTFLAGS="-C target-cpu=x86-64-v3" \
  cargo build --release -p openvx-ffi \
    --features "openvx-core/sse2 openvx-core/avx2 \
                openvx-vision/sse2 openvx-vision/avx2"

Using rustVX from a C application

libopenvx_ffi exports the full vx* / vxu* symbol set defined by the standard OpenVX headers, so existing OpenVX code links against it with no source changes. A minimal example:

#include <VX/vx.h>

int main(void) {
    vx_context ctx = vxCreateContext();
    vx_graph   g   = vxCreateGraph(ctx);
    /* ... build graph, call vxVerifyGraph / vxProcessGraph ... */
    vxReleaseGraph(&g);
    vxReleaseContext(&ctx);
    return 0;
}
# Linux
gcc app.c -I rustVX/include -L rustVX/target/release -lopenvx_ffi -o app
LD_LIBRARY_PATH=rustVX/target/release ./app

For drop-in compatibility with build systems that look for libopenvx / libvxu (e.g. find_library(NAMES openvx vxu)), symlink the rustVX library to those names:

ln -s libopenvx_ffi.so target/release/libopenvx.so
ln -s libopenvx_ffi.so target/release/libvxu.so

Running Conformance Tests

The Khronos OpenVX Conformance Test Suite is included as a git submodule. Build and run it against the rustVX library:

Note

The -DCMAKE_POLICY_VERSION_MINIMUM=3.5 flag below is needed when configuring with CMake 4.0+, which dropped compatibility with the older cmake_minimum_required versions used by the upstream CTS. It is harmless on older CMake.

Linux

# Build the CTS
cd OpenVX-cts
mkdir -p build && cd build
cmake .. \
  -DCMAKE_C_FLAGS="-fno-strict-aliasing" \
  -DCMAKE_CXX_FLAGS="-fno-strict-aliasing" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
  -DCMAKE_C_STANDARD_LIBRARIES="-lm" \
  -DCMAKE_CXX_STANDARD_LIBRARIES="-lm" \
  -DOPENVX_INCLUDES="$(pwd)/../../include;$(pwd)/../include" \
  -DOPENVX_LIBRARIES="$(pwd)/../../target/release/libopenvx_ffi.so;m" \
  -DOPENVX_CONFORMANCE_VISION=ON \
  -DOPENVX_USE_ENHANCED_VISION=ON \
  -DOPENVX_USE_USER_DATA_OBJECT=ON \
  -DOPENVX_USE_PIPELINING=ON
make -j$(nproc)

# Run all tests
export LD_LIBRARY_PATH=$(pwd)/../../target/release
export VX_TEST_DATA_PATH=$(pwd)/../test_data/
./bin/vx_test_conformance

macOS

# Build the CTS
cd OpenVX-cts
mkdir -p build && cd build
cmake .. \
  -DCMAKE_C_FLAGS="-fno-strict-aliasing" \
  -DCMAKE_CXX_FLAGS="-fno-strict-aliasing" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
  -DOPENVX_INCLUDES="$(pwd)/../../include;$(pwd)/../include" \
  -DOPENVX_LIBRARIES="$(pwd)/../../target/release/libopenvx_ffi.dylib" \
  -DOPENVX_CONFORMANCE_VISION=ON \
  -DOPENVX_USE_ENHANCED_VISION=ON \
  -DOPENVX_USE_USER_DATA_OBJECT=ON \
  -DOPENVX_USE_PIPELINING=ON
make -j$(sysctl -n hw.ncpu)

# Run all tests
export DYLD_LIBRARY_PATH=$(pwd)/../../target/release
export VX_TEST_DATA_PATH=$(pwd)/../test_data/
./bin/vx_test_conformance

Windows (MSVC)

# Build the CTS
cd OpenVX-cts
mkdir build; cd build
cmake .. `
  -DCMAKE_C_FLAGS="-fno-strict-aliasing" `
  -DCMAKE_CXX_FLAGS="-fno-strict-aliasing" `
  -DCMAKE_BUILD_TYPE=Release `
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 `
  -DOPENVX_INCLUDES="$PWD\..\..\include;$PWD\..\include" `
  -DOPENVX_LIBRARIES="$PWD\..\..\target\release\openvx_ffi.dll.lib" `
  -DOPENVX_CONFORMANCE_VISION=ON `
  -DOPENVX_USE_ENHANCED_VISION=ON `
  -DOPENVX_USE_USER_DATA_OBJECT=ON `
  -DOPENVX_USE_PIPELINING=ON
cmake --build . --config Release

# Run all tests
$env:PATH = "$PWD\..\..\target\release;$env:PATH"
$env:VX_TEST_DATA_PATH = "$PWD\..\test_data\"
.\bin\Release\vx_test_conformance.exe

Running Specific Test Categories

Use the --filter flag to run a subset of tests:

# Run only filter tests
./bin/vx_test_conformance --filter="Gaussian3x3.*:Median3x3.*:Box3x3.*"

# Run only feature detection tests
./bin/vx_test_conformance --filter="HarrisCorners.*:FastCorners.*:vxCanny.*"

# Run only control flow tests
./bin/vx_test_conformance --filter="ControlFlow.SelectNode*:ControlFlow.ScalarOperationNode*"

# Run only tensor tests
./bin/vx_test_conformance --filter="Tensor.*:TensorOp.*"

Note

The -fno-strict-aliasing flag above is needed because the CTS test suite contains intentional (but technically undefined-behavior) type punning between vx_uint8* and vx_char* inside own_verify_data_items(). GCC -O3 optimizes those comparisons incorrectly without the flag, causing 5 pre-existing Array.vxCreateArray failures. The flag is harmless on all compilers and does not affect rustVX runtime performance.

Unit Tests and Benchmarks

Beyond the Khronos CTS, rustVX has its own Rust-side test and benchmark suites:

# Run all unit and integration tests
cargo test --workspace --release

# Run the Criterion micro-benchmarks for vision kernels
cargo bench -p openvx-vision

End-to-end performance is also tracked against the Khronos OpenVX sample implementation on every CI run via openvx-mark; see the Benchmark & compare job in the Actions tab for the latest comparison report.

Tip

The Benchmark & compare job renders the rustVX-vs-Khronos comparison table directly into the GitHub Actions job summary for each run — no need to dig into logs. The summary opens with a headline panel showing the geomean speedup of rustVX over the Khronos sample (per-kernel best/worst speedups and a win/loss count) followed by the full per-benchmark detail table. The raw JSON reports are also published as downloadable workflow artifacts (benchmark-results-rustvx, benchmark-results-khronos-sample, and benchmark-comparison) on every push and pull request.

Continuous Integration

GitHub Actions builds and runs the full CTS on every push and pull request. The workflow splits the suite into parallel jobs for faster feedback:

Job Test categories Pipeline status
baseline GraphBase, Logging, SmokeTest, Target baseline
graph Graph framework (cycles, virtual data, multi-run, replicate node), GraphCallback, GraphDelay, GraphROI, UserNode graph
data-objects Scalar, Array, ObjectArray, Matrix, Convolution, Distribution, LUT, Histogram data-objects
image-ops Image, CopyImagePatch, MapImagePatch, CreateImageFromChannel, Remap image-ops
vision-color ColorConvert, ChannelExtract, ChannelCombine, ConvertDepth vision-color
vision-filters Box, Gaussian, Median, Dilate, Erode, Sobel, Magnitude, Phase, NonLinearFilter, Convolve, EqualizeHistogram vision-filters
vision-arithmetic Add, Subtract, Multiply, Bitwise (And/Or/Xor/Not), WeightedAverage, Threshold vision-arithmetic
vision-geometric Scale, WarpAffine, WarpPerspective, Remap, HalfScaleGaussian vision-geometric
vision-features HarrisCorners, FastCorners, Canny vision-features
vision-statistics MeanStdDev, MinMaxLoc, Integral vision-statistics
vision-pyramid GaussianPyramid, LaplacianPyramid, LaplacianReconstruct, OptFlowPyrLK vision-pyramid
user-data-object UserDataObject (14 tests) user-data-object
KHR: pipelining fast GraphPipeline (fast) KHR extension: pipelining fast
KHR: pipelining stress GraphPipeline (stress) KHR extension: pipelining stress
Enhanced-Vision: Feature Extraction HOGCells, HOGFeatures, MatchTemplate, LBP (44 tests) Enhanced-Vision: Feature Extraction
Enhanced-Vision: Post-Processing Copy, NonMaxSuppression, HoughLinesP (84 tests) Enhanced-Vision: Post-Processing
Enhanced-Vision: Tensor Arithmetic TensorOp, Min, Max (222 tests) Enhanced-Vision: Tensor Arithmetic
Enhanced-Vision: Tensor Transforms Tensor, TensorEnhanced (18 tests) Enhanced-Vision: Tensor Transforms
Enhanced-Vision: Advanced Filtering BilateralFilter (361 tests) Enhanced-Vision: Advanced Filtering
Enhanced-Vision: Control Flow SelectNode, ScalarOperationNode (186 tests) Enhanced-Vision: Control Flow

See the Actions tab for full run history.

Contributing

Contributions, bug reports, and feature requests are welcome.

  • Found a bug or have a question? Open an issue.
  • Want to contribute a fix or new kernel? Fork the repo, create a topic branch, and open a pull request against main. CI must pass — both the Khronos CTS jobs and the rustVX-vs-Khronos benchmark comparison run on every PR.
  • Please make sure cargo fmt, cargo clippy --workspace --all-targets, and cargo test --workspace pass locally before submitting.

License

This project is licensed under the MIT License.

The OpenVX logo is a trademark of The Khronos Group Inc. The vector logo file in docs/openvx-logo.svg is sourced from Wikimedia Commons and is included for identification purposes only.