Image Editor

Input sources:

• Local file path: /path/to/image.jpg
• Uploaded file: /mnt/user-data/uploads/filename.png
• URL: https://example.com/image.jpg

Output location:

• Save to /mnt/user-data/outputs/ for files users should access
• Specify format via file extension (.png, .jpg, etc.) or --format flag

Basic Edits

Resize

Resize images to specific dimensions. By default, maintains aspect ratio (recommended).

Maintain aspect ratio (image fits within dimensions):

python3 scripts/process_image.py input.jpg output.jpg \
  --operation resize \
  --width 800 \
  --height 600 \
  --maintain-aspect

Exact dimensions (may distort):

python3 scripts/process_image.py input.jpg output.jpg \
  --operation resize \
  --width 800 \
  --height 600

Common use cases:

• Web display: 1920x1080, 1280x720, 800x600
• Thumbnails: 300x300, 200x200, 150x150
• Social media: 1200x630 (Facebook), 1080x1080 (Instagram)

Rotate

Rotate images by any angle. Use positive values for clockwise, negative for counter-clockwise.

90° clockwise:

python3 scripts/process_image.py input.jpg output.jpg \
  --operation rotate \
  --angle 90

Common rotations:

• 90°: Quarter turn clockwise
• -90° or 270°: Quarter turn counter-clockwise
• 180°: Upside down

Note: Image dimensions change after rotation (except 180°). The script uses expand=True to prevent cropping.

Crop

Crop images to a specific rectangular region using pixel coordinates (left, top, right, bottom).

python3 scripts/process_image.py input.jpg output.jpg \
  --operation crop \
  --left 100 \
  --top 50 \
  --right 500 \
  --bottom 400

Coordinate system:

• Origin (0, 0) is top-left corner
• Use get_image_info.py to check current dimensions first

Examples for 1000x800 image:

• Center square: --left 250 --top 100 --right 750 --bottom 600
• Left half: --left 0 --top 0 --right 500 --bottom 800
• Top half: --left 0 --top 0 --right 1000 --bottom 400

Flip

Mirror images horizontally or vertically.

Horizontal flip (left-right mirror):

python3 scripts/process_image.py input.jpg output.jpg \
  --operation flip \
  --direction horizontal

Vertical flip (top-bottom mirror):

python3 scripts/process_image.py input.jpg output.jpg \
  --operation flip \
  --direction vertical

Color Adjustments

All color adjustments use a --factor parameter:

• < 1.0: Decrease effect
• = 1.0: No change (original)
• > 1.0: Increase effect

Refer to references/image_processing_guide.md for detailed factor ranges and recommendations.

Brightness

Adjust image brightness (lightness/darkness).

python3 scripts/process_image.py input.jpg output.jpg \
  --operation brightness \
  --factor 1.3

Factor guide:

• 0.0: Completely black
• 0.5: Half brightness (darker)
• 1.0: Original (no change)
• 1.3: 30% brighter
• 2.0: Double brightness

Typical range: 0.5 to 2.0 Subtle adjustments: ±0.2 to ±0.5

Contrast

Adjust contrast between light and dark areas.

python3 scripts/process_image.py input.jpg output.jpg \
  --operation contrast \
  --factor 1.2

Factor guide:

• 0.0: Completely gray (no contrast)
• 0.5: Half contrast (flatter)
• 1.0: Original (no change)
• 1.5: 50% more contrast (more dramatic)
• 2.0: Double contrast

Typical range: 0.5 to 2.0 Subtle adjustments: ±0.2 to ±0.5

Saturation

Adjust color intensity/vibrancy.

python3 scripts/process_image.py input.jpg output.jpg \
  --operation saturation \
  --factor 1.4

Factor guide:

• 0.0: Grayscale (no color)
• 0.5: Half saturation (washed out)
• 1.0: Original (no change)
• 1.4: 40% more saturated (more vibrant)
• 2.0: Double saturation

Typical range: 0.0 to 2.0 Special case: Use 0.0 to convert to grayscale

Sharpness

Adjust image sharpness (clarity vs blur).

python3 scripts/process_image.py input.jpg output.jpg \
  --operation sharpness \
  --factor 1.5

Factor guide:

• 0.0: Maximum blur
• 0.5: Softened
• 1.0: Original (no change)
• 1.5: 50% sharper
• 2.0: Very sharp

Typical range: 0.5 to 2.0 Warning: Values >2.0 can introduce artifacts

Format Conversion

Convert between image formats by specifying the output file extension or using --format.

By file extension:

# PNG to JPEG
python3 scripts/process_image.py input.png output.jpg --operation brightness --factor 1.0

# JPEG to PNG
python3 scripts/process_image.py input.jpg output.png --operation brightness --factor 1.0

Using --format flag:

python3 scripts/process_image.py input.png output.jpg \
  --operation brightness --factor 1.0 \
  --format JPEG \
  --quality 90

Format considerations:

• PNG: Lossless, supports transparency, larger files
• JPEG: Lossy, no transparency, smaller files, quality 1-100 (recommended: 85-95)
• Note: JPEG cannot save transparent images (RGBA mode). Script auto-converts to RGB with white background.

Workflow Best Practices

Operation Order

For best results, perform operations in this sequence:

1. Crop
2. Resize
3. Rotate/Flip
4. Color adjustments (brightness, contrast, saturation, sharpness)

Multiple Operations

For images requiring multiple operations, apply operations sequentially:

# Example: Crop, resize, and brighten
python3 scripts/process_image.py input.jpg temp_cropped.jpg \
  --operation crop --left 100 --top 100 --right 900 --bottom 700

python3 scripts/process_image.py temp_cropped.jpg temp_resized.jpg \
  --operation resize --width 800 --height 600 --maintain-aspect

python3 scripts/process_image.py temp_resized.jpg /mnt/user-data/outputs/final.jpg \
  --operation brightness --factor 1.2

Preserving Originals

Always save to a new filename to preserve the original image. Use descriptive output names:

• image_resized.jpg
• image_bright.jpg
• image_final.jpg

Handling URLs

For images from URLs, download and process in one step:

python3 scripts/process_image.py \
  "https://example.com/photo.jpg" \
  /mnt/user-data/outputs/processed.jpg \
  --operation resize \
  --width 800 \
  --height 600 \
  --maintain-aspect

Common Request Patterns

"Make this image brighter" → Use brightness adjustment with factor 1.2-1.5

"Resize this for the web" → Use resize with --maintain-aspect and appropriate dimensions (e.g., 1280x720)

"Rotate this 90 degrees" → Use rotate with --angle 90

"Convert this PNG to JPEG" → Use any operation with .jpg output extension

"Make this image grayscale" → Use saturation with --factor 0.0

"Crop out the background" → Check dimensions first, then use crop with appropriate coordinates

"Make the colors more vibrant" → Use saturation with factor 1.3-1.5

Dependencies

The scripts require:

• Python 3
• Pillow (PIL fork)
• requests (for URL support)

Install if needed:

pip install Pillow requests --break-system-packages

Resources

scripts/process_image.py

Main image processing script supporting all basic edits and color adjustments. Handles both local files and URLs.

scripts/get_image_info.py

Utility script to display image information (format, dimensions, mode, file size).

references/image_processing_guide.md

Comprehensive reference with detailed explanations of:

• Color adjustment factor ranges and recommendations
• Image format comparisons (PNG vs JPEG)
• Resize guidelines and best practices
• Rotation and coordinate systems
• Workflow optimization tips

Load this reference when users need detailed guidance on parameters or when providing recommendations for adjustments.