Image.Draw (image v0.65.0)

Copy Markdown View Source

Functions to draw directly on a mutable image.

Note that while the functions in this module mutate an image, the mutations are performed on a copy of the image so no harm will come to other functions maintaining a reference to the original image.

Summary

Types

box()

Bounding box returned from Image.Draw.flood/4

Functions

circle(image, cx, cy, radius, options \\ [])

Draw a circle on a mutable image.

circle!(image, cx, cy, radius, options \\ [])

Draw a circle on a mutable image returning the mutated image or raises an exception.

flood(image, left, top, options \\ [])

Flood-fill image with color, starting at position top, left.

flood!(image, left, top, options \\ [])

Flood-fill image with color, starting at position top, left or raise an exception.

image(image, sub_image, top, left, options \\ [])

Draw one image over the top of a mutable image.

image!(image, sub_image, top, left, options \\ [])

Draw one image over the top of a mutable image or raises an exception.

is_circle(cx, cy, radius)

Validates acceptable circle dimensions

is_point(left, top)

Validate a point location on an image

line(image, x1, y1, x2, y2, options \\ [])

Draw a line on a mutable image.

line!(image, x1, y1, x2, y2, options \\ [])

Draw a line on a mutable image returning the mutated image or raising an exception.

mask(image, mask, x, y, options \\ [])

Draw mask on the image.

point(image, left, top, options \\ [])

Draw a point on a mutable image.

point!(image, left, top, options)

Draw a point on a mutable image returning the mutated image or raising an exception.

rect(image, left, top, width, height, options \\ [])

Draw a rectangle on a mutable image.

rect!(image, left, top, width, height, options \\ [])

Draw a rectangle on a mutable image and returns the mutated image or raises an exception.

smudge(image, left, top, width, height, options \\ [])

Smudge a section of image .

Types

box()

@type box() :: %{
  height: non_neg_integer(),
  width: non_neg_integer(),
  top: non_neg_integer(),
  left: non_neg_integer()
}

Bounding box returned from Image.Draw.flood/4

Functions

circle(image, cx, cy, radius, options \\ [])

(since 0.7.0) 
@spec circle(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.circle()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}

Draw a circle on a mutable image.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • cx is the 0-based offset from the left edge of the image indicating where the center of the circle will be localed.

  • cy is the 0-based offset from the top edge of the image indicating where the center of the circle will be localed.

  • radius is the radius of the drawn circle.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

  • :fill is a boolean indicating whether the rectangle is to be filled with :color. The default is true.

  • :stroke_width indicates the width in pixels of the stroke that forms the rectangle. The default is 1. Values greater than 1 will have a negative performance impact since the rectangle will be draw as 4 filled rectangles forming each of the four sides. If fill: true is set then this options is ignored.

Returns

  • {:ok, image} where image is the same type as that passed as an argument to the function.

  • or {:error, reason}

Examples

iex> image = Image.new!(20, 20, color: :white)
iex> {:ok, with_circle} = Image.Draw.circle(image, 10, 10, 5, color: :red)
iex> Image.get_pixel!(with_circle, 10, 10)
[255, 0, 0]

circle!(image, cx, cy, radius, options \\ [])

(since 0.17.0) 
@spec circle!(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.circle()
) :: Vix.Vips.Image.t() | Vix.Vips.MutableImage.t() | no_return()

Draw a circle on a mutable image returning the mutated image or raises an exception.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • cx is the 0-based offset from the left edge of the image indicating where the center of the circle will be localed.

  • cy is the 0-based offset from the top edge of the image indicating where the center of the circle will be localed.

  • radius is the radius of the drawn circle.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

  • :fill is a boolean indicating whether the rectangle is to be filled with :color. The default is true.

Returns

  • image where image is the same type as that passed as an argument to the function or

  • raises an exception.

flood(image, left, top, options \\ [])

(since 0.7.0) 
@spec flood(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.flood()
) :: {:ok, {Vix.Vips.Image.t(), box()}} | {:error, Image.error()}

Flood-fill image with color, starting at position top, left.

The filled area is bounded by pixels that are equal to the :colour. That is, it searches for pixels enclosed by an edge of :color.

If :equal is true, it instead searches for pixels which are equal to the start point and fills them with :color.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • left is the 0-based offset from the left edge of the image where the flood will be drawn.

  • top is the 0-based offset from the top edge of the image where the flood will drawn.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • {:ok, {image, height, width, top, left} where image is the same type as that passed as an argument to the function. height and width represent the dimensions of the flood fill in pixels. top and left are the 0-based offsets from the top and left location respectively of the flood area.

  • or {:error, reason}.

flood!(image, left, top, options \\ [])

(since 0.24.0) 
@spec flood!(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.flood()
) :: Vix.Vips.Image.t() | no_return()

Flood-fill image with color, starting at position top, left or raise an exception.

The filled area is bounded by pixels that are equal to the :colour. That is, it searches for pixels enclosed by an edge of :color.

If :equal is true, it instead searches for pixels which are equal to the start point and fills them with :color.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • left is the 0-based offset from the left edge of the image where the flood will be drawn.

  • top is the 0-based offset from the top edge of the image where the flood will drawn.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • image where image is the same type as that passed as an argument to the function or

  • raises an exception.

image(image, sub_image, top, left, options \\ [])

(since 0.7.0) 
@spec image(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  Vix.Vips.Image.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.image()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}

Draw one image over the top of a mutable image.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • sub_image is any t:Vimage.t/0 that is drawn on top of image.

  • left is the 0-based offset from the left edge of the image where the sub-image will be drawn.

  • top is the 0-based offset from the top edge of the image where the sub-image will be drawn.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • {:ok, image} where image is the same type as that passed as an argument to the function.

  • or {:error, reason}

image!(image, sub_image, top, left, options \\ [])

(since 0.25.0) 
@spec image!(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  Vix.Vips.Image.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.image()
) :: Vix.Vips.Image.t() | Vix.Vips.MutableImage.t() | no_return()

Draw one image over the top of a mutable image or raises an exception.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • sub_image is any t:Vimage.t/0 that is drawn on top of image.

  • left is the 0-based offset from the left edge of the image where the sub-image will be drawn.

  • top is the 0-based offset from the top edge of the image where the sub-image will be drawn.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • image where image is the same type as that passed as an argument to the function.

  • raises an exception.

is_circle(cx, cy, radius)

(macro)

Validates acceptable circle dimensions

is_point(left, top)

(macro)

Validate a point location on an image

line(image, x1, y1, x2, y2, options \\ [])

(since 0.7.0) 
@spec line(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.line()
) ::
  {:ok, Vix.Vips.Image.t() | Vix.Vips.MutableImage.t()}
  | {:error, Image.error()}

Draw a line on a mutable image.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • x1, y1 are the 0-based offsets from the left and top accordingly indicating the point at the start of the line.

  • x2, y2 are the 0-based offsets from the left and top accordingly indicating the point at the end of the line.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • {:ok, image} where image is the same type as that passed as an argument to the function.

  • or {:error, reason}

Examples

iex> image = Image.new!(20, 20, color: :white)
iex> {:ok, with_line} = Image.Draw.line(image, 0, 0, 19, 19, color: :red)
iex> Image.get_pixel!(with_line, 0, 0)
[255, 0, 0]

line!(image, x1, y1, x2, y2, options \\ [])

(since 0.17.0) 
@spec line!(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.line()
) :: Vix.Vips.Image.t() | Vix.Vips.MutableImage.t() | no_return()

Draw a line on a mutable image returning the mutated image or raising an exception.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • x1, y1 are the 0-based offsets from the left and top accordingly indicating the point at the start of the line.

  • x2, y2 are the 0-based offsets from the left and top accordingly indicating the point at the end of the line.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • image where image is the same type as that passed as an argument to the function or

  • raises an exception.

mask(image, mask, x, y, options \\ [])

(since 0.7.0) 
@spec mask(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  Vix.Vips.Image.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.mask()
) ::
  {:ok,
   {Vix.Vips.Image.t(),
    height: integer(), width: integer(), top: integer(), left: integer()}}
  | {:error, Image.error()}

Draw mask on the image.

Mask is a monochrome 8-bit image with the values of 0 or 255 for transparent and any other value as a color to be blended into the base image.

point(image, left, top, options \\ [])

(since 0.7.0) 
@spec point(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.point()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}

Draw a point on a mutable image.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • left is the 0-based offset from the left edge of the image where the point will be drawn.

  • top is the 0-based offset from the top edge of the image where the point will be drawn.

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

Returns

  • {:ok, image} where image is the same type as that passed as an argument to the function.

  • or {:error, reason}

Examples

iex> image = Image.new!(10, 10, color: :white)
iex> {:ok, with_dot} = Image.Draw.point(image, 5, 5, color: :red)
iex> Image.shape(with_dot)
{10, 10, 3}

iex> image = Image.new!(10, 10, color: :white)
iex> {:ok, with_dot} = Image.Draw.point(image, 5, 5, color: :red)
iex> Image.get_pixel!(with_dot, 5, 5)
[255, 0, 0]

point!(image, left, top, options)

(since 0.17.0) 
@spec point!(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Draw.point()
) :: Vix.Vips.Image.t() | Vix.Vips.MutableImage.t() | no_return()

Draw a point on a mutable image returning the mutated image or raising an exception.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • left is the 0-based offset from the left edge of the image where the point will be drawn.

  • top is the 0-based offset from the top edge of the image where the point will be drawn.

  • options is a keyword list of options. The default is color: :black. See the options for Image.Draw.point/4.

Returns

  • image where image is the same type as that passed as an argument to the function or

  • raises an exception.

rect(image, left, top, width, height, options \\ [])

(since 0.7.0) 
@spec rect(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  pos_integer(),
  pos_integer(),
  Image.Options.Draw.rect()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}

Draw a rectangle on a mutable image.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • left is the 0-based offset from the left edge of the image where the rectangle will be drawn.

  • top is the 0-based offset from the top edge of the image where the rectangle will be drawn.

  • width is the width of the rectangle

  • height is the height of the rectangle

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

  • :fill is a boolean indicating whether the rectangle is to be filled with :color. The default is true.

  • :stroke_width indicates the width in pixels of the stroke that forms the rectangle. The default is 1. Values greater than 1 will have a negative performance impact since the rectangle will be draw as 4 filled rectangles forming each of the four sides. If fill: true is set then this options is ignored.

Returns

  • {:ok, image} where image is the same type as that passed as an argument to the function or

  • {:error, reason}.

Examples

iex> image = Image.new!(20, 20, color: :white)
iex> {:ok, with_rect} = Image.Draw.rect(image, 4, 4, 10, 10, color: :red)
iex> Image.get_pixel!(with_rect, 8, 8)
[255, 0, 0]

iex> image = Image.new!(20, 20, color: :white)
iex> {:ok, with_rect} = Image.Draw.rect(image, 4, 4, 10, 10, color: :red, fill: false, stroke_width: 2)
iex> Image.shape(with_rect)
{20, 20, 3}

rect!(image, left, top, width, height, options \\ [])

(since 0.17.0) 
@spec rect!(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  pos_integer(),
  pos_integer(),
  Image.Options.Draw.rect()
) :: Vix.Vips.Image.t() | Vix.Vips.MutableImage.t() | no_return()

Draw a rectangle on a mutable image and returns the mutated image or raises an exception.

Arguments

  • image is any t:Vimage.t/0 or a t:MutableImage.t/0 upon which the rectangle will be drawn. If image is a t:MutableImage.t/0 it will be mutated directly. If image is a t:Vimage.t/0 it will be copied to a t:MutableImage.t/0 and then mutated.

  • left is the 0-based offset from the left edge of the image where the rectangle will be drawn.

  • top is the 0-based offset from the top edge of the image where the rectangle will be drawn.

  • width is the width of the rectangle

  • height is the height of the rectangle

  • options is a keyword list of options. The default is color: :black.

Options

  • :color defines the color of the point. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. Lastly, it can also be supplied as a hex string of the form #rrggbb. See Color.new/2 from the Color library.

  • :fill is a boolean indicating whether the rectangle is to be filled with :color. The default is true.

  • :stroke_width indicates the width in pixels of the stroke that forms the rectangle. The default is 1. Values greater than 1 will have a negative performance impact since the rectangle will be draw as 4 filled rectangles forming each of the four sides. If fill: true is set then this options is ignored.

Returns

  • image where image is the same type as that passed as an argument to the function or

  • raises an exception.

smudge(image, left, top, width, height, options \\ [])

(since 0.7.0) 
@spec smudge(
  Vix.Vips.Image.t() | Vix.Vips.MutableImage.t(),
  non_neg_integer(),
  non_neg_integer(),
  pos_integer(),
  pos_integer(),
  Image.Options.Draw.smudge()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}

Smudge a section of image .

Each pixel in the area left , top , width , height is replaced by the average of the surrounding 3x3 pixels.