Shapearator

Created by Charis Tsevis.

Current version: 0.3.2

Shapearator exists to solve a common asset-preparation problem: taking a single file that contains many shapes or icons, identifying each individual shape, separating it cleanly, and cataloging the results into well-organized, individually named files. Instead of manually cropping, renaming, and sorting every asset by hand, Shapearator automates that workflow and produces structured exports with metadata.

Shapearator is a local-first Python app for extracting individual icons from hand-drawn icon sheets. It supports both a desktop GUI and a feature-rich CLI, works with PNG and SVG input sheets, and exports cleaned icons as PNG, JPG, TIFF, and SVG with per-icon metadata.

What It Does

• Detects isolated icons from raster or vector sheets
• Normalizes exports to a shared output canvas
• Supports multiple canvas scaling behaviors
• Exports bitmap and vector formats in one run
• Writes per-icon metadata JSON files
• Optionally uses local Ollama vision models for semantic file naming
• Keeps the workflow local-only and offline-friendly by design

Interfaces

Shapearator currently has two supported interfaces:

• GUI desktop app: best for visual workflows, previews, and settings management
• CLI: best for automation, scripting, and repeatable batch runs
• macOS packaged app: available upon request

GUI-only features:

• live preview
• extracted item browser
• file/folder picker dialogs
• light/dark appearance toggle

CLI parity covers extraction, export, metadata, settings, provider selection, semantic naming, and progress reporting.

Shapearator for macOS includes a native desktop workspace for local extraction and export workflows.

The macOS build also includes a native settings experience for local providers, Ollama configuration, and model management.

Distribution note:

• a packaged macOS .dmg exists separately from this repository
• the current installer is approximately 1.8 GB, so it may be impractical to distribute directly through GitHub in-repo
• the macOS build is available upon request

Supported Input and Output

Input formats:

• PNG
• SVG

Export formats:

• PNG
• JPG
• TIFF
• SVG

Requirements

Python dependencies used by the app include:

• Pillow
• opencv-python
• numpy
• requests

System tools required by parts of the pipeline:

• inkscape
• potrace

Notes:

• SVG input is the highest-fidelity route when available.
• Raster-to-SVG output is generated differently depending on the icon content:
  • monochrome shapes can be traced to vector paths
  • colored or non-monochrome content may be embedded as raster inside SVG

Running the App

GUI

Start the desktop app from the repository root:

./run.sh

You can also launch it directly with Python:

python main.py

CLI

Basic usage:

python shapearator.py sheet.png --output-dir exports

Show all CLI options:

python shapearator.py --help

CLI Highlights

The CLI supports:

• provider selection: geometry, ollama, directory
• output formats and canvas sizing
• canvas behavior selection
• bitmap export mode selection
• detection presets
• direct detection parameter overrides
• optional config loading from config/settings.json
• optional config persistence back to config/settings.json
• local Ollama semantic naming

Example: geometry-only extraction

python shapearator.py sheet.png \
  --output-dir exports \
  --formats png svg \
  --output-width 512 \
  --output-height 512 \
  --canvas-mode uniform_to_largest

Example: use a detection preset and override one value

python shapearator.py sheet.png \
  --output-dir exports \
  --detection-preset "Tiny Details" \
  --merge-gap 11 \
  --formats png jpg svg

Example: semantic naming with local Ollama

python shapearator.py sheet.png \
  --output-dir exports \
  --provider ollama \
  --ollama-url http://127.0.0.1:11434 \
  --ollama-model qwen2.5vl:3b \
  --semantic-naming \
  --formats png svg

Example: load defaults from config and save the resolved run settings

python shapearator.py sheet.svg \
  --use-config \
  --save-config \
  --output-dir exports

Extraction Controls

Canvas modes:

• original: keep each isolated icon at its original extracted size on the common canvas
• uniform_to_largest: scale the largest icon to fit, then apply the same scale to all icons
• individual_fit: scale each icon independently to fit the canvas

Bitmap export modes:

• keep_background: preserve the detected original background color in bitmap outputs
• transparent_preserve_interior: export transparent bitmaps while preserving internal light details when possible

Detection presets:

• Balanced
• Tiny Details
• Loose Sketches
• Bold Shapes

Explicit --padding, --min-area, and --merge-gap values override the preset if both are provided.

Local Model Providers

Provider modes:

• geometry: classical local extraction only
• ollama: local Ollama endpoint for semantic naming
• directory: local model catalog selection stored in settings for future adapters

Important constraints:

• Ollama must point to a local endpoint such as http://127.0.0.1:11434
• cloud endpoints are intentionally out of scope
• semantic naming is currently active only with provider=ollama
• the directory provider is exposed for local model organization and selection, but it is not yet a direct inference backend

Recommended local Ollama models currently referenced by the app:

• qwen2.5vl:3b
• minicpm-v:latest
• moondream:latest
• llava:7b

Output Layout

Each extraction run writes an output directory containing only the selected export folders plus metadata:

exports/
  png/
  jpg/
  tiff/
  svg/
  metadata/

Each metadata file contains information such as:

• exported file paths by format
• source bounds and source size
• output canvas size
• provider and model details
• vector export mode
• dominant color and palette
• semantic label, tags, and confidence when available

Configuration

User settings are stored in:

config/settings.json

This file can hold defaults for:

• provider selection
• Ollama URL/model
• local model directory selection
• semantic naming
• default formats
• output dimensions
• canvas mode
• bitmap export mode
• detection parameters
• last used input and output locations

The GUI reads and writes this automatically. The CLI uses it only when --use-config is supplied, and saves it only when --save-config is supplied.

Repository Notes

• main.py is the GUI entrypoint
• shapearator.py is the CLI entrypoint
• run.sh launches the GUI from the repository root
• services/ contains the shared extraction engine and settings logic
• gui/ contains the desktop interface
• much of docs/ contains sample inputs, outputs, and working assets rather than source code

For a full user guide, see MANUAL.md. For a repository map, see FILE_STRUCTURE.md.

Limitations

• The app expects icon sheets where symbols are reasonably separated.
• GUI preview is available only in the desktop app.
• The directory provider does not yet perform direct inference.
• Some raster-to-vector exports may remain embedded-raster SVG when tracing would lose fidelity.

Troubleshooting

• Required binary 'inkscape' was not found on PATH.: install inkscape and ensure it is available on your shell PATH.
• Required binary 'potrace' was not found on PATH.: install potrace and ensure it is available on your shell PATH.
• Ollama provider requires a local endpoint...: point --ollama-url to localhost, 127.0.0.1, or ::1.
• Very small marks are disappearing: lower min-area or try the Tiny Details preset.
• Multiple strokes are being split apart: raise merge-gap or try the Loose Sketches preset.
• Exports feel inconsistent in scale: use uniform_to_largest for a shared visual scale across the set.

License

This project is released under the MIT License. See LICENSE.