babayaga e7faf3ea02 pmedia : remove bg | crop

2025-08-10 15:56:47 +02:00

12 KiB

Raw Blame History

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.

Installation
Basic Usage
Text Watermarks
Image Watermarks
Command Line Options
API Usage
Examples
Troubleshooting

Installation

npm install @polymech/media

Basic Usage

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

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

Advanced Text Styling

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

# 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

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

import { 
  watermark, 
  addTextWatermark, 
  addLogoWatermark,
  WatermarkOptions,
  TextWatermarkOptions,
  LogoWatermarkOptions 
} from '@polymech/media';

Text Watermark API

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

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

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

# 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

# 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

# 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

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

Example 5: SVG Logo Watermarks

# 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

# 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

# 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

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

Performance Tips

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

Troubleshooting

Common Issues

"Logo file not found"

# Ensure the logo path is correct and file exists
ls -la path/to/logo.png

"Unable to open for write"

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

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

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

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

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.

12 KiB Raw Blame History