robodraw.schematic¶

Draw 2D and pseudo-3D diagrams programmatically using matplotlib.

Attributes¶

`_PROJECTION_DEFAULTS`
`_COLORS_DEFAULT`
`get_wong_color`
`_COLORS_SORTED`
`COLORING_SEED`

Classes¶

Drawing

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

Functions¶

`_readable_angle`(angle)	Normalize an angle to (-90, 90] so text reads right-way-up.
`parse_projection`(projection)	Parse a projection specification into a normalized tuple of
`parse_style_preset`(presets, preset, **kwargs)	Parse a one or more style presets plus manual kwargs.
`simple_scale`(i, j[, xscale, yscale])
`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[, a, b, xscale, yscale, zscale])	Given the coordinates of a point in 3D space, return a z-order value
`orthographic_project`(i, j, k[, azimuth, elevation, ...])	Project the 3D location `(i, j, k)` onto the 2D plane using an
`orthographic_zorder`(i, j, k[, azimuth, elevation, ...])	Compute z-order (depth) for orthographic projection by projecting
`get_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_rotator_and_inverse_3d`(pa, pb)	Get forward and inverse functions that translate `pa` to the
`shorten_line`(pa, pb, amount)
`get_control_points`(pa, pb, pc[, spacing])	Get two points that can be used to construct a bezier curve that
`convex_hull_2d`(points)	Compute the convex hull of a set of 2D points using Andrew's monotone
`gen_points_around`(coo[, radius, resolution])	Generate points around a circle.

Module Contents¶

robodraw.schematic._PROJECTION_DEFAULTS¶

robodraw.schematic._readable_angle(angle)[source]¶

Normalize an angle to (-90, 90] so text reads right-way-up.

Returns:

normalized (float) – The angle in (-90, 90].
flipped (bool) – Whether the angle was flipped by 180 degrees.

robodraw.schematic.parse_projection(projection)[source]¶

Parse a projection specification into a normalized tuple of (mode, arg1, arg2).

Parameters:

projection (str or tuple) –

The projection specification. Can be:

A 3-tuple (mode, arg1, arg2) specifying the projection mode and its parameters explicitly, e.g. ("orthographic", 20, 40) or ("axonometric", 50, 12).
A 2-tuple (arg1, arg2) which defaults to orthographic, e.g. (20, 40) is equivalent to ("orthographic", 20, 40).
A string "orthographic" or "axonometric" which uses the default parameters for that mode.

Returns:

A 3-tuple of (mode, arg1, arg2).

Return type:

tuple

class robodraw.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), projection=('orthographic', 20, 40), xscale=1, yscale=1, zscale=1, presets=None, ax=None, adjust_lims='auto', **kwargs)[source]¶

Draw 2D or pseudo-3D diagrams using matplotlib. This handles the 3D 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.
projection (tuple, optional) –
The 3D projection mode and parameters, specified as a tuple of (mode, *args). Available modes:
- ("orthographic", azimuth, elevation) : Orthographic projection (camera at infinity). azimuth is the horizontal camera angle in degrees (0 means looking along +y, i.e. the y-axis extends into the page). elevation is the vertical angle above the horizontal (0 is side-on, 90 is top-down). ("orthographic", 0, 90) gives an exact top-down view.
- ("axonometric", a, b) : Axonometric projection where a and b are the angles of the x and y axes measured counterclockwise from horizontal, in degrees. True isometric projection is ("axonometric", 30, 150), which you can also specify with the string "isometric".
Default is ("orthographic", 20, 40).
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[str, dict], optional) – 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. If an external ax is supplied, then note that this Drawing instance will not automatically adjust the limits of the axes as elements are added.
adjust_lims (bool or "auto", optional) – Whether to automatically adjust the axes limits as elements are added. If “auto” (the default), then this is True if ax is None, else False, i.e. only adjust limits if we own the figure.
kwargs – Passed to plt.figure if ax is None.

adjust_lims = 'auto'¶

drawcolor = (0.14, 0.15, 0.16, 1.0)¶

shapecolor = (0.45, 0.5, 0.55, 1.0)¶

_xmin = None¶

_xmax = None¶

_ymin = None¶

_ymax = None¶

presets¶

_project_xscale = 1¶

_project_yscale = 1¶

_project_zscale = 1¶

_projection¶

_3d_xmin = None¶

_3d_xmax = None¶

_3d_ymin = None¶

_3d_ymax = None¶

_3d_zmin = None¶

_3d_zmax = None¶

_offset = (0, 0, 0)¶

_screen_offset = (0, 0)¶

_axis_angle(axis)[source]¶: Get the screen rotation angle (in degrees) of a 3D axis.

_2d_project(x, y)[source]¶

_3d_project(x, y, z)[source]¶

_coo_to_zorder(x, y, z)[source]¶

translate(dx=0, dy=0, dz=0)[source]¶

Context manager to temporarily translate all draw operations, in coordinate space (i.e. before any projection and scaling).

Parameters:

dx (float) – The x offset.
dy (float) – The y offset.
dz (float) – The z offset (only relevant for 3D coordinates).

Examples

>>> d = Drawing()
>>> with d.translate(10, 5):
...     d.circle((0, 0))  # drawn at (10, 5)

translate_screen(dx=0, dy=0)[source]¶

Context manager to temporarily translate all draw operations in 2D screen space (i.e. after any projection and scaling).

Parameters:

dx (float) – The x screen offset.
dy (float) – The y screen offset.

Examples

>>> d = Drawing()
>>> with d.translate_screen(10, 5):
...     d.circle((0, 0, 0))  # 3D projected, then shifted

_project_coos(coos, style, zorder_delta=0.0, zorder_aggregate='mean', project=True)[source]¶: Possibly project sequence of coordinates and inject zorder.

_adjust_lims(x, y)[source]¶

text(coo, text, preset=None, **kwargs)[source]¶

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)[source]¶

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.
shorten (float or tuple[float, float], optional) – Shorten the implicit line by this absolute amount at each end. If a tuple, the first value is the start shortening, the second the end shortening.
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)[source]¶

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)[source]¶

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.

_project_and_parse_style_for_marker(coo, preset=None, project=True, **kwargs)[source]¶

_adjust_lims_for_marker(x, y, r)[source]¶

circle(coo, preset=None, **kwargs)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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.

star(coo, preset=None, **kwargs)[source]¶

cross(coo, preset=None, **kwargs)[source]¶

marker(coo, preset=None, **kwargs)[source]¶

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.

square(coo, preset=None, **kwargs)[source]¶: Draw a square of ‘radius’ radius at the specified coordinate. This is a shorthand for Drawing.marker with marker=’s’.

cube(coo, preset=None, **kwargs)[source]¶

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.

tetrahedron(coo, preset=None, **kwargs)[source]¶

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

Parameters:

coo (tuple[int, int, int]) – The 3D coordinate of the tetrahedron. 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 tetrahedron.
kwargs – Specific style options passed to matplotlib.patches.Polygon.

octahedron(coo, preset=None, **kwargs)[source]¶

Draw an octahedron at the specified coordinate, which must be 3D.

Parameters:

coo (tuple[int, int, int]) – The 3D coordinate of the octahedron. 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 octahedron.
kwargs – Specific style options passed to matplotlib.patches.Polygon.

dodecahedron(coo, preset=None, **kwargs)[source]¶

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

Parameters:

coo (tuple[int, int, int]) – The 3D coordinate of the dodecahedron. 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 dodecahedron.
kwargs – Specific style options passed to matplotlib.patches.Polygon.

icosahedron(coo, preset=None, **kwargs)[source]¶

Draw an icosahedron at the specified coordinate, which must be 3D.

Parameters:

coo (tuple[int, int, int]) – The 3D coordinate of the icosahedron. 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 icosahedron.
kwargs – Specific style options passed to matplotlib.patches.Polygon.

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

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.
shorten (float or tuple[float, float], optional) – Shorten the line by this absolute amount at each end. If a tuple, the first value is the start shortening, the second the end shortening.
stretch (float) – Stretch the line by this relative 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, Drawing.curve

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

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.

zigzag(cooa, coob, preset=None, **kwargs)[source]¶

Draw a zig-zagging line between two coordinates.

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.
width (float, optional) – The width of the zig-zagging. Default is to aim for 8 zig-zags.
extend (float, optional) – Only start zig-zagging after this distance from the end-points.
density (float, optional) – The density of the zig-zags, where 1.0 is the default density resulting in approximately 8 zig-zags along the line.
shorten (float or tuple[float, float], optional) – Shorten the zigzag by this absolute amount at each end. If a tuple, the first value is the start shortening, the second the end shortening.
preset (str, optional) – A preset style to use for the line.
kwargs – Specific style options passed to Drawing.curve.

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

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.
relative (bool or float, optional) – If True, the the width and length parameters are scaled as total_line_length ** relative.
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)[source]¶

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.
shorten (float or tuple[float, float], optional) – Shorten the line by this absolute amount at each end. If a tuple, the first value is the start shortening, the second the end shortening. The shortening is calculated with respect to the first and last segments of the curve.
preset (str, optional) – A preset style to use for the curve.
kwargs – Specific style options passed to matplotlib.patches.PathPatch.

shape(coos, preset=None, **kwargs)[source]¶

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

rectangle(cooa, coob, preset=None, **kwargs)[source]¶

patch(coos, preset=None, **kwargs)[source]¶

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, *, preset=None, **kwargs)[source]¶

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.

bezier(coos, preset=None, **kwargs)[source]¶

Draw a bezier curve, explicitly supplying the sequence of coordinates and anchors like [coo0, anchor0, anchor1, coo1, …].

Parameters:

coos (sequence[tuple[int, int]] or sequence[tuple[int, int, int]]) – The coordinates of the points to draw the bezier curve around.
preset (str, optional) – A preset style to use for the bezier curve.
kwargs – Specific style options passed to matplotlib.patches.PathPatch.

cup(cooa, coob, extend=0.0, flatness=1.0, which='left', preset=None, **kwargs)[source]¶: Draw a cup shape between two points.

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

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

grid(color=(0, 0.7, 0.8), alpha=0.3, zorder=-100, subdivisions=(1 / 4, 2 / 4, 3 / 4), margin=0.5, overextend=0.0, ticklabels=True)[source]¶

grid3d(color=(0, 0.7, 0.8), alpha=0.3, zorder_delta=-1000, subdivisions=(1 / 4, 2 / 4, 3 / 4), margin=0.5, ticklabels=True)[source]¶

scale_figsize(scale=1.0)[source]¶: Scale this figure’s size according to the plot limits, so that one unit in the drawing corresponds to scale inches in the figure. Note this should be called after all drawing including .grid() calls.

savefig(fname, dpi=300, bbox_inches='tight')[source]¶

Save this drawing to a file, using matplotlib’s savefig and some nicer defaults.

Parameters:

fname (str) – The filename to save to.
dpi (int, optional) – The DPI to use. Default is 300.
bbox_inches (str or Bbox, optional) – The bbox_inches parameter to pass to matplotlib’s savefig. Default is ‘tight’.

robodraw.schematic.parse_style_preset(presets, preset, **kwargs)[source]¶

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

robodraw.schematic.simple_scale(i, j, xscale=1, yscale=1)[source]¶

robodraw.schematic.axonometric_project(i, j, k, a=15, b=120, xscale=1, yscale=1, zscale=1)[source]¶

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

Both angles are measured counterclockwise from the horizontal (3 o’clock direction), following the standard math convention. The z-axis always points straight up.

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 angles of the x and y axes respectively, measured counterclockwise from horizontal, in degrees.
b (float) – The angles of the x and y axes respectively, measured counterclockwise 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

robodraw.schematic.coo_to_zorder(i, j, k, a=15, b=120, xscale=1, yscale=1, zscale=1)[source]¶

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.

The depth direction is the null space of the axonometric projection matrix: (cos(b), -cos(a), sin(b-a)), with axis flipping from the sign of the scale factors.

robodraw.schematic.orthographic_project(i, j, k, azimuth=20, elevation=40, xscale=1, yscale=1, zscale=1)[source]¶

Project the 3D location (i, j, k) onto the 2D plane using an orthographic projection (camera at infinity, no perspective distortion) with the given camera azimuth and elevation.

The camera convention is:

azimuth=0 means looking along the +y direction, so the y-axis extends “into the page” (y=1 is behind y=0).
Increasing azimuth rotates the camera clockwise when viewed from above.
elevation=0 is a horizontal (side-on) view, elevation=90 is directly above. (0, 90) gives an exact top-down view with x to the right and y up.

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.
azimuth (float) – Horizontal camera angle in degrees.
elevation (float) – Vertical camera angle above the horizontal, in degrees.
xscale (float) – Scaling factors for each axis. If negative, the axis is flipped.
yscale (float) – Scaling factors for each axis. If negative, the axis is flipped.
zscale (float) – Scaling factors for each axis. If negative, the axis is flipped.

Returns:

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

Return type:

float

robodraw.schematic.orthographic_zorder(i, j, k, azimuth=20, elevation=40, xscale=1, yscale=1, zscale=1)[source]¶: Compute z-order (depth) for orthographic projection by projecting onto the camera view direction. Higher values are closer to the camera and should be drawn on top.

robodraw.schematic._COLORS_DEFAULT¶

robodraw.schematic.get_color(which, alpha=None, hue_factor=0.0, sat_factor=1.0, val_factor=1.0)[source]¶

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]

robodraw.schematic.get_wong_color[source]¶

robodraw.schematic._COLORS_SORTED¶

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

robodraw.schematic.auto_colors(nc, alpha=None, default_sequence=False)[source]¶

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]]

robodraw.schematic.darken_color(color, factor=2 / 3)[source]¶: Take color and darken it by factor.

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

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

robodraw.schematic.COLORING_SEED = 8¶

robodraw.schematic.set_coloring_seed(seed)[source]¶

Set the seed for the random color generator.

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

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

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

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

robodraw.schematic.mean(xs)[source]¶: Get the mean of a list of numbers.

robodraw.schematic.distance(pa, pb)[source]¶: Get the distance between two points, in arbtirary dimensions.

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

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

robodraw.schematic.get_rotator_and_inverse_3d(pa, pb)[source]¶: Get forward and inverse functions that translate pa to the origin and rotate so that pb lies along the positive x-axis.

robodraw.schematic.shorten_line(pa, pb, amount)[source]¶

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

robodraw.schematic.convex_hull_2d(points)[source]¶

Compute the convex hull of a set of 2D points using Andrew’s monotone chain algorithm.

Parameters:: points (sequence[tuple[float, float]]) – The 2D points. Each item must support indexing as p[0], p[1].
Returns:: Indices into points of the hull vertices, in counter-clockwise order, matching the convention of scipy.spatial.ConvexHull.vertices for 2D inputs. Collinear points along a hull edge are excluded.
Return type:: list[int]

robodraw.schematic.gen_points_around(coo, radius=1, resolution=12)[source]¶: Generate points around a circle.