Skip to content

TauPlot

Inherits: PanelContainer

Root node for creating and displaying plots.

Description

TauPlot is the root node for creating and displaying plots. Add it to the scene, then call a plot-type method to build and display a plot.

Before a plot is created, all provided inputs are validated. This helps catch misconfiguration early and report it through user-friendly warnings or errors.

Once created, a plot remains live. It listens to the dataset and refreshes automatically when the data changes. Configuration objects can also be modified at runtime, but require queue_refresh() or refresh_now() to apply. A TauStyle resource is the exception, and applies on assignment. Refreshes are incremental and avoid rebuilding the whole plot when possible.

All plot types share the same high-level container behavior and optional interaction systems:

  • a legend, enabled by default, whose visibility is controlled through legend_enabled and whose placement, flow direction, and appearance are controlled through legend_config
  • a hover inspection system, enabled by default, which can provide tooltips, highlighting, and sample interaction signals

XY plots

plot_xy() builds an XY plot from three objects:

The Dataset stores the actual samples. The TauXYConfig defines how the plot is laid out. The TauXYSeriesBinding objects connect both by specifying where and how each dataset series should be rendered.

An XY plot is organized around one shared X axis. This axis spans the whole plot and is configured through TauXYConfig.x_axis_id. Its position determines how panes are arranged:

  • when the X axis is on the top or bottom edge, panes are stacked vertically
  • when the X axis is on the left or right edge, panes are stacked horizontally

A plot may contain one or more panes. Most XY plots need only one pane. Several panes keep apart series that should not share a Y scale, such as a price series above a volume series.

Each pane contains one or more overlays, which are the visual layers that render the data, such as bars, lines, or scatter points. A pane also manages its own Y axes independently from the other panes.

Each pane can expose up to two Y axes, placed on the two edges orthogonal to the X axis. For example, if the X axis is on the bottom, the pane may use a left Y axis, a right Y axis, or both. Series with very different value ranges then share a pane without sharing a scale.

A series can be bound once or multiple times depending on the intended visualization. See TauXYSeriesBinding for the supported binding rules.

By default, domains and ticks are computed automatically. Each axis scans the data, applies configurable padding, and selects readable tick positions that fit without overlap. When automatic bounds are not wanted, TauAxisConfig.range_override_enabled forces a fixed range.

After plot_xy() succeeds, the plot listens to the dataset and refreshes automatically whenever the data changes. Mutating a configuration property afterwards requires queue_refresh(), a style property does not.

Hover inspection

When hover_enabled is true, the plot can detect hovered samples, show tooltips, and emit interaction signals.

Use hover_config to customize the built-in behavior, or disable the built-in tooltip and drive a custom UI from:

Quick usage

  1. Add a TauPlot node to the scene.
  2. Build a Dataset.
  3. Build a TauXYConfig.
  4. Create one TauXYSeriesBinding per plotted series.
  5. Call plot_xy().

Example

var dataset := TauPlot.Dataset.make_shared_x_categorical(
    PackedStringArray(["Revenue", "Costs"]),
    PackedStringArray(["Q1", "Q2", "Q3", "Q4"]),
    [
        PackedFloat64Array([120.0, 135.0, 148.0, 160.0]),
        PackedFloat64Array([90.0, 95.0, 100.0, 108.0]),
    ]
)

var x_axis := TauAxisConfig.new()
x_axis.type = TauAxisConfig.Type.CATEGORICAL

var y_axis := TauAxisConfig.new()
y_axis.title = "EUR"

var bar_overlay_config := TauBarConfig.new()

var pane := TauPaneConfig.new()
pane.y_left_axis = y_axis
pane.overlays = [bar_overlay_config]

var config := TauXYConfig.new()
config.x_axis = x_axis
config.panes = [pane]

var b0 := TauXYSeriesBinding.new()
b0.series_id = dataset.get_series_id_by_index(0)
b0.pane_index = 0
b0.overlay_type = TauXYSeriesBinding.PaneOverlayType.BAR
b0.y_axis_id = TauPlot.AxisId.LEFT

var b1 := TauXYSeriesBinding.new()
b1.series_id = dataset.get_series_id_by_index(1)
b1.pane_index = 0
b1.overlay_type = TauXYSeriesBinding.PaneOverlayType.BAR
b1.y_axis_id = TauPlot.AxisId.LEFT

var bindings: Array[TauXYSeriesBinding] = [b0, b1]

$MyPlot.title = "Quick Start Example"
$MyPlot.plot_xy(dataset, config, bindings)

Common workflows

Update the data
Mutate the Dataset. The plot refreshes automatically when the dataset emits changed.

Change plot configuration at runtime
Mutate a configuration property on the objects passed to plot_xy(), then call queue_refresh().

Change the appearance at runtime
Assign a property on a TauStyle resource. The plot redraws on its own.

Replace the current plot
Call plot_xy() again. The current plot is cleared automatically before the new one is built.

Reset the plot
Call reset().

Notes

  1. plot_xy() replaces the active plot. Calling it while a plot is already displayed tears down the current plot before building the new one. The previous dataset is disconnected automatically.

  2. Validation errors abort without modifying the current plot. If validation finds errors, plot_xy() logs them and returns, leaving the existing plot in place. Validation warnings are logged but do not abort.

TauPlot Namespace

TauPlot is registered as a global class, so it can be referenced directly anywhere in GDScript.

Most supporting types in the addon are intentionally not registered as global classes to avoid cluttering the global class namespace. Instead, they are exposed as constants on TauPlot. This makes the most common TauPlot types available from a single access point without requiring separate preload() calls.

Reference them as TauPlot.ClassName, for example TauPlot.Dataset.new() or TauPlot.ColorBuffer.new().

The types listed below are available through this namespace.

The enums under Enums are exposed on the same namespace: AxisId, PaneOverlayType, StackedNormalization, and StackedNegativePolicy.

Enums

AxisId

Identifies an axis by the edge position it occupies on the plot.

Value Meaning
BOTTOM The bottom edge position.
TOP The top edge position.
LEFT The left edge position.
RIGHT The right edge position.

PaneOverlayType

Identifies the visual layer type used to render series data inside a pane.

Value Meaning
BAR Bar overlay. Renders each sample as a bar originating from zero.
SCATTER Scatter overlay. Renders each sample as a marker at its data position.
LINE Line overlay. Renders each series as one curve through its sample positions, with an optional area fill.

StackedNormalization

Sets what each stack of a stacking overlay is scaled to.

Two stacking overlays drawing against the same Y axis of the same pane must declare the same value, see TauBarConfig note 1.

Value Meaning
NONE Stacks the raw values. The top of each stack is their sum.
FRACTION Scales each stack to 1.0. Each series carries its share of the stack.
PERCENT Scales each stack to 100.0. The same share expressed as a percentage.

StackedNegativePolicy

Sets how a negative value enters a stack.

Two stacking overlays drawing against the same Y axis of the same pane must declare the same value, see TauBarConfig note 1.

Value Meaning
DIVERGING Positive values stack upward from zero and negative values stack downward from zero. Each X position carries two independent cumulatives.
SIGNED_SUM Negative values enter the cumulative signed, so a negative sample dips the stack below the layer under it. A stacking BAR overlay cannot draw that dip without overlapping rectangles, and plot_xy() reports a validation error when one declares it.
SKIP_NEGATIVES Negative values are dropped from the cumulative. The sample stacks as if its value were zero.

Signals

sample_hovered()

signal sample_hovered(hits: Array[SampleHit])

Emitted when the mouse moves over one or more samples. hits contains one SampleHit per detected sample, and its first entry is the sample the cursor is on, or the closest sample when the cursor is on none. In NEAREST mode the array contains one entry. In X_ALIGNED mode it may contain one entry per series, and overlays that do not use the same X values report at different X positions. For PER_SERIES_X datasets, an overlay only includes the series that have a data point at the X position it reports, so the array often contains a single entry. Requires hover_enabled to be true.

sample_hover_exited()

signal sample_hover_exited()

Emitted when the mouse leaves all sample hit zones. Requires hover_enabled to be true.

sample_clicked()

signal sample_clicked(hits: Array[SampleHit])

Emitted on a mouse click over one or more samples. hits follows the same content rules as sample_hovered. Requires hover_enabled to be true.

sample_click_dismissed()

signal sample_click_dismissed()

Emitted when a pinned tooltip is dismissed by clicking on empty space or by pressing Escape. Requires hover_enabled to be true.

Properties

title

title: String

Sets the title displayed above the plot. Supports BBCode. Defaults to "", which hides the title. The label updates on assignment and the plot area is re-laid out on the next frame. Safe to set after plot_xy().

hover_enabled

hover_enabled: bool

Master switch for the hover inspection system. When false, no hit testing runs, no hover signals fire, and no tooltip, crosshair, or highlight renders. When true, the system activates using the settings in hover_config. Defaults to true. Safe to set after plot_xy().

hover_config

hover_config: TauHoverConfig

Configuration for the hover inspection system. Controls hover mode, tooltip, crosshair, highlight, and formatting callbacks. If null, built-in defaults apply for all settings. Defaults to null. Safe to set after plot_xy().

legend_enabled

legend_enabled: bool

Controls legend visibility. When true, the legend renders using the settings in legend_config. When false, the legend is hidden. Defaults to true. The legend updates on assignment and the plot area is re-laid out on the next frame. Safe to set after plot_xy().

legend_config

legend_config: TauLegendConfig

Configuration for the legend system. Controls position, flow direction, and visual style. If null, built-in defaults apply for all settings. Defaults to null. The legend updates on assignment and the plot area is re-laid out on the next frame. Safe to set after plot_xy().

Methods

Plot lifecycle

plot_xy()

plot_xy(p_dataset: Dataset, p_xy_config: TauXYConfig, p_series_bindings: Array[TauXYSeriesBinding]) -> void

Builds and displays an XY plot.

Validates all inputs before making any change (see Note 2). On success, tears down any active plot, builds renderers, axes, panes, the legend, and the hover controller, subscribes to p_dataset.changed and to the TauStyle resources reachable from p_xy_config, and schedules the first render. The plot keeps references to the provided parameters. Mutating a configuration property after plotting is supported, but requires queue_refresh() or refresh_now() to apply the change.

Can be called before the node enters the scene tree. The first render then happens on entry.

Parameters

  • p_dataset: Dataset The data model. The plot holds a reference and subscribes to its changed signal for the lifetime of this plot. Must not be null.
  • p_xy_config: TauXYConfig Defines the X axis, pane layout, overlay configurations, and visual settings. Must not be null, and its x_axis must not be null either.
  • p_series_bindings: Array[TauXYSeriesBinding] One entry per series-to-pane mapping. Each entry specifies a series_id, a pane_index, an overlay_type, and a y_axis_id. Must not be null and must hold at least one entry.

reset()

reset() -> void

Destroys the active plot and clears the plot area.

Frees the internal plot nodes and disconnects dataset and style signals. The exported properties are left untouched, so a non-empty title stays displayed. Safe to call when no plot is active.

queue_refresh()

queue_refresh() -> void

Schedules a render update for the next frame.

Call this after mutating a configuration property on the objects passed to plot_xy() to apply the change. Repeated calls before the render coalesce into a single update.

On a node outside the scene tree, the request is held and the render happens when the node enters the tree.

refresh_now()

refresh_now() -> void

Renders in the current frame instead of the next one.

For a visual-only change this gives the same result as queue_refresh(), one frame earlier. A change that affects the layout may still need the next frame to settle. Prefer queue_refresh() unless a per-frame animation cannot afford the extra frame.

A render already scheduled by queue_refresh() is not cancelled and still runs on the next frame.