# `Image.Shape`
[🔗](https://github.com/elixir-image/image/blob/v0.66.0/lib/image/shape.ex#L1)

Functions to render a shape as an image.

The supported shapes match those defined in
[Scalable Vector Graphics](https://developer.mozilla.org/en-US/docs/Web/SVG)
including:

* Rectangle
* Polygon
* Circle
* Ellipse
* Line

# `path`

```elixir
@type path() :: String.t() | [point(), ...]
```

A path is a list of points representing
a path, open polygon or closed polygon.

# `point`

```elixir
@type point() :: [integer()]
```

A point is a list of two integers
representing the `x` and `y` coordinates

# `circle`
*since 1.38.0* 

```elixir
@spec circle(radius :: pos_integer(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Creates an image of a circle.

* `radius` is the radius of the circle in pixels.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  circle. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the circle. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the circle. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Returns

* `{:ok, circle_image}` or

* `{:error, reason}`

### Example

      iex> {:ok, circle} = Image.Shape.circle(50, fill_color: :green, stroke_color: :blue)

# `circle!`
*since 1.38.0* 

```elixir
@spec circle!(radius :: pos_integer(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Creates an image of a circle or raises an exception.

* `radius` is the radius of the circle in pixels.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  circle. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the circle. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the circle. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Returns

* `circle_image` or

* raises an exception.

### Example

      iex> circle = Image.Shape.circle!(50, fill_color: :green, stroke_color: :blue)

# `ellipse`
*since 1.38.0* 

```elixir
@spec ellipse(
  x_radius :: pos_integer(),
  y_radius :: pos_integer(),
  options :: Keyword.t()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Creates an image of a ellipse.

* `x_radius` is the radius of the x-aixs of the
  ellipse in pixels.

* `y_radius` is the radius of the y-aixs of the
  ellipse in pixels.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  ellipse. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the ellipse. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the ellipse. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Returns

* `{:ok, ellipse_image}` or

* `{:error, reason}`

### Examples

      iex> {:ok, ellipse} = Image.Shape.ellipse(50, 100, fill_color: :green, stroke_color: :none)

# `ellipse!`
*since 1.38.0* 

```elixir
@spec ellipse!(
  x_radius :: pos_integer(),
  y_radius :: pos_integer(),
  options :: Keyword.t()
) ::
  Vix.Vips.Image.t() | no_return()
```

Creates an image of a ellipse or raises an exception.

* `x_radius` is the radius of the x-aixs of the
  ellipse in pixels.

* `y_radius` is the radius of the y-aixs of the
  ellipse in pixels.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  ellipse. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the rectangle. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the polygon. The default is `:black`

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Returns

* `ellipse_image` or

* raises an exception.

### Example

      iex> ellipse = Image.Shape.ellipse!(50, 100, fill_color: :green, stroke_color: :none)

# `line`
*since 1.38.0* 

```elixir
@spec line(
  x1 :: pos_integer(),
  y1 :: pos_integer(),
  x2 :: pos_integer(),
  y2 :: pos_integer(),
  options :: Keyword.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Creates an image of a line.

* `x1` Defines the x-axis coordinate of the line
  starting point in pixels.

* `y1` Defines the y-axis coordinate of the line
  starting point in pixels.

* `x2` Defines the x-axis coordinate of the line
  ending point in pixels.

* `y2` Defines the y-axis coordinate of the line
  ending point in pixels.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  line. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the line. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the line. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Returns

* `{:ok, line_image}` or

* `{:error, reason}`

### Examples

      iex> {:ok, line} = Image.Shape.line(5, 5, 50, 50, stroke_width: 10, stroke_color: :white)

# `line!`
*since 1.38.0* 

```elixir
@spec line!(
  x1 :: pos_integer(),
  y1 :: pos_integer(),
  x2 :: pos_integer(),
  y2 :: pos_integer(),
  options :: Keyword.t()
) :: Vix.Vips.Image.t() | no_return()
```

Creates a image of a line or raises an exception.

* `x1` Defines the x-axis coordinate of the line
  starting point in pixels.

* `y1` Defines the y-axis coordinate of the line
  starting point in pixels.

* `x2` Defines the x-axis coordinate of the line
  ending point in pixels.

* `y2` Defines the y-axis coordinate of the line
  ending point in pixels.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:stroke_width` is the width of the line used
  to draw the rectangle. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the polygon. The default is `:black`

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Returns

* `line_image` or

* raises an exception.

### Example

      iex> line = Image.Shape.line!(5, 5, 50, 50, stroke_width: 10, stroke_color: :white)

# `polygon`

```elixir
@spec polygon(points :: path(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
@spec polygon(sides :: pos_integer(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Creates an image of a polygon.

### Arguments

* `points` defines the points of the polygon. The
  origin is the top left of the image with a positive
  `x` value moving from right to left and a positive
  `y` value moving from top to bottom.  The points can
  be an [SVG point string](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/points)
  or a "list of lists" of the form
  `[[x1, y1], [x2, y2], ...]` where `x1` and `y1`
  are integers.  `points` can also be a positive
  integer >= 3 which indicates that an `n` sided
  polygon will be generated. In this case the options
  `:rotation` and `:radius` are also applicable.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:width` is the width of the canvas onto which the
  polygon is drawn. The default is `500` pixels.

* `:height` is the height of the canvas onto which the
  polygon is drawn. The default is `500` pixels.

* `:fill_color` is the color used to fill in the
  polygon. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the polygon. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the polygon. The default is `:black`

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

* `:rotation` is the number of degrees to rotate the
  axis of a generated n-sided polygon. This option is
  only valid if `points` is an integer >= 3.
  The default is `180`.

* `:radius` indicates the radius in pixels of a generated
  n-sided polygon. The default is `100`.

### Notes

* The polygon points are scaled to fit the canvas size
  defined by `:width` and `:height` This means that the
  resulting image will fill the canvas. This is useful
  for composing images. Define the canvas to be the size
  intended to be composed into a base image and the
  polygon will be scaled to fit.

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Examples

# `polygon!`

```elixir
@spec polygon!(points :: path(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Creates an image of a polygon as a single
band image on a transparent background.

### Arguments

* `points` defines the points of the polygon. The
  origin is the top left of the image with a positive
  `x` value moving from right to left and a positive
  `y` value moving from top to bottom.  The points can
  be an [SVG point string](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/points)
  or a "list of lists" of the form
  `[[x1, y1], [x2, y2], ...]` where `x1` and `y1`
  are integers.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:width` is the width of the canvas onto which the
  polygon is drawn. The default is `500` pixels.

* `:height` is the width of the canvas onto which the
  polygon is drawn. The default is `500` pixels.

* `:fill_color` is the color used to fill in the
  polygon. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the polygon. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the polygon. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

### Notes

* The polygon points are scaled to fit the canvas size
  defined by `:width` and `:height` This means that the
  resulting image will fill the canvas. This is useful
  for composing images. Define the canvas to be the size
  intended to be composed into a base image and the
  polygon will be scaled to fit.

* Colors may be any valid
  [CSS color name](https://www.w3.org/wiki/CSS/Properties/color/keywords) or
  a six hexadecimal digit string prefixed with `#`. For example
  `#FF00FF` for the color "Fuchsia".

### Returns

* `image` or

* raises an exception

### Examples

# `rect`
*since 1.27.0* 

```elixir
@spec rect(width :: pos_integer(), height :: pos_integer(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Creates a image of a rectangle.

* `width` is the number of pixels wide.

* `height` is the number of pixels high.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  rectangle. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the rectangle. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the rectangle. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

* `:rotation` is the number of degrees to rotate the
  axis of a generated rectangle.

### Returns

* `{:ok, rectangle_image}` or

* `{:error, reason}`

### Example

      iex> {:ok, rectangle} = Image.Shape.rect(50, 100, fill_color: :red, stroke_color: :yellow)

# `rect!`
*since 1.27.0* 

```elixir
@spec rect!(width :: pos_integer(), height :: pos_integer(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Creates a image of a rectangle or raises
and exception.

* `width` is the number of pixels wide.

* `height` is the number of pixels high.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:fill_color` is the color used to fill in the
  rectangle. The default is `:none`.

* `:stroke_width` is the width of the line used
  to draw the rectangle. The default is `1px`.

* `:stroke_color` is the color used for the outline
  of the rectangle. The default is `:black`.

* `:opacity` is the opacity as a float between
  `0.0` and `1.0` where `0.0` is completely transparent
  and `1.0` is completely opaque. The default is `0.7`.

* `:rotation` is the number of degrees to rotate the
  axis of a generated rectangle.

### Returns

* `rectangle_image` or

* raises an exception.

### Examples

      iex> rectangle = Image.Shape.rect!(50, 100, fill_color: :red, stroke_color: :yellow)

# `star`

```elixir
@spec star(points :: pos_integer(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
```

Returns an image of an n-pointed star that
can be composed over other images.

### Arguments

* `points` is an integer number of points
  on the star. `points` must be >= 3. The default
  is `5`.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:inner_radius` is the size of the inner
  radius. The default is `60`.

* `:outer_radius` is the size of the outer
  radius. The default is `150`.

* `:rotation` is the angle in degrees of rotation
  applied to the points. The default is `0`.

* Any remaining options are passed to `Image.Shape.polygon/2`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Examples

    iex> {:ok, star} = Image.Shape.star
    iex> {:ok, star} = Image.Shape.star(5, rotation: 90, fill_color: :red, stroke_color: :green)

# `star!`

```elixir
@spec star!(points :: pos_integer(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Returns an image of an n-pointed star that
can be composed over other images.

### Arguments

* `points` is an integer number of points
  on the star. `points` must be >= 3. The default
  is `5`.

* `options` is a `t:Keyword.t/0` list of options.

### Options

* `:inner_radius` is the size of the inner
  radius. The default is `60`.

* `:outer_radius` is the size of the outer
  radius. The default is `150`.

* `:rotation` is the angle in degrees of rotation
  applied to the points. The default is `0`.

* Any remaining options are passed to `Image.Shape.polygon/2`.

### Returns

* `image` or

* raises an exception.

### Examples

    iex> star = Image.Shape.star!
    iex> star = Image.Shape.star!(5, rotation: 90, fill_color: :red, stroke_color: :green)

---

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