<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Linux/x86 (vers 1st March 2005), see www.w3.org" />
<title>RMagick: ImageMagick/GraphicsMagick 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) 2005 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>
</head>
<body>
<h6 id="header">RMagick User's Guide and Reference</h6>
<div class="nav">
« <a href="usage.html">Prev</a> | <a href=
"index.html">Contents</a> | <a href=
"comtasks.html">Next</a> »
</div>
<h1>RMagick: ImageMagick/GraphicsMagick 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="#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>×Magick supports over 90 major <a href=
"http://www.imagemagick.org/script/formats.php">image
formats</a>.</p>
<p>×Magick 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 ×Magick, not written.</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 X color name such as "red", "chocolate", or
"lightslategray". (On Linux and FreeBSD, the master list is
usually <code>/usr/X11R6/lib/X11/rgb.txt</code>.)</li>
<li>an <a href=
"http://www.w3.org/TR/SVG/types.html#ColorKeywords">SVG color
name</a> (similar to the X color names), or</li>
<li>a hex digit string in one of the formats shown in the
following table.</li>
</ol>
<table id="rgbfmts" summary="RGB formats">
<caption>
RGB 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>rgb(r,g,b)</td>
<td>SVG functional notation. r, g, and b are either three
integers 0-255 or 3 percentanges 0%-100%.</td>
</tr>
<tr class="evenrow">
<td>rgb(r,g,b,a)</td>
<td>SVG functional notation 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 MaxRGB
(Magick::TransparentOpacity).</p>
<p>A <code>Pixel</code> object contains the numeric
representation of a color. The <a href=
"struct.html#Pixel.from_color">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.to_color">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
depth and <a href="imageattrs.html#matte">matte</a> attributes.
If <code>matte</code> is false the opacity value is ignored.</p>
<p><em>Hint:</em> You can specify the transparent color as
"none", "transparent", or "#000000ff".</p>
<p><a href=
"http://www.imagemagick.org/script/command-line-options.php#fill">
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=
"http://www.imagemagick.org/script/command-line-options.php#geometry">
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>
</div>
<p>The x and y offsets, if present, can be preceeded 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>×Magick 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_eq">class_type=</a></code>
method.</p>
<h2 id="builtin_formats">Built-in image formats</h2>
<p>Some of the image formats that ×Magick supports are
special-purpose formats that are built-in to ×Magick
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">
i = Image.read("gradient:red-blue") { self.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, ×Magick 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>
</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 ×Magick 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>ImageMagick 5.5.7-3 introduced the <code>pattern:</code>
format. 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=
"http://www.imagemagick.org/script/formats.php">this
page.</a></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="comtasks.html">Next</a>
»
</div>
</body>
</html>