# ZOOMVTOOLS SRC KNOWLEDGE BASE
## OVERVIEW
- Core source root for motion-analysis orchestration. Leaf kernels live under `sad/`, `satd/`, `reduce/`, `refine/`, `util/`, etc.
- Keep this crate host-neutral. No `vapoursynth` imports; wrappers pass slices, strides, padding, and metadata through public core APIs.
- `plane_of_blocks.rs` is the main hotspot: predictor setup, search policy, block cost evaluation, DCT/SATD selection, vector writeout.
- `group_of_planes.rs` coordinates coarse-to-fine search, inter-level prediction, global MV propagation, and packed vector blob layout.
- `analysis.rs` owns `MVAnalysisData` and property-byte ABI. Changes here affect wrapper property IO and `fake/` readback.
- `frame.rs` is the frame-buffer seam: `FramePlanes`/`FramePlanesMut` expose host-owned planes without host-specific types.
- `fake/` is compatibility/readback support: reconstruct packed vectors, test usability, support recalc-style consumers.
## STRUCTURE
- `analysis.rs`: serialized analysis metadata, threshold scaling, clip/vector compatibility checks.
- `params.rs`: public enums/flags for search, pel, DCT, divide, penalty, plane-set policy.
- `frame.rs`: borrowed plane views for immutable/mutable host buffers.
- `mv_plane.rs`: one padded/refined plane, subpel windows, reduce/pad/refine state.
- `mv_frame.rs`: one frame across enabled planes; updates offsets and delegates plane operations.
- `mv_gof.rs`: frame pyramid container; builds reduced levels, keeps geometry/padding aligned across levels.
- `group_of_planes.rs`: vector-field pyramid; owns `PlaneOfBlocks` stack and serialized output ordering.
- `plane_of_blocks.rs`: per-level block grid, predictors, search loops, penalties, motion-vector packing.
- `fake/`: mirrors vector-grid geometry from serialized metadata; never the source of truth for search behavior.
## WHERE TO LOOK
| Change vector metadata or property ABI | `analysis.rs`, `fake/group_of_planes.rs` | Keep byte size, field order, and validation compatible |
| Change block-grid geometry or overlap math | `group_of_planes.rs`, `plane_of_blocks.rs`, `fake/group_of_planes.rs`, `fake/plane_of_blocks.rs` | Real and fake hierarchies must derive identical block counts |
| Change pyramid construction or frame layout | `frame.rs`, `mv_plane.rs`, `mv_frame.rs`, `mv_gof.rs` | Preserve host-neutral buffer contracts and plane offsets |
| Change coarse-to-fine search behavior | `group_of_planes.rs`, `plane_of_blocks.rs`, `params.rs` | Search order, predictor interpolation, and penalty flow meet here |
| Debug vector blob consumers or recalc paths | `group_of_planes.rs`, `fake/`, `analysis.rs` | Packed plane order is header, validity, then planes from coarsest to finest |
## CONVENTIONS
- Dataflow: host slices in `frame.rs` -> plane/frame pyramid in `mv_{plane,frame,gof}.rs` -> block search in `group_of_planes.rs`/`plane_of_blocks.rs` -> packed vectors/metadata in `analysis.rs` and `MvsOutput`.
- Finest level keeps requested `pel`; coarser levels are forced to full-pel. Preserve that assumption across real and fake hierarchies.
- Geometry formulas are shared invariants. Width/height from block size plus overlap must stay consistent between `GroupOfPlanes::new` and `FakeGroupOfPlanes::new`.
- Serialized vectors are cross-module ABI, not an internal cache. Header fields, validity flag, per-plane chunk sizes, and plane ordering must remain in lockstep.
- Subsampling and padding propagate through multiple layers. If `x_ratio_uv`, `y_ratio_uv`, `hpad`, or `vpad` rules change, audit `analysis.rs`, `mv_*`, `group_of_planes.rs`, and `fake/` together.
- Runtime kernel dispatch belongs in leaf modules. Source-root code should select/configure once via cpudetect, then reuse; do not add CPU-feature checks inside search loops.
- Use `semisafe_get()` / `semisafe_get_mut()` in hot coordination code; keep `unsafe` local and justified.
## ANTI-PATTERNS
- Editing `analysis.rs` without auditing `fake/` and wrapper property readers/writers.
- Changing block or plane serialization order in `group_of_planes.rs` only.
- Re-deriving overlap/block-count math differently in fake vs real hierarchy code.
- Smuggling host-specific frame types or plugin assumptions into `frame.rs`, `mv_*`, `group_of_planes.rs`, or `plane_of_blocks.rs`.
- Duplicating leaf-kernel details here; defer SAD/SATD/refine/reduce specifics to their local AGENTS.
- Adding per-pixel/per-block CPU dispatch, direct indexing, or new unchecked access in the search hot path.