Skip to content

SampleHit

Inherits: RefCounted
Namespace: TauPlot

Read-only data object describing one sample detected near the cursor during hover hit testing.

Description

SampleHit carries the identity, values, and screen position of one sample found near the cursor. The plot builds every instance, and user code only reads them.

Arrays of SampleHit objects are delivered through the TauPlot.sample_hovered and TauPlot.sample_clicked signals, and are also passed to the TauHoverConfig.format_tooltip_text and TauHoverConfig.create_tooltip_control callbacks. How many hits an array contains and which samples qualify depend on the active hover mode. See TauHoverConfig for a full description of the hover inspection system.

The first hit of an array is the sample the cursor is on. When the cursor is on no sample, it is the closest one. The plot uses it to place the tooltip.

Properties

series_id

series_id: int

The stable series ID of the hit series, as assigned by the Dataset.

series_name

series_name: String

The human-readable name of the hit series, as stored in the Dataset.

sample_index

sample_index: int

The logical index of the hit sample within its series.

x_value

x_value: Variant

The X value of the hit sample. Holds a float when the X axis is CONTINUOUS, or a String when it is CATEGORICAL.

In X_ALIGNED mode, two hits of the same array can carry different X values. This happens when the overlays of the pane do not use the same X values. Each overlay picks the X position closest to the hovered one among the positions where it has samples, so two overlays can land on different values.

y_plotted_value

y_plotted_value: float

The Y position the sample is drawn at, in data units.

On a STACKED bar overlay or a STACKED line overlay this is the cumulative total of the stack up to and including this series, rescaled when FRACTION or PERCENT normalization is active. In every other case it equals y_raw_value.

y_raw_value

y_raw_value: float

The Y value the Dataset holds for the sample, before stacking, normalization, and accumulation.

This is the value the built-in tooltip formatter renders, and the one to report when a tooltip has to answer what this series measured at this X. y_plotted_value answers where the sample sits on the axis instead.

screen_position

screen_position: Vector2

The pixel position of the hit sample in the plot's local coordinate space. For a BAR overlay this is the center of the bar tip, the edge the bar grows toward. For a SCATTER overlay this is the center of the marker. For a LINE overlay this is the sample position on the curve, never an interpolated point between two samples.

pane_index

pane_index: int

The zero-based index of the pane the hit sample belongs to, matching its position in TauXYConfig.panes.

overlay_type

overlay_type: PaneOverlayType

The overlay type that produced this hit.

distance_px

distance_px: float

The pixel distance from the cursor to screen_position. Useful for a custom proximity threshold applied when handling sample_hovered or sample_clicked.

contains_pointer

contains_pointer: bool

true when the cursor sits inside the hit zone of the sample.

A BAR overlay uses the painted bar rectangle. A SCATTER or LINE overlay has no area to fall inside, so it uses a disc of TauScatterConfig.hover_max_distance_px or TauLineConfig.hover_max_distance_px pixels around screen_position. In NEAREST mode the flag is always true, because that mode discards every sample that fails the same test.