510 lines
12 KiB
Markdown
510 lines
12 KiB
Markdown
# 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.
|