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.
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
fromstart
in the directionangle
.
-
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.
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.geom.
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.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
fromstart
in the direction oftarget
.
-
algoraphics.geom.
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.geom.
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.geom.
rad
(deg)¶ Convert degrees to radians.
- Return type
float
-
algoraphics.geom.
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.geom.
rotate_and_move
(start, ref, angle, distance)¶ Combine
rotated_point
andmove_toward
for convenience.- Parameters
start (
Tuple
[float
,float
]) – Starting point.ref (
Tuple
[float
,float
]) – A reference point.angle (
float
) – The angle in radians to rotateref
around start.distance (
float
) – The distance to move fromstart
.
- Returns
A point
distance
fromstart
in theangle
direction relative toref
.
-
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 ifcy
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 aratio
Param or number to multiply to each previous value.Passing a randomized
Param
object todelta
orratio
will result in a random walk. TheseParam
objects can themselves have adelta
/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 fromParam
.- 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.
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)¶
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.
-
class
algoraphics.shapes.
Line
(p1=None, p2=None, points=None, **style)¶ A line or polyline shape.
Supply either
p1
andp2
for a line orpoints
for a polyline.
-
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.
-
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
- Returns
A polygon shape.
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.
-
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.
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
- 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
- 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 tolength
(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 tolength
(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 tolength
(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.
-
algoraphics.extras.structures.
tentacle
(backbone, width)¶ Generate a filament that tapers to a point.
-
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 tospaced_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 tospaced_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.
-
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.