Alfie-Tech5/split-product-collage-skill

Split Product Collage

Create deterministic product crops. Never generate, repaint, remove backgrounds, or invent product detail. For low-resolution sources, use only fidelity-checked local enhancement and state that lost source detail cannot be recovered exactly.

Runtime

• Prefer .venv/bin/python in the skill directory.
• If .venv is absent, use python3 only after confirming python3 -c "from PIL import Image" succeeds.
• For a fresh installation, run sh scripts/install.sh once.

Workflow

1. Inspect every source image at original resolution with view_image.
2. Collect the output contract before writing:
   • folder name;
   • parent location;
   • individual naming policy: visible product names or numeric order. Ask one compact question only for missing fields. If the user already supplied them, proceed.
3. Choose a crop mode:
   • grid: contiguous photo tiles or equal catalog cells;
   • grid --tight: products and labels on a mostly uniform background;
   • boxes: irregular panels, unequal cells, or mixed layouts.
4. Exclude phone chrome, author information, carousel dots, captions, and engagement controls when they sit outside the product area. If a badge or watermark overlaps product pixels, report the limitation instead of pretending a lossless crop can remove it.
5. For uncertain boundaries, create an external numbered preview with --preview-only, inspect it, and ask for confirmation. For an obvious regular grid, proceed directly.
6. Run scripts/split_product_collage.py.
7. When the user explicitly asks for clearer delivery images, test conservative Lanczos enhancement first. For very small illustrated catalog cells, run a local A/B test against OpenCV EDSR and Waifu2x CUNet before choosing a method. Read references/enhancement-guide.md; never select a model that changes product geometry, text, colors, or accessories.
8. Validate count, order, dimensions, complete labels, balanced centering, and edge quality. Open the overview plus at least the first, middle, and last crop.
9. When Latin labels are available and Tesseract is installed, quantify horizontal label centering with scripts/measure_label_center.py. Target an absolute center offset below 0.5% of crop width and investigate anything above 1%.

Output Contract

• Copy the untouched source as 00-总图.<ext>.
• Save products as 01-名称.<ext>, 02-名称.<ext>, and so on.
• Order products left-to-right, then top-to-bottom.
• If labels are clearly readable, propose those names once. Confirm uncertain characters; never guess brand or product names.
• If names are unavailable, use 01.jpg, 02.jpg, and so on.
• Do not put previews or temporary files in the delivery folder. The hidden .cut-manifest.json is allowed for traceability.
• Never overwrite unrelated files. Use a new folder or pass --overwrite only for files created by this workflow.

Commands

Regular 3 by 3 grid:

.venv/bin/python scripts/split_product_collage.py INPUT \
  --output OUTPUT_FOLDER \
  --rows 3 --cols 3 \
  --box X1,Y1,X2,Y2

Uniform catalog board with tighter product-and-label crops:

.venv/bin/python scripts/split_product_collage.py INPUT \
  --output OUTPUT_FOLDER \
  --rows 3 --cols 3 \
  --box X1,Y1,X2,Y2 \
  --tight --tight-threshold 32 --tight-padding 0.04 \
  --names-file NAMES.txt \
  --upscale 3 --sharpen 60

Preview without delivering crops:

.venv/bin/python scripts/split_product_collage.py INPUT \
  --output TEMP_OUTPUT \
  --rows 3 --cols 3 \
  --box X1,Y1,X2,Y2 \
  --preview /tmp/cut-preview.jpg --preview-only

Irregular panels:

.venv/bin/python scripts/split_product_collage.py INPUT \
  --output OUTPUT_FOLDER \
  --boxes-file BOXES.json \
  --sort visual

BOXES.json accepts either [[x1,y1,x2,y2], ...] or:

[
  {"box": [10, 20, 300, 500], "name": "产品名"},
  {"box": [320, 20, 610, 500], "name": "产品名"}
]

Read references/cropping-guide.md when boundaries, gutters, tight cropping, or irregular ordering need judgment. Read references/enhancement-guide.md before using neural super-resolution or OCR-assisted recentering.

Validation

• Confirm output count equals rows * cols or the number of explicit boxes.
• Confirm every box is inside the source and has positive width and height.
• Confirm product content and labels are not cut off.
• Treat the product plus every visible label as one composition. Keep it visually centered with balanced side margins.
• Use OCR as a measurement aid, not as the only visual judge. Re-open any crop after shifting it; a mathematically centered label can still include a neighboring product.
• If the user identifies one crop as the visual reference, match its normalized subject scale and breathing room across the remaining crops. Do not force identical pixel boxes when overlays or label widths differ.
• Confirm no neighboring product leaks into a crop.
• Report any badge, watermark, or source overlay that cannot be removed by cropping without losing product pixels.
• Confirm 00-总图 is byte-for-byte copied from the source.
• Report the absolute delivery folder, output count, ordering, and any uncertain names.