View Source StbImage (StbImage v0.5.2)

Tiny module for image encoding and decoding.

The following formats are supported and have type u8:

  • 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)
  • PIC (Softimage PIC)
  • PNM (PPM and PGM binary only)

The following formats are supported and have type f32:

  • HDR (radiance rgbE format) (type is f32)

There are also specific functions for working with GIFs.

Link to this section Summary

Functions

The StbImage struct.

Creates a StbImage from a Nx tensor.

Creates a StbImage directly.

Reads image from binary representing an image.

Reads image from file at path.

Decodes GIF image from a binary representing a GIF.

Reads GIF image from file at path.

Resizes the image into the given output_h and output_w.

Encodes image to a binary.

Converts a StbImage to a Nx tensor.

Writes image to the file at path.

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 ({:u, 8} or {:f, 32})

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

Creates a StbImage from a Nx tensor.

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

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 {:u, 8}. Must be one of {:u, 8} or {:f, 32}. The :u8 and :f32 convenience atom syntax is also available.
Link to this function

read_binary!(buffer, opts \\ [])

View Source

Raising version of read_binary/2.

Link to this function

read_binary(buffer, opts \\ [])

View Source

Reads image from binary representing an image.

options

Options

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

example

Example

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

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

read_file!(buffer, opts \\ [])

View Source

Raising version of read_file/2.

Link to this function

read_file(path, opts \\ [])

View Source

Reads image from file at path.

options

Options

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

example

Example

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

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

Decodes GIF image from a binary representing a GIF.

example

Example

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

Reads GIF image from file at path.

example

Example

{:ok, frames, delays} = StbImage.read_gif_file("/path/to/image")
frame = Enum.at(frames, 0)
{h, w, 3} = frame.shape
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})
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, :hdr.

example

Example

img = StbImage.new(raw_img, {h, w, channels})
binary = StbImage.to_binary(img, :png)
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.

Link to this function

write_file!(image, path, opts \\ [])

View Source

Raising version of write_file/3.

Link to this function

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

View Source

Writes image to the file at path.

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

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.

options

Options

  • :format - one of the supported image formats