dengyu123456/crochet-engine

Purpose and delivery surfaces

crochet_chart_engine deterministically converts photos or ASCII crochet designs into grid-chart PNGs plus exact per-color stitch metadata. It is distributed as a Python API, command-line tool, and stdio MCP server for agent clients. Primary surfaces are src/crochet_chart_engine/__init__.py, src/crochet_chart_engine/cli.py, and src/crochet_chart_engine/mcp_server.py.

Core chart-generation pipeline

The main orchestration lives in src/crochet_chart_engine/engine.py. It accepts a Pillow image and chart parameters, validates/selects a crochet technique, derives output grid dimensions, resizes the source, quantizes pixels to a bounded palette, cleans isolated/confetti colors, then produces chart PNG bytes and metadata. The output contract includes grid dimensions, technique, color hex values, exact counts, total stitches, and warnings.

Technique-aware geometry boundary

Technique presets are architecture-defining because they change grid interpretation and sizing. src/crochet_chart_engine/engine.py applies technique rules for graph, C2C, tapestry, mosaic, and filet. In particular, C2C uses block aspect correction so physical worked dimensions preserve the source image’s apparent proportions rather than treating cells as square.

Design-file ingestion and rendering

src/crochet_chart_engine/design.py parses the repository’s ASCII design format: palette declarations, optional title/technique metadata, separator, and character-grid rows. It pads irregular rows and maps symbols to palette colors before rendering through the chart machinery. Example source assets are designs/frog.txt and designs/dragon.txt; render_design is exposed through src/crochet_chart_engine/__init__.py.

Stitch accounting and yarn estimation

Color counts are derived from the finalized grid, making them an output invariant: per-color counts sum to total grid stitches. src/crochet_chart_engine/yarn.py consumes chart metadata rather than source images and estimates total and per-color yardage across supported yarn weights. This separates visual/grid generation from material planning.

User-facing adapters

The CLI in src/crochet_chart_engine/cli.py exposes distinct chart, design, and yarn workflows around the library API. The MCP adapter in src/crochet_chart_engine/mcp_server.py presents equivalent capabilities as agent tools over stdio: photo conversion, ASCII design rendering, and yarn estimation. It handles transport-facing concerns such as local paths, base64/saved PNG output, and JSON-safe metadata rather than changing engine behavior.

Runtime and dependencies

The runtime is Python with Pillow and NumPy as the core image-processing dependencies, declared in pyproject.toml. Background removal is optional via the rembg extra, so it is an enrichment boundary rather than a required pipeline stage. MCP support is optional and launched as python -m crochet_chart_engine.mcp_server; server.json likely provides server/package integration metadata.

Validation focus

tests/test_engine.py is the visible behavioral verification point for deterministic engine outcomes. Determinism is central: repeated inputs and parameters must yield the same grid, rendered chart, color palette, and stitch totals.