Smart Photo Editor Skill#

AI-powered photo editing and restoration skill for OpenClaw. Unifies Seedream (AI edits), ImageMagick (basic edits), and OpenCV (programmatic fixes) into one intuitive workflow.

Overview#

All-in-one intelligent photo editing skill - automatically selects the best tool for each image processing task.

✨ Key Advantages:

• ✅ Smart Tool Selection - Automatically chooses Seedream / ImageMagick / OpenCV based on task
• ✅ Unified Interface - All operations use the same calling pattern
• ✅ Bilingual Support - Optimized prompts for both Chinese and English contexts
• ✅ Automatic Fallback - Switches to backup tools if primary tool fails
• ✅ Large Image Auto-Handling - Avoids "image too large" API errors

Feature Availability#

This skill provides two tiers of functionality:

✅ Works out of the box (no extra dependencies)#

These features only require ImageMagick and/or OpenCV (both widely available on Linux/macOS):

• Resize / Crop / Smart-crop — dimension changes, aspect-ratio-preserving scaling
• Color adjustment — brightness, contrast, saturation, grayscale
• Perspective correction — 4-point skew/warp correction
• Smart compression — quality targeting, binary-search for target file size
• HDR tonemapping — log/bilateral/shadow/highlight recovery
• Background removal (basic) — solid-color background removal via ImageMagick
• Geometric inpainting — wire/line/rect removal with known coordinates ( inpaint.py)

🔒 Requires Seedream skill (AI features)#

These features require the byted-ark-seedream-skill (VolcEngine Ark Agent Plan, managed skill):

• Object removal (natural language) — remove objects described in text (people, vehicles, watermarks)
• Old photo restoration — AI scratch/dust/fading repair
• Scene replacement ( replace-scene) — put subject into a new scene via multi-reference fusion
• Background removal (AI) — rembg-based, or Seedream-based for complex edges

Note: The byted-ark-seedream-skill is an OpenClaw managed skill that requires a VolcEngine Ark account with the Seedream model enabled. Install with openclaw skills install byted-ark-seedream-skill.

---

Trigger Conditions#

Activates automatically when users mention keywords like:

• photo editing, edit image, retouch, smart photo edit
• remove object, delete object, erase, remove person, remove watermark, remove logo, 去除, 消除
• remove background, background removal, cutout, 抠图, 换背景
• restore, fix, old photo restoration, repair, 修复老照片, 老照片修复
• portrait retouching, portrait edit, smooth skin, whiten teeth, enhance eyes, remove blemish, red eye, 美颜, 人像精修, 红眼
• replace scene, change scene, put subject in, 换场景, 多图融合
• color adjustment, color correction, color grading, brightness, 调色, 色彩调整
• crop, resize, compress, auto crop, smart crop, 裁剪, 自动裁剪, 智能裁剪
• perspective, fix skew, flatten, perspective correct, 透视矫正, 视角矫正
• hdr, tonemap, highlight recovery, shadow recovery, 高动态, 阴影增强
• sharpen, denoise, 锐化, 降噪

---

Tool Selection Policy#

The skill mixes three classes of tool. Picking the right one for each task is what makes the unified entry-point useful, so the routing is explicit:

Use Seedream first for semantic / generative edits.

• Object removal in complex scenes (people, vehicles, watermarks, signs)
• Old-photo restoration (scratches, fading, color loss)
• Background replacement / scene swap
• Subjective enhancement: “make this look better / natural / cinematic”
• Edits where the model must infer missing visual content
• Natural-language requests, especially in Chinese

For these, Seedream is the value-add. OpenCV/ImageMagick can’t compete on quality, and a deterministic tool can’t “invent” plausible content.

Use deterministic tools first for mechanical edits.

• Resize, crop, format conversion
• Compression / quality targeting
• Brightness, contrast, saturation, gamma adjustments
• Geometric inpainting when coordinates are known (wires, dust spots, exact rectangles — call inpaint.py directly)
• Batch operations where reproducibility matters

For these, Seedream would be slower, costlier, and less predictable.

Encoded policy (auto mode):

text

semantic edit / restoration / object removal       → Seedream first; deterministic fallback
mechanical edit / resize / crop / compress / color → deterministic tools first
user explicitly asks for AI / natural restoration  → Seedream
user explicitly forces a tool with --tool ...      → honored verbatim

Per-task defaults ( --tool auto):

TaskDefaultNotesremove-objectSeedreamOpenCV branch only fires when Seedream is unavailable; redirects to inpaint.py for known-geometry casesrestoreSeedreamSeedream-only operation by designremove-backgroundrembgImageMagick fallback for solid-color backgrounds when rembg is missingresize / crop / color-adjustOpenCV/ImageMagickDeterministic, instant, freesmart-compressOpenCVContent-aware quality + format selectionperspective-correctOpenCVDocument/whiteboard correctionhdr-tonemapOpenCVAll four modes (auto / bilateral / log / shadows) are deterministicreplace-sceneSeedreamAI-only; no deterministic fallback (would produce poor results). If Seedream is unavailable, returns error directing user to install the Seedream skill.

Override with --tool seedream | opencv | imagemagick | rembg.

---

Installation & Dependencies#

Standard Installation Path#

~/.openclaw/skills/smart-photo-editor/

Python Interpreter#

All Python scripts ( scripts/*.py) use a portable #!/usr/bin/env python3 shebang.

You can run them directly:

bash

./scripts/edit.py --help

Or explicitly with your Python of choice (e.g. a virtualenv where you have installed the dependencies below):

bash

python3 scripts/edit.py --help

Make sure the Python interpreter you use has the required dependencies (OpenCV, Pillow, NumPy). Optional deps ( piexif, exif, rembg) add extra features; the skill will gracefully skip those features if they are missing.

bash

# Sanity check — required deps\python3 -c "import cv2, numpy, PIL; print('core deps ok')"

# Sanity check — full deps (includes optional rembg/piexif/exif)
python3 -c "import cv2, numpy, PIL, piexif, exif, rembg; print('all deps ok')"

Required & Optional Dependencies#

DependencyRequiredPurposeInstallationbyted-ark-seedream-skill✅ RequiredAI object removal, old photo restoration, image-to-image editingRequires VolcEngine Ark API access. Follow official setup guide to enable Seedream model accessimagemagick✅ RequiredBasic image editing (resize, crop, format conversion, color adjustments)sudo apt install imagemagick (Debian/Ubuntu) or brew install imagemagick (macOS)opencv-python-headless✅ RequiredWire removal, spot removal, image resizingpip install opencv-python-headlessrembg⚠️ OptionalAI-powered background removal (better results for complex scenes)pip install rembgpiexif⚠️ OptionalEXIF metadata preservation during editspip install piexifexif⚠️ OptionalExtended EXIF tag readingpip install exif

Install Optional Dependencies#

bash

source ~/.openclaw/venv-clawd/bin/activate
pip install rembg piexif exif

Cloudflare R2 Upload (Large Reference Images)#

When a reference image (subject or scene image) exceeds 1.5 MB, the skill can upload it to Cloudflare R2 instead of embedding it as a base64 data URI. This avoids hitting Seedream API payload size limits.

R2 is optional. Without configuration, large images fall back to base64 data URI (which may fail for very large files due to CLI argument limits).

To enable R2 upload, deploy your own Cloudflare Worker:

1. Create a Cloudflare R2 bucket and a Worker that accepts PUT requests (see the Cloudflare R2 documentation)
2. Set the following environment variables:

VariableRequiredDescriptionSEEDREAM_UPLOAD_TOKEN✅ YesBearer token for your R2 upload worker.SEEDREAM_UPLOAD_WORKER_URL✅ YesYour worker URL, e.g. https://your-worker.your-subdomain.workers.dev.bash

# Add to your shell profile or ~/.openclaw/.env
export SEEDREAM_UPLOAD_TOKEN="your-token-here"
export SEEDREAM_UPLOAD_WORKER_URL="https://your-worker.your-subdomain.workers.dev"

Without both variables, large images gracefully fall back to the data URI path (works for most cases; may hit CLI arg limits for very large multi-image batches).

VolcEngine Ark Setup#

For AI editing features (object removal, photo restoration), ensure:

1. You have a VolcEngine Ark account with API access
2. The Seedream (豆包生图) model is enabled for your account
3. Your OpenClaw configuration has valid VolcEngine API credentials

See the official VolcEngine Ark documentation for detailed setup instructions.

---

Core Features & Implementation#

1. Object Removal#

Primary Tool: Seedream Image-to-Image

Fallback Tool: OpenCV Inpainting (small scratches/lines)

Usage:

bash

# AI method (recommended) - complex scenes
image_generate \
  model="byted-ark-seedream-skill" \
  mode="image-to-image" \
  image="/path/to/photo.jpg" \
  reference_strength=0.85 \
  prompt="Remove the [object description] located at [location description]. Restore the seamless texture, keep everything else exactly the same."

OpenCV method — simple lines/minor imperfections:

bash

# Remove horizontal wire
./scripts/inpaint.py /path/to/photo.jpg /path/to/output.jpg \
  --type wire --y 760 --thickness 10

# Remove diagonal/angled line (supports any angle)
./scripts/inpaint.py /path/to/photo.jpg /path/to/output.jpg \
  --type line --x1 100 --y1 200 --x2 500 --y2 400 --thickness 3

# Remove rectangular region (watermarks, logos, text)
./scripts/inpaint.py /path/to/photo.jpg /path/to/output.jpg \
  --type rect --x 50 --y 50 --w 400 --h 80 --feather 5

# Remove multiple sensor dust spots in one command
./scripts/inpaint.py /path/to/photo.jpg /path/to/output.jpg \
  --type spots --spots "100,150,8;200,300,10;50,400,6"

# Remove multiple lines in one command
./scripts/inpaint.py /path/to/photo.jpg /path/to/output.jpg \
  --type lines --lines "0,100,800,100,3;100,200,500,400,5"

# Batch processing from JSON config
./scripts/inpaint.py /path/to/photo.jpg /path/to/output.jpg \
  --type batch --batch tasks.json

# JSON config example (tasks.json):
# {
#   "operations": [
#     {"type": "spot", "x": 100, "y": 150, "radius": 8},
#     {"type": "spot", "x": 200, "y": 300, "radius": 10},
#     {"type": "wire", "y": 500, "thickness": 5},
#     {"type": "rect", "x": 50, "y": 50, "w": 200, "h": 50, "feather": 10}
#   ]
# }

Algorithm Selection:

• ns (Navier-Stokes) - Better for textures and larger regions (default for wire/line)
• telea (Telea) - Faster, better for small regions (default for spot) Use --algo ns or --algo telea to override the default selection.

Prompt Optimization Examples:

• "Remove the black power cable at the bottom of the image" → "Remove the thin black horizontal power cable at the bottom 20% of the image. Restore the mountain texture seamlessly, keep everything else exactly the same."
• "Remove the pedestrian in the middle" → "Remove the pedestrian in the center. Fill with matching background texture naturally."

---

2. Background Removal#

Primary Tool: rembg (AI)

Fallback Tool: ImageMagick (inline – solid color backgrounds)

Usage:

bash

# rembg AI method (complex backgrounds)
rembg i input.jpg output.png

# ImageMagick method (solid color backgrounds)
./scripts/remove_bg.sh input.png output.png 20 "#FFFFFF"

---

3. Old Photo Restoration#

Primary Tool: Seedream Image-to-Image

Usage:

bash

image_generate \
  model="byted-ark-seedream-skill" \
  mode="image-to-image" \
  image="/path/to/old_photo.jpg" \
  reference_strength=0.7 \
  prompt="Restore this old photo. Remove all scratches, dust spots, and damage. Enhance clarity and contrast. Restore natural, vivid colors while preserving the original photo's character. Do not change the composition or subjects."

---

4. Basic Editing#

Primary Tool: ImageMagick + OpenCV

Common Commands:

bash

# Resize
convert input.jpg -resize 1920x1920\> output.jpg

# Crop
convert input.jpg -crop 800x600+100+50 output.jpg

# Format conversion + compression
convert input.png -quality 85 output.webp

# Color adjustment
convert input.jpg -brightness-contrast 10x5 output.jpg  # Brighter, higher contrast
convert input.jpg -modulate 100,130,100 output.jpg      # Increase saturation
convert input.jpg -grayscale Rec709Luma output.jpg      # Convert to B&W

OpenCV Operations (inpaint.py):

bash

# Denoise (reduce noise in low-light photos)
./scripts/inpaint.py input.jpg output.jpg --type denoise --strength 15

# Sharpen (enhance edges and focus)
./scripts/inpaint.py input.jpg output.jpg --type sharpen --strength 1.5

# Brightness/contrast/gamma adjustment
./scripts/inpaint.py input.jpg output.jpg --type adjust --brightness 15 --contrast 10 --gamma 0.9

5. Portrait Retouching#

Primary Tool: OpenCV (face detection + image processing)

Dependencies: opencv-python-headless (already required)

Portrait retouching provides face-aware enhancements for portrait photography:

• Skin smoothing — bilateral filter preserves edges while softening skin
• Red-eye removal — detects and corrects flash red-eye
• Teeth whitening — targets lower-face region, preserves surrounding
• Eye enhancement — brightens and sharpens eyes
• Face brightness/contrast — applies adjustments only to detected face
• Blemish removal — removes small spots using inpainting
• Skin tone enhancement — warm, healthy color correction

bash

# Skin smoothing only
./scripts/portrait.py input.jpg output.jpg --smooth 3

# All enhancements (balanced)
./scripts/portrait.py input.jpg output.jpg --all

# Subtle preset (conservative)
./scripts/portrait.py input.jpg output.jpg --subtle

# Custom combination
./scripts/portrait.py input.jpg output.jpg \
  --smooth 2 --enhance-eyes --whiten-teeth 0.3 --brightness 10

# JSON output
./scripts/portrait.py input.jpg output.jpg --all --json

ParameterDescription--smoothSkin smoothing strength 1-10--denoiseDenoise strength 1-30--red-eyeRemove flash red-eye--whiten-teethTeeth whitening strength 0.1-0.8--enhance-eyesBrighten/sharpen eyes--brightnessFace brightness -100 to 100--contrastFace contrast -100 to 100--gammaFace gamma correction 0.1-3.0--sharpenSharpening strength 0.5-3.0--blemish-removalRemove small blemishes--skin-toneWarm skin tone enhancement--allApply all enhancements (balanced)--subtleConservative all enhancements--no-auto-detectSkip face/eye detection--no-exifDo not preserve EXIF--jsonJSON output mode

6. EXIF Preservation#

Automatic: All write operations preserve EXIF metadata by default

Tool: scripts/exif_utils.py — standalone EXIF utility

All editing scripts automatically preserve EXIF metadata from input to output.

bash

# Read EXIF from an image
./scripts/exif_utils.py read photo.jpg

# Strip EXIF from an image
./scripts/exif_utils.py strip photo.jpg -o output.jpg

# Copy EXIF from one image to another
./scripts/exif_utils.py copy source.jpg dest.jpg

Supported tags: Make, Model, DateTime, Orientation, Exposure Time, F-Number, ISO, Focal Length, Lens Model, and more.

---

7. Smart Crop (Auto-Crop)#

Primary Tool: OpenCV saliency detection + optional GrabCut refinement

Dependencies: opencv-python-headless (already required)

Automatically detects the most "interesting" region in an image and crops to it. Uses OpenCV's StaticSaliencyFineGrained algorithm by default, with spectral and edge-based fallbacks.

bash

# Auto-crop to salient region with default padding
./scripts/smart_crop.py input.jpg output.jpg

# Crop to specific aspect ratio
./scripts/smart_crop.py input.jpg output.jpg --aspect 16/9

# Crop to 4:3 with 10% margin around subject
./scripts/smart_crop.py input.jpg output.jpg --aspect 4/3 --padding 0.1

# Resize to exact dimensions after smart crop
./scripts/smart_crop.py input.jpg output.jpg --width 800 --height 600

# Use GrabCut refinement for cleaner boundaries
./scripts/smart_crop.py input.jpg output.jpg --grabcut

# Generate debug saliency map overlay
./scripts/smart_crop.py input.jpg output.jpg --debug

ParameterDescription--aspect, -aAspect ratio (e.g. 16/9, 4/3, 1/1)--width, -wTarget width in pixels--height, -HTarget height in pixels--padding, -pMargin around subject (0.0-0.5, default 0.05)--threshold, -tSaliency threshold 0.05-0.95 (default 0.3)--algorithm``auto / finegrained / spectral / edge``--grabcut, -gUse GrabCut to refine crop boundary--debug, -dGenerate debug saliency map overlay

8. Perspective Correction#

Primary Tool: OpenCV (auto-detection + warpPerspective)

Auto-detects document/sheet borders using edge detection + contour analysis and corrects perspective distortion. Also supports manual corner specification.

bash

# Auto-detect and correct
./scripts/edit.py --task perspective-correct --image doc.jpg --output flat.jpg

# With manual corners (top-left, top-right, bottom-right, bottom-left)
./scripts/edit.py --task perspective-correct --image doc.jpg --output flat.jpg \
  --corners "100,50,600,50,600,800,100,800"

# Batch JSON
./scripts/edit.py --json < tasks.json

ParameterDescription--corners4 points as CSV x1,y1,x2,y2,x3,y3,x4,y4 (TL,TR,BR,BL). Omit for auto-detection

Algorithm: Adaptive threshold → contour detection → largest 4-point quadrilateral → perspective transform.

---

9. Intelligent Compression#

Primary Tool: OpenCV (content analysis + format-specific encoding)

Content-aware image compression using entropy, edge density, and color variance analysis to auto-select the best format and quality.

bash

# Auto-select best format and quality
./scripts/edit.py --task smart-compress --image photo.jpg --output optimized.jpg

# Target file size (auto binary-searches quality)
./scripts/edit.py --task smart-compress --image photo.jpg --output optimized.jpg --target-kb 200

# Force WebP with specific quality
./scripts/edit.py --task smart-compress --image photo.jpg --output optimized.webp \
  --format webp --quality 85

# Batch JSON
./scripts/edit.py --json < tasks.json

ParameterDescription--target-kbTarget output size in KB (enables binary-search for optimal quality)--formatForce output: jpeg

Auto-decision logic:

• JPEG — high entropy (>6.5) + dense edges → complex photographic content
• PNG — low color variance (<500) + low edges → flat graphics/screenshots; or alpha channel detected
• Quality — auto-selected based on entropy (65–92) unless --target-kb is specified

---

10. HDR / Tonemapping#

Primary Tool: OpenCV (multi-scale bilateral decomposition + CLAHE)

HDR-style tone mapping to enhance dynamic range on single images. Uses bilateral filter decomposition to separate illumination from detail, compress the illumination layer's dynamic range, then recombine — producing natural-looking highlight/shadow recovery.

bash

# Auto mode (default — picks best method based on image analysis)
./scripts/edit.py --task hdr-tonemap --image photo.jpg --output hdr_enhanced.jpg

# Bilateral mode — detail-preserving compression (best for most photos)
./scripts/edit.py --task hdr-tonemap --image photo.jpg --output hdr_enhanced.jpg --mode bilateral --strength 1.2

# Log mode — fast global compression (good for screenshots/graphics)
./scripts/edit.py --task hdr-tonemap --image photo.jpg --output hdr_enhanced.jpg --mode log --gamma 2.2

# Shadows mode — lighten dark regions (backlit photos)
./scripts/edit.py --task hdr-tonemap --image photo.jpg --output hdr_enhanced.jpg --mode shadows --strength 1.5

# Highlight mode — compress blown highlights
./scripts/edit.py --task hdr-tonemap --image photo.jpg --output hdr_enhanced.jpg --mode highlight --strength 1.2

ParameterDescription--modeauto / bilateral / log / shadows / highlight (default: auto)--strengthEnhancement strength 0.1-2.0 (default: 1.0)--gammaGamma value for log mode (default: 2.2)

Algorithm: Bilateral filter decomposition — base (illumination) layer compressed with S-curve; detail layer preserved and boosted; adaptive saturation adjustment.

---

11. Scene Replacement#

Primary Tool: Seedream multi-reference image fusion (AI-only, no deterministic fallback)

Place a subject (portrait / pet / product) into a new scene using Seedream's multi-reference image fusion. Wraps 豆包 app's "多图融合" + "换场景" feature.

Requires: the byted-ark-seedream-skill (this task is AI-only; an OpenCV/ImageMagick fallback would produce poor results and is intentionally omitted).

Usage:

bash

# 1) Subject + scene image (most common)
./scripts/edit.py --task replace-scene \
    --subject photo.jpg --scene cafe.png --output out.jpg

# 2) Subject + text-only scene description
./scripts/edit.py --task replace-scene \
    --subject pet.jpg --scene-prompt "阳光下的草地" --output out.jpg

# 3) Product photo into lifestyle scene
./scripts/edit.py --task replace-scene \
    --subject product.png --scene lifestyle.jpg --output out.jpg \
    --subject-type product

# 4) Custom prompt override (full artistic control)
./scripts/edit.py --task replace-scene \
    --subject portrait.jpg --scene beach.jpg --output out.jpg \
    --prompt "把人物放在黄昏海边沙滩，长发随风，光线偏暖，景深虚化"

# 5) Subject in center, close-up framing
./scripts/edit.py --task replace-scene \
    --subject portrait.jpg --scene studio.jpg --output out.jpg \
    --position center --scale close

# 6) Full-body shot, subject on the right
./scripts/edit.py --task replace-scene \
    --subject portrait.jpg --scene beach.jpg --output out.jpg \
    --position right --scale full

# 7) JSON batch with position/scale
./scripts/edit.py --json < tasks.json

Argument table:

ParameterTypeRequiredDefaultDescription--subject / -Spath✅—Subject image (portrait / pet / product)--scenepath⚠️ one of—Target scene image--scene-promptstring⚠️ one of—Target scene text description (used if no scene image)--subject-typeenum❌auto``auto / portrait / pet / product. Selects prompt template + reference_strength.--prompt / -pstring❌(from template)Override the default prompt--reference-strengthfloat❌0.85 (portrait/pet) / 0.90 (product)How strongly Seedream must preserve the subject. Higher = stricter.--watermarkflag❌falseAdd Seedream watermark. Default OFF (most uses are product / academic).--positionenum❌centerHorizontal subject placement: left / center / right. Feeds into the scene-prompt as positional hint.--scaleenum❌mediumSubject framing: close (特写) / medium (中景) / full (全身). Feeds into the scene-prompt as framing hint.--output-formatenum❌follow subjectjpeg / png / webp``--output / -opath❌autoOutput path

Validation rules:

• --subject is required.
• Exactly one of --scene / --scene-prompt is required (both → error).
• If --scene-prompt is given, it must be at least 3 characters.
• Subject image is auto-resized to 2048px max side (existing API limit helper).

Subject-type auto-detection: When --subject-type auto is passed (default), the skill uses two heuristics:

1. Filename keyword — pet/cat/dog/... → pet; portrait/selfie/face/... → portrait; product/item/bottle/... → product
2. Corner solidity check — if all 4 corners are within 15 RGB units, classified as product (typical product shot on flat backdrop)

If neither heuristic matches, falls back to portrait (most common case). For certainty, always pass --subject-type explicitly.

JSON batch format:

json

{
  "operations": [
    {"task": "replace-scene", "subject": "p1.jpg", "scene": "office.jpg",
     "output": "p1_office.jpg", "subject-type": "portrait"},
    {"task": "replace-scene", "subject": "p2.jpg", "scene-prompt": "雪山日落",
     "output": "p2_mountain.jpg", "subject-type": "portrait"},
    {"task": "replace-scene", "subject": "shoe.png", "scene": "running_track.jpg",
     "output": "shoe_track.jpg", "subject-type": "product", "reference-strength": 0.9}
  ]
}

JSON batch key naming: JSON keys use underscores (Python identifier convention): scene_prompt, subject_type, reference_strength, etc. The CLI flags use dashes ( --scene-prompt, --subject-type). The skill automatically normalizes dashed JSON keys to underscored ones, so both work; use whichever is more natural for your tooling.

Output: The result JSON envelope includes a generation_time_s field (extracted from Seedream's own metadata) for quota tracking.

---

Unified API Interface#

ParameterTypeDefaultRequiredDescriptiontaskstring-✅Task type: remove-object / remove-background / restore / resize / crop / color-adjust / perspective-correct / smart-compress / hdr-tonemap / replace-scene``imagestring-✅Input image pathpromptstring""❌Object description/location (required for remove-object)toolstring"auto"❌Force specific tool: auto / seedream / imagemagick / opencv / rembg``output_formatstring"jpeg"❌Output format: jpeg / png / webpqualityinteger95❌Output quality (0-100)

---

Intelligent Decision Flow#

text

User request → Analyze task type
    ↓
Object removal? → Seedream (default) → Failed? → OpenCV fallback
    ↓
Background removal? → Detect background → Solid? ImageMagick : rembg
    ↓
Old photo restoration? → Seedream (reference_strength=0.7)
    ↓
Basic editing? → ImageMagick

---

Examples#

Remove Power Cable#

text

Task: Remove the black power cable at the bottom of the image
Parameters:
  task: remove-object
  image: mountain.jpg
  prompt: "Remove the thin black horizontal power cable at the bottom 20% of the image. Restore the mountain texture seamlessly, keep everything else exactly the same."
  tool: seedream

Old Photo Restoration#

text

Task: Restore this old photo
Parameters:
  task: restore
  image: old_photo.jpg
  prompt: "Remove scratches and dust spots, enhance clarity, restore natural colors"

Background Removal#

text

Task: Remove background from portrait photo
Parameters:
  task: remove-background
  image: portrait.jpg
  tool: auto

Portrait Retouching#

bash

# Apply all portrait enhancements
./scripts/portrait.py input.jpg output.jpg --all

# Subtle skin smoothing and eye enhancement
./scripts/portrait.py input.jpg output.jpg --smooth 2 --enhance-eyes

---

Error Handling & Fallbacks#

1. Seedream API failure → surface the Seedream error verbatim; for known-geometry cases use scripts/inpaint.py directly ( --type spot/wire/rect) or pass --tool opencv to get the inpaint.py guidance message.
2. Seedream skill unavailable / --tool opencv → op_remove_object returns an actionable redirect listing common inpaint.py invocations.
3. Image too large → Auto-resize to 2048px max side, process, output.
4. rembg not installed → Auto-fallback to ImageMagick remove-bg.
5. Unsupported format → Auto-convert to JPEG for processing.

---

Large Image Handling Strategy#

• Seedream API limit: ~2048px maximum side length
• Auto-detect image dimensions, if exceeded:
  1. Proportionally resize to 2048px max side
  2. Perform editing operation
  3. Output processed image
• Prevents "image too large" errors

---

Skill File Structure#

text

smart-photo-editor/
├── SKILL.md              # This file
├── README.md             # Quick start guide
├── scripts/
│   ├── edit.py           # ⭐ Unified CLI entry point (all operations)
│   ├── inpaint.py        # OpenCV wire/spot/line/rect/denoise/sharpen/adjust
│   ├── portrait.py        # Portrait retouching (skin, eyes, teeth, etc.)
│   ├── smart_crop.py     # Smart auto-crop based on saliency detection
│   ├── exif_utils.py     # EXIF read/strip/copy utility
│   └── remove_bg.sh      # Background removal wrapper
└── examples/             # Before/after comparison examples

---

Unified CLI ( edit.py)#

The recommended entry point for all photo editing operations.

bash

# Object removal (AI)
./scripts/edit.py --task remove-object --image photo.jpg \
  --prompt "Remove the person in the center" --output out.jpg

# Old photo restoration
./scripts/edit.py --task restore --image old_photo.jpg --output restored.jpg

# Background removal
./scripts/edit.py --task remove-background --image portrait.png --output no_bg.png

# Resize
./scripts/edit.py --task resize --image photo.jpg --output small.jpg --width 800

# Crop
./scripts/edit.py --task crop --image photo.jpg --output crop.jpg \
  --x 100 --y 100 --width 400 --height 300

# Color adjustment
./scripts/edit.py --task color-adjust --image photo.jpg --output bright.jpg \
  --brightness 20 --saturation 30

# Batch mode (JSON)
./scripts/edit.py --json < batch_tasks.json

Unified Parameters#

ParameterTypeDefaultDescription--taskstringrequiredOperation: remove-object, restore, remove-background, resize, crop, color-adjust, perspective-correct, smart-compress, hdr-tonemap``--image / -istringrequiredInput image path--output / -ostringautoOutput path (default: {input}.{task}{ext})--prompt / -pstring-Description for AI operations--tool / -tstringautoForce tool: auto, seedream, opencv, imagemagick, rembg``--width / -wint-Target width (resize/crop)--height / -Hint-Target height (resize/crop)--max-dimint-Max dimension, maintains aspect (resize)--x, --yint-Offset for crop--brightnessfloat-Brightness: -100 to 100--contrastfloat-Contrast: -100 to 100--saturationfloat-Saturation: -1 to 1--grayscaleflagfalseConvert to grayscale--cornersstring-Perspective corners: x1,y1,x2,y2,x3,y3,x4,y4 (TL,TR,BR,BL)--target-kbint-Target file size in KB (smart-compress quality search)--formatstring-Output format: jpeg | png | webp``--modestringautoHDR tonemap mode: auto / bilateral / log / shadows / highlight--strengthfloat1.0Enhancement strength 0.1-2.0 (hdr-tonemap)--gammafloat2.2Gamma value for log mode (hdr-tonemap)--qualityintautoOutput quality 1-100 (jpeg/webp; ignored when --target-kb is set)--positionstring-Horizontal placement for replace-scene: left / center / right``--scalestring-Framing for replace-scene: close / medium / full``--subject / -Sstring-Subject image path (required for replace-scene)--scenestring-Scene image path (one of --scene or --scene-prompt for replace-scene)--scene-promptstring-Scene text description (one of --scene or --scene-prompt for replace-scene)--subject-typestringautoSubject type for replace-scene: auto / portrait / pet / product``--reference-strengthfloat0.85How strongly Seedream preserves the subject--watermarkflagfalseAdd Seedream watermark (default OFF)--jsonflagfalseEmit JSON result envelope on stdout. Combine with --batch (or piped stdin) for JSON batch input.--batch / -bstring-JSON file for batch operations

JSON Batch Format#

json

{
  "operations": [
    {"task": "remove-object", "image": "a.jpg", "prompt": "Remove the person", "output": "a_out.jpg"},
    {"task": "restore", "image": "b.jpg", "output": "b_out.jpg"},
    {"task": "resize", "image": "c.jpg", "output": "c_small.jpg", "width": 800}
  ]
}

---

Changelog#

1.5.0 — 2026-07-19#

New replace-scene parameters

• --position {left,center,right} — controls horizontal placement of the subject in the generated scene. Feeds into the scene-prompt as a positional hint so Seedream places the subject accordingly.
• --scale {close,medium,full} — controls subject framing (特写/中景/全身). Feeds into the scene-prompt as a framing hint.

R2 large-file upload for Seedream reference images

• When a reference image exceeds 1.5 MB, the skill can upload to Cloudflare R2 and pass the public URL to Seedream instead of embedding a base64 data URI.
• Requires self-deployed Cloudflare R2 Worker + SEEDREAM_UPLOAD_TOKEN and SEEDREAM_UPLOAD_WORKER_URL env vars.
• Without R2 configured, large images gracefully fall back to base64 data URI.

1.4.0 — 2026-07-14#

New feature: replace-scene task Adds a new AI-driven task that places a subject (portrait / pet / product) into a new scene using Seedream's multi-reference image fusion. Wraps 豆包 app's "多图融合" + "换场景" feature.

• New --subject (alias of --image for this task) + mutually-exclusive --scene (image) or --scene-prompt (text) input pair.
• --subject-type {auto,portrait,pet,product} selects a per-type prompt template and reference_strength. auto uses filename keyword + corner solidity heuristics.
• --watermark defaults to OFF (most uses are product / academic).
• New _call_seedream(reference_images=...) parameter — passes a JSON array of data URIs to Seedream (which accepts up to 14 reference images).
• Subject image is auto-resized to 2048px max side; temp files are cleaned up.
• Returns info.generation_time_s extracted from Seedream's metadata for quota tracking.

Bug fixes (incidental, surfaced by v1.4.0 testing)

• process_batch now normalizes dashed JSON keys ( scene-prompt → scene_prompt, target-kb → target_kb, subject-type → subject_type, no-maintain-aspect → no_maintain_aspect) before unpacking into process(**op). Previously these were silently dropped into the trailing **kwargs and the real parameter received its default — a very confusing failure mode (especially for target-kb where the result was a wildly different file size than requested).
• process() now translates no_maintain_aspect=True (from JSON batch) to maintain_aspect=False (the inverted semantics the op_resize function expects), mirroring the same translation main() does for the CLI.

Docs

• New section 11 "Scene Replacement" with 6 worked examples, full argument table, validation rules, auto-detection logic, and JSON batch format.
• Updated Tool Selection Policy + Per-task defaults tables to include replace-scene.
• Updated Unified API Interface task list.

1.3.4 — 2026-07-14#

ImageMagick argument fix

• op_resize / op_crop / op_color_adjust / op_remove_background (ImageMagick fallback): all ImageMagick CLI arguments are now passed as separate list elements instead of single space-joined strings. Previously ImageMagick would reject commands like -resize 800x800> because the flag and value were concatenated into one string.

HDR bilateral saturation fix

• _tonemap_bilateral no longer performs a pseudo-HSV operation directly on BGR channels (which corrupted colors). Now uses proper cv2.cvtColor(BGR→HSV) → boost saturation → cv2.cvtColor(HSV→BGR).

Background removal fallback fix

• remove_bg.sh ImageMagick fallback: corrected matte floodfill coordinates (was passing RGB values as coordinates; now uses 0,0). Removed erroneous -alpha extract which turned output into a pure alpha mask.
• edit.py ImageMagick fallback: replaced -trim (which merely cropped edges) with -transparent <detected-bg-color> so the result is actually a transparent-background image.

Runtime robustness

• op_remove_background now probes both $PATH and the team venv ( venv-clawd/bin/rembg) for rembg, matching Laoguo's actual deployment environment.
• _call_seedream guards against shutil.copyfile(local, output_path) when source and destination are the same file (would truncate to zero bytes).
• _save_with_quality now derives the actual output format from the file extension, preventing OpenCV warnings when --format and --output disagree (e.g. --output foo.webp --format png).

CLI

• Added --no-maintain-aspect flag for resize task to allow non-proportional stretching.

1.3.3 — 2026-06-13#

Tool selection policy

• Codified the routing policy (see "Tool Selection Policy" near the top of this file): Seedream first for semantic / generative edits, deterministic tools first for mechanical edits.
• op_remove_object no longer keyword-sniffs the prompt for "wire / cable / line / spot / dust / scratch" and silently routes to a stub. --tool auto now picks Seedream when available; the OpenCV branch surfaces an actionable redirect to scripts/inpaint.py for known-geometry cases.
• The redirect message also lists the most common inpaint.py invocations ( --type spot, --type wire, --type rect) so users have a clear next step instead of a guess.

1.3.2 — 2026-06-13#

Bug fixes

• op_resize / op_crop / op_color_adjust no longer raise TypeError: got an unexpected keyword argument 'mode'. The CLI's --mode flag is now only forwarded for hdr-tonemap. (Was reported as "numpy 2.x compat issue"; root cause was kwargs leakage.)
• smart-compress --target-kb no longer crashes with No such file or directory: foo.q55.tmp. The binary-search probe file now uses the format's real extension ( .jpg/.png/.webp) so OpenCV can pick a codec.
• --quality is now an actual CLI flag, declared in argparse and forwarded into op_smart_compress (was documented but unrecognized).
• --json on a single-operation invocation now emits a JSON envelope on stdout instead of blocking on stdin. Batch input is still accepted via --batch FILE or piped stdin.
• Markdown code fence around the AI-method / OpenCV-method examples is correctly paired (was rendered with broken nesting).
• compatibility frontmatter key moved under metadata.compatibility (was rejected by the OpenClaw skill validator as an unknown top-level key).
• _tonemap_shadows annotation corrected from np.float32 to np.ndarray.

Seedream bridge rewrite The previous integration referenced a non-existent bin/generate.sh and a non-existent Python module. _call_seedream now invokes node scripts/generate.js with --prompt, --mode image-to-image, --reference_images <data-URI JSON array>, --reference_strength, and --optimize false, parses the JSON envelope from stdout, locates the first download_success image, and stages its local_path to the caller's output_path. Local file paths are encoded as data:image/<type>;base64,<...> data URIs because Seedream's validator only accepts HTTP URLs or data URIs. Verified end-to-end with a real ARK API call (200×200 input → 2048×2048 generated output, ~30 s).

Docs

• Added "Python Interpreter" section: all scripts hard-shebang the team venv ( ~/.openclaw/venv-clawd/bin/python); running them under system Python will spuriously report piexif/exif/rembg as missing.
• --quality and --json table entries clarified.