glc.py reference¶

Animation¶

class glc.Animation(*args, **kwargs)¶

Base class for animations.

Shouldn’t be instantiated for the most part. You should instead use Gif, unless you just want a single frame.

Parameters:

width (int) – Width of the drawing surface, in pixels. Defaults to 500.
height (int) – Height of the drawing surface, in pixels. Defaults to 500.
duration (float) – Duration of the animation, in seconds. Defaults to 2.
fps (float) – The frame rate of the animation. Defaults to 30.
ease (string) – The overall easing function of the animation. Defaults to 'sine'.
loop (bool) – Whether the animation should loop. Defaults to True.

render_list¶

RenderList

List of renderables/shapes. It’s what you use to create the actual animation.

set_size(width, height)¶

Changes the size of the drawing surface.

Please note that this creates an entirely new drawing surface/context.

Parameters:	width (int) – New width of the surface. height (int) – New height of the surface.
Returns:	self – For method chaining.
Return type:	`Animation`

set_ease(ease)¶

Sets the overall easing function for this animation.

Parameters:	ease (str) – The easing function to use.
Returns:	self – For method chaining.
Return type:	`Animation`

set_loop(loop=None)¶

Sets the looping mode to the specified value.

If a value for loop is not passed in, then the loop value is toggled - as in, if it’s False, then it will become True. And vice-versa.

Parameters:	loop (bool) – Whether the animation should loop or not.
Returns:	self – For method chaining.
Return type:	`Animation`

set_fps(fps)¶

Sets the frame rate for this animation.

Parameters:	fps (float) – The frame rate to apply.
Returns:	self – For method chaining.
Return type:	`Animation`

set_duration(duration)¶

Sets the duration for this animation.

Parameters:	duration (float) – The duration to apply.
Returns:	self – For method chaining.
Return type:	`Animation`

set_default_style(name, value)¶

Sets a default style to the specified value.

Parameters:	name (str) – The name of the style attribute to change. value (str) – The value to apply.
Returns:	self – For method chaining.
Return type:	`Animation`

set_bg_color(color)¶

Shortcut to set the background color to the specified color.

See the documentation on colors to know what kind of value you should pass as a parameter to this function.

Parameters:	color (`Color`) – The color to use in the background.
Returns:	self – For method chaining.
Return type:	`Animation`

set_emoji_path(path)¶

Defines where the library will try to find emoji images.

The library expects a folder with organization (and filenames) similar to the ones you can get from twemoji, like this: https://github.com/twitter/twemoji/tree/gh-pages/72x72

Parameters:	path (str) – The path to the folder containing the emoji images.
Returns:	self – For method chaining.
Return type:	`Animation`

render()¶

Renders all the necessary frames for this animation to numpy arrays.

Returns:	frames
Return type:	list of numpy arrays

render_at(t)¶

Renders one frame at time t to a numpy array.

Parameters:	t (float) – The time to render at. Should be a value within the range 0.0 to 1.0.
Returns:
Return type:	The rendered frame as a numpy array.

context¶: Shortcut to access the Cairo context of the render list for this animation.

w¶: Shortcut to access the width of the animation.

h¶: Shortcut to access the height of the animation.

class glc.Gif(filename, *args, **kwargs)¶

Animation rendered to a gif file.

This is a subclass of Animation.

Parameters:

filename (str or file-like object) – Where to save this GIF.
color_count (int) – GIF palette size, should be a power of two, and in the 2-256 range. Defaults to 256.
converter (str) –
The converter to use. Right now, there are three converters: - 'imagemagick' - 'imagemagick_tempfiles' - 'imageio'

The imagemagick[_tempfiles] converters are the only ones that support transparent gifs.

Defaults to 'imageio'.
converter_opts (dict) – Dictionary with extra options for the converters.

set_converter_opts(**kwargs)¶: Sets the options for the current converter.

save()¶

Writes this animation to a GIF file.

Uses the specified converter, unless that doesn’t exist, in which case imageio is the default.

save_with_imagemagick_tempfiles(frames)¶

Writes this animation to a GIF file using ImageMagick, using temporary files.

This converter supports transparent backgrounds. This saves every frame to a temporary file.

Parameters:	frames (list of numpy arrays) – Container with the frames necessary to render this animation to a file.
Returns:
Return type:	Image file as bytes

save_with_imagemagick(frames)¶

Writes this animation to a GIF file using ImageMagick and FFmpeg.

This converter supports transparent backgrounds. This uses piping to avoid temporary files.

Parameters:	frames (list of numpy arrays) – Container with the frames necessary to render this animation to a file.
Returns:
Return type:	Image file as bytes

save_with_imageio(frames)¶

Writes this animation to a GIF file using imageio.

This converter does not support transparent backgrounds.

Parameters:	frames (list of numpy arrays) – Container with the frames necessary to render this animation to a file.
Returns:
Return type:	Image file as bytes

class glc.ImageSequence(filename_pattern, *args, **kwargs)¶

Animation rendered to a sequence of image files.

This is a subclass of Animation.

Parameters:	filename_pattern (str) – Format string that specifies what path should the images be saved in. Values passed to this format string: frame Frame index. Generally a good idea to pad it with zeroes, i.e. `'thing_{frame:04d}.png'` converter (str) – The converter to use. Right now, there’s one converter: `'imageio'` Defaults to `'imageio'`.

save()¶

Saves this animation to disk as a sequence of image files.

Returns:
Return type:	List with the paths of the generated files.

save_with_imageio(frame)¶

Encodes the given frame to an image file using imageio.

Parameters:	frame (numpy array) – Frame to encode
Returns:
Return type:	Image file as bytes

Rendering¶

class glc.RenderList(*args, **kwargs)¶

List of renderables/shapes.

Parameters:

width (int) – Width of the drawing surface, in pixels. Defaults to 500.
height (int) – Height of the drawing surface, in pixels. Defaults to 500.
default_styles (dict) – Default styling for shapes.
ease (string) – The overall easing function of the animation. Defaults to 'sine'.
loop (bool) – Whether the animation should loop. Defaults to True.
emoji_path (string) – Where the emoji pngs are located. Defaults to None.
before_render (callable) – A function that takes in this render list, a Cairo surface, context, and a time t. It’s called before all shapes are rendered. Defaults to None.
after_render (callable) – A function that takes in this render list, a Cairo surface, context, and a time t. It’s called after all shapes are rendered. Defaults to None.

surface¶

cairo.ImageSurface

Memory buffer for storing drawings onto.

context¶

cairo.Context

Drawing context.

shapes¶

list of Shape

The list of shapes to render.

size(width=500, height=500)¶

Changes the size of the surface.

Please note that this creates an entirely new surface/context.

Parameters:	width (int) – New width of the surface. height (int) – New height of the surface.
Returns:	(width, height)
Return type:	tuple of int

add(shape)¶

Adds a shape to the list.

Parameters:	shape (`Shape`) –
Returns:	shape – The added shape.
Return type:	`Shape`

render(t)¶

Returns an image (frame) of this render list at time t.

Parameters:	t (float) – Specifies at what point in time this list should be rendered in.
Returns:	buf – The frame as a numpy array.
Return type:	array

Colors¶

class glc.color.Color(r=None, g=None, b=None, a=None)¶

Represents a color value.

All the color components here go from 0.0 to 1.0.

r¶: float

g¶: float

b¶: float

a¶: float

set_rgba(r, g, b, a=1.0)¶

Sets the current rgba values to the passed in ones.

All the color components here should go from 0.0 to 1.0. If no value for alpha (a) is passed in, then 1.0 is used as the default.

Parameters:	r (float) – g (float) – b (float) – a (float) –
Returns:	For method chaining.
Return type:	self

set_int(color)¶

Sets the current color value based on the passed in integer.

Parameters:	color (int) – Normally passed in as a hex literal (i.e. 0xffff0000). The format expected is AARRGGBB.
Returns:	For method chaining.
Return type:	self

desaturate(amount=10)¶

Desaturates this color by the given amount (a delta).

Parameters:	amount (float) – Amount to desaturate this color by. Should go from 0.0 to 100.0.
Returns:	For method chaining.
Return type:	self

saturate(amount=10)¶

Saturates this color by the given amount (a delta).

Parameters:	amount (float) – Amount to saturate this color by. Should go from 0.0 to 100.0.
Returns:	For method chaining.
Return type:	self

grayscale()¶

Desaturates this color until it is a shade of gray.

Returns:	For method chaining.
Return type:	self

lighten(amount=10)¶

Lightens up this color by the given amount (a delta).

Parameters:	amount (float) – Amount to lighten this color by. Should go from 0.0 to 100.0.
Returns:	For method chaining.
Return type:	self

darken(amount=10)¶

Darkens up this color by the given amount (a delta).

Parameters:	amount (float) – Amount to darken this color by. Should go from 0.0 to 100.0.
Returns:	For method chaining.
Return type:	self

in_hsv()¶: Returns this color in HSV, as a tuple.

in_hsl()¶: Returns this color in HSL, as a tuple.

in_int()¶: Returns this color as a single integer, in the format AA RR GG BB.

hexstr()¶: Returns this color as a hex string, in the format AA RR GG BB, with no leading character - such as # or 0x.

brightness()¶

Returns the overall brightness for this color.

Adapted from http://www.w3.org/TR/AERT#color-contrast

luminance()¶

Returns the overall luminance for this color.

Adapted from http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef

Colorspace converters¶

glc.color.rgb2hsv(red, green, blue)¶

Converts a color from RGB to HSV.

All the color components here should go from 0.0 to 1.0.

Parameters:	red (float) – green (float) – blue (float) –
Returns:	(hue, saturation, value)
Return type:	tuple with 3 floats

glc.color.hsv2rgb(hue, saturation, value)¶

Converts a color from HSV to RGB.

All the color components here should go from 0.0 to 1.0, except for hue, which should go from 0.0 to 360.

Parameters:	hue (float) – saturation (float) – value (float) –
Returns:	(red, green, blue)
Return type:	tuple with 3 floats

glc.color.rgb2hsl(red, green, blue)¶

Converts a color from RGB to HSL.

All the color components here should go from 0.0 to 1.0.

Parameters:	red (float) – green (float) – blue (float) –
Returns:	(hue, saturation, lightness)
Return type:	tuple with 3 floats

glc.color.hsl2rgb(hue, saturation, lightness)¶

Converts a color from HSV to RGB.

All the color components here should go from 0.0 to 1.0, except for hue, which should go from 0.0 to 360.

Parameters:	hue (float) – saturation (float) – lightness (float) –
Returns:	(red, green, blue)
Return type:	tuple with 3 floats

Shortcuts¶

glc.color.rgba(red, green, blue, alpha=1.0)¶

Creates a color using the passed in red, green, blue and alpha values.

All the color components here should go from 0.0 to 1.0.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.hsva(hue, saturation, value, alpha=1.0)¶

Creates a color using hue, saturation, value and alpha.

All the color components here should go from 0.0 to 1.0, except for hue, which should go from 0.0 to 360.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.gray(shade, alpha=1.0)¶

Creates a shade of gray.

All the color components here should go from 0.0 to 1.0.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.random_rgba(min_red, max_red, min_green, max_green, min_blue, max_blue, min_alpha=None, max_alpha=None)¶

Creates a random color using the passed in ranges for red, green, blue and alpha.

All the color components here should go from 0.0 to 1.0.

If min_alp and max_alp are left as None, then alpha is simply set to 1.0.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.random_hsva(min_hue, max_hue, min_saturation, max_saturation, min_value, max_value, min_alpha=None, max_alpha=None)¶

Creates a random color using the passed in ranges for hue, saturation, value and alpha.

All the color components here should go from 0.0 to 1.0, except for hue, which should go from 0.0 to 360.

If min_alp and max_alp are left as None, then alpha is simply set to 1.0.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.random_gray(min_shade, max_shade, min_alpha=None, max_alpha=None)¶

Creates a random shade of grey.

All the color components here should go from 0.0 to 1.0.

If min_alp and max_alp are left as None, then alpha is simply set to 1.0.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.name2color(name)¶

Creates a color based on a name.

If the passed in name is not recognized, black is returned.

The recognized names can be found here: https://en.wikipedia.org/wiki/X11_color_names

Returns:	color – A Color object.
Return type:	`Color`

glc.color.xkcd2color(name)¶

Creates a color based on a name from this list: https://xkcd.com/color/rgb/

If the passed in name is not recognized, black is returned.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.str2color(string)¶

Creates a color based on a string.

Parameters:

color (str) –

Can be one of the following:

Color value in base 16/hex.

The format is [#/0x][[A]A]R[R]G[G]B[B].
If you pass just one digit for each color value, the value is used twice (e.g. for R G B, the digits are duplicated so it becomes RR GG BB).

Alpha is optional, and so are the 0x/# hex identifiers.

CSS/X11 color name

(see https://en.wikipedia.org/wiki/X11_color_names)

XKCD color name

(see https://xkcd.com/color/rgb/)

The possible values here are ordered by check order - that is, hex literals are checked first, then X11 color names, then XKCD ones.

Returns: color – A Color object.

Return type: Color

glc.color.int2color(color)¶

Creates a color based on an integer.

Parameters:	color (int) – Usually you’ll want to pass a hex literal (e.g. `0xFFFF00AE`). The expected format is AARRGGBB.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.sinebow(offset, freq0, freq1, freq2, phase0, phase1, phase2, center=128, width=127)¶

Returns a color based on a ‘sinebow’.

See http://krazydad.com/tutorials/makecolors.php for more info.

Returns:	color – A Color object.
Return type:	`Color`

glc.color.hue_split(base_color, split_num=6)¶

Returns variations of a color by moving its hue around the “color wheel”.

Parameters:	base_color (`Color`) – The color to split by hue. split_num (int) – How many times this color should be split around the color wheel.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.complementaries(base_color)¶

Returns colors that are opposite each other on the color wheel.

Parameters:	base_color (`Color`) – The color to find the complementary of.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.split_complementaries(base_color, angle=30)¶

Returns the base color and two colors adjacent to its complement.

Parameters:	base_color (`Color`) – The color to find the complementaries of.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.triads(base_color)¶

Returns 3 colors that are evenly spaced around the color wheel.

Parameters:	base_color (`Color`) – The color to base the traids from.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.tetrads(base_color)¶

Returns four colors arranged into two complementary pairs.

Parameters:	base_color (`Color`) – The color to base the tetrads from.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.pentads(base_color)¶

Returns 5 colors arranged into a pentagon on the color wheel.

Parameters:	base_color (`Color`) – The color to base the pentads from.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.hexads(base_color)¶

Returns 6 colors arranged into a hexagon on the color wheel.

Parameters:	base_color (`Color`) – The color to base the hexads from.
Returns:	color – A Color object.
Return type:	`Color`

Misc.¶

glc.color.clerp(t, color_a, color_b)¶

Linearly interpolates from color_a to color_b by t.

Parameters:	t (float) – A number from 0.0 to 1.0. color_a (`Color`) – The color to interpolate from. color_b (`Color`) – The color to interpolate to.
Returns:	color – A Color object.
Return type:	`Color`

glc.color.multi_clerp(t, *colors)¶

Linearly interpolates between an array of colors by t.

Parameters:	t (float) – A number from 0.0 to 1.0. colors (iterable with `Color` objects) – The colors to interpolate.
Returns:	color – A Color object.
Return type:	`Color`

Utilities¶

glc.utils.deg()¶

degrees(x)

Convert angle x from radians to degrees.

glc.utils.rad()¶

radians(x)

Convert angle x from degrees to radians.

glc.utils.randrange(start, end)¶

Returns a random float in the range defined by start and end.

Returns:	The random value.
Return type:	float

glc.utils.clamp(value, start, end)¶

Limits a value to the passed in range.

If value is less than start, start is returned. If value is greater than end, end is returned. Otherwise, value is returned.

Returns:	The clamped value.
Return type:	float

glc.utils.norm(value, start, end)¶

Normalizes a value in the range specified by start and end to the range 0-1.

Returns:	The normalized value.
Return type:	float

glc.utils.remap(value, src_min, src_max, dst_min, dst_max)¶

Maps a value from a source range to a target range.

Returns:	The remapped value.
Return type:	float

glc.utils.lerp(t, start, end)¶

Linearly interpolates from start to end by t.

Returns:	The interpolated value.
Return type:	float

glc.utils.bezier(v, x0, x1, x2, x3)¶

Returns a point for a given v value on the specified cubic bézier path.

Returns:	The point on the 1D path.
Return type:	float

glc.utils.quadratic(v, x0, x1, x2)¶

Returns a point for a given v value on the specified quadratic bézier path.

Returns:	The point on the 1D path.
Return type:	float

glc.utils.catmull_rom(v, x0, x1, x2, x3)¶

Returns a point for a given v value on the specified Catmull-Rom spline.

Returns:	The point on the 1D path.
Return type:	float

glc.utils.spline(v, x0, x1, x2, x3, tightness=1)¶

glc.utils.hermite(v, x0, x1, x2, x3)¶

Returns a value v interpolated using hermite interpolation.

Returns:	The interpolated value.
Return type:	float

glc.utils.cosine(value, start, end)¶

Interpolates a value from start to end using cosine interpolation.

Returns:	The interpolated value.
Return type:	float

glc.utils.smoothstep(value, start, end)¶

Interpolate a value from start to end using the smoothstep function.

See https://en.wikipedia.org/wiki/Smoothstep

Returns:	The interpolated value.
Return type:	float

glc.utils.smootherstep(value, start, end)¶

Interpolate a value from start to end using the smootherstep function.

See https://en.wikipedia.org/wiki/Smoothstep#Variations

Returns:	The interpolated value.
Return type:	float

glc.utils.quantize(value, tick)¶

Rounds the given value to the nearest multiple of tick.

Returns:	The quantized value.
Return type:	float

glc.utils.distribute(divisions, start=0, end=1, inclusive=False)¶

Returns a range of values between start and end, divided in the wanted amount of pieces.

Parameters:	divisions (int) – How many pieces should the range be broken in. start (float) – The value to start at. end (float) – The value to end at. inclusive (bool) – Whether the end should be included in the distribution.
Returns:	The distribution of values.
Return type:	Generator of floats

glc.utils.pick_closest(n, l)¶

Pick a value from an iterable l at index n, which is “snapped back” to a valid index.

Parameters:	n (int) – Index to round. l (iterable) – Iterable to pick a value from.
Returns:	Whatever was at the picked index in the iterable.
Return type:	Iterable element

glc.utils.bgra_to_rgba(surface)¶

Converts a Cairo surface color format from BGRA to RGBA, using Pillow/PIL.

On little-endian machines, Cairo’s surface format becomes BGRA instead of RGBA. When creating numpy arrays with the data from the surface, the colors end up wrong if we don’t do this conversion.

Adapted from http://www.pygame.org/wiki/CairoPygame (thanks!)

Parameters:	surface (`cairo.Surface`) – The cairo surface to convert.
Returns:	img_bytes – The image in bytes.
Return type:	bytes object

glc.utils.draw_image(ctx, img, x, y, w=None, h=None)¶

Draws an image on a given Cairo context.

If given explicit width and height, the image is resized to fit those dimensions, without any regard for maintaining aspect ratio or anything like that.

If you want that kind of behavior, you’ll have to calculate the desired width and height a priori.

Parameters:	ctx (`cairo.Context`) – The context to draw an image on. img (`cairo.Surface`) – The image (as a Cairo surface) to draw. x (float) – Horizontal position to draw the image on. y (float) – Vertical position to draw the image on. w (float) – Target width for the image. h (float) – Target height for the image.

glc.utils.quadratic_curve_to(context, x1, y1, x2, y2)¶

Adds a quadratic Bézier spline to the path from the current point to position (x2, y2) in user-space coordinates, using (x1, y1) as the control point.

After this call the current point will be (x2, y2).

If there is no current point before the call to curve_to() this method will behave as if preceded by a call to context.move_to(x1, y1).

Parameters:	context (`cairo.Context`) – The context to draw on. x2 (float) – The X coordinate of the first control point. y2 (float) – The Y coordinate of the first control point. x3 (float) – The X coordinate of the end of the curve. y3 (float) – The Y coordinate of the end of the curve.

glc.utils.curve_path(context, points, loop=False)¶

Defines a path with multiple points connected by quadratic bézier curves.

Parameters:	context (`cairo.Context`) – The context to draw a curve on. points (list of tuples/lists) – Specifies the coordinates to plot the curve with. loop (bool) – Specifies whether the path should be closed by connecting the first point with the last one or not. Defaults to `False`.

glc.utils.arc_to(context, x1, y1, x2, y2, r)¶

Adds an arc to the path with the given control points and radius, connected to the previous point by a straight line.

After this call the current point will be (x2, y2).

Parameters:

context (cairo.Context) – The context to draw on.
x1 (float) – The x axis of the coordinate for the first control point.
y1 (float) – The y axis of the coordinate for the first control point.
x2 (float) – The x axis of the coordinate for the second control point.
y2 (float) – The y axis of the coordinate for the second control point.
radius (float) – The arc’s radius.