layer

Overlays multiple children in the same coordinate space without any layout offset.

from gofish import layer, rect, ellipse

layer([
    rect(w=100, h=80, fill="#9ecae1"),
    ellipse(w=60, h=60, fill="#fcae91"),
]).render(w=200, h=150)

Both shapes occupy the same space. The ellipse is drawn on top of the rectangle because it appears second in the list.

Signature

layer(children, **options) -> Mark

The children are a positional list of marks; layout options are passed as kwargs. Children typically carry .name(...) tags so they can be referenced from a .relate(...) callback or by a sibling relational mark like line / ref.

Parameters

Compose children on the same canvas at (0, 0) unless placed by constraints. Also accepts explicit box dims when given a self-scaling size.

Option	Type	Default	Description
key	str		Internal per-node key override.
coord	Any		Coordinate transform (polar(), clock(), wavy(), ...) the children are drawn in. Given one, the layer becomes that coordinate boundary.
axes	Any		Draw the coordinate axes of this layer's coord. Ignored on a layer with no coord.
transform	dict		Non-affine-foldable scale applied to the composed children.
box	bool		True renders this as a coordinate-space transparent "box" boundary rather than a plain layer.

Box dimensions

Option	Type	Default	Description
x	int | float | str		Left edge position.
cx	int | float | str		Center x.
x2	int | float | str		Right edge position.
w	int | float | str		Width.
em_x	bool		Embed x in the parent's x space.
y	int | float | str		Start edge on y: the top edge where y reads top-down, the bottom edge where it grows upward.
cy	int | float | str		Center y.
y2	int | float | str		Other y edge position.
h	int | float | str		Height.
em_y	bool		Embed y in the parent's y space.
dims	dict		Box dimensions by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}.

Z-ordering

By default, children are drawn in the order they appear in the list — later children appear on top. You can override this with .z_order(n) on any child. Children are sorted by z-order value before rendering; lower values are drawn first (underneath). Children with the same z-order value keep their original list order.

from gofish import layer, rect, ellipse

layer([
    ellipse(w=60, h=60, fill="#fcae91").z_order(1),  # forced on top
    rect(w=100, h=80, fill="#9ecae1").z_order(0),     # forced underneath
])

.z_order() is available on every Mark. The chart-composing form of layer (which overlays whole charts) exposes the same control on a ChartBuilder as .z_order().

Notes

• This is the low-level combinator-form layer, which wraps an explicit list of marks and renders directly. To overlay whole charts — for example to draw one chart's marks on top of another and relate them with cross-chart constraints — use the chart-composing form layer([chart1, chart2]), which composes ChartBuilder instances and accepts .relate(...).
• Naming a child (rect(...).name("a")) makes it addressable from a .relate(...) callback and from a sibling line or ribbon drawn over the same layer.