NativeImage

The Image component owns display and terminal-protocol selection. NativeImage owns image decode, transformed pixels, and native image handles.

This advanced API is for code that must inspect or transform pixels before display. Use the Image component to load and display an encoded source without direct pixel ownership.

Every materialized image uses top-left, straight-alpha, sRGB RGBA8 pixels. The API is supported in the Bun and Node.js runtimes listed in Runtime and platform support.

Load and dispose an image#

import { NativeImage } from "@opentui/core"

const image = await NativeImage.load("./image.webp")

try {
  const raw = image.raw("rgba8")
  console.log(raw.width, raw.height, raw.stride, raw.data)
} finally {
  image.dispose()
}

raw() returns an owned JavaScript copy. Disposing image does not invalidate that copy.

Accepted sources#

Format detection reads encoded bytes. It does not trust a filename, URL suffix, response header, or file extension.

decode() and fromRgba() copy caller data into native ownership. imageInfo() returns metadata without retaining an image handle. It can decode pixels when validation needs pixel inspection.

fromRgba() defaults stride to width * 4. The stride must fit one complete row. The input must contain every row, including stride padding.

Load options#

interface ImageLoadOptions {
  signal?: AbortSignal
  fetch?: (input: URL, init?: RequestInit) => Promise<Response>
}

signal cancels file, response-body, or fetch acquisition. An abort throws signal.reason. fetch replaces globalThis.fetch for fetched URLs.

Paths, blobs, and response bodies are fully buffered before native decode. load() rejects a non-success HTTP status before it reads the body.

Format behavior#

NativeImage does not expose animation frames or timing. GIF becomes one image. Animated WebP reports an unsupported feature.

Metadata#

image.info() and imageInfo() return ImageInfo:

explicit-srgb means the source supplied supported color metadata or the image came from explicit RGBA pixels. assumed-srgb means OpenTUI treated untagged source values as sRGB.

For PNG, supported sRGB cICP takes precedence. Otherwise, iCCP takes precedence over sRGB, gAMA, and cHRM. Unsupported cICP falls through to lower-priority metadata. OpenTUI converts supported RGB or grayscale ICC monitor profiles to sRGB with Little CMS.

Pixel access#

Both raw result types include data, width, height, stride, format, colorSpace: "srgb", and alpha: "straight".

copyTo() defaults to RGBA8 with stride width * 4. A custom stride must fit a row. The destination must fit all rows.

Transfer native pixels#

const image = await NativeImage.load(new Blob([encodedImage]))

try {
  const raw = image.takeRaw()
  try {
    consumeRgba(raw.data, raw.width, raw.height, raw.stride)
  } finally {
    raw.dispose()
  }
} finally {
  image.dispose()
}

takeRaw() consumes the NativeImage. Later image access throws, while image.dispose() remains a safe no-op.

OwnedRawImage.data aliases native memory. Keep the owner alive while any consumer uses the view. OwnedRawImage.dispose() is idempotent and required. It frees the native allocation and invalidates data.

takeRaw() requires one exclusive native reference. It throws while another retained handle or a native buffer keeps the image alive. Dispose extra handles and clear or destroy those buffers first.

Share or copy a handle#

Dispose every retained, cloned, decoded, and transformed handle separately. Disposing one retained handle does not invalidate another retained handle.

Transform images#

Operations do not mutate the source. Each successful operation returns a new NativeImage.

Resize kernels are "area", "default", "triangle", "cubic-bspline", "catmull-rom", "mitchell", and "nearest". The default is "area".

extend() defaults all sides to zero and the background to transparent [0, 0, 0, 0]. Each background channel is an integer from 0 through 255.

Composite options default to left: 0, top: 0, blend: "source-over", and opacity: 1. Blend modes are "source-over", "source", and "destination-over". Opacity must be finite and in 0..1. Negative offsets clip the overlay to the base image.

const source = await NativeImage.load("photo.jpg")

try {
  const thumbnail = source.resize({ width: 320 })
  try {
    useImage(thumbnail)
  } finally {
    thumbnail.dispose()
  }
} finally {
  source.dispose()
}

Encoded PNG retention#

ensureEncodedPng() makes encoded PNG data available for low-level native consumers. Raw and transformed images can need an encode at this point. The method returns void and leaves the image usable.

Opaque, orientation-free PNG input can retain its original encoded bytes without decoding pixels immediately. A direct unchanged Kitty placement can use those bytes. Any pixel read, pixel operation, Sixel or block rendering, or Kitty crop, resize, or opacity operation materializes pixels.

This lazy path means corrupt PNG pixel data can pass initial metadata validation and fail when the first pixel path runs.

Errors and limits#

ImageLoadError covers source acquisition. It exposes code, source, and optional HTTP status.

ImageError covers native decode and operations. It exposes numeric status and one of these codes:

• invalid-handle, unsupported-format, unsupported-color-space, or malformed-data
• dimension-limit, memory-limit, invalid-argument, or out-of-memory
• output-too-small, internal-error, or unsupported-feature

JavaScript option and geometry validation uses TypeError and RangeError. All image methods except dispose() throw after disposal or transfer.

OpenTUI keeps the eight most recently used validated ICC profiles and sRGB transforms. The cache key includes complete decompressed profile bytes and RGB or grayscale mode. The native library clears the cache when its final client releases it.

Next#

• Image owns normal display and protocol choice.
• FrameBuffer displays an existing or transformed image.
• Buffer API defines drawImage() placement ownership.
• Lifecycle and cleanup defines native-handle cleanup.
• Runtime and platform support lists native targets.
• API and symbol index lists every image export.