jackson2w/claude-code-skills / image-crop-focal-point
image-crop-focal-point
VerifiedThis skill should be used when the user asks to "fix this crop", "the photo is cut off", "set a focal point", "the preview is offset", "recrop this image", "the thumbnail cuts off the head", or any task requiring picking a normalized (x, y) focal point or CSS background-position so a specific subject stays in frame when an image is cropped to a different aspect ratio than its source.
Image Crop Focal Point Estimation
Determine a normalized (x, y) focal point (or CSS background-position)
so a specific subject stays visible when an image is cropped to a target
aspect ratio different from its source — for a smart-crop pipeline, a CSS
background-size: cover box, or any "center of interest" crop parameter.
Why this exists
Automatic saliency/attention-based cropping (or a naive center position)
frequently cuts off heads, faces, or other subjects when the source
photo's aspect ratio differs substantially from the target box — e.g. a
tall 3:4 portrait shot cropped into a wide 3:2 card, or a wide 3:2 group
photo cropped into a 1:1 square thumbnail. Manually picking a focal point
fixes it, but the crop math is easy to get wrong by eyeballing, and doing
it wrong silently ships a bad crop. This skill gives the exact procedure
so it doesn't need to be re-derived (or mis-derived) each time.
Procedure
-
View the actual source image file, not a resized/derivative version, at whatever resolution is convenient. Note the tool's reported original dimensions and the displayed-to-original scale factor if shown (e.g. "original 4284x5712, displayed at 1500x2000, multiply by 2.86") — the fraction math below doesn't need the multiplier, but it confirms which dimension is width vs. height.
-
Check for EXIF rotation before trusting displayed coordinates. If the image renders sideways or upside-down relative to how it's obviously meant to be viewed (e.g. text in the scene runs vertically, or the composition is clearly rotated), the file has an EXIF orientation tag that image-processing code (e.g.
sharp(buf).rotate()) will apply automatically — but the tool showing you the image may or may not have applied it. If you must estimate coordinates from a sideways render, transform them:- 90° CW correction:
(x', y') = (H_raw - y, x), new dimensions(H_raw, W_raw). - 90° CCW correction:
(x', y') = (y, W_raw - x), new dimensions(H_raw, W_raw). - 180° correction:
(x', y') = (W_raw - x, H_raw - y), same dimensions. Always double-check by reasoning about which correction makes the scene look upright, not just picking one.
- 90° CW correction:
-
Estimate the subject's bounding box in the (corrected) image as pixel coordinates, then convert to fractions:
x_frac = x / width,y_frac = y / height, each in[0, 1]. For multiple subjects (e.g. two faces), estimate each separately, then average — but sanity-check the average actually falls between them, not on top of one. -
Compute the crop's visible-fraction along the cropped axis, since this determines whether a candidate focal point actually keeps the subject in frame:
source_aspect = source_width / source_height,target_aspect = target_width / target_height.- If
source_aspect < target_aspect(source relatively taller than target): cropping happens on the vertical axis. Visible height fraction =source_aspect / target_aspect. - If
source_aspect > target_aspect(source relatively wider than target): cropping happens on the horizontal axis. Visible width fraction =target_aspect / source_aspect. - If they're equal, no cropping occurs on either axis — any focal point works, don't bother setting one.
-
Choose the focal coordinate on the cropped axis so the subject's bounding box falls inside
[focal - visible_fraction/2, focal + visible_fraction/2], clamped to[0, 1](a focal point withinvisible_fraction/2of an edge gets clamped by the crop implementation anyway, so don't overthink exact edge cases — bias inward with a small margin instead of hugging0or1). Leave the other (uncropped) axis at0.5or a rough visual center — it barely affects anything. -
Apply and verify against the real output, not just the input math:
- If the pipeline writes actual cropped derivative files (e.g. a
sharp().extract()-based square thumbnail), regenerate and inspect the real output image — don't just trust the arithmetic. - If the pipeline uses CSS
background-positionat render time (e.g.x_frac*100 + '%',y_frac*100 + '%'), build a small standalone HTML file with the exact same box dimensions/aspect-ratio, image URL, andbackground-position/background-size: cover, then screenshot it (headless Chrome or equivalent) to confirm visually. This is faster than a full rebuild/deploy cycle and works even when the image is already hosted remotely (point the test file's<img>/background URL directly at the live/remote asset).
- If the pipeline writes actual cropped derivative files (e.g. a
Translating Will's crop feedback into coordinates (2026-11-07)
He gives feedback per photo URL in plain words. Mapping that has held up:
| He says | Meaning for the crop centre |
|---|---|
| "fully centred" (a person) | centre on the midpoint of head and feet, not the face |
| "a bit higher in the crop" | move the crop down: larger y, about 10–15 % headroom above the top head |
| "off-centre" (a group) | x at the midpoint of the group's outer edges |
| "shift the preview all the way down" | subject near the top edge: use "top", not a numeric y |
Render the source with a 10 % grid before picking numbers
(photo-site-album-ingest/scripts/grid-sheet.sh), and review the regenerated
derivative as an image, not the arithmetic. Saliency crops get two-person
portraits wrong most often; check those first.
Worked example
Source photo 5712×4284 (aspect 1.333), target box 3:2 (aspect 1.5).
Since 1.333 < 1.5, cropping is vertical. Visible height fraction =
1.333 / 1.5 ≈ 0.889 — so only about 11% of the height is cropped total
(5.5% off each edge at center), meaning even a plain center crop is often
fine here. Contrast with a 3024×4032 portrait (aspect 0.75) into the same
3:2 box: visible height fraction = 0.75 / 1.5 = 0.5 — half the image
height is cropped, so a subject anywhere outside the middle 50% (e.g. a
face near the top third) gets cut off by a plain center crop and needs an
explicit focal point, typically y ≈ 0.2–0.3 for a subject positioned in
the upper part of the frame.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |