View Source Image.Shape (image v0.32.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

Link to this section Summary

Types

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

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

Functions

Creates an image of a polygon.

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

Creates a image of a rectangle.

Creates a image of a rectangle or raises and exception.

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

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

Link to this section Types

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

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

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

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

Link to this section Functions

Link to this function

polygon(points, options \\ [])

View Source
@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

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

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

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

Returns

  • {:ok, image} or

  • {:error, reason}

examples

Examples

Link to this function

polygon!(points, options \\ [])

View Source
@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

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

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

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

Returns

  • image or

  • raises an exception

examples

Examples

Link to this function

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

View Source (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

Options

  • :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 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.

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

returns

Returns

  • {:ok, rectangle_image} or

  • {:error, reason}

examples

Examples

Link to this function

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

View Source (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

Options

  • :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 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.

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

returns

Returns

  • rectangle_image or

  • raises an exception.

examples

Examples

Link to this function

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

View Source
@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

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

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

Returns

  • {:ok, image} or

  • {:error, reason}

examples

Examples

#=> {:ok, star} = Image.Shape.star
#=> {:ok, star} = Image.Shape.star 5, rotation: 90, fill_color: :red, stroke_color: :green
Link to this function

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

View Source
@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

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

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

Returns

  • image or

  • raises an exception

examples

Examples

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