Overlay and Position Images Safely with ImageMagick composite

You will place one image over another, move the foreground to a known offset, and verify that the output has the expected canvas. The examples use composite-im6.q16 from ImageMagick 6.9.12-98 Q16, supplied by the 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 image files, and a directory where you can create a new output. These examples read the inputs and write a separate result. Do not use a source file as the output path until you have a backup and have checked the command.

1. Check the installed command

Confirm the executable and version before copying an example. This is an ordinary read-only check and does not need 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 installation. Use the fully qualified package-specific name in scripts when you want to make the ImageMagick 6 dependency obvious.

Checkpoint: if command -v finds nothing, stop here and install ImageMagick through your normal package-management process. Do not solve a missing command by running the image operation with sudo.

2. Prepare and inspect the inputs

The command calls its first positional file the change image and its second positional file the base image. The result is the final positional file. Inspect both inputs before composing them:

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

The exact metadata varies. Check the dimensions and formats, and make sure the paths are not accidentally pointing at the same file. A transparent PNG is a common change image because its transparent areas leave the base visible, but transparency is an image property, not a separate composite option.

For a first test, copy the inputs to a working directory or use files that are already disposable. The command can read several ImageMagick formats, but format support depends on the installed delegates. If identify cannot read a file, fix that input problem before trying different composite operators.

3. Place the foreground at an offset

Run the basic operation with a new output name:

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

Here logo.png is placed over photo.jpg, 40 pixels from the left and 30 pixels from the top. With no -gravity, the positive geometry offsets use the top-left corner as the reference. The output format is selected by the .png suffix, so choose a suffix that matches the format you need.

Verify the result rather than trusting a silent exit:

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

For a normal overlay, the output keeps the base image's 2400 by 1600 canvas. If the dimensions are not what you expect, check the base path, the image geometry, and whether an option was placed in the wrong part of the command.

4. Choose how pixels are combined

The default composition is suitable for an ordinary overlay. Use -compose when you need another documented operator. For example, this multiplies the change image with the base 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 remains first and the base image remains second. Verify the output format and dimensions:

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

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

5. Control the reference point

Use -gravity when a corner or edge is more useful than fixed top-left coordinates. This example 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, while -geometry supplies the offset. The same-looking +20+20 should not be copied between gravity settings without checking the result. Use identify for the canvas check and open the output in an image viewer when the visual position matters.

Do not confuse placement with resizing. -geometry controls the composite location in this workflow; it does not mean that the foreground will be resized to fit the base. Resize the change image as a separate, reviewed operation if its dimensions are wrong.

6. Add a mask only when the workflow needs one

The installed command accepts an optional mask file between the base image and the output image. A mask changes which pixels are used, so treat it as part of the image data and inspect it before running a batch. Keep the invocation unambiguous by using explicit paths:

$ 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 merely because the foreground has transparent pixels. Start with the three-file form and use a fourth file only when you have a deliberate mask image and have tested how its values affect the installed version. Verify the output with identify and inspect it before replacing any original.

7. Protect existing output and diagnose failures

ImageMagick writes the destination file. If the destination already exists, treat replacement as a destructive step. Make a backup or write a temporary result first:

$ 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

The final mv is the state-changing step. Only run it after checking the new file. If composition fails, remove the incomplete .new file and the previous output remains available. Do not remove the backup until you have inspected the replacement; deleting it is irreversible.

A missing required positional argument produces an error rather than a useful image. A failure to read an input usually means a wrong path, permission problem or 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. Use elevated privileges only when the input directory genuinely requires them, and never let root-owned output become the default workaround for a path or permission mistake.