View Source StbImage (StbImage v0.3.0)

Tiny image encoding and decoding.

The following formats are supported:

  • JPEG baseline & progressive (12 bpc/arithmetic not supported, same as stock IJG lib)
  • PNG 1/2/4/8/16-bit-per-channel
  • TGA
  • BMP non-1bpp, non-RLE
  • PSD (composited view only, no extra channels, 8/16 bit-per-channel)
  • GIF (always reports as 4-channel)
  • HDR (radiance rgbE format)
  • PIC (Softimage PIC)
  • PNM (PPM and PGM binary only)

There are also specific functions for working with GIFs.

Link to this section Summary

Functions

The StbImage struct.

Decodes image from binary representing an image.

Decodes image from file at path.

Creates a StbImage from a Nx tensor.

Decodes GIF image from a binary representing a GIF.

Decodes GIF image from file at path.

Creates a StbImage directly.

Resizes the image into the given output_h and output_w.

Encodes image to a binary.

Saves image to the file at path.

Converts a StbImage to a Nx tensor.

Link to this section Functions

The StbImage struct.

It has the following fields:

  • :data - a blob with the image bytes in HWC (heigth-width-channels) order
  • :shape - a tuple with the {height, width, channels}
  • :type - the type unit in the binary (u8/f32)

The number of channels correlate directly to the color mode. 1 channel is greyscale, 2 is greyscale+alpha, 3 is RGB, and 4 is RGB+alpha.

Link to this function

from_binary(buffer, opts \\ [])

View Source

Decodes image from binary representing an image.

options

Options

  • :channels - The number of desired channels. Use 0 for auto-detection. Defaults to 0.

  • :type - The type of the data. Defaults to :u8. Must be one of :u8 or :f32.

example

Example

{:ok, buffer} = File.read("/path/to/image")
{:ok, img} = StbImage.from_binary(buffer)
{h, w, c} = img.shape
img = img.data

# If you know the image is a 4-channel image and auto-detection failed
{:ok, img} = StbImage.from_file("/path/to/image", channels: 4)
{h, w, c} = img.shape
img = img.data
Link to this function

from_file(path, opts \\ [])

View Source

Decodes image from file at path.

options

Options

  • :channels - The number of desired channels. Use 0 for auto-detection. Defaults to 0.

  • :type - The type of the data. Defaults to :u8. Must be one of :u8 or :f32.

example

Example

{:ok, img} = StbImage.from_file("/path/to/image")
{h, w, c} = img.shape
data = img.data

# If you know the image is a 4-channel image and auto-detection failed
{:ok, img} = StbImage.from_file("/path/to/image", channels: 4)
{h, w, c} = img.shape
img = img.data

Creates a StbImage from a Nx tensor.

The tensor is expected to have shape {h, w, c} and one of the supported types.

Decodes GIF image from a binary representing a GIF.

example

Example

{:ok, buffer} = File.read("/path/to/image")
{:ok, frames, delays} = StbImage.gif_from_binary(buffer)
frame = Enum.at(frames, 0)
{h, w, 3} = frame.shape

Decodes GIF image from file at path.

example

Example

{:ok, frames, delays} = StbImage.gif_from_file("/path/to/image")
frame = Enum.at(frames, 0)
{h, w, 3} = frame.shape
Link to this macro

is_dimension(d)

View Source (macro)
Link to this function

new(data, shape, opts \\ [])

View Source

Creates a StbImage directly.

data is a binary blob with the image bytes in HWC (heigth-width-channels) order. shape is a tuple with the heigth, width, and channel dimensions.

options

Options

  • :type - The type of the data. Defaults to :u8. Must be one of :u8 or :f32.
Link to this function

resize(stb_image, output_h, output_w)

View Source

Resizes the image into the given output_h and output_w.

example

Example

img = StbImage.new(raw_img, {h, w, channels})
{:ok, resized_img} = StbImage.resize(raw_img, div(h, 2), div(w, 2))
Link to this function

to_binary(stb_image, format)

View Source

Encodes image to a binary.

The supported formats are :jpg, :png, :bmp, :tga.

Returns {:ok, binary} on success and {:error, reason} otherwise.

Only u8 images can be encoded at the moment.

example

Example

img = StbImage.new(raw_img, {h, w, channels})
{:ok, binary} = StbImage.to_binary(img, :png)
Link to this function

to_file(stb_image, path, opts \\ [])

View Source

Saves image to the file at path.

The supported formats are :jpg, :png, :bmp, :tga.

The format is determined from the file extension if possible, you can also pass it explicitly via the :format option.

Returns :ok on success and {:error, reason} otherwise.

Make sure the directory you intend to write the file to exists, otherwise an error is returned.

Only u8 images can be saved at the moment.

options

Options

  • :format - one of the supported image formats
Link to this function

to_nx(stb_image, opts \\ [])

View Source

Converts a StbImage to a Nx tensor.

It accepts the same options as Nx.from_binary/3.