Readme
MoosicBox Image Helper
A command-line image processing tool for resizing, converting, and optimizing images with support for multiple formats.
Overview
The Image Helper (image_helper ) is a utility for image processing operations including:
Image Resizing : Resize images while maintaining aspect ratio
Format Conversion : Convert between multiple image formats
Quality Control : Configurable compression quality settings
Smart Resizing : Automatic aspect ratio calculation
Batch Processing : Process multiple images efficiently
libvips Integration : High-performance image processing (when available)
Installation
From Source
cargo install -- path packages/image -- features " build-binary,image,libvips"
Dependencies
System dependencies for optimal performance:
libvips (recommended, for high-performance processing)
Usage
Basic Usage
Resize an image to specific dimensions:
image_helper input.jpg output.jpg -- width 800 -- height 600
Maintain Aspect Ratio
Resize by width only (height calculated automatically):
image_helper input.png output.png -- width 1024
Resize by height only (width calculated automatically):
image_helper large.jpg thumbnail.jpg -- height 200
Convert between formats:
image_helper photo.png photo.jpg -- encoding JPEG -- quality 85
Quality Control
Set compression quality (0-100):
image_helper input.jpg output.jpg -- width 800 -- quality 95
Complete Example
image_helper \
/path/to/input.png \
/path/to/output.webp \
--width 1200 \
--height 800 \
--encoding WEBP \
--quality 90
Command Line Options
Option
Short
Description
Default
--width
- w
Target width in pixels
Auto-calculated
--height
- h
Target height in pixels
Auto-calculated
--encoding
- e
Output format (JPEG, PNG, WEBP)
Auto-detect from extension
--output
- o
Output file path
Required
--quality
- q
Compression quality (0-100)
80
JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
TIFF (.tiff, .tif)
BMP (.bmp)
GIF (.gif) - static images only
ICO (.ico)
JPEG (.jpg, .jpeg) - Good compression, lossy
PNG (.png) - Lossless, supports transparency
WebP (.webp) - Modern format, excellent compression
Aspect Ratio Handling
The tool intelligently handles aspect ratios:
Both Dimensions Specified
# Resize to exact dimensions (may distort image)
image_helper input.jpg output.jpg --width 800 --height 600
Width Only
# Height calculated to maintain aspect ratio
image_helper input.jpg output.jpg --width 800
Height Only
# Width calculated to maintain aspect ratio
image_helper input.jpg output.jpg --height 600
Neither Dimension
# Original dimensions preserved, format/quality change only
image_helper input.png output.jpg --encoding JPEG --quality 85
Quality Guidelines
JPEG Quality Settings
60-70 : Good for web thumbnails, small file size
75-85 : Good balance of quality and file size
85-95 : High quality for photos
95-100 : Maximum quality, larger files
WebP Quality Settings
50-70 : Excellent compression for web use
70-85 : High quality with good compression
85-100 : Maximum quality
PNG
PNG is lossless, quality setting affects compression level
Higher quality = better compression but slower processing
Examples
Create web thumbnails
# Create small thumbnail
image_helper photo.jpg thumb.jpg --width 150 --quality 75
# Create medium preview
image_helper photo.jpg preview.jpg --width 400 --quality 80
# Convert PNG to WebP for better compression
image_helper large.png optimized.webp --quality 85
# Convert old JPEG to high-quality WebP
image_helper old-photo.jpg new-photo.webp --quality 90
Batch processing script
# !/bin/bash
mkdir -p thumbnails
for img in *.jpg; do
image_helper "$img" "thumbnails/${img%.jpg}_thumb.jpg" --width 200 --quality 80
done
Album artwork optimization
# Standard album cover size
image_helper cover.png cover.jpg --width 1000 --height 1000 --quality 90
# High-res album cover
image_helper cover.png cover_hd.jpg --width 1400 --height 1400 --quality 95
libvips vs Image Crate
libvips : Faster processing, better memory usage, more formats
image crate : Pure Rust, easier deployment, fewer dependencies
Memory Usage
Optimized for large images with streaming processing
Automatically handles memory management for batch operations
Processing Speed
Multi-threaded processing where supported
Efficient algorithms for common operations like resizing
Error Handling
Common errors and solutions:
Unsupported format : Check input file format is supported
Permission denied : Verify read/write permissions for files
Out of memory : Reduce image size or enable libvips for better memory usage
Invalid dimensions : Ensure width/height values are positive integers
Integration
The image helper is used by other MoosicBox components:
Server : Automatic album artwork optimization
Web Interface : Dynamic image resizing for different screen sizes
Mobile App : Thumbnail generation for better performance
See Also