Visualize.Shape.Line (Visualize v0.2.25)

Line generator for creating SVG paths from data points.

Similar to D3's line generator, this produces path data for line charts.

Examples

data = [
  %{date: ~D[2024-01-01], value: 10},
  %{date: ~D[2024-01-02], value: 25},
  %{date: ~D[2024-01-03], value: 15}
]

line = Visualize.Shape.Line.new()
  |> Visualize.Shape.Line.x(fn d -> scale_x.(d.date) end)
  |> Visualize.Shape.Line.y(fn d -> scale_y.(d.value) end)
  |> Visualize.Shape.Line.curve(:monotone_x)

path_data = Visualize.Shape.Line.generate(line, data)

Summary

Types

accessor()

t()

Functions

curve(line, curve_type, opts \\ [])

Sets the curve interpolation type.

defined(line, predicate)

Sets the defined predicate function.

generate(line, data)

Generates the SVG path data string from the data.

generate_path(line, data)

Generates a Path struct from the data.

new()

Creates a new line generator

x(line, accessor)

Sets the x accessor: a 1-arity function, a field name, or a constant.

y(line, accessor)

Sets the y accessor: a 1-arity function, a field name, or a constant.

Types

accessor()

@type accessor() :: (any() -> number()) | atom() | number()

t()

@type t() :: %Visualize.Shape.Line{
  curve: Visualize.Shape.Curve.curve_type(),
  curve_opts: keyword(),
  defined: (any() -> boolean()) | nil,
  x: accessor() | nil,
  y: accessor() | nil
}

Functions

curve(line, curve_type, opts \\ [])

@spec curve(t(), Visualize.Shape.Curve.curve_type(), keyword()) :: t()

Sets the curve interpolation type.

Available curves:

:linear - straight lines (default)
:step - step at midpoint
:step_before - step at start
:step_after - step at end
:basis - B-spline
:cardinal - cardinal spline (use curve_opts for tension)
:catmull_rom - Catmull-Rom spline (use curve_opts for alpha)
:monotone_x - monotone cubic (preserves monotonicity in x)
:monotone_y - monotone cubic (preserves monotonicity in y)
:natural - natural cubic spline

defined(line, predicate)

@spec defined(t(), (any() -> boolean())) :: t()

Sets the defined predicate function.

A datum for which it returns a falsy value breaks the line: the points before it and the points after it become separate subpaths, so the gap is visible.

generate(line, data)

@spec generate(t(), Visualize.Data.Table.source()) :: String.t()

Generates the SVG path data string from the data.

Note: For backend-agnostic usage, prefer generate_path/2 and render with your chosen backend.

generate_path(line, data)

@spec generate_path(t(), Visualize.Data.Table.source()) :: Visualize.IR.Path.t()

Generates a Path struct from the data.

Each run of consecutive defined data (see defined/2) becomes one subpath, generated through the curve; a run of fewer than two points draws nothing.

new()

@spec new() :: t()

Creates a new line generator

x(line, accessor)

@spec x(t(), accessor()) :: t()

Sets the x accessor: a 1-arity function, a field name, or a constant.

Examples

Line.x(line, fn d -> d.timestamp end)
Line.x(line, :x)  # a field: reads :x or "x", see Visualize.Data.Table.get/2
Line.x(line, 0)   # every point at x = 0

y(line, accessor)

@spec y(t(), accessor()) :: t()

Sets the y accessor: a 1-arity function, a field name, or a constant.