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

vispy_2

VisPy 2 package.

Axes Module

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

vispy_2.axes

Initialization code for the axes module.

Axes Display

vispy_2.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/vispy_2/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())
        """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

        # 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 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)
        # 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_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_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_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_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_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

    @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_numpy = AxesDisplay._compute_tick_coords_horizontal(inner_viewport_unit, outter_viewport_unit, x_min_dunit, x_max_dunit)

        has_tick_horizontal = len(coords_numpy) > 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_numpy = AxesDisplay._compute_tick_coords_vertical(inner_viewport_unit, outter_viewport_unit, y_min_dunit, y_max_dunit)

        has_tick_vertical = len(coords_numpy) > 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,
    ) -> np.ndarray:
        """Compute the tick coordinates for the horizontal axis."""
        inner_viewport = inner_viewport_unit.get_viewport()

        # Create positions for ticks from -num_ticks/2 to +num_ticks/2
        coords_array = []
        for tick_x_inner_dunit in range(math.ceil(x_min_dunit), math.ceil(x_max_dunit) + 1):
            # skip ticks outside data space limits
            if tick_x_inner_dunit > x_max_dunit:
                continue

            # 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

            # 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

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

        coords_numpy = np.array(coords_array, dtype=np.float32)
        return coords_numpy

    @staticmethod
    def _compute_tick_coords_vertical(
        inner_viewport_unit: ViewportUnitUtils,
        outter_viewport_unit: ViewportUnitUtils,
        y_min_dunit: float,
        y_max_dunit: float,
    ) -> np.ndarray:
        """Compute the tick coordinates for the vertical axis."""
        inner_viewport = inner_viewport_unit.get_viewport()

        # Create positions for ticks from -num_ticks/2 to +num_ticks/2
        coords_array = []
        for tick_y_inner_dunit in range(math.ceil(y_min_dunit), math.ceil(y_max_dunit) + 1):
            # skip ticks outside data space limits
            if tick_y_inner_dunit > y_max_dunit:
                continue

            # 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

            # 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

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

        coords_numpy = np.array(coords_array, dtype=np.float32)
        return coords_numpy

    @staticmethod
    def _generate_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_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_numpy = 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_numpy:
            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_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_numpy = 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_numpy:
            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_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_numpy = 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.3)

        # build positions array from coords
        positions_array = []
        for tick_x_outter_ndc, tick_y_outter_ndc, tick_z_outter_ndc in coords_numpy:
            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)

        strings = []
        for tick_x_inner_dunit in range(math.ceil(x_min_dunit), math.ceil(x_max_dunit) + 1):
            # skip texts outside data space limits
            if tick_x_inner_dunit > x_max_dunit:
                continue

            strings.append(f"{tick_x_inner_dunit}")
        string_count = len(strings)

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

        font_size_numpy = np.array([UnitUtils.pixel_to_point(12, canvas.get_dpi())] * string_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
        anchors_numpy = np.array([[0, 1] for _ in range(string_count)], dtype=np.float32)
        anchors_buffer = Bufferx.from_numpy(anchors_numpy, BufferType.vec2)

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

        font_name = "Arial"

        # Create the Texts visual
        texts = Texts(positions_buffer, strings, colors_buffer, font_size_buffer, anchors_buffer, angles_buffer, font_name)

        return texts

    @staticmethod
    def _generate_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_numpy = 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_numpy:
            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)

        strings = []
        for tick_y_inner_dunit in range(math.ceil(y_min_dunit), math.ceil(y_max_dunit) + 1):
            # skip texts outside data space limits
            if tick_y_inner_dunit > y_max_dunit:
                continue
            strings.append(f"{tick_y_inner_dunit}")
        string_count = len(strings)

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

        font_size_numpy = np.array([UnitUtils.pixel_to_point(12, canvas.get_dpi())] * string_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
        anchors_numpy = np.array([[1, 0] for _ in range(string_count)], dtype=np.float32)
        anchors_buffer = Bufferx.from_numpy(anchors_numpy, BufferType.vec2)

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

        font_name = "Arial"

        # Create the Texts visual
        texts = Texts(positions_buffer, strings, colors_buffer, font_size_buffer, anchors_buffer, angles_buffer, font_name)

        return texts

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/vispy_2/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())
    """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

    # Build render items
    self._build_render_items()

get_inner_viewport() -> Viewport

Get the inner viewport.

Source code in src/vispy_2/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/vispy_2/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/vispy_2/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/vispy_2/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)
    # 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/vispy_2/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/vispy_2/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()

AxesDisplayNewLimitsEventCallback

Bases: typing.Protocol

Protocol for axes display new limits event callback functions.

Source code in src/vispy_2/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/vispy_2/axes/axes_display.py

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

Axes Pan Zoom

vispy_2.axes.axes_pan_zoom

Class AxesPanZoom to handle panning and zooming in a viewport.

AxesPanZoom

Class to handle panning and zooming in a viewport.

Source code in src/vispy_2/axes/axes_pan_zoom.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."""
        self._viewport_events = viewport_events
        """Viewport events to listen to."""
        self._base_scale = base_scale
        """Base scale for zooming."""
        self._axes_display = axes_display
        """Axes display to update."""

        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."""

        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."""

        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_button_move)
        self._viewport_events.mouse_scroll_event.subscribe(self._on_mouse_scroll)

    def close(self) -> None:
        """Close the PanAndZoom example."""
        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_button_move)
        self._viewport_events.mouse_scroll_event.unsubscribe(self._on_mouse_scroll)

    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_button_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 space
        self._axes_display.set_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

        x_min_dunit, x_max_dunit, y_min_dunit, y_max_dunit = self._axes_display.get_limits_dunit()

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

        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)

        new_width: float = (x_max_dunit - x_min_dunit) * scale_factor
        new_height: 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)

        new_x_min: float = mouse_x_dunit - new_width * (1 - relative_x)
        new_x_max: float = mouse_x_dunit + new_width * (relative_x)
        new_y_min: float = mouse_y_dunit - new_height * (1 - relative_y)
        new_y_max: float = mouse_y_dunit + new_height * (relative_y)

        self._axes_display.set_limits_dunit(new_x_min, new_x_max, new_y_min, new_y_max)

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

Initialize the PanAndZoom example.

Source code in src/vispy_2/axes/axes_pan_zoom.py

def __init__(self, viewport_events: ViewportEventsBase, base_scale: float, axes_display: AxesDisplay) -> None:
    """Initialize the PanAndZoom example."""
    self._viewport_events = viewport_events
    """Viewport events to listen to."""
    self._base_scale = base_scale
    """Base scale for zooming."""
    self._axes_display = axes_display
    """Axes display to update."""

    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."""

    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."""

    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_button_move)
    self._viewport_events.mouse_scroll_event.subscribe(self._on_mouse_scroll)

close() -> None

Close the PanAndZoom example.

Source code in src/vispy_2/axes/axes_pan_zoom.py

def close(self) -> None:
    """Close the PanAndZoom example."""
    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_button_move)
    self._viewport_events.mouse_scroll_event.unsubscribe(self._on_mouse_scroll)