| <?xml version="1.0" encoding="utf-8" ?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>Magick++ API: Geometry</title> |
| <link rel="stylesheet" href="magick.css" type="text/css" /> |
| </head> |
| <body> |
| <div class="doc-section"> |
| <h1 align="center">Magick::Geometry</h1> |
| <p>Geometry provides a convenient means to specify a geometry |
| argument. The object may be initialized from a C string or C++ string |
| containing a geometry specification. It may also be initialized by |
| more efficient parameterized constructors. |
| </p> |
| <h3><a name="GeometrySpecifications"></a>Geometry |
| Specifications</h3> |
| <p>Geometry specifications are in the form |
| <kbd>"<width>x<height>{+-}<xoffset>{+-}<yoffset>"</kbd> |
| (where <i>width</i>, <i>height</i>, <i>xoffset</i>, and <i>yoffset</i> |
| are numbers) for specifying the size and placement location for an |
| object. |
| </p> |
| <p style="margin-bottom: 0in">The <i>width</i> and <i>height</i> |
| parts of the geometry specification are measured in pixels. The |
| <i>xoffset</i> and <i>yoffset</i> parts are also measured in pixels |
| and are used to specify the distance of the placement coordinate from |
| the left and top and edges of the image, respectively. Both types of |
| offsets are measured from the indicated edge of the object to the |
| corresponding edge of the image. The X offset may be specified in the |
| following ways: |
| </p> |
| <table width="90%" border="1" cellpadding="2" cellspacing="3"> |
| <col width="21*" /> |
| <col width="235*" /> |
| <tr> |
| <td width="8%"> |
| <p>+<i>xoffset</i></p> |
| </td> |
| <td width="92%"> |
| <p>The left edge of the object is to be placed <i>xoffset</i> |
| pixels in from the <em>left edge </em>of the image.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="8%"> |
| <p>-<i>xoffset</i></p> |
| </td> |
| <td width="92%"> |
| <p>The left edge of the object is to be placed outside the image, |
| <i>xoffset</i> pixels out from the <em>left edge </em>of the image.</p> |
| </td> |
| </tr> |
| </table> |
| <p style="margin-bottom: 0in">The Y offset has similar meanings: |
| </p> |
| <table width="90%" border="1" cellpadding="2" cellspacing="3"> |
| <col width="27*" /> |
| <col width="229*" /> |
| <tr> |
| <td width="11%"> |
| <p>+<i>yoffset</i></p> |
| </td> |
| <td width="89%"> |
| <p>The top edge of the object is to be <i>yoffset</i> pixels |
| <em>below</em> the <em>top edge </em>of the image.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="11%"> |
| <p>-<i>yoffset</i></p> |
| </td> |
| <td width="89%"> |
| <p>The top edge of the object is to be <i>yoffset</i> pixels |
| <em>above</em> the <em>top edge</em> of the image.</p> |
| </td> |
| </tr> |
| </table> |
| <p>Offsets must be given as pairs; in other words, in order to |
| specify either <i>xoffset</i> or <i>yoffset</i> both must be present. |
| </p> |
| <h3><a name="ExtendedGeometrySpecifications"></a>ImageMagick |
| Extensions To Geometry Specifications</h3> |
| <p style="margin-bottom: 0in">ImageMagick has added a number of |
| qualifiers to the standard geometry string for use when resizing |
| images. The form of an extended geometry string is |
| "<kbd><width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>}"</kbd>. |
| Extended geometry strings should <em>only</em> be used <em>when resizing |
| an image</em>. Using an extended geometry string for other |
| applications may cause the API call to fail. The available |
| qualifiers are shown in the following table: |
| </p> |
| <p align="center" STYLE="margin-bottom: 0in"><b>ImageMagick Geometry |
| Qualifiers</b></p> |
| <table width="90%" border="1" cellpadding="2" cellspacing="3"> |
| <col width="36*" /> |
| <col width="220*" /> |
| <tr> |
| <td width="14%"> |
| <p align="center"><b>Qualifier</b></p> |
| </td> |
| <td width="86%"> |
| <p align="center"><b>Description</b></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="14%"> |
| <p align="center"><b>%</b></p> |
| </td> |
| <td width="86%"> |
| <p>Interpret width and height as a <b>percentage</b> of the |
| current size.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="14%"> |
| <p align="center"><b>!</b></p> |
| </td> |
| <td width="86%"> |
| <p>Resize to width and height <b>exactly</b>, loosing original |
| aspect ratio.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="14%"> |
| <p align="center"><b><</b></p> |
| </td> |
| <td width="86%"> |
| <p>Resize only if the image is <b>smaller</b> than the geometry |
| specification.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="14%"> |
| <p align="center"><b>></b></p> |
| </td> |
| <td width="86%"> |
| <p>Resize only if the image is <b>greater</b> than the geometry |
| specification.</p> |
| </td> |
| </tr> |
| </table> |
| <h3><a name="PostscriptPageSize"></a>Postscript Page Size Extension |
| To Geometry Specifications</h3> |
| <p>Any geometry string specification supplied to the Geometry |
| constructor is considered to be a Postscript page size nickname if |
| the first character is not numeric. The Geometry constructor converts |
| these page size specifications into the equivalent numeric geometry |
| string specification (preserving any offset component) prior to |
| conversion to the internal object format. Postscript page size |
| specifications are short-hand for the pixel geometry required to fill |
| a page of that size. Since the 11x17 inch page size used in the US |
| starts with a digit, it is not supported as a Postscript page size |
| nickname. Instead, substitute the geometry specification "<kbd>792x1224>"</kbd> |
| when 11x17 output is desired. |
| </p> |
| <p style="margin-bottom: 0in">An example of a Postscript page size |
| specification is <kbd>"letter+43+43>"</kbd>. |
| </p> |
| <p align="center" style="margin-bottom: 0in"><b>Postscript Page Size |
| Nicknames</b></p> |
| <table width="70%" border="1" cellpadding="2" cellspacing="3"> |
| <col width="105*" /> |
| <col width="151*" /> |
| <tr> |
| <td width="41%"> |
| <p align="center"><b>Postscript Page Size Nickname</b></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><b>Equivalent Extended Geometry Specification</b></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">Ledger</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1224x792></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">Legal</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">612x1008></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">Letter</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">612x792></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">LetterSmall</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">612x792></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">ArchE</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">2592x3456></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">ArchD</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1728x2592></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">ArchC</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1296x1728></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">ArchB</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">864x1296></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">ArchA</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">648x864></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A0</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">2380x3368></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A1</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1684x2380></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A2</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1190x1684></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A3</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">842x1190></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A4</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">595x842></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A4Small</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">595x842></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A5</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">421x595></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A6</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">297x421></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A7</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">210x297></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A8</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">148x210></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A9</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">105x148></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">A10</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">74x105></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">B0</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">2836x4008></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">B1</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">2004x2836></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">B2</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1418x2004></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">B3</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1002x1418></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">B4</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">709x1002></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">B5</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">501x709></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C0</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">2600x3677></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C1</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1837x2600></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C2</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">1298x1837></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C3</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">918x1298></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C4</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">649x918></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C5</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">459x649></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">C6</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">323x459></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">Flsa</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">612x936></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">Flse</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">612x936></font></p> |
| </td> |
| </tr> |
| <tr> |
| <td width="41%"> |
| <p align="center"><font size="2">HalfLetter</font></p> |
| </td> |
| <td width="59%"> |
| <p align="center"><font size="2">396x612></font></p> |
| </td> |
| </tr> |
| </table> |
| <H3 align="center">Geometry Methods</H3> |
| <p style="margin-bottom: 0in">Geometry provides methods to initialize |
| its value from strings, from a set of parameters, or via attributes. |
| The methods available for use in Geometry are shown in the following |
| table: |
| </p> |
| <p align="center" style="margin-bottom: 0in"><b>Geometry Methods</b></p> |
| <table width="100%" border="1" cellpadding="2" cellspacing="3"> |
| <col width="25*" /> |
| <col width="26*" /> |
| <col width="111*" /> |
| <col width="94*" /> |
| <tr> |
| <td width="10%"> |
| <p align="center"><b>Method</b></p> |
| </td> |
| <td width="10%"> |
| <p align="center"><b>Return Type</b></p> |
| </td> |
| <td width="44%"> |
| <p align="center"><b>Signature(s)</b></p> |
| </td> |
| <td width="37%"> |
| <p align="center"><b>Description</b></p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="3" width="10%"> |
| <p>Geometry</p> |
| </td> |
| <td rowspan="3" width="10%" bgcolor="#666666"> |
| <p> </p> |
| </td> |
| <td width="44%"> |
| <p>size_t width_, size_t height_, ssize_t xOff_ = |
| 0, ssize_t yOff_ = 0, bool xNegative_ = false, bool |
| yNegative_ = false</p> |
| </td> |
| <td width="37%"> |
| <p>Construct geometry via explicit parameters.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="44%"> |
| <p>const string geometry_</p> |
| </td> |
| <td width="37%"> |
| <p>Construct geometry from C++ string</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="44%"> |
| <p>const char * geometry_</p> |
| </td> |
| <td width="37%"> |
| <p>Construct geometry from C string</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>width</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>size_t width_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Width</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>size_t</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>height</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>size_t height_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Height</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>size_t</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>xOff</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>ssize_t xOff_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>X offset from origin</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>ssize_t</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>yOff</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>ssize_t yOff_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Y offset from origin</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>size_t</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>xNegative</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool xNegative_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Sign of X offset negative? (X origin at right)</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>yNegative</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool yNegative_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Sign of Y offset negative? (Y origin at bottom)</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>percent</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool percent_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Width and height are expressed as percentages</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>aspect</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool aspect_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Resize without preserving aspect ratio (!)</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>greater</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool greater_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Resize if image is greater than size (>)</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>less</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool less_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Resize if image is less than size (<)</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td rowspan="2" width="10%"> |
| <p>isValid</p> |
| </td> |
| <td width="10%"> |
| <p>void</p> |
| </td> |
| <td width="44%"> |
| <p>bool isValid_</p> |
| </td> |
| <td rowspan="2" width="37%"> |
| <p>Does object contain a valid geometry? May be set to <i>false</i> |
| in order to invalidate an existing geometry object.</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>bool</p> |
| </td> |
| <td width="44%"> |
| <p>void</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>operator =</p> |
| </td> |
| <td width="10%"> |
| <p>const Geometry&</p> |
| </td> |
| <td width="44%"> |
| <p>const string geometry_</p> |
| </td> |
| <td width="37%"> |
| <p>Set geometry via C++ string</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>operator =</p> |
| </td> |
| <td width="10%"> |
| <p>const Geometry&</p> |
| </td> |
| <td width="44%"> |
| <p>const char * geometry_</p> |
| </td> |
| <td width="37%"> |
| <p>Set geometry via C string</p> |
| </td> |
| </tr> |
| <tr> |
| <td width="10%"> |
| <p>operator string</p> |
| </td> |
| <td width="10%"> |
| <p>string</p> |
| </td> |
| <td width="44%"> |
| <p>Geometry&</p> |
| </td> |
| <td width="37%"> |
| <p>Obtain C++ string representation of geometry</p> |
| </td> |
| </tr> |
| </table> |
| <p>In addition, we support these yet to be documented geometry flags: the fill area flag ('^') and the pixel area count limit flag ('@').</p> |
| <p><br /><br /> |
| </p> |
| </div> |
| </body> |
| </html> |
