Patterns

keyed_extras.patterns

Generate patterns that can be applied to shapes.

Tip

The size of the pattern should equal or exceed the size of the object receiving the fill pattern to prevent a weird, unavoidable tiling edge effect in cairo.

However, it is best to keep patterns as small as possible, as they are relatively expensive to render compared to solid colors.

linear_gradient_pattern

linear_gradient_pattern(x0, y0, x1, y1, stops)

Create a linear gradient pattern that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
x0	float	X-coordinate of the starting point of the gradient	required
y0	float	Y-coordinate of the starting point of the gradient	required
x1	float	X-coordinate of the ending point of the gradient	required
y1	float	Y-coordinate of the ending point of the gradient	required
stops	list[tuple[float, tuple[float, float, float]]]	List of color stops, where each stop is a tuple of (offset, color) offset is a float from 0.0 to 1.0 representing position along the gradient color is a tuple of (r, g, b) values from 0.0 to 1.0	required

Returns:

Type	Description
LinearGradient	A linear gradient pattern.

Example

r = Rectangle(...)
gradient = linear_gradient_pattern(
    0, 0, 100, 100,
    [(0, (1, 0, 0)), (0.5, (0, 1, 0)), (1, (0, 0, 1))]
)
r.fill_pattern = gradient

radial_gradient_pattern

radial_gradient_pattern(cx0, cy0, radius0, cx1, cy1, radius1, stops)

Create a radial gradient pattern that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
cx0	float	X-coordinate of the center of the starting circle	required
cy0	float	Y-coordinate of the center of the starting circle	required
radius0	float	Radius of the starting circle	required
cx1	float	X-coordinate of the center of the ending circle	required
cy1	float	Y-coordinate of the center of the ending circle	required
radius1	float	Radius of the ending circle	required
stops	list[tuple[float, tuple[float, float, float]]]	List of color stops, where each stop is a tuple of (offset, color) offset is a float from 0.0 to 1.0 representing position along the gradient color is a tuple of (r, g, b) values from 0.0 to 1.0	required

Returns:

Type	Description
RadialGradient	A radial gradient pattern.

Example

r = Rectangle(...)
gradient = radial_gradient_pattern(
    50, 50, 0, 50, 50, 50,
    [(0, (1, 1, 1)), (1, (0, 0, 0))]
)
r.fill_pattern = gradient

cross_hatch_pattern

cross_hatch_pattern(size=100, line_width=2, spacing=10, color=(0, 0, 0), direction='forward', freehand=False)

Create a cross-hatching pattern that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
size	int	Size of the pattern tile in pixels	100
line_width	float	Width of the hatching lines	2
spacing	float	Space between hatching lines	10
color	tuple	RGB color tuple for the lines, each value from 0.0 to 1.0	(0, 0, 0)
freehand	bool	If True, uses FreeHandContext for a hand-drawn appearance	False
direction	Literal['forward', 'backward', 'both']	Direction of the hatching lines: "forward" for lines going from bottom-left to top-right "backward" for lines going from top-left to bottom-right "both" for a true cross-hatch pattern with lines going in both directions	'forward'

Returns:

Type	Description
SurfacePattern	A repeating pattern containing the cross-hatch design.

Example

r = Rectangle(...)
pattern = cross_hatch_pattern(size=50, line_width=1, spacing=8, direction="both")
r.fill_pattern = pattern

checker_pattern

checker_pattern(size=100, square_size=10, color1=(1, 1, 1), color2=(0, 0, 0), freehand=False)

Create a checkerboard pattern that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
size	int	Size of the pattern tile in pixels	100
square_size	int	Size of each square in the checkerboard	10
color1	tuple	RGB color tuple for the first set of squares	(1, 1, 1)
color2	tuple	RGB color tuple for the second set of squares	(0, 0, 0)
freehand	bool	If True, uses FreeHandContext for a hand-drawn appearance	False

Returns:

Type	Description
SurfacePattern	A repeating pattern containing the checkerboard design.

Example

r = Rectangle(...)
pattern = checker_pattern(size=64, square_size=8,
                           color1=(1, 1, 1), color2=(0.2, 0.2, 0.2))
r.fill_pattern = pattern

polka_dot_pattern

polka_dot_pattern(size=100, dot_radius=5, spacing=20, dot_color=(0, 0, 0), bg_color=(1, 1, 1), freehand=False)

Create a polka dot pattern that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
size	int	Size of the pattern tile in pixels	100
dot_radius	int	Radius of each dot in pixels	5
spacing	int	Distance between dot centers in pixels	20
dot_color	tuple	RGB color tuple for the dots	(0, 0, 0)
bg_color	tuple	RGB color tuple for the background	(1, 1, 1)
freehand	bool	If True, uses FreeHandContext for a hand-drawn appearance	False

Returns:

Type	Description
SurfacePattern	A repeating pattern containing the polka dot design.

Example

r = Rectangle(...)
pattern = polka_dot_pattern(size=100, dot_radius=4, spacing=20,
                         dot_color=(0.8, 0.2, 0.2), bg_color=(1, 1, 1))
r.fill_pattern = pattern

spiral_pattern

spiral_pattern(size=100, revolutions=5, line_width=2, color=(0, 0, 0), freehand=False)

Create a spiral pattern that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
size	int	Size of the pattern tile in pixels	100
revolutions	int	Number of complete revolutions in the spiral	5
line_width	float	Width of the spiral line	2
color	tuple	RGB color tuple for the spiral	(0, 0, 0)
freehand	bool	If True, uses FreeHandContext for a hand-drawn appearance	False

Returns:

Type	Description
SurfacePattern	A repeating pattern containing the spiral design.

Example

r = Rectangle(...)
pattern = make_spirals(size=150, revolutions=3, line_width=2,
                     color=(0.2, 0.5, 0.8))
r.fill_pattern = pattern

concentric_circle_pattern

concentric_circle_pattern(size=100, num_circles=5, color_stops=[(0, (1, 0, 0)), (1, (0, 0, 1))], freehand=False)

Create a pattern of concentric circles that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
size	int	Size of the pattern tile in pixels	100
num_circles	int	Number of concentric circles to draw	5
color_stops	list[tuple[float, tuple[float, float, float]]]	List of color stops to use for the circles, where each stop is a tuple of (offset, color). The offset is a value from 0.0 to 1.0 representing the position from innermost to outermost circle, and color is an RGB tuple.	[(0, (1, 0, 0)), (1, (0, 0, 1))]
freehand	bool	If True, uses FreeHandContext for a hand-drawn appearance	False

Returns:

Type	Description
SurfacePattern	A repeating pattern containing the concentric circles design.

Example

r = Rectangle(...)
pattern = concentric_circle_pattern(
    size=200,
    num_circles=8,
    color_stops=[(0, (1, 0, 0)), (0.5, (1, 1, 0)), (1, (0, 0, 1))]
)
r.fill_pattern = pattern

stipple_pattern

stipple_pattern(size=100, dot_radius=0.5, density=0.1, dot_color=(0, 0, 0), bg_color=(1, 1, 1), freehand=False)

Create a stippling pattern with randomly distributed dots that can be used as a fill or stroke source.

Parameters:

Name	Type	Description	Default
size	int	Size of the pattern tile in pixels	100
dot_radius	float	Radius of each stipple dot in pixels	0.5
density	float	Density of dots as a fraction from 0.0 to 1.0 (higher means more dots)	0.1
dot_color	tuple[float, float, float]	RGB color tuple for the stipple dots	(0, 0, 0)
bg_color	tuple[float, float, float]	RGB color tuple for the background	(1, 1, 1)
freehand	bool	If True, uses FreeHandContext for a hand-drawn appearance	False

Returns:

Type	Description
SurfacePattern	A repeating pattern containing the stippling design.

Example

r = Rectangle(...)
pattern = stipple_pattern(
    size=150,
    dot_radius=0.8,
    density=0.2,
    dot_color=(0.1, 0.1, 0.1),
    bg_color=(0.95, 0.95, 0.95)
)
r.fill_pattern = pattern