Skip to content

CLAUDE.md

Latest commit

 

History

History
85 lines (62 loc) · 3.43 KB

CLAUDE.md

File metadata and controls

85 lines (62 loc) · 3.43 KB

PureCV — Claude Code Instructions

Project Mission

Pure Rust port of OpenCV's core and imgproc modules. Memory-safe, zero-FFI, high-performance. See .agents/instructions.md for the full architectural mandate.

Architectural Rules

  • Zero-FFI: No bindgen, cc, or C++ linking. Every algorithm must be rewritten in idiomatic Rust.
  • Memory Safety: Use Rust's ownership model. Prefer Vec<T> or Box<[T]> for buffers. Avoid unsafe — if you must use it, justify why pulp or std::arch is required and why safe iterators failed.
  • Data Layout: Row-major contiguous memory (Matrix<T>) matching cv::Mat.
  • Concurrency: Use Rayon (parallel feature) for pixel-parallel tasks; always provide a sequential fallback.
  • SIMD: Use pulp (simd feature) for manual SIMD. Prefer .chunks_exact(n) over .chunks(n) for LLVM auto-vectorization.
  • OpenCV Parity: Match OpenCV default border types and naming (e.g. cvt_color not convert_color).
  • Error handling: Use Result<T, PureCvError> — never panic! in library code.

Code Quality — run in this order before every commit

cargo fmt
cargo clippy        # fix ALL warnings
cargo test          # all unit + doc tests must pass

CI rejects any PR that fails cargo fmt --check or cargo clippy.

New Files

Every new Rust source file must start with the LGPL-3.0 license header. Template: .agents/skills/license-header-adder/resources/HEADER.txt Replace {{FILENAME}} with the actual filename.

Commits — Conventional Commits (mandatory)

Format: <type>(<scope>): <description>

Type When
feat new feature or algorithm
fix bug fix
perf performance improvement
doc documentation only
refactor neither fix nor feature
test adding or fixing tests
chore build, deps, tooling

Preferred scopes: (core) (imgproc) (simd) (wasm) (parallel)

Git / PR Workflow

  • PRs start from and target the dev branch (not main).
  • Keep PRs focused; one feature or fix per PR.

Module Structure Convention

Each top-level module (core/, imgproc/, features2d/, etc.) must contain its own:

  • tests.rs — unit tests for that module (#[cfg(test)] mod tests;)
  • simd.rs — SIMD-accelerated helpers specific to that module (pub(crate) mod simd;)

Keep SIMD kernels co-located with the module that uses them. The core SimdElement trait and element-wise operations stay in src/core/simd.rs; domain-specific kernels (e.g. color conversion, derivatives) belong in their respective module's simd.rs.

Project Structure

src/core/       — Matrix<T>, Scalar, arithmetic, stats, linear algebra
src/imgproc/    — color conversion, filtering, edge detection, threshold
crates/wasm/    — wasm-bindgen wrappers and wasm-pack build
benches/        — Criterion benchmarks
.agents/        — reference docs, roadmap, skills (shared with other agents)

Key Types

  • Matrix<T> — main n-channel image/matrix type
  • Scalar<T> — 4-channel per-pixel constant (channels beyond 4 default to T::default())
  • MatType / Depth — OpenCV-style type constants (CV_8UC3, CV_32FC1, …)
  • PureCvError — library error type; use Result<T, PureCvError> everywhere

Performance Notes

  • SIMD + Parallel benchmarks target 1024×1024 matrices.
  • Full benchmark results: benches/benchmark_results.md.
  • Best speedup achieved: 22× (sobel_3x3_f32 with Parallel + SIMD).