process-photos

name	process-photos
description	Process and enhance product photos for a marketplace listing using the Gemini API. Fixes orientation/colors/lighting and produces 3-4 realistic, authentic-looking photos ready for posting. Keeps backgrounds and natural wear visible for credibility.
user_invocable	true
argument	product name (subfolder name under marketplace/)

Process Photos: {{ argument }}

You are preparing listing-ready photos for {{ argument }} using the Gemini API image editing model (gemini-3.1-flash-image-preview) via the helper script scripts/gemini-edit-image.py.

Step 1 – Gather Context

1. Read {{ argument }}/LISTING.md to get:
   • דגם (model) and לינק רשמי (official URL) — needed to find reference photos
2. Check if an {{ argument }}/archive/ directory already exists. If it does, photos have already been processed — tell the user and stop (unless they explicitly asked to re-process).
3. Read all image files (*.jpeg, *.jpg, *.png, *.webp) in the {{ argument }}/ directory.
4. If there are no photos at all, go to Step 1b – Generate Photos from Web.
5. Otherwise, assess each photo:
   • What does it show? (front view, back/specs label, side, detail, etc.)
   • What's the orientation? (portrait, landscape, rotated?)
   • What's the quality? (lighting, focus, clutter in background)
   • Is it useful for the listing or just a reference/label shot?

Step 1b – Generate Photos from Web (only if no source photos exist)

When the product folder has no photos at all, create realistic listing photos from web reference images:

1. Use the official product URL from LISTING.md to fetch the manufacturer's product page.
2. Download 3–4 official product photos (different angles: front, open/detail, side).
3. For each downloaded photo, use the Gemini image editing script to transform it into a realistic apartment photo:
   • Place the product in a believable home environment (kitchen, living room, bedroom — whatever fits the product type)
   • Add subtle signs of real use: minor dust, light fingerprints, small scuffs, slightly imperfect placement
   • Use warm, natural home lighting (not studio lighting)
   • Add realistic surroundings: countertops, walls, flooring, nearby everyday items
   • The photo should look like it was taken with a phone camera in someone's apartment, NOT like a catalog shot
   • Example prompt: "Transform this product photo into a realistic photo taken in a real apartment. Place the product in a natural home setting (e.g., kitchen counter, living room). Add warm natural lighting as if from a window or ceiling light. Make it look like a real phone photo — slightly imperfect framing, natural shadows. Add very subtle signs of normal use like light dust or minor wear. The result must look completely authentic, as if someone took this photo of their own product at home to sell it."
4. Save the generated photos to the {{ argument }}/ directory.
5. Continue to Step 3 (skip Step 2 — reference photos were already used as the source).

Step 2 – Get Official Reference Photos

1. Use the official product URL from LISTING.md to fetch the manufacturer's product page.
2. Look at the official product photos — note:
   • How the product is styled and angled
   • Background style (usually clean white/neutral)
   • Which angles they chose (front, open, detail)
3. These serve as a style reference for how the processed photos should look.

Step 3 – Plan the Photo Set

Select 3–4 photos that will make the best listing. Prioritize:

1. Hero shot — front/main view, the most important photo (shown as thumbnail in listings)
2. Detail/feature shot — shows a key feature, open view, or interior
3. Angle/context shot — side view or the product in situ
4. Specs/label shot (optional) — if there's a label showing model/specs, include it as the last photo for credibility

If there are fewer than 3 usable source photos, note this and work with what's available.

Step 4 – Process Each Photo

For each selected photo, use the Gemini image editing script to enhance it. Process them one at a time.

The script is at scripts/gemini-edit-image.py. Usage:

python scripts/gemini-edit-image.py <input_path> <output_path> "<prompt>"

Requires GEMINI_API_KEY (or GOOGLE_API_KEY) env var to be set, and google-genai + Pillow packages installed.

Key principle: AUTHENTICITY over polish

The photos must look like real photos taken in a real home. Buyers distrust overly polished or synthetic-looking images. Do NOT replace or remove backgrounds — keep the real environment visible. Do NOT hide wear and tear, scratches, or signs of use — buyers expect to see the actual condition. The goal is a well-lit, well-framed photo that honestly represents the product.

General editing instructions for all photos:

• Fix orientation if the photo is rotated or tilted
• Improve lighting — make it brighter and more even, but keep it natural (not studio-perfect)
• Improve color balance — natural, accurate colors
• Keep the product itself exactly as-is, including any wear, scratches, or patina
• Keep the real background/environment — do NOT replace with white or neutral backgrounds
• Do NOT remove or hide signs of use — this builds buyer trust

Per-photo type instructions:

Hero shot:

• Prompt: "Fix orientation if tilted. Brighten the image and improve lighting to be more even and natural. Improve color balance. Keep the product exactly as-is including any wear or scratches. Keep the real background and surroundings — do NOT replace or remove them. This should look like a real, honest photo taken in someone's home, not a studio product shot."

Detail/feature shot:

• Prompt: "Improve lighting and color balance. Fix orientation if needed. Keep the product details sharp and clear, including any signs of use or wear. Keep the real background visible. This should highlight the product's features/interior while looking authentic and real."

Angle/context shot:

• Prompt: "Keep the real surroundings and background to show the product's size and placement in the home. Improve lighting and colors. Fix orientation if needed. Do not remove or replace the background — the real environment adds credibility."

Specs/label shot:

• Prompt: "Improve clarity and readability of the specs label. Brighten the image, increase contrast slightly, and fix orientation so the label reads straight. Keep the surroundings as-is."

After each edit:

1. Read the output image to review the result.
2. If the result needs refinement, run the script again on the original source photo with an adjusted prompt.
3. Note the output filename.

Step 5 – Review with User

1. Show all processed photos to the user (read each image file).
2. Present them in order: hero, detail, angle, specs.
3. For each photo, briefly note what was changed.
4. Ask the user:
   • Are they happy with the results?
   • Should any photo be re-processed with different instructions?
   • Should any photo be swapped for a different source photo?
5. If the user wants changes, re-run the script on the original source photo with an adjusted prompt.

Step 6 – Archive Original Photos

After the user approves the processed photos:

1. Create an archive/ subdirectory inside {{ argument }}/ if it doesn't already exist.
2. Move all original source image files (the ones that were processed) into {{ argument }}/archive/.
3. Do NOT move the newly processed output files — only the originals.
4. Confirm to the user which files were moved.

Output

Summarize:

• How many photos processed (out of how many source photos)
• What edits were applied to each
• Final photo filenames in listing order
• Which original files were archived to {{ argument }}/archive/