LayerForge

LayerForge turns a single anime or illustrated character image into an editable, Spine-oriented Photoshop mask-review PSD. It combines one character-specific semantic plan with local SAM 2 segmentation, mask refinement, topology repair, and quality checks.

Note

LayerForge is an early-stage tool. Expect to review and correct masks in Photoshop before using them in production.

What it does

• Splits visible source pixels into 20–35 rig-friendly body, hair, clothing, and accessory layers.
• Keeps the original RGB pixels intact and expresses every cut as a native Photoshop layer mask.
• Refines antialiased edges, preserves line art, repairs small topology defects, and highlights uncertain or unassigned regions.
• Supports corrected-mask import, local quality benchmarks, and optional local learning from aggregate correction statistics.
• Runs locally. LayerForge does not include telemetry or upload artwork, masks, or statistics.

LayerForge deliberately does not reconstruct hidden regions, inpaint missing artwork, create Spine bones or animations, or handle multi-character scenes. The approved PSD is a mask-review artifact, not a finished rig.

Requirements

• macOS or Linux
• Python 3.12
• Node.js and npm
• uv
• About 10 GB of free disk space
• Photoshop or another PSD editor that preserves native bitmap masks for the review step

Apple Silicon can use MPS acceleration. Other environments fall back to CPU; CUDA is not currently part of the supported bootstrap path.

Install

git clone https://github.com/jdbd25414-ops/LayerForge.git
cd LayerForge
python .agents/skills/layerforge/scripts/bootstrap.py
uv run layerforge doctor --load-model

The bootstrap script creates a local environment, installs Python and Node dependencies, checks out the pinned SAM 2 revision, and downloads the checkpoint declared in models/manifest.json. These downloads are several gigabytes in total. Model weights, third-party source, environments, artwork, and job outputs are ignored by Git.

To use a custom Python package index, set UV_DEFAULT_INDEX before running the script.

Quick start

1. Analyze a source image:

   uv run layerforge analyze character.png --job-id character

2. Review work/jobs/character/previews/analysis-grid.png, then turn parts-plan-template.json into a character-specific parts-plan.json. Each visible part needs a tight prompt box and reliable prompt points. The bundled Codex skill describes the planning rules.

3. Build the review package:

   uv run layerforge build-review \
     character work/jobs/character/parts-plan.json --quality balanced

4. Open the generated review PSD in Photoshop. Paint white or black on the formal layer masks to reveal or hide pixels; do not erase the image pixels. REFERENCE/original appears below the formal layers at 25% opacity, while QA layers are hidden by default.

5. Import and approve a corrected PSD:

   uv run layerforge import-masks \
     character work/jobs/character/previews/edited-review.psd
   uv run layerforge approve character masks

6. Optionally update a local correction profile:

   uv run layerforge learn character --profile local

Run uv run layerforge --help to see individual and diagnostic commands.

Reference profiles and privacy

You can summarize the mask topology and naming patterns of an existing Spine asset directory:

uv run layerforge build-reference-profile /path/to/assets --name my-project --max-images 2000

This command does not copy source artwork or store its absolute path. It does record aggregate counts plus common filename and attachment tokens. Generated profile JSON files are ignored by default; inspect and sanitize one before intentionally publishing it.

Job inputs and outputs live under work/, learned profiles under profiles/local/, and downloaded models under models/. All are local and ignored by Git. No command sends these files to a remote service.

Development

uv run pytest
uv run ruff check .
npm test

See CONTRIBUTING.md before opening a pull request. Regression cases use matching mask filenames under predicted/ and corrected/ directories and can be checked with:

uv run layerforge benchmark benchmarks/cases

Report suspected vulnerabilities through the process in SECURITY.md, not through a public issue.

Third-party software

LayerForge downloads and uses Meta's SAM 2 source and model checkpoint. SAM 2 has its own license and usage terms; review them before distribution or commercial use. Other dependencies retain their respective licenses.

LayerForge is an independent project and is not affiliated with Adobe, Esoteric Software, or Meta.

License

LayerForge is available under the MIT License.