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.
Decodes image from binary
representing an image.
options
Options
:channels
- The number of desired channels. Use0
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
Decodes image from file at path
.
options
Options
:channels
- The number of desired channels. Use0
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
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
.
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))
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)
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
Converts a StbImage
to a Nx tensor.
It accepts the same options as Nx.from_binary/3
.