jcmaloney/screenprinttool

ScreenPrint Separator AI

Open-source-first screen-print prepress engine and web demo. The MVP runs locally, uses deterministic image-processing algorithms, and does not call paid services or proprietary separation systems.

Goal

Convert uploaded artwork into screen-print-oriented separations for T-shirts:

• —Spot-color SVG screens for flat, limited-color artwork.
• —Simulated-process raster plates for complex art, gradients, photos, and tonal AI art.
• —Optional underbase, highlight white, choke, trap, dot-gain curves, halftone plates, proof previews, and ZIP export.

Important limitations

This tool is a prepress aid, not a guaranteed replacement for a professional separator or press test.

Flat, limited-color artwork should work best. Complex images may need simulated-process separations, halftones, calibration, and human review.

No official Pantone matching is claimed. Included ink names are generic house colors or mixed RGB labels.

Default jobs assume a white garment and no underbase. Select a black/grey/custom garment and auto or always underbase when preparing dark-shirt output.

Current outputs

Each job returns a ZIP containing:

• —manifest.json
• —README_JOB_NOTES.txt
• —production_qa.json
• —composite_preview.png
• —proof_on_garment.png
• —spot_svg/vector_proof_on_garment.png for spot jobs
• —benchmark_report.json
• —spot SVG screens for flat artwork
• —spot raster fidelity plates used for closer proof previews
• —simulated-process grayscale and optional halftone PNG plates for tonal artwork
• —optional debug masks and palette swatches

Clean Logo SVG quality controls

For raster logos and AI-generated shirt graphics, use Auto or Clean Logo SVG with the cleanup controls:

• —Conservative: app default; preserves more edge/detail, may leave noisier paths.
• —Standard: balanced cleanup for simpler limited-color logo art.
• —Aggressive: simplifies harder for cleaner screens and fewer path points.

SVG trace scale runs mask tracing internally at 1x, 2x, or 3x. Higher values can smooth contours but may take longer. The SVG viewBox stays at the original artwork size.

For closer visual proofs, spot-mode jobs render proof_on_garment.png from the raw extracted palette masks before choke/trap/SVG cleanup. The ZIP also includes matching spot_raster/fidelity_plates/*.png files so users can inspect the higher-fidelity raster version alongside the production SVG screens. Spot jobs also include spot_svg/vector_proof_on_garment.png, which renders the actual traced SVG masks back to pixels so operators can catch vector simplification damage before sending screens to film. Conservative mode favors fidelity over compact SVGs, so detailed artwork can produce larger path counts and should be reviewed with the SVG proof plus the raster fidelity plates. When higher Max ink colors values are selected, the spot palette uses spare slots for residual colors that still have high Delta-E error. This helps preserve low-coverage but important tones such as browns, grays, shadows, and highlights instead of collapsing them into the closest large brand color.

Production QA gates

Every job receives a conservative production-readiness grade:

• —production_candidate: proof metrics and required exports pass; still review normally before film output.
• —needs_review: output may be usable, but detail, screen count, or warnings require operator judgment or a rerun.
• —not_production_safe: do not send directly to film; rerun, manually separate, or rebuild the artwork.

The grade appears in manifest.json, production_qa.json, README_JOB_NOTES.txt, and the app diagnostics panel.

For spot jobs, the QA gate checks both the close raster garment proof and the actual SVG/vector proof. This is intentionally conservative: a job can be marked needs_review or not_production_safe even when the raster proof looks good if the generated SVG screens lost important text, outline, or distress detail.

Run the local benchmark suite with:

python scripts/evaluate_quality_suite.py --out-dir examples/generated/quality_eval

Run the broader deterministic stress suite with:

python scripts/evaluate_stress_suite.py --out-dir examples/generated/stress_eval --cases 36

The stress suite generates synthetic logos, mascots, badges, text marks, muted earth-tone traps, and gradient/photo-like images, then verifies that printable spot cases meet quality thresholds and tonal/process cases are honestly flagged as not production-safe.

Local setup

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -U pip
pip install -e .[dev]

Run tests

python -m pytest -q

Generate sample art

python scripts/make_sample_art.py

CLI target command

python -m printsep.cli process examples/generated/simple_badge.png \
  --garment "#000000" \
  --print-width-in 12 \
  --max-inks 5 \
  --mode auto \
  --underbase auto \
  --out examples/generated/job.zip \
  --include-debug-masks

App target command

python app.py

The Docker/Hugging Face Spaces app listens on port 7860 and does not require API keys, accounts, a database, or persistent storage.

Codex setup

Codex should read AGENTS.md and PLAN.md first.

Suggested goal:

/goal Rework and implement the project with the separation engine as the highest priority. Build a clean-room, open-source-first screen-print prepress engine inspired only by public screen-printing practices and public product feature descriptions. Do not copy, scrape, reverse engineer, decompile, train on, or depend on Separo or any other proprietary service. Implement PLAN.md completely, update PROGRESS.md after each checkpoint, keep tests green, and stop only if cost/license/security/hosting approval is required.