Skip to content

ScatterVisualCallbacks

Inherits: VisualCallbacks
Namespace: TauPlot

Callback-driven per-sample style overrides for SCATTER overlays.

Description

ScatterVisualCallbacks is the SCATTER specific subclass of VisualCallbacks. It carries the two callbacks inherited from that base class, color_callback and alpha_callback, and adds four scatter-specific callbacks: size_callback, shape_callback, outline_color_callback, and outline_width_callback.

Assign an instance to TauScatterConfig.scatter_visual_callbacks. Any other subclass on a scatter overlay is a validation error and TauPlot.plot_xy() aborts. The plot invokes each valid callback once per sample on each draw pass and applies the returned values on top of the values resolved from TauScatterStyle and TauXYStyle.

Each callback is optional. An invalid Callable means no override for that property, and the resolved style value applies to every sample of the series. Each callback receives the dataset series index, the logical sample index, and the X and Y values of the sample, as described in VisualCallbacks.

The emphasized marker takes the hovered-state properties of TauScatterStyle, so size_callback, outline_color_callback, and outline_width_callback shape every marker except that one.

See TauPaneOverlayConfig for the order a callback resolves in against a ScatterVisualAttributes buffer and the style property.

Example

# Scale each marker by its Y value and use a distinct shape for outliers.
var callbacks := TauPlot.ScatterVisualCallbacks.new()

callbacks.size_callback = func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> float:
    return 8.0 + abs(y_value) * 2.0

callbacks.shape_callback = func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> TauScatterStyle.MarkerShape:
    return TauScatterStyle.MarkerShape.DIAMOND if abs(y_value) > 10.0 else TauScatterStyle.MarkerShape.CIRCLE

var scatter_overlay := TauScatterConfig.new()
scatter_overlay.scatter_visual_callbacks = callbacks

Constructor

new()

ScatterVisualCallbacks.new() -> ScatterVisualCallbacks

Creates a new ScatterVisualCallbacks instance with all callbacks set to an invalid Callable.

Properties

size_callback

size_callback: Callable

Callback computing the marker size of one sample. Default is an invalid Callable.

The return value overrides the size of the marker, taking priority over TauScatterStyle.marker_sizes_px. A negative return is treated as unset. The unit follows the active TauScatterConfig.marker_size_policy: pixels under THEME, X data units under DATA_UNITS, where the drawn size then changes with the X domain. The callback signature is:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> float

The resolved pixel size is raised to 1.0, so a return of 0.0 draws a one pixel marker rather than hiding one. Hide a marker through shape_callback instead.

Under DATA_UNITS on a categorical X axis there is no data span to convert, and the return value is discarded: the size comes from TauScatterStyle.marker_sizes_px, with no error and no warning.

shape_callback

shape_callback: Callable

Callback computing the marker shape of one sample. Default is an invalid Callable.

The return value overrides the shape of the marker, taking priority over TauScatterStyle.marker_shapes. A negative return is treated as unset. Any other value outside TauScatterStyle.MarkerShape draws a CIRCLE with no message, since the callback runs once per sample. The callback signature is:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> TauScatterStyle.MarkerShape

A return of NONE draws nothing for that sample. A sample that draws nothing is also left out of hover hit testing, so it reports no SampleHit and never appears in a tooltip.

outline_color_callback

outline_color_callback: Callable

Callback computing the color of the outline stroked around one marker. Default is an invalid Callable.

The return value overrides the outline color of the marker, taking priority over TauScatterStyle.outline_color. A return of ColorBuffer.NO_COLOR is treated as unset, see note 1 on the base class. The callback signature is:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> Color

The resolved alpha of the sample is applied on top of the returned color, so a marker and its outline fade together.

outline_width_callback

outline_width_callback: Callable

Callback computing the thickness in pixels of the outline stroked around one marker. Default is an invalid Callable.

The return value overrides the outline width of the marker, taking priority over TauScatterStyle.outline_width_px. A negative return is treated as unset. Valid override values are 0.0 or greater, where 0.0 leaves that marker unoutlined, and the drawn outline never exceeds half the resolved marker size. The callback signature is:

func(series_index: int, sample_index: int, x_value: Variant, y_value: float) -> float