Reference

QuickCharts provides lightweight chart-oriented plotting primitives backed by Cairo, including single charts, chart grids, annotations, legends, colors, and math-aware text rendering.

cm

Conversion factor from centimeters to typographic points.

Use it when specifying figure sizes, e.g. size=(8cm, 6cm).

Chart(; 
    size=(220,150), font="serif", font_size=7.0,
    xlimits, ylimits, aspect_ratio=:auto,
    nxticks=7, nyticks=6,
    title="", background=nothing,
    xlabel="`x`", ylabel="`y`",
    xticks=Float64[], yticks=Float64[],
    xtick_labels=String[], ytick_labels=String[],
    legend=:top_right, legend_font_size=0, legend_background=nothing)

Construct a 2D chart figure with axes, legend, and optional tick customization.

Arguments

• size::Tuple{<:Real,<:Real}: width × height in points. Use cm as a convenience helper, e.g. size=(8cm, 6cm).
• font::AbstractString: font family for axes and legend.
• font_size::Real: base font size.
• xlimits::Vector{<:Real}, ylimits::Vector{<:Real}: axis limits [min,max]; use empty vectors for auto scaling.
• aspect_ratio::Symbol: :auto or :equal.
• nxticks::Int, nyticks::Int: target number of tick intervals on each axis.
• title::AbstractString: chart title, centered above the plot area.
• background::Union{Nothing,Symbol,Color,Tuple}: full-figure background fill; nothing leaves the figure unfilled.
• xlabel::AbstractString, ylabel::AbstractString: axis labels.
• xticks::Vector{<:Real}, yticks::Vector{<:Real}: explicit tick positions; empty vectors enable auto ticks.
• xtick_labels::Vector{<:AbstractString}, ytick_labels::Vector{<:AbstractString}: custom tick labels; if provided, lengths must match the corresponding tick arrays.
• legend::Symbol: legend location (e.g., :top_right, :top_left, :bottom_left, :outer_right).
• legend_font_size::Real: legend font size; 0 uses font_size.
• legend_background::Union{Nothing,Symbol,Color,Tuple}: legend box fill color; if unset it defaults to white standalone and follows the grid background when drawn inside a ChartGrid.

Notes

• Use add_series to append data series to the chart.
• Use add_annotation to add plot-relative overlay annotations.
• Prefer backticks for inline math in plot text, e.g. $`sin(x)`$. Dollar delimiters are also accepted, but must be escaped in Julia strings, e.g. "$sin(x)$".
• The legend is drawn after annotations.
• background=nothing leaves the chart background unfilled in vector outputs and uses a white page background in PNG.
• Use save to export the chart to a file.

Returns

• A Chart object.

Example

using QuickCharts: Chart, cm

ch = Chart(size=(8cm, 6cm),
           title="Response History",
           xlabel="Time [s]",
           ylabel="Displacement [mm]",
           xlimits=[0.0,10.0],
           ylimits=[-5.0,5.0],
           legend=:bottom_right)

ChartGrid(; title="", size=(420,320), font="serif", font_size=10.0,
            background=nothing,
            column_headers=String[], row_headers=String[],
            outerpad=0.0, hgap=8.0, vgap=8.0)

Create a composed figure that arranges child figures in a uniform grid.

Keywords

• title::AbstractString: grid title centered above the cells.
• size::Tuple{<:Real,<:Real}: figure size in points. Use cm as a convenience helper, e.g. size=(16cm, 10cm).
• font::AbstractString: font family used for the grid title and headers.
• font_size::Real: title and header font size.
• background: full-figure background fill; nothing leaves the figure unfilled.
• column_headers::Vector{<:AbstractString}: optional headers centered above columns.
• row_headers::Vector{<:AbstractString}: optional headers drawn on the left, rotated like y-axis labels.
• outerpad::Real: outer figure margin.
• hgap::Real, vgap::Real: horizontal and vertical gaps between cells.

Notes

• Add child figures with add_chart.
• The grid can contain any Figure, including Chart or another ChartGrid.
• Prefer backticks for inline math in titles and headers, e.g. $`sigma_n`$. Dollar delimiters are also accepted, but must be escaped in Julia strings, e.g. "$sigma_n$".
• background=nothing leaves the grid background unfilled in vector outputs and uses a white page background in PNG.
• Child chart backgrounds are ignored when charts are rendered inside a grid.
• Headers and titles use the same math-aware text rendering as the rest of the plotting API.

DataSeries(kind::Symbol, X::AbstractArray, Y::AbstractArray; kwargs...)
DataSeries(X::AbstractArray, Y::AbstractArray; kwargs...)

Store the data and styling for a chart series.

kind must be :line, :scatter, or :bar; the two-argument constructor uses :line. X and Y must have equal length. Most users should create series with add_series, add_line, add_scatter, or add_bar, because those helpers also attach the series to a chart and resolve color=:auto against the chart palette.

Keyword options

• line_style: one of :none, :solid, :dot, :dash, or :dashdot.
• dash: custom dash pattern; when nonempty, line_style becomes :dash.
• color: series color, or :auto for later chart palette assignment.
• line_width: positive stroke width.
• mark: one of the supported marker symbols.
• mark_size: positive marker size.
• mark_color, mark_stroke_color: marker fill and edge colors, or :auto.
• label: legend label; an empty label keeps the series out of the legend.
• tag, tag_anchor, tag_pos, tag_orientation, tag_padding, tag_font_size: on-series tag text and placement.
• bar_width, bar_base: bar-series width and baseline.
• order: nonnegative draw order; 0 is assigned by add_series.

Legend(; location=:top_right, font="serif", font_size=7.0,
         background=nothing, ncols=1)

Configure a chart legend.

location controls where labeled series are drawn relative to the plot area. Supported values are :right, :left, :top, :bottom, the corner variants :top_right, :top_left, :bottom_right, :bottom_left, and the outer variants :outer_right, :outer_left, :outer_top, :outer_top_left, :outer_top_right, :outer_bottom, :outer_bottom_right, and :outer_bottom_left.

background accepts the same color inputs as Color, or nothing to use the render background when available and white otherwise.

Annotation(text::AbstractString, x::Real, y::Real; kwargs...)
Annotation(text::AbstractString, pos; kwargs...)

Create a plot-area annotation.

x and y are normalized coordinates in the chart canvas, where (0, 0) is the lower-left of the plot area and (1, 1) is the upper-right. Set target=[xdata, ydata] to draw a connector from the annotation to a point in data coordinates.

Keyword options

• anchor: :auto, :left, :right, :top, or :bottom.
• target: optional two-element data-coordinate target for a connector.
• line_width: positive connector stroke width.
• font: annotation font family.
• font_size: annotation font size in points. nothing uses 0.8 * chart.xaxis.font_size.
• color: named annotation text and connector color.

Color(r::Float64, g::Float64, b::Float64[, a::Float64=1.0])
Color(r::Int, g::Int, b::Int[, a::Float64=1.0])
Color((r, g, b[, a]))
Color(name::Symbol)
Color(color::Color)

Represent an RGBA color with channel values stored in [0, 1].

Float constructors interpret r, g, b, and a as normalized channels. Integer constructors interpret RGB channels as 8-bit values in 0:255 and the alpha channel as a normalized value. Tuple inputs may contain either 3 or 4 channels and are dispatched to the numeric constructors. Symbol inputs use the built-in named color table, including browser-style names such as :royal_blue and QuickCharts palette names such as :c1.

Out-of-range channel values are clamped.

Colormap(stops, colors)
Colormap(name::Symbol; limits=Float64[], rev=false)

Represent a scalar-to-color lookup table.

stops are scalar positions and colors may be named color symbols, RGB/RGBA tuples, Color values, or a mixture of those forms. Colors are normalized and stored internally as RGB tuples. A Colormap is callable: cmap(x) returns an interpolated RGB tuple, clamped to the first or last color outside the stop range.

The named constructor loads one of QuickCharts' built-in maps. limits=[lo, hi] clips the stop range before use, and rev=true reverses the map.

VideoBuilder(;
    framerate=12,
    codec=nothing,
    cleanup=true,
    tempdir=nothing,
    freeze_scale=false,
    bounds_factor=1.0)

Accumulate Figure frames and encode them to a video with save.

Arguments

• framerate::Real: output frame rate in frames per second.
• codec::Union{Nothing,AbstractString}: video codec passed to ffmpeg; nothing uses a format-dependent default.
• cleanup::Bool: remove temporary PNG frames after successful encoding.
• tempdir::Union{Nothing,AbstractString}: parent directory for the temporary frame directory; nothing uses the system temporary location.
• freeze_scale::Bool: reuse the scaling state from frame 1 for all frames.
• bounds_factor::Real: expand frozen bounds by this factor when freeze_scale=true.

Notes

• VideoBuilder stores figure references exactly as they are passed to add_frame. If the same mutable figure is modified after being added, the saved video will reflect the later state.
• All frames must render to the same pixel size. save(video, ...) throws a QuickChartsException when frame sizes differ.
• Supported output formats are currently .mp4 and .avi.

Returns

• A VideoBuilder object.

Example

using QuickCharts: VideoBuilder

video = VideoBuilder(framerate=12, freeze_scale=true, bounds_factor=1.05)

Axis(; kwargs...)

Creates an Axis component.

Parameters

• direction::Symbol : Axis direction (:horizontal or :vertical, default :horizontal).
• location::Symbol : Axis location (:none, :left, :right, :top, :bottom, default :none). If :none, it becomes :bottom for horizontal and :left for vertical.
• limits::Vector{Float64} : Axis limits [min, max]. Use Float64[] for auto limits.
• label::AbstractString : Axis label text (default "").
• font::AbstractString : Font family for label and ticks (default "serif").
• font_size::Float64 : Font size (> 0, default 7.0).
• ticks::AbstractArray : Explicit tick positions (default Float64[]).
• tick_labels::AbstractArray : Labels for ticks (default String[]). Must match length(ticks) when provided.
• tick_length::Float64 : Tick mark length input (default 0.4*font_size).
• nticks::Int : Hint for the number of tick intervals (default 6).

Notes

• direction and location control orientation and side.
• If tick_labels are given, their count must equal length(ticks).
• nticks is a hint. Explicit ticks take precedence.

add_series(chart::Chart, kind::Symbol, X::AbstractArray, Y::AbstractArray; kwargs...)
add_series(chart::Chart, X::AbstractArray, Y::AbstractArray; kwargs...)

Append a DataSeries to chart. The second version uses kind = :line.

Arguments

• chart::Chart : Target chart (mutated).
• kind::Symbol : Plot type: :line, :scatter, :bar.
• X, Y::AbstractArray : Data vectors.

Keyword options

• line_style::Symbol = :solid : Line style (e.g. :solid, :dash, ...).
• dash::Vector{Float64} = Float64[] : Custom dash pattern. If nonempty, overrides line_style.
• color::Union{Symbol,Color,Tuple} = :auto : Line/marker color. :auto selects from the chart palette cyclically.
• line_width::Float64 = 0.5 : Line width (> 0).
• mark::Symbol = :none : Mark shape.
• mark_size::Float64 = 2.5 : Mark size (> 0).
• mark_color::Union{Symbol,Color,Tuple} = :white : Mark fill color.
• mark_stroke_color::Union{Symbol,Color,Tuple} = :auto : Mark edge color (:auto follows color).
• label::AbstractString = "" : Legend label.
• tag::AbstractString = "" : On-curve annotation text.
• tag_anchor::Symbol = :top : Anchor side of the tag (:top, :top_right, :right, :bottom_right, :bottom, :bottom_left, :left, :top_left).
• tag_pos::Float64 = 0.5 : Position along the curve in [0,1].
• tag_orientation::Symbol = :horizontal : Tag orientation (:horizontal, :vertical, :parallel).
• tag_padding::Union{Nothing,Real} = nothing : Padding between the curve and tag in points. nothing uses the default based on font size.
• tag_font_size::Union{Nothing,Real} = nothing : Tag font size in points. nothing uses 0.8 * chart.xaxis.font_size.
• bar_width::Float64 = 0.0 : Bar width in x-data units (0 enables auto width).
• bar_base::Float64 = 0.0 : Bar baseline in y-data units.
• order::Int = 0 : Z-order. If 0, an incremental order is assigned.

Returns

• The series object.

Examples

ch = Chart(size=(300,200), xlabel="Time [s]", ylabel="Displacement [mm]",
           xlimits=[0.0,10.0], ylimits=[-5.0,5.0], legend=:bottom_right)

add_line(ch, 0:0.1:10, sin.(0:0.1:10); label="sin")

add_line(chart::Chart, X::AbstractArray, Y::AbstractArray; kwargs...)

Add a line series to chart.

Arguments

• chart::Chart: Target chart (mutated).
• X, Y::AbstractArray: Data vectors.
• kwargs...: Keyword arguments controlling series appearance and metadata.

Keyword options

• line_style::Symbol = :solid: Line style (e.g. :solid, :dash, ...).
• dash::Vector{Float64} = Float64[]: Custom dash pattern. If nonempty, overrides line_style.
• color::Union{Symbol,Color,Tuple} = :auto: Line/marker color. :auto selects from the chart palette cyclically.
• line_width::Float64 = 0.5: Line width (> 0).
• mark::Symbol = :none: Mark shape.
• mark_size::Float64 = 2.5: Mark size (> 0).
• mark_color::Union{Symbol,Color,Tuple} = :white: Mark fill color.
• mark_stroke_color::Union{Symbol,Color,Tuple} = :auto: Mark edge color (:auto follows color).
• label::AbstractString = "": Legend label.
• tag::AbstractString = "": On-curve annotation text.
• tag_anchor::Symbol = :top: Anchor side of the tag (:top, :top_right, :right, :bottom_right, :bottom, :bottom_left, :left, :top_left).
• tag_pos::Float64 = 0.5: Position along the curve in [0,1].
• tag_orientation::Symbol = :horizontal: Tag orientation (:horizontal, :vertical, :parallel).
• tag_padding::Union{Nothing,Real} = nothing: Padding between the curve and tag in points. nothing uses the default based on font size.
• tag_font_size::Union{Nothing,Real} = nothing: Tag font size in points. nothing uses 0.8 * chart.xaxis.font_size.
• bar_width::Float64 = 0.0: Bar width in x-data units (0 enables auto width).
• bar_base::Float64 = 0.0: Bar baseline in y-data units.
• order::Int = 0: Z-order. If 0, an incremental order is assigned.

Returns

• The created series object.

add_scatter(chart::Chart, X::AbstractArray, Y::AbstractArray; kwargs...)

Add a scatter series to chart.

This is a convenience wrapper around add_series with line_style=:none and mark=:circle unless those keywords are supplied.

Arguments

• chart::Chart: Target chart (mutated).
• X, Y::AbstractArray: Data vectors.
• kwargs...: Keyword arguments accepted by add_line; explicit values override the defaults above.

Returns

• The created series object.

add_bar(chart::Chart, X::AbstractArray, Y::AbstractArray; kwargs...)

Add a bar series to chart.

This is a convenience wrapper around add_series with line_style=:none and mark=:none unless those keywords are supplied.

Arguments

• chart::Chart: Target chart (mutated).
• X, Y::AbstractArray: Data vectors.
• kwargs...: Keyword arguments accepted by add_line; explicit values override the defaults above.

Returns

• The created series object.

add_annotation(chart::Chart, annotation::Annotation)
add_annotation(chart::Chart, text::AbstractString, pos; kwargs...)

Append an annotation to chart and return it.

Annotations are drawn over the plot canvas when the chart is saved or otherwise rendered.

add_chart(grid::ChartGrid, child::Figure, pos::Tuple{Int,Int})

Insert child into grid at position (row, col).

Arguments

• grid::ChartGrid: target grid.
• child::Figure: child figure to place in the grid.
• pos::Tuple{Int,Int}: one-based (row, col) cell coordinates.

Notes

• Grid dimensions grow automatically to accommodate the largest inserted row/column.
• Inserting into an occupied cell throws an error.

add_frame(video::VideoBuilder, figure::Figure)

Append one frame to video.

render(figure::Figure; format=:svg, scale=1.5)
render(io::IO, figure::Figure; format=:svg, scale=1.5)

Render figure as SVG without saving a file.

The one-argument form returns an SVG String. The IO form writes SVG bytes to io and returns nothing. render is intended for rich display frontends such as VS Code and notebooks; use save for persistent files. Figures with no explicit background are rendered on white for display readability.

scale enlarges or shrinks the displayed SVG viewport without changing the figure's internal layout or the dimensions used by save.

save(figure::Figure, files::String...)

Configure and render figure to one or more output files.

Supported extensions are .pdf, .png, .svg, and .ps. Missing output directories are created automatically. PNG output is rasterized at a higher internal scale and uses a white background when the figure background is nothing; vector outputs leave a nothing background transparent/unfilled.

save(video::VideoBuilder, filename::AbstractString)

Encode the frames accumulated in video and write them to filename.

Supported output formats are .mp4 and .avi. The target directory is created automatically when needed. All frames must render to the same pixel size or save throws a QuickChartsException.

gray(x::Real)

Create an opaque grayscale Color with red, green, and blue channels all set to x. Values are clamped by the Color constructor.

lighten(c::Color, ratio::Float64)
lighten(c::Symbol, ratio::Float64)

Return a lighter copy of c by increasing its HSL lightness.

ratio must be in [0, 1]; 0 returns the original color and 1 returns white with the original alpha channel.

darken(c::Color, ratio::Float64)
darken(c::Symbol, ratio::Float64)

Return a darker copy of c by decreasing its HSL lightness.

ratio must be in [0, 1]; 0 returns the original color and 1 returns black with the original alpha channel.