celiagg API documentation

Canvas Classes

There are many canvas classes which all have a common interface. The difference between the classes is the color format of the destination frame buffer. The list of available canvas classes follows this documentation of CanvasRGBA32 which covers the interface:

class celiagg.CanvasRGBA32(array, bottom_up=False, font_cache=None)

Provides AGG (Anti-Grain Geometry) drawing routines that render to the numpy array passed as the constructor argument. Because this array is modified in place, it must be of type numpy.uint8, must be C-contiguous, and must be MxNx4 (4 channels: red, green, blue, and alpha).

Parameters

  • array – A numpy.uint8 array with shape (H, W, 4).

  • bottom_up – If True, the origin is the bottom left, instead of top-left

  • font_cache – A FontCache instance. Defaults to a global instance.

class celiagg._celiagg.CanvasRGBA32
clear(r, g, b, a)

Fill the canvas with a single RGBA value

Parameters

  • r – Red value in [0, 1]

  • g – Green value in [0, 1]

  • b – Blue value in [0, 1]

  • a – Alpha value in [0, 1] (defaults to 1.0)

draw_image(image, format, transform, state, bottom_up=False)

Draw an image on the canvas.

Parameters

  • image – A 2D or 3D numpy array containing image data

  • format – A PixelFormat describing the array’s data

  • transform – A Transform object

  • state – A GraphicsState object

  • bottom_up – If True, the image data is flipped in the y axis

draw_shape(shape, transform, state, stroke=SolidColor(0, 0, 0), fill=SolidColor(0, 0, 0))

Draw a shape on the canvas.

Note

Use GraphicsState.drawing_mode to enable/disable stroke or fill drawing.

Parameters

  • shape – A VertexSource object

  • transform – A Transform object

  • state – A GraphicsState object

  • stroke – The Paint to use for outlines. Defaults to black.

  • fill – The Paint to use for fills. Defaults to black.

draw_shape_at_points(shape, points, transform, state, stroke=SolidColor(0, 0, 0), fill=SolidColor(0, 0, 0))

Draw a shape at multiple points on the canvas.

Note

Use GraphicsState.drawing_mode to enable/disable stroke or fill drawing.

Parameters

  • shape – A VertexSource object

  • points – A sequence of (x, y) pairs where the shape should be drawn.

  • transform – A Transform object

  • state – A GraphicsState object

  • stroke – The Paint to use for outlines. Defaults to black.

  • fill – The Paint to use for fills. Defaults to black.

draw_text(text, font, transform, state, stroke=SolidColor(0, 0, 0), fill=SolidColor(0, 0, 0))

Draw a line of text on the canvas.

Note

Use GraphicsState.drawing_mode to enable/disable stroke or fill drawing.

Parameters

  • text – A Unicode string of text to be renderered. Newlines will be ignored.

  • font – A Font object

  • transform – A Transform object

  • state – A GraphicsState object

  • stroke – The Paint to use for outlines. Defaults to black.

  • fill – The Paint to use for fills. Defaults to black.

class celiagg.CanvasG8(array, bottom_up=False, font_cache=None)

Provides AGG (Anti-Grain Geometry) drawing routines that render to the numpy array passed as the constructor argument. Because this array is modified in place, it must be of type numpy.uint8, must be C-contiguous, and must be MxN (1 channel: intensity).

Parameters

  • array – A numpy.uint8 array with shape (H, W).

  • bottom_up – If True, the origin is the bottom left, instead of top-left

  • font_cache – A FontCache instance. Defaults to a global instance.

class celiagg.CanvasGA16(array, bottom_up=False, font_cache=None)

Provides AGG (Anti-Grain Geometry) drawing routines that render to the numpy array passed as the constructor argument. Because this array is modified in place, it must be of type numpy.uint8, must be C-contiguous, and must be MxNx2 (2 channels: intensity and alpha).

Parameters

  • array – A numpy.uint8 array with shape (H, W, 2).

  • bottom_up – If True, the origin is the bottom left, instead of top-left

  • font_cache – A FontCache instance. Defaults to a global instance.

class celiagg.CanvasRGB24(array, bottom_up=False, font_cache=None)

Provides AGG (Anti-Grain Geometry) drawing routines that render to the numpy array passed as the constructor argument. Because this array is modified in place, it must be of type numpy.uint8, must be C-contiguous, and must be MxNx3 (3 channels: red, green, and blue).

Parameters

  • array – A numpy.uint8 array with shape (H, W, 3.

  • bottom_up – If True, the origin is the bottom left, instead of top-left

  • font_cache – A FontCache instance. Defaults to a global instance.

class celiagg.CanvasBGRA32(array, bottom_up=False, font_cache=None)

Provides AGG (Anti-Grain Geometry) drawing routines that render to the numpy array passed as the constructor argument. Because this array is modified in place, it must be of type numpy.uint8, must be C-contiguous, and must be MxNx4 (4 channels: blue, green, red, and alpha).

Parameters

  • array – A numpy.uint8 array with shape (H, W, 4).

  • bottom_up – If True, the origin is the bottom left, instead of top-left

  • font_cache – A FontCache instance. Defaults to a global instance.

class celiagg.CanvasRGBA128(array, bottom_up=False, font_cache=None)

Provides AGG (Anti-Grain Geometry) drawing routines that render to the numpy array passed as the constructor argument. Because this array is modified in place, it must be of type numpy.float32, must be C-contiguous, and must be MxNx4 (2 channels: red, green, blue, and alpha).

Parameters

  • array – A numpy.float32 array with shape (H, W, 4).

  • bottom_up – If True, the origin is the bottom left, instead of top-left

  • font_cache – A FontCache instance. Defaults to a global instance.

Drawing State Container Classes

There are a handful of objects which contain state or data useful to the various drawing methods of Canvas. GraphicsState and Transform for example, are passed to every drawing method. Image instances can either be drawn directly on a Canvas, or supplied to PatternPaint to serve as a repeating fill pattern. Finally, Font determines the font used when drawing text. And FontCache is used internally by the canvas classes to cache glyphs for the purpose of faster text rendering. Additionally, FontCache can be used to measure the width of a rendered string.

class celiagg.GraphicsState(**properties)

A container for drawing state. Can be initialized using keyword arguments and works as a namespace for the following properties:

  • anti_aliased: A boolean denoting whether drawing is anti-aliased or not.

  • drawing_mode: A DrawingMode value denoting the drawing mode.

  • text_drawing_mode: A TextDrawingMode value denoting the text drawing

    mode.

  • blend_mode: A BlendMode for non-image drawing. (ignored)

  • image_blend_mode: A BlendMode for image drawing. (ignored)

  • line_cap: A LineCap value denoting the style of line ends.

  • line_join: A LineJoin value denoting the style of joins.

  • inner_join: An InnerJoin value denoting the style of inner joins.

  • miter_limit: The miter limit

  • inner_miter_limit: The miter limit for inner joins

  • master_alpha: A master opacity value.

  • line_width: The width when stroking lines.

  • clip_box: A Rect which defines a simple clipping area.

  • line_dash_pattern: A sequence of (dash length, gap length) pairs.

  • line_dash_phase: Where in line_dash_pattern to start, when drawing.

  • stencil: An Image with format Gray8 which will mask any drawing.

    The dimensions must match the size of the canvas that is being drawn to.

class celiagg.Image(array, pixel_format, bottom_up=False)
Parameters

  • image – A 2D or 3D numpy array containing image data

  • pixel_format – A PixelFormat describing the image’s pixel format

  • bottom_up – If True, the image data starts at the bottom of the image

class celiagg.FontCache

An object which manages a render cache of glyphs.

width(font, text)

Measures the width of a string rendered with font.

Parameters

  • font – a Font instance

  • text – a unicode string

class celiagg.Font(path, size, face_index=0)
Parameters

  • path – A Unicode string containing the path of a Font file

  • size – The size of the font

  • face_index – For .ttc fonts, the index of the desired font within the collection.

class celiagg.Rect(x, y, w, h)

A rectangle.

Parameters

  • x – The X coordinate of the top left corner

  • y – The Y coordinate of the top left corner

  • w – The width of the rectangle in pixels

  • h – The height of the rectangle in pixels

class celiagg.Transform(sx=1.0, shy=0.0, shx=0.0, sy=1.0, tx=0.0, ty=0.0)

A 2D affine transform.

After construction, the same names can be used as get/set properties for individual components of the transform.

NOTE: If you’re familar with SVG, you’ll notice the format of this constructor. The arguments are exactly the same as the SVG matrix attribute.

Parameters

  • sx – Scale X

  • shy – Shear/Skew Y

  • shx – Shear/Skew X

  • sy – Scale Y

  • tx – Translation X

  • ty – Translation Y

copy()

Returns a deep copy of the object.

invert()

Inverts the matrix.

multiply(other)

Post-multiply this transform with another transform.

Parameters

other – A Transform instance to multiply

premultiply(other)

Pre-multiply this transform with another transform.

Parameters

other – A Transform instance to premultiply

reset()

Resets to the identity transform.

rotate(angle)

Apply a rotation to the transform.

Parameters

angle – The desired rotation in radians.

scale(x, y)

Apply a scaling to the transform

Parameters

  • x – The scale factor in X

  • y – The scale factor in Y

screenToWorld(x, y)

Transforms a point from screen space to world space.

Parameters

  • x – The X coordinate of the point to transform.

  • y – The Y coordinate of the point to transform.

Returns

An (x, y) tuple containing the transformed point.

skew(x, y)

Apply a skew to the transform.

Parameters

  • x – The skew factor in X

  • y – The skew factor in Y

translate(x, y)

Apply a translation to the transform.

Parameters

  • x – The translation in X

  • y – The translation in Y

worldToScreen(x, y)

Transforms a point from world space to screen space.

Parameters

  • x – The X coordinate of the point to transform.

  • y – The Y coordinate of the point to transform.

Returns

An (x, y) tuple containing the transformed point.

Paint Classes

The Paint classes determine the look of strokes and fills. Canvas.draw_shape* and Canvas.draw_text both accept optional arguments for fill and stroke Paint arguments. The currently available options are solid colors, gradients, or image patterns.

class celiagg.LinearGradientPaint(x1, y1, x2, y2, stops, spread, units)

A Paint for drawing linear gradients

Parameters

  • x1 – Gradient start point X

  • y1 – Gradient start point Y

  • x2 – Gradient end point X

  • y2 – Gradient end point Y

  • stops – An iterable of gradient stop tuples: (offset, r, g, b, a)

  • spread – The GradientSpread type for this gradient

  • units – The GradientUnits type for this gradient

class celiagg.RadialGradientPaint(cx, cy, r, fx, fy, stops, spread, units)

A Paint for drawing radial gradients

Parameters

  • cx – Gradient center point X

  • cy – Gradient center point Y

  • r – Gradient radius

  • fx – Gradient focus point X

  • fy – Gradient focus point Y

  • stops – An iterable of gradient stop tuples: (offset, r, g, b, a)

  • spread – The GradientSpread type for this gradient

  • units – The GradientUnits type for this gradient

class celiagg.PatternPaint(style, image)

A Paint for repeating patterns.

Parameters

  • style – A PatternStyle

  • image – An Image object

class celiagg.SolidPaint(r, g, b, a)

A Paint for solid colors.

Parameters

  • r – Red value in [0, 1]

  • g – Green value in [0, 1]

  • b – Blue value in [0, 1]

  • a – Alpha value in [0, 1] (defaults to 1.0)

VetexSource Classes

The VertexSource (an internal base class) classes contain geometry data which can be drawn using the Canvas.draw_shape* methods.

class celiagg.BSpline(points)

A B-Spline curve.

Parameters

points – 2D array of (x, y) pairs

bounding_rect()

Returns a bounding rectangle for the vertices of the source in the format: (x, y, w, h)

copy()

Returns a deep copy of the object.

final_point()

Returns the last vertex that will be returned by the source.

length()

Returns the number of vertices returned by vertices()

vertices()

Returns all the vertices in the source as a numpy array.

class celiagg.Path

A path object.

add_path(other)

Add another path to this path.

Parameters

other – A Path object which will be concatenated onto the end of this path.

arc(x, y, radius, start_angle, end_angle, clockwise)

Adds an arc to the path.

Parameters

  • x – Center X coordinate of the arc

  • y – Center Y coordinate of the arc

  • radius – Radius of the arc

  • start_angle – Starting angle, in radians

  • end_angle – Ending angle, in radians

  • clockwise – If True, the arc is drawn in a clockwise direction

arc_to(x1, y1, x2, y2, radius)

Adds an arc to the path connecting two points

Parameters

  • x1 – The starting X point of the arc

  • y1 – The starting Y point of the arc

  • x2 – The end X point of the arc

  • y2 – The end Y point of the arc

  • radius – The radius of the arc

begin()

Begins a new subpath.

bounding_rect()

Returns a bounding rectangle for the vertices of the source in the format: (x, y, w, h)

close()

Closes the current subpath.

copy()

Returns a deep copy of the object.

cubic_to(x_ctrl1, y_ctrl1, x_ctrl2, y_ctrl2, x_to, y_to)

Adds a cubic Bezier curve to the path, starting from the current pen position.

Parameters

  • x_ctrl1 – First control point X

  • y_ctrl1 – First control point Y

  • x_ctrl2 – Second control point X

  • y_ctrl2 – Second control point Y

  • x_to – End point X

  • y_to – End point Y

ellipse(cx, cy, rx, ry)

Adds an ellipse to the path.

Parameters

  • cx – Center X coordinate of the ellipse

  • cy – Center Y coordinate of the ellipse

  • rx – Ellipse radii x dimension.

  • ry – Ellipse radii y dimension.

final_point()

Returns the last vertex that will be returned by the source.

length()

Returns the number of vertices returned by vertices()

line_to(x, y)

Adds a line segment to the path from the current position to the given position.

Parameters

  • x – X coordinate of the line end point

  • y – Y coordinate of the line end point

lines(points)

Adds multiple connected line segmests to the path.

Parameters

points – 2D array of (x, y) pairs

lines_set(starts, ends)

Adds multiple disconnected line segments to the path.

Parameters

  • starts – 2D array of (x, y) pairs

  • ends – 2D array of (x, y) pairs

move_to(x, y)

Moves the current position of the path.

Parameters

  • x – X coordinate of the new current position

  • y – Y coordinate of the new current position

quadric_to()

Adds a quadratic Bezier curve to the path, starting from the current position.

Parameters

  • x_ctrl – Control point X

  • y_ctrl – Control point Y

  • x_to – End point X

  • y_to – End point Y

rect(x, y, width, height)

Adds a rectangle to the path.

Parameters

  • x – Rectangle X position

  • y – Rectangle Y position

  • width – Rectangle widtht

  • height – Rectangle height

rects(rects)

Adds multiple rectangles to the path.

Parameters

rects – 2D array of (x, y, w, h) sequences

reset()

Clears the path.

vertices()

Returns all the vertices in the source as a numpy array.

class celiagg.ShapeAtPoints(source, points)

Replicates a shape at mutiple points.

Parameters

  • source – A VertexSource object (BSpline, Path, etc.)

  • points – A sequence of (x, y) pairs where the shape defined by source should be drawn.

bounding_rect()

Returns a bounding rectangle for the vertices of the source in the format: (x, y, w, h)

copy()

Returns a deep copy of the object.

final_point()

Returns the last vertex that will be returned by the source.

length()

Returns the number of vertices returned by vertices()

vertices()

Returns all the vertices in the source as a numpy array.

Functions

celiagg.example_font()

Returns the path to a TTF font which is included with the library for testing purposes.

Enumerations

BlendMode

NOTE: The various blend modes are currently ignored.

  • BlendAlpha

  • BlendClear

  • BlendSrc

  • BlendDst

  • BlendSrcOver

  • BlendDstOver

  • BlendSrcIn

  • BlendDstIn

  • BlendSrcOut

  • BlendDstOut

  • BlendSrcAtop

  • BlendDstAtop

  • BlendXor

  • BlendAdd

  • BlendMultiply

  • BlendScreen

  • BlendOverlay

  • BlendDarken

  • BlendLighten

  • BlendColorDodge

  • BlendColorBurn

  • BlendHardLight

  • BlendSoftLight

  • BlendDifference

  • BlendExclusion

DrawingMode

Drawing mode: outline (stroke) only, fill only, or a combination. The Eof fill variations use the even-odd rule when filling self-intersecting curves.

  • DrawFill

  • DrawEofFill

  • DrawStroke

  • DrawFillStroke

  • DrawEofFillStroke

GradientSpread

How a gradient behaves at its boundaries. Pad means that the colors at the ends of a gradient extend to infinity. Reflect sweeps back and forth over a gradient, and Repeat starts over at the first color after getting to the end of a gradient.

  • SpreadPad

  • SpreadReflect

  • SpreadRepeat

GradientUnits

How the coordinates of a gradient object are interpreted. UserSpace means the local transform (the Transform passed to the draw method) affects the gradient coordinates. ObjectBoundingBox means the coordinates are interpreted as relative values (percentages) within the bounding box of the VertexSource object currently being drawn.

NOTE: This is identical to how SVG handles gradients. See https://www.w3.org/TR/SVG/pservers.html for a more lucid description.

  • UserSpace

  • ObjectBoundingBox

InnerJoin

  • InnerBevel

  • InnerMiter

  • InnerJag

  • InnerRound

LineCap

  • CapButt

  • CapSquare

  • CapRound

LineJoin

  • JoinMiter

  • JoinRound

  • JoinBevel

PatternStyle

Similar to GradientSpread, patterns can either reflect or repeat.

  • StyleRepeat

  • StyleReflect

PixelFormat

  • Gray8

  • Gray16

  • Gray32

  • BGR24

  • RGB24

  • BGR48

  • RGB48

  • BGR96

  • RGB96

  • BGRA32

  • RGBA32

  • ARGB32

  • ABGR32

  • BGRA64

  • RGBA64

  • ARGB64

  • ABGR64

  • BGRA128

  • RGBA128

  • ARGB128

  • ABGR128

TextDrawingMode

  • TextDrawInvisible

  • TextDrawFill

  • TextDrawStroke

  • TextDrawClip

  • TextDrawRaster

  • TextDrawFillStroke

  • TextDrawFillClip

  • TextDrawStrokeClip

  • TextDrawFillStrokeClip

Miscellaneous

exception celiagg.AggError