
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "gallery/event_handling/cursor_demo.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. meta::
        :keywords: codex

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_gallery_event_handling_cursor_demo.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_gallery_event_handling_cursor_demo.py:


=================
Cross-hair cursor
=================

This example adds a cross-hair as a data cursor.  The cross-hair is
implemented as regular line objects that are updated on mouse move.

We show three implementations:

1) A simple cursor implementation that redraws the figure on every mouse move.
   This is a bit slow, and you may notice some lag of the cross-hair movement.
2) A cursor that uses blitting for speedup of the rendering.
3) A cursor that snaps to data points.

Faster cursoring is possible using native GUI drawing, as in
:doc:`/gallery/user_interfaces/wxcursor_demo_sgskip`.

The mpldatacursor__ and mplcursors__ third-party packages can be used to
achieve a similar effect.

__ https://github.com/joferkington/mpldatacursor
__ https://github.com/anntzer/mplcursors

.. redirect-from:: /gallery/misc/cursor_demo

.. GENERATED FROM PYTHON SOURCE LINES 27-82

.. code-block:: Python


    import matplotlib.pyplot as plt
    import numpy as np

    from matplotlib.backend_bases import MouseEvent


    class Cursor:
        """
        A cross hair cursor.
        """
        def __init__(self, ax):
            self.ax = ax
            self.horizontal_line = ax.axhline(color='k', lw=0.8, ls='--')
            self.vertical_line = ax.axvline(color='k', lw=0.8, ls='--')
            # text location in axes coordinates
            self.text = ax.text(0.72, 0.9, '', transform=ax.transAxes)

        def set_cross_hair_visible(self, visible):
            need_redraw = self.horizontal_line.get_visible() != visible
            self.horizontal_line.set_visible(visible)
            self.vertical_line.set_visible(visible)
            self.text.set_visible(visible)
            return need_redraw

        def on_mouse_move(self, event):
            if not event.inaxes:
                need_redraw = self.set_cross_hair_visible(False)
                if need_redraw:
                    self.ax.figure.canvas.draw()
            else:
                self.set_cross_hair_visible(True)
                x, y = event.xdata, event.ydata
                # update the line positions
                self.horizontal_line.set_ydata([y])
                self.vertical_line.set_xdata([x])
                self.text.set_text(f'x={x:1.2f}, y={y:1.2f}')
                self.ax.figure.canvas.draw()


    x = np.arange(0, 1, 0.01)
    y = np.sin(2 * 2 * np.pi * x)

    fig, ax = plt.subplots()
    ax.set_title('Simple cursor')
    ax.plot(x, y, 'o')
    cursor = Cursor(ax)
    fig.canvas.mpl_connect('motion_notify_event', cursor.on_mouse_move)

    # Simulate a mouse move to (0.5, 0.5), needed for online docs
    t = ax.transData
    MouseEvent(
        "motion_notify_event", ax.figure.canvas, *t.transform((0.5, 0.5))
    )._process()




.. image-sg:: /gallery/event_handling/images/sphx_glr_cursor_demo_001.png
   :alt: Simple cursor
   :srcset: /gallery/event_handling/images/sphx_glr_cursor_demo_001.png, /gallery/event_handling/images/sphx_glr_cursor_demo_001_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 83-94

Faster redrawing using blitting
"""""""""""""""""""""""""""""""
This technique stores the rendered plot as a background image. Only the
changed artists (cross-hair lines and text) are rendered anew. They are
combined with the background using blitting.

This technique is significantly faster. It requires a bit more setup because
the background has to be stored without the cross-hair lines (see
``create_new_background()``). Additionally, a new background has to be
created whenever the figure changes. This is achieved by connecting to the
``'draw_event'``.

.. GENERATED FROM PYTHON SOURCE LINES 94-169

.. code-block:: Python



    class BlittedCursor:
        """
        A cross-hair cursor using blitting for faster redraw.
        """
        def __init__(self, ax):
            self.ax = ax
            self.background = None
            self.horizontal_line = ax.axhline(color='k', lw=0.8, ls='--')
            self.vertical_line = ax.axvline(color='k', lw=0.8, ls='--')
            # text location in axes coordinates
            self.text = ax.text(0.72, 0.9, '', transform=ax.transAxes)
            self._creating_background = False
            ax.figure.canvas.mpl_connect('draw_event', self.on_draw)

        def on_draw(self, event):
            self.create_new_background()

        def set_cross_hair_visible(self, visible):
            need_redraw = self.horizontal_line.get_visible() != visible
            self.horizontal_line.set_visible(visible)
            self.vertical_line.set_visible(visible)
            self.text.set_visible(visible)
            return need_redraw

        def create_new_background(self):
            if self._creating_background:
                # discard calls triggered from within this function
                return
            self._creating_background = True
            self.set_cross_hair_visible(False)
            self.ax.figure.canvas.draw()
            self.background = self.ax.figure.canvas.copy_from_bbox(self.ax.bbox)
            self.set_cross_hair_visible(True)
            self._creating_background = False

        def on_mouse_move(self, event):
            if self.background is None:
                self.create_new_background()
            if not event.inaxes:
                need_redraw = self.set_cross_hair_visible(False)
                if need_redraw:
                    self.ax.figure.canvas.restore_region(self.background)
                    self.ax.figure.canvas.blit(self.ax.bbox)
            else:
                self.set_cross_hair_visible(True)
                # update the line positions
                x, y = event.xdata, event.ydata
                self.horizontal_line.set_ydata([y])
                self.vertical_line.set_xdata([x])
                self.text.set_text(f'x={x:1.2f}, y={y:1.2f}')

                self.ax.figure.canvas.restore_region(self.background)
                self.ax.draw_artist(self.horizontal_line)
                self.ax.draw_artist(self.vertical_line)
                self.ax.draw_artist(self.text)
                self.ax.figure.canvas.blit(self.ax.bbox)


    x = np.arange(0, 1, 0.01)
    y = np.sin(2 * 2 * np.pi * x)

    fig, ax = plt.subplots()
    ax.set_title('Blitted cursor')
    ax.plot(x, y, 'o')
    blitted_cursor = BlittedCursor(ax)
    fig.canvas.mpl_connect('motion_notify_event', blitted_cursor.on_mouse_move)

    # Simulate a mouse move to (0.5, 0.5), needed for online docs
    t = ax.transData
    MouseEvent(
        "motion_notify_event", ax.figure.canvas, *t.transform((0.5, 0.5))
    )._process()




.. image-sg:: /gallery/event_handling/images/sphx_glr_cursor_demo_002.png
   :alt: Blitted cursor
   :srcset: /gallery/event_handling/images/sphx_glr_cursor_demo_002.png, /gallery/event_handling/images/sphx_glr_cursor_demo_002_2_00x.png 2.00x
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 170-180

Snapping to data points
"""""""""""""""""""""""
The following cursor snaps its position to the data points of a `.Line2D`
object.

To save unnecessary redraws, the index of the last indicated data point is
saved in ``self._last_index``. A redraw is only triggered when the mouse
moves far enough so that another data point must be selected. This reduces
the lag due to many redraws. Of course, blitting could still be added on top
for additional speedup.

.. GENERATED FROM PYTHON SOURCE LINES 180-243

.. code-block:: Python



    class SnappingCursor:
        """
        A cross-hair cursor that snaps to the data point of a line, which is
        closest to the *x* position of the cursor.

        For simplicity, this assumes that *x* values of the data are sorted.
        """
        def __init__(self, ax, line):
            self.ax = ax
            self.horizontal_line = ax.axhline(color='k', lw=0.8, ls='--')
            self.vertical_line = ax.axvline(color='k', lw=0.8, ls='--')
            self.x, self.y = line.get_data()
            self._last_index = None
            # text location in axes coords
            self.text = ax.text(0.72, 0.9, '', transform=ax.transAxes)

        def set_cross_hair_visible(self, visible):
            need_redraw = self.horizontal_line.get_visible() != visible
            self.horizontal_line.set_visible(visible)
            self.vertical_line.set_visible(visible)
            self.text.set_visible(visible)
            return need_redraw

        def on_mouse_move(self, event):
            if not event.inaxes:
                self._last_index = None
                need_redraw = self.set_cross_hair_visible(False)
                if need_redraw:
                    self.ax.figure.canvas.draw()
            else:
                self.set_cross_hair_visible(True)
                x, y = event.xdata, event.ydata
                index = min(np.searchsorted(self.x, x), len(self.x) - 1)
                if index == self._last_index:
                    return  # still on the same data point. Nothing to do.
                self._last_index = index
                x = self.x[index]
                y = self.y[index]
                # update the line positions
                self.horizontal_line.set_ydata([y])
                self.vertical_line.set_xdata([x])
                self.text.set_text(f'x={x:1.2f}, y={y:1.2f}')
                self.ax.figure.canvas.draw()


    x = np.arange(0, 1, 0.01)
    y = np.sin(2 * 2 * np.pi * x)

    fig, ax = plt.subplots()
    ax.set_title('Snapping cursor')
    line, = ax.plot(x, y, 'o')
    snap_cursor = SnappingCursor(ax, line)
    fig.canvas.mpl_connect('motion_notify_event', snap_cursor.on_mouse_move)

    # Simulate a mouse move to (0.5, 0.5), needed for online docs
    t = ax.transData
    MouseEvent(
        "motion_notify_event", ax.figure.canvas, *t.transform((0.5, 0.5))
    )._process()

    plt.show()



.. image-sg:: /gallery/event_handling/images/sphx_glr_cursor_demo_003.png
   :alt: Snapping cursor
   :srcset: /gallery/event_handling/images/sphx_glr_cursor_demo_003.png, /gallery/event_handling/images/sphx_glr_cursor_demo_003_2_00x.png 2.00x
   :class: sphx-glr-single-img






.. _sphx_glr_download_gallery_event_handling_cursor_demo.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: cursor_demo.ipynb <cursor_demo.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: cursor_demo.py <cursor_demo.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: cursor_demo.zip <cursor_demo.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
