composite

Overlay/composite one image on top of another with precise positioning and blend modes.

Usage

Terminal
$ mediaproc image composite <input> --overlay <overlay> [options]

Description

The composite command layers one image (overlay) on top of another (base image) with precise control over positioning, blend modes, opacity, and tiling. This is perfect for:

  • Watermarking: Add copyright or brand logos
  • Overlays: Layer graphics, badges, or icons
  • Textures: Apply texture overlays with blend modes
  • Creative compositions: Combine multiple images artistically
  • Branding: Add consistent visual elements across images

The command supports various positioning strategies (gravity-based or exact coordinates), multiple blend modes for different effects, and can tile patterns across the entire image.

Options

OptionTypeDefaultDescription
<input>stringrequiredBase input image file path
--overlaystringrequiredOverlay image file path to composite on top
-o, --outputstring<input>_composite.<ext>Output file path
--gravitystringcenterPosition: center, north, south, east, west, northeast, northwest, southeast, southwest
--blendstringoverBlend mode: over, multiply, screen, overlay, darken, lighten, add, saturate, etc.
--leftnumber(none)X position in pixels (overrides gravity)
--topnumber(none)Y position in pixels (overrides gravity)
--opacitynumber1Overlay opacity 0-1 (0 = transparent, 1 = opaque)
--tilebooleanfalseTile the overlay across the entire image
--dry-runbooleanfalseShow what would be done without processing
-v, --verbosebooleanfalseEnable verbose logging

Examples

Basic Watermarking

Add watermarks to images:

# Add watermark to bottom-right
mediaproc image composite photo.jpg --overlay watermark.png --gravity southeast -o watermarked.jpg

# Center watermark
mediaproc image composite image.jpg --overlay logo.png --gravity center -o branded.jpg

# Top-left watermark
mediaproc image composite photo.jpg --overlay logo.png --gravity northwest -o marked.jpg

# Bottom-center watermark
mediaproc image composite picture.jpg --overlay copyright.png --gravity south -o protected.jpg

Opacity Control

Create semi-transparent overlays:

# 50% transparent watermark
mediaproc image composite photo.jpg --overlay watermark.png --opacity 0.5 -o subtle.jpg

# Very subtle overlay (20%)
mediaproc image composite image.jpg --overlay logo.png --opacity 0.2 -o light_brand.jpg

# 70% transparent
mediaproc image composite photo.jpg --overlay overlay.png --opacity 0.3 -o semi_visible.jpg

# Nearly opaque (90%)
mediaproc image composite image.jpg --overlay badge.png --opacity 0.9 -o strong.jpg

Exact Positioning

Position overlays at precise coordinates:

# Position at 50,50 pixels from top-left
mediaproc image composite image.jpg --overlay badge.png --left 50 --top 50 -o positioned.jpg

# Bottom-right corner with 20px padding
mediaproc image composite photo.jpg --overlay logo.png --left -70 --top -70 -o corner.jpg

# Center-left side
mediaproc image composite image.jpg --overlay icon.png --left 20 --top 300 -o sidebar.jpg

# Custom grid position
mediaproc image composite photo.jpg --overlay element.png --left 200 --top 150 -o custom.jpg

Blend Modes

Apply different blend modes for creative effects:

# Multiply blend (darkens, great for textures)
mediaproc image composite bg.jpg --overlay texture.png --blend multiply -o textured.jpg

# Screen blend (lightens, great for glow effects)
mediaproc image composite dark.jpg --overlay light.png --blend screen -o brightened.jpg

# Overlay blend (combination of multiply and screen)
mediaproc image composite image.jpg --overlay pattern.png --blend overlay -o blended.jpg

# Darken (keep darker of two colors)
mediaproc image composite photo.jpg --overlay shadow.png --blend darken -o darkened.jpg

# Lighten (keep lighter of two colors)
mediaproc image composite image.jpg --overlay highlight.png --blend lighten -o lightened.jpg

# Add (adds pixel values together)
mediaproc image composite base.jpg --overlay glow.png --blend add -o glowing.jpg

# Saturate (increase color intensity)
mediaproc image composite photo.jpg --overlay color.png --blend saturate -o vibrant.jpg

Tiling Patterns

Tile overlays across entire image:

# Tile pattern across image
mediaproc image composite photo.jpg --overlay pattern.png --tile -o patterned.jpg

# Tile with opacity for subtle effect
mediaproc image composite image.jpg --overlay texture.png --tile --opacity 0.3 -o textured.jpg

# Tile with multiply blend
mediaproc image composite bg.jpg --overlay tile.png --tile --blend multiply -o tiled_dark.jpg

# Tile watermark pattern
mediaproc image composite photo.jpg --overlay watermark_tile.png --tile --opacity 0.1 -o protected.jpg

Combining Options

Use multiple options together:

# Semi-transparent watermark at bottom-right
mediaproc image composite photo.jpg \
  --overlay watermark.png \
  --gravity southeast \
  --opacity 0.5 \
  -o watermarked.jpg

# Multiply blend texture with opacity
mediaproc image composite image.jpg \
  --overlay texture.png \
  --blend multiply \
  --opacity 0.6 \
  -o textured.jpg

# Precise position with custom opacity
mediaproc image composite photo.jpg \
  --overlay badge.png \
  --left 100 \
  --top 100 \
  --opacity 0.8 \
  -o badge_added.jpg

# Tiled pattern with screen blend
mediaproc image composite dark_bg.jpg \
  --overlay light_pattern.png \
  --tile \
  --blend screen \
  --opacity 0.4 \
  -o glowing_pattern.jpg

Batch Processing

Watermark multiple images:

# Watermark entire photo collection
for file in photos/*.jpg; do
  mediaproc image composite "$file" \
    --overlay watermark.png \
    --gravity southeast \
    --opacity 0.5 \
    -o "watermarked/${file##*/}"
done

# Add logo to all images
for file in images/*.png; do
  mediaproc image composite "$file" \
    --overlay logo.png \
    --gravity northwest \
    -o "branded/${file##*/}"
done

# Apply texture to multiple images
for file in photos/*.jpg; do
  mediaproc image composite "$file" \
    --overlay texture.png \
    --blend multiply \
    --opacity 0.3 \
    -o "textured/${file##*/}"
done

Creative Effects

Advanced creative compositions:

# Vintage film grain effect
mediaproc image composite photo.jpg \
  --overlay film_grain.png \
  --tile \
  --blend overlay \
  --opacity 0.15 \
  -o vintage.jpg

# Light leak effect
mediaproc image composite image.jpg \
  --overlay light_leak.png \
  --blend screen \
  --opacity 0.6 \
  --gravity northeast \
  -o light_leak_effect.jpg

# Dust and scratches overlay
mediaproc image composite photo.jpg \
  --overlay dust.png \
  --blend darken \
  --opacity 0.2 \
  -o aged.jpg

# Bokeh overlay
mediaproc image composite portrait.jpg \
  --overlay bokeh.png \
  --blend screen \
  --opacity 0.4 \
  -o dreamy.jpg

Logo Placement Variations

Different logo positioning strategies:

# Top-left corner
mediaproc image composite image.jpg --overlay logo.png --gravity northwest -o tl_logo.jpg

# Top-right corner
mediaproc image composite image.jpg --overlay logo.png --gravity northeast -o tr_logo.jpg

# Bottom-left corner
mediaproc image composite image.jpg --overlay logo.png --gravity southwest -o bl_logo.jpg

# Bottom-right corner
mediaproc image composite image.jpg --overlay logo.png --gravity southeast -o br_logo.jpg

# Centered
mediaproc image composite image.jpg --overlay logo.png --gravity center -o centered_logo.jpg

# Top center
mediaproc image composite image.jpg --overlay logo.png --gravity north -o tc_logo.jpg

Professional Watermarking

Professional watermark strategies:

# Diagonal tiled watermark
mediaproc image composite photo.jpg \
  --overlay watermark_diagonal.png \
  --tile \
  --opacity 0.08 \
  -o protected.jpg

# Corner watermark with high opacity
mediaproc image composite image.jpg \
  --overlay copyright.png \
  --gravity southeast \
  --opacity 0.7 \
  -o copyrighted.jpg

# Center watermark with low opacity (for proofs)
mediaproc image composite photo.jpg \
  --overlay proof.png \
  --gravity center \
  --opacity 0.3 \
  -o proof.jpg

Dry Run Testing

Test composite operations:

# Test gravity positioning
mediaproc image composite image.jpg --overlay logo.png --gravity southeast --dry-run

# Test exact positioning
mediaproc image composite image.jpg --overlay badge.png --left 100 --top 100 --dry-run

# Test blend mode and opacity
mediaproc image composite image.jpg --overlay texture.png --blend multiply --opacity 0.5 --dry-run

# Test tiling
mediaproc image composite image.jpg --overlay pattern.png --tile --dry-run

Verbose Processing

Monitor composite operations:

# See detailed processing information
mediaproc image composite photo.jpg \
  --overlay watermark.png \
  --gravity southeast \
  --opacity 0.5 \
  -v \
  -o watermarked.jpg

# Debug positioning and blend mode
mediaproc image composite image.jpg \
  --overlay texture.png \
  --blend multiply \
  -v \
  -o textured.jpg

Blend Modes Explained

over (default)

Standard overlay - places overlay image on top of base image.

Use for:

  • Watermarks
  • Logos
  • Standard overlays
  • PNG images with transparency

Example:

mediaproc image composite photo.jpg --overlay watermark.png --blend over -o standard.jpg

multiply

Multiplies pixel values - darkens the image.

Use for:

  • Adding textures
  • Creating shadow effects
  • Darkening specific areas
  • Vintage looks

Example:

mediaproc image composite image.jpg --overlay texture.png --blend multiply --opacity 0.4 -o textured.jpg

screen

Inverts, multiplies, inverts again - lightens the image.

Use for:

  • Glow effects
  • Light leaks
  • Brightening
  • Dreamy effects

Example:

mediaproc image composite dark.jpg --overlay light.png --blend screen --opacity 0.6 -o brightened.jpg

overlay

Combination of multiply and screen based on base color.

Use for:

  • Balanced blending
  • Preserving highlights and shadows
  • General compositing
  • Color grading

Example:

mediaproc image composite photo.jpg --overlay color_grade.png --blend overlay --opacity 0.5 -o graded.jpg

darken

Keeps the darker of the two colors.

Use for:

  • Shadow overlays
  • Darkening effects
  • Preserving dark details

Example:

mediaproc image composite image.jpg --overlay shadow.png --blend darken -o darkened.jpg

lighten

Keeps the lighter of the two colors.

Use for:

  • Highlight overlays
  • Lightening effects
  • Preserving bright details

Example:

mediaproc image composite photo.jpg --overlay highlight.png --blend lighten -o lightened.jpg

add

Adds pixel values together (may clip at maximum).

Use for:

  • Glow effects
  • Light addition
  • Bright overlays
  • Special effects

Example:

mediaproc image composite dark_scene.jpg --overlay glow.png --blend add --opacity 0.7 -o glowing.jpg

saturate

Increases color intensity where overlay and base overlap.

Use for:

  • Color enhancement
  • Vibrant effects
  • Selective saturation

Example:

mediaproc image composite photo.jpg --overlay color_boost.png --blend saturate --opacity 0.4 -o vibrant.jpg

Gravity Positions Reference

Gravity Options

  • center: Center of image (default)
  • north: Top center
  • south: Bottom center
  • east: Right center
  • west: Left center
  • northeast: Top-right corner
  • northwest: Top-left corner
  • southeast: Bottom-right corner
  • southwest: Bottom-left corner

Visual Guide

northwest north northeast ┌──────────────┐ west│ center │east └──────────────┘ southwest south southeast

Best Practices

  1. Watermarking:

    • Use PNG overlays with transparency
    • Position in corners (southeast common)
    • Use 0.3-0.7 opacity for subtlety
    • Consider --tile with low opacity for full protection

  2. Blend Mode Selection:

    • Start with over for standard overlays
    • Use multiply for textures and darkening
    • Use screen for glows and lightening
    • overlay for balanced blending

  3. Opacity Guidelines:

    • 0.1-0.3: Very subtle, background effects
    • 0.3-0.5: Watermarks, subtle overlays
    • 0.5-0.7: Visible but not dominant
    • 0.7-1.0: Strong, prominent overlays

  4. Performance:

    • Overlay image is loaded once for batch processing
    • Use appropriate overlay sizes (don't use massive files)
    • PNG format best for transparency preservation

  5. Quality Preservation:

    • Use high-quality overlay images
    • Match overlay and base image quality levels
    • Save in appropriate format (PNG for transparency)

  6. Positioning:

    • Use gravity for dynamic positioning
    • Use --left/--top for precise pixel placement
    • Consider different screen sizes for web watermarks

  7. Batch Consistency:

    • Use same overlay and parameters for consistency
    • Maintain watermark quality across all images
    • Test on sample images first

Common Use Cases

Brand Watermarking

# Add company logo to all product photos
for photo in products/*.jpg; do
  mediaproc image composite "$photo" \
    --overlay company_logo.png \
    --gravity southeast \
    --opacity 0.6 \
    -o "branded/${photo##*/}"
done

Photography Portfolio Protection

# Add copyright to portfolio images
for image in portfolio/*.jpg; do
  mediaproc image composite "$image" \
    --overlay copyright.png \
    --gravity south \
    --opacity 0.5 \
    -o "watermarked/${image##*/}"
done

Texture Overlay for Artistic Effect

# Apply film grain texture
mediaproc image composite photo.jpg \
  --overlay film_grain.png \
  --tile \
  --blend overlay \
  --opacity 0.2 \
  -o vintage_film.jpg

Social Media Branding

# Add profile logo to social media images
mediaproc image composite post.jpg \
  --overlay profile_badge.png \
  --gravity northwest \
  --left 20 \
  --top 20 \
  --opacity 0.9 \
  -o branded_post.jpg

Real Estate Watermarking

# Add agency branding to property photos
for listing in listings/*.jpg; do
  mediaproc image composite "$listing" \
    --overlay agency_watermark.png \
    --gravity southeast \
    --opacity 0.4 \
    -o "watermarked/${listing##*/}"
done

Performance Tips

  1. Overlay Optimization: The overlay image is loaded and prepared once, then applied to all base images in batch mode
  2. Size Matching: Resize overlay to appropriate size before compositing for better performance
  3. Format Selection: PNG best for overlays with transparency; JPEG for opaque overlays
  4. Batch Efficiency: Process similar images together with same overlay parameters
  5. Memory Usage: Large overlay images consume more memory; optimize overlay size first

Troubleshooting

Overlay Not Visible

Problem: Overlay doesn't appear on output.

Solutions:

# Check if overlay file exists
ls -lh watermark.png

# Increase opacity
mediaproc image composite image.jpg --overlay logo.png --opacity 1 -o visible.jpg

# Try different blend mode
mediaproc image composite image.jpg --overlay logo.png --blend over -o standard.jpg

# Check with verbose mode
mediaproc image composite image.jpg --overlay logo.png -v -o test.jpg

Overlay in Wrong Position

Problem: Overlay positioned incorrectly.

Solutions:

# Use different gravity
mediaproc image composite image.jpg --overlay logo.png --gravity southeast -o corner.jpg

# Use exact coordinates
mediaproc image composite image.jpg --overlay logo.png --left 50 --top 50 -o positioned.jpg

# Test with dry-run first
mediaproc image composite image.jpg --overlay logo.png --gravity center --dry-run

Overlay Too Prominent

Problem: Overlay dominates the image.

Solutions:

# Reduce opacity
mediaproc image composite photo.jpg --overlay watermark.png --opacity 0.3 -o subtle.jpg

# Use different blend mode
mediaproc image composite photo.jpg --overlay texture.png --blend multiply --opacity 0.4 -o soft.jpg

# Reduce overlay image size/contrast before compositing

Overlay Quality Loss

Problem: Overlay looks pixelated or low quality.

Solutions:

# Use PNG format for overlay (not JPEG)
# Ensure overlay is high resolution
# Avoid scaling up small overlays

# Use high-quality overlay image
mediaproc image composite image.jpg --overlay high_res_logo.png -o quality.jpg

Batch Processing Inconsistencies

Problem: Overlays look different across batch.

Solutions:

# Use consistent parameters
OVERLAY_PARAMS="--overlay logo.png --gravity southeast --opacity 0.5"
for file in *.jpg; do
  mediaproc image composite "$file" $OVERLAY_PARAMS -o "processed/${file}"
done

# Ensure all base images are similar dimensions
# Normalize images first if needed

Tiling Creates Seams

Problem: Visible seams when tiling overlay.

Solutions:

# Use seamless tiling pattern
# Reduce opacity to minimize visibility
mediaproc image composite image.jpg --overlay pattern.png --tile --opacity 0.2 -o subtle_tile.jpg

# Create seamless overlay pattern first (in external tool)

Overlay File Not Found

Problem: Error: "Overlay file not found".

Solutions:

# Check file path
ls -lh path/to/overlay.png

# Use absolute path
mediaproc image composite image.jpg --overlay /full/path/to/watermark.png -o output.jpg

# Verify file exists and is readable
file overlay.png

See Also

  • watermark - Specialized watermarking command
  • flatten - Flatten alpha channel before compositing
  • extend - Add padding/borders before overlays
  • crop - Crop before/after compositing
  • resize - Resize base or overlay images
  • rotate - Rotate overlay before compositing
  • flip - Flip overlay before compositing

Found an issue? Help us improve this page.

Edit on GitHub →