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