HumanCrop

High-performance, privacy-first desktop application for offline batch processing of official ID photos using AI biometric cropping and background removal.

Quick Start

git clone https://github.com/roymejia2217/HumanCrop.git
cd HumanCrop
npm install
npm run build

npm start

Features

Prerequisites

Note: Release packaging validates hydrated model assets before building installers. If model files are still Git LFS pointers, npm run validate:models and release builds fail intentionally.

Installation

npm install
npm run build
npm run validate:models

Usage

Desktop App

npm start

1. Choose a source folder or add individual image files.
2. Select an output folder.
3. Choose a biometric preset or enter custom dimensions.
4. Choose a background color.
5. Start the batch and review the per-file status table.
6. Open the result folder from the completion dialog.

Development Build

npm run dev

1. Compile the TypeScript source.
2. Launch Electron from the compiled dist entrypoint.

Release Build

npm run dist

1. Validate model assets.
2. Compile the TypeScript source.
3. Package the application with Electron Builder.

Output naming:

• Processed images are written as PNG files named {original_name}_{preset}.png.
• Temporary output files are staged in the selected destination folder and atomically renamed after the write succeeds.

Status meanings:

• Success means the crop fit the selected biometric framing.
• Warning means the output was generated but should be reviewed for tight margins.
• Error means the file could not be processed and the UI shows the mapped error state.

Project Structure

HumanCrop/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── release.yml
├── build/
│   ├── icon.icns
│   ├── icon.ico
│   └── icons/
├── docs/
│   ├── banner.webp
│   ├── examples/
│   └── screenshots/
├── scripts/
│   ├── apply-fuses.js              # Applies Electron security fuses after packaging.
│   ├── validate-model-assets.js    # Rejects builds with unhydrated Git LFS model pointers.
│   └── validate-release-config.js  # Validates release scripts, packaging settings, and runtime constraints.
├── src/
│   ├── assets/
│   │   ├── icon.png
│   │   └── models/
│   │       ├── human/
│   │       └── imgly/
│   ├── locales/
│   │   ├── en.json
│   │   └── es.json
│   ├── global.d.ts
│   ├── index.html
│   ├── main.ts
│   ├── preload.ts
│   ├── processor.ts
│   ├── renderer.ts
│   ├── styles.css
│   └── worker.ts
├── LICENSE
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json

Building Executables

npm run dist:win
npm run dist:linux
npm run dist:all

Release builds run model validation, compile TypeScript, and write packaged artifacts to release/. The Windows target is NSIS, and the Linux targets are AppImage and Debian packages.

Testing

npm test
npm run build

Test coverage includes:

• scripts/validate-release-config.js: validates package scripts, model validation policy, lockfile policy, renderer state ownership, and offline background removal runtime constraints.
• npm run build: validates TypeScript compilation for the Electron main process, preload bridge, renderer, processor, and worker.

Credits

Examples

Example	Description
	Original input image before processing.
	Processed biometric ID photo after background removal and cropping.

Screenshots

Screenshot	Description
	Main interface for configuring batch photo processing.
	Import controls for adding images or a source folder.
	Preset selection for ID, passport, CV, and custom dimensions.
	Background color controls.
	System status panel during setup.
	Batch progress and result statuses.
	Completion dialog with success, warning, and error counts.
	In-app guide for the HumanCrop workflow.

License

MIT License. See LICENSE for details.