> ## Documentation Index
> Fetch the complete documentation index at: https://hackmamba-3f164318.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Geometry Syntax Reference

> How dimension strings like `800x600>`, `50%`, and `WxH!` control resize, crop, extent, and other spatial operations.

Geometry is a string format that specifies dimensions, offsets, and resize behavior. It appears in `-resize`, `-crop`, `-extent`, `-thumbnail`, `-scale`, `-sample`, and other options that manipulate image dimensions. The authoritative overview is [Command-line processing (geometry)](https://imagemagick.org/script/command-line-processing.php#geometry) on imagemagick.org; this page summarizes the parts doc readers use most often.

## Base syntax

Unless noted, examples assume a **1600×1200** source (4∶3 aspect ratio). For “fit inside” sizes, ImageMagick uses **scale = min(W/w, H/h)** so neither output dimension exceeds the box.

| Format    | Meaning                                                                    | Example (1600×1200 source)                                                                                                                    |
| --------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `WxH`     | Fit inside **W×H**, keep aspect ratio (scale = min of width/height ratios) | `800x400` → **533×400**; height binds first because `400÷1200` is a smaller scale than `800÷1600`; **not** 800×600 (height would exceed 400). |
| `W`       | Set width **W**, height follows aspect ratio                               | `800` → **800×600**                                                                                                                           |
| `xH`      | Set height **H**, width follows aspect ratio                               | `x600` → **800×600**                                                                                                                          |
| `W%`      | Scale **both** width and height by the same percentage                     | `50%` → **800×600**                                                                                                                           |
| `W%xH%`   | Scale width and height **independently** (aspect ratio usually changes)    | `50%x25%` → **800×300** (half width, quarter height. A common mistake is expecting 50% on both axes; use plain `50%` for uniform shrink).     |
| `WxH+X+Y` | Width×height plus offset (typical with `-crop`)                            | `400x300+100+50` → 400×300 region with top-left of the crop at **pixel (100, 50)**                                                            |
| `A@`      | Resize to approximate total pixel area **A**                               | `640000@` → **924×693** (area ≈ 640,332)                                                                                                      |

<Info>
  Geometry dimensions are in pixels. ImageMagick does not factor in DPI or print resolution when interpreting geometry strings. An image at 300 DPI and an image at 72 DPI with the same pixel dimensions receive the same resize result.
</Info>

## Resize modifier flags

Modifier flags are appended to the end of a geometry string. They change how ImageMagick handles aspect ratio and sizing constraints.

### Independent percentages on both axes (`W%xH%`)

Strings like **`50%x25%`** scale width and height **by different percentages**, so the aspect ratio **changes** (unlike a single `50%`, which scales both axes together). See the **`W%xH%`** row in the [base syntax](#base-syntax) table. That trips people who expect `50%x25%` to mean “50% overall.”

All examples below use a **1600x1200** input image and a target of **800x400**.

### No flag (default)

```bash theme={null}
magick input.jpg -resize 800x400 output.jpg
```

Fits the image within 800x400 while preserving aspect ratio. The result never exceeds either dimension. Output: **533x400** (height is the limiting dimension).

### `!` Force exact dimensions

```bash theme={null}
magick input.jpg -resize '800x400!' output.jpg
```

Ignores aspect ratio and forces the image to exactly 800x400. Output: **800x400**.

<Warning>
  The `!` flag distorts the image if the target aspect ratio differs from the source. A 4:3 image forced into 2:1 dimensions will appear horizontally stretched.
</Warning>

### `>` Only shrink

```bash theme={null}
magick input.jpg -resize '800x600>' output.jpg
```

Resizes the image only if it is larger than the target. If the image already fits within the dimensions, it stays unchanged.

| Input size | Target     | Output              |
| ---------- | ---------- | ------------------- |
| 1600x1200  | `800x600>` | 800x600 (shrunk)    |
| 400x300    | `800x600>` | 400x300 (unchanged) |

### `<` Only enlarge

```bash theme={null}
magick input.jpg -resize '800x600<' output.jpg
```

Resizes the image only if it is smaller than the target. Larger images stay unchanged.

| Input size | Target     | Output                |
| ---------- | ---------- | --------------------- |
| 400x300    | `800x600<` | 800x600 (enlarged)    |
| 1600x1200  | `800x600<` | 1600x1200 (unchanged) |

### `^` Fill area

```bash theme={null}
magick input.jpg -resize '800x400^' output.jpg
```

**`^` means “cover” the box**, not “fit inside.” ImageMagick scales until **both** dimensions are at least the target (`max(W/w, H/h)`). For 1600×1200 into an **800×400** box, the width hits 800 first, producing **800×600**. The image is **150px taller than the 400px target**. That overflow is expected; you still need a **crop** or **extent** step if the deliverable must be exactly 800×400.

This is typically paired with `-gravity center -extent` (or `-crop`) to trim the extra:

```bash theme={null}
magick input.jpg -resize '800x400^' -gravity center -extent 800x400 output.jpg
```

Final output: **800×400** (scaled to cover, then canvas cropped from the center).

## Offset syntax

Offsets specify a position within the image, written as `+X+Y` or `-X-Y` after the dimensions. They are primarily used with `-crop` and `-extent`.

```bash theme={null}
magick input.jpg -crop 400x300+100+50 +repage output.jpg
```

This extracts a 400x300 region starting 100 pixels from the left edge and 50 pixels from the top edge. The `+repage` resets the virtual canvas to match the cropped dimensions.

Negative offsets shift in the opposite direction:

```bash theme={null}
magick input.jpg -crop 400x300-50-25 +repage output.jpg
```

This shifts the crop region 50 pixels left and 25 pixels up from the default origin. Pixels outside the image boundary are not included; the result may be smaller than 400x300.

## Gravity and crop offsets

When `-gravity` is set, crop offsets are measured from the gravity anchor point instead of the top-left corner.

| Gravity               | Anchor for `+X+Y` (on an **800×800** image, 0-based pixels)  | `-crop 400x400+0+0` result    |
| --------------------- | ------------------------------------------------------------ | ----------------------------- |
| `NorthWest` (default) | Top-left corner **(0, 0)**                                   | Top-left 400×400 block        |
| `NorthEast`           | Top-right corner **(799, 0)**; column `width−1`, row `0`     | Top-right 400×400 block       |
| `Center`              | Image center **(400, 400)**; half of 800 in each axis        | Centered 400×400              |
| `SouthEast`           | Bottom-right **(799, 799)**; column and row `size−1`         | Bottom-right 400×400 block    |
| `South`               | Bottom edge center **(400, 799)**; middle column, bottom row | Bottom-centered 400×400 strip |

Offsets add to the anchor in the direction ImageMagick defines for that gravity (see the [official geometry](https://imagemagick.org/script/command-line-processing.php#geometry) page for edge cases).

`-gravity` persists for all subsequent spatial operations until explicitly reset. To reset it:

```bash theme={null}
magick input.jpg -gravity Center -crop 400x400+0+0 +repage -gravity None -crop 200x200+0+0 +repage output.jpg
```

The first crop uses Center gravity. The second crop uses the default top-left origin after `-gravity None` resets it.

## Options that accept geometry

**Resize operations** (all preserve aspect ratio by default, all accept modifier flags):

| Option       | Behavior                                                          | Use when                                                                       |
| ------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `-resize`    | High-quality resize with filtering                                | Default: best visual quality for photos and general output.                    |
| `-thumbnail` | Same geometry as `-resize`, plus **strips metadata and profiles** | Web assets and thumbnails where smaller files and privacy matter.              |
| `-scale`     | Fast resize **without** resize filters (pixel averaging)          | Speed over quality; large downscales where a softer `-resize` is unnecessary.  |
| `-sample`    | **Nearest-neighbor** only (no interpolation)                      | Pixel art, crisp UI captures, masks; avoid on photos (stair‑edges / aliasing). |

**Crop and extent operations** (use `WxH+X+Y` offset syntax):

| Option    | Behavior                                                            |
| --------- | ------------------------------------------------------------------- |
| `-crop`   | Extract a region; add `+repage` to reset virtual canvas             |
| `-extent` | Set canvas size; pads with `-background` color if larger than image |

## Edge cases

### `x600` vs `0x600`

These are different. `x600` omits the width, so ImageMagick calculates it proportionally from the height. `0x600` specifies a width of zero, which produces a 1x1 pixel output. Always omit the dimension rather than setting it to zero.

### Two-axis percentages (`50%x25%`)

Covered in the base table above: width and height scale **independently**, so the picture stretches unless both percentages match.

### Decimal percentages

Values like `33.3%` are valid. ImageMagick rounds the result to the nearest whole pixel. A 1600x1200 image at `33.3%` becomes 533x400.

### Area resize (`@`)

The `@` flag targets an approximate pixel count rather than specific dimensions. `640000@` on a 1600x1200 image produces 924x693 (area = 640,332). The result preserves aspect ratio and gets as close to the target area as possible.

### Shell escaping

The `>`, `<`, `^`, and `!` characters have special meaning in most shells. Wrap geometry strings in single quotes on Linux/macOS (`'800x600>'`) or double quotes on Windows (`"800x600>"`). The backslash escape (`800x600\>`) also works on Linux/macOS.

## See also

* [Common options reference](/reference/common-options) for `-strip`, `-quality`, `-gravity`, `-background`, `-composite`, and related flags used together with geometry in real commands.