GnuplotEx (gnuplot_ex v0.2.0)

Elixir wrapper for Gnuplot 6+.

GnuplotEx provides both low-level and high-level APIs for creating plots. This module contains the low-level API that gives direct control over gnuplot commands.

Requirements

  • Gnuplot 6.0+ installed and available in PATH
  • Elixir 1.18+

Quick Start

# Plot a sine wave to SVG
GnuplotEx.plot([
  [:set, :terminal, :svg, :size, {800, 600}],
  [:set, :output, "/tmp/sine.svg"],
  [:plot, 'sin(x)']
])

# Plot data points
data = for x <- 1..100, do: [x, :math.sin(x / 10)]

GnuplotEx.plot([
  [:set, :terminal, :svg],
  [:set, :output, "/tmp/data.svg"],
  [:plot, "-", :with, :lines, :title, "Sine Wave"]
], [data])

Command Syntax

Commands are represented as nested lists where:

  • Atoms become unquoted strings: :setset
  • Strings become quoted: "Title""Title"
  • Charlists become raw expressions: 'sin(x)'sin(x)
  • Ranges become gnuplot ranges: 0..10[0:10]
  • Tuples become comma-separated: {800, 600}800,600

Multiple Datasets

Use plots/1 or splots/1 to plot multiple datasets:

GnuplotEx.plot([
  [:set, :terminal, :svg],
  [:set, :output, "/tmp/multi.svg"],
  GnuplotEx.plots([
    ["-", :with, :points, :title, "Points"],
    ["-", :with, :lines, :title, "Lines"]
  ])
], [data1, data2])

Summary

Functions

Set the azimuth angle for 3D plots.

Build an inspectable spec from commands and datasets.

Show or hide the colorbar.

Set the colorbar range.

Add a raw gnuplot command (escape hatch).

Add a contour plot.

Define a named datablock for reuse across multiple series.

Add a donut chart series.

Add a histogram series.

Set the legend position.

Add a line plot series.

Create a new empty plot for the fluent builder API.

Apply a nonlinear transformation to an axis.

Set the color palette for surfaces and heatmaps.

Add a parallel coordinates series.

Add a parametric surface plot.

Add a pie chart series.

Execute gnuplot commands without datasets.

Execute gnuplot commands with datasets.

Execute gnuplot commands with a third argument.

Build a comma-separated plot list for multiple 2D datasets.

Add a 3D polygon mesh series.

Add a 2D polygon series.

Render a plot to a specific format.

Render plot asynchronously, returning a Task.

Render multiple plots in parallel.

Export plot as a reproducible gnuplot script file.

Add a 3D scatter series.

Add a scatter plot series.

List all active named sessions.

Set the plot size.

Add a spider/radar chart series.

Build a comma-separated splot list for multiple 3D datasets.

Add a surface plot.

Set the plot theme.

Set the plot title.

Render plot to ASCII art.

Render plot to PNG file.

Convert a Plot to a Spec for inspection without execution.

Render plot to SVG file.

Remove a nonlinear transformation from an axis.

Get the installed gnuplot version.

Check if gnuplot version meets the minimum requirement (6.0.0).

Set the 3D view angle.

Set the X-axis label.

Set the X-axis range.

Set the Y-axis label.

Set the Y-axis range.

Set the Z-axis label (for 3D plots).

Set the Z-axis range (for 3D plots).

Types

command()

@type command() :: [command_term()]

command_term()

@type command_term() ::
  atom() | String.t() | charlist() | number() | Range.t() | tuple()

dataset()

@type dataset() :: [[number()] | tuple()]

plot_option()

@type plot_option() :: {:dry, boolean()}

Functions

azimuth(plot, angle)

@spec azimuth(GnuplotEx.Plot.t(), number()) :: GnuplotEx.Plot.t()

Set the azimuth angle for 3D plots.

Example

plot |> GnuplotEx.azimuth(30)

build_spec(commands, datasets \\ [])

@spec build_spec([command()], [dataset()]) :: GnuplotEx.Spec.t()

Build an inspectable spec from commands and datasets.

Useful for debugging or deferred execution.

Example

spec = GnuplotEx.build_spec(commands, data)
IO.inspect(spec)

# Execute later
{:ok, _} = GnuplotEx.Spec.execute(spec)

colorbar(plot, setting)

@spec colorbar(GnuplotEx.Plot.t(), :on | :off) :: GnuplotEx.Plot.t()

Show or hide the colorbar.

Example

plot |> GnuplotEx.colorbar(:off)

colorbar_range(plot, range)

@spec colorbar_range(GnuplotEx.Plot.t(), Range.t() | {number(), number()}) ::
  GnuplotEx.Plot.t()

Set the colorbar range.

Controls the data range mapped to the color palette.

Example

plot |> GnuplotEx.colorbar_range(0..100)
plot |> GnuplotEx.colorbar_range({-1, 1})

command(plot, cmd)

@spec command(GnuplotEx.Plot.t(), list()) :: GnuplotEx.Plot.t()

Add a raw gnuplot command (escape hatch).

Example

plot |> GnuplotEx.command([:set, :grid])

contour(plot, data_or_fn)

contour(plot, data_or_fn, opts)

@spec contour(GnuplotEx.Plot.t(), Enumerable.t() | fun(), keyword()) ::
  GnuplotEx.Plot.t()

Add a contour plot.

Options

  • :label - Legend label
  • :contour_levels - Number of contour levels
  • :contour_style - :base (default), :surface, or :both

Example

data = for x <- -5..5, y <- -5..5, do: [x, y, x*x + y*y]
GnuplotEx.contour(data, contour_levels: 10)

datablock(plot, name, data)

@spec datablock(GnuplotEx.Plot.t(), atom(), Enumerable.t()) :: GnuplotEx.Plot.t()

Define a named datablock for reuse across multiple series.

Named datablocks allow you to define data once and reference it multiple times in different plot commands. This is useful when the same data should be displayed with different styles (e.g., as both scatter and line).

Example

GnuplotEx.new()
|> GnuplotEx.datablock(:mydata, [[1, 2], [3, 4], [5, 6]])
|> GnuplotEx.scatter(:mydata, label: "Points")
|> GnuplotEx.line(:mydata, label: "Line")
|> GnuplotEx.to_svg("/tmp/reused_data.svg")

donut(plot, data)

donut(plot, data, opts)

Add a donut chart series.

Donut charts are pie charts with a hollow center. This is achieved by setting an inner radius that creates a ring-shaped visualization.

Data Formats

Same as pie/2,3:

  • List of numbers: [30, 25, 20]
  • List of {label, value} tuples: [{"A", 30}, {"B", 25}]
  • List of maps: [%{label: "A", value: 30}, %{label: "B", value: 25}]

Options

  • :inner_radius - Inner radius ratio 0.0-1.0 (default: 0.5)
  • :labels - List of slice labels
  • :colors - List of colors or palette name
  • :explode - List of slice indices to offset outward
  • :start_angle - Starting angle in degrees

Examples

# Default donut (50% hole)
[30, 25, 20, 15, 10]
|> GnuplotEx.donut()
|> GnuplotEx.to_svg("/tmp/donut.svg")

# Thin ring
GnuplotEx.donut(data, inner_radius: 0.7)

# With styling
GnuplotEx.new()
|> GnuplotEx.title("Distribution")
|> GnuplotEx.donut(data, ir: 0.4, colors: :plasma)

histogram(plot, data)

histogram(plot, data, opts)

@spec histogram(GnuplotEx.Plot.t(), Enumerable.t(), keyword()) :: GnuplotEx.Plot.t()

Add a histogram series.

Options

  • :label - Legend label
  • :color - Bar color
  • :bins - Number of bins
  • :fill - Fill style (:solid, :transparent)

Example

values |> GnuplotEx.histogram(bins: 20) |> GnuplotEx.to_svg(path)

legend(plot, position)

@spec legend(GnuplotEx.Plot.t(), atom()) :: GnuplotEx.Plot.t()

Set the legend position.

Positions

  • :top_right (default)
  • :top_left
  • :bottom_right
  • :bottom_left
  • :off - Hide legend

Example

plot |> GnuplotEx.legend(:top_left)

line(plot, data)

line(plot, data, opts)

Add a line plot series.

Options

  • :label - Legend label
  • :color - Line color
  • :line_width - Line width
  • :smooth - Smoothing (:csplines, :bezier)

Example

GnuplotEx.new()
|> GnuplotEx.line(data, label: "Trend", color: "#666")

new(opts \\ [])

@spec new(keyword()) :: GnuplotEx.Plot.t()

Create a new empty plot for the fluent builder API.

Options

  • :title - Plot title
  • :size - Plot dimensions as {width, height}
  • :theme - Theme preset or custom theme

Example

GnuplotEx.new()
|> GnuplotEx.title("My Plot")
|> GnuplotEx.scatter(data)
|> GnuplotEx.to_svg("/tmp/plot.svg")

nonlinear(plot, axis, transform)

Apply a nonlinear transformation to an axis.

Nonlinear transformations use gnuplot 6's set nonlinear command to create log scales, square root scales, and other nonlinear axis mappings.

Preset Transformations

  • :log10 - Base-10 logarithmic scale
  • :log - Natural logarithmic scale
  • :sqrt - Square root scale
  • :inverse - Reciprocal scale (1/x)
  • :probit - Probit (normal CDF) scale
  • :logit - Logit scale

Supported Axes

  • :x, :x2 - X axes
  • :y, :y2 - Y axes
  • :z - Z axis (3D)
  • :r - Radial axis (polar)
  • :cb - Colorbar axis

Examples

# Log scale on X axis
GnuplotEx.new()
|> GnuplotEx.scatter(data)
|> GnuplotEx.nonlinear(:x, :log10)
|> GnuplotEx.to_svg("/tmp/logscale.svg")

# Multiple axes with different transforms
GnuplotEx.new()
|> GnuplotEx.scatter(data)
|> GnuplotEx.nonlinear(:x, :log10)
|> GnuplotEx.nonlinear(:y, :sqrt)

# Custom transformation
GnuplotEx.nonlinear(plot, :y, via: "sqrt(y)", inverse: "y**2")

palette(plot, palette_value)

@spec palette(GnuplotEx.Plot.t(), atom() | [String.t()]) :: GnuplotEx.Plot.t()

Set the color palette for surfaces and heatmaps.

Named Palettes

  • :viridis - Perceptually uniform, colorblind-friendly
  • :magma - Dark to light, warm tones
  • :plasma - Blue to yellow through pink
  • :inferno - Dark to light, fire-like
  • :cividis - Colorblind-optimized blue-yellow
  • :turbo - Rainbow-like, high contrast

Example

GnuplotEx.surface(data) |> GnuplotEx.palette(:viridis)
GnuplotEx.surface(data) |> GnuplotEx.palette(["#440154", "#21918c", "#fde725"])

parallel(plot, data)

parallel(plot, data, opts)

@spec parallel(GnuplotEx.Plot.t(), map() | Enumerable.t(), keyword()) ::
  GnuplotEx.Plot.t()

Add a parallel coordinates series.

Parallel coordinates display multivariate data with each variable represented as a vertical axis. Lines connect values across all axes, making it easy to see patterns and relationships in high-dimensional data.

Data Formats

  • Single map: %{var1: value1, var2: value2, ...} (one line)
  • List of maps: [%{var1: v1, var2: v2}, ...] (multiple lines)
  • List of lists: [[v1, v2, ...], ...] (with :axes option)

Options

  • :label - Legend label for this series
  • :axes - List of axis names (required for list-of-lists format)
  • :color - Line color
  • :line_width - Line width (alias: :lw)

Examples

# From map data (auto-detect axes)
data = [
  %{price: 25000, mpg: 30, horsepower: 150, weight: 3000},
  %{price: 35000, mpg: 25, horsepower: 200, weight: 3500}
]
GnuplotEx.parallel(data)
|> GnuplotEx.to_svg("/tmp/parallel.svg")

# With styling
GnuplotEx.parallel(data, color: "#3daee9", lw: 2)

# Matrix format with explicit axes
matrix = [[25000, 30, 150], [35000, 25, 200]]
GnuplotEx.parallel(matrix, axes: ["Price", "MPG", "HP"])

# With plot builder
GnuplotEx.new()
|> GnuplotEx.title("Car Comparison")
|> GnuplotEx.parallel(data1, label: "Dataset A", color: "#E95420")
|> GnuplotEx.parallel(data2, label: "Dataset B", color: "#3daee9")

parametric_surface(func, opts)

parametric_surface(plot, func, opts)

@spec parametric_surface(GnuplotEx.Plot.t(), fun(), keyword()) :: GnuplotEx.Plot.t()

Add a parametric surface plot.

The function should take (u, v) parameters and return {x, y, z}.

Options

  • :label - Legend label
  • :u_range - U parameter range (required)
  • :v_range - V parameter range (required)
  • :samples - Grid resolution
  • :surface_style - :pm3d, :lines, or :hidden3d

Example

# Sphere
sphere = fn u, v ->
  {:math.cos(u) * :math.cos(v),
   :math.sin(u) * :math.cos(v),
   :math.sin(v)}
end

GnuplotEx.parametric_surface(sphere,
  u_range: {0, 2 * :math.pi()},
  v_range: {-:math.pi()/2, :math.pi()/2})

pie(plot, data)

pie(plot, data, opts)

Add a pie chart series.

Pie charts display proportional data as circular sectors. Each slice represents a portion of the whole based on its value relative to the sum.

Data Formats

  • List of numbers: [30, 25, 20, 15, 10]
  • List of {label, value} tuples: [{"A", 30}, {"B", 25}]
  • List of maps: [%{label: "A", value: 30}, %{label: "B", value: 25}]

Options

  • :labels - List of slice labels (auto-detected from maps/tuples)
  • :colors - List of colors or palette name (e.g., :viridis)
  • :explode - List of slice indices to offset outward (0-based)
  • :start_angle - Starting angle in degrees (0 = top, clockwise)

Examples

# Simple pie from values
[30, 25, 20, 15, 10]
|> GnuplotEx.pie()
|> GnuplotEx.to_svg("/tmp/pie.svg")

# With labels and colors
data = [
  %{label: "Category A", value: 30},
  %{label: "Category B", value: 25},
  %{label: "Category C", value: 20}
]
GnuplotEx.pie(data, colors: ["#E95420", "#3daee9", "#27ae60"])

# Exploded slice
GnuplotEx.pie(data, explode: [0])  # First slice exploded

# With plot builder
GnuplotEx.new()
|> GnuplotEx.title("Sales Distribution")
|> GnuplotEx.pie(data, colors: :viridis)

plot(commands)

@spec plot([command()]) :: {:ok, String.t()} | {:error, term()}

Execute gnuplot commands without datasets.

Example

GnuplotEx.plot([
  [:set, :terminal, :dumb],
  [:plot, 'sin(x)']
])

plot(commands, datasets)

@spec plot([command()], [dataset()]) :: {:ok, String.t()} | {:error, term()}

Execute gnuplot commands with datasets.

Each dataset corresponds to a "-" placeholder in the commands. Data is streamed to gnuplot's stdin for memory efficiency.

Parameters

  • commands - List of gnuplot commands as nested lists
  • datasets - List of datasets, each being a list of points

Returns

  • {:ok, command_string} - Success
  • {:error, :gnuplot_not_found} - gnuplot not in PATH
  • {:error, {:exit, code, output}} - gnuplot error
  • {:error, :timeout} - Execution timed out

Example

data = [[0, 0], [1, 1], [2, 4], [3, 9]]

GnuplotEx.plot([
  [:set, :terminal, :svg],
  [:set, :output, "/tmp/plot.svg"],
  [:set, :title, "Quadratic"],
  [:plot, "-", :with, :linespoints]
], [data])

plot(session_name, commands, datasets)

@spec plot(atom(), [command()], [dataset()]) :: {:ok, String.t()} | {:error, term()}
@spec plot([command()], [dataset()], [plot_option()]) ::
  {:ok, String.t() | GnuplotEx.Spec.t()} | {:error, term()}

Execute gnuplot commands with a third argument.

Named Session (atom, list, list)

# Start a session first
{:ok, _} = GnuplotEx.Session.start_link(name: :analysis)

# Plot to that session
GnuplotEx.plot(:analysis, commands, data)

With Options (list, list, keyword)

Options:

  • :dry - If true, returns the spec without executing (default: false)

    # Dry mode - returns spec without executing {:ok, spec} = GnuplotEx.plot(commands, data, dry: true) IO.inspect(spec)

plots(commands)

@spec plots([command()]) :: command()

Build a comma-separated plot list for multiple 2D datasets.

Example

GnuplotEx.plot([
  [:set, :terminal, :svg],
  GnuplotEx.plots([
    ["-", :with, :points],
    ["-", :with, :lines]
  ])
], [data1, data2])

This generates: plot "-" with points, "-" with lines

polygon3d(plot, data)

polygon3d(plot, data, opts)

@spec polygon3d(GnuplotEx.Plot.t(), Enumerable.t(), keyword()) :: GnuplotEx.Plot.t()

Add a 3D polygon mesh series.

3D polygons are filled closed shapes in 3D space, useful for rendering meshes and custom surfaces.

Data Formats

  • Single polygon: [[x1, y1, z1], [x2, y2, z2], [x3, y3, z3], ...]
  • Multiple polygons (mesh): [[[x1, y1, z1], ...], [[x2, y2, z2], ...]]

Options

  • :label - Legend label
  • :color - Fill color
  • :fill - Fill style (:solid, :transparent, :pattern, :empty)
  • :alpha - Fill transparency 0.0-1.0
  • :border_color - Border line color
  • :border_width - Border line width

Abbreviations

  • :c - color
  • :bc - border_color
  • :bw - border_width
  • :a - alpha

Examples

# 3D triangle
vertices = [[0, 0, 0], [1, 0, 0], [0.5, 1, 0.5]]
GnuplotEx.polygon3d(vertices, color: "#E95420")
|> GnuplotEx.to_svg("/tmp/polygon3d.svg")

# Mesh (multiple polygons)
mesh = [
  [[0, 0, 0], [1, 0, 0], [0.5, 1, 0.5]],
  [[1, 0, 0], [1, 1, 0], [0.5, 1, 0.5]]
]
GnuplotEx.polygon3d(mesh, fill: :transparent, alpha: 0.8)

polygon(plot, data)

polygon(plot, data, opts)

Add a 2D polygon series.

Polygons are filled closed shapes defined by vertices. Supports single polygons or multiple polygons rendered together.

Data Formats

  • Single polygon: [[x1, y1], [x2, y2], [x3, y3], ...]
  • Multiple polygons: [[[x1, y1], ...], [[x2, y2], ...]]

Options

  • :label - Legend label
  • :color - Fill color
  • :fill - Fill style (:solid, :transparent, :pattern, :empty)
  • :alpha - Fill transparency 0.0-1.0
  • :border_color - Border line color
  • :border_width - Border line width

Abbreviations

  • :c - color
  • :bc - border_color
  • :bw - border_width
  • :a - alpha

Examples

# Triangle
vertices = [[0, 0], [1, 0], [0.5, 1]]
GnuplotEx.polygon(vertices, color: "#3daee9")
|> GnuplotEx.to_svg("/tmp/triangle.svg")

# Multiple shapes
shapes = [
  [[0, 0], [1, 0], [1, 1], [0, 1]],
  [[2, 0], [3, 0], [2.5, 1]]
]
GnuplotEx.polygon(shapes, fill: :solid, bc: "#000")

# With plot builder
GnuplotEx.new()
|> GnuplotEx.title("Shapes")
|> GnuplotEx.polygon(vertices, color: "#E95420", bw: 2)

render(plot, format \\ :svg, opts \\ [])

@spec render(GnuplotEx.Plot.t(), atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Render a plot to a specific format.

Formats

  • :svg - SVG vector graphics (default)
  • :png - PNG raster image
  • :pdf - PDF document
  • :dumb - ASCII art

Options

  • :output - Output file path (required for file formats)
  • :size - {width, height} tuple
  • :on_progress - Progress callback fn(sent, total) -> any
  • :timeout - Override base timeout in milliseconds

Example

GnuplotEx.new()
|> GnuplotEx.scatter(data)
|> GnuplotEx.render(:svg, output: "/tmp/plot.svg")

# With progress monitoring for large datasets
GnuplotEx.render(plot, :png,
  output: "/tmp/large.png",
  on_progress: fn sent, total -> IO.puts("Progress: #{sent}/#{total}") end
)

render_async(plot, format \\ :svg, opts \\ [])

@spec render_async(GnuplotEx.Plot.t(), atom(), keyword()) :: Task.t()

Render plot asynchronously, returning a Task.

Example

task = GnuplotEx.render_async(plot, :svg)
# Do other work...
{:ok, svg} = Task.await(task)

render_many(plots, format \\ :svg, opts \\ [])

@spec render_many([GnuplotEx.Plot.t()], atom(), keyword()) :: [
  ok: String.t(),
  error: term()
]

Render multiple plots in parallel.

Example

plots = [plot1, plot2, plot3]
results = GnuplotEx.render_many(plots, :svg, max_concurrency: 4)

save_script(plot, path)

@spec save_script(GnuplotEx.Plot.t(), String.t()) :: :ok | {:error, term()}

Export plot as a reproducible gnuplot script file.

The generated script includes inline data and can be run with:

gnuplot script.gp

Example

GnuplotEx.new()
|> GnuplotEx.scatter(data, label: "Points")
|> GnuplotEx.title("My Plot")
|> GnuplotEx.save_script("/tmp/plot.gp")

scatter3d(plot, data)

scatter3d(plot, data, opts)

@spec scatter3d(GnuplotEx.Plot.t(), Enumerable.t(), keyword()) :: GnuplotEx.Plot.t()

Add a 3D scatter series.

Data should be a list of [x, y, z] points.

Options

  • :label - Legend label
  • :color - Point color
  • :point_type - Point shape (1-14)
  • :point_size - Point size multiplier

Example

points = for _ <- 1..100, do: [:rand.uniform(), :rand.uniform(), :rand.uniform()]
GnuplotEx.scatter3d(points, label: "Random")
|> GnuplotEx.to_svg("/tmp/scatter3d.svg")

scatter(plot, data)

scatter(plot, data, opts)

Add a scatter plot series.

Can be called with just data to start a new plot, or with an existing plot.

Options

  • :label - Legend label
  • :color - Point color (e.g., "#E95420")
  • :point_type - Point shape (1-14)
  • :point_size - Point size multiplier

Example

# Start new plot with data
data |> GnuplotEx.scatter(label: "Points") |> GnuplotEx.to_svg(path)

# Add to existing plot
GnuplotEx.new()
|> GnuplotEx.scatter(data1, label: "Series 1")
|> GnuplotEx.scatter(data2, label: "Series 2")

sessions()

@spec sessions() :: [atom()]

List all active named sessions.

Example

GnuplotEx.sessions()
# => [:analysis, :realtime]

size(plot, dimensions)

Set the plot size.

Example

plot |> GnuplotEx.size({800, 600})

spider(plot, data)

spider(plot, data, opts)

@spec spider(GnuplotEx.Plot.t(), map() | Enumerable.t(), keyword()) ::
  GnuplotEx.Plot.t()

Add a spider/radar chart series.

Spider charts display multivariate data on axes radiating from a center point. Useful for comparing multiple entities across several metrics.

Data Formats

  • Single map: %{axis1: value1, axis2: value2, ...}
  • List of maps: [%{name: "A", axis1: v1, ...}, ...]
  • List of lists: [[v1, v2, ...], ...] (with :axes option)

Options

  • :label - Legend label
  • :axes - List of axis names (required for list-of-lists data)
  • :filled - Fill the spider area (default: false)
  • :alpha - Fill transparency 0.0-1.0 (default: 0.3)
  • :color - Line/fill color

Examples

# Single entity
stats = %{speed: 8, power: 6, defense: 7, magic: 5}
GnuplotEx.spider(stats, label: "Warrior", filled: true)
|> GnuplotEx.to_svg("/tmp/spider.svg")

# Multiple entities comparison
data = [
  %{name: "Warrior", speed: 8, power: 6, defense: 7},
  %{name: "Mage", speed: 5, power: 9, defense: 4}
]
GnuplotEx.spider(data, filled: true)

# With plot builder
GnuplotEx.new()
|> GnuplotEx.title("Character Comparison")
|> GnuplotEx.spider(data1, label: "A", filled: true)
|> GnuplotEx.spider(data2, label: "B", filled: false)

splots(commands)

@spec splots([command()]) :: command()

Build a comma-separated splot list for multiple 3D datasets.

Example

GnuplotEx.plot([
  [:set, :terminal, :svg],
  GnuplotEx.splots([
    ["-", :with, :pm3d],
    ["-", :with, :lines]
  ])
], [surface1, surface2])

This generates: splot "-" with pm3d, "-" with lines

surface(plot, data_or_fn)

surface(plot, data_or_fn, opts)

@spec surface(GnuplotEx.Plot.t(), Enumerable.t() | fun(), keyword()) ::
  GnuplotEx.Plot.t()

Add a surface plot.

Data can be:

  • A list of [x, y, z] points
  • A function (x, y) -> z (requires x_range/y_range)

Options

  • :label - Legend label
  • :surface_style - :pm3d (default), :lines, or :hidden3d
  • :samples - Grid resolution

Example

# From data
data = for x <- 0..10, y <- 0..10, do: [x, y, x*x + y*y]
GnuplotEx.surface(data) |> GnuplotEx.to_svg("/tmp/surface.svg")

# From function
GnuplotEx.surface(fn x, y -> :math.sin(x) * :math.cos(y) end,
  x_range: -5..5, y_range: -5..5)

theme(plot, theme_value)

@spec theme(GnuplotEx.Plot.t(), atom() | map()) :: GnuplotEx.Plot.t()

Set the plot theme.

Presets

  • :default - Minimal theme with grid
  • :dark - Dark background theme
  • :publication - Publication-ready styling

Example

plot |> GnuplotEx.theme(:dark)

title(plot, title_text)

@spec title(GnuplotEx.Plot.t(), String.t()) :: GnuplotEx.Plot.t()

Set the plot title.

Example

plot |> GnuplotEx.title("My Plot")

to_ascii(plot, opts \\ [])

@spec to_ascii(
  GnuplotEx.Plot.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Render plot to ASCII art.

Returns the ASCII representation as a string in the result.

Example

{:ok, ascii} = plot |> GnuplotEx.to_ascii()
IO.puts(ascii)

to_png(plot, path, opts \\ [])

@spec to_png(GnuplotEx.Plot.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Render plot to PNG file.

Example

plot |> GnuplotEx.to_png("/tmp/plot.png")

to_spec(plot)

@spec to_spec(GnuplotEx.Plot.t()) :: GnuplotEx.Spec.t()

Convert a Plot to a Spec for inspection without execution.

Example

spec = plot |> GnuplotEx.to_spec()
IO.inspect(spec)

to_svg(plot, path, opts \\ [])

@spec to_svg(GnuplotEx.Plot.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Render plot to SVG file.

Example

plot |> GnuplotEx.to_svg("/tmp/plot.svg")

unset_nonlinear(plot, axis)

Remove a nonlinear transformation from an axis.

Returns the axis to linear scaling.

Example

plot
|> GnuplotEx.nonlinear(:x, :log10)
|> GnuplotEx.unset_nonlinear(:x)

version()

@spec version() :: {:ok, String.t()} | {:error, term()}

Get the installed gnuplot version.

Example

{:ok, "6.0.0"} = GnuplotEx.version()

version!()

@spec version!() :: {:ok, String.t()} | {:error, term()}

Check if gnuplot version meets the minimum requirement (6.0.0).

Example

{:ok, "6.0.0"} = GnuplotEx.version!()
{:error, {:version_too_old, "5.4.0", "6.0.0"}} = GnuplotEx.version!()

view_angle(plot, rotation, elevation)

@spec view_angle(GnuplotEx.Plot.t(), number(), number()) :: GnuplotEx.Plot.t()

Set the 3D view angle.

Controls the viewing angle for 3D plots using rotation and elevation.

  • rotation - Rotation around the Z-axis in degrees (0-360)
  • elevation - Elevation angle in degrees (0-90, where 90 is top-down)

Example

plot |> GnuplotEx.view_angle(60, 30)

x_label(plot, label)

@spec x_label(GnuplotEx.Plot.t(), String.t()) :: GnuplotEx.Plot.t()

Set the X-axis label.

Example

plot |> GnuplotEx.x_label("Time (s)")

x_range(plot, range)

@spec x_range(GnuplotEx.Plot.t(), Range.t() | {number(), number()}) ::
  GnuplotEx.Plot.t()

Set the X-axis range.

Example

plot |> GnuplotEx.x_range(0..100)
plot |> GnuplotEx.x_range({-10, 10})

y_label(plot, label)

@spec y_label(GnuplotEx.Plot.t(), String.t()) :: GnuplotEx.Plot.t()

Set the Y-axis label.

Example

plot |> GnuplotEx.y_label("Value")

y_range(plot, range)

@spec y_range(GnuplotEx.Plot.t(), Range.t() | {number(), number()}) ::
  GnuplotEx.Plot.t()

Set the Y-axis range.

Example

plot |> GnuplotEx.y_range(-1..1)

z_label(plot, label)

@spec z_label(GnuplotEx.Plot.t(), String.t()) :: GnuplotEx.Plot.t()

Set the Z-axis label (for 3D plots).

Example

plot |> GnuplotEx.z_label("Height (m)")

z_range(plot, range)

@spec z_range(GnuplotEx.Plot.t(), Range.t() | {number(), number()}) ::
  GnuplotEx.Plot.t()

Set the Z-axis range (for 3D plots).

Example

plot |> GnuplotEx.z_range(0..100)