babayaga 207cb53f6f media : background | watermark

2025-08-11 12:25:45 +02:00

12 KiB

Raw Blame History

Resize CLI Documentation

The pm-media resize command allows you to resize images with precise control over dimensions, quality, and performance. This tool supports batch processing and offers extensive options for scaling, cropping, and format conversion.

Installation
Basic Usage
Resize Methods
Command Line Options
API Usage
Examples
Performance Options
Troubleshooting

Installation

npm install @polymech/media

Basic Usage

pm-media resize --src <input> --dst <output> [resize-options]

Required Parameters

--src: Source files (FILE|FOLDER|GLOB pattern)

Optional Parameters

--dst: Destination path (defaults to source location)

Resize Methods

1. Percentage-based Resizing

Resize images by a percentage of their original size:

pm-media resize \
  --src "photos/*.jpg" \
  --dst "thumbnails/" \
  --percent 50

2. Fixed Width/Height

Resize to specific dimensions:

pm-media resize \
  --src "photos/*.jpg" \
  --dst "resized/" \
  --width 800 \
  --height 600

3. Width-only or Height-only

Maintain aspect ratio with one dimension:

# Resize to 1920px width, auto height
pm-media resize \
  --src "photos/*.jpg" \
  --dst "web/" \
  --width 1920

# Resize to 1080px height, auto width  
pm-media resize \
  --src "photos/*.jpg" \
  --dst "web/" \
  --height 1080

Command Line Options

Resize Dimensions

Option	Type	Default	Description
`--width`	number	-	Target width in pixels
`--height`	number	-	Target height in pixels
`--percent`	number	-	Resize by percentage (1-100)

Minimum Size Constraints

Option	Type	Default	Description
`--minWidth`	number	-	Don't resize if width below this value
`--minHeight`	number	-	Don't resize if height below this value
`--minSize`	number	-	Don't resize if file size below this (bytes)

Sharp-specific Options

Option	Type	Default	Description
`--fit`	string	'cover'	How to fit: cover, contain, fill, inside, outside
`--position`	string	'centre'	Position when using fit: top, bottom, left, right, etc
`--background`	string	'white'	Background color for contain/letterbox
`--withoutEnlargement`	boolean	false	Don't enlarge smaller images
`--withoutReduction`	boolean	false	Don't reduce larger images
`--fastShrinkOnLoad`	boolean	true	Use JPEG/WebP shrink-on-load

Common Options

Option	Type	Default	Description
`--src`	string	required	Source files (FILE\|FOLDER\|GLOB)
`--dst`	string	-	Destination path
`--dry`	boolean	false	Preview mode (no files written)
`--verbose`	boolean	false	Show detailed processing info
`--debug`	boolean	false	Enable debug messages
`--logLevel`	string	"info"	Log level (warn\|info\|debug\|error)

API Usage

Import the Library

import { 
  resize, 
  resizeFile,
  IResizeOptions 
} from '@polymech/media';

Single File Resize

import { resizeFile } from '@polymech/media';

// Resize by percentage
await resizeFile(
  'input.jpg',
  'output.jpg', 
  () => {}, // onNode callback
  {
    percent: 50,
    logLevel: 'info'
  }
);

// Resize to specific dimensions
await resizeFile(
  'input.jpg',
  'thumbnail.jpg',
  () => {},
  {
    width: 300,
    height: 300,
    fit: 'cover',
    withoutEnlargement: true
  }
);

Batch Resize API

import { resize } from '@polymech/media';

const options: IResizeOptions = {
  src: 'photos/*.jpg',
  dst: 'resized/',
  width: 1920,
  height: 1080,
  fit: 'inside',
  withoutEnlargement: true,
  // ... other IOptions
};

const results = await resize(options);

Advanced Resize Options

const advancedOptions: IResizeOptions = {
  src: 'raw/*.tiff',
  dst: 'processed/',
  width: 2048,
  height: 1536,
  fit: 'cover',
  position: 'center',
  background: { r: 255, g: 255, b: 255, alpha: 1 },
  withoutEnlargement: true,
  fastShrinkOnLoad: true,
  kernel: 'lanczos3'
};

Examples

Example 1: Create Thumbnails

# Generate 150px square thumbnails
pm-media resize \
  --src "gallery/*.jpg" \
  --dst "thumbs/" \
  --width 150 \
  --height 150 \
  --fit cover \
  --withoutEnlargement

Example 2: Web Optimization

# Optimize for web (max 1920px width)
pm-media resize \
  --src "photos/*.jpg" \
  --dst "web-optimized/" \
  --width 1920 \
  --minWidth 800 \
  --fit inside \
  --withoutEnlargement

Example 3: Percentage-based Batch Resize

# Reduce all images to 75% of original size
pm-media resize \
  --src "archive/**/*.{jpg,png}" \
  --dst "compressed/" \
  --percent 75

# Instagram square format (1080x1080)
pm-media resize \
  --src "photos/*.jpg" \
  --dst "instagram/" \
  --width 1080 \
  --height 1080 \
  --fit cover \
  --position center

# Twitter header (1500x500)
pm-media resize \
  --src "headers/*.jpg" \
  --dst "twitter/" \
  --width 1500 \
  --height 500 \
  --fit cover

Example 5: Preserve Small Images

# Don't resize images smaller than 500px width
pm-media resize \
  --src "mixed/*.jpg" \
  --dst "standardized/" \
  --width 1200 \
  --minWidth 500 \
  --withoutEnlargement

Example 6: File Size Based Resize

# Only resize files larger than 2MB
pm-media resize \
  --src "large/*.jpg" \
  --dst "optimized/" \
  --percent 60 \
  --minSize 2097152

Example 7: Format Conversion with Resize

# Resize and convert to WebP
pm-media resize \
  --src "photos/*.jpg" \
  --dst "webp/{SRC_NAME}.webp" \
  --width 1920 \
  --fit inside

Fit Options Explained

`cover` (default)

Crop to fill exact dimensions
Maintains aspect ratio
May crop parts of the image

pm-media resize --src input.jpg --dst output.jpg --width 800 --height 600 --fit cover

`contain`

Letterbox to fit within dimensions
Maintains aspect ratio
No cropping, adds background

pm-media resize --src input.jpg --dst output.jpg --width 800 --height 600 --fit contain --background white

`fill`

Stretch to exact dimensions
Does not maintain aspect ratio
No cropping

pm-media resize --src input.jpg --dst output.jpg --width 800 --height 600 --fit fill

`inside`

Resize to fit within dimensions
Maintains aspect ratio
May result in smaller dimensions

pm-media resize --src input.jpg --dst output.jpg --width 800 --height 600 --fit inside

`outside`

Resize to cover dimensions
Maintains aspect ratio
May result in larger dimensions

pm-media resize --src input.jpg --dst output.jpg --width 800 --height 600 --fit outside

Position Options

When using fit: cover or fit: contain, control crop/letterbox position:

center (default)
top, bottom, left, right
top left, top right, bottom left, bottom right
north, south, east, west
northeast, northwest, southeast, southwest

pm-media resize \
  --src portrait.jpg \
  --dst cropped.jpg \
  --width 800 \
  --height 600 \
  --fit cover \
  --position "top center"

File Format Support

Supported Input Formats

JPEG (.jpg, .jpeg)
PNG (.png)
WebP (.webp)
TIFF (.tiff, .tif)
AVIF (.avif)
SVG (.svg) - rasterized
GIF (.gif) - first frame

Supported Output Formats

Output format determined by destination file extension:

.jpg, .jpeg → JPEG
.png → PNG
.webp → WebP
.tiff, .tif → TIFF
.avif → AVIF

Performance Tips

1. Fast Shrink-on-Load

# Use JPEG/WebP built-in scaling (faster for large reductions)
pm-media resize \
  --src "huge/*.jpg" \
  --dst "thumbnails/" \
  --width 300 \
  --fastShrinkOnLoad

2. Batch Processing

# Process multiple files efficiently
pm-media resize --src "batch/*.jpg" --dst "output/" --percent 50

3. Prevent Unnecessary Enlargement

# Don't enlarge small images (saves processing time)
pm-media resize \
  --src "mixed/*.jpg" \
  --dst "standardized/" \
  --width 1920 \
  --withoutEnlargement

4. Size-based Processing

# Only process large files
pm-media resize \
  --src "photos/*.jpg" \
  --dst "compressed/" \
  --percent 70 \
  --minSize 1048576  # 1MB minimum

Troubleshooting

Common Issues

Images appear distorted

# Maintain aspect ratio with 'inside' or 'cover'
pm-media resize --src input.jpg --dst output.jpg --width 800 --height 600 --fit inside

Small images getting enlarged

# Prevent enlargement
pm-media resize --src input.jpg --dst output.jpg --width 1920 --withoutEnlargement

Poor quality on large reductions

# Use better kernel for quality
pm-media resize --src input.jpg --dst output.jpg --percent 25 --kernel lanczos3

Memory issues with large files

# Use fast shrink for initial reduction
pm-media resize --src huge.jpg --dst smaller.jpg --percent 50 --fastShrinkOnLoad

Debug Mode

Enable detailed logging:

pm-media resize \
  --src "input/*" \
  --dst "output/" \
  --width 800 \
  --debug \
  --verbose

File Permissions

Ensure you have:

Read access to source files
Write access to destination directory
Sufficient disk space for output files

Advanced Usage

Template Variables

Use template variables in destination paths:

# Use source filename in destination
pm-media resize \
  --src "photos/*.jpg" \
  --dst "resized/{SRC_NAME}_resized.jpg" \
  --width 1200

Available variables:

{SRC_NAME}: Source filename without extension
{SRC_EXT}: Source file extension
{SRC_DIR}: Source directory

Integration Scripts

#!/bin/bash
# Multi-size generation script

SIZES=(300 600 1200 1920)
INPUT_DIR="$1"
OUTPUT_BASE="$2"

for size in "${SIZES[@]}"; do
  pm-media resize \
    --src "$INPUT_DIR/*.jpg" \
    --dst "$OUTPUT_BASE/${size}px/" \
    --width $size \
    --withoutEnlargement \
    --fit inside
done

Conditional Processing

#!/bin/bash
# Only resize if source is larger than target

if [ -f "$1" ]; then
  pm-media resize \
    --src "$1" \
    --dst "$2" \
    --width 1920 \
    --minWidth 1920 \
    --withoutEnlargement
fi

TypeScript Definitions

interface IResizeOptionsSharp {
  width?: number;
  height?: number;
  fit?: keyof sharp.FitEnum;
  position?: number | string;
  background?: sharp.Color;
  kernel?: keyof sharp.KernelEnum;
  withoutEnlargement?: boolean;
  withoutReduction?: boolean;
  fastShrinkOnLoad?: boolean;
}

interface IResizeOptions extends IOptions, IResizeOptionsSharp {
  percent?: number;
  minWidth?: number;
  minHeight?: number;
  minSize?: number;
}

Contributing

For bug reports, feature requests, or contributions, please visit the project repository.

License

This tool is part of the @polymech/media package. Please refer to the package license for usage terms.

12 KiB Raw Blame History