`cotengra.schematic`¶

Draw psuedo-3D diagrams using matplotlib.

Module Contents¶

Classes¶

Drawing

Draw 2D or pseudo-3D diagrams using matplotlib. This handles the

Functions¶

`parse_style_preset`(presets, preset, **kwargs)	Parse a one or more style presets plus manual kwargs.
`axonometric_project`(i, j, k[, a, b, xscale, yscale, ...])	Project the 3D location `(i, j, k)` onto the 2D plane, using
`coo_to_zorder`(i, j, k[, xscale, yscale, zscale])	Given the coordinates of a point in 3D space, return a z-order value
`get_wong_color`(which[, alpha, hue_factor, sat_factor, ...])	Get a color by name, optionally modifying its alpha, hue, saturation
`mod_sat`(c[, mod, alpha])	Modify the luminosity of color `c`, optionally set the `alpha`
`auto_colors`(nc[, alpha, default_sequence])	Generate a nice sequence of `nc` colors. By default this uses an
`darken_color`(color[, factor])	Take `color` and darken it by `factor`.
`average_color`(colors)	Take a sequence of colors and return the RMS average in RGB space.
`jitter_color`(color[, factor])	Take `color` and add a random offset to each of its components.
`set_coloring_seed`(seed)	Set the seed for the random color generator.
`hash_to_nvalues`(s, nval[, seed])	Hash the string `s` to `nval` different floats in the range [0, 1].
`hash_to_color`(s[, hmin, hmax, smin, smax, vmin, vmax])	Generate a random color for a string `s`.
`mean`(xs)	Get the mean of a list of numbers.
`distance`(pa, pb)	Get the distance between two points, in arbtirary dimensions.
`get_angle`(pa, pb)	Get the angle between the line from p1 to p2 and the x-axis.
`get_rotator_and_inverse`(pa, pb)	Get a rotation matrix that rotates points by theta radians about
`get_control_points`(pa, pb, pc[, spacing])	Get two points that can be used to construct a bezier curve that
`gen_points_around`(coo[, radius, resolution])	Generate points around a circle.

Attributes¶

`_COLORS_DEFAULT`
`_COLORS_SORTED`
`COLORING_SEED`

class cotengra.schematic.Drawing(background=(0, 0, 0, 0), drawcolor=(0.14, 0.15, 0.16, 1.0), shapecolor=(0.45, 0.5, 0.55, 1.0), a=50, b=12, xscale=1, yscale=1, zscale=1, presets=None, ax=None, **kwargs)¶

Draw 2D or pseudo-3D diagrams using matplotlib. This handles the axonometric projection and the z-ordering of the elements, as well as named preset styles for repeated elements, and the automatic adjustment of the figure limits. It also has basic support for drawing smooth curves and shaded areas around certain elements automatically.

Parameters:

background (color, optional) – The background color of the figure, defaults to transparent.
drawcolor (color, optional) – The default color to draw lines and text in.
shapecolor (color, optional) – The default color to fill shapes with.
a (float) – The axonometric angle of the x-axis in degrees.
b (float) – The axonometric angle of the y-axis in degrees.
xscale (float) – A factor to scale the x-axis by.
yscale (float) – A factor to scale the y-axis by.
zscale (float) – A factor to scale the z-axis by.
presets (dict) – A dictionary of named style presets. When you add an element to the drawing, you can specify a preset name to use as default styling.
ax (matplotlib.axes.Axes) – The axes to draw on. If None, a new figure is created.
kwargs – Passed to plt.figure if ax is None.

_adjust_lims(x, y)¶

text(coo, text, preset=None, **kwargs)¶

Place text at the specified coordinate.

Parameters:

coo (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinate of the text. If 3D, the coordinate will be projected onto the 2D plane, and a z-order will be assigned.
text (str) – The text to place.
preset (str, optional) – A preset style to use for the text.
kwargs – Specific style options passed to matplotlib.axes.Axes.text.

text_between(cooa, coob, text, preset=None, **kwargs)¶

Place text between two coordinates.

Parameters:

cooa (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinates of the text endpoints. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
coob (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinates of the text endpoints. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
text (str) – The text to place.
center (float, optional) – The position of the text along the line, where 0.0 is the start and 1.0 is the end. Default is 0.5.
preset (str, optional) – A preset style to use for the text.
kwargs – Specific style options passed to matplotlib.axes.Axes.text.

label_ax(x, y, text, preset=None, **kwargs)¶

Place text at the specified location, using the axis coordinates rather than 2D or 3D data coordinates.

Parameters:

x (float) – The x and y positions of the text, relative to the axis.
y (float) – The x and y positions of the text, relative to the axis.
text (str) – The text to place.
preset (str, optional) – A preset style to use for the text.
kwargs – Specific style options passed to matplotlib.axes.Axes.text.

label_fig(x, y, text, preset=None, **kwargs)¶

Place text at the specified location, using the figure coordinates rather than 2D or 3D data coordinates.

Parameters:

x (float) – The x and y positions of the text, relative to the figure.
y (float) – The x and y positions of the text, relative to the figure.
text (str) – The text to place.
preset (str, optional) – A preset style to use for the text.
kwargs – Specific style options passed to matplotlib.axes.Axes.text.

_parse_style_for_marker(coo, preset=None, **kwargs)¶

_adjust_lims_for_marker(x, y, r)¶

circle(coo, preset=None, **kwargs)¶

Draw a circle at the specified coordinate.

Parameters:

coo (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinate of the circle. If 3D, the coordinate will be projected onto the 2D plane, and a z-order will be assigned.
preset (str, optional) – A preset style to use for the circle.
kwargs – Specific style options passed to matplotlib.patches.Circle.

wedge(coo, theta1, theta2, preset=None, **kwargs)¶

Draw a wedge at the specified coordinate.

Parameters:

coo (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinate of the wedge. If 3D, the coordinate will be projected onto the 2D plane, and a z-order will be assigned.
theta1 (float) – The angle in degrees of the first edge of the wedge.
theta2 (float) – The angle in degrees of the second edge of the wedge.
preset (str, optional) – A preset style to use for the wedge.
kwargs – Specific style options passed to matplotlib.patches.Wedge.

dot(coo, preset=None, **kwargs)¶

Draw a small circle with no border. Alias for circle with defaults radius=0.1 and linewidth=0.0.

Parameters:

coo (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinate of the dot. If 3D, the coordinate will be projected onto the 2D plane, and a z-order will be assigned.
preset (str, optional) – A preset style to use for the dot.
kwargs – Specific style options passed to matplotlib.patches.Circle.

regular_polygon(coo, preset=None, **kwargs)¶

Draw a regular polygon at the specified coordinate.

Parameters:

coo (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinate of the polygon. If 3D, the coordinate will be projected onto the 2D plane, and a z-order will be assigned.
n (int) – The number of sides of the polygon.
orientation (float, optional) – The orientation of the polygon in radians. Default is 0.0.
preset (str, optional) – A preset style to use for the polygon.
kwargs – Specific style options passed to matplotlib.patches.Polygon.

marker(coo, preset=None, **kwargs)¶

Draw a ‘marker’ at the specified coordinate. This is a shorthand for creating polygons with shape specified by a single character.

Parameters:

coo (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinate of the marker. If 3D, the coordinate will be projected onto the 2D plane, and a z-order will be assigned.
marker (str, optional) – The marker shape to draw. One of "o.v^<>sDphH8".
preset (str, optional) – A preset style to use for the marker.
kwargs – Specific style options.

cube(coo, preset=None, **kwargs)¶

Draw a cube at the specified coordinate, which must be 3D.

Parameters:

coo (tuple[int, int, int]) – The 3D coordinate of the cube. The coordinate will be projected onto the 2D plane, and a z-order will be assigned.
preset (str, optional) – A preset style to use for the cube.
kwargs – Specific style options passed to matplotlib.patches.Polygon.

line(cooa, coob, preset=None, **kwargs)¶

Draw a line between two coordinates.

Parameters:

cooa (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinates of the line endpoints. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
coob (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinates of the line endpoints. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
stretch (float) – Stretch the line by this factor. 1.0 is no stretch, 0.5 is half length, 2.0 is double length. Default is 1.0.
arrowhead (bool or dict, optional) – Draw an arrowhead at the end of the line. Default is False. If a dict, it is passed as keyword arguments to the arrowhead method.
text_between (str, optional) – Add text along the line.
preset (str, optional) – A preset style to use for the line.
kwargs – Specific style options passed to matplotlib.lines.Line2D.

See also

Drawing.arrowhead

line_offset(cooa, coob, offset, midlength=0.5, relative=True, preset=None, **kwargs)¶

Draw a line between two coordinates, but curving out by a given offset perpendicular to the line.

Parameters:

cooa (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinates of the line endpoints. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
coob (tuple[int, int] or tuple[int, int, int]) – The 2D or 3D coordinates of the line endpoints. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
offset (float) – The offset of the curve from the line, as a fraction of the total line length. This is always processed in the 2D projected plane.
midlength (float) – The length of the middle straight section, as a fraction of the total line length. Default is 0.5.
arrowhead (bool or dict, optional) – Draw an arrowhead at the end of the line. Default is False. If a dict, it is passed as keyword arguments to the arrowhead method.
text_between (str, optional) – Add text along the line.
relative (bool, optional) – If True (the default), then offset is taken as a fraction of the line length, else in absolute units.
preset (str, optional) – A preset style to use for the line.
kwargs – Specific style options passed to curve.

arrowhead(cooa, coob, preset=None, **kwargs)¶

Draw just a arrowhead on the line between cooa and coob.

Parameters:

cooa (tuple[int, int] or tuple[int, int, int]) – The coordinates of the start and end of the line. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
coob (tuple[int, int] or tuple[int, int, int]) – The coordinates of the start and end of the line. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
reverse (bool or "both", optional) – Reverse the direction by switching cooa and coob. If "both", draw an arrowhead in both directions. Default is False.
center (float, optional) – The position of the arrowhead along the line, where 0 is the start and 1 is the end. Default is 0.5.
width (float, optional) – The width of the arrowhead. Default is 0.05.
length (float, optional) – The length of the arrowhead. Default is 0.1.
preset (str, optional) – A preset style to use for the arrowhead, including the above options.
kwargs – Specific style options passed to matplotlib.lines.Line2D.

curve(coos, preset=None, **kwargs)¶

Draw a smooth line through the given coordinates.

Parameters:

coos (Sequence[tuple[int, int]] or Sequence[tuple[int, int, int]]) – The 2D or 3D coordinates of the line. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
smoothing (float, optional) – The amount of smoothing to apply to the curve. 0.0 is no smoothing, 1.0 is maximum smoothing. Default is 0.5.
preset (str, optional) – A preset style to use for the curve.
kwargs – Specific style options passed to matplotlib.lines.Line2D.

shape(coos, preset=None, **kwargs)¶

Draw a closed shape with (sharp) corners at the given coordinates.

Parameters:

coos (sequence of coordinates) – The coordinates of the corners’ of the shape.
preset (str, optional) – A preset style to use for the shape.
kwargs – Specific style options passed to matplotlib.patches.PathPatch.

See also

Drawing.patch

patch(coos, preset=None, **kwargs)¶

Draw a closed smooth patch through given coordinates.

Parameters:

coos (sequence of coordinates) – The coordinates of the ‘corners’ of the patch, the outline is guaranteed to pass through these points.
smoothing (float) – The smoothing factor, the higher the smoother. The default is 0.5.
preset (str, optional) – A preset style to use for the patch.
kwargs – Specific style options passed to matplotlib.patches.PathPatch.

See also

Drawing.shape, Drawing.curve

patch_around(coos, radius=0.0, resolution=12, preset=None, **kwargs)¶

Draw a patch around the given coordinates, by contructing a convex hull around the points, optionally including an extra uniform or per coordinate radius.

Parameters:

coos (sequence[tuple[int, int]] or sequence[tuple[int, int, int]]) – The coordinates of the points to draw the patch around. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on min z-order of the endpoints.
radius (float or sequence[float], optional) – The radius of the patch around each point. If a sequence, must be the same length as coos. Default is 0.0.
resolution (int, optional) – The number of points to use pad around each point. Default is 12.
preset (str, optional) – A preset style to use for the patch.
kwargs – Specific style options passed to matplotlib.patches.PathPatch.

patch_around_circles(cooa, ra, coob, rb, padding=0.2, pinch=True, preset=None, **kwargs)¶

Draw a smooth patch around two circles.

Parameters:

cooa (tuple[int, int] or tuple[int, int, int]) – The coordinates of the center of the first circle. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
ra (int) – The radius of the first circle.
coob (tuple[int, int] or tuple[int, int, int]) – The coordinates of the center of the second circle. If 3D, the coordinates will be projected onto the 2D plane, and a z-order will be assigned based on average z-order of the endpoints.
rb (int) – The radius of the second circle.
padding (float, optional) – The amount of padding to add around the circles. Default is 0.2.
pinch (bool or float, optional) – If or how much to pinch the patch in between the circles. Default is to match the padding.
preset (str, optional) – A preset style to use for the patch.
kwargs – Specific style options passed to matplotlib.patches.PathPatch.

See also

Drawing.patch

cotengra.schematic.parse_style_preset(presets, preset, **kwargs)¶

Parse a one or more style presets plus manual kwargs.

Parameters:

presets (dict) – The dictionary of presets.
preset (str or sequence of str) – The name of the preset(s) to use. If multiple, later presets take precedence.
kwargs – Any additional manual keyword arguments are added to the style and override the presets.

Returns:

style

Return type:

dict

cotengra.schematic.axonometric_project(i, j, k, a=50, b=12, xscale=1, yscale=1, zscale=1)¶

Project the 3D location (i, j, k) onto the 2D plane, using the axonometric projection with the given angles a and b.

The xscale, yscale and zscale parameters can be used to scale the axes, including flipping them.

Parameters:

i (float) – The 3D coordinates of the point to project.
j (float) – The 3D coordinates of the point to project.
k (float) – The 3D coordinates of the point to project.
a (float) – The left and right angles to displace x and y axes, from horizontal, in degrees.
b (float) – The left and right angles to displace x and y axes, from horizontal, in degrees.
xscale (float) – The scaling factor for the x, y and z axes. If negative, the axis is flipped.
yscale (float) – The scaling factor for the x, y and z axes. If negative, the axis is flipped.
zscale (float) – The scaling factor for the x, y and z axes. If negative, the axis is flipped.

Returns:

x, y – The 2D coordinates of the projected point.

Return type:

float

cotengra.schematic.coo_to_zorder(i, j, k, xscale=1, yscale=1, zscale=1)¶: Given the coordinates of a point in 3D space, return a z-order value that can be used to draw it on top of other elements in the diagram. Take into account the scaling of the axes, so that the z-ordering is correct even if the axes flipped.

cotengra.schematic._COLORS_DEFAULT¶

cotengra.schematic.get_wong_color(which, alpha=None, hue_factor=0.0, sat_factor=1.0, val_factor=1.0)¶

Get a color by name, optionally modifying its alpha, hue, saturation or value.

These colorblind friendly colors were ppularized in an article by Wong (https://www.nature.com/articles/nmeth.1618) but originally come from Okabe & Ito (https://jfly.uni-koeln.de/color/).

Parameters:

which ({'blue', 'orange', 'green', 'red', 'yellow', 'pink', 'bluedark'}) – The name of the color to get.
alpha (float, optional) – The alpha channel value to set for the color. Default is 1.0.
hue_factor (float, optional) – The amount to shift the hue of the color. Default is 0.0.
sat_factor (float, optional) – The amount to scale the saturation of the color. Default is 1.0.
val_factor (float, optional) – The amount to scale the value of the color. Default is 1.0.

Returns:

color – The RGBA color as a tuple of floats.

Return type:

tuple[float, float, float, float]

cotengra.schematic._COLORS_SORTED¶

cotengra.schematic.mod_sat(c, mod=None, alpha=None)¶: Modify the luminosity of color c, optionally set the alpha channel, and return the final color as a RGBA tuple.

cotengra.schematic.auto_colors(nc, alpha=None, default_sequence=False)¶

Generate a nice sequence of nc colors. By default this uses an interpolation between the colorblind friendly colors of Okabe & Ito in hue sorted order, with luminosity moderated by a sine function to increase local distinguishability.

Parameters:

nc (int) – The number of colors to generate.
alpha (float, optional) – The alpha channel value to set for all colors. Default is 1.0.
default_sequence (bool, optional) – If True, take from the default sequence of 7 colors, un-sorted and un-modulated.

Returns:

colors

Return type:

list[tuple[float, float, float, float]]

cotengra.schematic.darken_color(color, factor=2 / 3)¶: Take color and darken it by factor.

cotengra.schematic.average_color(colors)¶: Take a sequence of colors and return the RMS average in RGB space.

cotengra.schematic.jitter_color(color, factor=0.05)¶: Take color and add a random offset to each of its components.

cotengra.schematic.COLORING_SEED = 8¶

cotengra.schematic.set_coloring_seed(seed)¶

Set the seed for the random color generator.

Parameters:: seed (int) – The seed to use.

cotengra.schematic.hash_to_nvalues(s, nval, seed=None)¶: Hash the string s to nval different floats in the range [0, 1].

cotengra.schematic.hash_to_color(s, hmin=0.0, hmax=1.0, smin=0.3, smax=0.8, vmin=0.8, vmax=0.9)¶

Generate a random color for a string s.

Parameters:

s (str) – The string to generate a color for.
hmin (float, optional) – The minimum hue value.
hmax (float, optional) – The maximum hue value.
smin (float, optional) – The minimum saturation value.
smax (float, optional) – The maximum saturation value.
vmin (float, optional) – The minimum value value.
vmax (float, optional) – The maximum value value.

Returns:

color – A tuple of floats in the range [0, 1] representing the RGB color.

Return type:

tuple

cotengra.schematic.mean(xs)¶: Get the mean of a list of numbers.

cotengra.schematic.distance(pa, pb)¶: Get the distance between two points, in arbtirary dimensions.

cotengra.schematic.get_angle(pa, pb)¶: Get the angle between the line from p1 to p2 and the x-axis.

cotengra.schematic.get_rotator_and_inverse(pa, pb)¶: Get a rotation matrix that rotates points by theta radians about the origin and then translates them by offset.

cotengra.schematic.get_control_points(pa, pb, pc, spacing=1 / 3)¶: Get two points that can be used to construct a bezier curve that passes smoothly through the angle pa, pb, pc.

cotengra.schematic.gen_points_around(coo, radius=1, resolution=12)¶: Generate points around a circle.

cotengra.schematic¶

Module Contents¶

Classes¶

Functions¶

Attributes¶

`cotengra.schematic`¶