🐻 BRB - Bear Right Back

BearRB (“Bear Right Back”) is an image-to-image system that rearranges the pixels of one bear photograph until they align with another bear image. Colors never change; only coordinates do.

---

Table of Contents

1. Philosophy
2. How It Works
3. Quick Start
4. Command-Line Tour
5. Motion & Panels
6. Development Notes
7. License

---

Philosophy

BearRB is built on a simple idea:

The source and target share the same pixels in different arrangements.

Formally, the output is a permutation of the input pixels. Informally, it’s the same bear reassembled into another bear, unchanged in material, transformed in appearance.

Source	Morph (BearRB)	Target

---

How It Works

Pipeline overview

1. Bear validation Inputs are first checked using a CLIP-based classifier. If they are not recognized as bear images, BearRB aborts with a warning instead of producing nonsense.

2. Resize & multiscale pyramid Each image may be downscaled (configurable --max-side) and expanded into a multi-resolution pyramid. Optimization proceeds coarse-to-fine for stability and speed.

3. Sliced Optimal Transport (SOT) BearRB models each pixel as a point in a joint color position space and uses Sliced Optimal Transport with low discrepancy directions (Halton / Sobol / random) to iteratively refine a permutation that makes the permuted source resemble the target as closely as possible—without changing any colors.

4. Optional animation & layout Given the final permutation, BearRB generates smooth pixel motion animations (with bilinear splatting and optional trails) and can compose side by side or triptych panels for presentation.

All core logic lives in src/brb/.

---

Quick Start

# 1) Install with extras (recommended)
pip install -e .[extras]

# 2) Choose two bear images
export SRC=img/bear.jpg
export TGT=img/silly_bear.jpg

# 3) Run BearRB
bearrb "$SRC" "$TGT" -o out.png --motion motion.mp4 --panel triptych

The command above:

• produces a permutation-only out.png,
• renders an MP4 animation (if OpenCV is available),
• assembles a triptych panel for visual comparison.

Dependencies

Base:

• numpy
• pillow

Extras (via .[extras]):

• opencv-python: MP4 writing
• imageio: GIF writing
• scikit-image: improved Lab conversion (optional)
• scipy: Sobol direction sampling (optional)
• numba: animation acceleration (optional)
• torch, transformers: CLIP based bear validation

---

Command-Line Tour

Run:

bearrb --help

Key options:

Flag	Description
--dir-method {random,halton,sobol}	Direction sequence for Sliced OT projections.
--iters	SOT iterations (per level or total, depending on setup).
--lam, --lam-end	Start/end color weights.
--mu, --mu-end	Start/end spatial weights.
--pyr-levels, --pyr-min-side	Multiscale pyramid depth and coarsest size.
--max-side	Per-image max side length before processing (0 = disabled).
--motion, --motion-gif	Output MP4 / GIF animation.
--fps, --seconds, --hold	Control animation timing and final-frame hold.
--trail	Add motion trails (0–1).
--panel {current,side,triptych}	Compose animation with source / target panels.
--loopback	Create a looped animation returning to the source image.

For full reference, see src/brb/cli.py.

---

Motion & Panels

BearRB’s animation system uses the final permutation to move each pixel along a smooth trajectory from its original location to its assigned target location.

You can:

• Tune timing with --seconds and --fps.

• Keep the final frame displayed via --hold.

• Enable subtle trails with --trail for a more cinematic motion effect.

• Use --panel side or --panel triptych to render:

  • animation only,
  • animation + target,
  • or source + target + animation in one frame.

If tqdm is installed, BearRB displays per-level progress bars for SOT iterations.

---

Development Notes

• Code is organized under src/brb/.

• Optional dependencies (Numba, SciPy, scikit-image, CLIP stack) are detected dynamically; the core pipeline runs without them.

• You can run directly via:

  python -m brb.cli <args>

• Type hints are included to make navigation and tooling easier.

Contributions, experiments, and bear-related abuses of Optimal Transport are welcome.

---

License

Released under the MIT License. See LICENSE for details.