Plums-Microlib Legend painter

A legend is a visual explanation of the colors used on the visualisations. By visualisations, we mean one or several tiles with their respective painted annotations (records geometry with optionally confidence).

  • Content is contained in the legend to aid in the interpretation of the visualisations. For Plums purposes, the legend will map colors or color maps to some meaningful descriptors (exposed by the ColorEngine).

  • Design involves the overall appearance of the legend. As a rule of thumb, we have chosen to handle two modes of visualisation. First, descriptors that are categorical. They will be represented with a colored rectangle, whereas, continuous descriptors will appear as plain colormaps.

  • Placement is where the legend itself is located on the final composition. Some places are better than others. Keep in mind that the legend is not the main attraction, it is used to describe the main attraction. The size should only be large enough to be legible for the reader. The legend can either be placed horizontally or vertically.

The actual legend API is exposed here.

class plums.plot.engine.legend_painter.LegendItemDrawer(background_color, scale=1.0, margins=(15, 15))[source]

Bases: object

Class that draw legend items, depending on their types.

Items either be:

  • categorical: item would look like a colored box with the name of the category next to it.

  • nested categorical: a category name with several categorical items under it.

  • continuous: a color map with its range and, optionally, a descriptor name.

Parameters

  • background_color (tuple) – Legend background color (RGB or RGBA format).

  • scale (float) – Optional. Defaults to 1.0 Scale to use, regarding the default dimensions used.

  • margins (tuple) – Optional. Defaults to (15, 15). Margins around the item (left/right and top/bottom).

MODE = 'RGBA'
ITEM_BACKGROUND_COLOR = (255, 255, 255, 0)
BOX_DIMENSIONS = (80, 40)
BOX_OUTLINE_WIDTH = 1
SEPARATION_DISTANCE = 20
TEXT_SIZE = 20
OUTLINE_HEADER_MARGIN = 5
SUB_ITEMS_AXIS = 0
SUB_ITEM_SCALE = 0.7
SUB_ITEM_OFFSET = 20
COLOR_MAP_DIMENSIONS = (200, 50)
COLOR_MAP_MARGIN = 8
COLOR_MAP_TITLE_HEIGHT = 18
COLOR_MAP_TEXT_HEIGHT = 13
draw_simple_category(name, fill_color, scale=None, margins=None)[source]

Draw a simple category item: a colored box with a category name next to it.

Parameters

  • name (str) – Category name to draw.

  • fill_color (Color) – Color of the category.

  • scale (float) – Optional. Defaults to None Scale to use, regarding the default dimensions used.

  • margins (tuple) – Optional. Defaults to None. Margins around the item (left/right and top/bottom).

Returns

A simple categorical item.

Return type

Image

draw_composite_category(descriptor_name, category_name, color_engine_interface, max_category_height)[source]

Draw a nested category item: a category name with several categorical items under it.

Parameters

  • descriptor_name (str) – Name of the CategoricalDescriptor used.

  • category_name (str) – Name of the primary category.

  • color_engine_interface (dict) – Interface of the ColorEngine object. (key = category name, value = color/colormaps).

  • max_category_height (int) – Height of the item to not exceed, in pixels.

Returns

A nested categorical item.

Return type

Image

draw_outline_with_title(descriptor_name, legend_set_item, scale=None, margins=(0, 0, 0, 0))[source]

Draw a set of category item: a descriptor name with a border and several categorical items under it.

Parameters

  • descriptor_name (str) – Name of the CategoricalDescriptor used.

  • legend_set_item (Image) – A nested legend categorical set item.

  • scale (float) – Optional. Defaults to None Scale to use, regarding the default dimensions used.

  • margins (tuple) – Optional. Default to (0, 0, 0, 0). Optional margin in between legend item exterior and outline start coordinates

Returns

A nested categorical item.

Return type

Image

draw_colormap(descriptor_name, color_map, category_name=None)[source]

Draw a color map: a color map with its range and descriptor name (optional).

Parameters

  • descriptor_name (str) – The name of the descriptor.

  • color_map (ContinuousColorMap) – A ContinuousColorMap which vary the the color around a reference Color.

  • category_name (str) – Optional. Defaults to None. The name of the category.

Returns

The computed colormap item.

Return type

Image

class plums.plot.engine.legend_painter.LegendPainterBase(color_engine_interface, mosaic_size, scale=1.0, axis=0, background_color=(255, 255, 255), item_margins=(10, 10), main_axis_align='start', minor_axis_align='start', **kwargs)[source]

Bases: abc.ABC

An abstract base class that defines the interface a legend painter should implement.

Parameters

  • color_engine_interface (dict) – A mapping of categories with colors/colormaps to draw.

  • mosaic_size (tuple) – The size, in pixels, of the mosaic computed by the Compositor.

  • scale (float) – Optional. Defaults to 1.0. Scale to use, regarding the default dimensions used.

  • axis (int) – Optional. Defaults to 0. Main direction of the legend (0 = vertically, 1 = horizontally)

  • background_color (tuple) – Optional. Defaults to (255, 255, 255). Legend background color (RGB or RGBA format).

  • item_margins (tuple) – Optional. Defaults to (10, 10). Margins around the item (left/right and top/bottom).

  • main_axis_align (str) – Optional. Defaults to start. Alignment of the item in its cell along the main axis.

  • minor_axis_align (str) – Optional. Defaults to start. Alignment of the item in its cell along the minor axis.

abstract draw()[source]

Draw the legend, along the given axis.

The generated legend is a grid with each cell having the dimensions of the biggest item to draw. The grid is then filled along the main axis first. The size of the legend along the main axis is fixed while the size along the minor one is variable.

Returns

The output legend.

Return type

Image

class plums.plot.engine.legend_painter.LegendPainter(color_engine_interface, mosaic_size, scale=1.0, axis=0, background_color=(255, 255, 255), item_margins=(10, 10), main_axis_align='start', minor_axis_align='start', **kwargs)[source]

Bases: plums.plot.engine.legend_painter.LegendPainterBase

Class that draws a legend from a given color mapping.

The legend could be drawn either horizontally or vertically. Moreover, the item could occupy different positions in its cell.

Parameters

  • color_engine_interface (dict) – A mapping of categories with colors/colormaps to draw.

  • mosaic_size (tuple) – The size, in pixels, of the mosaic computed by the Compositor.

  • scale (float) – Optional. Defaults to 1.0. Scale to use, regarding the default dimensions used.

  • axis (int) – Optional. Defaults to 0. Main direction of the legend (0 = vertically, 1 = horizontally)

  • background_color (tuple) – Optional. Defaults to (255, 255, 255). Legend background color (RGB or RGBA format).

  • item_margins (tuple) – Optional. Defaults to (10, 10). Margins around the item (left/right and top/bottom).

  • main_axis_align (str) – Optional. Defaults to start. Alignment of the item in its cell along the main axis.

  • minor_axis_align (str) – Optional. Defaults to start. Alignment of the item in its cell along the minor axis.

draw()[source]

Draw the legend, along the given axis.

The generated legend is a grid with each cell having the dimensions of the biggest item to draw. The grid is then filled along the main axis first. The size of the legend along the main axis is fixed while the size along the minor one is variable.

Returns

The output legend.

Return type

Image