Skip to content
Hokusai2.2.2
ivantokar.com

Crop & canvas

Four operations change which pixels are kept or added without scaling them: extract cuts a rectangle, extend adds canvas, trim removes a uniform border, and smartCrop cuts a window around the most interesting region. The sample images are the 1600 × 1000 landscape and the 400 × 400 emblem (with transparent corners).

extract(x:y:width:height:) returns the rectangle whose top-left corner is (x, y).

let image = try Hokusai(url: URL(fileURLWithPath: "scene.png"))
// Coordinates count from the top-left corner of the image *as it is at this point*.
try await image
.extract(x: 1000, y: 120, width: 400, height: 560)
.png()
.write(to: URL(fileURLWithPath: "lighthouse.png"))
// After a resize, the same numbers address a different part of the picture.
try await image
.resize(width: 800)
.extract(x: 1000 / 2, y: 120 / 2, width: 400 / 2, height: 560 / 2)
.png()
.write(to: URL(fileURLWithPath: "lighthouse-after-resize.png"))
  • A 400 by 560 vertical slice of the landscape containing the lighthouse.
    on the originalPNG · 400 × 560 · 67 KB
  • A 200 by 280 slice taken after halving the image; it shows the same lighthouse at half size.
    after resizePNG · 200 × 280 · 46 KB
Parameter Type Bounds
x, y Int 0…10,000,000
width, height Int 1…2,147,483,647

Coordinates count from the top-left of the image as it is at that point of the pipeline. The same numbers after a resize address different pixels, so scale them too (above, the second call halves every number). A rectangle that reaches outside the image is not clipped: it fails when the pipeline is evaluated (see Limits).

extend only adds canvas. It has three forms.

  • extend(to:anchor:background:): grow to an exact ImageSize, placing the image at anchor (a Gravity: .center, the four sides or the four corners) and filling with a colour. The default background is transparent.
  • extend(to:anchor:mode:): the same, filled according to an ExtendMode.
  • extend(top:left:bottom:right:mode:): add that many pixels on each side (0…10,000,000).

ExtendMode is .background(Color), .copy (repeat the nearest edge pixel outwards), .repeat (tile the image) or .mirror (tile it, mirroring every other tile).

let emblem = try Hokusai(url: URL(fileURLWithPath: "emblem.png")).resize(width: 160)
let paper = Color(red: 0.96, green: 0.94, blue: 0.88)
// To an exact size, anchored, filled with a colour.
try await emblem.extend(to: ImageSize(width: 320, height: 200), anchor: .west, background: paper)
.png().write(to: URL(fileURLWithPath: "to-size.png"))
// Padding on each side, filled by the image's own edge pixels.
let modes: [(String, ExtendMode)] = [("copy", .copy), ("repeat", .repeat), ("mirror", .mirror)]
for (name, mode) in modes {
try await emblem.extend(top: 40, left: 40, bottom: 40, right: 40, mode: mode)
.png().write(to: URL(fileURLWithPath: "\(name).png"))
}
  • The emblem at the left of a wider canvas filled with a paper colour; its own transparent corners stay transparent.
    to a size, .westPNG · 320 × 200 · 9 KB
  • The emblem with its edge pixels smeared outwards on all four sides.
    .copyPNG · 240 × 240 · 8 KB
  • The emblem tiled, with partial copies around the original.
    .repeatPNG · 240 × 240 · 12 KB
  • The emblem tiled with alternate copies mirrored.
    .mirrorPNG · 240 × 240 · 12 KB

The new area is filled; the image’s own pixels are not touched, so transparent parts of the original stay transparent even when the background is a colour. Fill them with flatten if that is not what you want. To grow and scale to a fixed box, use resize(fit: .contain) instead.

trim removes a border of nearly uniform colour. trim(threshold:) is the short form; trim(_ options: TrimOptions) adds control:

TrimOptions Default Meaning
threshold 10 Tolerance for treating a pixel as background; lower removes only nearly identical borders. Must be finite and ≥ 0.
background .topLeft The colour to remove: the top-left pixel at that point of the pipeline, or .color(Color) (grey or RGB images).
lineArt false Detect borders in line art and synthetic images by strong edges instead of colour difference.
margin 0 Pixels of background to keep around the content (clamped to the image).
// Add a plain border first, so there is something to trim.
let framed = try Hokusai(url: URL(fileURLWithPath: "emblem.png"))
.resize(width: 200)
.extend(top: 30, left: 60, bottom: 30, right: 60,
mode: .background(Color(red: 1, green: 1, blue: 1)))
try await framed.png().write(to: URL(fileURLWithPath: "framed.png"))
try await framed.trim().png().write(to: URL(fileURLWithPath: "trimmed.png"))
// Keep a margin of the background around the detected content.
try await framed.trim(TrimOptions(margin: 12)).png()
.write(to: URL(fileURLWithPath: "trimmed-margin.png"))
  • The emblem inside a wide white border.
    inputPNG · 320 × 260 · 11 KB
  • The emblem alone; the border is gone.
    trim()PNG · 200 × 200 · 9 KB
  • The emblem with a 12-pixel margin of the white border kept.
    margin: 12PNG · 224 × 224 · 10 KB

The scan runs when the pipeline is evaluated, not when trim is called, and an image that is entirely background is left unchanged rather than cropped to nothing. Because the background is the top-left pixel, an image whose corner is part of the subject (such as the emblem’s transparent corner) is trimmed by what that corner looks like; flatten onto a known colour first when in doubt.

smartCrop(width:height:strategy:) cuts a width × height window of the original pixels, without resizing, around the region chosen by the strategy: .attention (skin tones, saturated colour, detail; the default) or .entropy (most local variation).

let image = try Hokusai(url: URL(fileURLWithPath: "scene.png"))
// smartCrop crops without resizing: it keeps a 500 × 500 window of the original pixels.
for (name, strategy) in [("attention", SmartCropStrategy.attention), ("entropy", .entropy)] {
try await image
.smartCrop(width: 500, height: 500, strategy: strategy)
.png()
.write(to: URL(fileURLWithPath: "\(name).png"))
}
  • A 500 by 500 window around the lighthouse and sun.
    .attentionPNG · 500 × 500 · 70 KB
  • A 500 by 500 window chosen by local variation.
    .entropyPNG · 500 × 500 · 25 KB

To scale and crop in one step use resize(fit: .cover, position: .attention), which makes the same selection (Resize). A window larger than the image is clamped to the image.

let image = try Hokusai(url: URL(fileURLWithPath: "emblem.png")) // 400 × 400
func attempt(_ name: String, _ pipeline: () throws -> Hokusai) async {
do {
let output = try await pipeline().png().data()
print(name, "→", output.info.width, "×", output.info.height)
} catch {
print(name, "→ throws", error)
}
}
await attempt("extract inside") { try image.extract(x: 100, y: 100, width: 200, height: 200) }
await attempt("extract past the edge") { try image.extract(x: 300, y: 300, width: 200, height: 200) }
await attempt("extend smaller") { try image.extend(to: ImageSize(width: 300, height: 300)) }
await attempt("smartCrop larger") { try image.smartCrop(width: 900, height: 900) }
await attempt("trim, nothing to trim") { try image.flatten(background: .white).trim() }
Call on a 400 × 400 image Result
extract(x: 100, y: 100, width: 200, height: 200) 200 × 200
extract(x: 300, y: 300, width: 200, height: 200) throws HokusaiError.transform (extract), when evaluated
extend(to: 300 × 300) throws HokusaiError.invalidOption (“extend cannot reduce an image”), when evaluated
smartCrop(width: 900, height: 900) 400 × 400: clamped
trim() with nothing to trim 400 × 400: unchanged

Option values outside their bounds (a negative x, a zero width, a negative margin) throw HokusaiError.invalidOption when the pipeline is built, before any image is opened.