solidsf-inc / solidcv

# solidcv
**Pure-Rust OpenCV Replacement & Visual/Mechanistic Accelerator for LLMs, VLMs, and 3D Spatial Computing (`solidSF`)**
`solidcv` (re-exported as `solidcv::opencv` for drop-in `opencv-rust` ergonomics) is a 100% pure-Rust, zero-FFI computer vision, stereo reconstruction, and mechanistic interpretability engine developed by **solidSF** (**Andy Norris**).
It eliminates C++ `libopencv` build chains while unifying classical 2D/3D computer vision with **Pixelean bit-sliced algebra**, **Voxelean 3D octree topology**, **$(3+1)\text{D}$ Hyper-Voxelean Worldtubes**, **RealityComber** static-vs-moving scene separation, and native hardware kernels for **Apple Silicon (`aarch64` NEON + Metal 3.1 + WebGPU)** and **NVIDIA Grace-Blackwell GB300 / GB10 (`PTX 8.5+` Tensor Core `b1.xor.popc` + NVLink-C2C coherent slabs)**.
---
## Why `solidcv` Exists for the LLM / VLM & Mechanistic Interpretability Community
Modern Vision-Language Models (VLMs) and Mechanistic Interpretability pipelines face three severe bottlenecks that `solidcv` solves directly in memory:
### 1. Eliminating VLM Patch-Token & KV-Cache Bloat (`mechinterp::prune_vlm_patch_tokens`)
Current VLMs (ViT-14, SigLIP, LLaVA, Qwen-VL) tokenize every video or GUI frame into dense $14\times 14$ or $16\times 16$ patch grids and run full transformer prefill on every frame—even when $95\%+$ of the scene is static.
- `solidcv` slices frames into bitplanes at **`39.18 GPix/s`** and computes temporal XOR minterm carriers (`Theorem 2: XorMintermCarrier`) at **`34.4 GPix/s`** raw byte SIMD (`2.90 us` bitplane XOR).
- `prune_vlm_patch_tokens` returns the exact `(grid_row, grid_col)` coordinates of active patches and a `kv_cache_reuse_mask` so VLMs only re-encode changed patches and reuse prior KV-cache states for static patches (`>95%` token reduction on real video and desktop streams).
### 2. 1-Bit Tensor-Core Sparse Autoencoder (SAE) & Circuit Matching (`mechinterp::SaeBinaryCircuitMatcher`)
Probing LLM/VLM residual streams with Sparse Autoencoders (SAEs) traditionally requires expensive FP16/BF16 matrix multiplications ($d_{\text{model}} \times d_{\text{SAE}}$) at every layer.
- `SaeBinaryAtom` quantizes activation vectors and monosemantic SAE dictionary atoms into 256-bit binary signatures (`[u64; 4]`).
- `SaeBinaryCircuitMatcher` dispatches batches of residual-stream states through a fused $4\times N$ register-blocked `b1.xor.popc` argmin microkernel (`mma.sync.aligned.m16n8k256.row.col.s32.b1.b1.s32.xor.popc` on NVIDIA Grace-Blackwell GB300/GB10, or hardware `cnt`/`popcnt` on Apple Silicon NEON over a contiguous Structure-of-Arrays bit slab at **`1.29 billion` 256-bit pairs/sec on CPU**).
### 3. True 3D/4D Geometric & Topological Grounding for VLMs (`voxelean`, `worldtube`, `realitycomb`)
2D patch tokenizers lack projective 3D geometry, topological invariants, and physical causality:
- **Exact 3D Topology (`VoxelComplex3D`)**: Computes Discrete Exterior Calculus boundary ranks and exact **Euler-Poincare