VisPy 2 API Reference

The VisPy 2 package provides high-level components for interactive axes display and pan/zoom functionality, building on top of the GSP API.

Overview

vispy2

VisPy 2 package.

Axes Module

The axes module provides components for displaying and interacting with 2D axes in a viewport.

vispy2.axes

Initialization code for the axes module.

Axes Display

vispy2.axes.axes_display

Module providing an AxesDisplay class to display axes in a viewport using NDC conversions.

AxesDisplay

Class to display axes in a viewport using NDC conversions.

Source code in src/vispy2/axes/axes_display.py

class AxesDisplay:
    """Class to display axes in a viewport using NDC conversions."""

    def __init__(self, canvas: Canvas, inner_viewport: Viewport) -> None:
        """Initialize the AxesDisplay example."""
        self._canvas = canvas
        """Canvas to render on."""
        self._inner_viewport = inner_viewport
        """Innert viewport to render visual in."""
        self._outter_viewport = Viewport(0, 0, self._canvas.get_width(), self._canvas.get_height(), Constants.Color.transparent)
        """Outter viewport to render axes in (arround inner viewport)."""

        self._inner_viewport_unit = ViewportUnitUtils(self._canvas, self._inner_viewport)
        """Unit converter for inner viewport."""
        self._outter_viewport_unit = ViewportUnitUtils(self._canvas, self._outter_viewport)
        """Unit converter for outter viewport."""
        self._x_min_dunit = -1.0
        """x minimum in data units."""
        self._x_max_dunit = +1.0
        """x maximum in data units."""
        self._y_min_dunit = -1.0
        """y minimum in data units."""
        self._y_max_dunit = +1.0
        """y maximum in data units."""

        self.new_limits_event = Event[AxesDisplayNewLimitsEventCallback]()
        """Event triggered when the axes limits are changed.

        Allow to render visuals and axes synchronously when axes limits change.
        """

        # Initialize render items
        self._axes_segments_render_item: RenderItem | None = None
        self._ticks_horizontal_render_item: RenderItem | None = None
        self._ticks_vertical_render_item: RenderItem | None = None
        self._texts_horizontal_render_item: RenderItem | None = None
        self._texts_vertical_render_item: RenderItem | None = None

        # Label text state
        self._title: str | None = None
        """Plot title text, or None if not set."""
        self._xlabel: str | None = None
        """X-axis label text, or None if not set."""
        self._ylabel: str | None = None
        """Y-axis label text, or None if not set."""

        # Label render items
        self._title_render_item: RenderItem | None = None
        self._xlabel_render_item: RenderItem | None = None
        self._ylabel_render_item: RenderItem | None = None

        # Build render items
        self._build_render_items()

    def set_limits_dunit(self, x_min_dunit: float, x_max_dunit: float, y_min_dunit: float, y_max_dunit: float) -> None:
        """Set the axes limits in data units."""
        # sanity checks
        assert x_min_dunit < x_max_dunit, f"x_min MUST be less than x_max, got x_min_dunit={x_min_dunit}, x_max_dunit={x_max_dunit}"
        assert y_min_dunit < y_max_dunit, f"y_min MUST be less than y_max, got y_min_dunit={y_min_dunit}, y_max_dunit={y_max_dunit}"

        # set limits
        self._x_min_dunit = x_min_dunit
        self._x_max_dunit = x_max_dunit
        self._y_min_dunit = y_min_dunit
        self._y_max_dunit = y_max_dunit

        # rebuild render items
        self._build_render_items()

        # Notify event listeners
        self.new_limits_event.dispatch()

    def get_limits_dunit(self) -> tuple[float, float, float, float]:
        """Get the axes limits in data units."""
        return (self._x_min_dunit, self._x_max_dunit, self._y_min_dunit, self._y_max_dunit)

    def set_title(self, text: str | None) -> None:
        """Set the plot title. Pass None to remove it."""
        self._title = text
        self._build_render_items()
        self.new_limits_event.dispatch()

    def set_xlabel(self, text: str | None) -> None:
        """Set the x-axis label. Pass None to remove it."""
        self._xlabel = text
        self._build_render_items()
        self.new_limits_event.dispatch()

    def set_ylabel(self, text: str | None) -> None:
        """Set the y-axis label. Pass None to remove it."""
        self._ylabel = text
        self._build_render_items()
        self.new_limits_event.dispatch()

    def get_transform_matrix_numpy(self) -> np.ndarray:
        """Get the transform matrix from data units to NDC units for the inner viewport."""
        # Compute translation matrix
        translation_matrix = glm.translate(np.array([-(self._x_max_dunit + self._x_min_dunit) / 2.0, -(self._y_max_dunit + self._y_min_dunit) / 2.0, 0.0]))
        # Compute scale matrix
        scale_matrix = glm.scale(np.array([2.0 / (self._x_max_dunit - self._x_min_dunit), 2.0 / (self._y_max_dunit - self._y_min_dunit), 1.0]))
        # Combine translation and scale to get the final transform matrix
        axes_transform_numpy = scale_matrix @ translation_matrix
        # Return the transform matrix
        return axes_transform_numpy

    def get_inner_viewport(self) -> Viewport:
        """Get the inner viewport."""
        return self._inner_viewport

    def get_outter_viewport(self) -> Viewport:
        """Get the outter viewport."""
        return self._outter_viewport

    def get_render_items(self) -> list[RenderItem]:
        """Get the render items for the axes display."""
        # Collect all render items into a list
        render_items: list[RenderItem] = []
        if self._axes_segments_render_item is not None:
            render_items.append(self._axes_segments_render_item)
        if self._ticks_horizontal_render_item is not None:
            render_items.append(self._ticks_horizontal_render_item)
        if self._ticks_vertical_render_item is not None:
            render_items.append(self._ticks_vertical_render_item)
        if self._texts_horizontal_render_item is not None:
            render_items.append(self._texts_horizontal_render_item)
        if self._texts_vertical_render_item is not None:
            render_items.append(self._texts_vertical_render_item)
        if self._title_render_item is not None:
            render_items.append(self._title_render_item)
        if self._xlabel_render_item is not None:
            render_items.append(self._xlabel_render_item)
        if self._ylabel_render_item is not None:
            render_items.append(self._ylabel_render_item)
        # Retrun the render items
        return render_items

    # =============================================================================
    #
    # =============================================================================

    def _build_render_items(self) -> None:
        """Build the render items for the axes display."""
        has_tick_horizontal = AxesDisplay._has_tick_horizontal(self._inner_viewport_unit, self._outter_viewport_unit, self._x_min_dunit, self._x_max_dunit)
        has_tick_vertical = AxesDisplay._has_tick_vertical(self._inner_viewport_unit, self._outter_viewport_unit, self._y_min_dunit, self._y_max_dunit)

        # =============================================================================
        # Create new axes segments, preserving UUIDs to avoid recreating visuals
        # =============================================================================
        axes_segments_uuid: str | None = self._axes_segments_render_item.visual_base.get_uuid() if self._axes_segments_render_item is not None else None
        self._axes_segments_render_item = RenderItem(
            self._outter_viewport_unit.get_viewport(),
            AxesDisplay._generate_visual_axes_segments(self._inner_viewport_unit, self._outter_viewport_unit),
            Bufferx.mat4_identity(),
            Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
        )
        if axes_segments_uuid is not None:
            self._axes_segments_render_item.visual_base.set_uuid(axes_segments_uuid)

        # =============================================================================
        # Create new horizontal ticks, preserving UUIDs to avoid recreating visuals
        # =============================================================================
        if has_tick_horizontal is True:
            ticks_horizontal_uuid: str | None = (
                self._ticks_horizontal_render_item.visual_base.get_uuid() if self._ticks_horizontal_render_item is not None else None
            )
            self._ticks_horizontal_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_ticks_horizontal(self._inner_viewport_unit, self._outter_viewport_unit, self._x_min_dunit, self._x_max_dunit),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if ticks_horizontal_uuid is not None:
                self._ticks_horizontal_render_item.visual_base.set_uuid(ticks_horizontal_uuid)
        else:
            self._ticks_horizontal_render_item = None

        # =============================================================================
        # Create new vertical ticks, preserving UUIDs to avoid recreating visuals
        # =============================================================================
        if has_tick_vertical is True:
            ticks_vertical_uuid: str | None = self._ticks_vertical_render_item.visual_base.get_uuid() if self._ticks_vertical_render_item is not None else None
            self._ticks_vertical_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_ticks_vertical(self._inner_viewport_unit, self._outter_viewport_unit, self._y_min_dunit, self._y_max_dunit),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if ticks_vertical_uuid is not None:
                self._ticks_vertical_render_item.visual_base.set_uuid(ticks_vertical_uuid)
        else:
            self._ticks_vertical_render_item = None

        # =============================================================================
        # Create new horizontal texts, preserving UUIDs to avoid recreating visuals
        # =============================================================================
        if has_tick_horizontal is True:
            texts_horizontal_uuid: str | None = (
                self._texts_horizontal_render_item.visual_base.get_uuid() if self._texts_horizontal_render_item is not None else None
            )
            self._texts_horizontal_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_texts_horizontal(self._inner_viewport_unit, self._outter_viewport_unit, self._x_min_dunit, self._x_max_dunit),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if texts_horizontal_uuid is not None:
                self._texts_horizontal_render_item.visual_base.set_uuid(texts_horizontal_uuid)
        else:
            self._texts_horizontal_render_item = None

        # =============================================================================
        # Create new vertical texts, preserving UUIDs to avoid recreating visuals
        # =============================================================================
        if has_tick_vertical is True:
            texts_vertical_uuid: str | None = self._texts_vertical_render_item.visual_base.get_uuid() if self._texts_vertical_render_item is not None else None
            self._texts_vertical_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_texts_vertical(self._inner_viewport_unit, self._outter_viewport_unit, self._y_min_dunit, self._y_max_dunit),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if texts_vertical_uuid is not None:
                self._texts_vertical_render_item.visual_base.set_uuid(texts_vertical_uuid)
        else:
            self._texts_vertical_render_item = None

        # =============================================================================
        # Title
        # =============================================================================
        if self._title is not None:
            title_uuid: str | None = self._title_render_item.visual_base.get_uuid() if self._title_render_item is not None else None
            self._title_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_title(self._inner_viewport_unit, self._outter_viewport_unit, self._title),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if title_uuid is not None:
                self._title_render_item.visual_base.set_uuid(title_uuid)
        else:
            self._title_render_item = None

        # =============================================================================
        # X-axis label
        # =============================================================================
        if self._xlabel is not None:
            xlabel_uuid: str | None = self._xlabel_render_item.visual_base.get_uuid() if self._xlabel_render_item is not None else None
            self._xlabel_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_xlabel(self._inner_viewport_unit, self._outter_viewport_unit, self._xlabel),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if xlabel_uuid is not None:
                self._xlabel_render_item.visual_base.set_uuid(xlabel_uuid)
        else:
            self._xlabel_render_item = None

        # =============================================================================
        # Y-axis label
        # =============================================================================
        if self._ylabel is not None:
            ylabel_uuid: str | None = self._ylabel_render_item.visual_base.get_uuid() if self._ylabel_render_item is not None else None
            self._ylabel_render_item = RenderItem(
                self._outter_viewport_unit.get_viewport(),
                AxesDisplay._generate_visual_ylabel(self._inner_viewport_unit, self._outter_viewport_unit, self._ylabel),
                Bufferx.mat4_identity(),
                Camera(Bufferx.mat4_identity(), Bufferx.mat4_identity()),
            )
            if ylabel_uuid is not None:
                self._ylabel_render_item.visual_base.set_uuid(ylabel_uuid)
        else:
            self._ylabel_render_item = None

    @staticmethod
    def _has_tick_horizontal(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        x_min_dunit: float,
        x_max_dunit: float,
    ) -> bool:
        """Check if there is at least one tick to display for the horizontal axis."""
        coords_array, _ = AxesDisplay._compute_tick_coords_horizontal(inner_viewport_unit, outter_viewport_unit, x_min_dunit, x_max_dunit)

        has_tick_horizontal = len(coords_array) > 0
        return has_tick_horizontal

    @staticmethod
    def _has_tick_vertical(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        y_min_dunit: float,
        y_max_dunit: float,
    ) -> bool:
        """Check if there is at least one tick to display for the vertical axis."""
        coords_array, _ = AxesDisplay._compute_tick_coords_vertical(inner_viewport_unit, outter_viewport_unit, y_min_dunit, y_max_dunit)

        has_tick_vertical = len(coords_array) > 0
        return has_tick_vertical

    @staticmethod
    def _compute_tick_coords_horizontal(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        x_min_dunit: float,
        x_max_dunit: float,
    ) -> tuple[list[Tuple[float, float, float]], list[str]]:
        """Compute the tick coordinates in outer viewport NDC for the horizontal axis."""
        inner_viewport = inner_viewport_unit.get_viewport()

        # compute tick_y_outter_ndc
        tick_y_inner_ndc = -1.0  # at bottom of inner viewport
        tick_y_outter_pixel = inner_viewport.get_y() + ((tick_y_inner_ndc + 1.0) / 2.0) * inner_viewport.get_height()
        _, tick_y_outter_delta_ndc = outter_viewport_unit.delta_pixel_to_ndc(0.0, tick_y_outter_pixel)
        tick_y_outter_ndc = tick_y_outter_delta_ndc - 1.0

        # Compute nice tick positions and labels using AxisTickLocator and AxisTickFormatter
        tick_locator = AxisTickLocator(target_ticks=7)
        tick_positions_dunit, tick_step = tick_locator.compute_location_dunit(x_min_dunit, x_max_dunit)
        tick_formatter = AxisTickFormatter()
        tick_labels = [tick_formatter.format(tick_position, tick_step) for tick_position in tick_positions_dunit]

        # Create positions for ticks from -num_ticks/2 to +num_ticks/2
        tick_positions = []
        for tick_x_inner_dunit in tick_positions_dunit:
            # compute tick_x_outter_ndc
            tick_x_inner_ndc = (tick_x_inner_dunit - x_min_dunit) / (x_max_dunit - x_min_dunit) * 2.0 - 1.0
            tick_x_outter_delta_pixel = inner_viewport.get_x() + ((tick_x_inner_ndc + 1.0) / 2.0) * inner_viewport.get_width()
            tick_x_outter_delta_ndc, _ = outter_viewport_unit.delta_pixel_to_ndc(tick_x_outter_delta_pixel, 0.0)
            tick_x_outter_ndc = tick_x_outter_delta_ndc - 1.0

            tick_positions.append([tick_x_outter_ndc, tick_y_outter_ndc, 0.0])

        # =============================================================================
        # Return coord_array and tick_labels
        # =============================================================================
        return tick_positions, tick_labels

    @staticmethod
    def _compute_tick_coords_vertical(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        y_min_dunit: float,
        y_max_dunit: float,
    ) -> tuple[list[Tuple[float, float, float]], list[str]]:
        """Compute the tick coordinates in outer viewport NDC for the vertical axis."""
        inner_viewport = inner_viewport_unit.get_viewport()

        # compute tick_x_outter_ndc
        tick_x_inner_ndc = -1.0  # at left of inner viewport
        tick_x_outter_pixel = inner_viewport.get_x() + ((tick_x_inner_ndc + 1.0) / 2.0) * inner_viewport.get_width()
        tick_x_outter_delta_ndc, _ = outter_viewport_unit.delta_pixel_to_ndc(tick_x_outter_pixel, 0.0)
        tick_x_outter_ndc = tick_x_outter_delta_ndc - 1.0

        # Compute nice tick positions and labels using AxisTickLocator and AxisTickFormatter
        tick_locator = AxisTickLocator(target_ticks=7)
        tick_positions_dunit, tick_step = tick_locator.compute_location_dunit(y_min_dunit, y_max_dunit)
        tick_formatter = AxisTickFormatter()
        tick_labels = [tick_formatter.format(tick_position, tick_step) for tick_position in tick_positions_dunit]

        # Create positions for ticks from -num_ticks/2 to +num_ticks/2
        tick_positions = []
        # for tick_y_inner_dunit in range(math.ceil(y_min_dunit), math.ceil(y_max_dunit) + 1):
        for tick_y_inner_dunit in tick_positions_dunit:
            # compute tick_y_outter_ndc
            tick_y_inner_ndc = (tick_y_inner_dunit - y_min_dunit) / (y_max_dunit - y_min_dunit) * 2.0 - 1.0
            tick_y_outter_delta_pixel = inner_viewport.get_y() + ((tick_y_inner_ndc + 1.0) / 2.0) * inner_viewport.get_height()
            _, tick_y_outter_delta_ndc = outter_viewport_unit.delta_pixel_to_ndc(0.0, tick_y_outter_delta_pixel)
            tick_y_outter_ndc = tick_y_outter_delta_ndc - 1.0

            tick_positions.append([tick_x_outter_ndc, tick_y_outter_ndc, 0.0])

        return tick_positions, tick_labels

    @staticmethod
    def _generate_visual_axes_segments(inner_viewport_unit: ViewportUnitUtils, outter_viewport_unit: ViewportUnitUtils) -> Segments:
        """Generate axes segments in NDC units for the given viewport."""
        inner_viewport = inner_viewport_unit.get_viewport()
        canvas = inner_viewport_unit.get_canvas()

        # Compute NDC coordinates of the inner viewport corners in outter viewport
        delta_min_ndc = outter_viewport_unit.delta_pixel_to_ndc(inner_viewport.get_x(), inner_viewport.get_y())
        delta_max_ndc = outter_viewport_unit.delta_pixel_to_ndc(
            inner_viewport.get_x() + inner_viewport.get_width(),
            inner_viewport.get_y() + inner_viewport.get_height(),
        )
        coord_min_ndc = (-1.0 + delta_min_ndc[0], -1.0 + delta_min_ndc[1])
        coord_max_ndc = (-1.0 + delta_max_ndc[0], -1.0 + delta_max_ndc[1])

        # Create segments for the axes
        segments_count = 2
        positions_numpy = np.array(
            [
                [coord_min_ndc[0], coord_min_ndc[1], 0.0],
                [coord_max_ndc[0], coord_min_ndc[1], 0.0],
                [coord_min_ndc[0], coord_min_ndc[1], 0.0],
                [coord_min_ndc[0], coord_max_ndc[1], 0.0],
            ],
            dtype=np.float32,
        )
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        line_widths_numpy = np.array([UnitUtils.pixel_to_point(2, canvas.get_dpi())] * segments_count, dtype=np.float32)
        line_widths_buffer = Bufferx.from_numpy(line_widths_numpy, BufferType.float32)

        colors_buffer = Buffer(segments_count, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * segments_count, 0, segments_count)

        segments = Segments(positions_buffer, line_widths_buffer, CapStyle.ROUND, colors_buffer)
        return segments

    @staticmethod
    def _generate_visual_ticks_horizontal(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        x_min_dunit: float,
        x_max_dunit: float,
    ) -> Segments:
        canvas = outter_viewport_unit.get_canvas()

        # get tick coordinates
        coords_array, _ = AxesDisplay._compute_tick_coords_horizontal(inner_viewport_unit, outter_viewport_unit, x_min_dunit, x_max_dunit)

        # compute tick_height_ndc
        _, tick_height_ndc = outter_viewport_unit.delta_cm_to_ndc(0.0, 0.2)

        # build positions array from coords
        positions_array = []
        for tick_x_outter_ndc, tick_y_outter_ndc, tick_z_outter_ndc in coords_array:
            positions_array.append([tick_x_outter_ndc, tick_y_outter_ndc + 0.0, 0.0])
            positions_array.append([tick_x_outter_ndc, tick_y_outter_ndc - tick_height_ndc, 0.0])

        positions_numpy = np.array(positions_array, dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        # sanitity checks
        assert positions_buffer.get_count() % 2 == 0
        segments_count = positions_buffer.get_count() // 2
        assert segments_count == positions_buffer.get_count() / 2

        line_widths_numpy = np.array([UnitUtils.pixel_to_point(1, canvas.get_dpi())] * segments_count, dtype=np.float32)
        line_widths_buffer = Bufferx.from_numpy(line_widths_numpy, BufferType.float32)

        colors_buffer = Buffer(segments_count, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * segments_count, 0, segments_count)

        segments = Segments(positions_buffer, line_widths_buffer, CapStyle.ROUND, colors_buffer)
        return segments

    @staticmethod
    def _generate_visual_ticks_vertical(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        y_min_dunit: float,
        y_max_dunit: float,
    ) -> Segments:
        canvas = outter_viewport_unit.get_canvas()

        # get tick coordinates
        coords_array, tick_labels = AxesDisplay._compute_tick_coords_vertical(inner_viewport_unit, outter_viewport_unit, y_min_dunit, y_max_dunit)

        # compute tick_width_ndc
        tick_width_ndc, _ = outter_viewport_unit.delta_cm_to_ndc(0.2, 0.0)

        # build positions array from coords
        positions_array = []
        for tick_x_outter_ndc, tick_y_outter_ndc, tick_z_outter_ndc in coords_array:
            positions_array.append([tick_x_outter_ndc + 0.0, tick_y_outter_ndc, 0.0])
            positions_array.append([tick_x_outter_ndc - tick_width_ndc, tick_y_outter_ndc, 0.0])

        positions_numpy = np.array(positions_array, dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        # sanitity checks
        assert positions_buffer.get_count() % 2 == 0
        segments_count = positions_buffer.get_count() // 2
        assert segments_count == positions_buffer.get_count() / 2

        line_widths_numpy = np.array([UnitUtils.pixel_to_point(1, canvas.get_dpi())] * segments_count, dtype=np.float32)
        line_widths_buffer = Bufferx.from_numpy(line_widths_numpy, BufferType.float32)

        colors_buffer = Buffer(segments_count, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * segments_count, 0, segments_count)

        segments = Segments(positions_buffer, line_widths_buffer, CapStyle.BUTT, colors_buffer)
        return segments

    @staticmethod
    def _generate_visual_texts_horizontal(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        x_min_dunit: float,
        x_max_dunit: float,
    ) -> Texts:
        canvas = outter_viewport_unit.get_canvas()

        # get tick coordinates
        coords_array, tick_labels = AxesDisplay._compute_tick_coords_horizontal(inner_viewport_unit, outter_viewport_unit, x_min_dunit, x_max_dunit)

        # compute tick_height_ndc
        _, tick_height_ndc = outter_viewport_unit.delta_cm_to_ndc(0.0, 0.4)

        # build positions array from coords
        positions_array = []
        for tick_x_outter_ndc, tick_y_outter_ndc, tick_z_outter_ndc in coords_array:
            positions_array.append([tick_x_outter_ndc, tick_y_outter_ndc - tick_height_ndc, 0.0])

        positions_numpy = np.array(positions_array, dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        label_count = len(tick_labels)

        colors_buffer = Buffer(label_count, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * label_count, 0, label_count)

        font_size_numpy = np.array([UnitUtils.pixel_to_point(12, canvas.get_dpi())] * label_count, dtype=np.float32)
        font_size_buffer = Bufferx.from_numpy(font_size_numpy, BufferType.float32)

        # Create a anchor_numpy for each string with a bottom-left anchor
        textAligns = [TextAlign.CENTER_CENTER] * label_count

        angles_numpy = np.array([[0] for _ in range(label_count)], dtype=np.float32)
        angles_buffer = Bufferx.from_numpy(angles_numpy, BufferType.float32)

        font_name = "Arial"

        # Create the Texts visual
        texts = Texts(positions_buffer, tick_labels, colors_buffer, font_size_buffer, textAligns, angles_buffer, font_name)

        return texts

    @staticmethod
    def _generate_visual_texts_vertical(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        y_min_dunit: float,
        y_max_dunit: float,
    ) -> Texts:
        canvas = outter_viewport_unit.get_canvas()

        # get tick coordinates
        coords_array, tick_labels = AxesDisplay._compute_tick_coords_vertical(inner_viewport_unit, outter_viewport_unit, y_min_dunit, y_max_dunit)

        # compute tick_width_ndc
        tick_width_ndc, _ = outter_viewport_unit.delta_cm_to_ndc(0.3, 0.0)

        # build positions array from coords
        positions_array = []
        for tick_x_outter_ndc, tick_y_outter_ndc, tick_z_outter_ndc in coords_array:
            positions_array.append([tick_x_outter_ndc - tick_width_ndc, tick_y_outter_ndc, 0.0])

        positions_numpy = np.array(positions_array, dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        label_count = len(tick_labels)

        colors_buffer = Buffer(label_count, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * label_count, 0, label_count)

        font_size_numpy = np.array([UnitUtils.pixel_to_point(12, canvas.get_dpi())] * label_count, dtype=np.float32)
        font_size_buffer = Bufferx.from_numpy(font_size_numpy, BufferType.float32)

        # Create a anchor_numpy for each string with a bottom-left anchor
        textAligns = [TextAlign.CENTER_RIGHT] * label_count

        angles_numpy = np.array([[0] for _ in range(label_count)], dtype=np.float32)
        angles_buffer = Bufferx.from_numpy(angles_numpy, BufferType.float32)

        font_name = "Arial"

        # Create the Texts visual
        texts = Texts(positions_buffer, tick_labels, colors_buffer, font_size_buffer, textAligns, angles_buffer, font_name)

        return texts

    @staticmethod
    def _generate_visual_title(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        text: str,
    ) -> Texts:
        """Generate a title Texts visual centered above the inner viewport.

        Visual style: 14 pt, black, centered horizontally, no rotation.
        Position: 0.15 cm above the top edge of the inner viewport.
        """
        canvas = outter_viewport_unit.get_canvas()
        inner_viewport = inner_viewport_unit.get_viewport()

        # x: horizontal center of the inner viewport in outer NDC
        center_x_pixel = inner_viewport.get_x() + 0.5 * inner_viewport.get_width()
        center_x_delta_ndc, _ = outter_viewport_unit.delta_pixel_to_ndc(center_x_pixel, 0.0)
        center_x_ndc = center_x_delta_ndc - 1.0

        # y: top of inner viewport + 0.15 cm upward offset
        top_y_pixel = inner_viewport.get_y() + inner_viewport.get_height()
        _, top_y_delta_ndc = outter_viewport_unit.delta_pixel_to_ndc(0.0, top_y_pixel)
        top_y_ndc = top_y_delta_ndc - 1.0
        _, offset_ndc = outter_viewport_unit.delta_cm_to_ndc(0.0, 0.15)
        title_y_ndc = top_y_ndc + offset_ndc

        positions_numpy = np.array([[center_x_ndc, title_y_ndc, 0.0]], dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        colors_buffer = Buffer(1, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * 1, 0, 1)

        font_size_numpy = np.array([UnitUtils.pixel_to_point(14, canvas.get_dpi())], dtype=np.float32)
        font_size_buffer = Bufferx.from_numpy(font_size_numpy, BufferType.float32)

        # centered horizontally, top of text at position (text hangs down into the gap)
        textAligns = [TextAlign.TOP_CENTER]

        angles_numpy = np.array([[0.0]], dtype=np.float32)
        angles_buffer = Bufferx.from_numpy(angles_numpy, BufferType.float32)

        return Texts(positions_buffer, [text], colors_buffer, font_size_buffer, textAligns, angles_buffer, "Arial")

    @staticmethod
    def _generate_visual_xlabel(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        text: str,
    ) -> Texts:
        """Generate an x-axis label Texts visual centered below the inner viewport.

        Visual style: 13 pt, black, centered horizontally, no rotation.
        Position: 0.8 cm below the bottom edge of the inner viewport (below the tick labels).
        """
        canvas = outter_viewport_unit.get_canvas()
        inner_viewport = inner_viewport_unit.get_viewport()

        # x: horizontal center of the inner viewport in outer NDC
        center_x_pixel = inner_viewport.get_x() + 0.5 * inner_viewport.get_width()
        center_x_delta_ndc, _ = outter_viewport_unit.delta_pixel_to_ndc(center_x_pixel, 0.0)
        center_x_ndc = center_x_delta_ndc - 1.0

        # y: bottom of inner viewport - 0.8 cm downward offset (clears tick labels)
        bottom_y_pixel = inner_viewport.get_y()
        _, bottom_y_delta_ndc = outter_viewport_unit.delta_pixel_to_ndc(0.0, bottom_y_pixel)
        bottom_y_ndc = bottom_y_delta_ndc - 1.0
        _, offset_ndc = outter_viewport_unit.delta_cm_to_ndc(0.0, 0.6)
        xlabel_y_ndc = bottom_y_ndc - offset_ndc

        positions_numpy = np.array([[center_x_ndc, xlabel_y_ndc, 0.0]], dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        colors_buffer = Buffer(1, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * 1, 0, 1)

        font_size_numpy = np.array([UnitUtils.pixel_to_point(13, canvas.get_dpi())], dtype=np.float32)
        font_size_buffer = Bufferx.from_numpy(font_size_numpy, BufferType.float32)

        # centered horizontally, same anchor convention as horizontal tick labels
        textAligns = [TextAlign.CENTER_CENTER]

        angles_numpy = np.array([[0.0]], dtype=np.float32)
        angles_buffer = Bufferx.from_numpy(angles_numpy, BufferType.float32)

        return Texts(positions_buffer, [text], colors_buffer, font_size_buffer, textAligns, angles_buffer, "Arial")

    @staticmethod
    def _generate_visual_ylabel(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        text: str,
    ) -> Texts:
        """Generate a y-axis label Texts visual centered to the left of the inner viewport.

        Visual style: 13 pt, black, rotated 90° counter-clockwise.
        Position: 1.2 cm to the left of the inner viewport's left edge (clears tick labels).
        """
        canvas = outter_viewport_unit.get_canvas()
        inner_viewport = inner_viewport_unit.get_viewport()

        # x: left of inner viewport - 1.2 cm leftward offset (clears tick labels)
        left_x_pixel = inner_viewport.get_x()
        left_x_delta_ndc, _ = outter_viewport_unit.delta_pixel_to_ndc(left_x_pixel, 0.0)
        left_x_ndc = left_x_delta_ndc - 1.0
        offset_ndc, _ = outter_viewport_unit.delta_cm_to_ndc(0.6, 0.0)
        ylabel_x_ndc = left_x_ndc - offset_ndc

        # y: vertical center of the inner viewport in outer NDC
        center_y_pixel = inner_viewport.get_y() + 0.5 * inner_viewport.get_height()
        _, center_y_delta_ndc = outter_viewport_unit.delta_pixel_to_ndc(0.0, center_y_pixel)
        center_y_ndc = center_y_delta_ndc - 1.0

        positions_numpy = np.array([[ylabel_x_ndc, center_y_ndc, 0.0]], dtype=np.float32)
        positions_buffer = Bufferx.from_numpy(positions_numpy, BufferType.vec3)

        colors_buffer = Buffer(1, BufferType.rgba8)
        colors_buffer.set_data(Constants.Color.black * 1, 0, 1)

        font_size_numpy = np.array([UnitUtils.pixel_to_point(13, canvas.get_dpi())], dtype=np.float32)
        font_size_buffer = Bufferx.from_numpy(font_size_numpy, BufferType.float32)

        # vertically centered at position, same anchor convention as vertical tick labels
        textAligns = [TextAlign.CENTER_CENTER]

        # 90° counter-clockwise so the label reads bottom-to-top along the y-axis
        angles_numpy = np.array([[90.0]], dtype=np.float32)
        angles_buffer = Bufferx.from_numpy(angles_numpy, BufferType.float32)

        return Texts(positions_buffer, [text], colors_buffer, font_size_buffer, textAligns, angles_buffer, "Arial")

new_limits_event = Event[AxesDisplayNewLimitsEventCallback]() instance-attribute

Event triggered when the axes limits are changed.

Allow to render visuals and axes synchronously when axes limits change.

__init__(canvas: Canvas, inner_viewport: Viewport) -> None

Initialize the AxesDisplay example.

Source code in src/vispy2/axes/axes_display.py

def __init__(self, canvas: Canvas, inner_viewport: Viewport) -> None:
    """Initialize the AxesDisplay example."""
    self._canvas = canvas
    """Canvas to render on."""
    self._inner_viewport = inner_viewport
    """Innert viewport to render visual in."""
    self._outter_viewport = Viewport(0, 0, self._canvas.get_width(), self._canvas.get_height(), Constants.Color.transparent)
    """Outter viewport to render axes in (arround inner viewport)."""

    self._inner_viewport_unit = ViewportUnitUtils(self._canvas, self._inner_viewport)
    """Unit converter for inner viewport."""
    self._outter_viewport_unit = ViewportUnitUtils(self._canvas, self._outter_viewport)
    """Unit converter for outter viewport."""
    self._x_min_dunit = -1.0
    """x minimum in data units."""
    self._x_max_dunit = +1.0
    """x maximum in data units."""
    self._y_min_dunit = -1.0
    """y minimum in data units."""
    self._y_max_dunit = +1.0
    """y maximum in data units."""

    self.new_limits_event = Event[AxesDisplayNewLimitsEventCallback]()
    """Event triggered when the axes limits are changed.

    Allow to render visuals and axes synchronously when axes limits change.
    """

    # Initialize render items
    self._axes_segments_render_item: RenderItem | None = None
    self._ticks_horizontal_render_item: RenderItem | None = None
    self._ticks_vertical_render_item: RenderItem | None = None
    self._texts_horizontal_render_item: RenderItem | None = None
    self._texts_vertical_render_item: RenderItem | None = None

    # Label text state
    self._title: str | None = None
    """Plot title text, or None if not set."""
    self._xlabel: str | None = None
    """X-axis label text, or None if not set."""
    self._ylabel: str | None = None
    """Y-axis label text, or None if not set."""

    # Label render items
    self._title_render_item: RenderItem | None = None
    self._xlabel_render_item: RenderItem | None = None
    self._ylabel_render_item: RenderItem | None = None

    # Build render items
    self._build_render_items()

get_inner_viewport() -> Viewport

Get the inner viewport.

Source code in src/vispy2/axes/axes_display.py

def get_inner_viewport(self) -> Viewport:
    """Get the inner viewport."""
    return self._inner_viewport

get_limits_dunit() -> tuple[float, float, float, float]

Get the axes limits in data units.

Source code in src/vispy2/axes/axes_display.py

def get_limits_dunit(self) -> tuple[float, float, float, float]:
    """Get the axes limits in data units."""
    return (self._x_min_dunit, self._x_max_dunit, self._y_min_dunit, self._y_max_dunit)

get_outter_viewport() -> Viewport

Get the outter viewport.

Source code in src/vispy2/axes/axes_display.py

def get_outter_viewport(self) -> Viewport:
    """Get the outter viewport."""
    return self._outter_viewport

get_render_items() -> list[RenderItem]

Get the render items for the axes display.

Source code in src/vispy2/axes/axes_display.py

def get_render_items(self) -> list[RenderItem]:
    """Get the render items for the axes display."""
    # Collect all render items into a list
    render_items: list[RenderItem] = []
    if self._axes_segments_render_item is not None:
        render_items.append(self._axes_segments_render_item)
    if self._ticks_horizontal_render_item is not None:
        render_items.append(self._ticks_horizontal_render_item)
    if self._ticks_vertical_render_item is not None:
        render_items.append(self._ticks_vertical_render_item)
    if self._texts_horizontal_render_item is not None:
        render_items.append(self._texts_horizontal_render_item)
    if self._texts_vertical_render_item is not None:
        render_items.append(self._texts_vertical_render_item)
    if self._title_render_item is not None:
        render_items.append(self._title_render_item)
    if self._xlabel_render_item is not None:
        render_items.append(self._xlabel_render_item)
    if self._ylabel_render_item is not None:
        render_items.append(self._ylabel_render_item)
    # Retrun the render items
    return render_items

get_transform_matrix_numpy() -> np.ndarray

Get the transform matrix from data units to NDC units for the inner viewport.

Source code in src/vispy2/axes/axes_display.py

def get_transform_matrix_numpy(self) -> np.ndarray:
    """Get the transform matrix from data units to NDC units for the inner viewport."""
    # Compute translation matrix
    translation_matrix = glm.translate(np.array([-(self._x_max_dunit + self._x_min_dunit) / 2.0, -(self._y_max_dunit + self._y_min_dunit) / 2.0, 0.0]))
    # Compute scale matrix
    scale_matrix = glm.scale(np.array([2.0 / (self._x_max_dunit - self._x_min_dunit), 2.0 / (self._y_max_dunit - self._y_min_dunit), 1.0]))
    # Combine translation and scale to get the final transform matrix
    axes_transform_numpy = scale_matrix @ translation_matrix
    # Return the transform matrix
    return axes_transform_numpy

set_limits_dunit(x_min_dunit: float, x_max_dunit: float, y_min_dunit: float, y_max_dunit: float) -> None

Set the axes limits in data units.

Source code in src/vispy2/axes/axes_display.py

def set_limits_dunit(self, x_min_dunit: float, x_max_dunit: float, y_min_dunit: float, y_max_dunit: float) -> None:
    """Set the axes limits in data units."""
    # sanity checks
    assert x_min_dunit < x_max_dunit, f"x_min MUST be less than x_max, got x_min_dunit={x_min_dunit}, x_max_dunit={x_max_dunit}"
    assert y_min_dunit < y_max_dunit, f"y_min MUST be less than y_max, got y_min_dunit={y_min_dunit}, y_max_dunit={y_max_dunit}"

    # set limits
    self._x_min_dunit = x_min_dunit
    self._x_max_dunit = x_max_dunit
    self._y_min_dunit = y_min_dunit
    self._y_max_dunit = y_max_dunit

    # rebuild render items
    self._build_render_items()

    # Notify event listeners
    self.new_limits_event.dispatch()

set_title(text: str | None) -> None

Set the plot title. Pass None to remove it.

Source code in src/vispy2/axes/axes_display.py

def set_title(self, text: str | None) -> None:
    """Set the plot title. Pass None to remove it."""
    self._title = text
    self._build_render_items()
    self.new_limits_event.dispatch()

set_xlabel(text: str | None) -> None

Set the x-axis label. Pass None to remove it.

Source code in src/vispy2/axes/axes_display.py

def set_xlabel(self, text: str | None) -> None:
    """Set the x-axis label. Pass None to remove it."""
    self._xlabel = text
    self._build_render_items()
    self.new_limits_event.dispatch()

set_ylabel(text: str | None) -> None

Set the y-axis label. Pass None to remove it.

Source code in src/vispy2/axes/axes_display.py

def set_ylabel(self, text: str | None) -> None:
    """Set the y-axis label. Pass None to remove it."""
    self._ylabel = text
    self._build_render_items()
    self.new_limits_event.dispatch()

AxesDisplayNewLimitsEventCallback

Bases: typing.Protocol

Protocol for axes display new limits event callback functions.

Source code in src/vispy2/axes/axes_display.py

class AxesDisplayNewLimitsEventCallback(Protocol):
    """Protocol for axes display new limits event callback functions."""

    def __call__(self) -> None:
        """Handle a new limits event."""
        ...

__call__() -> None

Handle a new limits event.

Source code in src/vispy2/axes/axes_display.py

def __call__(self) -> None:
    """Handle a new limits event."""
    ...

Axes Pan Zoom

vispy2.axes.axes_panzoom

Class AxesPanZoom to handle panning and zooming in a viewport.

AxesPanZoom

Class to handle panning and zooming in a viewport.

Source code in src/vispy2/axes/axes_panzoom.py

class AxesPanZoom:
    """Class to handle panning and zooming in a viewport."""

    def __init__(self, viewport_events: ViewportEventsBase, base_scale: float, axes_display: AxesDisplay) -> None:
        """Initialize the PanAndZoom example.

        Args:
            viewport_events (ViewportEventsBase): Viewport events to listen to.
            base_scale (float): Base scale for zooming. Greater than 1.0. E.g., 1.1 means 10% zoom in/out per scroll step.
            axes_display (AxesDisplay): Axes display to update.
        """
        self._viewport_events = viewport_events
        """Viewport events to listen to."""
        self._base_scale = base_scale
        """Base scale for zooming. Greater than 1.0. E.g., 1.1 means 10% zoom in/out per scroll step."""
        self._axes_display = axes_display
        """Axes display to update."""

        # Store state for panning
        self._button_press_x_ndc: float | None = None
        """X coordinate of the button press in NDC units."""
        self._button_press_y_ndc: float | None = None
        """Y coordinate of the button press in NDC units."""

        # Store initial limits for this axes
        self._x_min_dunit: float | None = None
        """Current x minimum viewport in data units."""
        self._x_max_dunit: float | None = None
        """Current x maximum viewport in data units."""
        self._y_min_dunit: float | None = None
        """Current y minimum viewport in data units."""
        self._y_max_dunit: float | None = None
        """Current y maximum viewport in data units."""

        # Subscribe to viewport events
        self._viewport_events.button_press_event.subscribe(self._on_button_press)
        self._viewport_events.button_release_event.subscribe(self._on_button_release)
        self._viewport_events.mouse_move_event.subscribe(self._on_mouse_move)
        self._viewport_events.mouse_scroll_event.subscribe(self._on_mouse_scroll)

        # Zoom range limit in data units
        self._zoom_x_min_range_dunit: float | None = None
        """Minimum zoom range in data units for x axis."""
        self._zoom_y_min_range_dunit: float | None = None
        """Minimum zoom range in data units for y axis."""
        self._zoom_x_max_range_dunit: float | None = None
        """Maximum zoom range in data units for x axis."""
        self._zoom_y_max_range_dunit: float | None = None
        """Maximum zoom range in data units for y axis."""

        # Pan limits in data units
        self._pan_x_min_dunit: float | None = None
        """Minimum pan limit in data units for x axis."""
        self._pan_x_max_dunit: float | None = None
        """Maximum pan limit in data units for x axis."""
        self._pan_y_min_dunit: float | None = None
        """Minimum pan limit in data units for y axis."""
        self._pan_y_max_dunit: float | None = None
        """Maximum pan limit in data units for y axis."""

    def close(self) -> None:
        """Close the PanAndZoom example."""
        # Unsubscribe from viewport events
        self._viewport_events.button_press_event.unsubscribe(self._on_button_press)
        self._viewport_events.button_release_event.unsubscribe(self._on_button_release)
        self._viewport_events.mouse_move_event.unsubscribe(self._on_mouse_move)
        self._viewport_events.mouse_scroll_event.unsubscribe(self._on_mouse_scroll)

    # =============================================================================
    # Getters / setters for pan limit
    # =============================================================================

    def get_pan_limits_dunit(self) -> tuple[float | None, float | None, float | None, float | None]:
        """Get the pan limits in data units.

        Returns:
            tuple[float | None, float | None, float | None, float | None]: Pan limits for x min, x max, y min, y max in data units.
        """
        return self._pan_x_min_dunit, self._pan_x_max_dunit, self._pan_y_min_dunit, self._pan_y_max_dunit

    def set_pan_limits_dunit(self, x_min_dunit: float | None, x_max_dunit: float | None, y_min_dunit: float | None, y_max_dunit: float | None) -> None:
        """Set the pan limits in data units.

        Args:
            x_min_dunit (float | None): Minimum pan limit for x axis in data units. If None, no limit is applied.
            x_max_dunit (float | None): Maximum pan limit for x axis in data units. If None, no limit is applied.
            y_min_dunit (float | None): Minimum pan limit for y axis in data units. If None, no limit is applied.
            y_max_dunit (float | None): Maximum pan limit for y axis in data units. If None, no limit is applied.
        """
        self._pan_x_min_dunit = x_min_dunit
        self._pan_x_max_dunit = x_max_dunit
        self._pan_y_min_dunit = y_min_dunit
        self._pan_y_max_dunit = y_max_dunit

    # =============================================================================
    # getters / setters zoom range limit
    # =============================================================================

    def get_zoom_range_limits_dunit(self) -> tuple[float | None, float | None, float | None, float | None]:
        """Get the zoom range limits in data units.

        Returns:
            tuple[float | None, float | None, float | None, float | None]: Min and max zoom range for x and y axes in data units.
        """
        return (self._zoom_x_min_range_dunit, self._zoom_x_max_range_dunit, self._zoom_y_min_range_dunit, self._zoom_y_max_range_dunit)

    def set_zoom_range_limits_dunit(
        self, x_min_range_dunit: float | None, x_max_range_dunit: float | None, y_min_range_dunit: float | None, y_max_range_dunit: float | None
    ) -> None:
        """Set the zoom range limits in data units.

        Args:
            x_min_range_dunit (float | None): Minimum zoom range for x axis in data units. If None, no limit is applied.
            x_max_range_dunit (float | None): Maximum zoom range for x axis in data units. If None, no limit is applied.
            y_min_range_dunit (float | None): Minimum zoom range for y axis in data units. If None, no limit is applied.
            y_max_range_dunit (float | None): Maximum zoom range for y axis in data units. If None, no limit is applied.
        """
        self._zoom_x_min_range_dunit = x_min_range_dunit
        self._zoom_x_max_range_dunit = x_max_range_dunit
        self._zoom_y_min_range_dunit = y_min_range_dunit
        self._zoom_y_max_range_dunit = y_max_range_dunit

    # =============================================================================
    #
    # =============================================================================
    def _on_button_press(self, mouse_event: MouseEvent):
        # Store pixel coordinates instead of data coordinates
        self._button_press_x_ndc = mouse_event.x_ndc
        self._button_press_y_ndc = mouse_event.y_ndc

        self._x_min_dunit, self._x_max_dunit, self._y_min_dunit, self._y_max_dunit = self._axes_display.get_limits_dunit()

    def _on_button_release(self, mouse_event: MouseEvent):
        self._button_press_x_ndc = None
        self._button_press_y_ndc = None
        self._x_min_dunit = None
        self._x_max_dunit = None
        self._y_min_dunit = None
        self._y_max_dunit = None

    def _on_mouse_move(self, mouse_event: MouseEvent):
        # sanity check
        if self._button_press_x_ndc is None or self._button_press_y_ndc is None:
            return
        if self._x_min_dunit is None or self._x_max_dunit is None or self._y_min_dunit is None or self._y_max_dunit is None:
            return

        # Calculate the delta in NDC units
        delta_x_ndc: float = mouse_event.x_ndc - self._button_press_x_ndc
        delta_y_ndc: float = mouse_event.y_ndc - self._button_press_y_ndc

        # Compute new limits in data space for the viewports
        new_x_min_dunit: float = self._x_min_dunit - (delta_x_ndc / 2.0) * (self._x_max_dunit - self._x_min_dunit)
        new_x_max_dunit: float = self._x_max_dunit - (delta_x_ndc / 2.0) * (self._x_max_dunit - self._x_min_dunit)
        new_y_min_dunit: float = self._y_min_dunit - (delta_y_ndc / 2.0) * (self._y_max_dunit - self._y_min_dunit)
        new_y_max_dunit: float = self._y_max_dunit - (delta_y_ndc / 2.0) * (self._y_max_dunit - self._y_min_dunit)

        # =============================================================================
        # Update the axes limits in data unit
        # =============================================================================
        self._set_axes_limits_dunit(new_x_min_dunit, new_x_max_dunit, new_y_min_dunit, new_y_max_dunit)

    def _on_mouse_scroll(self, mouse_event: MouseEvent):
        scale_factor: float = 1 / self._base_scale if mouse_event.scroll_steps >= 0 else self._base_scale

        # Get current limits in data unit
        x_min_dunit, x_max_dunit, y_min_dunit, y_max_dunit = self._axes_display.get_limits_dunit()

        # print(f"scale_factor: {scale_factor}")

        # Calculate mouse position in data units
        mouse_x_dunit: float = x_min_dunit + (mouse_event.x_ndc + 1.0) / 2.0 * (x_max_dunit - x_min_dunit)
        mouse_y_dunit: float = y_min_dunit + (mouse_event.y_ndc + 1.0) / 2.0 * (y_max_dunit - y_min_dunit)

        # Calculate new limits in data units, keeping the mouse position fixed
        new_width_dunit: float = (x_max_dunit - x_min_dunit) * scale_factor
        new_height_dunit: float = (y_max_dunit - y_min_dunit) * scale_factor
        relative_x: float = (x_max_dunit - mouse_x_dunit) / (x_max_dunit - x_min_dunit)
        relative_y: float = (y_max_dunit - mouse_y_dunit) / (y_max_dunit - y_min_dunit)

        # Compute new limits in data units
        new_x_min_dunit: float = mouse_x_dunit - new_width_dunit * (1 - relative_x)
        new_x_max_dunit: float = mouse_x_dunit + new_width_dunit * (relative_x)
        new_y_min_dunit: float = mouse_y_dunit - new_height_dunit * (1 - relative_y)
        new_y_max_dunit: float = mouse_y_dunit + new_height_dunit * (relative_y)

        # =============================================================================
        # Update the axes limits in data unit
        # =============================================================================

        self._set_axes_limits_dunit(new_x_min_dunit, new_x_max_dunit, new_y_min_dunit, new_y_max_dunit)

    # =============================================================================
    #
    # =============================================================================
    def _set_axes_limits_dunit(self, x_min_dunit: float, x_max_dunit: float, y_min_dunit: float, y_max_dunit: float) -> None:
        """Set the axes limits in data units. Applies pan and zoom limits if set.

        Args:
            x_min_dunit (float): Minimum x limit in data units.
            x_max_dunit (float): Maximum x limit in data units.
            y_min_dunit (float): Minimum y limit in data units.
            y_max_dunit (float): Maximum y limit in data units.
        """
        # =============================================================================
        # Enforce min/max zoom range for x/y
        # =============================================================================

        # Enforce minimum zoom range if set for x
        if self._zoom_x_min_range_dunit is not None:
            zoom_x_range_dunit: float = x_max_dunit - x_min_dunit
            if zoom_x_range_dunit < self._zoom_x_min_range_dunit:
                # Clamp the zoom range
                center_x_dunit: float = (x_min_dunit + x_max_dunit) / 2.0
                x_min_dunit = center_x_dunit - self._zoom_x_min_range_dunit / 2.0
                x_max_dunit = center_x_dunit + self._zoom_x_min_range_dunit / 2.0
        # Enforce minimum zoom range if set for y
        if self._zoom_y_min_range_dunit is not None:
            zoom_y_range_dunit: float = y_max_dunit - y_min_dunit
            if zoom_y_range_dunit < self._zoom_y_min_range_dunit:
                # Clamp the zoom range
                center_y_dunit: float = (y_min_dunit + y_max_dunit) / 2.0
                y_min_dunit = center_y_dunit - self._zoom_y_min_range_dunit / 2.0
                y_max_dunit = center_y_dunit + self._zoom_y_min_range_dunit / 2.0
        # Enforce maximum zoom range if set for x
        if self._zoom_x_max_range_dunit is not None:
            zoom_x_range_dunit: float = x_max_dunit - x_min_dunit
            if zoom_x_range_dunit > self._zoom_x_max_range_dunit:
                # Clamp the zoom range
                center_x_dunit: float = (x_min_dunit + x_max_dunit) / 2.0
                x_min_dunit = center_x_dunit - self._zoom_x_max_range_dunit / 2.0
                x_max_dunit = center_x_dunit + self._zoom_x_max_range_dunit / 2.0
        # Enforce maximum zoom range if set for y
        if self._zoom_y_max_range_dunit is not None:
            zoom_y_range_dunit: float = y_max_dunit - y_min_dunit
            if zoom_y_range_dunit > self._zoom_y_max_range_dunit:
                # Clamp the zoom range
                center_y_dunit: float = (y_min_dunit + y_max_dunit) / 2.0
                y_min_dunit = center_y_dunit - self._zoom_y_max_range_dunit / 2.0
                y_max_dunit = center_y_dunit + self._zoom_y_max_range_dunit / 2.0

        # =============================================================================
        # Enforce pan limit
        # =============================================================================
        if self._pan_x_min_dunit is not None:
            if x_min_dunit <= self._pan_x_min_dunit:
                shift_dunit: float = self._pan_x_min_dunit - x_min_dunit
                x_min_dunit += shift_dunit
                x_max_dunit += shift_dunit
        if self._pan_x_max_dunit is not None:
            if x_max_dunit >= self._pan_x_max_dunit:
                shift_dunit: float = x_max_dunit - self._pan_x_max_dunit
                x_min_dunit -= shift_dunit
                x_max_dunit -= shift_dunit
        if self._pan_y_min_dunit is not None:
            if y_min_dunit <= self._pan_y_min_dunit:
                shift_dunit: float = self._pan_y_min_dunit - y_min_dunit
                y_min_dunit += shift_dunit
                y_max_dunit += shift_dunit
        if self._pan_y_max_dunit is not None:
            if y_max_dunit >= self._pan_y_max_dunit:
                shift_dunit: float = y_max_dunit - self._pan_y_max_dunit
                y_min_dunit -= shift_dunit
                y_max_dunit -= shift_dunit

        # handle edge case where pan limits are smaller goes beyond min/max limits by epsilon
        # - sometimes floating point errors can cause this issue e.g. self._pan_x_min_dunit = -2.0 but x_min_dunit = -2.00000001
        epsilon: float = 1e-8
        if self._pan_x_min_dunit is not None:
            if abs(x_min_dunit - self._pan_x_min_dunit) < epsilon:
                x_min_dunit = self._pan_x_min_dunit
        if self._pan_x_max_dunit is not None:
            if abs(x_max_dunit - self._pan_x_max_dunit) < epsilon:
                x_max_dunit = self._pan_x_max_dunit
        if self._pan_y_min_dunit is not None:
            if abs(y_min_dunit - self._pan_y_min_dunit) < epsilon:
                y_min_dunit = self._pan_y_min_dunit
        if self._pan_y_max_dunit is not None:
            if abs(y_max_dunit - self._pan_y_max_dunit) < epsilon:
                y_max_dunit = self._pan_y_max_dunit

        # =============================================================================
        # Finally set the new limits
        # =============================================================================

        # print(f"Set axes limits: x=({x_min_dunit}, {x_max_dunit}), y=({y_min_dunit}, {y_max_dunit})")

        self._axes_display.set_limits_dunit(x_min_dunit, x_max_dunit, y_min_dunit, y_max_dunit)

__init__(viewport_events: ViewportEventsBase, base_scale: float, axes_display: AxesDisplay) -> None

Initialize the PanAndZoom example.

Parameters:

Name	Type	Description	Default
viewport_events	gsp.types.viewport_events_base.ViewportEventsBase	Viewport events to listen to.	required
base_scale	float	Base scale for zooming. Greater than 1.0. E.g., 1.1 means 10% zoom in/out per scroll step.	required
axes_display	vispy2.axes.axes_display.AxesDisplay	Axes display to update.	required

Source code in src/vispy2/axes/axes_panzoom.py

def __init__(self, viewport_events: ViewportEventsBase, base_scale: float, axes_display: AxesDisplay) -> None:
    """Initialize the PanAndZoom example.

    Args:
        viewport_events (ViewportEventsBase): Viewport events to listen to.
        base_scale (float): Base scale for zooming. Greater than 1.0. E.g., 1.1 means 10% zoom in/out per scroll step.
        axes_display (AxesDisplay): Axes display to update.
    """
    self._viewport_events = viewport_events
    """Viewport events to listen to."""
    self._base_scale = base_scale
    """Base scale for zooming. Greater than 1.0. E.g., 1.1 means 10% zoom in/out per scroll step."""
    self._axes_display = axes_display
    """Axes display to update."""

    # Store state for panning
    self._button_press_x_ndc: float | None = None
    """X coordinate of the button press in NDC units."""
    self._button_press_y_ndc: float | None = None
    """Y coordinate of the button press in NDC units."""

    # Store initial limits for this axes
    self._x_min_dunit: float | None = None
    """Current x minimum viewport in data units."""
    self._x_max_dunit: float | None = None
    """Current x maximum viewport in data units."""
    self._y_min_dunit: float | None = None
    """Current y minimum viewport in data units."""
    self._y_max_dunit: float | None = None
    """Current y maximum viewport in data units."""

    # Subscribe to viewport events
    self._viewport_events.button_press_event.subscribe(self._on_button_press)
    self._viewport_events.button_release_event.subscribe(self._on_button_release)
    self._viewport_events.mouse_move_event.subscribe(self._on_mouse_move)
    self._viewport_events.mouse_scroll_event.subscribe(self._on_mouse_scroll)

    # Zoom range limit in data units
    self._zoom_x_min_range_dunit: float | None = None
    """Minimum zoom range in data units for x axis."""
    self._zoom_y_min_range_dunit: float | None = None
    """Minimum zoom range in data units for y axis."""
    self._zoom_x_max_range_dunit: float | None = None
    """Maximum zoom range in data units for x axis."""
    self._zoom_y_max_range_dunit: float | None = None
    """Maximum zoom range in data units for y axis."""

    # Pan limits in data units
    self._pan_x_min_dunit: float | None = None
    """Minimum pan limit in data units for x axis."""
    self._pan_x_max_dunit: float | None = None
    """Maximum pan limit in data units for x axis."""
    self._pan_y_min_dunit: float | None = None
    """Minimum pan limit in data units for y axis."""
    self._pan_y_max_dunit: float | None = None
    """Maximum pan limit in data units for y axis."""

close() -> None

Close the PanAndZoom example.

Source code in src/vispy2/axes/axes_panzoom.py

def close(self) -> None:
    """Close the PanAndZoom example."""
    # Unsubscribe from viewport events
    self._viewport_events.button_press_event.unsubscribe(self._on_button_press)
    self._viewport_events.button_release_event.unsubscribe(self._on_button_release)
    self._viewport_events.mouse_move_event.unsubscribe(self._on_mouse_move)
    self._viewport_events.mouse_scroll_event.unsubscribe(self._on_mouse_scroll)

get_pan_limits_dunit() -> tuple[float | None, float | None, float | None, float | None]

Get the pan limits in data units.

Returns:

Type	Description
tuple[float | None, float | None, float | None, float | None]	tuple[float | None, float | None, float | None, float | None]: Pan limits for x min, x max, y min, y max in data units.

Source code in src/vispy2/axes/axes_panzoom.py

def get_pan_limits_dunit(self) -> tuple[float | None, float | None, float | None, float | None]:
    """Get the pan limits in data units.

    Returns:
        tuple[float | None, float | None, float | None, float | None]: Pan limits for x min, x max, y min, y max in data units.
    """
    return self._pan_x_min_dunit, self._pan_x_max_dunit, self._pan_y_min_dunit, self._pan_y_max_dunit

get_zoom_range_limits_dunit() -> tuple[float | None, float | None, float | None, float | None]

Get the zoom range limits in data units.

Returns:

Type	Description
tuple[float | None, float | None, float | None, float | None]	tuple[float | None, float | None, float | None, float | None]: Min and max zoom range for x and y axes in data units.

Source code in src/vispy2/axes/axes_panzoom.py

def get_zoom_range_limits_dunit(self) -> tuple[float | None, float | None, float | None, float | None]:
    """Get the zoom range limits in data units.

    Returns:
        tuple[float | None, float | None, float | None, float | None]: Min and max zoom range for x and y axes in data units.
    """
    return (self._zoom_x_min_range_dunit, self._zoom_x_max_range_dunit, self._zoom_y_min_range_dunit, self._zoom_y_max_range_dunit)

set_pan_limits_dunit(x_min_dunit: float | None, x_max_dunit: float | None, y_min_dunit: float | None, y_max_dunit: float | None) -> None

Set the pan limits in data units.

Parameters:

Name	Type	Description	Default
x_min_dunit	float | None	Minimum pan limit for x axis in data units. If None, no limit is applied.	required
x_max_dunit	float | None	Maximum pan limit for x axis in data units. If None, no limit is applied.	required
y_min_dunit	float | None	Minimum pan limit for y axis in data units. If None, no limit is applied.	required
y_max_dunit	float | None	Maximum pan limit for y axis in data units. If None, no limit is applied.	required

Source code in src/vispy2/axes/axes_panzoom.py

def set_pan_limits_dunit(self, x_min_dunit: float | None, x_max_dunit: float | None, y_min_dunit: float | None, y_max_dunit: float | None) -> None:
    """Set the pan limits in data units.

    Args:
        x_min_dunit (float | None): Minimum pan limit for x axis in data units. If None, no limit is applied.
        x_max_dunit (float | None): Maximum pan limit for x axis in data units. If None, no limit is applied.
        y_min_dunit (float | None): Minimum pan limit for y axis in data units. If None, no limit is applied.
        y_max_dunit (float | None): Maximum pan limit for y axis in data units. If None, no limit is applied.
    """
    self._pan_x_min_dunit = x_min_dunit
    self._pan_x_max_dunit = x_max_dunit
    self._pan_y_min_dunit = y_min_dunit
    self._pan_y_max_dunit = y_max_dunit

set_zoom_range_limits_dunit(x_min_range_dunit: float | None, x_max_range_dunit: float | None, y_min_range_dunit: float | None, y_max_range_dunit: float | None) -> None

Set the zoom range limits in data units.

Parameters:

Name	Type	Description	Default
x_min_range_dunit	float | None	Minimum zoom range for x axis in data units. If None, no limit is applied.	required
x_max_range_dunit	float | None	Maximum zoom range for x axis in data units. If None, no limit is applied.	required
y_min_range_dunit	float | None	Minimum zoom range for y axis in data units. If None, no limit is applied.	required
y_max_range_dunit	float | None	Maximum zoom range for y axis in data units. If None, no limit is applied.	required

Source code in src/vispy2/axes/axes_panzoom.py

def set_zoom_range_limits_dunit(
    self, x_min_range_dunit: float | None, x_max_range_dunit: float | None, y_min_range_dunit: float | None, y_max_range_dunit: float | None
) -> None:
    """Set the zoom range limits in data units.

    Args:
        x_min_range_dunit (float | None): Minimum zoom range for x axis in data units. If None, no limit is applied.
        x_max_range_dunit (float | None): Maximum zoom range for x axis in data units. If None, no limit is applied.
        y_min_range_dunit (float | None): Minimum zoom range for y axis in data units. If None, no limit is applied.
        y_max_range_dunit (float | None): Maximum zoom range for y axis in data units. If None, no limit is applied.
    """
    self._zoom_x_min_range_dunit = x_min_range_dunit
    self._zoom_x_max_range_dunit = x_max_range_dunit
    self._zoom_y_min_range_dunit = y_min_range_dunit
    self._zoom_y_max_range_dunit = y_max_range_dunit