Skip to content

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 
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
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 = 0.0
        """x minimum in data units."""
        self._x_max_dunit = +1.0
        """x maximum in data units."""
        self._y_min_dunit = 0.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_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

    @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.3)

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

        labels_count = len(tick_labels)

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

        font_size_numpy = np.array([UnitUtils.pixel_to_point(12, canvas.get_dpi())] * labels_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(labels_count)], dtype=np.float32)
        anchors_buffer = Bufferx.from_numpy(anchors_numpy, BufferType.vec2)

        angles_numpy = np.array([[0] for _ in range(labels_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, anchors_buffer, 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
        anchors_numpy = np.array([[1, 0] for _ in range(label_count)], dtype=np.float32)
        anchors_buffer = Bufferx.from_numpy(anchors_numpy, BufferType.vec2)

        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, 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 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
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 = 0.0
    """x minimum in data units."""
    self._x_max_dunit = +1.0
    """x maximum in data units."""
    self._y_min_dunit = 0.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 
109
110
111
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 
94
95
96
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 
113
114
115
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 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
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 
 98
 99
100
101
102
103
104
105
106
107
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 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
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 
27
28
29
30
31
32
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 
30
31
32
def __call__(self) -> None:
    """Handle a new limits event."""
    ...

Axes Pan Zoom

vispy_2.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/vispy_2/axes/axes_panzoom.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
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 vispy_2.axes.axes_display.AxesDisplay

Axes display to update.

 required
Source code in src/vispy_2/axes/axes_panzoom.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
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/vispy_2/axes/axes_panzoom.py 
70
71
72
73
74
75
76
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/vispy_2/axes/axes_panzoom.py 
82
83
84
85
86
87
88
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/vispy_2/axes/axes_panzoom.py 
108
109
110
111
112
113
114
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/vispy_2/axes/axes_panzoom.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
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/vispy_2/axes/axes_panzoom.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
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