Image.Shape (image v0.62.0)

View Source

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)