ansel/image

This module is primarily a wrapper around the Elixir package Vix, which is a wrapper around the great image processing library vips. A pre-built vips binary comes with Vix, but see the readme for more information on how to bring your own to support more image formats.

This module uses the snag package for error handling because vix errors just come back as strings and are not enumerated. Make sure to install it as well to work with the error messages.

import ansel
import ansel/image
import gleam/result
import snag

pub fn main() {
  let assert Ok(img) = image.read("input.jpeg")

  image.scale(img, by: 2.0)
  |> result.try(
    image.write(_, "output", ansel.JPEG(quality: 60, keep_metadata: False)),
  )
  |> snag.context("Unable to process my cool image")
}
// -> output.jpeg written to disk as a smaller, rounded, bordered version of the
//    original image

Types

ImageFormat

</>

Image formats supported by vips. All may not be supported by the default vips binary included with this package, you may need to provide your own vips binary on the host system to. See the package readme for details.

The Custom constructor allows for advanced vips save options to be used, like `ansel.Custom(“.png[compression=90,squash=true]”), refer to the Vix package documentation for details.

pub type ImageFormat {
  JPEG(quality: Int, keep_metadata: Bool)
  JPEG2000(quality: Int, keep_metadata: Bool)
  JPEGXL(quality: Int, keep_metadata: Bool)
  PNG
  WebP(quality: Int, keep_metadata: Bool)
  AVIF(quality: Int, keep_metadata: Bool)
  TIFF(quality: Int, keep_metadata: Bool)
  HEIC(quality: Int, keep_metadata: Bool)
  FITS
  Matlab
  PDF
  SVG
  HDR
  PPM
  CSV
  GIF
  Analyze
  NIfTI
  DeepZoom
  Custom(format: String)
}

Constructors

```
JPEG(quality: Int, keep_metadata: Bool)
```

JPEG2000(quality: Int, keep_metadata: Bool)

JPEGXL(quality: Int, keep_metadata: Bool)

```
PNG
```
```
WebP(quality: Int, keep_metadata: Bool)
```
```
AVIF(quality: Int, keep_metadata: Bool)
```
```
TIFF(quality: Int, keep_metadata: Bool)
```
```
HEIC(quality: Int, keep_metadata: Bool)
```
```
FITS
```
```
Matlab
```
```
PDF
```
```
SVG
```
```
HDR
```
```
PPM
```
```
CSV
```
```
GIF
```
```
Analyze
```
```
NIfTI
```
```
DeepZoom
```
```
Custom(format: String)
```

Functions

blur

</>

pub fn blur(
  image image: Image,
  with sigma: Float,
) -> Result(Image, Snag)

Applies a gaussian blur with the given sigma value to an image.

border

</>

pub fn border(
  around image: Image,
  with color: Color,
  thickness thickness: Int,
) -> Result(Image, Snag)

Add a solid border around the passed image, expanding the dimensions of the image by the border thickness. Replaces any transparent pixels with the color of the border. This can be used with the round function to add a rounded border to an image.

composite_over

</>

pub fn composite_over(
  base base: Image,
  with overlay: Image,
  at_left l: Int,
  at_top t: Int,
) -> Result(Image, Snag)

Places an image over another image, with the top left corner of the overlay image placed at the specified coordinates.

create_thumbnail

</>

pub fn create_thumbnail(
  from path: String,
  width width: Int,
) -> Result(Image, Snag)

Creates a thumbnail of an image at the specified path with the given width.

extract_area

</>

pub fn extract_area(
  from image: Image,
  at bounding_box: BoundingBox,
) -> Result(Image, Snag)

Extracts an area out of an image, resulting in a new image of the extracted area.

fill

</>

pub fn fill(
  image: Image,
  in bounding_box: BoundingBox,
  with color: Color,
) -> Result(Image, Snag)

Fills in an area of the passed image with a solid color.

fit_bounding_box

</>

pub fn fit_bounding_box(
  bounding_box bounding_box: BoundingBox,
  in image: Image,
) -> Result(BoundingBox, Snag)

Fits a fixed bounding box to an image by dropping any pixels outside the dimensions of the image.

Example

let assert Ok(bb) = bounding_box.ltwh(4, 2, 40, 30)
let assert Ok(img) = image.new(6, 7, color.GleamLucy)
image.fit_bounding_box(bb, in: img)
// -> bounding_box.ltwh(left: 4, top: 2, width: 2, height: 5)

from_bit_array

</>

pub fn from_bit_array(bin: BitArray) -> Result(Image, Snag)

Reads a vips image from a bit array

Example

simplifile.read_bits("input.jpeg")
|> result.try(image.from_bit_array)
// -> Ok(ansel.Image)

get_height

</>

pub fn get_height(image: Image) -> Int

Returns the height of an image.

get_width

</>

pub fn get_width(image: Image) -> Int

Returns the width of an image.

new

</>

pub fn new(
  width width: Int,
  height height: Int,
  color color: Color,
) -> Result(Image, Snag)

Creates a new image with the specified width, height, and color

Example

image.new(6, 6, color.Olive)
// -> Ok(ansel.Image)

outline

</>

pub fn outline(
  in image: Image,
  area bounding_box: BoundingBox,
  with color: Color,
  thickness thickness: Int,
) -> Result(Image, Snag)

Outlines an area in the passed image with a solid color. All outline pixels are written inside the bounding box area.

read

</>

pub fn read(from path: String) -> Result(Image, Snag)

Reads an image from the specified path.

rotate

</>

pub fn rotate(
  image image: Image,
  by degrees: Float,
) -> Result(Image, Snag)

Rotates an image by the given number of degrees.

round

</>

pub fn round(
  image image: Image,
  by radius: Float,
) -> Result(Image, Snag)

Rounds the corners of an image by a given radius, leaving transparent pixels where the rounding was applied. A large radius can be given to create circular images. This can be used with the border function to create rounded borders around images. This implmentation is heavily inspired by the extensive elixir library Image.

scale

</>

pub fn scale(
  image img: Image,
  by scale: Float,
) -> Result(Image, Snag)

Resizes an image by the given scale, preserving the aspect ratio.

scale_height

</>

pub fn scale_height(
  image img: Image,
  to target: Int,
) -> Result(Image, Snag)

Scales an image to the given height, preserving the aspect ratio.

scale_width

</>

pub fn scale_width(
  image img: Image,
  to target: Int,
) -> Result(Image, Snag)

Scales an image to the given width, preserving the aspect ratio.

to_bit_array

</>

pub fn to_bit_array(img: Image, format: ImageFormat) -> BitArray

Saves a vips image to a bit array. Assumes your vips was built with the correct encoder support for the format to save in.

Example

image.new(6, 6, color.GleamLucy)
|> result.map(to_bit_array(_, ansel.PNG))
|> result.try(simplifile.write_bits("output.png"))

to_bounding_box

</>

pub fn to_bounding_box(image image: Image) -> BoundingBox

Returns the dimensions of an image as a bounding box. Useful for bounding box operations.

write

</>

pub fn write(
  image img: Image,
  to path: String,
  in format: ImageFormat,
) -> Result(Nil, Snag)

Writes an image to the specified path in the specified format.