Tools and Overlays

Overview

Chaco, Enable, and Event Dispatch

A Basic Tool

A Basic Overlay

Interaction Tools

PanTool

ZoomTool

RectZoom

DragZoom

LegendTool

DataLabelTool

MoveTool

Inspector-type Tools

DataPrinter

LineInspector

ScatterInspector

CursorTool

HighlightTool

ImageInspectorTool

The chaco.tools.api.ImageInspectorTool is designed to work with an chaco.api.ImagePlot renderer to display the data space coordinates and data value of the displayed 2D array. The tool is designed to be used in conjunction with the chaco.overlays.api.ImageInspectorOverlay: the tool collects mouse position and data values and triggers Event emissions, and the overlay catches these events and displays the data as an overlay.

To use it, as for other tools, you need to:

  1. create a tool object and append it to the renderer’s list of tools,

  2. create an overlay object and append it to the renderer’s list of overlays.

For example, a method to build a chaco.api.Plot object with that tool could look like:

def build_plot(self, img):
    plot = Plot(data=ArrayPlotData(img=img))
    # Capture the renderer object to pass it to the tool
    img_plot = plot.img_plot("img")[0]
    # Tool code to be added here...
    return plot

Note that unlike other ImagePlot examples, the renderer returned by the chaco.api.Plot.img_plot() call is captured since the tool will need it. The tool code to be inserted would look something like this:

imgtool = ImageInspectorTool(component=img_plot)
img_plot.tools.append(imgtool)
overlay = ImageInspectorOverlay(component=img_plot, image_inspector=imgtool,
                                bgcolor="white", border_visible=True)

img_plot.overlays.append(overlay)

Note the two important connections that are made for the tool/overlay to work correctly. The first one is that the component that is passed is the Chaco renderer rather than the Plot object, since it has access to the data being displayed. The second connection is that, for the overlay to update when the tool catches a mouse event, it needs to be provided the tool instance as its image_inspector attribute.

In addition to the background color and border_visible, other interesting overlay attributes to consider overriding include tooltip_mode to control the location of the text box and all of the chaco.overlays.api.TextBoxOverlay attributes (see below).

Finally, the overlay’s _build_text_from_event() method can be overwritten to customize the actual text content. The method should receive a single argument, the event data (dictionary), and return the desired text to display. The event data contains 3 keys: indices with the 2D coordinates of the mouse in data space, color_value containing the color of the tile where the mouse is, and data_value with the scalar value being displayed in that tile.

For a complete example, see examples/demo/basic/image_inspector.py.

TraitsTool

Selection Tools

RangeSelection

LassoSelection

SelectTool

Drawing Tools

DrawPointsTool

LineSegmentTool

Core Overlays

Axis

Grid

Legend

Annotation Overlays

PointMarker

DataBox

TextBoxOverlay

The chaco.overlays.api.TextBoxOverlay is the base class of the overlay component of several inspector type tools (see above). It is designed to draw a text box over the plots to display custom information.

The rendering of the text can be customized with the following attributes:

  • bgcolor and border_visible to control the styling of the box,

  • alpha to control the transparency of the text box,

  • text_color and font to control how the text looks like,

  • align to control what corner of the plot the text box should appear,

Note

The overlay can also be used directly by any custom tool that needs to display information upon an event. It should be done by subclassing the overlay and defining a listener on the inspector’s state which will modify the overlay’s text (and optionally visibility) attribute(s). After a text update, the component’s request_redraw() should be called. Good examples include chaco.overlays.api.ImageInspectorOverlay.

ToolTip

PlotLabel