Skip to content

twinko-ai/imagewand

Repository files navigation

ImageWand

PyPI version Python Versions Build Status codecov License Code style: black GitHub last commit GitHub repo size Downloads

A powerful command-line tool for image manipulation, including PDF to image conversion, image resizing, auto-fixing scanned images, applying filters, and merging scanned images.

Installation

pip install imagewand

Commands Overview

ImageWand provides several commands for different image manipulation tasks:

  • pdf2img: Convert PDF files to images
  • resize: Resize images
  • align: Automatically align tilted images to be horizontal/vertical
  • filter: Apply various filters to images
  • merge: Merge multiple scanned images into one
  • autocrop: Automatically crop images using frame detection or border removal
  • rmbg: Remove backgrounds from images using AI
  • workflow: Execute a saved workflow on an image
  • create-workflow: Create a new workflow by specifying steps
  • info: Display detailed information about images

Command Usage

PDF to Images

Convert PDF files to images with customizable DPI and format:

# Basic usage
imagewand pdf2img input.pdf

# Specify output directory and format
imagewand pdf2img input.pdf -o output_dir -f png

# Set custom DPI
imagewand pdf2img input.pdf -d 300

Resize Images

Resize images while maintaining aspect ratio:

# Resize by width
imagewand resize input.jpg -w 800

# Resize by height
imagewand resize input.jpg --height 600

# Resize by percentage
imagewand resize input.jpg -p 50

# Specify output path
imagewand resize input.jpg -o resized.jpg -w 800

Align Tilted Images

Automatically detect and correct the rotation of tilted images:

# Basic usage - auto-detects the best method
imagewand align tilted_scan.jpg

# Specify output path
imagewand align tilted_scan.jpg -o aligned.jpg

# Choose specific alignment method
imagewand align tilted_scan.jpg -m hough
imagewand align tilted_scan.jpg -m contour
imagewand align tilted_scan.jpg -m center

# Adjust minimum angle threshold for correction (default: 1.0 degrees)
imagewand align tilted_scan.jpg -a 0.5  # More sensitive
imagewand align tilted_scan.jpg -a 2.0  # Less sensitive

Alignment methods explained:

  • auto (default): Tries all methods and uses the one that detects the most significant angle
  • hough: Uses Hough Line Transform, best for documents with clear straight lines
  • contour: Uses contour analysis, better for images with distinct shapes
  • center: Focuses on the central portion of the image, ignoring the background (best for photos with clear subjects)

Output filenames:

  • Default: image_aligned.jpg (for default parameters)
  • With parameters: image_aligned_hough_a0.5.jpg (for method=hough, angle_threshold=0.5)

Apply Filters

Apply various image filters:

# Apply single filter
imagewand filter input.jpg -f grayscale

# Apply multiple filters
imagewand filter input.jpg -f "grayscale,sharpen"

# Process directory recursively
imagewand filter images/ -f grayscale -r

# List available filters
imagewand list-filters

Filter Parameters

You can customize filter parameters using the format filtername:param=value:

# Adjust contrast level (default is 1.5)
imagewand filter drawing.jpg -f "contrast:factor=1.2"

# Multiple filters with custom parameters
imagewand filter drawing.jpg -f "saturation:factor=1.3,contrast:factor=1.2,sharpen:factor=1.8"

# Mix of default and custom parameters
imagewand filter drawing.jpg -f "saturation:factor=1.3,contrast,sharpen:factor=2.0"

Common filter parameters:

  • contrast:factor=1.2 - Lighter contrast (default: 1.5)
  • sharpen:factor=1.8 - Stronger sharpening (default: 2.0)
  • blur:radius=3 - Adjust blur radius (default: 2)

Merge Images

Merge multiple scanned images into one:

# Merge all images in a directory
imagewand merge images_folder/ -o merged.jpg

# Merge specific images
imagewand merge image1.jpg image2.jpg image3.jpg -o merged.jpg

# Enable debug mode to see the matching process
imagewand merge images_folder/ -o merged.jpg --debug

Autocrop Images

Automatically crop images using frame detection or border removal:

# Auto mode - Tries frame detection first, falls back to border removal
imagewand autocrop photo.jpg

# Frame mode - Extract photo from contrasting frame/background
imagewand autocrop photo.jpg -m frame
imagewand autocrop photo.jpg -m frame --margin -5  # More aggressive crop
imagewand autocrop photo.jpg -m frame --margin 10  # Add margin

# Border mode - Remove white margins only
imagewand autocrop photo.jpg -m border
imagewand autocrop photo.jpg -m border -b -5  # More aggressive crop
imagewand autocrop photo.jpg -m border -b 10  # Keep more border

Cropping modes explained:

  • auto (default): Tries frame detection first, falls back to border removal if no frame is detected

  • frame: Best for photos on contrasting backgrounds (e.g., artwork on black paper)

    • Use --margin to adjust cropping (negative for tighter crop, positive for more margin)
    • Default margin is -5 for slightly aggressive crop
  • border: Best for documents with white margins

    • Use -b to adjust border percentage (negative for tighter crop, positive to keep more border)
    • Default border is 0 for exact content boundaries

Output filenames:

  • Auto mode: photo_auto.jpg, photo_auto_frame.jpg, or photo_auto_border.jpg
  • Frame mode: photo_frame.jpg or photo_frame_m10.jpg (with margin 10)
  • Border mode: photo_border.jpg or photo_border_b10.jpg (with 10% border)

Remove Backgrounds

Remove backgrounds from images using state-of-the-art AI models:

# Basic usage - single image
imagewand rmbg input.jpg

# Specify output path
imagewand rmbg input.jpg -o output.png

# Process all images in a directory
imagewand rmbg images/ -b

# Save to a specific output directory
imagewand rmbg images/ -b -o processed/

# Use alpha matting for improved edges
imagewand rmbg input.jpg --alpha-matting

# Use alpha matting with custom parameters
imagewand rmbg input.jpg --alpha-matting --alpha-matting-foreground-threshold 220 --alpha-matting-background-threshold 5 --alpha-matting-erode-size 15

# Use a different model
imagewand rmbg input.jpg --model u2net_human_seg  # Optimized for people

# Save current settings as a preset
imagewand rmbg input.jpg --model isnet-general-use --alpha-matting --alpha-matting-foreground-threshold 200 --alpha-matting-background-threshold 5 --alpha-matting-erode-size 20 --save-preset "my_portrait_settings"

# Use a saved preset
imagewand rmbg input.jpg --preset my_portrait_settings

# List all available presets
imagewand rmbg --list-presets

Available models:

  • u2net (default): General-purpose background removal
  • u2netp: Smaller, faster model but less accurate
  • u2net_human_seg: Optimized for human subjects
  • silueta: Alternative model with different characteristics
  • isnet-general-use: Another high-quality general-purpose model

Alpha matting parameters:

  • --alpha-matting: Enable alpha matting for improved edges
  • --alpha-matting-foreground-threshold: Foreground threshold (default: 240)
  • --alpha-matting-background-threshold: Background threshold (default: 10)
  • --alpha-matting-erode-size: Erode size (default: 10)

Presets:

  • Save your favorite settings with --save-preset "name"
  • Use saved settings with --preset name
  • List all available presets with --list-presets

Output filenames include information about the parameters used:

  • Default: input_nobg.png (always outputs PNG to preserve transparency)
  • With non-default model: input_nobg_modelname.png (e.g., input_nobg_u2net_human_seg.png)
  • With alpha matting: input_nobg_am.png or input_nobg_modelname_am.png
  • With custom alpha matting parameters: input_nobg_am_f220_b5_e15.png (where f=foreground threshold, b=background threshold, e=erode size)

Workflows

Workflows allow you to chain multiple operations together and apply them to an image in a single command. This is useful for repetitive image processing tasks.

# Create a workflow that aligns, crops, and resizes an image
imagewand create-workflow product_photo --add-align --add-autocrop --crop-mode frame --add-resize --resize-width 800

# Create a workflow for product photos with background removal
imagewand create-workflow product_bg_removal --add-align --add-autocrop --add-resize --resize-width 1200 --add-rmbg --rmbg-model isnet-general-use --rmbg-alpha-matting --rmbg-foreground-threshold 200

# Create a workflow with filters for document scanning
imagewand create-workflow document_scan --add-align --add-autocrop --add-filter "auto_levels,contrast:factor=1.2,sharpen"

# List all available workflows
imagewand workflow --list

# Execute a workflow on an image
imagewand workflow input.jpg --workflow product_photo

# Delete a workflow
imagewand workflow --delete product_photo

You can include any combination of:

  • Alignment (--add-align)
  • Auto-cropping (--add-autocrop)
  • Resizing (--add-resize)
  • Filters (--add-filter)
  • Background removal (--add-rmbg)

Each operation supports the same parameters as its corresponding standalone command.

The operations are performed in the order they're defined in the workflow, with each step receiving the output of the previous step.

Image Information

Display comprehensive information about images:

# Basic usage
imagewand info photo.jpg

The info command displays:

  • Basic file information: filename, path, size, modification date
  • Image properties: dimensions, format, color mode, color depth
  • DPI information
  • Color statistics: brightness, RGB channel values, sharpness
  • EXIF data (when --verbose flag is used)

About

Image processing utilities

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published