-
Notifications
You must be signed in to change notification settings - Fork 2
/
imusage.html
481 lines (358 loc) · 17.1 KB
/
imusage.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta name="generator" content="HTML Tidy for Linux/x86 (vers 1 September 2005), see www.w3.org" />
<title>RMagick 6.0.1: ImageMagick Conventions</title>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta name="GENERATOR" content="Quanta Plus" />
<meta name="Copyright" content="Copyright (C) 2006 by Timothy P. Hunter" />
<link rel="stylesheet" type="text/css" href="css/doc.css" />
<script type="text/javascript" src="scripts/doc.js"></script>
<style type="text/css">
/*<![CDATA[*/
/* Styles local to this page. */
/*
* Modify the example style for the scripts on this page.
*/
.example {
margin-left: 100px;
margin-right: 100px;
margin-bottom: 1em;
}
#rgbfmts {
border-collapse: separate;
border-spacing: 0;
border: thin solid black;
background-color: #f0f0f0;
margin: 1em auto 1em auto;
width: 70%;
}
#rgbfmts td {
padding: 3px 1em 3px 1em;
border-width: 0;
}
#rgbfmts caption {
font-weight: bold;
}
.evenrow {
background-color: #f0f0f0;
}
.oddrow {
background-color: white;
}
#geostr {
width: 100%;
font-weight: bold;
text-align: center;
}
#bi_format_list {
margin-left: 100px;
}
#bi_format_list h4 {
padding-left: 5px;
position: relative;
left: -100px;
background-image: url(ex/images/graydient230x6.gif);
background-repeat: repeat-y;
}
/*]]>*/
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github.min.css" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
<script>
hljs.configure({ cssSelector: "pre" });
hljs.highlightAll();
</script>
</head>
<body>
<h6 id="header">RMagick 6.0.1 User's Guide and Reference</h6>
<div class="nav">« <a href="usage.html">Prev</a> | <a href="index.html">Contents</a> | <a href="optequiv.html">Next</a> »</div>
<h1>RMagick: ImageMagick Conventions</h1>
<div id="toc">
<h2>Table of Contents</h2>
<ul style="margin-left: 15px; padding-top: 1em">
<li><a href="#formats">Image formats and filenames</a></li>
<li>
<a href="#frames">Selecting frames from a multi-frame image file</a>
</li>
<li><a href="#color_names">Color names</a></li>
<li><a href="#geometry">The geometry string</a></li>
<li><a href="#classtype">DirectClass and PseudoClass</a></li>
<li><a href="#builtin_formats">Built-in image formats</a></li>
</ul>
</div>
<h2 id="formats">Image formats and filenames</h2>
<p>
ImageMagick supports over 100 major
<a href="https://www.imagemagick.org/script/formats.php">image formats</a>.
</p>
<p>
ImageMagick determines the format (GIF, PNG, JPEG, etc.) of an image file either from its magic number, the filename suffix (.gif, .png, .jpg) or from a
prefix attached to the filename. For example,
<code>ps:mydoc</code> indicates that <code>mydoc</code> is a Postscript file.
<span class="imquote"
>The magic number takes precedence over the filename suffix and the prefix takes precedence over the magic number and the suffix in input files. The
prefix takes precedence over the filename suffix in output files.</span
>
</p>
<p>
This makes it easy to convert an image file to another format. Simply write the image file using a name that has either a prefix or a suffix corresponding
to the format you want.
</p>
<p><em>Note:</em> Keep in mind that files in some formats may only be read by ImageMagick, not written.</p>
<h2 id="frames">Selecting frames from a multi-frame image file</h2>
<p>
When reading a multi-frame image file such as an AVI you can specify the subset of frames by adding a list of frame number(s) to the end of the file name
enclosed in square brackets. For example, "my_movie.avi[0]" tells ImageMagick to read only the first frame. In general,
</p>
<dl>
<dt>[N]</dt>
<dd>identifies a single frame. Frame numbers start at 0. Negative numbers cause frames to be selected from the end of the image file.</dd>
<dt>[M,N,O]</dt>
<dd>identifies multiple non-sequential frame numbers.</dd>
<dt>[N-M]</dt>
<dd>identifies the sequence of frames numbered N through M.</dd>
<dt>[M,N-O,P]</dt>
<dd>identifies both non-sequential and sequential frame numbers</dd>
</dl>
<p>
Note that the entire image file will be read into memory before the frames are selected. See
<a href="https://www.imagemagick.org/Usage/files/#read"> this page</a>
for additional uses of the [] modifier.
</p>
<h2 id="color_names">Color names</h2>
<p>Many RMagick methods expect color name arguments or return color names. A color name can be</p>
<ol>
<li>
an
<a href="https://en.wikipedia.org/wiki/X11_color_names">X11 color name</a>
such as "red", "chocolate", or "lightslategray".
</li>
<li>
an
<a href="https://www.w3.org/TR/SVG/types.html#ColorKeywords">SVG color name</a>
(similar to the X color names), or
</li>
<li>a string in one of the formats shown in the following table.</li>
</ol>
<table id="rgbfmts" summary="color name formats">
<caption>
Color name formats
</caption>
<tr class="oddrow">
<td>#RGB</td>
<td>4 bits for each channel</td>
</tr>
<tr class="evenrow">
<td>#RRGGBB</td>
<td>8 bits for each channel</td>
</tr>
<tr class="oddrow">
<td>#RRRGGGBBB</td>
<td>12 bits for each channel</td>
</tr>
<tr class="evenrow">
<td>#RRRRGGGGBBBB</td>
<td>16 bits for each channel</td>
</tr>
<tr class="oddrow">
<td>#RGBA</td>
<td>4 bits for each channel, plus the alpha channel</td>
</tr>
<tr class="evenrow">
<td>#RRGGBBAA</td>
<td>8 bits for each channel, plus the alpha channel</td>
</tr>
<tr class="oddrow">
<td>#RRRGGGBBBAAA</td>
<td>12 bits for each channel, plus the alpha channel</td>
</tr>
<tr class="evenrow">
<td>#RRRRGGGGBBBBAAAA</td>
<td>16 bits for each channel, plus the alpha channel</td>
</tr>
<tr class="oddrow">
<td>cmyk(c,m,y,k)</td>
<td>CMYK functional notation. c, m, y, and k are either 4 integers 0-QuantumRange or 4 percentages 0%-100%.</td>
</tr>
<tr class="evenrow">
<td>cmyka(c,m,y,a)</td>
<td>CMYK functional notation plus the alpha channel.</td>
</tr>
<tr class="oddrow">
<td>rgb(r,g,b)</td>
<td>SVG functional notation. r, g, and b are either 3 integers 0-QuantumRange or 3 percentages 0%-100%.</td>
</tr>
<tr class="evenrow">
<td>rgba(r,g,b,a)</td>
<td>SVG functional notation plus the alpha channel.</td>
</tr>
<tr class="oddrow">
<td>hsl(h,s,l)</td>
<td>
Hue, saturation, lightness. The <em>hue</em> value (h) should be a number in the range 0 <= n < 360. The <em>saturation</em> (s) and
<em>lightness</em> (l) values should be numbers in the range 0 <= n <= 100.
</td>
</tr>
<tr class="evenrow">
<td>hsla(h,s,l,a)</td>
<td>Hue, saturation, lightness, plus the alpha channel.</td>
</tr>
</table>
<p>The alpha channel is the opacity of the image, which can range from 0 (Magick::OpaqueOpacity) to QuantumRange (Magick::TransparentOpacity).</p>
<p>
A <code>Pixel</code> object contains the numeric representation of a color. The <a href="struct.html#Pixel">Pixel.from_color</a> method converts a color
name to a pixel. There are two methods to convert a pixel to a color name. The <a href="struct.html#Pixel">Pixel#to_color</a> method requires that you
specify whether the alpha (opacity) channel is used, the depth (8 or 16) and the color standard to use. The
<a href="image3.html#to_color">Image#to_color</a> method uses the image's <a href="imageattrs.html#depth">depth</a> attribute and
<a href="image1.html#alpha">alpha</a> method.
</p>
<p><em>Hint:</em> You can specify the transparent color as "none", "transparent", "#00000000", or rgba(0, 0, 0, 0.0).</p>
<p><a href="https://www.imagemagick.org/script/color.php">This</a> is ImageMagick's page about color names.</p>
<h2 id="geometry">The geometry string</h2>
<p>
RMagick methods frequently require a <code>geometry</code> string argument. This string generally specifies width and height values as well as x and y
offset values. The values are usually specified in pixels (but see the % flag, below).
</p>
<p>This is the format of the geometry string. Any of the values may be omitted, depending on the context:</p>
<pre id="geostr">
<width>x<height>+-<x>+-<y>{%@!<>}
</pre
>
<p>
<a href="https://www.imagemagick.org/script/command-line-options.php#resize"> This</a>
is the ImageMagick description of the geometry string:
</p>
<div class="imquote">
<p>
By default, the width and height are maximum values. That is, the image is expanded or contracted to fit the width and height value while maintaining
the aspect ratio of the image. Append an exclamation point to the geometry to force the image size to exactly the size you specify. For example, if you
specify 640x480! the image width is set to 640 pixels and height to 480.
</p>
<p>
If only the width is specified, the width assumes the value and the height is chosen to maintain the aspect ratio of the image. Similarly, if only the
height is specified (e.g., "x256"), the width is chosen to maintain the aspect ratio. To specify a percentage width or height instead, append %. The
image size is multiplied by the width and height percentages to obtain the final image dimensions. To increase the size of an image, use a value greater
than 100 (e.g. 125%). To decrease an image's size, use a percentage less than 100.
</p>
<p>Use @ to specify the maximum area in pixels of an image.</p>
<p>
Use > to change the dimensions of the image only if its width or height exceeds the geometry specification. < resizes the image only if both of
its dimensions are less than the geometry specification. For example, if you specify '640x480>' and the image size is 256x256, the image size does
not change. However, if the image is 512x512 or 1024x1024, it is resized to 480x480.
</p>
<p>
Use ^ to set a minimum image size limit. The geometry 640x480^, for example, means the image width will not be less than 640 and the image height will
not be less than 480 pixels after the resize. One of those dimensions will match the requested size, but the image will likely overflow the space
requested to preserve its aspect ratio.
</p>
</div>
<p>
The x and y offsets, if present, can be preceded with either a + or - sign. The + causes x and y to be measured from the left or top edges, respectively.
Conversely, - measures from the right or bottom edges. Offsets are always measured in pixels.
</p>
<p>
Any method that accepts a geometry string will also accept a
<a href="struct.html#Geometry"><code>Geometry</code></a>
object.
</p>
<p>
Some RMagick methods interpret the geometry string values differently. Where this is the case the documentation for the method will explain the
differences.
</p>
<h2 id="classtype">DirectClass and PseudoClass</h2>
<p>ImageMagick classifies all images into two <em>classes</em>, PseudoClass and DirectClass.</p>
<div class="imquote">
<p>
DirectClass images are continuous-tone images stored as RGB (red, green, blue), RGBA (red, green, blue, alpha), or CMYK (cyan, yellow, magenta, black)
intensity values as defined by the
<code>colorspace</code> [attribute].
</p>
<p>
PseudoClass images are colormapped RGB images. The colormap is stored as a series of red, green, and blue pixel values, each value being a byte in size.
If the image depth is 16, each colormap entry consumes two bytes with the most significant byte being first. The number of colormap entries is defined
by the <code>colors</code> [attribute].
</p>
</div>
<p>
GIF format images are PseudoClass. JPEG format images are DirectClass. You can change the class of a image with the
<code><a href="imageattrs.html#class_type">class_type</a></code>
method.
</p>
<h2 id="builtin_formats">Built-in image formats</h2>
<p>
Some of the image formats that ImageMagick supports are special-purpose formats that are built-in to ImageMagick itself. That is, even though you can
"read" images in these formats, they do not correspond to any real image files.
</p>
<p>
These are the built-in formats that I know something about. (There are more but I've never used them.) When the format is marked with an
<sup>*</sup>, you must supply the desired size of the image in order to "read" it. Specify the size by assigning a string in the form "WxH" to the
<code>size</code> attribute in the <code>read</code> method's additional parms block. For example, to create a image in the gradient format that is 100
pixels wide and 200 pixels high, use:
</p>
<pre class="example language-ruby">i = Magick::Image.read("gradient:red-blue") { |options| options.size = "100x200" }</pre>
<p>See <a href="javascript:popup('demo.rb.html')">demo.rb</a> for more examples of reading built-in formats.</p>
<div id="bi_format_list">
<h4>caption<sup>*</sup></h4>
<p>The caption format is used to create an image from a text string. Ex: "caption:My caption text".</p>
<p>
If you specify only the width in the <code>size</code> argument, ImageMagick will wrap the text and compute the necessary height. In addition to
<code>size</code> (which is required) you can use the following <a href="info.html">optional arguments</a>:
</p>
<ul>
<li>antialias</li>
<li>background_color</li>
<li>border_color</li>
<li>density</li>
<li>fill</li>
<li>font</li>
<li>gravity</li>
<li>pointsize</li>
<li>stroke</li>
<li>stroke_width</li>
<li>undercolor</li>
</ul>
<h4>gradient<sup>*</sup></h4>
<p>
Gradient filenames have the form <code>"gradient:color1-color2"</code>. These images are created by gradually changing from <code>color1</code> at the
top edge to <code>color2</code> at the bottom. Don't confuse this image format with the <a href="struct.html#GradientFill">GradientFill</a> class, which
is part of RMagick.
</p>
<h4>granite</h4>
<p>
A mottled gray image suitable for use as a tiled background texture. Ex:
<code>"granite:"</code>.
</p>
<h4>logo</h4>
<p>The ImageMagick logo. Ex: <code>"logo:"</code>.</p>
<h4>netscape</h4>
<p>The 216-color "Web safe" cube. Ex: <code>"netscape:"</code>.</p>
<h4>null<sup>*</sup></h4>
<p>An empty image. Ex: <code>"null:"</code>.</p>
<h4>pattern</h4>
<p>
This format supplies a number of built-in patterns that may be referenced by specifying the pattern name. For example,
<code>pattern:checkerboard</code>. For a list of acceptable patterns, see
<a href="https://www.imagemagick.org/script/formats.php">this page.</a>
If you do not specify a size the pattern's default size is used. If you specify a size the pattern will be repeated as necessary to fill the image.
</p>
<h4>plasma<sup>*</sup></h4>
<p>
Creates a swirly, psychedelic image. Specify a pair of colors in the filename (<code>"plasma:red-blue"</code>) or specify the filename
<code>"plasma:fractal"</code> for best results.
</p>
<h4>rose</h4>
<p>A small picture of a rose. Ex: <code>"rose:"</code>.</p>
<h4>xc<sup>*</sup></h4>
<p>
Specify a <a href="#color_names">color name</a> after the xc: prefix. For example, <code>"xc:red"</code>. This format is simply an image of the
specified color. You can get exactly the same results by specifying the background color when creating an image.
</p>
</div>
<p class="spacer"></p>
<div class="nav">
« <a href="usage.html">Prev</a> | <a href="index.html">Contents</a> | <a href="optequiv.html">Next</a>
»
</div>
</body>
</html>