Skip to content

Bars, Band and Spans

There are several layers that is composed of faces and edges.

  • Bars ... a layer composed of bars.
  • Band ... a layer composed of a band region (fill-between region).
  • Spans ... a layer composed of infinitely long spans.

These layers have two namespaces: face and edge. face has following properties:

  • color ... color of the faces. Any color-like object is accepted.
  • hatch ... hatch pattern of the faces. Should be one of "", "-", "|, "+", "/", "\\", "x" or ".".

Note

hatch is not supported in some backends.

edge has following properties:

  • color ... color of the lines. Any color-like object is accepted.
  • width ... width of the lines. Should be a non-negative number.
  • style ... style of the lines. Should be one of "-", ":", "-.", "--".

Note

style is not supported in some backends.

Methods for adding these layers always configure the face properties with the arguments. You can use the with_edge method of the output layer to set edge properties. This separation is very helpful to prevent the confusion of the arguments, especially the colors.

Following example uses add_bars and add_spans methods to create Bars and Spans layers.

import numpy as np
from whitecanvas import new_canvas

canvas = new_canvas("matplotlib")

bars_layer = (
    canvas
    .add_bars([0, 1, 2, 3], [3, 4, 1, 2], color="yellow")
    .with_edge(color="black")
)

spans_layer = (
    canvas
    .add_spans([[0.2, 0.8], [1.4, 2.1], [1.8, 3.0]], color="blue")
    .with_edge(color="black")
)
canvas.y.lim = (0, 5)
canvas.show()

All the properties can be set via properties of face and edge, or the update method.

#!skip
bars_layer.face.color = "yellow"
bars_layer.face.hatch = "x"

spans_layer.edge.color = "black"
spans_layer.edge.width = 2
spans_layer.edge.style = "--"

# use `update`
bars_layer.face.update(color="yellow", hatch="x")
spans_layer.edge.update(color="black", width=2, style="--")

Multi-face and Multi-edge

As for Markers, Bars and Spans supports multi-face and multi-edge.

import numpy as np
from whitecanvas import new_canvas

canvas = new_canvas("matplotlib")

layer = (
    canvas
    .add_bars([0, 1, 2, 3], [3, 4, 1, 2])
    .with_face_multi(color=["red", "#00FF00", "rgb(0, 0, 255)", "black"])
)
canvas.show()

After calling with_face_multi, the layer face property will return arrays instead of scalar values.

layer.face.color  # (N, 4) array of RGBA colors
layer.face.hatch  # (N,) array of hatchs
layer.face.alpha # (N,) array of alpha values