Thumbnail
Generate square thumbnails from images with customizable size and fit modes. Perfect for creating preview images, profile pictures, gallery thumbnails, and icon sizes.
Installation
To install the Image plugin:
Usage
Basic Usage
Options
| Option | Alias | Type | Default | Description |
|---|---|---|---|---|
--size <pixels> | -s | number | 150 | Thumbnail size (creates square) |
--output <path> | -o | string | - | Output file path (default: <input>-thumb.<ext>) |
--quality <quality> | -q | number | 85 | Output quality (1-100) |
--fit <mode> | string | cover | Fit mode: cover, contain, fill, inside, outside | |
--dry-run | boolean | false | Preview without making changes | |
--verbose | -v | boolean | false | Show detailed output |
--help | boolean | false | Display help information |
Common Thumbnail Sizes
| Size | Use Case |
|---|---|
| 32×32 | Tiny icons, favicons |
| 64×64 | Small icons, list views |
| 100×100 | Small thumbnails |
| 150×150 | Default thumbnail size |
| 200×200 | Medium thumbnails, profiles |
| 256×256 | Large thumbnails |
| 300×300 | Gallery previews |
| 512×512 | High-resolution icons, app icons |
| 1024×1024 | Extra large previews |
Fit Modes
cover (Default)
Fills entire thumbnail, crops if necessary:
mediaproc image thumbnail photo.jpg -s 200 --fit cover
Behavior:
- Fills entire 200×200 area
- Maintains aspect ratio
- Crops overflow
- Best for: Profile pictures, avatars, grid layouts
contain
Fits entire image with padding:
mediaproc image thumbnail landscape.jpg -s 200 --fit contain
Behavior:
- Shows complete image
- Adds padding if needed
- Maintains aspect ratio
- Best for: Product images, artwork, preserving full image
fill
Stretches to fill (may distort):
mediaproc image thumbnail image.jpg -s 200 --fit fill
Behavior:
- Fills entire area
- Ignores aspect ratio
- May distort image
- Best for: Rarely used (causes distortion)
inside
Shrinks if larger, never enlarges:
mediaproc image thumbnail big-image.jpg -s 200 --fit inside
Behavior:
- Shrinks large images
- Never enlarges small images
- Maintains aspect ratio
- Best for: Don't upscale small images
outside
Ensures minimum dimensions:
mediaproc image thumbnail photo.jpg -s 200 --fit outside
Behavior:
- Minimum 200×200 dimensions
- May exceed if aspect ratio requires
- Best for: Ensure minimum size
Examples
1. Default Thumbnail
Standard 150×150 thumbnail:
mediaproc image thumbnail photo.jpg
Output: photo-thumb.jpg (150×150)
2. Profile Picture
Avatar-sized thumbnail:
mediaproc image thumbnail profile.jpg -s 200 -o avatar.jpg
Social: 200×200 profile picture
3. Gallery Thumbnail
Medium-sized preview:
mediaproc image thumbnail artwork.png -s 300 -q 90
Gallery: 300×300 high-quality preview
4. Small Icon
Tiny icon size:
mediaproc image thumbnail logo.png -s 64 -o icon.png
Icon: 64×64 small icon
5. Large Preview
High-resolution thumbnail:
mediaproc image thumbnail photo.jpg -s 512 -q 95
Preview: 512×512 detailed preview
6. Product Thumbnail with Padding
Show complete product:
mediaproc image thumbnail product.jpg -s 300 --fit contain -o product-thumb.jpg
E-commerce: Full product visible with padding
7. Batch Gallery Thumbnails
Process entire gallery:
mediaproc image thumbnail "gallery/*.jpg" -s 250
Batch: Consistent gallery thumbnails
8. App Icon
iOS/Android app icon:
mediaproc image thumbnail app-icon.png -s 1024 -q 100 -o icon-1024.png
Apps: High-res app store icon
9. Favicon
Website favicon:
mediaproc image thumbnail logo.png -s 32 -o favicon.ico
Web: 32×32 favicon
10. Video Thumbnail
Video preview thumbnail:
mediaproc image thumbnail video-frame.jpg -s 320 --fit cover
Video: Video preview image
11. Preserve Small Images
Don't upscale small images:
mediaproc image thumbnail small-icon.png -s 200 --fit inside
Smart: Won't enlarge if already smaller
12. Social Media Profile
Instagram/Twitter profile size:
mediaproc image thumbnail profile.jpg -s 400 -q 90 -o social-profile.jpg
Social: Platform-ready profile picture
13. Verbose Processing
See dimensions change:
mediaproc image thumbnail photo.jpg -s 200 --verbose
Info: Shows original → thumbnail dimensions
14. Preview Batch
Check files before processing:
mediaproc image thumbnail "photos/*.jpg" -s 150 --dry-run
Safety: Verify file list
15. Contact Photo
Address book photo size:
mediaproc image thumbnail contact.jpg -s 180 --fit cover
Contacts: Contact card photo
Use Cases
1. Profile Pictures
Social media avatars:
# Standard profile picture
mediaproc image thumbnail profile.jpg -s 200 --fit cover -o avatar.jpg
# Multiple sizes
mediaproc image thumbnail profile.jpg -s 100 -o avatar-small.jpg
mediaproc image thumbnail profile.jpg -s 300 -o avatar-large.jpg
Social Media: Platform profile pictures
2. Gallery Previews
Image gallery thumbnails:
# Gallery thumbnails
mediaproc image thumbnail "gallery/*.jpg" -s 250 -q 85
# Consistent preview size
Galleries: Fast-loading previews
3. Product Images
E-commerce thumbnails:
# Product thumbnail with padding
mediaproc image thumbnail product.jpg -s 300 --fit contain
# Shows complete product
E-commerce: Product catalog thumbnails
4. Blog Post Previews
Article featured images:
# Blog preview
mediaproc image thumbnail article-image.jpg -s 400 --fit cover
# Consistent blog layout
Blogging: Article preview images
5. File Managers
File preview icons:
# File manager preview
mediaproc image thumbnail document.pdf -s 128
# Quick visual reference
File Systems: Visual file browsing
6. App Icons
Mobile/desktop app icons:
# iOS App Store icon
mediaproc image thumbnail app-icon.png -s 1024 -q 100
# Android icon sizes
mediaproc image thumbnail app-icon.png -s 512
Apps: Platform-specific icons
7. User Avatars
Forum/chat avatars:
# Chat avatar
mediaproc image thumbnail user.jpg -s 80 --fit cover
# Small, fast-loading
Communities: User identification
8. Video Thumbnails
Video preview images:
# YouTube-style thumbnail
mediaproc image thumbnail frame.jpg -s 320 --fit cover
# Video preview
Video: Video selection previews
9. Real Estate Listings
Property thumbnails:
# Property preview
mediaproc image thumbnail house.jpg -s 400 --fit cover
# Listing thumbnail
Real Estate: Property browsing
10. Portfolio Thumbnails
Artist/photographer portfolios:
# Portfolio grid
mediaproc image thumbnail "portfolio/*.jpg" -s 350
# Uniform grid layout
Portfolios: Professional presentations
Combining with Other Commands
Crop + Thumbnail
Smart crop before thumbnail:
# Smart crop to square
mediaproc image smart-crop photo.jpg -w 1000 -h 1000 -o square.jpg
# Then thumbnail
mediaproc image thumbnail square.jpg -s 300
Better Composition: Intelligent cropping
Optimize + Thumbnail
Create then optimize:
# Create thumbnail
mediaproc image thumbnail photo.jpg -s 200 -o thumb.jpg
# Further optimize
mediaproc image optimize thumb.jpg -q 80
Smaller Files: Extra compression
Batch Resize + Thumbnail
Multiple sizes from one source:
# Large version
mediaproc image resize photo.jpg -w 1920 -o large.jpg
# Medium version
mediaproc image resize photo.jpg -w 800 -o medium.jpg
# Thumbnail
mediaproc image thumbnail photo.jpg -s 200 -o thumb.jpg
Responsive: Multiple sizes for responsive design
Watermark + Thumbnail
Watermark before thumbnail:
# Add watermark
mediaproc image watermark photo.jpg --text "© 2024" -o marked.jpg
# Create thumbnail
mediaproc image thumbnail marked.jpg -s 300
Protection: Watermarked previews
Border + Thumbnail
Add border to thumbnails:
# Create thumbnail
mediaproc image thumbnail photo.jpg -s 200 -o thumb.jpg
# Add border
mediaproc image border thumb.jpg --width 2 --color white
Styling: Framed thumbnails
Technical Details
Thumbnail Generation
Process:
- Load source image
- Resize to size×size with specified fit mode
- Center position for cover mode
- Apply quality setting
- Save to output format
Fit Mode Behavior:
- cover: Resize to fill, crop excess (default)
- contain: Resize to fit, add padding
- fill: Stretch/squash to exact size
- inside: Shrink only, never enlarge
- outside: Ensure minimum dimensions
Performance
- Small thumbnails (64-150): ~30-60ms
- Medium thumbnails (200-300): ~50-100ms
- Large thumbnails (512+): ~100-200ms
- Batch processing: ~50-150ms per image
Quality vs Size
| Quality | File Size | Use Case |
|---|---|---|
| 70-75 | Smallest | Small thumbnails, file size critical |
| 80-85 | Small | Standard web thumbnails (default: 85) |
| 90-95 | Medium | High-quality previews |
| 100 | Largest | App icons, no compression |
Output Formats
- JPEG: Photos, default for .jpg
- PNG: Logos, transparency, default for .png
- WebP: Modern web, smaller sizes
- Format determined by output extension
Best Practices
1. Use Cover for Most Cases
Cover mode works best for uniform layouts:
# Default is best
mediaproc image thumbnail photo.jpg -s 200
2. Contain for Full Product Views
Show complete image for products:
# Full product visible
mediaproc image thumbnail product.jpg -s 300 --fit contain
3. Quality 85 is Optimal
Balance quality and size:
# Default quality is good
mediaproc image thumbnail photo.jpg -s 200 -q 85
4. Consistent Sizes in Batch
Use same size for related images:
# Uniform gallery
mediaproc image thumbnail "gallery/*.jpg" -s 250
5. Larger Source Images
Start with high-quality source:
# Better downscaling from large sources
# Original: 4000×3000
# Thumbnail: 300×300 (good quality)
6. Use PNG for Transparency
Preserve transparency:
# PNG preserves alpha
mediaproc image thumbnail logo.png -s 200 -o logo-thumb.png
7. Test Fit Modes
Compare cover vs contain:
# Try both
mediaproc image thumbnail image.jpg -s 200 --fit cover -o cover.jpg
mediaproc image thumbnail image.jpg -s 200 --fit contain -o contain.jpg
Troubleshooting
Issue: Image Cropped Too Much
Problem: Important parts cut off
Cause: Cover mode crops to fill
Solution: Use contain mode or smart-crop first
# Show full image
mediaproc image thumbnail photo.jpg -s 200 --fit contain
Issue: Image Has Padding
Problem: Unwanted borders around image
Cause: Contain mode with non-square source
Solution: Use cover mode or crop first
# Fill frame
mediaproc image thumbnail photo.jpg -s 200 --fit cover
Issue: Image Looks Distorted
Problem: Stretched or squashed
Cause: Using fill mode
Solution: Use cover or contain mode
# Proper aspect ratio
mediaproc image thumbnail photo.jpg -s 200 --fit cover
Issue: Thumbnail Too Large
Problem: File size too big
Cause: High quality setting or large size
Solution: Reduce quality or size
# Smaller file
mediaproc image thumbnail photo.jpg -s 200 -q 75
Issue: Small Image Upscaled
Problem: Small source image enlarged and pixelated
Cause: Default behavior enlarges
Solution: Use inside fit mode
# Don't upscale
mediaproc image thumbnail small.jpg -s 200 --fit inside
Issue: Blurry Thumbnail
Problem: Thumbnail lacks sharpness
Cause: Too much downscaling or low quality
Solution: Increase quality or sharpen after
# Higher quality
mediaproc image thumbnail photo.jpg -s 200 -q 95
# Or sharpen after
mediaproc image thumbnail photo.jpg -s 200 -o thumb.jpg
mediaproc image sharpen thumb.jpg -s 0.7
Related Commands
- resize - Resize to specific dimensions
- crop - Crop to specific area
- smart-crop - Content-aware cropping
- optimize - Further optimize thumbnails
- border - Add borders to thumbnails