v7.1.2-36 Latest Stable Release

Architecture

Discover the architecture of ImageMagick, including its pixel cache, image properties, profiles, threading, distributed processing, and custom coders/filters. Learn how ImageMagick efficiently manages pixels, metadata, and large images across heterogeneous platforms for powerful image conversion, editing, and composition.

quickstart.sh
# Install via your favorite Package Manager
$ apt install imagemagick
# Convert PNG to WebP with compression
$ magick input.png -quality 85 output.webp
# Resize image maintaining aspect ratio
$ magick input.jpg -resize 800x600^ output.jpg
Under the Hood

Architecture of ImageMagick

The citizens of Oz were quite content with their benefactor, the all-powerful Wizard. They accepted his wisdom and benevolence without ever questioning the who, why, and where of his power. Like the citizens of Oz, if you feel comfortable that ImageMagick can help you convert, edit, or compose your images without knowing what goes on behind the curtain, feel free to skip this section. However, if you want to know more about the software and algorithms behind ImageMagick, read on. To fully benefit from this discussion, you should be comfortable with image nomenclature and be familiar with computer programming.

Architecture Overview

An image typically consists of a rectangular region of pixels and metadata. To convert, edit, or compose an image efficiently, we need convenient access to any pixel anywhere within the region (and sometimes outside the region), as well as across any image in an image sequence. However, hundreds of image formats—such as JPEG, TIFF, PNG, and GIF—complicate on-demand pixel access due to differences in:

  • Colorspace: sRGB, linear RGB, linear GRAY, CMYK, YUV, Lab, etc.
  • Bit depth: 1, 4, 8, 12, 16, etc.
  • Storage format: unsigned, signed, float, double, etc.
  • Compression: uncompressed, RLE, Zip, BZip, etc.
  • Orientation: top-to-bottom, right-to-left, etc.
  • Layout: raw, interspersed with opcodes, etc.

Additionally, some image pixels require attenuation, some formats permit multiple frames, and vector formats must first be rasterized into pixels.

Processing Requirements

An efficient implementation of an image processing algorithm may require getting or setting:

  • One pixel at a time (e.g. location 10,3)
  • A single scanline (e.g. all pixels from row 4)
  • A few scanlines at once (e.g. pixel rows 4–7)
  • A single column or columns of pixels (e.g. column 11)
  • An arbitrary region of pixels (e.g. 10,7 to 10,19)
  • Pixels in random order (e.g. 14,15 and 640,480)
  • Pixels from two different images (e.g. 5,1 in image 1 & 2)
  • Pixels outside image boundaries (e.g. -1,-3)
  • Unsigned (e.g. 65311) or floating-point (e.g. 0.17836) components
  • High-dynamic range values, including negative (-0.007297) or out-of-range (>65535) values
  • One or more pixels simultaneously across multiple threads
  • All pixels in memory for heterogeneous execution across CPUs, GPUs, and accelerators
  • Channel traits specifying whether each channel is copied, updated, or blended
  • Pixel masks defining which pixels are eligible to be updated
  • Extra user-defined meta-channels left untouched by standard algorithms

To handle these varied formats and requirements, ImageMagick implements the pixel cache, providing sequential or parallel on-demand access to any pixel inside an image region (authentic pixels), across image sequences, or outside image boundaries (virtual pixels).

Alongside pixels, images carry properties and profiles—such as width, height, depth, colorspace, author, comments, creation date, color management profiles, and EXIF, IPTC, 8BIM, or XMP metadata—accessible via command-line options or API calls.

Although ImageMagick comprises nearly half a million lines of C code (plus millions of lines in optional delegate libraries like JPEG, PNG, and TIFF), most image processing boils down to reading and writing pixels and metadata. The sections below detail the pixel cache, metadata handling, multithreading, image coders, and custom filters.

The Pixel Cache

The ImageMagick pixel cache is a repository for image pixels with up to 64 channels stored contiguously at the build-time quantum depth: 8 bits per channel for Q8, 16 bits for Q16, and 32 bits for Q32. By default, pixel components are 32-bit floating-point high dynamic-range (HDRI) quantities. Channels typically hold red, green, blue, and alpha intensities—or cyan, magenta, yellow, black, and alpha—and can also store colormap indexes for colormapped images.

Pixel cache storage may reside in heap memory, disk-backed memory-mapped files, or directly on disk. The cache is reference-counted: cloning an image copies only the cache properties, while the pixel data itself is copied only when you signal an intention to modify it (copy-on-write).

Create the Pixel Cache

The pixel cache is associated with an image upon creation and initialized when you first read or write pixels. While these examples use the MagickCore API, the same principles apply across all ImageMagick language bindings:

Canvas Initialized

Create a canvas initialized to a background color:

image=AllocateImage(image_info);
if (SetImageExtent(image,640,480) == MagickFalse)
  { /* an exception was thrown */ }
(void) QueryMagickColor("red",
  &image->background_color,&image->exception);
SetImageBackgroundColor(image);
From Disk Image

Create from a JPEG image on disk:

(void) strcpy(image_info->filename,"image.jpg");
image=ReadImage(image_info,exception);
if (image == (Image *) NULL)
  { /* an exception was thrown */ }
From Memory Blob

Create from a memory-based image blob:

image=BlobToImage(blob_info,blob,extent,exception);
if (image == (Image *) NULL)
  { /* an exception was thrown */ }

When initialized, pixels are scaled from their native bit depth to the pixel cache depth—for example, a 1-channel 1-bit monochrome PBM image scales to 8-bit gray in Q8 or 16-bit RGBA in Q16. While storing a 1-bit image at 16-bit depth trades storage and full-image buffering for uniform access, the convenience generally outweighs the overhead. Check your build quantum depth and features using -version:

identify-version.sh
$ identify -version
Version: ImageMagick 7.1.2-36 2026-11-16 Q16-HDRI https://imagemagick.org

Access the Pixel Cache

Pixels inside the image region are authentic pixels, while those outside are virtual pixels. Access them with:

  • GetVirtualPixels(): gets pixels you do not intend to modify or pixels outside the image region (e.g. at -1,-3).
  • GetAuthenticPixels(): gets existing pixels inside the image bounds that you intend to modify.
  • QueueAuthenticPixels(): queues pixels you intend to overwrite without reading existing values first (slightly faster when initializing pixels).
  • SyncAuthenticPixels(): pushes any modified pixels from intermediate buffers back into the pixel cache.

Here is a typical MagickCore snippet copying pixels and reducing intensity by 10%:

pixel-manipulation.c
const Quantum
  *p;

Quantum
  *q;

ssize_t
  x,
  y;

destination=CloneImage(source,source->columns,source->rows,MagickTrue,exception);
if (destination == (Image *) NULL)
  { /* an exception was thrown */ }
for (y=0; y < (ssize_t) source->rows; y++)
{
  p=GetVirtualPixels(source,0,y,source->columns,1,exception);
  q=GetAuthenticPixels(destination,0,y,destination->columns,1,exception);
  if ((p == (const Quantum *) NULL) || (q == (Quantum *) NULL))
    break;
  for (x=0; x < (ssize_t) source->columns; x++)
  {
    SetPixelRed(image,90*p->red/100,q);
    SetPixelGreen(image,90*p->green/100,q);
    SetPixelBlue(image,90*p->blue/100,q);
    SetPixelAlpha(image,90*p->opacity/100,q);
    p+=GetPixelChannels(source);
    q+=GetPixelChannels(destination);
  }
  if (SyncAuthenticPixels(destination,exception) == MagickFalse)
    break;
}
if (y < (ssize_t) source->rows)
  { /* an exception was thrown */ }

Because the pixel cache manager may stage pixels in an intermediate buffer, you must call SyncAuthenticPixels() after updates—which is why reading or updating a single scanline or a few scanlines at a time is recommended. Note that GetAuthenticPixels() throws an exception if requested coordinates fall outside the image bounds (e.g. row 480 on a 640×480 image, where rows are 0–479), whereas GetVirtualPixels() seamlessly returns out-of-bounds pixels (e.g. GetVirtualPixels(source,-3,-3,source->columns+3,6,exception)).

You can also associate arbitrary metacontent with each pixel, accessed via GetVirtualMetacontent() (read-only) or GetAuthenticMetacontent() (read/write):

metacontent.c
const void
  *metacontent;

for (y=0; y < (ssize_t) source->rows; y++)
{
  p=GetVirtualPixels(source,0,y,source->columns,1,exception);
  if (p == (const Quantum *) NULL)
    break;
  metacontent=GetVirtualMetacontent(source);
  /* print meta content here */
}
if (y < (ssize_t) source->rows)
  { /* an exception was thrown */ }

Virtual Pixels

Many neighborhood-based algorithms (blurs, distortions, resizes, convolutions) require pixels surrounding edge pixels. Virtual pixels eliminate custom edge-handling logic by defining what value is returned outside image boundaries. Configure them via SetImageVirtualPixelMethod() or -virtual-pixel:

Method Description
backgroundthe area surrounding the image is the background color
blackthe area surrounding the image is black
checker-tilealternate squares with image and background color
dithernon-random 32x32 dithered pattern
edgeextend the edge pixel toward infinity (default)
graythe area surrounding the image is gray
horizontal-tilehorizontally tile the image, background color above/below
horizontal-tile-edgehorizontally tile the image and replicate the side edge pixels
mirrormirror tile the image
randomchoose a random pixel from the image
tiletile the image
transparentthe area surrounding the image is transparent blackness
vertical-tilevertically tile the image, sides are background color
vertical-tile-edgevertically tile the image and replicate the side edge pixels
whitethe area surrounding the image is white

Cache Storage and Resource Requirements

Pixel cache size scales as width × height × (bit-depth / 8) × channels: a 640×480 non-HDRI Q16 RGBA image consumes ~2.3 MiB, whereas a 25,000×25,000 image requires ~4.7 GiB. ImageMagick automatically allocates pixel caches in heap memory first, spilling to disk-backed memory-mapped files (up to 5× faster than standard disk I/O) and then standard disk I/O (up to 1000× slower than RAM) as limits are reached.

Resource limits apply globally across all open images in an ImageMagick invocation (though certain algorithms and external delegate libraries such as JPEG or TIFF do not enforce them). Configure limits via policy.xml, environment variables, -limit, or SetMagickResourceLimit():

Resource Limit Description
widthmaximum width of an image; exceeding throws an exception and stops processing
heightmaximum height of an image; exceeding throws an exception and stops processing
areamaximum area in bytes in cache memory before automagically spilling to disk/memory-map
memorymaximum heap memory in bytes allocated for the pixel cache
mapmaximum memory-map allocation in bytes for the pixel cache
diskmaximum disk space in bytes permitted for the pixel cache; exceeding throws a fatal exception
filesmaximum open pixel cache files; excess disk caches close and reopen on demand
threadmaximum parallel threads permitted (defaults to host CPU core count; set to 1 for single-threaded execution)
timemaximum execution time in seconds before throwing an exception and halting

Inspect active resource limits with identify -list resource, or trace live cache allocations with -debug cache:

resource-and-debug.sh
$ identify -list resource
Resource limits:
  Width: 100MP
  Height: 100MP
  Area: 25.181GB
  Memory: 11.726GiB
  Map: 23.452GiB
  Disk: unlimited
  File: 768
  Thread: 12
  Throttle: 0
  Time: unlimited

$ magick -debug cache logo: -sharpen 3x2 null:
2016-12-17T13:33:42-05:00 0:00.000 0.000u 7.0.0 Cache magick: cache.c/OpenPixelCache/3834/Cache
  open LOGO[0] (Heap Memory, 640x480x4 4.688MiB)
2016-12-17T13:33:42-05:00 0:00.010 0.000u 7.0.0 Cache magick: cache.c/OpenPixelCache/3834/Cache
  open LOGO[0] (Heap Memory, 640x480x3 3.516MiB)

For public web services such as MagickStudio, a hardened policy.xml prevents denial-of-service and unauthorized file or delegate execution (note that prior to ImageMagick 7.0.1-8, delegate restrictions used domain="coder" instead of domain="delegate"):

policy.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policymap [
  <!ELEMENT policymap (policy)*>
  <!ATTLIST policymap xmlns CDATA #FIXED "">
  <!ELEMENT policy EMPTY>
  <!ATTLIST policy
    xmlns   CDATA   #FIXED ""
    domain  NMTOKEN #REQUIRED
    name    NMTOKEN #IMPLIED
    pattern CDATA   #IMPLIED
    rights  NMTOKEN #IMPLIED
    stealth NMTOKEN #IMPLIED
    value   CDATA   #IMPLIED>
]>
<policymap>
  <!-- Resource Limits -->
  <policy domain="resource" name="thread" value="4"/>
  <policy domain="resource" name="time" value="60"/>
  <policy domain="resource" name="file" value="768"/>
  <policy domain="resource" name="memory" value="256MiB"/>
  <policy domain="resource" name="map" value="512MiB"/>
  <policy domain="resource" name="area" value="32MP"/>
  <policy domain="resource" name="disk" value="1GiB"/>
  <policy domain="resource" name="list-length" value="16"/>
  <policy domain="resource" name="width" value="4KP"/>
  <policy domain="resource" name="height" value="4KP"/>
  <policy domain="resource" name="throttle" value="2"/>
  <policy domain="resource" name="dynamic-throttle" value="false"/>

  <!-- Pixel Cache & System Security -->
  <policy domain="cache" name="memory-map" value="anonymous"/>
  <policy domain="cache" name="synchronize" value="true"/>
  <policy domain="system" name="shred" value="1"/>
  <policy domain="system" name="memory-map" value="anonymous"/>
  <policy domain="system" name="max-memory-request" value="256MiB"/>
  <policy domain="system" name="symlink" rights="none" pattern="follow"/>
  <policy domain="system" name="svg" rights="none" pattern="substitute-entities"/>

  <!-- Delegate, Filter, Path & Module Restrictions -->
  <policy domain="delegate" rights="none" pattern="*"/>
  <policy domain="filter" rights="none" pattern="*"/>
  <policy domain="path" rights="none" pattern="-"/>
  <policy domain="path" rights="none" pattern="[Ff][Dd]:*"/>
  <policy domain="path" rights="none" pattern="/etc/*"/>
  <policy domain="path" rights="none" pattern="*../*"/>
  <policy domain="path" rights="none" pattern="@*"/>
  <policy domain="path" rights="none" pattern="|*"/>
  <policy domain="module" rights="none" pattern="*"/>
  <policy domain="module" rights="read | write" pattern="{GIF,JPEG,PNG,WEBP}"/>
</policymap>

Distributed Pixel Cache

A distributed pixel cache extends the local cache across one or more remote servers so very large images can scale beyond single-host memory and disk limits. When local cache resources are exhausted, ImageMagick marshals pixels over the network to remote pixel servers (trading network latency for capacity):

distributed-cache.sh
$ magick -distribute-cache 6668 & # start on 192.168.100.50
$ magick -define registry:cache:hosts=192.168.100.50:6668 myimage.jpg -sharpen 5x2 mimage.png

Cache Views

Standard accessors (GetVirtualPixels(), GetAuthenticPixels(), QueueAuthenticPixels(), SyncAuthenticPixels()) operate on a single cache region per image at a time. To access multiple regions simultaneously—or across multiple threads of execution—open a cache view and destroy it when finished:

cache-view.c
CacheView
  *first_row,
  *last_row;

first_row=AcquireVirtualCacheView(source,exception);
last_row=AcquireVirtualCacheView(source,exception);
for (y=0; y < (ssize_t) source->rows; y++)
{
  const Quantum
    *p,
    *q;

  p=GetCacheViewVirtualPixels(first_row,0,y,source->columns,1,exception);
  q=GetCacheViewVirtualPixels(last_row,0,source->rows-y-1,source->columns,1,exception);
  if ((p == (const Quantum *) NULL) || (q == (const Quantum *) NULL))
    break;
  for (x=0; x < (ssize_t) source->columns; x++)
  {
    /* do something with p & q here */
  }
}
last_row=DestroyCacheView(last_row);
first_row=DestroyCacheView(first_row);
if (y < (ssize_t) source->rows)
  { /* an exception was thrown */ }

Magick Pixel Cache (MPC) Format

The native Magick Pixel Cache (MPC) format eliminates decode/encode overhead by saving two files: .mpc (image properties) and .cache (raw native pixel cache). When read back, ImageMagick memory-maps the .cache file directly with near-zero decoding overhead—ideal for write-once, read-many workflows (such as repeated crops on web servers like MagickStudio):

mpc-workflow.sh
$ magick image.tif image.mpc
$ magick image.mpc -crop 100x100+0+0 +repage 1.png
$ magick image.mpc -crop 100x100+100+0 +repage 2.png
$ magick image.mpc -crop 100x100+200+0 +repage 3.png
Pixel Cache Best Practices
  • Prefer sequential row access: Access a single scanline or a few scanlines at a time, top-to-bottom, rather than column-by-column or random regions.
  • Use Queue over Get when initializing: Call QueueAuthenticPixels() / QueueCacheViewAuthenticPixels() when setting new pixels to avoid an unnecessary read, and always call SyncAuthenticPixels() / SyncCacheViewAuthenticPixels() afterward.
  • Use Cache Views for concurrency: Direct accessors are slightly faster for single-region, single-thread work, but cache views are mandatory for multi-region or multithreaded access.
  • Stay in-bounds & in-memory: Requesting in-bounds pixels is faster than virtual pixels, and keeping the cache in heap memory avoids disk I/O penalties (up to 1000× slower).
  • Choose Q8 vs. Q16/HDRI intentionally: Q8 uses half the cache memory of Q16 and executes faster; HDRI stores 32-bit floats without clamping out-of-band values.
  • Point large disk caches to fast storage: Set registry:temporary-path (defaulting to /tmp on Linux or c:/temp on Windows) to a partition with ample free space.
$ magick -limit memory 2GB -limit map 4GB -define registry:temporary-path=/data/tmp ...

Image Properties and Profiles

Core image attributes are stored directly on the Image structure (e.g. image->columns, image->rows), while arbitrary metadata properties (such as comments or descriptions) are managed via GetImageProperty() and SetImageProperty(). ImageMagick also supports stealth properties called artifacts via GetImageArtifact() and SetImageArtifact(), which are not exported to output image files.

Binary profiles (EXIF, IPTC, ICC color profiles, 8BIM, XMP) are managed with GetImageProfile(), SetImageProfile(), and ProfileImage():

properties-and-profiles.c
/* Properties */
const char *comment;
(void) SetImageProperty(image,"comment","This space for rent");
comment=GetImageProperty(image,"comment");
if (comment != (const char *) NULL)
  (void) printf("Image comment: %s
",comment);

/* Profiles */
StringInfo *profile;
profile=AcquireStringInfo(length);
SetStringInfoDatum(profile,my_exif_profile);
(void) SetImageProfile(image,"EXIF",profile);
DestroyStringInfo(profile);
profile=GetImageProfile(image,"EXIF");
if (profile != (StringInfo *) NULL)
  (void) PrintStringInfo(stdout,"EXIF",profile);

Multispectral Imagery

ImageMagick supports multispectral imagery where all channels share the same dimensions and pixel count. PSD, TIFF, MIFF, MPC, and FTXT fully support multispectral images up to 31 bands (21 meta channels), or up to 62 bands (52 meta channels) when built with --enable-64bit-channel-masks.

If you have a multispectral use case not currently supported by a given image format, share it on the ImageMagick discussion forum for consideration in a future release.

Streaming Pixels

Pixel streaming processes pixels row-by-row as they are read or written. Unlike the pixel cache—whose memory scales with image area—pixel streaming scales with image width, though pixels are not persisted in memory once consumed. Use ReadStream() or WriteStream() with a callback in MagickCore, or use the standalone stream CLI utility to extract raw pixel components from large images (note that a few formats, such as PSD, do not store pixels in standard top-to-bottom, left-to-right scanline order):

read-stream.c
static size_t StreamPixels(const Image *image,const void *pixels,const size_t columns)
{
  const Quantum *p;
  MyData *my_data;

  my_data=(MyData *) image->client_data;
  p=(const Quantum *) pixels;
  if (p != (const Quantum *) NULL)
    {
      /* process pixels here */
    }
  return(columns);
}

/* Invoke the pixel stream */
image_info->client_data=(void *) MyData;
image=ReadStream(image_info,&StreamPixels,exception);

Large Image Support

ImageMagick supports mega- to tera-pixel images—theoretically up to 31 million rows/columns on 32-bit systems and 31 trillion on 64-bit systems, bounded by host resources and format limits (for instance, Photoshop PSD files cap dimensions at 300,000 pixels). Because disk-backed caches are roughly 1000× slower than RAM, use resource limits, progress monitoring, fast temporary storage, or remote cache servers when scaling up:

tera-pixel.sh
# Resize to 250,000x250,000 using a custom temporary partition
$ magick -define registry:temporary-path=/data/tmp logo: -resize 250000x250000 logo.miff

# Force pixels to memory-mapped disk or purely on disk (-limit area 0)
$ magick -define registry:temporary-path=/data/tmp -limit memory 16mb logo: -resize 250000x250000 logo.miff
$ magick -define registry:temporary-path=/data/tmp -limit area 0 logo: -resize 250000x250000 logo.miff

# Monitor long-running disk-backed operations
$ magick -monitor -limit memory 2GiB -limit map 4GiB -define registry:temporary-path=/data/tmp   logo: -resize 250000x250000 logo.miff

# Offload across multiple distributed pixel cache hosts
$ magick -distribute-cache 6668 &  # on 192.168.100.50
$ magick -distribute-cache 6668 &  # on 192.168.100.51
$ magick -limit memory 2mb -limit map 2mb -limit disk 2gb   -define registry:cache:hosts=192.168.100.50:6668,192.168.100.51:6668   myhugeimage.jpg -sharpen 5x2 myhugeimage.png

Threads of Execution

Many internal ImageMagick algorithms are multithreaded with OpenMP. While higher-level APIs like MagickWand are thread-safe, MagickCore's direct pixel accessors (GetVirtualPixels(), GetAuthenticPixels(), QueueAuthenticPixels(), SyncAuthenticPixels()) are not safe across multiple concurrent threads outside an internal OpenMP loop. Always acquire a separate cache view per thread (e.g. AcquireVirtualCacheView() / GetCacheViewAuthenticPixels()), or use wand views / image views for row-parallel callbacks.

Note that if your OpenMP application dynamically increases its thread count, do so before invoking ImageMagick APIs. On macOS or older Linux systems where mixing POSIX threads and OpenMP causes conflicts, build with --disable-openmp. You can also reduce lock contention with --with-tcmalloc.

openmp-cache-view.c
CacheView *image_view;
MagickBooleanType status = MagickTrue;
ssize_t y;

image_view=AcquireVirtualCacheView(image,exception);
#pragma omp parallel for schedule(static,4) shared(status)
for (y=0; y < (ssize_t) image->rows; y++)
{
  Quantum *q;
  ssize_t x;
  void *metacontent;

  if (status == MagickFalse)
    continue;
  q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception);
  if (q == (Quantum *) NULL)
    {
      status=MagickFalse;
      continue;
    }
  metacontent=GetCacheViewAuthenticMetacontent(image_view);
  for (x=0; x < (ssize_t) image->columns; x++)
  {
    SetPixelRed(image,...,q);
    SetPixelGreen(image,...,q);
    SetPixelBlue(image,...,q);
    SetPixelAlpha(image,...,q);
    if (metacontent != NULL)
      metacontent[indexes+x]=...;
    q+=GetPixelChannels(image);
  }
  if (SyncCacheViewAuthenticPixels(image_view,exception) == MagickFalse)
    status=MagickFalse;
}
image_view=DestroyCacheView(image_view);
Threading Performance & Tuning

By default, ImageMagick sets threads to the host's logical CPU count. On virtual hosts with capped vCPUs or hyperthreaded CPUs where hyperthreads add contention, constrain threads via MAGICK_THREAD_LIMIT, -limit thread, or policy.xml, and verify the sweet spot with -bench:

thread-benchmark.sh
$ export MAGICK_THREAD_LIMIT=6
$ magick -bench 10 model.png -sharpen 5x2 null:
Performance[1]: 10i 1.135ips 1.000e 8.760u 0:08.810
Performance[2]: 10i 2.020ips 0.640e 9.190u 0:04.950
Performance[3]: 10i 2.786ips 0.710e 9.400u 0:03.590
Performance[4]: 10i 3.378ips 0.749e 9.580u 0:02.960
Performance[5]: 10i 4.032ips 0.780e 9.580u 0:02.480
Performance[6]: 10i 4.566ips 0.801e 9.640u 0:02.190
Performance[7]: 10i 3.788ips 0.769e 10.980u 0:02.640
Performance[12]: 10i 4.525ips 0.799e 18.320u 0:02.210

Enable Dynamic Throttling for Optimized Performance

Enable dynamic throttling to automatically introduce slight delays between processing scanlines based on your system's current load average, preventing resource exhaustion under heavy workloads:

<policy domain="resource" name="dynamic-throttle" value="true"/>

Heterogeneous Distributed Processing

ImageMagick supports heterogeneous distributed processing via the OpenCL framework, executing kernels across CPUs, GPUs, and accelerators for order-of-magnitude speed-ups. If an accelerator is unavailable or fails to respond (such as triggering Windows GPU Timeout Detection and Recovery, which can be mitigated by increasing the TdrDelay registry key), ImageMagick automatically falls back to the standard CPU path. See MagickCore/accelerate.c for the full OpenCL kernel implementations:

opencl-check.sh
$ magick identify -version
Features: DPC Cipher Modules OpenCL OpenMP(4.5)
$ magick image.png -convolve '-1, -1, -1, -1, 9, -1, -1, -1, -1' convolve.png

Custom Image Coders

An image coder (encoder/decoder) registers a format with ImageMagick, optionally inspects magic header bytes to classify files (IsMGK), reads image metadata and pixels into the pixel cache (ReadMGKImage), writes pixels out to disk or blob (WriteMGKImage), and unregisters the format upon unload. Below is an abbreviated example of the custom MGK coder (header id=mgk, dimensions, and raw RGB bytes). Build custom modules using the Magick Coder Kit (set PKG_CONFIG_PATH if ImageMagick is installed in a non-default prefix):

mgk-coder.c
static MagickBooleanType IsMGK(const unsigned char *magick,const size_t length)
{
  if (length < 7)
    return(MagickFalse);
  if (LocaleNCompare((char *) magick,"id=mgk",7) == 0)
    return(MagickTrue);
  return(MagickFalse);
}

static Image *ReadMGKImage(const ImageInfo *image_info,ExceptionInfo *exception)
{
  /* Open blob, validate "id=mgk" header, parse columns & rows,
     allocate pixel cache via SetImageExtent(), read RGB scanlines with
     QueueAuthenticPixels() + SyncAuthenticPixels(), and support multi-frame lists. */
}

static MagickBooleanType WriteMGKImage(const ImageInfo *image_info,Image *image,
  ExceptionInfo *exception)
{
  /* Convert to RGBColorspace, write "id=mgk
<cols> <rows>
" header,
     and stream scanlines via GetVirtualPixels() + WriteBlob(). */
}

ModuleExport unsigned long RegisterMGKImage(void)
{
  MagickInfo *entry;

  entry=AcquireMagickInfo("MGK","MGK","MGK image");
  entry->decoder=(DecodeImageHandler *) ReadMGKImage;
  entry->encoder=(EncodeImageHandler *) WriteMGKImage;
  entry->magick=(IsImageFormatHandler *) IsMGK;
  (void) RegisterMagickInfo(entry);
  return(MagickImageCoderSignature);
}

ModuleExport void UnregisterMGKImage(void)
{
  (void) UnregisterMagickInfo("MGK");
}
$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
$ magick logo: logo.mgk
$ display logo.mgk

Custom Image Filters

Custom image filters let you plug custom processing algorithms into ImageMagick, invoked from the CLI with -process or via ExecuteModuleProcess() in MagickCore. Below is an outline of the sample analyze filter, which computes brightness and saturation statistics (mean, standard deviation, skewness, kurtosis) in parallel with OpenMP and stores them as image properties. Get started with the Magick Filter Kit:

analyze-filter.c
ModuleExport size_t analyzeImage(Image **images,const int argc,
  const char **argv,ExceptionInfo *exception)
{
  Image *image;

  for (image=(*images); image != (Image *) NULL; image=GetNextImageInList(image))
  {
    CacheView *image_view = AcquireVirtualCacheView(image,exception);
    #pragma omp parallel for schedule(static)
    for (ssize_t y=0; y < (ssize_t) image->rows; y++)
    {
      const Quantum *p = GetCacheViewVirtualPixels(image_view,0,y,image->columns,1,exception);
      for (ssize_t x=0; x < (ssize_t) image->columns; x++)
      {
        /* ConvertRGBToHSL() and accumulate 1st–4th moments for brightness & saturation */
        p+=GetPixelChannels(image);
      }
    }
    image_view=DestroyCacheView(image_view);
    /* Compute mean, std-dev, kurtosis, skewness and record via SetImageProperty() */
  }
  return(MagickImageFilterSignature);
}
$ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
$ magick logo: -process "analyze" -verbose info:
  filter:brightness:kurtosis: 3.97886
  filter:brightness:mean: 58901.3
  filter:brightness:skewness: -2.30827
  filter:brightness:standard-deviation: 16179.8
  filter:saturation:kurtosis: 6.59719
  filter:saturation:mean: 5321.05
  filter:saturation:skewness: 2.75679
  filter:saturation:standard-deviation: 14484.7