Squircle (Squircle v1.0.0)

Generate parametrizable squircle paths and full SVG documents.

A squircle is a shape intermediate between a square and a circle — its corners are rounded by a parametrizable curvature factor (0.0 = round rectangle / full square with sharp corners, 1.0 = perfect circle).

Usage

Two high-level functions produce complete SVG documents:

image/5 — wraps an image URL inside a squircle-clipped SVG
svg_group/5 — wraps arbitrary SVG content inside a squircle-clipped SVG

For custom integrations, create/6 returns the raw path primitives (path data, viewbox, and transform string).

Curvature

The curvature parameter controls how rounded the corners are:

0.0 — sharp corners (a rounded rectangle with corner radius 0)
0.5 — medium rounding
0.8 — pill-like (the default)
1.0 — perfect circle (when width == height)

Summary

Functions

create(w, h, vw, vh, curvature \\ 0.8, rotate \\ 0)

Compute the raw squircle path primitives for the given dimensions.

image(href, size, padding \\ 0, curvature \\ 0.8, opts \\ [id: nil])

Generate a complete SVG document wrapping an image inside a squircle.

svg_group(svg_g, size, padding \\ 0, curvature \\ 0.8, opts \\ [id: nil])

Generate a complete SVG document wrapping SVG content inside a squircle.

Functions

create(w, h, vw, vh, curvature \\ 0.8, rotate \\ 0)

(since 0.1.0)

Compute the raw squircle path primitives for the given dimensions.

Returns a map with four keys:

:arc — the corner arc radius (derived from size and curvature)
:path_d — the SVG path d attribute string for the squircle outline
:path_transform — the SVG transform attribute string (rotation + centering translation)
:viewbox — the SVG viewBox attribute string

This is the low-level building block used by image/5 and svg_group/5. Use it when you need to integrate the squircle path into a custom SVG.

Examples

iex> result = Squircle.create(100, 100, 100, 100, 0.8)
iex> Map.keys(result) |> Enum.sort()
[:arc, :path_d, :path_transform, :viewbox]

iex> Squircle.create(100, 100, 100, 100, 0).arc
50.0

iex> Squircle.create(100, 100, 100, 100, 1).arc
0.0

iex> Squircle.create(100, 100, 100, 100, 0.5).viewbox
"0 0 100 100"

image(href, size, padding \\ 0, curvature \\ 0.8, opts \\ [id: nil])

(since 0.1.0)

Generate a complete SVG document wrapping an image inside a squircle.

The image at href is embedded in an SVG <pattern> and rendered through a squircle-shaped <path>, producing a visually cropped result.

Examples

iex> svg = Squircle.image("https://example.com/img.png", 100)
iex> String.starts_with?(svg, "<svg")
true
iex> String.ends_with?(svg, "</svg>")
true
iex> String.contains?(svg, "viewBox")
true

With padding and custom curvature:

iex> svg = Squircle.image("test.png", 50, 10, 0.5)
iex> String.contains?(svg, ~s(viewBox="0 0 70 70"))
true

svg_group(svg_g, size, padding \\ 0, curvature \\ 0.8, opts \\ [id: nil])

(since 0.1.0)

Generate a complete SVG document wrapping SVG content inside a squircle.

The given SVG fragment is embedded in a <pattern> and rendered through a squircle-shaped <path>. Useful for cropping arbitrary SVG graphics (icons, shapes, text) into a squircle.

Examples

iex> svg = Squircle.svg_group(~s(<rect width="40" height="40" fill="red" />), 100)
iex> String.starts_with?(svg, "<svg")
true
iex> String.ends_with?(svg, "</svg>")
true
iex> String.contains?(svg, ~s(<rect width="40" height="40"))
true