ansel/bounding_box

A module for working with bounding boxes in Ansel. Bounding boxes are a common way to represent rectangular areas in images, and can be used to crop images, fill in images, and highlight areas of images.

let assert Ok(box) = bounding_box.x1y1x2y2(2, 2, 4, 4)

bounding_box.expand(box, by: 2)
|> image.extract_area(image, at: _)

Types

BoundingBox

opaque </>

A representation of a rectangular area in any given image.

pub opaque type BoundingBox

Functions

cut

</>

pub fn cut(
  out_of to_cut: BoundingBox,
  with cutter: BoundingBox,
) -> List(BoundingBox)

Cuts a bounding box out of another bounding box, returning a list of bounding boxes that represent the area of the original that was not cut out.

expand

</>

pub fn expand(
  bounding_box: BoundingBox,
  by amount: Int,
) -> BoundingBox

Expands a bounding box by the given amount in all dimensions. If the amount is negative, the bounding box will not be modified.

fit

</>

pub fn fit(
  box: BoundingBox,
  into reference: BoundingBox,
) -> Option(BoundingBox)

Fits a bounding box into another bounding box, dropping any pixels outside the dimensions of the reference bounding box.

intersection

</>

pub fn intersection(
  of box1: BoundingBox,
  with box2: BoundingBox,
) -> Option(BoundingBox)

Returns the intersection of two bounding boxes. If they do not intersect, None will be returned.

ltrb

</>

pub fn ltrb(
  left left: Int,
  top top: Int,
  right right: Int,
  bottom bottom: Int,
) -> Result(BoundingBox, Snag)

Creates a new bounding box from the given values in the (Left, Top), (Right, Bottom) rectangular coordinate format.

ltwh

</>

pub fn ltwh(
  left left: Int,
  top top: Int,
  width width: Int,
  height height: Int,
) -> Result(BoundingBox, Snag)

Creates a new bounding box from the given values in the (Left, Top), (Width, Height) rectangular coordinate format.

make_relative

</>

pub fn make_relative(
  box: BoundingBox,
  to reference: BoundingBox,
) -> Option(BoundingBox)

Makes a bounding box relative to and fit inside another bounding box. Assuming both bounding boxes are on the same image, they are both relative to 0,0 on that image. This adjusts the first bounding box so that the original coordinates are relative to the top left corner of the second bounding box instead, and then fits the adjusted bounding box into the reference bounding box.

This is useful when you have two bounding boxes on an image, where one represents an extracted area of the original image and you want to do an operation on that extracted area with the second bounding box, but the second bounding box was calculated with the coordinates of the original image.

Example

let assert Ok(box) = bounding_box.ltwh(left: 2, top: 2, width: 4, height: 4) 
let assert Ok(ref) = bounding_box.ltwh(left: 4, top: 4, width: 6, height: 6) 
bounding_box.make_relative(box, to: ref)
// -> Some(bounding_box.ltwh(left: 0, top: 0, width: 2, height: 2))

scale

</>

pub fn scale(
  bounding_box: BoundingBox,
  by scale: Float,
) -> BoundingBox

Resizes a bounding box by the given scale.

shrink

</>

pub fn shrink(
  bounding_box: BoundingBox,
  by amount: Int,
) -> Result(BoundingBox, Nil)

Shrinks a bounding box by the given amount in all dimensions. If the amount is negative, the bounding box will not be modified. If the amount to shrink is greater than the size of the bounding box, an error will be returned.

to_ltrb_tuple

</>

pub fn to_ltrb_tuple(
  bounding_box: BoundingBox,
) -> #(Int, Int, Int, Int)

Converts a bounding box to a tuple with the coordinate values left, top, right, bottom. Useful for working with with custom bounding box operations.

Example

let assert Ok(box) = bounding_box.x1y1x2y2(x1: 2, y1: 2, x2: 6, y2: 6) 
bounding_box.to_ltrb_tuple(box)
// -> #(2, 2, 6, 6)

to_ltwh_tuple

</>

pub fn to_ltwh_tuple(
  bounding_box: BoundingBox,
) -> #(Int, Int, Int, Int)

Converts a bounding box to a tuple with the coordinate values left, top, width, height. Useful for working with with custom bounding box operations and getting the width and height of a bounding box.

Example

let assert Ok(box) = bounding_box.x1y1x2y2(x1: 2, y1: 2, x2: 6, y2: 6) 
bounding_box.to_ltwh_tuple(box)
// -> #(2, 2, 4, 4)

let assert Ok(box) = bounding_box.x1y1x2y2(x1: 4, y1: 4, x2: 10, y2: 10) 
let #(_, _, width, height) = bounding_box.to_ltwh_tuple(box)
// -> 6, 6

to_x1y1x2y2_tuple

</>

pub fn to_x1y1x2y2_tuple(
  bounding_box: BoundingBox,
) -> #(Int, Int, Int, Int)

Converts a bounding box to a tuple with the coordinate values x1, y1, x2, y2. Useful for working with with custom bounding box operations.

Example

let assert Ok(box) = bounding_box.ltwh(2, 2, 4, 4) 
bounding_box.to_x1y1x2y2_tuple(box)
// -> #(2, 2, 6, 6)

x1y1x2y2

</>

pub fn x1y1x2y2(
  x1 x1: Int,
  y1 y1: Int,
  x2 x2: Int,
  y2 y2: Int,
) -> Result(BoundingBox, Snag)

Creates a new bounding box from the given values in the (x1, y1), (x2, y2) rectangular coordinate format.