Magick++ API: Geometry

# Magick::Geometry

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.

### Geometry Specifications

Geometry specifications are in the form `"<width>x<height>{+-}<xoffset>{+-}<yoffset>"` (where width, height, xoffset, and yoffset are numbers) for specifying the size and placement location for an object.

The width and height parts of the geometry specification are measured in pixels. The xoffset and yoffset 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:

+xoffset | The left edge of the object is to be placed xoffset pixels in from the left edge of the image.
-xoffset | The left edge of the object is to be placed outside the image, xoffset pixels out from the left edge of the image.

The Y offset has similar meanings:

+yoffset | The top edge of the object is to be yoffset pixels below the top edge of the image.
-yoffset | The top edge of the object is to be yoffset pixels above the top edge of the image.

Offsets must be given as pairs; in other words, in order to specify either xoffset or yoffset both must be present.

### ImageMagick Extensions To Geometry Specifications

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 "`<width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>}"`. Extended geometry strings should only be used when resizing an image. Using an extended geometry string for other applications may cause the API call to fail. The available qualifiers are shown in the following table:

ImageMagick Geometry Qualifiers

Qualifier | Description
% | Interpret width and height as a percentage of the current size.
! | Resize to width and height exactly, loosing original aspect ratio.
< | Resize only if the image is smaller than the geometry specification.
> | Resize only if the image is greater than the geometry specification.

### Postscript Page Size Extension To Geometry Specifications

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 "`792x1224>"` when 11x17 output is desired.

An example of a Postscript page size specification is `"letter+43+43>"`.

Postscript Page Size Nicknames

Postscript Page Size Nickname | Equivalent Extended Geometry Specification
Ledger | 1224x792>
Legal | 612x1008>
Letter | 612x792>
LetterSmall | 612x792>
ArchE | 2592x3456>
ArchD | 1728x2592>
ArchC | 1296x1728>
ArchB | 864x1296>
ArchA | 648x864>
A0 | 2380x3368>
A1 | 1684x2380>
A2 | 1190x1684>
A3 | 842x1190>
A4 | 595x842>
A4Small | 595x842>
A5 | 421x595>
A6 | 297x421>
A7 | 210x297>
A8 | 148x210>
A9 | 105x148>
A10 | 74x105>
B0 | 2836x4008>
B1 | 2004x2836>
B2 | 1418x2004>
B3 | 1002x1418>
B4 | 709x1002>
B5 | 501x709>
C0 | 2600x3677>
C1 | 1837x2600>
C2 | 1298x1837>
C3 | 918x1298>
C4 | 649x918>
C5 | 459x649>
C6 | 323x459>
Flsa | 612x936>
Flse | 612x936>
HalfLetter | 396x612>

### Geometry Methods

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:

Geometry Methods

Method | Return Type | Signature(s) | Description
Geometry |  | size_t width_, size_t height_, ssize_t xOff_ = 0, ssize_t yOff_ = 0, bool xNegative_ = false, bool yNegative_ = false | Construct geometry via explicit parameters.
const string geometry_ | Construct geometry from C++ string
const char * geometry_ | Construct geometry from C string
width | void | size_t width_ | Width
size_t | void
height | void | size_t height_ | Height
size_t | void
xOff | void | ssize_t xOff_ | X offset from origin
ssize_t | void
yOff | void | ssize_t yOff_ | Y offset from origin
size_t | void
xNegative | void | bool xNegative_ | Sign of X offset negative? (X origin at right)
bool | void
yNegative | void | bool yNegative_ | Sign of Y offset negative? (Y origin at bottom)
bool | void
percent | void | bool percent_ | Width and height are expressed as percentages
bool | void
aspect | void | bool aspect_ | Resize without preserving aspect ratio (!)
bool | void
greater | void | bool greater_ | Resize if image is greater than size (>)
bool | void
less | void | bool less_ | Resize if image is less than size (<)
bool | void
isValid | void | bool isValid_ | Does object contain a valid geometry? May be set to false in order to invalidate an existing geometry object.
bool | void
operator = | const Geometry& | const string geometry_ | Set geometry via C++ string
operator = | const Geometry& | const char * geometry_ | Set geometry via C string
operator string | string | Geometry& | Obtain C++ string representation of geometry

In addition, we support these yet to be documented geometry flags: the fill area flag ('^') and the pixel area count limit flag ('@').