The ImageMagick graphics library
A gentle introduction to Magick++
Rev 1.0.5
1 About this document
This document is an introductory tutorial to the free-software Magick++ C++ graphics library, and
it thus covers only the basic Magick++ methods for image manipulation. For a complete reference
guide to the Magick++ library the reader is advised to consult the original library documentation,
as well as various application notes that address specific functionalities (these are freely available
on the internet).
This document has been written such that it gradually introduces the various concepts that the
Magick++ library is based upon: it starts with a brief overview of the library and how it is meant to
be used as a component inside an application, continues with describing the meaning of a Canvas
as the drawing area utilized by the Magick++ library, then it presents some essential
characteristics of an Image object (which is itself based on the concept of Canvas), and ends with
a detailed presentation of a collection of methods that the Image object provides for image
generation, manipulation, and storage.
Only a limited set of Magick++ image manipulation methods is covered in this tutorial, but this set
does however provide the necessary image manipulation tools for a large number of applications,
including web-based server applications that need to generate dynamic images for embedding in
web pages (e.g. pie charts, wire graphs, bar graphs, annotated pictures, etc).
IMPORTANT:
The reader is assumed to be familiar with all the C++ terminology that is being used
throughout this document.
License
This document is Copyright (c) Information Technology Group www.itgroup.ro
(c) Alin Avasilcutei, Cornel Paslariu, Lucian Ungureanu, Virgil Mager.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
with no Invariant Sections, no Front-Cover Texts, no Back-Cover Texts.
2 Introducing the Magick++ library
The Magick++ library is a set of C++ wrapper classes that provides access to the ImageMagick
package functionality from within a C++ application.
ImageMagick is a free software package used for image manipulation, and it is available for al the
major operating systems: Linux, Windows, MacOS X, and UN*X. It includes a GUI for rendering
images, command line utilities for image processing, and APIs for many programming languages:
Magick++ (C++), MagickCore (C), MagickWand (C), ChMagick (Ch), JMagick (Java), L-Magick (Lisp),
PerlMagick (Perl), MagickWand for PHP (PHP), PythonMagick (Python), TclMagick (Tcl/TK).
➢ Note: ImageMagick is provided with automated installers for Linux, Windows, and MacOS X
ImageMagick is released under a license that is compatible with, but less restrictive than, the GNU
General Public License: significantly, ImageMagick may be included in, and used by, a software
package, fully or in part, with proper attribution and with the ImageMagick license file attached.
The Magick++ library can perform the following classes of operations on images:
● create new images, or read existing images,
● edit images : flip, mirror, rotate, scale, transform images, adjust image colors, apply
various special effects, or draw text, lines, polygons, arcs, ellipses and Bezier curves,
● compose new images based on other images,
● save images in a variety of formats, including GIF, JPEG, PNG, SVG, and PostScript.
Using the Magick++ library in an application
In order to use the Magick++ library in a C++ application one should first install the ImageMagick
package (the automated installers may be used). One needs to include the relevant header files in
the application's source(s), and link the application binary against the ImageMagick runtime libs:
● In the source files: after '#include <Magick++.h>' (in the application's files, as required),
add the 'using namespace Magick;' statement, or add the prefix 'Magick::' to each
Magick++ class/enumeration name.
● In a GNU environment the linker's LDFLAGS can be configured using the Magick++-config
script: `Magick++-config --cppflags --cxxflags --ldflags --libs`
N O T E : the ` character is the backquote character, it cannot be replaced with ' or " !
Fo r e x a m p l e , in A n j u t a 1. 2 . x (on a G N U O S) p a s t e t h e li n e a b o v e i n t h e 'S e t t i n g s - > C o m p i l e r
a n d Li n k e r S e t t i n g s - > O p t i o n s t a b -> A d d i t i o n a l O p t i o n s : Li n k e r Fl a g s (L D F L A G S ) ' b o x
● Windows applications can be built using a MSVC6+ compiler: they can be derived from one
of the demo projects, must ship with the ImageMagick DLLs and must “initialize the library”
prior to any Magick++ operation: InitializeMagick(path_to_ImageMagick_DLLs);
Library versions
ImageMagick and the Magick++ libraries are advertised as being under development at the time
of writing this document. As such, this document contains information about the functionality
provided by the library Version 6.2.5.4, based on actually testing the library API for this version.
It has been found during the tests that a number of advertised features work in an unpredictable
manner, or are inconsistent with the library specifications. A very hilarious example is the
DrawableRotation and DrawableTranslation objects that require 'angle/2' (instead of 'angle') and
'displacement/2' (instead of 'displacement') as arguments. If this could be regarded as some
hacker joke made by one of the library implementers, more serious problems seem to exist: for
example, the above two coordinate system transformations don't work together at all (they give
nonsensical effects when drawing objects on a canvas).
IMPORTANT:
This document only presents features that were effectively tested on Magick++ version 6.2.5.4
3 Images in the Magick++ library
In object oriented graphics, an image (also known as a 'digital image') is described by an object
featured with a self-rendering method. In the Magick++ implementation each such image object
always has an associated canvas which actually holds the picture data (or it may also be an empty
canvas, which is not the same with a "blank" canvas because in the latter case the canvas actually
holds a background color).
What is a Canvas
A canvas can be described from several perspectives:
● From visual point of view, a canvas represents a virtual surface where an application can
draw, paint or paste pieces of image.
● From the point of view of the internal representation, the canvas is stored as an array of
pixels (also known as a 'bitmap'), with each pixel being stored in an certain format (usually
based on the Red-Green-Blue-Alpha components, but other pixel formats may also be
implemented).
The Geometry class
A number of Magick++ methods use a parameter of type 'Geometry' for specifying (mostly) the
size of a rectangular object. The 'Geometry' class is relatively complex (actually reflecting the X11
geometry specification), but for the purpose of this tutorial it can be thought of as being a
mechanism that encapsulates two dimensions (x and y) into a single object which is further used
by Magick++ methods.
Geometry::Geometry(unsigned int x, unsigned int y);
Geometry::Geometry(const String& geometry);
// examples:
Geometry g1(100,200); // numeric constructor
Geometry g2(“300x400”); // string constructor
Pixels in Magick++ library
The PixelPacket structure
The data format of the pixel is of type 'PixelPacket'. The 'PixelPacket' is a C structure used to
represent pixels. The PixelPacket members are:
➢ 'red'
➢ 'green'
➢ 'blue'
➢ 'opacity' : this PixelPacket member defines the “opacity” of the pixel, thus allowing an
image to include transparency information (an example of image file format that is able of
preserving the image transparency information is the PNG format)
Quantizing levels: the Quantum type and the MaxRGB constant
Each member of the PixelPacket structure is an unsigned integer number, and depending on how
the library was compiled it may be implemented on 8 bits or 16 bits (i.e. the total size of a
PixelPacket is 4*8=32 bits or 4*16=64 bits); thus, the number of quantizing levels for each of the
PixelPacket components can be 2^8=256 or 2^16=65536.
In any case, Magick++ provides the applications with the 'MaxRGB' constant which always
specifies the number of quantizing levels - 1 as available on the particular version of the library
that is being used (e.g. for a library version compiled with 8 bits per PixelPacket component the
MaxRGB constant is 255).
In order to accommodate the implementation-specific values of quantizing levels, Magick++
provides the 'Quantum' data type. This type is an unsigned integer value that may be
implemented as unsigned char, unsigned short int, etc, but it is always guaranteed to be able of
holding all the quantizing levels as available on the particular version of the library that is being
used (i.e. it can always hold the 'MaxRGB' value).
The PixelPacket structure members are of type Quantum, and are in range [0, MaxRGB]:
struct PixelPacket {
Quantum red;
Quantum green;
Quantum blue;
Quantum opacity;
};
The Color class
The Magick++ library provides a class 'Color' that can be assigned to, and from, PixelPacket data
structures, thus facilitating an object-oriented approach for handling PixelPacket data structures.
The 'Color' class is also used as argument type by a number of Magick++ methods that set the
color attributes of various graphical operations.
The following table lists the most important Color methods:
// constructors
Color::Color();
Color::Color(const string& color); // the string 'color' is one of a set of "inbuilt"
// colors: "red", “blue”, "magenta", etc
Color::Color(Quantum red, // parameters in range 0 to MaxRGB
Quantum green,
Quantum blue,
Quantum alpha); // alpha is transparency: 0=opaque, MaxRGB=fully transparent
Color::Color(const PixelPacket& pixel);
// getter functions
Quantum Color::redQuantum();
Quantum Color::greenQuantum();
Quantum Color::blueQuantum();
Quantum Color::alphaQuantum();
// setter functions
void Color::redQuantum(Quantum red);
void Color::greenQuantum(Quantum green);
void Color::blueQuantum(Quantum blue);
void Color::alphaQuantum(Quantum alpha);
// conversion functions to and from PixelPacket
Color::operator PixelPacket() const;
const Color& Color::operator=(const PixelPacket& pixel);
评论0