Pixviper

July 14, 2026 · View on GitHub

Pixviper is a parallel template matching and de-redaction investigation tool written in V. It is designed to recover obfuscated (pixelated or blurred) text through parallel dictionary-matching and sequential greedy character-by-character search.

Quick Demonstration

Here is a visual demonstration of Pixviper's trial-and-error search process:

Sequential Search (Letter-by-Letter)Dictionary Candidate Search
Sequential Search ProcessDictionary Search Process

Key Architectural Features

  • Parallel Candidate Evaluation: Concurrently spawns OS-level threads to evaluate dictionary candidates using a sliding-window Mean Absolute Error (MAE) metric.
  • Greedy Character-by-Character Search: Builds unknown strings sequentially without a dictionary.
  • Grid-Aligned Full-Canvas Simulation: Eliminates boundary block contamination. Sequential candidates are rendered on target-sized canvases to preserve global pixelation block coordinates.
  • Right-to-Left (RTL) Script Support: Supports Arabic and any RTL language text recovery by leveraging ImageMagick's bidirectional formatting, correct text direction flags, and anchor alignments.
  • Scribble Mask Support: Accepts alpha masks to exclude specific coordinates (e.g., pen scribbles or black bars) from the error calculations.
  • Integrated GIF Pipeline: Automates the compilation of search frames into a lightweight animated GIF utilizing ImageMagick.

Quick Install

To update your system, install dependencies (git, clang, make, imagemagick), pull the V language compiler (if not present), clone Pixviper, compile with release optimizations, and link to your local binary path, run the following command:

apt update -y && apt install -y git clang make imagemagick && if ! command -v v >/dev/null 2>&1; then git clone --depth=1 https://github.com/vlang/v && cd v && make && ./v symlink && cd ..; fi && git clone --depth=1 https://github.com/tailsmails/pixviper && cd pixviper && v -prod pixviper.v -o pixviper && ln -sf $(pwd)/pixviper $PREFIX/bin/pixviper

System Requirements

  • V Compiler (Latest stable release)
  • C Compiler (Clang, GCC, or MSVC)
  • ImageMagick (Optional; required only for compiling visual GIF animations)

Technical Background

The Block Contamination Problem

In traditional de-redaction, when the pixelation block size (e.g., 8px) is larger than the character boundaries (e.g., 5px + 2px spacing), neighboring characters merge into shared blocks. Evaluating a single character in a small template causes mathematical mismatches near the boundaries.

Target Grid [ABC] (Globally Pixelated):
[Block 1: A + part of B] [Block 2: B + part of C]

Localized Candidate Template [A] (No Alignment):
[Block 1: A Only] [Block 2: Blank (Edge Effects)] -> Highly inaccurate MSE comparison

The Pixviper Solution

Pixviper resolves this by rendering each candidate on a full-size target canvas at its exact anchor point. Global pixelation is then simulated across the entire frame. This aligns the averaging grid perfectly with the target image and cancels out mathematical edge distortions:

Full-Size Candidate [A _ _] (Globally Pixelated):
[Block 1: A + Blank] [Block 2: Blank + Blank] -> Zero grid shift or border averaging mismatch

CLI Flags and Parameters

FlagShorthandDefaultDescription
--image-itarget.pngPath to the redacted target image
--mode-mpixelateObfuscation filter: pixelate or blur
--intensity-s8Degradation parameter (block size / blur radius)
--bg-color-bFFFFFFCanvas background color in hex (RRGGBB)
--text-color-t000000Text color in hex (RRGGBB)
--font-f(empty)Optional path to custom .ttf or .otf font file
--alphabet-aa-z0-9Search space for letter-by-letter decoding
--length-l8Length of the text to recover
--mask-k(empty)Path to alpha mask to ignore occlusions
--seq-qtrueSequential search (Set to false for Dictionary Mode)
--gif(none)falseGenerates a visualization GIF of the trials
--rtl-rfalseEnable Right-to-Left (RTL) mode for Persian / Arabic / Urdu / Pashto / Kurdish (Sorani) / Balochi / Luri / Sindhi / Uyghur / Kashmiri / Punjabi (Shahmukhi) / Azerbaijani / Turkmen / Gilaki / Mazanderani / Hebrew / Yiddish / Ladino / Dhivehi / Aramaic / Syriac / Mandaic / Samaritan / Rohingya / Fulani / Bambara / Mende / Phoenician / Avestan / Pahlavi / Sogdian / Old Turkic text rendering

Usage Examples

Example 1: Standard English Recovery (Sequential Mode)

To recover an English pixelated string of length 4:

pixviper --image target.png --mode pixelate --intensity 4 --font ./fonts/Roboto-Regular.ttf --alphabet "abcdefghijklmnopqrstuvwxyz" --length 4 --gif

Example 2: Arabic/Persian RTL Recovery (Sequential Mode)

To recover a right-to-left script like Arabic, it is important to provide an Arabic-compatible .ttf font (e.g., Amiri, Scheherazade, or Tahoma) and enable the --rtl flag.

Suppose you have a pixelated target image of the Arabic word "مرحبا" (length 5) with pixelation block size 4:

pixviper --image arabic_redacted.png --mode pixelate --intensity 4 --font ./fonts/Amiri-Regular.ttf --rtl --alphabet "امربح" --length 5 --gif

Why this works:

  • --font ./fonts/Amiri-Regular.ttf supplies the glyph shapes required for cursive Arabic script.
  • --rtl (or -r) forces the renderer to align text to the right boundary using -gravity East and sets the -direction right-to-left layout direction in ImageMagick.
  • --alphabet "امربح" restricts the search space to candidate letters present in the word to optimize search execution.

Running Self-Tests

To verify the parallel matching engine, masked search, and sequential de-pixelation algorithms on your machine, execute the test suite:

pixviper test

By default, the 8th test case (using custom fonts) runs an English LTR test. If you want to verify the Arabic RTL implementation with your custom font, run the test command with the -rtl flag and the path to your Arabic font file:

pixviper test ./fonts/Amiri-Regular.ttf -rtl

This runs 8 rigorous tests covering:

  1. Brute-Force Pixelation Matching
  2. Blurred Text Reconstruction
  3. Alphabet Combinations Generation
  4. Scribble-Mask Occlusion Ignoring
  5. Sequential Pixelation Decoding (Letter-by-Letter)
  6. Sequential Blur Decoding (Letter-by-Letter)
  7. Custom Numeric Sequential Recovery
  8. Custom Font Sequential Recovery (Tests Arabic RTL if -rtl and a font are provided, otherwise falls back to English LTR)

These tests generate visual PNG and animated GIF assets (test_case_*.gif) in your current working directory.

License

License