1.. -*- mode: rst -*-
2.. This text is in reStucturedText format, so it may look a bit odd.
3.. See http://docutils.sourceforge.net/rst.html for details.
4
5=====================
6Magick::Montage Class
7=====================
8
9A montage is a single image which is composed of thumbnail images
10composed in a uniform grid. The size of the montage image is
11determined by the size of the individual thumbnails and the number of
12rows and columns in the grid.
13
14The following illustration shows a montage consisting of three columns
15and two rows of thumbnails rendered on a gray background:
16
17.. image:: montage-sample-framed.jpg
18   :width: 378px
19   :height: 238px
20   :scale: 100%
21   :align: center
22   :alt: Figure showing framed montage
23
24Montages may be either "plain" (undecorated thumbnails) or "framed"
25(decorated thumbnails). In order to more easily understand the options
26supplied to MontageImages(), montage options are supplied by two
27different classes: Magick::Montage and Magick::MontageFramed.
28
29Plain Montages
30--------------
31
32Magick::Montage is the base class to provide montage options and
33provides methods to set all options required to render simple
34(unframed) montages. See Magick::MontageFramedif you would like to
35create a framed montage.
36
37Unframed thumbnails consist of four components: the thumbnail image,
38the thumbnail border, an optional thumbnail shadow, and an optional
39thumbnail label area.
40
41.. image:: thumbnail-anatomy-plain.jpg
42   :width: 309px
43   :height: 327px
44   :scale: 100%
45   :align: center
46   :alt: Figure showing plain montage
47
48The following is the definition of the Magick::Montage class::
49
50  class Montage
51  {
52  public:
53    Montage( void );
54    virtual ~Montage( void );
55
56    // Specifies the background color that thumbnails are imaged upon.
57    void              backgroundColor ( const Color &backgroundColor_ );
58    Color             backgroundColor ( void ) const;
59
60    // Specifies the image composition algorithm for thumbnails. This
61    // controls the algorithm by which the thumbnail image is placed
62    // on the background. Use of OverCompositeOp is recommended for
63    // use with images that have transparency. This option may have
64    // negative side-effects for images without transparency.
65    void              compose ( CompositeOperator compose_ );
66    CompositeOperator compose ( void ) const;
67
68    // Specifies the image filename to be used for the generated
69    // montage images. To handle the case were multiple montage images
70    // are generated, a printf-style format may be embedded within the
71    // filename. For example, a filename specification of
72    // image%02d.miff names the montage images as image00.miff,
73    // image01.miff, etc.
74    void              fileName( const std::string &fileName_ );
75    std::string       fileName( void ) const;
76
77    // Specifies the fill color to use for the label text.
78    void              fillColor ( const Color &fill_ );
79    Color             fillColor ( void ) const;
80
81    // Specifies the thumbnail label font.
82    void              font ( const std::string &font_ );
83    std::string       font ( void ) const;
84
85    // Specifies the size of the generated thumbnail.
86    void              geometry ( const Geometry &geometry_ );
87    Geometry          geometry ( void ) const;
88
89    // Specifies the thumbnail positioning within the specified
90    // geometry area. If the thumbnail is smaller in any dimension
91    // than the geometry, then it is placed according to this
92    // specification
93    void              gravity ( GravityType gravity_ );
94    GravityType       gravity ( void ) const;
95
96    // Specifies the format used for the image label. Special format
97    // characters may be embedded in the format string to include
98    // information about the image.
99    void              label( const std::string &label_ );
100    std::string       label( void ) const;
101
102    // Specifies the pen color to use for the label text (same as fill).
103    void              penColor ( const Color &pen_ );
104    Color             penColor ( void ) const;
105
106    // Specifies the thumbnail label font size.
107    void              pointSize ( unsigned int pointSize_ );
108    unsigned int      pointSize ( void ) const;
109
110    // Enable/disable drop-shadow on thumbnails.
111    void              shadow ( bool shadow_ );
112    bool              shadow ( void ) const;
113
114    // Specifies the stroke color to use for the label text .
115    void              strokeColor ( const Color &stroke_ );
116    Color             strokeColor ( void ) const;
117
118    // Specifies a texture image to use as montage background. The
119    // built-in textures "granite:" and "plasma:" are available. A
120    // texture is the same as a background image.
121    void              texture ( const std::string &texture_ );
122    std::string       texture ( void ) const;
123
124    // Specifies the maximum number of montage columns and rows in the
125    // montage. The montage is built by filling out all cells in a row
126    // before advancing to the next row. Once the montage has reached
127    // the maximum number of columns and rows, a new montage image is
128    // started.
129    void              tile ( const Geometry &tile_ );
130    Geometry          tile ( void ) const;
131
132    // Specifies the montage title
133    void              title ( const std::string &title_ );
134    std::string       title ( void ) const;
135
136    // Specifies a montage color to set transparent. This option can
137    // be set the same as the background color in order for the
138    // thumbnails to appear without a background when rendered on an
139    // HTML page. For best effect, ensure that the transparent color
140    // selected does not occur in the rendered thumbnail colors.
141    void              transparentColor ( const Color &transparentColor_ );
142    Color             transparentColor ( void ) const;
143
144  };
145
146Framed Montages
147---------------
148
149Magick::MontageFramed provides the means to specify montage options
150when it is desired to have decorative frames around the image
151thumbnails. MontageFramed inherits from Montage and therefore provides
152all the methods of Montage as well as those shown in the table
153"MontageFramed Methods".
154
155Framed thumbnails consist of four components: the thumbnail image, the
156thumbnail frame, the thumbnail border, an optional thumbnail shadow,
157and an optional thumbnail label area.
158
159.. image:: thumbnail-anatomy-framed.jpg
160   :width: 350px
161   :height: 345px
162   :scale: 100%
163   :align: center
164   :alt: Figure showing anatomy of a framed montage
165
166The following is the definition of the Magick::MontageFramed class::
167
168  class MontageFramed : public Montage
169  {
170  public:
171    MontageFramed ( void );
172    /* virtual */ ~MontageFramed ( void );
173
174    // Specifies the background color within the thumbnail frame.
175    void           borderColor ( const Color &borderColor_ );
176    Color          borderColor ( void ) const;
177
178    // Specifies the border (in pixels) to place between a thumbnail
179    // and its surrounding frame. This option only takes effect if
180    // thumbnail frames are enabled (via frameGeometry) and the
181    // thumbnail geometry specification doesn't also specify the
182    // thumbnail border width.
183    void           borderWidth ( unsigned int borderWidth_ );
184    unsigned int   borderWidth ( void ) const;
185
186    // Specifies the geometry specification for frame to place around
187    // thumbnail. If this parameter is not specified, then the montage
188    // is unframed.
189    void           frameGeometry ( const Geometry &frame_ );
190    Geometry       frameGeometry ( void ) const;
191
192    // Specifies the thumbnail frame color.
193    void           matteColor ( const Color &matteColor_ );
194    Color          matteColor ( void ) const;
195
196  };
197
198.. |copy|   unicode:: U+000A9 .. COPYRIGHT SIGN
199
200Copyright |copy| Bob Friesenhahn 1999 - 2020
201