Overlays: Axis, Grid, etc.

Overlays are elements that decorate plots, like for example axes, legends, grids, etc.

Overlays are very similar to regular plot elements, and share most of their interface with plot renderers (both are subclasses of chaco.plot_component.PlotComponent).

In addition, they have a lightweight interface defined in chaco.abstract_overlay.AbstractOverlay: the additional features are that

  1. they keep a reference to the plot they are decorating in component;

  2. the background color bgcolor is ‘transparent’ by default;

  3. they plot on the ‘overlay’ layer by default.

Core Overlays

There are three important classes of overlays defined in Chaco: axes, legends, and grids.

Axes

The Chaco overlay representing a plot axis is defined in the class PlotAxis.

A new axis is created by passing a mapper, usually the mapper defined for the corresponding plot data coordinate. PlotAxis also defines a range of attributes to customize the appearance of labels, ticks, and other axis elements. For example, given an X-Y plot renderer, plot, we can define a new x-axis as:

AXIS_DEFAULTS = {
    'axis_line_weight': 2,
    'tick_weight': 2,
    'tick_label_font': 'modern 16',
    'title_font': 'modern 20',
}

x_axis = PlotAxis(
    orientation='bottom',
    title='My x axis',
    mapper=plot.x_mapper,
    component=plot,
    **AXIS_DEFAULTS,
)

The newly created axis can then be attached to the plot renderer by appending it to its underlays layer:

plot.underlays.append(x_axis)

Minor Axes Ticks

The Chaco overlay representing a minor plot axis is defined in the class MinorPlotAxis (a subclass of PlotAxis). This overlay adds minor tick marks to an axis.

A MinorPlotAxis should be added along with a PlotAxis. For example, minor axis tick marks can be added with:

x_major_axis = PlotAxis(
    orientation='bottom',
    title='My x axis',
    mapper=plot.x_mapper,
    component=plot,
)
plot.underlays.append(x_major_axis)

x_minor_axis = MinorPlotAxis(
    orientation='bottom',
    mapper=plot.x_mapper,
    component=plot,
)
plot.underlays.append(x_minor_axis)

Attributes

These attributes control the appearance of the axis:

title, title_font, title_color, title_spacing title_angle

Define the axis label. title is a string or unicode object that is rendered using the given font and color. title_font is a string describing a font (e.g. ‘12 pt bold italic’, ‘swiss family Arial’ or ‘default 12’; see TraitKivaFont for details). Finally, title_spacing is the space between the axis line and the title (either the number of pixels or ‘auto’, default) and title_angle can be overridden to change the rotation angle (in deg, wrt horizontal).

tick_weight, tick_color, tick_in, tick_out, tick_visible,

These attributes control the aspect of the ticks on the axis. If tick_visible is True, ticks are represented as lines of color tick_color (default is black) and thickness tick_weight (in pixels, default is 1). Each line extends into the plot area by tick_in pixels and into the label area by tick_out pixels (default is 5).

tick_label_font, tick_label_color, tick_label_rotate_angle, tick_label_alignment, tick_label_margin, tick_label_offset, tick_label_position,

These attributes allow to fine-tune the aspect of the tick labels: first of all, the font (e.g. ‘12 pt bold italic’) and color of the labels. The position and orientation of the label can be also be closely controlled: tick_label_rotate_angle give the rotation angle (only multiples of 90 degrees are supported); tick_label_alignment selects whether the corner (‘corner’) or center (‘edge’, default) of the label are aligned to the corresponding tick (‘corner’ is better for 45 degrees rotation); tick_label_margin and tick_label_offset control the margin around the tick labels, and their distance from the axis; finally, tick_label_position can be set to either ‘outside’ (default) or ‘inside’ depending on whether the labels should be displayed inside or outside the plot area.

tick_label_formatter

By default, tick labels are assumed to be floating point numbers, and are displayed as such after removing trailing zeros and the decimal dot if necessary (e.g., ‘10.000’ will be displayed as ‘10’, and ‘21.10’ as ‘21.1’). The default behavior can be changed by setting tick_label_formatter to a callable that takes the value of the tick label and returns a formatted string.

tick_interval, tick_generator,

Locations and distances of ticks are controlled by the attribute tick_generator

Default is chaco.ticks.auto_ticks or chaco.ticks.log_auto_ticks

Events

updated

Fired when the axis’s range bounds change.

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.