auto-deskew
Use when the user wants to automatically straighten a tilted image — scanned documents, phone-captured pages, photographed receipts, or slightly off-axis photos. Detects the dominant skew angle and rotates the image to vertical/horizontal, optionally cropping the resulting transparent triangles. Uses ImageMagick `-deskew` for documents and a Hough-line fallback (via Python + OpenCV) for photographs. Triggers - "straighten this scan", "this photo is tilted", "deskew before OCR".
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- auto-deskew
- description
- Use when the user wants to automatically straighten a tilted image — scanned documents, phone-captured pages, photographed receipts, or slightly off-axis photos. Detects the dominant skew angle and rotates the image to vertical/horizontal, optionally cropping the resulting transparent triangles. Uses ImageMagick `-deskew` for documents and a Hough-line fallback (via Python + OpenCV) for photographs. Triggers - "straighten this scan", "this photo is tilted", "deskew before OCR".
- allowed-tools
- Bash(magick *), Bash(convert *), Bash(identify *), Bash(command *), Bash(test *), Bash(getconf *), Bash(mktemp *), Bash(cat *), Bash(awk *), Bash(rm *), Bash(mkdir *), Bash(find *), Bash(xargs *), Read, Write
03 SKILL.md 正文
Auto Deskew
Straighten a tilted image. Two backends, picked by content type:
- document (default) —
magick -deskew 40%. Detects skew via the Radon-style projection profile that ImageMagick's deskew operator implements. Fast, robust on text/scans up to ±15°. - photo — Python + OpenCV Hough-line transform. Detects the dominant horizontal/vertical line angle (horizons, building edges, table corners) and rotates by its negative. Use for photographs without a clean text baseline.
When to use
- Scanned documents that came in at an angle.
- Phone snapshots of pages, receipts, whiteboards.
- Slightly-tilted architectural / horizon photos (
--mode photo). - Pre-step before OCR — Tesseract accuracy degrades sharply past ±2° skew.
Do not use this skill when:
- The image is intentionally tilted (Dutch angle, artistic composition).
- Skew is severe (>15°) — usually means the document was captured upside down or sideways. Detect orientation first (
exiftool -Orientation, or rotate by 90/180 multiples) before deskewing. - The image has no straight reference lines (clouds, abstract textures) — Hough will return noise; rotation will be near-random.
Inputs
- Input — file or directory. Required.
- Mode —
document(default) |photo|auto(heuristic: ifmagick identify -format "%[colorspace]"isGrayor the image has very low saturation →document; elsephoto). - Recursive —
--recursivefor directory descent. - Output — default in-place suffix
_deskew.--output-dir <path>for sibling folder.--overwriteto replace. - Threshold (mode=document) —
-deskewpercentage. Default40%(ImageMagick's recommended value). Higher = more aggressive detection, more false positives. - Max angle — default
15°. If detected skew exceeds this, refuse to rotate and flag the file (probably wrong orientation, not skew). - Crop — default
on. After rotation, crop to the largest inscribed rectangle so there are no transparent / black triangle borders.--no-cropto keep the full rotated canvas. - Background — fill colour for the post-rotation triangles when
--no-crop. Defaultwhite. Usenonefor transparent (PNG/WebP only).
Procedure
-
Verify ImageMagick 7+. For
photomode, also resolve the plugin's uv venv and verify it hasopencv-python-headlessandnumpy(managed byimage-ops-install-deps; if missing, point at it):PLUGIN_DATA_DIR="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/image-ops" VENV_PY="$PLUGIN_DATA_DIR/venv/bin/python" test -x "$VENV_PY" || { echo "Plugin venv missing — run image-ops-install-deps."; exit 1; } "$VENV_PY" -c 'import cv2, numpy' 2>/dev/null \ || { echo "photo mode needs opencv-python-headless + numpy in the plugin venv — run image-ops-install-deps."; exit 1; }Invoke Python as
"$VENV_PY"directly, matching the conventionimage-ops-install-depsestablishes. Do not shell out touv run. -
Enumerate inputs (JPEG/JPG/PNG/TIFF/TIF/WebP). Skip and note RAW.
-
document mode:
Measure first, then write — the max-angle guard in step 5 has to decide before the file is rotated.
-deskewrecords what it detected in thedeskew:angleartifact, so a throwaway pass tonull:yields the angle without producing output:ANGLE=$(magick "$IN" -deskew "${THRESHOLD}%" -print '%[deskew:angle]\n' null:)Apply the guard (step 5), then do the real conversion:
magick "$IN" -background "$BG" -deskew "${THRESHOLD}%" \ $( [ "$CROP" = on ] && echo "+repage -fuzz 1% -trim +repage" ) \ "$OUT"-deskewapplies the rotation.-trimwith a small fuzz removes the resulting fill border whenCROP=on.$ANGLEfrom the measuring pass feeds both the guard and the summary. -
photo mode (Python via the plugin's uv venv):
import cv2, numpy as np, sys img = cv2.imread(sys.argv[1]) if img is None: # Unreadable / corrupt / unsupported — exit non-zero so the caller skips # the file rather than reading a "0.0" as "no skew detected". print("unreadable", file=sys.stderr) sys.exit(1) gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) edges = cv2.Canny(gray, 50, 150, apertureSize=3) lines = cv2.HoughLines(edges, 1, np.pi/720, 200) if lines is None: print("0.0"); sys.exit(0) # Collect angles near horizontal (±30°) and near vertical (±30° of 90°) angles = [] for rho, theta in lines[:200, 0]: deg = np.degrees(theta) - 90 # 0 = horizontal line if abs(deg) < 30: angles.append(deg) elif abs(deg - 90) < 30: angles.append(deg - 90) elif abs(deg + 90) < 30: angles.append(deg + 90) if not angles: print("0.0"); sys.exit(0) print(f"{np.median(angles):.3f}")That snippet is not shipped as a file — write it to a temp script at run time, then invoke it with the venv interpreter resolved in step 1:
DESKEW_PY="$(mktemp "${TMPDIR:-/tmp}/deskew_photo.XXXXXX")" # no suffix: BSD mktemp leaves it unrandomised cat > "$DESKEW_PY" <<'PYEOF' # ... the Python above, verbatim ... PYEOF if ! ANGLE=$("$VENV_PY" "$DESKEW_PY" "$IN"); then echo "SKIPPED (unreadable): $IN" >> "$failed_log" rm -f "$DESKEW_PY" continue fi magick "$IN" -background "$BG" -rotate "$(awk -v a="$ANGLE" 'BEGIN{print -1*a}')" \ $( [ "$CROP" = on ] && echo "+repage -fuzz 1% -trim +repage" ) \ "$OUT" rm -f "$DESKEW_PY"For a batch, write the temp script once before the loop and delete it after, rather than per file.
-
Max-angle guard: applies to both modes, using
$ANGLEfrom step 3 (document, measuring pass) or step 4 (photo). If|angle| > MAX_ANGLE, skip the file before writing anything and flag it:if awk -v a="$ANGLE" -v m="$MAX_ANGLE" 'BEGIN{ exit !(((a < 0) ? -a : a) > m) }'; then echo "$IN: detected ${ANGLE}° — exceeds max-angle ${MAX_ANGLE}°, skipping (likely wrong orientation, not skew)" continue fi -
Crop to inscribed rectangle (when
--no-cropis off and the simple-trimleaves uneven borders): use the analytic formula for the largest inscribed axis-aligned rectangle inside a rotated rectangle. For inputW×Hrotated byθ:new_w = (W·|cos θ| - H·|sin θ|) / (cos²θ - sin²θ) if W ≥ H new_h = (H·|cos θ| - W·|sin θ|) / (cos²θ - sin²θ)Crop centred. For small angles (<5°) the difference vs.
-trimis negligible —-trimis fine. -
For batch, parallelise with
xargs -P "$(getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)"—nprocis GNU coreutils and is absent on macOS/BSD. Skip files ending_deskew. -
Per-file failures append to
$failed_logand the batch continues. Report that list in the summary; a processed count on its own hides the skips.
Output
- Deskewed images at the resolved paths.
- Summary:
- Files processed / skipped (RAW or non-image) / failed / unchanged (|angle| < 0.1°) / refused (|angle| > max).
- Per-mode count when mixed.
- Distribution of detected angles (min / median / max) — sanity check across the batch.
Notes
- ImageMagick's
-deskewis tuned for bilevel/grayscale text. On colour photos it often returns 0° or noise — that's whyphotomode exists. - For OCR pipelines: deskew before binarisation. After deskew,
magick "$IN" -threshold 50%or hand off totesseractdirectly. - If you want both content types handled in one run:
--mode auto. The heuristic isn't perfect — review the angle distribution in the summary and re-run misclassified files explicitly. - This skill rotates only. For perspective correction (four-corner unwarping of a photographed document), use a dedicated tool like
dewarpor OpenCV'sgetPerspectiveTransform— auto-deskew won't fix keystoning.
04 同仓库更多 Skills
no-description
暂无简介
good-skill
Fixture skill that satisfies every rule.
broken-link
Links to a reference file that does not exist.
Bad_Name
Name violates the kebab-case rule and does not match the directory.
skill-authoring
Write, review, and validate portable agent skills in SKILL.md format. Use when creating a new skill, editing an existing one, or asked whether a skill follows the Agent Skills spec.
weigh-bags
Record scale readings for each bag — empty (tare), outbound, current, final — and reconcile them against the itemised inventory to find unaccounted weight. Use when the user gives a bag weight, says how heavy something is, weighs their luggage, or asks how close to the limit they are. Appends to bags.yaml and runs scripts/reconcile.py.