# Watermark CLI Documentation

The `pm-media watermark` command allows you to add watermarks to images using either text or image overlays. This tool supports batch processing and offers extensive customization options for positioning, styling, and opacity.

## Table of Contents

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Text Watermarks](#text-watermarks)
- [Image Watermarks](#image-watermarks)
- [Command Line Options](#command-line-options)
- [API Usage](#api-usage)
- [Examples](#examples)
- [Troubleshooting](#troubleshooting)

## Installation

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

## Basic Usage

```bash
pm-media watermark --src <input> --dst <output> --watermarkType <type> [options]
```

### Required Parameters

- `--src`: Source files (FILE|FOLDER|GLOB pattern)
- `--watermarkType`: Type of watermark (`text` or `image`)

### Conditional Requirements

- For text watermarks: `--text` is required
- For image watermarks: `--logoPath` is required

## Text Watermarks

Add text overlays to your images with full typography control.

### Basic Text Watermark

```bash
pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType text \
  --text "© 2024 MyBrand"
```

### Advanced Text Styling

```bash
pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType text \
  --text "© 2024 MyBrand" \
  --position bottom-right \
  --fontSize 42 \
  --color "#ffffff" \
  --fontFamily "Arial" \
  --strokeColor "#000000" \
  --strokeWidth 3 \
  --opacity 0.9 \
  --margin 30
```

### Text Watermark Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--text` | string | required | Text to display as watermark |
| `--fontSize` | number | 48 | Font size in pixels |
| `--color` | string | "#ffffff" | Text color (hex format) |
| `--fontFamily` | string | "Arial" | Font family name |
| `--strokeColor` | string | "#000000" | Text outline color (hex format) |
| `--strokeWidth` | number | 2 | Text outline width in pixels |

## Image Watermarks

Add logo or image overlays with automatic scaling and positioning.

### Basic Image Watermark

```bash
# Using explicit options
pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType image \
  --logoPath "logo.png"

# Using shortcut option (recommended)
pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermark "logo.png"
```

### Advanced Image Positioning

```bash
pm-media watermark \
  --src "photos/*.jpg" \
  --dst "output/" \
  --watermarkType image \
  --logoPath "watermark.png" \
  --position top-left \
  --sizePct 0.15 \
  --opacity 0.7 \
  --margin 20
```

### Image Watermark Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--logoPath` | string | required | Path to logo/watermark image file (PNG, JPG, SVG) |
| `--watermark` | string | - | Shortcut: Path to watermark file (auto-sets type to image) |
| `--sizePct` | number | 0.2 | Size as percentage of base image width (0-1) |

## Command Line Options

### Common Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--src` | string | required | Source files (FILE\|FOLDER\|GLOB) |
| `--dst` | string | - | Destination path |
| `--watermarkType` | choice | required | "text" or "image" |
| `--position` | choice | "bottom-right" | Watermark position |
| `--margin` | number | 24 | Margin from edges in pixels |
| `--opacity` | number | 0.85 | Opacity level (0-1) |

### Position Options

- `top-left`: Upper left corner
- `top-right`: Upper right corner  
- `bottom-left`: Lower left corner
- `bottom-right`: Lower right corner (default)
- `center`: Center of image

### Utility Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--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 { 
  watermark, 
  addTextWatermark, 
  addLogoWatermark,
  WatermarkOptions,
  TextWatermarkOptions,
  LogoWatermarkOptions 
} from '@polymech/media';
```

### Text Watermark API

```typescript
import { addTextWatermark } from '@polymech/media';

await addTextWatermark(
  'input.jpg',
  '© 2024 MyBrand',
  'output.jpg',
  {
    position: 'bottom-right',
    fontSize: 48,
    color: '#ffffff',
    opacity: 0.9,
    margin: 24,
    fontFamily: 'Arial',
    strokeColor: '#000000',
    strokeWidth: 2
  }
);
```

### Image Watermark API

```typescript
import { addLogoWatermark } from '@polymech/media';

await addLogoWatermark(
  'input.jpg',
  'logo.png',
  'output.jpg',
  {
    position: 'bottom-right',
    sizePct: 0.2,
    opacity: 0.85,
    margin: 24,
    blend: 'over'
  }
);
```

### Batch Processing API

```typescript
import { watermark } from '@polymech/media';

const options: WatermarkOptions = {
  src: 'photos/*.jpg',
  dst: 'output/',
  watermarkType: 'text',
  text: '© 2024 MyBrand',
  textOptions: {
    position: 'bottom-right',
    fontSize: 48,
    color: '#ffffff',
    opacity: 0.9
  },
  // ... other IOptions
};

await watermark(options);
```

## Examples

### Example 1: Brand Photos with Logo

```bash
# Add company logo to product photos
pm-media watermark \
  --src "products/*.jpg" \
  --dst "branded/" \
  --watermarkType image \
  --logoPath "brand-logo.png" \
  --position bottom-right \
  --sizePct 0.12 \
  --opacity 0.8 \
  --margin 30
```

### Example 2: Copyright Text on Multiple Formats

```bash
# Add copyright to various image formats
pm-media watermark \
  --src "gallery/*.{jpg,png,webp}" \
  --dst "copyrighted/" \
  --watermarkType text \
  --text "© 2024 Photography Studio" \
  --position bottom-left \
  --fontSize 28 \
  --color "#ffffff" \
  --strokeColor "#000000" \
  --strokeWidth 1 \
  --opacity 0.85
```

### Example 3: Centered Watermark

```bash
# Large central watermark for draft images
pm-media watermark \
  --src "drafts/*.jpg" \
  --dst "review/" \
  --watermarkType text \
  --text "DRAFT - NOT FOR PUBLICATION" \
  --position center \
  --fontSize 72 \
  --color "#ff0000" \
  --opacity 0.3
```

### Example 4: Batch Processing with Dry Run

```bash
# Preview changes before applying
pm-media watermark \
  --src "archive/**/*.jpg" \
  --dst "processed/" \
  --watermarkType image \
  --logoPath "watermark.png" \
  --dry \
  --verbose
```

### Example 5: SVG Logo Watermarks

```bash
# High-quality SVG logo (recommended for logos)
pm-media watermark \
  --src "photos/*.jpg" \
  --dst "branded/" \
  --watermark "company-logo.svg" \
  --position top-right \
  --sizePct 0.12 \
  --opacity 0.9
```

### Example 6: Custom Logo Positioning

```bash
# Small logo in top-right corner
pm-media watermark \
  --src "social-media/*.png" \
  --dst "branded/" \
  --watermark "social-logo.svg" \
  --position top-right \
  --sizePct 0.08 \
  --margin 15 \
  --opacity 0.9
```

## File Format Support

### Supported Input Formats
- JPEG (.jpg, .jpeg)
- PNG (.png)
- WebP (.webp)
- TIFF (.tiff, .tif)

### Supported Watermark Formats
- **PNG** (.png) - With transparency support
- **JPEG** (.jpg, .jpeg) - Standard photos
- **SVG** (.svg) - **Recommended for logos** - Vector graphics with crisp scaling

### Supported Output Formats
Output format is automatically determined by the destination file extension or input format.

## SVG Watermarks (Recommended for Logos)

### Why Use SVG for Logos?

✅ **Advantages of SVG watermarks:**
- **Perfect Scaling**: Crisp at any size (vector graphics)
- **Small File Size**: Compact file size for better performance  
- **Professional Quality**: No pixelation or quality loss
- **Transparency Support**: Clean integration with photos
- **Color Flexibility**: Easy to modify colors in the SVG file

### SVG Usage Examples

```bash
# Company logo watermark
pm-media watermark \
  --src "products/*.jpg" \
  --dst "catalog/" \
  --watermark "brand-logo.svg" \
  --sizePct 0.15

# Copyright watermark with custom positioning  
pm-media watermark \
  --src "portfolio/*.jpg" \
  --dst "watermarked/" \
  --watermark "copyright-symbol.svg" \
  --position bottom-left \
  --sizePct 0.08 \
  --opacity 0.7
```

### Creating SVG Watermarks

1. **Design Tools**: Use Inkscape, Adobe Illustrator, or Figma
2. **Keep Simple**: Avoid complex gradients for best performance
3. **Optimize Size**: Remove unnecessary elements and metadata
4. **Test Scaling**: Ensure logo looks good at different sizes

## Performance Tips

1. **Batch Processing**: Process multiple files in one command for better performance
2. **Concurrency**: The tool processes files with controlled concurrency (default: 1)
3. **Logo Optimization**: Use SVG for logos, PNG for complex images with transparency
4. **Size Optimization**: Keep logo files reasonably sized to improve processing speed

## Troubleshooting

### Common Issues

#### "Logo file not found"
```bash
# Ensure the logo path is correct and file exists
ls -la path/to/logo.png
```

#### "Unable to open for write"
```bash
# Ensure output directory exists
mkdir -p output/directory
```

#### Text appears blurry
- Increase `--fontSize` for better clarity
- Adjust `--strokeWidth` for better contrast
- Use appropriate `--color` contrast against background

#### Logo appears too large/small
- Adjust `--sizePct` (0.1 = 10% of image width)
- Consider image dimensions when setting size

### Debug Mode

Enable detailed logging to troubleshoot issues:

```bash
pm-media watermark \
  --src "input/*" \
  --dst "output/" \
  --watermarkType text \
  --text "Debug Test" \
  --debug \
  --verbose
```

### File Permissions

Ensure you have:
- Read access to source files
- Write access to destination directory
- Execute permissions on the tool

## Advanced Usage

### Using Environment Variables

```bash
export WATERMARK_TEXT="© 2024 MyCompany"
export WATERMARK_LOGO="./assets/logo.png"

pm-media watermark \
  --src "batch/*.jpg" \
  --dst "output/" \
  --watermarkType text \
  --text "$WATERMARK_TEXT"
```

### Integration with Scripts

```bash
#!/bin/bash
# Automated watermarking script

INPUT_DIR="$1"
OUTPUT_DIR="$2"
WATERMARK_TYPE="$3"

if [ "$WATERMARK_TYPE" = "logo" ]; then
  pm-media watermark \
    --src "$INPUT_DIR/*.jpg" \
    --dst "$OUTPUT_DIR/" \
    --watermarkType image \
    --logoPath "./branding/logo.png" \
    --position bottom-right
else
  pm-media watermark \
    --src "$INPUT_DIR/*.jpg" \
    --dst "$OUTPUT_DIR/" \
    --watermarkType text \
    --text "© $(date +%Y) MyBrand" \
    --position bottom-right
fi
```

## TypeScript Definitions

```typescript
type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center";

interface LogoWatermarkOptions {
  position?: Corner;
  margin?: number;
  sizePct?: number;
  opacity?: number;
  blend?: OverlayOptions["blend"];
}

interface TextWatermarkOptions {
  position?: Corner;
  margin?: number;
  fontSize?: number;
  opacity?: number;
  color?: string;
  fontFamily?: string;
  strokeColor?: string;
  strokeWidth?: number;
}

interface WatermarkOptions extends IOptions {
  watermarkType: 'text' | 'image';
  text?: string;
  textOptions?: TextWatermarkOptions;
  logoPath?: string;
  imageOptions?: LogoWatermarkOptions;
}
```

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