The ImageMagick pixel cache is a repository for image pixels with up to 5 channels. The first 4 channels are stored contiguously and an optional second area follows with 1 channel. The channels are at the depth specified when ImageMagick was built. The channel depths are 8 bits-per-pixel component for the Q8 version of ImageMagick, 16 bits-per-pixel component for the Q16 version, and 32 bits-per-pixel component for the Q32 version. By default pixel components are unsigned quantities, however, if you use the high dynamic-range version of ImageMagick, the components are 32-bit floating point. The primary 4 channels can hold any value but typically contain red, green, blue, and alpha intensities or cyan, magenta, yellow, and alpha intensities. The optional fifth channel contains the colormap indexes for colormapped images or the black channel for CMYK images. The pixel cache storage may be heap memory, anonymous memory mapped memory, disk-backed memory mapped, or on disk. The pixel cache is reference-counted. Only the cache properties are copied when the cache is cloned. The cache pixels are subsequently copied when you signal your intention to update any of the pixels.
+The ImageMagick pixel cache is a repository for image pixels with up to 5 channels. The first 4 channels are stored contiguously and an optional second area follows with 1 channel. The channels are at the depth specified when ImageMagick was built. The channel depths are 8 bits-per-pixel component for the Q8 version of ImageMagick, 16 bits-per-pixel component for the Q16 version, and 32 bits-per-pixel component for the Q32 version. By default pixel components are unsigned quantities, however, if you use the high dynamic-range version of ImageMagick, the components are 32-bit floating point. The primary 4 channels can hold any value but typically contain red, green, blue, and alpha intensities or cyan, magenta, yellow, and alpha intensities. The optional fifth channel contains the colormap indexes for colormapped images or the black channel for CMYK images. The pixel cache storage may be heap memory, anonymous memory mapped memory, disk-backed memory mapped, or on disk. The pixel cache is reference-counted. Only the cache properties are copied when the cache is cloned. The cache pixels are subsequently copied only when you signal your intention to update any of the pixels.
When the pixel cache is initialized, pixels are scaled from whatever bit depth they originated from to that required by the pixel cache. For example, a 1-channel 1-bit monochrome PBM image is scaled to a 4 channel 8-bit RGBA image, if you are using the Q8 version of ImageMagick, and 16-bit RGBA for the Q16 version. You can determine which version you have with the ‑version option:
-$magick> identify -versionVersion: ImageMagick 6.6.4-1 2010-19-14 Q16 http://www.imagemagick.org
+$magick> identify -versionVersion: ImageMagick 6.6.6-3 2010-22-21 Q16 http://www.imagemagick.org
As you can see, the convenience of the pixel cache sometimes comes with a trade-off in storage (e.g. storing a 1-bit monochrome image as 16-bit RGBA is wasteful) and speed (i.e. storing the entire image in memory is generally slower than accessing one scanline of pixels at a time). In most cases, the benefits of the pixel cache typically outweigh any disadvantages.
Once the pixel cache is associated with an image, you typically want to get, update, or put pixels into it. We refer to pixels inside the image region as authentic pixels and outside the region as virtual pixels. Use these methods to access the pixels in the cache:
When we first create the destination image by cloning the source image, the pixel cache pixels are not copied. They are only copied when you signal your intentions to modify the pixel cache by calling GetAuthenticPixels() or QueueAuthenticPixels(). Use QueueAuthenticPixels() if you want to set new pixel values rather than update existing ones. Finally, use SyncAuthenticPixels() to ensure any updated pixels are pushed to the pixel cache.
+When we first create the destination image by cloning the source image, the pixel cache pixels are not copied. They are only copied when you signal your intentions to modify the pixel cache by calling GetAuthenticPixels() or QueueAuthenticPixels(). Use QueueAuthenticPixels() if you want to set new pixel values rather than update existing ones. You could use GetAuthenticPixels() to set pixel values but it is slightly more efficient to use QueueAuthenticPixels() instead. Finally, use SyncAuthenticPixels() to ensure any updated pixels are pushed to the pixel cache.
Recall how we mentioned that the indexes of a colormapped image or the black channel of a CMYK image are stored separately. Use GetVirtualIndexes() (to read the indexes) or GetAuthenticIndexes() (to update the indexes) to gain access to this channel. For example, to print the colormap indexes, use:
@@ -317,23 +317,23 @@ const IndexPacket *indexes; - for (y=0; y < (long) source->rows; y++) + for (y=0; y < (ssize_t) source->rows; y++) { p=GetVirtualPixels(source,0,y,source->columns,1); if (p == (const PixelPacket *) NULL) break; indexes=GetVirtualIndexes(source); - for (x=0; x < (long) source->columns; x++) + for (x=0; x < (ssize_t) source->columns; x++) (void) printf("%d\n",indexes[x]; } - if (y < (long) source->rows) + if (y < (ssize_t) source->rows) /* an exception was thrown */The pixel cache manager decides whether to give you direct or indirect access to the image pixels. In some cases the pixels are staged to an intermediate buffer-- and that is why you must call SyncAuthenticPixels() to ensure this buffer is pushed out to the pixel cache to guarantee the corresponding pixels in the cache are updated. For this reason we recommend that you only read or update a scanline or a few scanlines of pixels at a time. However, you can get any rectangular region of pixels you want. GetAuthenticPixels() requires that the region you request is within the bounds of the image area. For a 640 by 480 image, you can get a scanline of 640 pixels at row 479 but if you ask for a scanline at row 480, an exception is returned (rows are numbered starting at 0). GetVirtualPixels() does not have this constraint. For example,
- p=GetVirtualPixels(source,-3,3,source->columns+7,7,exception); + p=GetVirtualPixels(source,-3,-3,source->columns+3,6,exception);
gives you the pixels you asked for without complaint, even though some are not within the confines of the image region.
@@ -350,13 +350,13 @@ black: the area surrounding the image is black checker-tile: alternate squares with image and background color dither: non-random 32x32 dithered pattern - edge: extend the edge pixel toward infinity + edge: extend the edge pixel toward infinity (default) gray: the area surrounding the image is gray horizontal-tile: horizontally tile the image, background color above/below horizontal-tile-edge: horizontally tile the image and replicate the side edge pixels mirror: mirror tile the image random: choose a random pixel from the image - tile: tile the image (default) + tile: tile the image transparent: the area surrounding the image is transparent blackness vertical-tile: vertically tile the image, sides are background color vertical-tile-edge: vertically tile the image and replicate the side edge pixels @@ -387,7 +387,9 @@ $magick> identify -list resourceFile Area Memory Map Disk Thread Time
-------------------------------------------------------------------------------
- 768 12.443GB 8.6917GiB 23.178GiB 18.446744EB 8 unlimited
You can set these limits either as a policy (see policy.xml), with an environment variable, with the -limit command line option, or with the SetMagickResourceLimit() MagickCore API method. As an example, our online web interface to ImageMagick, ImageMagick Studio, has an area limit of 64 megabytes, a memory limit of 128 mebibytes and a map limit of 256 mebibytes and a disk limit of 1 gigabytes. Since we process multiple simultaneous sessions, we don't want any one session consuming all the available memory. Instead large images are cached to disk. If the image is too large and exceeds the pixel cache disk limit, the program exits. In addition, we place a 60 second time limit to prevent any run-away processing tasks.
Note, the cache limits are global, meaning if you create several images, the combined resource requirements are compared to the limit to determine the pixel cache storage disposition.
@@ -405,20 +407,20 @@ view_1=OpenCacheView(source); view_2=OpenCacheView(source); - for (y=0; y < (long) source->rows; y++) + for (y=0; y < (ssize_t) source->rows; y++) { u=GetCacheViewVirtualPixels(view_1,0,y,source->columns,1,exception); v=GetCacheViewVirtualPixels(view_2,0,source->rows-y-1,source->columns,1,exception); if ((u == (const PixelPacket *) NULL) || (v == (const PixelPacket *) NULL)) break; - for (x=0; x < (long) source->columns; x++) + for (x=0; x < (ssize_t) source->columns; x++) { /* do something with u & v here */ } } view_1=CloseCacheView(view_1); view_2=CloseCacheView(view_2); - if (y < (long) source->rows) + if (y < (ssize_t) source->rows) { /* an exception was thrown */ }Recall that each image format is decoded by ImageMagick and the pixels are deposited in the pixel cache. If you write an image, the pixels are read from the pixel cache and encoded as required by the format you are writing (e.g. GIF, PNG, etc.). The Magick Persistent Cache (MPC) format is designed to eliminate the overhead of decoding and encoding pixels to and from an image format. MPC writes two files. One, with the extension .mpc, retains all the properties associated with the image or image sequence (e.g. width, height, colorspace, etc.) and the second, with the extension .cache, is the pixel cache in the native raw format. When reading an MPC image file, ImageMagick reads the image properties and memory maps the pixel cache on disk eliminating the need for decoding the image pixels. The tradeoff is in disk space. MPC is generally larger in file size than most other image formats.
+The most efficient use of MPC image files is a write-once, read-many-times pattern. For example, your workflow requires extracting random blocks of pixels from the source image. Rather than re-reading and possibly decompressing the source image each time, we use MPC and map the image directly to memory.
ImageMagick supports artifacts with the GetImageArtifact() and SetImageArtifact() methods. Artifacts are stealth properties that are not exported to image formats (e.g. PNG) and they do not display when identifying an image.
+ImageMagick supports artifacts with the GetImageArtifact() and SetImageArtifact() methods. Artifacts are stealth properties that are not exported to image formats (e.g. PNG).
Image profiles are handled with GetImageProfile(), SetImageProfile(), and ProfileImage() methods. Here we set a profile and fetch it right back:
@@ -545,7 +548,7 @@ image=ReadStream(image_info,&StreamHandler,exception);Many of ImageMagick's internal algorithms are threaded to take advantage of speed-ups offered by the multicore processor chips. However, you are welcome to use ImageMagick algorithms in your threads of execution with the exception of the MagickCore's GetVirtualPixels(), GetAuthenticPixels(), QueueAuthenticPixels(), or SyncAuthenticPixels() pixel cache methods. These methods are intended for one thread of execution only. To access the pixel cache with more than one thread of execution, use a cache view. We do this for the CompositeImage() method, for example. Suppose we want to composite a single image over a different image in each thread of execution. If we use GetVirtualPixels(), the results are unpredictable because multiple threads would likely be asking for different areas of the pixel cache simultaneously. Instead we use GetCacheViewVirtualPixels() which creates a unique view for each thread of execution ensuring our program behaves properly regardless of how many threads are invoked. The other program interfaces, such as the MagickWand API, are completely thread safe so there are no special precautions for threads of execution.
+Many of ImageMagick's internal algorithms are threaded to take advantage of speed-ups offered by the multicore processor chips. However, you are welcome to use ImageMagick algorithms in your threads of execution with the exception of the MagickCore's GetVirtualPixels(), GetAuthenticPixels(), QueueAuthenticPixels(), or SyncAuthenticPixels() pixel cache methods. These methods are intended for one thread of execution only with the exception of an OpenMP parallel section. To access the pixel cache with more than one thread of execution, use a cache view. We do this for the CompositeImage() method, for example. Suppose we want to composite a single image over a different image in each thread of execution. If we use GetVirtualPixels(), the results are unpredictable because multiple threads would likely be asking for different areas of the pixel cache simultaneously. Instead we use GetCacheViewVirtualPixels() which creates a unique view for each thread of execution ensuring our program behaves properly regardless of how many threads are invoked. The other program interfaces, such as the MagickWand API, are completely thread safe so there are no special precautions for threads of execution.
Here is an example of how ImageMagick can take advantage of threads of execution with the OpenMP programming paradigm:
@@ -555,26 +558,26 @@ image=ReadStream(image_info,&StreamHandler,exception); CacheView *image_view; - long - y; - MagickBooleanType status; + ssize_t + y; + status=MagickTrue; image_view=AcquireCacheView(image); #pragma omp parallel for schedule(dynamic,4) shared(status) - for (y=0; y < (long) image->rows; y++) + for (y=0; y < (ssize_t) image->rows; y++) { register IndexPacket *indexes; - register long - x; - register PixelPacket *q; + register ssize_t + x; + if (status == MagickFalse) continue; q=GetCacheViewAuthenticPixels(image_view,0,y,image->columns,1,exception); @@ -584,7 +587,7 @@ image=ReadStream(image_info,&StreamHandler,exception); continue; } indexes=GetCacheViewAuthenticIndexQueue(image_view); - for (x=0; x < (long) image->columns; x++) + for (x=0; x < (ssize_t) image->columns; x++) { q->red= ... q->green= ... @@ -607,9 +610,22 @@ image=ReadStream(image_info,&StreamHandler,exception);If you call the ImageMagick API from your OpenMP-enabled application and you intend to dynamically increase the number of threads available in subsequent parallel regions, be sure to perform the increase before you call the API otherwise ImageMagick may fault.
-MagickWand support wand views. A view iterates over the entire, or portion, of the image in parallel and for each row of pixels, it invokes a callback method you provide. This limits most of your parallel programming activity to just that one module. There are similar methods in MagickCore. For an example, see the same sigmoidal contrast algorithm implemented in both MagickWand and MagickCore.
+MagickWand supports wand views. A view iterates over the entire, or portion, of the image in parallel and for each row of pixels, it invokes a callback method you provide. This limits most of your parallel programming activity to just that one module. There are similar methods in MagickCore. For an example, see the same sigmoidal contrast algorithm implemented in both MagickWand and MagickCore.
+ +In most circumstances, the default number of threads is set to the number of processor cores on your system for optimal performance. However, if your system is hyperthreaded or if you are running on a virtual host and only a subset of the processors are available to your server instance, you might get an increase in performance by setting the thread policy or the MAGICK_THREAD_LIMIT environment variable. For example, your virtual host has 8 processors but only 2 are assigned to your server instance. The default of 8 threads can cause severe performance problems. One solution is to limit the number of threads to the available processors in your policy.xml configuration file:
+ ++ <policy domain="resource" name="thread" value="2"/> ++ +
Or suppose your 12 core hyperthreaded computer defaults to 24 threads. Set the MAGICK_THREAD_LIMIT environment variable and you will likely get improved performance:
+ ++ export MAGICK_THREAD_LIMIT=12 +
The OpenMP committee has not defined the behavior of mixing OpenMP with other threading models such as Posix threads. However, using modern releases of Linux, OpenMP and Posix threads appear to interoperate without complaint. If you want to use Posix threads from a program module that calls one of the ImageMagick application programming interfaces (e.g. MagickCore, MagickWand, Magick++, etc.) from Mac OS X or an older Linux release, you may need to disable OpenMP support within ImageMagick. Add the --disable-openmp option to the configure script command line and rebuild and reinstall ImageMagick.
+