mono/packages/media/docs/cli-resize.md

# 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.

## Table of Contents

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Resize Methods](#resize-methods)
- [Command Line Options](#command-line-options)
- [API Usage](#api-usage)
- [Examples](#examples)
- [Performance Options](#performance-options)
- [Troubleshooting](#troubleshooting)

## Installation

```bash
npm install @polymech/media
```

## Basic Usage

```bash
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:

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

### 2. Fixed Width/Height

Resize to specific dimensions:

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

### 3. Width-only or Height-only

Maintain aspect ratio with one dimension:

```bash
# 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

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

### Single File Resize

```typescript
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

```typescript
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

```typescript
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

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

### Example 2: Web Optimization

```bash
# 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

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

### Example 4: Social Media Formats

```bash
# 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

```bash
# 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

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

### Example 7: Format Conversion with Resize

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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`

```bash
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
```bash
# Use JPEG/WebP built-in scaling (faster for large reductions)
pm-media resize \
  --src "huge/*.jpg" \
  --dst "thumbnails/" \
  --width 300 \
  --fastShrinkOnLoad
```

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

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

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

## Troubleshooting

### Common Issues

#### Images appear distorted
```bash
# 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
```bash
# Prevent enlargement
pm-media resize --src input.jpg --dst output.jpg --width 1920 --withoutEnlargement
```

#### Poor quality on large reductions
```bash
# Use better kernel for quality
pm-media resize --src input.jpg --dst output.jpg --percent 25 --kernel lanczos3
```

#### Memory issues with large files
```bash
# Use fast shrink for initial reduction
pm-media resize --src huge.jpg --dst smaller.jpg --percent 50 --fastShrinkOnLoad
```

### Debug Mode

Enable detailed logging:

```bash
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:

```bash
# 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

```bash
#!/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

```bash
#!/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

```typescript
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.