zoomvtools 2.0.0

Video motion vector analysis utilities in pure Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

# RESIZE KNOWLEDGE BASE

**Generated:** 2026-04-25

## OVERVIEW

Table-driven vector-field resizer (`SimpleResize`). Resizes motion vector fields between different resolutions. Separate u8/i16 paths for unsigned/signed components.

## STRUCTURE

```
src/resize/
├── rust.rs    # Scalar table-driven resize
├── avx2.rs    # AVX2 SIMD resize (40-90% faster for i16 path)
├── tests.rs   # Test generator macro
└── resize.rs  # Module root (not present - logic in src/resize.rs)
```

Module root: `src/resize.rs` (200 lines). Subdirectory contains `rust.rs`, `avx2.rs`, `tests.rs`.

## WHERE TO LOOK

| Area | File | Notes |
|------|------|-------|
| SimpleResize struct | `src/resize.rs:21` | Lookup-table resizer with precomputed offsets/weights |
| init_tables | `src/resize.rs:111` | Builds vertical/horizontal offset+weight tables |
| resize_u8 | `src/resize.rs:140` | Unsigned component resize (vectors) |
| resize_i16 | `src/resize.rs:164` | Signed component resize (motion vectors) |
| AVX2 weight scaling | `src/resize.rs:82-90` | Packs weights: `(w << 16) | (max - w)` |
| Weight constants | `src/resize.rs:17-19` | `WEIGHT_SHIFT=14`, `WEIGHT_MAX=16384` |

## CONVENTIONS (RESIZE-SPECIFIC)

- `SimpleResize::new()` precomputes lookup tables for vertical/horizontal interpolation at construction time.
- Table-driven approach: each output pixel maps to 2 input pixels with a fractional weight.
- `resize_u8()` for `Pixel` component types (`u8`/`u16`). `resize_i16()` for signed motion vectors (`i16`).
- `resize_i16()` preserves C-compatible vector clamping without relying on VapourSynth `Component` trait bounds.
- AVX2 weight packing: combines weight and complement into single i32: `(w << 16) | (WEIGHT_MAX - w)`. Enables single SIMD multiply-add.
- AVX2 path: 5-15% faster (u8), 40-90% faster (i16).
- `limit_width`/`limit_height` fields constrain vectors to actual frame size (unpadded dimensions).
- `horizontal_offsets_avx2` field is `#[cfg]`-gated — only present with AVX2 feature.

## ANTI-PATTERNS

- Using `resize_u8()` for signed motion vectors (loses sign information; use `resize_i16()`).
- Recreating `SimpleResize` per frame (tables are expensive; construct once, reuse).
- Assuming `horizontal_offsets_avx2` exists without `#[cfg]` guard.
- Incorrect stride calculation in `resize_i16()` (must multiply by `size_of::<i16>()` for byte strides).