# `Image.Draw`
[🔗](https://github.com/elixir-image/image/blob/v0.65.0/lib/image/draw.ex#L1)

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.

# `box`

```elixir
@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

# `circle`
*since 0.7.0* 

```elixir
@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!`
*since 0.17.0* 

```elixir
@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`
*since 0.7.0* 

```elixir
@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!`
*since 0.24.0* 

```elixir
@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`
*since 0.7.0* 

```elixir
@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!`
*since 0.25.0* 

```elixir
@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`
*macro* 

Validates acceptable circle dimensions

# `is_point`
*macro* 

Validate a point location on an image

# `line`
*since 0.7.0* 

```elixir
@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!`
*since 0.17.0* 

```elixir
@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`
*since 0.7.0* 

```elixir
@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`
*since 0.7.0* 

```elixir
@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!`
*since 0.17.0* 

```elixir
@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`
*since 0.7.0* 

```elixir
@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!`
*since 0.17.0* 

```elixir
@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`
*since 0.7.0* 

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*