View Source Image.Shape (image v0.44.0)

Functions to render a shape as an image.

The supported shapes match those defined in Scalable Vector Graphics including:

Rectangle
Polygon
Circle
Ellipse
Line

Summary

Types

path()

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

point()

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

Functions

circle(radius, options \\ [])

Creates an image of a circle.

circle!(radius, options \\ [])

Creates an image of a circle or raises an exception.

ellipse(x_radius, y_radius, options \\ [])

Creates an image of a ellipse.

ellipse!(x_radius, y_radius, options \\ [])

Creates an image of a ellipse or raises an exception.

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

Creates an image of a line.

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

Creates a image of a line or raises an exception.

polygon(points, options \\ [])

Creates an image of a polygon.

polygon!(points, options \\ [])

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

rect(width, height, options \\ [])

Creates a image of a rectangle.

rect!(width, height, options \\ [])

Creates a image of a rectangle or raises and exception.

star(points \\ 5, options \\ [])

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

star!(points \\ 5, options \\ [])

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

Types

path()

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

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

point()

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

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

Functions

circle(radius, options \\ [])

(since 1.38.0)

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

Creates an image of a circle.

radius is the radius of the circle in pixels.
options is a 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!(radius, options \\ [])

(since 1.38.0)

@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 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(x_radius, y_radius, options \\ [])

(since 1.38.0)

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

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 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!(x_radius, y_radius, options \\ [])

(since 1.38.0)

@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 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(x1, y1, x2, y2, options \\ [])

(since 1.38.0)

@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_message()}

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 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!(x1, y1, x2, y2, options \\ [])

(since 1.38.0)

@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 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(points, options \\ [])

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

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

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 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 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

Returns

{:ok, image} or
{:error, reason}

Examples

polygon!(points, options \\ [])

@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 or a "list of lists" of the form [[x1, y1], [x2, y2], ...] where x1 and y1 are integers.
options is a 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 or a six hexadecimal digit string prefixed with #. For example #FF00FF for the color "Fuchsia".

Returns

image or
raises an exception

Examples

rect(width, height, options \\ [])

(since 1.27.0)

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

Creates a image of a rectangle.

width is the number of pixels wide.
height is the number of pixels high.
options is a 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!(width, height, options \\ [])

(since 1.27.0)

@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 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(points \\ 5, options \\ [])

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

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 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!(points \\ 5, options \\ [])

@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 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)