fastplotlib · clewis7 · May 22, 2025 · May 20, 2025 · May 20, 2025 · May 20, 2025
@@ -0,0 +1,47 @@
+.. _api.Graphic:
+
+Graphic
+*******
+
+=======
+Graphic
+=======
+.. currentmodule:: fastplotlib
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: Graphic_api
+
+    Graphic
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: Graphic_api
+
+    Graphic.axes
+    Graphic.block_events
+    Graphic.deleted
+    Graphic.event_handlers
+    Graphic.name
+    Graphic.offset
+    Graphic.right_click_menu
+    Graphic.rotation
+    Graphic.supported_events
+    Graphic.visible
+    Graphic.world_object
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: Graphic_api
+
+    Graphic.add_axes
+    Graphic.add_event_handler
+    Graphic.clear_event_handlers
+    Graphic.remove_event_handler
+    Graphic.rotate
+    Graphic.share_property
+    Graphic.unshare_property
+
@@ -4,6 +4,7 @@ Graphics
 .. toctree::
     :maxdepth: 1
 
+    Graphic
     LineGraphic
     ScatterGraphic
     ImageGraphic

@@ -9,6 +9,7 @@ API Reference
     graphics/index
     graphic_features/index
     selectors/index
+    tools/index
     ui/index
     widgets/index
     fastplotlib

@@ -27,6 +27,8 @@ Properties
     Figure.names
     Figure.renderer
     Figure.shape
+    Figure.show_tooltips
+    Figure.tooltip_manager
 
 Methods
 ~~~~~~~

@@ -29,6 +29,8 @@ Properties
     ImguiFigure.names
     ImguiFigure.renderer
     ImguiFigure.shape
+    ImguiFigure.show_tooltips
+    ImguiFigure.tooltip_manager
 
 Methods
 ~~~~~~~

@@ -0,0 +1,53 @@
+.. _api.HistogramLUTTool:
+
+HistogramLUTTool
+****************
+
+================
+HistogramLUTTool
+================
+.. currentmodule:: fastplotlib
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: HistogramLUTTool_api
+
+    HistogramLUTTool
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: HistogramLUTTool_api
+
+    HistogramLUTTool.axes
+    HistogramLUTTool.block_events
+    HistogramLUTTool.cmap
+    HistogramLUTTool.deleted
+    HistogramLUTTool.event_handlers
+    HistogramLUTTool.image_graphic
+    HistogramLUTTool.name
+    HistogramLUTTool.offset
+    HistogramLUTTool.right_click_menu
+    HistogramLUTTool.rotation
+    HistogramLUTTool.supported_events
+    HistogramLUTTool.visible
+    HistogramLUTTool.vmax
+    HistogramLUTTool.vmin
+    HistogramLUTTool.world_object
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: HistogramLUTTool_api
+
+    HistogramLUTTool.add_axes
+    HistogramLUTTool.add_event_handler
+    HistogramLUTTool.clear_event_handlers
+    HistogramLUTTool.disconnect_image_graphic
+    HistogramLUTTool.remove_event_handler
+    HistogramLUTTool.rotate
+    HistogramLUTTool.set_data
+    HistogramLUTTool.share_property
+    HistogramLUTTool.unshare_property
+
@@ -0,0 +1,38 @@
+.. _api.Tooltip:
+
+Tooltip
+*******
+
+=======
+Tooltip
+=======
+.. currentmodule:: fastplotlib
+
+Constructor
+~~~~~~~~~~~
+.. autosummary::
+    :toctree: Tooltip_api
+
+    Tooltip
+
+Properties
+~~~~~~~~~~
+.. autosummary::
+    :toctree: Tooltip_api
+
+    Tooltip.background_color
+    Tooltip.font_size
+    Tooltip.outline_color
+    Tooltip.padding
+    Tooltip.text_color
+    Tooltip.world_object
+
+Methods
+~~~~~~~
+.. autosummary::
+    :toctree: Tooltip_api
+
+    Tooltip.register
+    Tooltip.unregister
+    Tooltip.unregister_all
+
@@ -0,0 +1,8 @@
+Tools
+*****
+
+.. toctree::
+    :maxdepth: 1
+
+    HistogramLUTTool
+    Tooltip
@@ -9,6 +9,7 @@
 from fastplotlib.layouts import Subplot
 from fastplotlib import graphics
 from fastplotlib.graphics import features, selectors
+from fastplotlib import tools
 from fastplotlib import widgets
 from fastplotlib import utils
 from fastplotlib import ui
@@ -21,6 +22,7 @@
 GRAPHICS_DIR = API_DIR.joinpath("graphics")
 GRAPHIC_FEATURES_DIR = API_DIR.joinpath("graphic_features")
 SELECTORS_DIR = API_DIR.joinpath("selectors")
+TOOLS_DIR = API_DIR.joinpath("tools")
 WIDGETS_DIR = API_DIR.joinpath("widgets")
 UI_DIR = API_DIR.joinpath("ui")
 GUIDE_DIR = current_dir.joinpath("user_guide")
@@ -31,6 +33,7 @@
     GRAPHICS_DIR,
     GRAPHIC_FEATURES_DIR,
     SELECTORS_DIR,
+    TOOLS_DIR,
     WIDGETS_DIR,
     UI_DIR,
 ]
@@ -264,7 +267,8 @@ def main():
         )
 
     # the rest of this is a mess and can be refactored later
-
+    ##############################################################################
+    # ** Graphic classes ** #
     graphic_classes = [getattr(graphics, g) for g in graphics.__all__]
 
     graphic_class_names = [g.__name__ for g in graphic_classes]
@@ -290,7 +294,7 @@ def main():
             source_path=GRAPHICS_DIR.joinpath(f"{graphic_cls.__name__}.rst"),
         )
     ##############################################################################
-
+    # ** GraphicFeature classes ** #
     feature_classes = [getattr(features, f) for f in features.__all__]
 
     feature_class_names = [f.__name__ for f in feature_classes]
@@ -315,7 +319,7 @@ def main():
             source_path=GRAPHIC_FEATURES_DIR.joinpath(f"{feature_cls.__name__}.rst"),
         )
     ##############################################################################
-
+    # ** Selector classes ** #
     selector_classes = [getattr(selectors, s) for s in selectors.__all__]
 
     selector_class_names = [s.__name__ for s in selector_classes]
@@ -339,8 +343,35 @@ def main():
             modules=["fastplotlib"],
             source_path=SELECTORS_DIR.joinpath(f"{selector_cls.__name__}.rst"),
         )
+
     ##############################################################################
+    # ** Tools classes ** #
+    tools_classes = [getattr(tools, t) for t in tools.__all__]
 
+    tools_class_names = [t.__name__ for t in tools_classes]
+
+    tools_class_names_str = "\n    ".join([""] + tools_class_names)
+
+    with open(TOOLS_DIR.joinpath("index.rst"), "w") as f:
+        f.write(
+            f"Tools\n"
+            f"*****\n"
+            f"\n"
+            f".. toctree::\n"
+            f"    :maxdepth: 1\n"
+            f"{tools_class_names_str}\n"
+        )
+
+    for tool_cls in tools_classes:
+        generate_page(
+            page_name=tool_cls.__name__,
+            classes=[tool_cls],
+            modules=["fastplotlib"],
+            source_path=TOOLS_DIR.joinpath(f"{tool_cls.__name__}.rst"),
+        )
+
+    ##############################################################################
+    # ** Widget classes ** #
     widget_classes = [getattr(widgets, w) for w in widgets.__all__]
 
     widget_class_names = [w.__name__ for w in widget_classes]
@@ -365,7 +396,7 @@ def main():
             source_path=WIDGETS_DIR.joinpath(f"{widget_cls.__name__}.rst"),
         )
     ##############################################################################
-
+    # ** UI classes ** #
     ui_classes = [ui.BaseGUI, ui.Window, ui.EdgeWindow, ui.Popup]
 
     ui_class_names = [cls.__name__ for cls in ui_classes]
@@ -410,6 +441,7 @@ def main():
             "    graphics/index\n"
             "    graphic_features/index\n"
             "    selectors/index\n"
+            "    tools/index\n"
             "    ui/index\n"
             "    widgets/index\n"
             "    fastplotlib\n"
@@ -438,6 +470,9 @@ def write_table(name, feature_cls):
         f.write("============\n\n")
 
         for graphic_cls in [*graphic_classes, *selector_classes]:
+            if graphic_cls is graphics.Graphic:
+                # skip Graphic base class
+                continue
             f.write(f"{graphic_cls.__name__}\n")
             f.write("-" * len(graphic_cls.__name__) + "\n\n")
             for name, type_ in graphic_cls._features.items():

@@ -19,7 +19,10 @@
 data = np.column_stack([xs, ys])
 multi_data = np.stack([data] * 10)
 
-figure = fpl.Figure(size=(700, 560))
+figure = fpl.Figure(
+    size=(700, 560),
+    show_tooltips=True
+)
 
 line_stack = figure[0, 0].add_line_stack(
     multi_data,  # shape: (10, 100, 2), i.e. [n_lines, n_points, xy]
@@ -28,6 +31,26 @@
     separation=1,  # spacing between lines along the separation axis, default separation along "y" axis
 )
 
+
+def tooltip_info(ev):
+    """A custom function to display the index of the graphic within the collection."""
+    index = ev.pick_info["vertex_index"]  # index of the line datapoint being hovered
+
+    # get index of the hovered line within the line stack
+    line_index = np.where(line_stack.graphics == ev.graphic)[0].item()
+    info = f"line index: {line_index}\n"
+
+    # append data value info
+    info += "\n".join(f"{dim}: {val}" for dim, val in zip("xyz", ev.graphic.data[index]))
+
+    # return str to display in tooltip
+    return info
+
+# register the line stack with the custom tooltip function
+figure.tooltip_manager.register(
+    line_stack, custom_info=tooltip_info
+)
+
 figure.show(maintain_aspect=False)
 
 

@@ -0,0 +1,54 @@
+"""
+Tooltips
+========
+
+Show tooltips on all graphics
+"""
+
+# test_example = false
+# sphinx_gallery_pygfx_docs = 'screenshot'
+
+import numpy as np
+import imageio.v3 as iio
+import fastplotlib as fpl
+
+
+# get some data
+scatter_data = np.random.rand(1_000, 3)
+
+xs = np.linspace(0, 2 * np.pi, 100)
+ys = np.sin(xs)
+
+gray = iio.imread("imageio:camera.png")
+rgb = iio.imread("imageio:astronaut.png")
+
+# create a figure
+figure = fpl.Figure(
+    cameras=["3d", "2d", "2d", "2d"],
+    controller_types=["orbit", "panzoom", "panzoom", "panzoom"],
+    size=(700, 560),
+    shape=(2, 2),
+    show_tooltips=True,  # tooltip will display data value info for all graphics
+)
+
+# create graphics
+scatter = figure[0, 0].add_scatter(scatter_data, sizes=3, colors="r")
+line = figure[0, 1].add_line(np.column_stack([xs, ys]))
+image = figure[1, 0].add_image(gray)
+image_rgb = figure[1, 1].add_image(rgb)
+
+
+figure.show()
+
+# to hide tooltips for all graphics in an existing Figure
+# figure.show_tooltips = False
+
+# to show tooltips for all graphics in an existing Figure
+# figure.show_tooltips = True
+
+
+# NOTE: `if __name__ == "__main__"` is NOT how to use fastplotlib interactively
+# please see our docs for using fastplotlib interactively in ipython and jupyter
+if __name__ == "__main__":
+    print(__doc__)
+    fpl.loop.run()