fastplotlib.ReferenceIndices

class ReferenceIndices(ref_ranges)

Manages the shared reference index for one or more NDWidget instances.

Stores the current index for each named slider dimension in reference-space units (ex: seconds, depth in µm, Hz). Whenever an index is updated, every NDGraphic in the manged NDWidgets are requested to render data at the new indices.

Each key in ref_ranges defines a slider dimension. When adding an NDGraphic, every dimension listed in dims is either a spatial dimension (listed in spatial_dims) or a slider dimension. A slider dim without a reference range gets an AutoRangeContinuous sized to the data, so an explicit range is only needed when the slider should map reference-space units to array indices rather than use a one-to-one (identity) mapping.

You can also define conceptually identical but independent reference spaces by using distinct names, ex: "time-1" and "time-2" for two subsets of data that should be sycned independently. Each NDGraphic then declares the specific "time-n" space that corresponds to its data, so the widget keeps the two timelines decoupled.

Parameters:

ref_ranges (dict[str, tuple | RangeContinuous]) – Mapping of dimension names to range specifications. A 3-tuple (start, stop, step) creates a RangeContinuous. A 1-tuple (options,) creates a RangeDiscrete.

Examples

Single shared time axis:

ri = ReferenceIndex(ref_ranges={"time": (0, 1000, 1), "depth": (15, 35, 0.5)})
ri.set_dim_index("time", 500)           # update one dim and re-render
ri.set({"time": 500, "depth": 10})      # update several dims atomically

Two independent time axes for data from two different recording sessions:

ri = ReferenceIndex({
    "time-1": (0, 3600, 1),   # session 1 — 1 h at 1 s resolution
    "time-s": (0, 1800, 1),   # session 2 — 30 min at 1 s resolution
})

Each NDGraphic declares matching names for slider dims to indicate that these should be synced across graphics:

ndw[0, 0].add_nd_image(data_s1, ("time-s1", "row", "col"), ("row", "col"))
ndw[0, 1].add_nd_image(data_s2, ("time-s2", "row", "col"), ("row", "col"))