Public API

This page lists exported symbols of CTBase.Plotting.

---

From CTBase.Plotting

CTBase.Plotting [Module]

CTBase.Plotting Module

Plotting

Generic, domain-free plotting engine for the Control Toolbox.

It manipulates a backend-agnostic intermediate representation (IR): a weighted tree (Leaf/HBox/VBox) of titled Axes carrying Series and Decorations. It knows nothing about states, controls, costates, trajectories or optimal control — the case layers (CTModels, CTFlows) build the IR and hand it to a backend via render.

The IR and all its transforms live here in src (no backend dependency); only the drawing lives in an extension (CTBasePlots for Plots.jl). See the design report in CTModels.jl/.reports/dev/plot_engine_ctbase_report.md.

Public API

• IR: Series, HLine, VLine, Axes, Leaf, HBox, VBox, Figure, leaves

• case-layer building blocks: Panel, Stacked, Paired, Grid

• backend contract: AbstractPlottingBackend, PlotsBackend, render, render!

AbstractLayoutNode [Abstract Type]

CTBase.Plotting.AbstractLayoutNode Type

abstract type AbstractLayoutNode

Supertype of the weighted layout tree: Leaf (a cell), HBox (columns side by side) and VBox (rows stacked). This is the backend-agnostic geometry a renderer turns into subplots.

AbstractPlottingBackend [Abstract Type]

CTBase.Plotting.AbstractPlottingBackend Type

abstract type AbstractPlottingBackend

Supertype of rendering backends. A backend adds methods to render / render! on its concrete type from a weak-dependency extension; the fallback here errors when no backend is loaded.

Axes [Struct]

CTBase.Plotting.Axes Type

struct Axes

One drawable cell: a single axis system holding a list of Series, optional Decorations drawn on top, and its labels/limits. Domain-free — the case layer decides what a cell means.

ylims is one of:

• nothing — leave the backend default,

• (lo, hi) — fixed limits,

• :auto — backend auto-scaling,

• :auto_guarded — auto, but widen a (near-)constant series so the axis does not collapse (resolved from the series data, either at lowering or by the backend).

Fields

• title::String

• xlabel::String

• ylabel::String

• series::Vector{CTBase.Plotting.Series}

• decorations::Vector{Union{CTBase.Plotting.HLine, CTBase.Plotting.VLine}}

• legend::Bool

• ylims::Union{Nothing, Tuple{Float64, Float64}, Symbol}

Figure [Struct]

CTBase.Plotting.Figure Type

struct Figure

A complete figure: a layout root plus optional overall size and title. size === nothing defers to the engine size heuristic (default_size); title === nothing draws no overall title.

Fields

• root::CTBase.Plotting.AbstractLayoutNode

• size::Union{Nothing, Tuple{Int64, Int64}}

• title::Union{Nothing, String}

Grid [Function]

CTBase.Plotting.Grid Function

Grid(
    cells::AbstractMatrix{<:CTBase.Plotting.AbstractLayoutNode};
    row_weights,
    col_weights
) -> CTBase.Plotting.VBox

Arrange a rectangular matrix of nodes into a grid: cells[i, j] is row i, column j (e.g. the :group n×m layout). Each row becomes an HBox and the rows are stacked in a VBox. Row and column weights default to equal; pass row_weights / col_weights to override.

HBox [Struct]

CTBase.Plotting.HBox Type

struct HBox <: CTBase.Plotting.AbstractLayoutNode

Horizontal juxtaposition of child nodes (columns placed side by side). weights are relative column widths, one per child (strictly positive). See also VBox.

Fields

• children::Vector{CTBase.Plotting.AbstractLayoutNode}

• weights::Vector{Float64}

HLine [Struct]

CTBase.Plotting.HLine Type

struct HLine

A horizontal reference line at height value (e.g. a box bound). style follows the same neutral vocabulary as Series.

Fields

• value::Float64

• style::NamedTuple

Leaf [Struct]

CTBase.Plotting.Leaf Type

struct Leaf <: CTBase.Plotting.AbstractLayoutNode

A leaf of the layout tree: a single drawable cell wrapping one Axes.

Paired [Function]

CTBase.Plotting.Paired Function

Paired(
    children::AbstractVector{<:CTBase.Plotting.AbstractLayoutNode};
    weights
) -> CTBase.Plotting.HBox

Place children side by side into an HBox (e.g. state | costate). With weights=:auto each child's weight is its number of columns (grid_shape(child)[2]), so equal-width columns stay equal; pass an explicit weight vector to override. A two-argument form Paired(left, right) is provided for the common pair.

Panel [Struct]

CTBase.Plotting.Panel Type

struct Panel

A titled group of components sharing one time grid — the case layer's convenient input unit (e.g. all state components). It is not part of the rendered IR: the lower step turns a Panel into Leaf/Axes nodes.

Each panel carries its own time grid x (so different groups may live on different grids) and, optionally, a per-component styles vector (finer than the single shared style). data is (n_times, n_components).

Fields

• x::Vector{Float64}

• title::String

• labels::Vector{String}

• data::Matrix{Float64}

• style::NamedTuple

• styles::Vector{NamedTuple}

PlotsBackend [Struct]

CTBase.Plotting.PlotsBackend Type

struct PlotsBackend <: CTBase.Plotting.AbstractPlottingBackend

The Plots.jl backend. The type lives here in src; its render/render! methods live in the CTBasePlots extension, loaded automatically once Plots is available.

Series [Struct]

CTBase.Plotting.Series Type

struct Series

One plotted curve: a set of (x, y) points. Used both for time series (x a time grid) and for phase plots (x, y two state components). An empty label draws no legend entry.

style uses the neutral, backend-agnostic vocabulary — color, linewidth, linestyle, alpha, seriestype (:path, :steppost, :scatter), z_order (:back/:front) — plus backend_kwargs::NamedTuple as an escape hatch for backend-specific attributes (decision D2).

Fields

• x::Vector{Float64}

• y::Vector{Float64}

• label::String

• style::NamedTuple

Stacked [Function]

CTBase.Plotting.Stacked Function

Stacked(
    children::AbstractVector{<:CTBase.Plotting.AbstractLayoutNode};
    weights
) -> CTBase.Plotting.VBox

Stack children vertically into a VBox. With weights=:auto (default, decision D4) each child's weight is its number of rows (grid_shape(child)[1]), so stacking blocks of different heights keeps every cell the same height — including when a child is itself a paired block; pass an explicit weight vector to override.

VBox [Struct]

CTBase.Plotting.VBox Type

struct VBox <: CTBase.Plotting.AbstractLayoutNode

Vertical stacking of child nodes (rows one under another). weights are relative row heights, one per child (strictly positive). See also HBox.

Fields

• children::Vector{CTBase.Plotting.AbstractLayoutNode}

• weights::Vector{Float64}

VLine [Struct]

CTBase.Plotting.VLine Type

struct VLine

A vertical reference line at abscissa value (e.g. initial/final time). style follows the same neutral vocabulary as Series.

Fields

• value::Float64

• style::NamedTuple

leaves [Function]

CTBase.Plotting.leaves Function

leaves(
    leaf::CTBase.Plotting.Leaf
) -> Vector{CTBase.Plotting.Leaf}

Return the Leafs of a node in deterministic order: depth-first, children visited in stored order. This order is the contract used to target existing cells by index when overlaying with render!.

render [Function]

CTBase.Plotting.render Function

render(
    ::CTBase.Plotting.AbstractPlottingBackend,
    ::CTBase.Plotting.Figure;
    kwargs...
) -> Any

Render fig into a backend figure. Fallback (no backend loaded) errors with an ExtensionError; a backend extension overrides this on its concrete type.

render(
    ::CTBase.Plotting.PlotsBackend,
    fig::CTBase.Plotting.Figure;
    kwargs...
) -> Any

Render fig into a new Plots.Plot (Plots backend). Series attributes among kwargs (color, linewidth, label, …) are forwarded to every series; the rest (legend, grid, …) are applied to every cell.

render! [Function]

CTBase.Plotting.render! Function

render!(
    ::CTBase.Plotting.AbstractPlottingBackend,
    target,
    ::CTBase.Plotting.Figure;
    kwargs...
) -> Any

Overlay fig onto an existing backend target, targeting existing cells by the deterministic leaf order (see leaves).

render!(
    ::CTBase.Plotting.PlotsBackend,
    target,
    fig::CTBase.Plotting.Figure;
    kwargs...
) -> Any

Overlay fig onto an existing Plots plot target, targeting existing subplots by the deterministic leaf order. Series/decorations are added; axes untouched.