Generating Crochet Charts
YAML--- name: generating-crochet-charts description: Converts photos into deterministic crochet charts with exact stitch counts, color palettes, and yarn estimates using the crochetpatterngen-engine library. Use when a user wants to turn an image into a crochet pattern/chart, needs stitch counts for a specific technique (graph, c2c, tapestry, mosaic, filet), needs yarn yardage estimates, or wants to render an ASCII design into a chart. --- Quick Start ```bash pip install crochetpatterngen-engine
Pythonfrom PIL import Image from crochet_chart_engine import generate_chart, estimate_yarn png_bytes, meta = generate_chart( Image.open("photo.jpg"), technique="c2c", # graph | c2c | tapestry | mosaic | filet grid_w=60, # 20..120 n_colors=8, # 2..16 ) with open("out.png", "wb") as f: f.write(png_bytes) yarn = estimate_yarn(meta, weight="worsted") print(meta["total_stitches"], yarn["total_yards"])
Progress:
- Clarify technique, grid width, color count, and yarn weight preferences
- Install/confirm
crochetpatterngen-engine(add[mcp]or[rembg]extras if needed) - Generate chart via Python API, CLI, or MCP tool
- Inspect
metafor stitch counts, warnings, and color breakdown - Estimate yarn if requested
- Deliver PNG + stitch count summary to user
1. Gather requirements
- Technique:
graph(default, simple pixel grid),c2c(corner-to-corner, needs aspect correction — engine handles this automatically),tapestry,mosaic,filet. - Grid width: 20–120 stitches. Larger = more detail, more stitches to track. Default 50–60 for most photos.
- Color count: 2–16. Fewer colors = simpler pattern, easier color changes. Default 6–8.
- Yarn weight for estimation: fingering, sport, dk, worsted, bulky, super bulky.
2. Choose interface
- Python API: for programmatic/scripted use or embedding in another tool.
- CLI: for quick one-off conversions.
Bash
crochet-chart chart photo.jpg out.png --technique c2c --grid-w 60 --colors 8 crochet-chart design designs/frog.txt frog.png crochet-chart yarn photo.jpg --technique graph --weight worsted - MCP server: when operating inside Claude Desktop/Cursor with the MCP server configured. Use tools
photo_to_chart,render_ascii_design,estimate_yarn_tool.
3. Generate the chart
Call generate_chart(image, technique, grid_w, n_colors). This is deterministic — same inputs always produce the same chart (resize → median-cut color quantization → confetti cleanup). No AI image generation, no hallucinated rows.
4. Read the metadata
meta contains:
grid_w,grid_h— actual chart dimensions (note: forc2c,grid_his aspect-corrected at 0.7:1 h:w ratio so the finished piece isn't squashed)colors— list of{hex, count}, counts sum exactly togrid_w * grid_htotal_stitchestechniquewarning— surface this to the user if present (e.g., too many colors for grid size)
5. Estimate yarn (if requested)
Pythonyarn = estimate_yarn(meta, weight="worsted") # {"total_yards", "colors": [{"hex", "count", "yards"}], ...}
6. ASCII designs (precise hand-authored charts)
For exact, hand-designed charts (not photo-derived), use render_design("designs/file.txt"). Format:
# comment
palette: G=#58A05C, W=#FFFFFF, .=#FAFAF7
title: Frog Face
technique: graph
---
..GGGG..........GGGG....
.GGWWGG........GGWWGG...
One character = one stitch. . is background/padding. Rows auto-pad to longest row length.
Example 1:
Input: "Turn my cat photo into a C2C blanket pattern with 8 colors"
Output: Call generate_chart(Image.open("cat.jpg"), technique="c2c", grid_w=60, n_colors=8); report grid_w × grid_h (height aspect-corrected), list each hex color with stitch count, confirm counts sum to total grid size, and offer yarn estimate (ask preferred weight, default worsted).
Example 2:
Input: "How much yarn do I need for a worsted-weight version of this 50x50 graphgan with these colors?"
Output: Build meta dict with grid/colors, call estimate_yarn(meta, weight="worsted"), return per-color yardage plus total_yards.
Example 3:
Input: "I have an ASCII frog design, make it into a chart"
Output: Call render_design("designs/frog.txt"), save PNG, report stitch counts per palette color from returned meta.
- Default to
grid_w=50–60andn_colors=6–8unless the user specifies otherwise — good detail-to-complexity tradeoff. - For C2C, never manually adjust height for aspect ratio — the engine already applies the 0.7:1 h:w correction. Trust
meta["grid_h"]. - Always surface
meta["warning"]to the user if non-empty. - When giving stitch counts, state explicitly that they sum exactly to
grid_w * grid_h— this is a selling point (no hallucinated rows). - Recommend
rembgextra only when the user's photo has a busy background that should be removed before quantization. - Use the MCP server tools directly when running inside Claude Desktop/Cursor rather than shelling out to the CLI.
- Don't treat this as a generative/AI-art tool — it's deterministic image processing (resize + median-cut quantization + cleanup). Don't imply the output chart is "creatively generated."
- Don't forget technique-specific grid height differs for C2C vs. other techniques — never assume square-ish grids uniformly.
- Don't request
n_colorsoutside 2–16 orgrid_woutside 20–120 — these are hard bounds. - Don't manually recompute yarn yardage — always use
estimate_yarnagainst the chart'smeta, not raw guesses. - Don't forget ASCII design rows must be padded to equal length (engine auto-pads, but malformed palettes/missing
---separator will break parsing).