View Source StbImage (StbImage v0.2.1)

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.

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/u16/f32)
  • :color_mode - the color mode as :l, :la, :rgb, or :rgba
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, :u16, :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, :u16, :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

# GIFs always have channels == :rgb and type == :u8
# delays is a list that has n elements, where n is the number of frames

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

# GIFs always have channels == :rgb and type == :u8
# delays is a list that has n elements, where n is the number of frames
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

  • :color_mode - the color mode. One is automatically inferred from the number of channels.

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

Link to this function

to_binary(stb_image, format)

View Source

Encodes image to a binary.

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

example

Example

img = %StbImage{data: raw_img, shape: {h, w, channels}, type: :u8, color_mode: :rgba}
{: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 intent to write the file to exists, otherwise an error is returned.

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.