API

color.py

Functions for working with colors.

class algoraphics.color.Color(hue=None, sat=None, li=None, RGB=None)

Object to represent a color or distribution of colors.

Define using either an hsl tuple, separate hue/saturation/lightness arguments, or an RGB tuple. Any component can be a Param object.

Parameters
  • hsl – The hsl specification, where each component is between 0 and 1.

  • hue (Optional[float]) – The hue specification from 0 to 1. sat and li must also be provided.

  • sat (Optional[float]) – The saturation specification from 0 to 1.

  • li (Optional[float]) – The lightness specification from 0 to 1.

  • RGB (Optional[Tuple[int, int, int]]) – The red/green/blue components, each ranging from 0 to 255.

hsl(t=0)

Get the color’s hsl specification.

Returns the specification at time t if the color is parameterized.

Return type

Tuple[float, float, float]

rgb(t=0)

Get the color’s rgb specification.

Returns the specification at time t if the color is parameterized.

Return type

Tuple[float, float, float]

state(t=0)

Get the color’s hex specification.

Returns one fixed specification if the color is parameterized.

Return type

str

algoraphics.color.average_color(colors)

Find average of list of colors.

This finds the arithmetic mean in RGB color space, since averaging hues has unexpected results with black, white, and gray.

Parameters

colors (Sequence[Color]) – A list of Color objects.

Return type

Color

Returns

The average color.

algoraphics.color.make_color(x)

Convert to a color object if a tuple (assumed to be hsl) is provided.

Return type

Color

geom.py

General functions involving points in 2D space.

algoraphics.geom.angle_between(p1, p2, p3)

Get the angle (in radians) between segment p2->p1 and p2->p3.

The angle can be negative.

Parameters
  • p1 (Tuple[float, float]) – The first endpoint.

  • p2 (Tuple[float, float]) – The point where the angle is calculated.

  • p3 (Tuple[float, float]) – The other endpoint.

Return type

float

algoraphics.geom.deg(rad)

Convert radians to degrees.

Return type

float

algoraphics.geom.direction_to(p1, p2)

Get the direction of p2 from p1 in degrees.

Return type

float

algoraphics.geom.distance(p1, p2)

Get the distance between two points.

Return type

float

algoraphics.geom.endpoint(start, angle, distance)
Parameters
  • start (Tuple[float, float]) – Starting point.

  • angle (float) – Direction from starting point in radians.

  • distance (float) – Distance from starting point.

Return type

Tuple[float, float]

Returns

A point distance from start in the direction angle.

algoraphics.geom.get_nearest(points, point, index=False)

Find the nearest point in a list to a target point.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of points.

  • point (Tuple[float, float]) – The target point.

  • index (bool) – Whether to return the point or its index in the list.

Return type

Union[Tuple[float, float], int]

Returns

If index is False, returns point, otherwise returns index of point in list.

algoraphics.geom.horizontal_range(points)

Get the magnitude of the horizontal range of a list of points.

Parameters

points (Sequence[Tuple[float, float]]) – A list of points.

Return type

float

algoraphics.geom.jitter_points(points, r)

Add noise to the locations of points.

Distance and direction of movement are both uniformly random, so the 2D probability density is circular with higher concentration toward the center.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of points.

  • r (float) – The maximum distance points will move.

algoraphics.geom.jittered_points(points, r)

Get noisy copy of points.

Like jitter_points but returns jittered points, not affecting the original list.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of points.

  • r (float) – The maximum distance points will move.

Return type

Sequence[Tuple[float, float]]

Returns

A list of points.

algoraphics.geom.line_to_polygon(points, width)

Convert a sequence of points to a thin outline.

Imagining the points were connected with a stroke with positive width, the outline of the stroke is returned.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of line points.

  • width (float) – Width of the stroke to be outlined.

Return type

Sequence[Tuple[float, float]]

Returns

A list of points.

algoraphics.geom.midpoint(p1, p2)

Get the midpoint between two points.

Parameters
  • p1 (Tuple[float, float]) – A point.

  • p2 (Tuple[float, float]) – Another point.

Return type

Tuple[float, float]

algoraphics.geom.move_toward(start, target, distance)
Parameters
  • start (Tuple[float, float]) – Starting point.

  • target (Tuple[float, float]) – Point to indicate direction from starting point to move.

  • distance (float) – Distance from starting point to returned point.

Return type

Tuple[float, float]

Returns

A point distance from start in the direction of target.

algoraphics.geom.rad(deg)

Convert degrees to radians.

Return type

float

algoraphics.geom.rotate_and_move(start, ref, angle, distance)

Combine rotated_point and move_toward for convenience.

Parameters
  • start (Tuple[float, float]) – Starting point.

  • ref (Tuple[float, float]) – A reference point.

  • angle (float) – The angle in radians to rotate ref around start.

  • distance (float) – The distance to move from start.

Returns

A point distance from start in the angle direction relative to ref.

algoraphics.geom.rotate_points(points, pivot, angle)

Rotate points around a reference point.

Parameters
  • points (Sequence[Sequence[+T_co]]) – A list of points, which can be nested.

  • pivot (Tuple[float, float]) – The center of rotation.

  • angle (float) – The angle in radians by which to rotate.

algoraphics.geom.rotated_point(point, pivot, angle)

Get the new location of a point after rotating around a reference point.

Parameters
  • point (Tuple[float, float]) – The starting location.

  • pivot (Tuple[float, float]) – The center of rotation.

  • angle (float) – The angle in radians by which to rotate.

Return type

Tuple[float, float]

algoraphics.geom.scale_points(points, cx, cy=None)

Scale the coordinates of points.

Parameters
  • points (Sequence[Sequence[+T_co]]) – A list of points, which can be nested.

  • cx (float) – The horizontal scale factor.

  • cy (Optional[float]) – The vertical scale factor. If omitted, y-coordinates will be scaled by cx.

algoraphics.geom.scaled_point(point, cx, cy=None)

Get the new location of point after scaling coordinates.

Provide either one scaling factor or cx and cy.

Parameters
  • cx (float) – Either the scaling factor, or if cy is also provided, the horizontal scaling factor.

  • cy (Optional[float]) – The vertical scaling factor.

Return type

Tuple[float, float]

algoraphics.geom.translate_points(points, dx, dy)

Shift the location of points.

Parameters
  • points (Sequence[Sequence[+T_co]]) – A list of points, which can be nested.

  • dx (float) – Horizontal change.

  • dy (float) – Vertical change.

algoraphics.geom.translated_point(point, dx, dy)

Get a translated point.

Parameters
  • point (Tuple[float, float]) – The starting location.

  • dx (float) – The horizontal translation.

  • dy (float) – The vertical translation.

Return type

Tuple[float, float]

main.py

General functions for creating graphics.

algoraphics.main.add_margin(bounds, margin)

Add margin to bounds.

A convenience function used when generating objects to avoid issues at the edges of the region or canvas.

Parameters
  • bounds (Tuple[float, float, float, float]) – A tuple of min x, min y, max x, and max y.

  • margin (float) – The width of the margin.

Return type

Tuple[float, float, float, float]

Returns

Bounds that include the margin on all sides.

algoraphics.main.add_shadows(objects, stdev=10, darkness=0.5)

Add shadows to objects.

Each element (nested or not) of the list is replaced with a group with shadow filter. So items that are shapes will have their own shadow, while an item that is a (nested) list of shapes will have one shadow for the composite object.

Parameters
  • objects (Sequence[Union[Shape, Group, list]]) – A list of shapes (can be nested).

  • stdev (float) – Standard deviation of the shadow gradient.

  • darkness (float) – A number below one for lighter shadow, above one for darker.

algoraphics.main.filtered(obj, fltr)

Apply a filter to one or more shapes.

Parameters
  • obj (Union[Shape, Group, list]) – A shape or (nested) list.

  • fltr (dict) – A filter.

Return type

dict

Returns

A group with obj as members and filter applied to group.

algoraphics.main.flatten(objects)

Create a flattened list from a nested list.

Parameters

objects (Any) – A nested list or a non-list.

Return type

list

Returns

The non-list elements within the input.

algoraphics.main.region_background(region, color)

Add background color to a clipped region.

Adds a filled rectangle to the beginning of the region’s members.

Parameters
  • region (dict) – A clipped group shape.

  • color (Color) – A color to apply to the region.

algoraphics.main.reorder_objects(objects, by='random', w=None, h=None)

Reorder objects in list.

Used to change order in which objects are drawn.

Parameters
  • objects (Sequence[Union[Shape, Group, list]]) – A list whose items are shapes or lists.

  • by (str) – ‘random’ to shuffle objects. ‘out to in’ to arrange objects closer to the center on top of (later in list) those further from the center. Distance is determined by furthest corner of bounding box so that smaller objects tend to be arranged on top of larger ones that surround them.

  • w (Optional[float]) – Canvas width, used to get center when by=’out to in’.

  • h (Optional[float]) – Canvas height, used to get center when by=’out to in’.

algoraphics.main.shuffled(items)

Create shuffled version of a list.

Parameters

items (Sequence[+T_co]) – A list of items.

Return type

list

Returns

A new list with same objects as input but reordered.

algoraphics.main.with_shadow(obj, stdev, darkness)

Add shadow to an object.

Like add_shadows() but returns a group with a single shadow filter.

Parameters
  • obj (Union[Shape, Group, list]) – A shape or list of objects (can be nested).

  • stdev (float) – Standard deviation of shadow gradient.

  • darkness (float) – A number below one for lighter shadow, above one for darker.

Return type

dict

Returns

A group with obj as members and a filter applied to the group.

param.py

Define parameter objects that incorporate randomness.

class algoraphics.param.Dynamic(start=None, delta=None, ratio=None, min=None, max=None)

Parameters whose values depend on the previous value.

Provide a Param or number for delta which will be added to the previously generated value to get the next one. Or, provide a ratio Param or number to multiply to each previous value.

Passing a randomized Param object to delta or ratio will result in a random walk. These Param objects can themselves have a delta/ratio argument, resulting in higher-order random walks.

Parameters
  • start – The starting value, which can be obtained from a Param.

  • delta – A value to add to the previous value to get the next.

  • ratio – Similar to delta, but is multiplied by, rather than added to, the previous value to get the next.

  • min – The smallest allowable value.

  • max – The largest allowable value.

class algoraphics.param.Exponential(mean=1, stdev=1, sigma=2, static=True)

Parameters with Exponential distributions.

Parameters
  • mean (float) – The distribution’s mean.

  • stdev (float) – The distribution’s standard deviation.

  • sigma (float) – How many standard deviations from the mean to clip values.

class algoraphics.param.Normal(mean=0, stdev=1, static=True)

Parameters with Gaussian (normal) distributions.

Parameters
  • mean (float) – The distribution’s mean.

  • stdev (float) – The distribution’s standard deviation.

class algoraphics.param.Param(x, static=True)

Objects to represent fixed or random parameters for shapes.

Create Param objects for fixed values, value lists, or arbitrary functions. For random distributions, use a specific class that inherits from Param.

Parameters

x (Union[str, float, list, Callable]) – A value, list, or a function that takes no arguments and returns a value.

class algoraphics.param.Uniform(min=0, max=1, static=True)

Parameters with uniformly random distributions.

Parameters
  • min (float) – The lower bound.

  • max (float) – The upper bound.

  • static (bool) – If set to false, the value will be recomputed for each frame.

algoraphics.param.fixed_value(x, t=0)

Get a fixed value even if a Param object is supplied.

Parameters
  • x (Union[float, str, Param]) – An object.

  • t (int) – The current timepoint.

Return type

Union[float, str]

algoraphics.param.make_param(x)

Get a Param object even if something else is supplied.

Return type

Param

point.py

Define objects that represent dynamic 2D points.

class algoraphics.point.Move(ref, direction=None, distance=0)
Parameters
  • ref (Union[Tuple[float, float], Point]) – The reference or starting point.

  • direction (Optional[Param]) – A param giving directions (in degrees) of generated points relative to ref. By default the direction is uniformly random.

  • distance (Param) – A param giving distances of generated points relative to ref.

class algoraphics.point.Point(point)

A representation of a dynamic location in 2D space.

Parameters
  • ref – The reference or starting point.

  • direction – A param giving directions (in degrees) of generated points relative to ref. By default the direction is uniformly random.

  • distance – A param giving distances of generated points relative to ref.

class algoraphics.point.Rotation(start, pivot, angle)
class algoraphics.point.Scaling(start, cx, cy=None)
class algoraphics.point.Translation(start, move)
algoraphics.point.make_point(x)

Get a Point object even if a tuple is supplied.

Return type

Point

shapes.py

Create and manipulate shapes.

class algoraphics.shapes.Circle(c, r, **style)

A circle shape.

Parameters
  • c (Point) – The circle’s center.

  • r (float) – The circle’s radius.

class algoraphics.shapes.Group(members=None, clip=None, filter=None)

A group of shapes, usually with a clip.

Parameters
  • members (Union[list, Shape, Group, None]) – The shapes in the group.

  • clip (Union[list, Shape, Group, None]) – The shape/s determining where the members are visible.

  • filter (Optional[dict]) – An SVG filter, e.g. shadow, to apply to the group.

class algoraphics.shapes.Line(p1=None, p2=None, points=None, **style)

A line or polyline shape.

Supply either p1 and p2 for a line or points for a polyline.

Parameters
  • p1 (Optional[Point]) – The starting point.

  • p2 (Optional[Point]) – The ending point.

  • points (Optional[Sequence[Point]]) – If a list of points is provided, a polyline is created.

class algoraphics.shapes.Polygon(points, **style)

A polygon shape.

Parameters

points (Sequence[Point]) – A list of polygon vertices.

class algoraphics.shapes.Spline(points, smoothing=0.3, circular=False, **style)

A spline shape.

Parameters
  • points (Sequence[Point]) – A list of points.

  • smoothing (float) – The distance to the control point relative to the distance to the adjacent point. Usually between zero and one.

  • circular (bool) – If False, spline ends reasonably at the first and last points. If True, the ends of the spline will connect smoothly.

algoraphics.shapes.bounding_box(shapes)

Find the bounding box of a shape or shape collection.

Currently assumes t == 0.

Parameters

shapes (Union[list, Shape, Group]) – One or more shapes.

Return type

Tuple[float, float, float, float]

Returns

The min x, max x, min y, and max y coordinates of the input.

algoraphics.shapes.centroid(shape)

Find the centroid of a shape.

Parameters

shape (Shape) – A shape.

Return type

Tuple[float, float]

Returns

A point.

algoraphics.shapes.coverage(obj)

Create a shapely object.

Used to calculate area/coverage.

Parameters

obj (Union[list, Shape, Group]) – One or more shapes.

Return type

Union[Polygon, Point, GeometryCollection]

Returns

A shapely object representing the union of coverage for all input shapes.

algoraphics.shapes.keep_points_inside(points, boundary)

Keep points that lie within a boundary.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of points.

  • boundary (Union[list, Shape, Group]) – One or more shapes giving the boundary.

algoraphics.shapes.keep_shapes_inside(shapes, boundary)

Remove shapes if they lie entirely outside the boundary.

Used to optimize SVG file without altering the appearance.

Parameters
  • shapes (Sequence[Union[list, Shape, Group]]) – A list of shapes, which can be nested.

  • boundary (Union[list, Shape, Group]) – One or more shapes giving the boundary.

algoraphics.shapes.polygon_area(vertices)

Find the area of a polygon.

Parameters

vertices (Sequence[Tuple[float, float]]) – The vertex points.

Return type

float

Returns

The area.

algoraphics.shapes.rectangle(start=None, w=None, h=None, bounds=None, **style)

Create a rectangular Polygon shape.

Provide either start + w + h or a bounds tuple.

Parameters
  • start (Optional[Tuple[float, float]]) – Bottom left point of the rectangle (unless w or h is negative).

  • w (Optional[float]) – Width of the rectangle.

  • h (Optional[float]) – Height of the rectangle.

  • bounds (Optional[Tuple[float, float, float, float]]) – The (x_min, y_min, x_max, y_max) of the rectangle.

Return type

Polygon

Returns

A polygon shape.

algoraphics.shapes.remove_hidden(shapes)

Remove shapes from (nested) list if they are entirely covered.

Used to optimize SVG file without altering appearance, e.g. when randomly placing objects to fill a region. Ignores opacity when determining overlap.

Parameters

shapes (Sequence[Union[list, Shape, Group]]) – A list of shapes.

algoraphics.shapes.rotate_shapes(shapes, angle, pivot=(0, 0))

Rotate one or more shapes around a point.

Parameters
  • shapes (Union[list, Shape, Group]) – One or more shapes.

  • angle (float) – The angle of rotation in degrees.

  • pivot (Tuple[float, float]) – The rotation pivot point.

algoraphics.shapes.rotated_bounding_box(shapes, angle)

Find the rotated bounding box of a shape or shape collection.

Parameters
  • shapes (Union[list, Shape, Group]) – One or more shapes.

  • angle (float) – The orientation of the bounding box in degrees.

Return type

Tuple[float, float, float, float]

Returns

The min x, max x, min y, and max y coordinates in rotated space. Anything created using these coordinates must then be rotated by the same angle around the origin to be in the right place.

algoraphics.shapes.sample_points_in_shape(shape, n)

Sample random points inside a shape.

Parameters
  • shape (dict) – A shape (currently works for polygons and splines).

  • n (int) – Number of points to sample.

Return type

List[Tuple[float, float]]

Returns

The sampled points.

algoraphics.shapes.scale_shapes(shapes, cx, cy=None)

Scale one or more shapes.

Parameters
  • shapes (Union[list, Shape, Group]) – One or more shapes.

  • cx (float) – The horizontal scaling factor.

  • cy (Optional[float]) – The vertical scaling factor. If missing, cx will be used.

algoraphics.shapes.set_style(obj, attribute, value)

Set style attribute of one or more shapes.

Parameters
  • obj (Union[list, Shape, Group]) – A shape or (nested) list of shapes.

  • attribute (str) – Name of the style attribute.

  • value (Union[str, float, Param, Color]) – Either a single value, Color, or Param.

algoraphics.shapes.set_styles(obj, attribute, value)

Set style attribute of one or more shapes.

Unlike set_style, it creates a deep copy of the Param or Color for each shape so that there is variation.

Parameters
  • obj (Union[list, Shape, Group]) – A shape or (nested) list of shapes.

  • attribute (str) – Name of the style attribute.

  • value (Union[Param, Color]) – A Color or Param.

algoraphics.shapes.translate_shapes(shapes, dx, dy)

Shift the location of one or more shapes.

Parameters
  • shapes (Union[list, Shape, Group]) – One or more shapes.

  • dx (float) – The horizontal shift.

  • dy (float) – The vertical shift.

svg.py

write SVG files.

class algoraphics.svg.Canvas(width, height, background='white')

A rectangular space to be filled with graphics.

Parameters
  • width (float) – The canvas width.

  • height (float) – The canvas height.

  • background (Color) – The background color. If None, background will be transparent.

add(*object)

Add one or more shapes or collections to the canvas.

clear()

Remove all objects from the canvas.

get_svg()

Get the SVG representation of the canvas as a string.

Return type

str

gif(file_name, fps, n_frames=None, seconds=None)

Create a GIF image of a dynamic graphic.

Parameters
  • file_name (str) – The file name to write to.

  • fps (int) – Frames per second of the GIF.

  • n_frames (Optional[int]) – Number of frames to generate.

  • seconds (Optional[float]) – Specify length of the GIF in seconds instead of number of frames.

new(*object)

Clear the canvas and then add one or more shapes or collections.

png(file_name, force_RGBA=False)

Write the canvas to a PNG file.

Parameters
  • file_name (str) – The file name to write to.

  • force_RGBA (bool) – Whether to write PNG in RGBA colorspace, even if it could be grayscale. This is for, e.g., moviepy which requires all frame images to be in the same colorspace.

svg(file_name, optimize=True)

Write the canvas to an SVG file.

Parameters
  • file_name (str) – The file name to write to.

  • optimize (bool) – Whether to optimize the SVG file using svgo.

algoraphics.svg.gif(function, fps, file_name, n_frames=None, seconds=None)

Create a GIF image from a frame-generating function.

By wrapping typical canvas drawing code in a function, multiple versions of the drawing, each with random variation, can be stitched together into an animated GIF.

Parameters
  • function (Callable) – A function called with no arguments that returns a (filled) Canvas.

  • fps (int) – Frames per second of the GIF.

  • file_name (str) – The file name to write to.

  • n_frames (Optional[int]) – Number of frames to generate.

  • seconds (Optional[float]) – Specify length of the GIF in seconds instead of number of frames.

algoraphics.svg.svg_string(objects, w, h, t=0)

Create an SVG string for a collection of objects.

Parameters
  • objects (Union[list, dict]) – A (nested) collection of objects. They are placed onto the canvas in order after flattening.

  • w (float) – Width of the canvas.

  • h (float) – Height of the canvas.

  • t (int) – If objects are dynamic, the timepoint to render.

algoraphics.svg.video(function, fps, file_name, n_frames=None, seconds=None)

Create a GIF image from a frame-generating function.

By wrapping typical canvas drawing code in a function, multiple versions of the drawing, each with random variation, can be stitched together into an animated GIF.

Parameters
  • function (Callable) – A function called with no arguments that returns a (filled) Canvas.

  • fps (int) – Frames per second of the GIF.

  • file_name (str) – The file name to write to.

  • n_frames (Optional[int]) – Number of frames to generate.

  • seconds (Optional[float]) – Specify length of the GIF in seconds instead of number of frames.

Extras API

fill.py

Fill regions with objects in various ways.

class algoraphics.extras.fill.Doodle(function, footprint)

A Doodle object is a generator of doodles.

Parameters
  • function (Callable[[], Union[dict, list]]) – A function that takes no arguments and returns a shape or collection.

  • footprint (ndarray) – A boolean 2D array whose cells indicate the shape (within a grid) occupied by the generated doodles (before being oriented). Row 0 should correspond to the top row of the doodle’s footprint.

footprint(orientation=0)

Get the doodle’s footprint in a given orientation.

Parameters

orientation (int) – 0 to 7.

Return type

ndarray

Returns

The oriented footprint.

oriented(orientation=0)

Draw the doodle in a given orientation.

Parameters

orientation (int) – 0 to 7.

Return type

Union[dict, list]

Returns

The oriented doodle.

algoraphics.extras.fill.fill_region(outline, object_fun, min_coverage=1, max_tries=None)

Fill a region by iteratively placing randomly generated objects.

Parameters
  • outline (Union[dict, list]) – A shape or (nested) list of shapes that will become clip.

  • object_fun (Callable[[Tuple[float, float, float, float]], Union[dict, list]]) – A function that takes bounds as input and returns a randomly generated object.

  • min_coverage (float) – The minimum fraction of the region’s area filled before stopping.

  • max_tries (Optional[int]) – If not None, the number of objects to generate (including those discarded for not filling space) before giving up and returning the region as is.

Return type

Group

Returns

A group with clip.

algoraphics.extras.fill.fill_spots(outline, spacing=10)

Fill a region with randomly sized spots.

The spots are reminiscent of Ishihara color blindness tests. The spots are not completely non-overlapping, but overlaps are somewhat avoided by spacing out their centers.

Parameters
  • outline (Union[dict, list]) – A region outline shape.

  • spacing (float) – The approximate distance between the centers of neighboring spots.

Return type

List[Circle]

Returns

A list of Circle shapes.

algoraphics.extras.fill.fill_wrapping_paper(outline, spacing, doodles, rotate=True)

Fill a region with a tiling of non-overlapping doodles.

Parameters
  • outline (Union[dict, list]) – A shape or (nested) list of shapes that will become the clip.

  • spacing (float) – Height/width of each grid cell.

  • doodles (Sequence[Doodle]) – A list of Doodle objects.

  • rotate (bool) – Whether to place the grid in a random rotated orientation.

Return type

Group

Returns

A clipped group.

algoraphics.extras.fill.grid_wrapping_paper(rows, cols, spacing, start, doodles)

Create a tiling of non-overlapping doodles.

Parameters
  • rows (int) – Number of rows to include.

  • cols (int) – Number of columns to include.

  • spacing (float) – Height/width of each grid cell.

  • start (Tuple[float, float]) – Bottom left point of the grid.

  • doodles (Sequence[Doodle]) – A list of Doodle objects.

Return type

List[Union[dict, list]]

Returns

A list of placed doodle collections.

grid.py

Functions for working with grids.

algoraphics.extras.grid.grid_tree(rows, cols)

Generate random spanning tree for a grid.

Tree connects adjacent elements of a grid. Used for pixels and for other grids.

Parameters
  • rows (int) – Number of rows in the grid.

  • cols (int) – Number of columns in the grid.

Return type

ndarray

Returns

A 2D binary array in sparse format with dimensions (num. grid cells x num. grid cells) indicating which cells are connected.

algoraphics.extras.grid.grid_tree_dists(rows, cols)

Generate an array of random spanning tree distances.

Each value is the distance to (0, 0) along a spanning tree. Map to a cyclical color gradient to create a billowing effect.

Parameters
  • rows (int) – Number of rows in the grid.

  • cols (int) – Number of columns in the grid.

Return type

ndarray

Returns

A 2D array of integers.

algoraphics.extras.grid.grid_tree_edges(rows, cols)

Generate edges of a random spanning tree for a grid.

Parameters
  • rows (int) – Number of rows in the grid.

  • cols (int) – Number of columns in the grid.

Return type

Sequence[Tuple[Tuple[int, int], Tuple[int, int]]]

Returns

A list of ((r1, c1), (r2, c2)) coordinate tuple pairs.

algoraphics.extras.grid.grid_tree_neighbors(rows, cols)

Generate a random spanning tree for a grid and return neighbor array.

Parameters
  • rows (int) – Number of rows in grid.

  • cols (int) – Number of cols in grid.

Return type

ndarray

Returns

A 3D boolean array (rows x cols x [d?, r?, u?, l?]). The third dimension is length 4 and indicates whether that cell shares an edge with the cell below, right, above, and left of it.

algoraphics.extras.grid.hsv_array_to_rgb(hsv)

Convert matrix of HSV values to rgb.

Parameters

hsv (ndarray) – An array of HSV colors.

Return type

ndarray

Returns

An array of rgb colors.

algoraphics.extras.grid.map_colors_to_array(values, colors, gradient_mode='rgb')

Map 2D array of values to a cyclical color gradient.

If values vary continuously in space, this produces a cyclical color gradient.

Parameters
  • values (ndarray) – A 2D array of floats. Values should range from 0, inclusive, to len(colors) + 1, exclusive. Each value corresponds to a proportional mixture of the colors at the two indices it is between (with values higher than the last index cycling back to the first color).

  • colors (Sequence[Color]) – A list of Color objects.

  • gradient_mode (str) – Either ‘rgb’ or ‘hsv’ to indicate how the colors are interpolated.

Return type

ndarray

Returns

A 3D array of RGB values (RGB mode because this is used for PIL images).

algoraphics.extras.grid.rgb_array_to_hsv(rgb)

Convert matrix of rgb values to HSV.

Parameters

rgb (ndarray) – An array of rgb colors.

Return type

ndarray

Returns

An array of HSV colors.

images.py

Generate graphics based on images.

algoraphics.extras.images.fill_shapes_from_image(shapes, image)

Fill shapes according to their corresponding image region.

Faster than region_color which samples points, but should only be used for regular shapes like tiles since it colors according to the centroid, which may not be inside the shape if it is irregular.

Parameters
  • shapes – A list of shapes.

  • image – A PIL image.

algoraphics.extras.images.image_regions(image, n_segments=100, compactness=10, smoothness=0, simplify=1, expand=2, smoothing=0.2)

Get spline shapes corresponding to image regions.

Parameters
  • image – A PIL image.

  • n_segments – Approximate number of desired segments.

  • compactness – A higher value produces more compact, square-like segments. Try values along log-scale, e.g. 0.1, 1, 10, 100.

  • smoothness – The width of gaussian smoothing applied before segmentation.

  • simplify – Maximum distance from the edge of a simplified shape to its actual boundary when reducing the number of points, or None for no simplification.

  • expand – Number of pixels to expand each segment in every direction to avoid gaps between adjacent shapes.

  • smoothing – The degree of curvature in spline. Usually between zero and one.

Returns

A list of spline shapes, generally in order from left to right and then bottom to top.

algoraphics.extras.images.open_image(path)

Load a PIL image from file.

Parameters

path – Path to the image file.

Returns

A PIL Image.

algoraphics.extras.images.pad_array(pixels, margin=1)

Create a new pixel array with added padding.

Adds additional rows and columns of zeros to four edges of matrix. Used to enable finding a contour around a segment at the edge of an image and to allow segments to be expanded to overlap each other.

Parameters
  • pixels (ndarray) – A 2D array of pixels.

  • margin (int) – The width of padding on each side.

Return type

ndarray

Returns

A 2D array with 2 * margin added to both dimensions.

algoraphics.extras.images.region_color(outline, image, n_points=10)

Find representative color for an image region.

Parameters
  • outline – A shape corresponding to an image region to sample.

  • image – A PIL image.

  • n_points – Number of points to sample.

Returns

The average color of the sampled image points.

algoraphics.extras.images.resize_image(image, width, height)

Downscale an image.

Scales according to whichever of width or height is not None. Only scales down.

Parameters
  • image – A PIL image.

  • width – The new width. If None, scales according to height.

  • height – The new height. If None, scales according to width.

algoraphics.extras.images.sample_colors(image, points)

Sample colors from an image.

Parameters
  • image – A PIL image.

  • points – A list of image coordinates, or a single coordinate.

Returns

A list of colors corresponding to points, or a single color if input is a single point.

mazes.py

Functions for creating maze-like patterns.

class algoraphics.extras.mazes.Maze_Style

Specifications for maze styles.

Built-in styles inherit from this class, and custom styles can be made to do so as well. It must implement the tip, turn, straight, T, and cross methods to describe how each component is drawn.

Each of these methods should generate forms for one cell of the maze. They must provide one or more pieces which are stitched together when the maze is assembled. For example, for a cell in which the maze turns right, the inner and outer edges of the curve are generated. Once this cell is encountered in the stitching process, the inner edge is added, then everything from the cell to the right is recursively added, and then the outer edge is added to get one continuous edge.

For all methods the edge enters below and draws the component counter-clockwise. During maze generation components are generated and then rotated as needed to accomodate any combination of neighbors that the cell should connect to.

T()

Generate a ‘T’-shaped cell.

This should return a tuple of three lists of path commands corresponding to the right inner edge, top edge, and then left inner edge.

cross()

Generate a cell connecting in all directions.

This should return a tuple of four lists of path commands corresponding to the lower-right, upper-right, upper-left, and lower-left inner edges.

output(points)

Make the output shape/s from the generated points.

This takes the maze outline points and produces the intended shape/s, e.g. polygon or spline. Returns a polygon by default.

straight()

Generate a non-turning cell.

This should return a tuple of two lists of path commands corresponding to the right and then left edges.

tip()

Generate a dead-end cell.

This should return a list of path command dictionaries.

turn()

Generate a right turn cell.

This should return a tuple of two lists of path commands corresponding to the inner and then outer edges.

Left turns will be drawn with this and then rotated.

class algoraphics.extras.mazes.Maze_Style_Jagged(min_w, max_w)

Generate pieces for jagged maze.

Parameters
  • min_w (float) – Minimum width of channel segment relative to cell width.

  • max_w (float) – Maximum width of channel segment relative to cell width.

output(points)

Make the output shape/s from the generated points.

This takes the maze outline points and produces the intended shape/s, e.g. polygon or spline. Returns a polygon by default.

class algoraphics.extras.mazes.Maze_Style_Pipes(rel_thickness)

Generate pieces for curved pipes.

Parameters

rel_thickness (float) – Channel width relative to cell width, from 0 to 1.

output(points)

Make the output shape/s from the generated points.

This takes the maze outline points and produces the intended shape/s, e.g. polygon or spline. Returns a polygon by default.

class algoraphics.extras.mazes.Maze_Style_Round(rel_thickness)

Generate pieces for very curvy pipes.

Parameters

rel_thickness (float) – Channel width relative to cell width, from 0 to 1.

output(points)

Make the output shape/s from the generated points.

This takes the maze outline points and produces the intended shape/s, e.g. polygon or spline. Returns a polygon by default.

class algoraphics.extras.mazes.Maze_Style_Straight(rel_thickness)

Generate pieces for simple right-angle maze.

Parameters

rel_thickness (float) – Channel width relative to cell width, from 0 to 1.

output(points)

Make the output shape/s from the generated points.

This takes the maze outline points and produces the intended shape/s, e.g. polygon or spline. Returns a polygon by default.

algoraphics.extras.mazes.fill_maze(outline, spacing, style, rotation=None)

Fill a region with a maze-like pattern.

Parameters
  • outline (Union[list, Shape, Group]) – The shape/s that will become the clip.

  • spacing (float) – The cell width of the grid.

  • style (Maze_Style) – An object specifying how the maze path is to be drawn.

  • rotation (Optional[float]) – The orientation of the grid in degrees.

Return type

dict

Returns

A group with clip.

algoraphics.extras.mazes.maze(rows, cols, spacing, start, style)

Generate a maze-like pattern spanning the specified grid.

Parameters
  • rows (int) – Number of rows in the grid.

  • cols (int) – Number of columns in the grid.

  • spacing (float) – The cell width.

  • start (Tuple[float, float]) – The bottom-left coordinate of the grid.

  • style (Maze_Style) – An object specifying how the maze path is to be drawn.

Return type

Union[list, Shape, Group]

Returns

A shape (usually a spline or polygon) or collection.

ripples.py

Create space-filling ripple effects.

algoraphics.extras.ripples.ripple_canvas(w, h, spacing, trans_probs=None, existing_pts=None)

Fill the canvas with ripples.

The behavior of the ripples is determined by a first-order Markov chain in which events correspond to points along splines. The states are ‘S’, ‘R’, ‘L’, and ‘X’. At ‘S’, the ripple begins in a random direction. At ‘R’, the ripple turns right sharply until encountering a ripple or other barrier, and then follows along it. Likewise with ‘L’ turning left. At ‘X’, the ripple moves straight forward +/- up to 60 degrees. Higher state-changing transition probabilities result in more erratic ripples.

Parameters
  • w (float) – Width of the canvas.

  • h (float) – Height of the canvas.

  • spacing (float) – Distance between ripples.

  • trans_probs (Optional[Dict[str, Dict[str, float]]]) – A dictionary of dictionaries containing Markov chain transition probabilities from one state (first key) to another (second key).

  • existing_pts (Optional[Sequence[Tuple[float, float]]]) – An optional list of points that ripples will avoid.

Return type

List[dict]

Returns

The ripple splines.

structures.py

Create structures such as filaments and trees.

algoraphics.extras.structures.blow_paint_area(points, spacing=20, length=40, len_dev=0.25, width=5)

Draw a blow-paint effect around an area.

Creates ‘fingers’ of paint projecting from each edge, as if being blown along the page perpindicular to the edge.

Parameters
  • points (Sequence[Tuple[float, float]]) – The vertices of the polygonal area.

  • spacing (float) – Average distance between paint fingers.

  • length (float) – Average length of the paint fingers.

  • len_dev (float) – The standard deviation of finger lengths relative to length (so it should be less than 1).

  • width (float) – Average thickness of each finger.

Return type

dict

algoraphics.extras.structures.blow_paint_line(points, line_width=10, spacing=20, length=20, len_dev=0.33, width=5)

Draw a blow-paint effect connecting a sequence of points.

Creates ‘fingers’ of paint projecting from each edge, as if being blown along the page perpindicular to the edge (in both directions).

Parameters
  • points (Sequence[Tuple[float, float]]) – The points to connect.

  • line_width (float) – The thickness of the line (excluding the fingers).

  • spacing (float) – Average distance between paint fingers.

  • length (float) – Average length of the paint fingers.

  • len_dev (float) – The standard deviation of finger lengths relative to length (so it should be less than 1).

  • width (float) – Average thickness of each finger.

Return type

dict

algoraphics.extras.structures.blow_paint_spot(point, length=10, len_dev=0.7, width=3)

Draw a paint splatter.

Creates ‘fingers’ of paint projecting from a point.

Parameters
  • point (Tuple[float, float]) – The center of the splatter.

  • length (float) – Average length of the paint fingers.

  • len_dev (float) – The standard deviation of finger lengths relative to length (so it should be less than 1).

  • width (float) – Average thickness of each finger.

Return type

dict

algoraphics.extras.structures.filament(backbone, width)

Generate a meandering segmented filament.

Parameters
  • backbone (Sequence[Point]) – A list of Points specifying the midpoint of the filament ends and segment boundaries.

  • width (Param) – The width/s of the filament (at segment joining edges).

Return type

List[Polygon]

Returns

A list of Polygons (the segments from start to end).

algoraphics.extras.structures.tentacle(backbone, width)

Generate a tentacle.

Parameters
  • backbone (Sequence[Point]) – A list of Points specifying the midpoint of the filament ends and segment boundaries.

  • width (Param) – The width of the tentacle base.

Return type

Spline

Returns

A Spline shape.

algoraphics.extras.structures.tree(start, direction, branch_length, theta, p, delta_p=0)

Generate a tree with randomly terminating branches.

Parameters
  • start (Point) – The starting point.

  • direction (Param) – The starting direction (in degrees).

  • branch_length (Param) – Branch length.

  • theta (Param) – The angle (in degrees) between sibling branches.

  • p (float) – The probability that a given branch will split instead of terminating. Recommended to have a delta < 0 or ratio < 1 so that the tree is guaranteed to terminate.

  • delta_p (float) – The decrease in p at each branching.

Return type

List[dict]

Returns

A list of line shapes.

text.py

Generate text in the form of shapes or SVG text.

algoraphics.extras.text.char_points(char, start, h, spacing)

Generate points along a character shape.

Parameters
  • char (str) – A character.

  • start (Tuple[float, float]) – The lower-left point of the character bounds.

  • h (float) – The line height.

  • spacing (float) – Distance between adjacent points.

Return type

List[List[Tuple[float, float]]]

Returns

A list of lists of points. Each list of points corresponds to a pen stroke (i.e. what can be drawn without lifting the pen).

algoraphics.extras.text.text_points(text, height, pt_spacing, char_spacing=0.1, grouping='points')

Generate points that spell out text.

Text starts at (0, 0) and should be repositioned.

Parameters
  • text (str) – The text.

  • height (float) – Line height.

  • pt_spacing (float) – Approximate distance between adjacent points.

  • char_spacing (float) – Size of the largest space on either side of each character relative to line height. This space is shrunk for certain characters depending on shape.

  • grouping (str) – ‘points’ to return list of points, ‘strokes’ to group by stroke.

Return type

Union[List[Tuple[float, float]], List[List[Tuple[float, float]]]]

Returns

Either a list of points or a list of lists of points in which each list of points corresponds to a pen stroke (i.e. what can be drawn without lifting the pin).

tiling.py

Fill a region or the canvas with tiles or webs.

algoraphics.extras.tiling.delaunay_edges(points)

Find edges of Delaunay regions for a set of points.

Parameters

points (Sequence[Tuple[float, float]]) – A list of points.

Return type

List[dict]

Returns

A list of line shapes.

algoraphics.extras.tiling.delaunay_regions(points)

Find the Delaunay regions for a set of points.

Parameters

points (Sequence[Tuple[float, float]]) – A list of points.

Return type

List[dict]

Returns

A list of triangular polygon shapes. Items do not correspond to input points because points on the periphery do not have finite regions.

algoraphics.extras.tiling.fill_nested_triangles(outline, min_level, max_level, color=None, color2=None)

Fill region with nested triangle pattern.

Parameters
  • outline (Union[list, Shape, Group]) – A region outline shape or collection.

  • min_level (int) – The level of the largest triangles (0 is bounding triangle).

  • max_level (int) – The level of the smallest triangles.

  • color1 – The color/s for half of the triangles.

  • color2 (Optional[Color]) – The color for the opposing half of the triangles. This half of triangles will all be one color because it is the background.

Return type

dict

Returns

A group with the outline as clip.

algoraphics.extras.tiling.nested_triangles(tip, height, min_level, max_level)

Generate nested equilateral triangles.

Parameters
  • tip (Tuple[float, float]) – The tip of the bounding triangle.

  • height (float) – The height of the bounding triangle (negative for upside-down triangle).

  • min_level (int) – The level of the largest triangles (0 is the bounding triangle).

  • max_level (int) – The level of the smallest triangles.

Return type

List[dict]

Returns

A list of triangle polygon shapes.

algoraphics.extras.tiling.tile_canvas(w, h, shape='polygon', edges=False, tile_size=500, regularity=10)

Fill canvas with (uncolored) tiles.

Parameters
  • w (float) – Width of the canvas.

  • h (float) – Height of the canvas.

  • tile_shape – Either ‘polygon’ for Voronoi tiling or ‘triangle’ for Delaunay tiling.

  • edges (bool) – Whether to return the edges around tiles as lines instead of the tiles themselves.

  • tile_size (float) – The approximate area of each tile.

  • regularity (int) – A value of one or higher, passed to spaced_points.

Return type

List[dict]

Returns

A list of polygon or line shapes.

algoraphics.extras.tiling.tile_region(outline, shape='polygon', edges=False, tile_size=500, regularity=10)

Fill region with (uncolored) tiles or tile edges.

Parameters
  • outline (Union[list, Shape, Group]) – The shape/s that will become the clip.

  • shape (str) – Either ‘polygon’ for Voronoi tiling or ‘triangle’ for Delaunay tiling.

  • edges (bool) – Whether to return the edges around tiles as lines instead of the tiles themselves.

  • tile_size (float) – The approximate area of each tile.

  • regularity (int) – A value of one or higher, passed to spaced_points().

Return type

dict

Returns

A group with clip.

algoraphics.extras.tiling.voronoi_edges(points)

Find the edges of Voronoi regions for a set of points.

Parameters

points (Sequence[Tuple[float, float]]) – A list of points.

Return type

List[dict]

Returns

A list of line shapes.

algoraphics.extras.tiling.voronoi_regions(points)

Find Voronoi regions for a set of points.

Parameters

points (Sequence[Tuple[float, float]]) – A list of points.

Return type

List[dict]

Returns

A list of polygon shapes. Items do not correspond to input points because points on the periphery do not have finite regions.

utils.py

Functions used in the extras library.

class algoraphics.extras.utils.Rtree(points=None)

An object to efficiently query a field of points.

Parameters

points (Optional[Sequence[Tuple[float, float]]]) – Starting points.

add_point(point)

Add a point to the collection.

Parameters

point (Tuple[float, float]) – The new point.

add_points(points)

Add points to the collection.

Parameters

points (Sequence[Tuple[float, float]]) – The new points.

nearest(point, n=1, index=False)

Get the nearest point or points to a query point.

Parameters
  • point (Tuple[float, float]) – A query point.

  • n (int) – Number of nearest points to return.

  • index (bool) – Whether to return the nearets points’ indices instead of the points themselves.

Return type

Union[Sequence[Tuple[float, float]], Tuple[float, float]]

Returns

If n is 1, the nearest point, otherwise a list of nearest points.

algoraphics.extras.utils.contrasting_lightness(color, light_diff)

Get color with contrasting lightness to reference color.

Color is lighter if original lightness is < 0.5 and darker otherwise. Used to create color pairs for a mixture of light and dark colors.

Parameters
  • color (Color) – A color.

  • light_diff (float) – Magnitude of difference in lightness, between 0 and 1.

Return type

Color

Returns

The contrasting color.

algoraphics.extras.utils.interpolate(points, spacing)

Insert interpolated points.

Insert equally-spaced, linearly interpolated points into list such that consecutive points are no more than ‘spacing’ distance apart.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of points.

  • spacing (float) – Maximum distance between adjacent points.

algoraphics.extras.utils.is_clockwise(points)

Determine the derection of a sequence of points around a polygon.

Finds whether a set of polygon points goes in a clockwise or counterclockwise direction. If edges cross, it gives the more prominent direction.

Parameters

points (Sequence[Tuple[float, float]]) – A list of polygon vertices.

Return type

bool

algoraphics.extras.utils.points_on_arc(center, radius, theta_start, theta_end, spacing)

Generate points along an arc.

Parameters
  • center (Tuple[float, float]) – The center of the arc.

  • radius (float) – The radius of the arc.

  • theta_start (float) – The starting position in degrees.

  • theta_end (float) – The ending position in degrees.

  • spacing (float) – The approximate distance between adjacent points.

Return type

Sequence[Tuple[float, float]]

Returns

A list of points.

algoraphics.extras.utils.points_on_line(start, end, spacing)

Generate points along a line.

Parameters
  • start (Tuple[float, float]) – The first point.

  • end (Tuple[float, float]) – The last point.

  • spacing (float) – The approximate (max) distance between adjacent points.

Return type

Sequence[Tuple[float, float]]

Returns

A list of points.

algoraphics.extras.utils.remove_close_points(points, spacing)

Remove points that are closer than ‘spacing’.

A point is removed if it follows the previous point too closely. Consecutive points cannot both be removed, so the list is scanned repeatedly until all consecutive points are at least ‘spacing’ apart.

Parameters
  • points (Sequence[Tuple[float, float]]) – A list of points.

  • spacing (float) – Minimum distance between adjacent points.

algoraphics.extras.utils.spaced_points(n, bounds, n_cand=10)

Generate random but evenly-spaced points.

Uses Mitchell’s best-candidate algorithm.

Parameters
  • n (int) – Number of points to generate.

  • bounds (Tuple[float, float, float, float]) – A bounds tuple.

  • n_cand (int) – Number of candidate points to generate for each output point. Higher numbers result in higher regularity.

Return type

List[Tuple[float, float]]

Returns

The generated points.

algoraphics.extras.utils.wobble(shapes, dev=2)

Add a little messiness to perfect lines and curves.

Convert straight lines and curves into slightly wavy splines. Currently it converts the shape into a shape with fixed parameters, since it has to do point interpolation. The new shape’s parameters can later be made dynamic.

Parameters
  • obj – A list of one or more shapes (can be nested).

  • dev (float) – The (approximate) maximum distance a part of an edge will move.