Skip to content
Hokusai2.2.2
ivantokar.com

Raw pixels

When pixels already exist in memory (a camera frame, a rendered chart, test data), Hokusai(raw:width:height:format:rowStride:premultiplied:limits:) builds a pipeline from them, and raw(_:premultiplied:background:) returns pixels as a RawImage. Raw and encoded pipelines share every transformation.

Samples are interleaved (RGBRGB…), unsigned, with no padding between pixels. Colour channels come first and alpha, when present, last. 16-bit samples use the machine’s byte order, which is little-endian on every supported platform. Colour is sRGB; grey is the same transfer curve with one channel. No colour profile is applied to raw pixels.

Format Channels Bytes per pixel
gray8 grey 1
grayAlpha8 grey, alpha 2
rgb8 red, green, blue 3
rgba8 red, green, blue, alpha 4
gray16 grey 2
grayAlpha16 grey, alpha 4
rgb16 red, green, blue 6
rgba16 red, green, blue, alpha 8

Parameters: the data, width and height (1…2,147,483,647), the format, an optional rowStride (bytes between row starts; nil means tightly packed, width × bytesPerPixel), premultiplied (whether colour channels were already multiplied by alpha; they are divided out on load, so every later operation sees straight alpha; ignored for formats without alpha), and limits. Dimensions, stride and byte count are checked with overflow detection before any native call, so a lying header cannot wrap around.

// Raw pixels you already hold: here, a 4 × 2 RGBA image drawn by hand.
var pixels = Data()
for y in 0..<2 {
for x in 0..<4 {
pixels.append(contentsOf: [UInt8(x * 80), UInt8(y * 200), 128, 255]) // R G B A
}
}
let tiny = try Hokusai(raw: pixels, width: 4, height: 2, format: .rgba8)
// Every transformation works on it; nearest keeps the pixels visible.
try await tiny.resize(width: 200, kernel: .nearest).png().write(to: URL(fileURLWithPath: "tiny.png"))
// And pixels come back out as RawImage: the format, size, stride and alpha convention are stated.
let frame = try await Hokusai(url: URL(fileURLWithPath: "emblem.png")).resize(width: 64).raw(.rgb8)
print("raw out:", frame.width, "×", frame.height, "stride", frame.rowStride, "bytes", frame.byteCount, "format", frame.format)
// A wrong byte count is rejected before any native work.
do { _ = try Hokusai(raw: Data(count: 10), width: 4, height: 2, format: .rgba8) } catch { print("bad count →", error) }
  • A tiny 4 by 2 image hand-built from raw pixels, enlarged with nearest-neighbour: eight coloured blocks.
    4 × 2 → 200PNG · 200 × 100 · 1 KB

raw(_ format:premultiplied:background:) (defaults .rgba8, false, .white) returns a RawImage that states everything needed to read it: data, width, height, format, rowStride, premultiplied, byteCount. Rows run top to bottom and pixels left to right. Hokusai’s own output is tightly packed (rowStride == width × bytesPerPixel, and the example printed stride 192 and 12,288 bytes for a 64 × 64 rgb8 frame). Pass the RawImage back to Hokusai(raw:) unchanged to round-trip. background fills transparency when the format has no alpha.

raw has no encoder: calling it on a pipeline that has one selected throws invalidOption (“an encoder is selected; raw output has no encoder, so use data() for an encoded image”).

Situation Result
Byte count does not match the geometry invalidInput: “raw data is 10 bytes; a 4×2 rgba8 image with a row stride of 16 needs 32”
Non-positive or oversize dimension, a stride too small, or an overflowing row invalidOption, thrown by the initializer
Limits exceeded resource