Overlay and Position Images Safely with ImageMagick composite

Getting a logo exactly where you want it on a photo is what ImageMagick's composite does in one line, once you know its argument order. Examples use composite-im6.q16 from ImageMagick 6.9.12-98 Q16, Ubuntu package imagemagick-6.q16 version 8:6.9.12.98+dfsg1-5.2ubuntu0.1~esm13.

Allow about fifteen minutes. You need ImageMagick, two readable images, and somewhere to write a new output; do not reuse a source file as the output path until you have a backup and have tested the command.

1. Check the installed command

Confirm the executable and version before copying an example; this is a read-only check that needs no elevated privileges.

$ command -v composite-im6.q16
/usr/bin/composite-im6.q16
$ composite-im6.q16 -version
Version: ImageMagick 6.9.12-98 Q16 x86_64

The unqualified composite and composite-im6 names are aliases on this install. Use the fully qualified name in scripts if you want the ImageMagick 6 dependency to be obvious to the next reader.

2. Prepare and inspect the inputs

composite calls its first positional file the change image and its second the base image; the final positional file is the result. Inspect both before combining them:

$ identify /path/to/logo.png /path/to/photo.jpg
/path/to/logo.png PNG 320x120 ...
/path/to/photo.jpg JPEG 2400x1600 ...

• Check dimensions and format. Metadata varies by file; confirm both look right.
• Make sure the paths differ. It is easy to accidentally point both arguments at the same file.
• Transparency is a property, not an option. A transparent PNG is a common change image because its clear areas leave the base visible.

Work on copies or already-disposable files for a first test. Format support depends on installed delegates, so if identify cannot read a file, fix that before you try different composite operators.

3. Place the foreground at an offset

$ composite-im6.q16 -geometry +40+30 \
    /path/to/logo.png \
    /path/to/photo.jpg \
    /path/to/photo-with-logo.png

That places logo.png over photo.jpg, 40 pixels from the left and 30 from the top. With no -gravity set, positive offsets are measured from the top-left corner. The output format comes from the .png suffix, so pick a suffix that matches the format you actually need.

$ test -s /path/to/photo-with-logo.png && \
    identify /path/to/photo-with-logo.png
/path/to/photo-with-logo.png PNG 2400x1600 ...

A normal overlay keeps the base image's canvas, 2400 by 1600 here. Wrong dimensions mean check the base path, the geometry, or whether an option landed in the wrong part of the command.

4. Choose how pixels are combined

The default composition suits an ordinary overlay. Reach for -compose when you need another documented operator, for example multiplying pixels where the images overlap:

$ composite-im6.q16 -compose multiply -geometry +40+30 \
    /path/to/texture.png \
    /path/to/photo.jpg \
    /path/to/photo-textured.png

Operators change the pixel calculation, not the meaning of the positional arguments: the change image is still first, the base still second.

$ identify -format '%m %wx%h\n' /path/to/photo-textured.png
PNG 2400x1600

Other installed operators include over, screen, copy, plus and many more, but the visible result depends on colours, alpha channels and operator semantics. Test one on copies before using it in a batch. -blend and -dissolve are separate options for controlled mixing; do not treat an operator name as interchangeable with either one.

5. Control the reference point

Use -gravity when a corner or edge matters more than fixed top-left coordinates. This puts the foreground 20 pixels from the bottom-right corner:

$ composite-im6.q16 -gravity southeast -geometry +20+20 \
    /path/to/logo.png \
    /path/to/photo.jpg \
    /path/to/photo-with-logo.png

Gravity changes the reference point; -geometry supplies the offset from it. Do not copy the same-looking +20+20 between different gravity settings without checking the result with identify, or in an image viewer when the visual position actually matters.

-geometry controls placement here, not resizing. If the foreground's dimensions are wrong, resize it as its own separate, reviewed step.

6. Add a mask only when the workflow needs one

An optional mask file can go between the base image and the output. A mask changes which pixels get used, so treat it as image data and inspect it before a batch run:

$ composite-im6.q16 -geometry +40+30 \
    /path/to/change.png \
    /path/to/base.png \
    /path/to/mask.png \
    /path/to/masked-result.png

Do not add a mask just because the foreground has transparent pixels. Start with the three-file form, and only add a fourth once you have a deliberate mask image and have tested its effect on this installed version. Verify with identify before replacing anything original.

7. Protect existing output and diagnose failures

$ composite-im6.q16 -geometry +40+30 \
    /path/to/logo.png /path/to/photo.jpg \
    /path/to/photo-with-logo.png.new
$ identify /path/to/photo-with-logo.png.new
$ mv /path/to/photo-with-logo.png.new /path/to/photo-with-logo.png

Only run that final mv after checking the new file. If composition fails, delete the incomplete .new file; the previous output stays available. Do not remove a backup until you have inspected the replacement, that deletion cannot be undone.

A missing required positional argument produces an error, not a useful image. A read failure usually means a wrong path, a permission problem, or an unsupported format; check without changing anything:

$ ls -l /path/to/logo.png /path/to/photo.jpg
$ test -r /path/to/logo.png && echo 'logo readable'
$ test -r /path/to/photo.jpg && echo 'base readable'

Run as the ordinary user who owns the working directory. Reach for elevated privileges only when the input directory genuinely needs them, and never let root-owned output become the default fix for a path mistake.