About • Features • Installation • Usage • Architecture • Development • Roadmap • License
Reclaim is a local, private photo-recovery desktop app. An Electron + React
shell wraps reclaim_core — a Rust engine (crates/reclaim_core) that does
the heavy lifting: signature-based disk scanning that carves images straight
from raw sectors, file integrity/entropy diagnostics, and real, OpenCV-backed
image correction.
Everything runs on your machine. No account, no cloud, no telemetry — nothing ever leaves your computer.
Reclaim has two workflows:
- Recovery — scan a drive or memory card byte by byte and carve back deleted JPG/PNG photos into a folder you choose.
- MCU Repair — a guided, JPEG-bitstream workspace that decodes a recovered photo's entropy-coded scan MCU by MCU, automatically flags the broken blocks, re-encodes a valid baseline JPEG, and lets you pick any break (click the red box), shift the MCUs to realign horizontal tearing, add your own break points, rotate the preview, and fix the color bands the corruption itself left behind.
Recover what was lost — locally, privately, on your terms.
| Feature | Description |
|---|---|
| Deep signature scan | Carves JPG/PNG straight from raw disk sectors, even after deletion |
| Guided MCU Repair | Single-image, step-by-step workspace: decode → detect breaks → re-align → compare → export |
| Bitstream MCU engine | A baseline-JPEG entropy codec (ported from JVRT) that decodes/re-encodes the scan at the coefficient level — no lossy pixel re-processing |
| Automatic break detection | Every MCU that fails to decode is boxed in red on the image; DC-jump "suspects" are flagged too |
| Click-to-pick & manual breaks | Click any red box to select a break, or add your own where the detector missed a tear |
| Manual MCU shift | Insert/drop MCUs at a break (← → keys) to realign horizontal tearing, JVRT-style |
| Coefficient-space color de-cast | Removes the color/brightness bands left by MCU desync directly in the DC coefficients — on by default, gated on actual corruption |
| Preview rotation | Rotate the compare view without touching pixels or MCU coordinates |
| Before / after comparison | Draggable divider plus an Original / MCU switch — you decide what to keep |
| In-screen Guide | A beginner-friendly walkthrough that explains MCU problems and how to read the results |
| Fully local & non-destructive | No cloud, no telemetry; the original file is never overwritten |
| Bilingual UI | Full Portuguese and English, light and dark themes |
- Node.js 20 LTS or newer
- A Rust toolchain (
cargo) to buildreclaim_core - OpenCV 4.x + contrib modules, via vcpkg — the single
heaviest one-time setup step. The Rust core reads its paths from
.cargo/config.toml:VCPKG_ROOT(e.g.C:/vcpkg) andLIBCLANG_PATH/CLANG_PATH(e.g.C:/tools/llvm19). vcpkg and LLVM/clang are only needed on the machine that compiles the core — not to run an already-built app. Seecrates/reclaim_core/README.mdfor the exact install command. - Windows: raw disk access for a real scan needs Administrator privileges.
git clone <your-fork-url> Reclaim
cd Reclaim
npm install
npm run build:core # compiles crates/reclaim_core and copies the library
# (+ OpenCV runtime DLLs) into vendor/reclaim_core/
npm run dev # Vite dev server + an Electron window, renderer hot-reloadRe-run npm run build:core whenever the Rust core changes. Rust changes are
not hot-reloaded.
- Click Recovery in the top navigation (or New recovery on the Home screen).
- Pick the drive or memory card, the formats (JPG / PNG) and a destination folder.
- Start the scan and watch live progress; recovered files land in your folder.
Real volume reads require Administrator on Windows.
npm run devdoes not self-elevate — run your terminal as Administrator to test real scans. Without elevation the app still runs; scan calls just report a clear "access denied" message.
- Open MCU Repair in the top navigation. A short Guide appears the first time — reopen it anytime from the header.
- Select an image (a recovered JPG/PNG).
- Scan analysis runs automatically — the JPEG scan is decoded MCU by MCU and the blocks that fail to decode are boxed in red on the image.
- Repair & re-align — Reclaim re-encodes a valid baseline JPEG. Click a red
box (or a numbered chip) to pick a break, then use the shift controls (← →
arrows, Shift = ×10) to slide the MCUs until the torn content lines up. Missed
a tear? Add break and click the spot. Rotate adjusts the view only.
Drag the before/after divider and keep or discard the result.
- This step also runs the coefficient-space color de-cast (on by default, toggleable), which removes the color/brightness bands left by the corruption, directly in the JPEG DC coefficients. It's the only color correction MCU Repair applies — no separate whole-image color pass.
- Open the folder with the exported
_mcufile. Your original is never touched.
The renderer never touches Node or the native library directly —
contextIsolation and sandbox stay on. Every native call passes plain JSON
strings; koffi's disposable wrapper frees the Rust-allocated string
automatically after decoding.
┌────────────────────────────┐ ┌──────────────────────────────┐
│ Renderer (React + Vite) │ │ Electron main process │
│ Header · Home · Recovery │ IPC │ ipc.js → native/ │
│ MCU Repair · Settings │◄──────►│ reclaimCore.js (koffi) │
│ window.reclaim (preload) │ │ │
└────────────────────────────┘ └───────────────┬────────────────┘
│ C ABI (extern "C"),
│ JSON in / JSON out
▼
┌──────────────────────────────┐
│ reclaim_core (Rust cdylib) │
│ recovery/ scanner · carver │
│ repair/ diagnostics │
│ correction/ OpenCV algorithms│
└──────────────────────────────┘
Reclaim/
├── electron/ # main process: main.js, ipc.js, preload.js, native/reclaimCore.js (koffi)
├── src/ # React renderer
│ ├── screens/ # Welcome, Onboarding, Workspace, RecoveryWizard, Scanning,
│ │ # Results, McuRepair (+ McuGuide), Settings
│ ├── hooks/ # useScanSimulation, useMcuRepair
│ ├── components/ui/ # Button, Card, IconTile, SegmentedControl, ImageCompare, …
│ ├── state/ # reducer, actions, screen constants, context
│ └── i18n/ # pt / en string tables (identical key sets)
├── crates/reclaim_core/ # Rust engine (see its own README)
├── vendor/reclaim_core/ # compiled core + OpenCV DLLs (build output, git-ignored)
├── docs/ # documentation assets (README screenshot, etc.)
└── scripts/ # build/copy/icon helpers
The MCU Repair screen composes existing per-image primitives on
window.reclaim.repair:
| Step | IPC channel | reclaim_core |
|---|---|---|
| Preview any file (base64) | repair:readPreview |
— (Node fs) |
| Decode scan + break map | repair:analyzeMcu |
analyze_mcu_c (baseline-JPEG entropy decode) |
| Re-encode + re-align + de-cast | repair:repairMcu {ops} |
repair_mcu_c (fix_colors runs the coefficient-space de-cast) |
| Open output folder | shell:openFolder |
— (Electron shell) |
See crates/reclaim_core/README.md for the
full analyzer API and correction catalog.
npm run dev # Vite dev server + Electron (renderer hot-reload)
npm run build # build the React app into dist/
npm run start # run Electron against the built dist/ (production mode)
npm run build:core # rebuild the Rust core + copy into vendor/
npm run dist # build + package an installer via electron-builder
npm run icons # regenerate app icons from reclaim_favicon/Tests. The Rust core has a unit suite:
cargo test --manifest-path crates/reclaim_core/Cargo.tomlTwo dev-only example probes exercise the pipeline on a real recovered photo without launching Electron:
cargo run --release --manifest-path crates/reclaim_core/Cargo.toml --example repair_probe -- <in.jpg> <out.jpg>
cargo run --release --manifest-path crates/reclaim_core/Cargo.toml --example channel_probe -- <in.jpg> <swapped.jpg>The Electron/React side has no automated tests — verify UI changes by running
npm run dev and exercising the affected screen.
- ✅ Signature-based disk recovery (JPG/PNG) with live progress
- ✅ Guided single-image MCU Repair workspace
- ✅ Baseline-JPEG bitstream engine: decode + automatic break detection + lossless re-encode
- ✅ Coefficient-space DC re-baseline that removes corruption color/brightness bands, on by default
- ✅ Click-to-pick breaks, user-added break points, and preview rotation
- ✅ Manual MCU shift realignment (← → keys) with before/after comparison
- ✅ Coefficient-space color de-cast (removes corruption bands, on by default, toggleable)
- ✅ In-screen Guide, PT/EN, light/dark
- 💭 Full click-select MCU editor (delete/insert/copy, per-channel DC painting)
- 💭 Progressive-JPEG support; more recoverable formats (HEIC, RAW)
- 💭 Batch MCU Repair for many files
- Baseline JPEG only. Progressive (
SOF2) and arithmetic-coded JPEGs are detected and reported, not repaired — the same limitation as JVRT. - Coefficient-space de-cast is gated on corruption. The automatic DC re-baseline only runs when the decode actually shows corruption (errors or an MCU-count mismatch); on a pristine JPEG a horizon is locally indistinguishable from a cast band, so it deliberately does nothing. It only fixes bands left by the corruption — MCU Repair has no separate tool for a global camera/scanner color cast.
- Where scan data is fully destroyed the content is genuinely lost; the engine still produces a valid file and lets you re-align around the break.
- Vendored OpenCV DLLs are unoptimized —
build:corecopies the full vcpkgbin/rather than only the linked subset.
git checkout -b feature/YourFeature
# ... your changes ...
git commit -m 'feat: add YourFeature'
git push origin feature/YourFeatureThe official repository language is English — keep code comments,
documentation and commit messages in English. UI strings must be added to both
src/i18n/en.js and src/i18n/pt.js with matching keys.
GPLv3 — see LICENSE.
- 🦀 Rust — the recovery/repair engine
- 👁️ OpenCV — image-correction algorithms
- ⚛️ Electron · React · Vite — the desktop shell and UI
- 🔗 koffi — the JS ↔ Rust FFI bridge