Kiva Interface Quick Reference

This document is a summary of the classes and functions available in Kiva. More specifically, it describes some of the details of the kiva.agg backend, including enumerated types and helper classes.

Graphics Context

Construction

__init__(ary_or_size, pix_format=”bgra32”, base_pixel_scale=1.0):

ary_or_size can be either a numpy array or a tuple of the form (width, height). If it is an array, it will be used as the backing store for the pixels. Its shape must be compatible with pix_format

pix_format determines the pixel format and is a string which can be any of the following: “gray8”, “rgb24”, “bgr24”, “rgba32”, “argb32”, “abgr32”, “bgra32”.

base_pixel_scale is scaling factor which will be applied to the transformation matrix before all other transformations. It is used for rendering to high-resolution displays.

State functions

Saving and restoring state

In addtion to the save_state and restore_state methods, it is also possible to use a GraphicsContext instance as a context manager.

abstract AbstractGraphicsContext.save_state()

Push the current graphics state onto the stack

abstract AbstractGraphicsContext.restore_state()

Pop the previous graphics state from the stack

Methods controlling state

abstract AbstractGraphicsContext.set_fill_color(color)

Set the color used to fill the region bounded by a path or when drawing text.

Parameters

color – A three or four component tuple describing a color (R, G, B[, A]). Each color component should be in the range [0.0, 1.0]

abstract AbstractGraphicsContext.get_fill_color()

Get the color used to fill the region bounded by a path or when drawing text.

abstract AbstractGraphicsContext.set_stroke_color(color)

Set the color used when stroking a path

Parameters

color – A three or four component tuple describing a color (R, G, B[, A]). Each color component should be in the range [0.0, 1.0]

abstract AbstractGraphicsContext.get_stroke_color()

Get the current color used when stroking a path

abstract AbstractGraphicsContext.set_line_width(width)

Set the width of the pen used to stroke a path

abstract AbstractGraphicsContext.set_line_join(line_join)

Set the style of join to use a path corners

Parameters

line_join – Options are JOIN_ROUND, JOIN_BEVEL, or JOIN_MITER. Each is defined in kiva.api.

abstract AbstractGraphicsContext.set_line_cap(line_cap)

Set the style of cap to use a path ends

Parameters

line_cap – One of CAP_BUTT, CAP_ROUND, or CAP_SQUARE. Each is defined in kiva.api.

abstract AbstractGraphicsContext.set_line_dash(line_dash, phase=0)

Set the dash style to use when stroking a path

Parameters

• line_dash – An even-lengthed tuple of floats that represents the width of each dash and gap in the dash pattern.

• phase (float) – Specifies how many units into the dash pattern to start.

abstract AbstractGraphicsContext.linear_gradient(x1, y1, x2, y2, stops, spread_method, units='userSpaceOnUse')

Modify the fill color to be a linear gradient

Parameters

• x1 – The X starting point of the gradient.

• y1 – The Y starting point of the gradient.

• x2 – The X ending point of the gradient.

• y3 – The Y ending point of the gradient.

• stops – An array/sequence of color stops ((offset, r, g, b, a), (offset2, r2, g2, b2, a2), …) where offset is some number between 0 and 1 inclusive and the entries are sorted from lowest offset to highest.

• spread_method – One of the following strings: “pad”, “reflect”, “repeat”.

• units – One of the following strings: “userSpaceOnUse”, “objectBoundingBox”.

abstract AbstractGraphicsContext.radial_gradient(cx, cy, r, fx, fy, stops, spread_method, units='userSpaceOnUse')

Modify the fill color to be a radial gradient

Parameters

• cx – The X center point of the gradient.

• cy – The Y center point of the gradient.

• r – The radius of the gradient

• fx – The X ending point of the gradient.

• fy – The Y ending point of the gradient.

• stops – An array/sequence of color stops ((offset, r, g, b, a), (offset2, r2, g2, b2, a2), …) where offset is some number between 0 and 1 inclusive and the entries are sorted from lowest offset to highest.

• spread_method – One of the following strings: “pad”, “reflect”, “repeat”.

• units – One of the following strings: “userSpaceOnUse”, “objectBoundingBox”.

abstract AbstractGraphicsContext.set_alpha(alpha)

Set the alpha to use when drawing

abstract AbstractGraphicsContext.get_alpha(alpha)

Return the alpha used when drawing

abstract AbstractGraphicsContext.set_antialias(antialias)

Set whether or not to antialias when drawing

abstract AbstractGraphicsContext.get_antialias()

Set whether or not to antialias when drawing

abstract AbstractGraphicsContext.set_miter_limit(miter_limit)

Set the limit at which mitered joins are flattened.

Only applicable when the line join type is set to JOIN_MITER.

abstract AbstractGraphicsContext.set_flatness(flatness)

Set the error tolerance when drawing curved paths

abstract AbstractGraphicsContext.set_image_interpolation(interpolation)

Set the type of interpolation to use when scaling images.

Parameters

interpolation – One of “nearest”, “bilinear”, “bicubic”, “spline16”, “spline36”, “sinc64”, “sinc144”, “sinc256”, “blackman64”, “blackman100”, or “blackman256”.

abstract AbstractGraphicsContext.get_image_interpolation()

Get the type of interpolation to use when scaling images

Current Transformation Matrix

These methods control the affine transformation applied to drawing operations. The current transformation matrix is part of the graphic state and therefore covered by calls to save_state() and restore_state()

abstract AbstractGraphicsContext.translate_ctm(x, y)

Concatenate a translation to the current transformation matrix

abstract AbstractGraphicsContext.rotate_ctm(angle)

Concatenate a rotation to the current transformation matrix.

Parameters

angle – An angle in radians.

abstract AbstractGraphicsContext.scale_ctm(x_scale, y_scale)

Concatenate a scaling to the current transformation matrix

abstract AbstractGraphicsContext.concat_ctm(matrix)

Concatenate an arbitrary affine matrix to the current transformation matrix.

abstract AbstractGraphicsContext.set_ctm(matrix)

Set the current transformation matrix

abstract AbstractGraphicsContext.get_ctm()

Get the current transformation matrix

Clipping functions

Note

All of these functions are affected by the current transformation matrix.

abstract AbstractGraphicsContext.clip_to_rect(rect)

Set the clipping region to the specified rectangle

abstract AbstractGraphicsContext.clip_to_rects(rect_array)

Set the clipping region to the collection of rectangles

abstract AbstractGraphicsContext.clip()

Set the clipping region to the current path

abstract AbstractGraphicsContext.even_odd_clip()

Modify clipping region with current path using even-odd rule

Path functions

The path has the concept of a “current point”, which can be though of as the pen position. Many path manipulations use the current point as a starting position for the geometry which is added to the path.

abstract AbstractGraphicsContext.begin_path()

Start a new path

abstract AbstractGraphicsContext.close_path()

Finish a subpath, connecting back to the start

abstract AbstractGraphicsContext.get_empty_path()

Get an empty CompiledPath instance

abstract AbstractGraphicsContext.add_path(compiled_path)

Add the current path to a compiled path

abstract AbstractGraphicsContext.move_to(x, y)

Move the current point on the path without drawing

abstract AbstractGraphicsContext.line_to(x, y)

Add a line from the current point to (x, y) to the path

abstract AbstractGraphicsContext.lines(points)

Adds a series of lines as a new subpath.

Parameters

points – an Nx2 sequence of (x, y) pairs

The current point is moved to the last point in points.

abstract AbstractGraphicsContext.line_set(starts, ends)

Adds a set of disjoint lines as a new subpath.

Parameters

• starts – an Nx2 array of x,y pairs

• ends – an Nx2 array of x,y pairs

starts and ends arrays should have the same length. The current point is moved to the last point in ends.

abstract AbstractGraphicsContext.rect(x, y, w, h)

Add a rectangle as a new sub-path

Parameters

• x – The left X coordinate of the rectangle

• y – The bottom Y coordinate of the rectangle

• w – The width of the rectangle

• h – The height of the rectangle

abstract AbstractGraphicsContext.rects(rect_array)

Add a sequence of rectangles as separate sub-paths.

Parameters

rect_array – An Nx4 array of (x, y, w, h) quadruples

abstract AbstractGraphicsContext.curve_to(x1, y1, x2, y2, end_x, end_y)

Draw a cubic bezier curve

The curve starts from the current point and ends at (end_x, end_y), with control points (x1, y1) and (x2, y2).

abstract AbstractGraphicsContext.quad_curve_to(cp_x, cp_y, end_x, end_y)

Draw a quadratic bezier curve

The curve starts the current point and ends at (end_x, end_y), with control point (cp_x, cp_y)

abstract AbstractGraphicsContext.arc(x, y, radius, start_angle, end_angle, cw=False)

Draw a circular arc of the given radius, centered at (x, y)

The angular span is from start_angle to end_angle, where angles are measured counter-clockwise from the positive X axis.

If “cw” is True, then the arc is swept from the end_angle back to the start_angle (it does not change the sense in which the angles are measured, but may affect rendering based on winding number calculations).

abstract AbstractGraphicsContext.arc_to(x1, y1, x2, y2, radius)

Draw a circular arc from current point to tangent line

The arc is tangent to the line from the current point to (x1, y1), and it is also tangent to the line from (x1, y1) to (x2, y2). (x1, y1) is the imaginary intersection point of the two lines tangent to the arc at the current point and at (x2, y2).

If the tangent point on the line from the current point to (x1, y1) is not equal to the current point, a line is drawn to it. Depending on the supplied radius, the tangent point on the line from (x1, y1) to (x2, y2) may or may not be (x2, y2). In either case, the arc is drawn to the point of tangency, which is also the new current point.

Consider the common case of rounding a rectangle’s upper left corner. Let “r” be the radius of rounding. Let the current point be (x_left + r, y_top). Then (x2, y2) would be (x_left, y_top - radius), and (x1, y1) would be (x_left, y_top).

Drawing functions

abstract AbstractGraphicsContext.draw_path(draw_mode=5)

Draw the current path with the specified mode

Parameters

draw_mode – One of FILL, EOF_FILL, STROKE, FILL_STROKE, or EOF_FILL_STROKE. Each is defined in kiva.api.

abstract AbstractGraphicsContext.fill_path()

Fill the current path with fill settings from the current state

This fills using the nonzero rule filling algorithm

abstract AbstractGraphicsContext.eof_fill_path()

Fill the current path with fill settings from the current state

This fills using the even-odd rule filling algorithm

abstract AbstractGraphicsContext.stroke_path()

Stroke the current path with pen settings from current state

abstract AbstractGraphicsContext.draw_rect(rect, draw_mode=5)

Draw a rectangle with the specified mode

Parameters

• rect – A tuple (x, y, w, h)

• draw_mode – One of FILL, EOF_FILL, STROKE, FILL_STROKE, or EOF_FILL_STROKE. Each is defined in kiva.api.

abstract AbstractGraphicsContext.draw_image(image, rect=None)

Render an image into a rectangle

Parameters

• image – An image. Can be a numpy array, a PIL Image instance, or another GraphicsContext instance.

• rect – A tuple (x, y, w, h). If not specified then the bounds of the the graphics context are used as the rectangle.

Enhanced drawing functions

Note

These methods are not available from every backend, so you should test for their presence before attempting to call them.

abstract EnhancedAbstractGraphicsContext.draw_marker_at_points(point_array, size, marker=1)

Draw a marker at a collection of points

Parameters

• point_array – An Nx2 array of x,y points

• size – The size of the marker in points.

• marker – One of NO_MARKER, SQUARE_MARKER, DIAMOND_MARKER, CIRCLE_MARKER, CROSSED_CIRCLE_MARKER, CROSS_MARKER, TRIANGLE_MARKER, INVERTED_TRIANGLE_MARKER, PLUS_MARKER, DOT_MARKER, or PIXEL_MARKER. Each is defined in kiva.api.

Returns

result – True if markers were drawn, False otherwise.

Return type

bool

abstract EnhancedAbstractGraphicsContext.draw_path_at_points(point_array, compiled_path, draw_mode=5)

Draw a compiled path at a collection of points

The starting point of the paths are specified by the points, and the drawing mode is specified by the third argument.

Parameters

• point_array – An Nx2 array of x,y points

• compiled_path – A CompiledPath instance.

• draw_mode – One of FILL, EOF_FILL, STROKE, FILL_STROKE, or EOF_FILL_STROKE. Each is defined in kiva.api.

Text functions

abstract AbstractGraphicsContext.set_text_drawing_mode(draw_mode)

Set the drawing mode to use with text

Parameters

draw_mode – Allowed values are TEXT_FILL, TEXT_STROKE, TEXT_FILL_STROKE, TEXT_INVISIBLE, TEXT_FILL_CLIP, TEXT_STROKE_CLIP, TEXT_FILL_STROKE_CLIP, or TEXT_CLIP. Each is defined in kiva.api.

abstract AbstractGraphicsContext.set_text_matrix(text_matrix)

Set the transformation matrix to use when drawing text

abstract AbstractGraphicsContext.get_text_matrix()

Get the transformation matrix to use when drawing text

abstract AbstractGraphicsContext.set_text_position(x, y)

Set the current point for drawing text

This point is on the baseline of the text

abstract AbstractGraphicsContext.get_text_position()

Get the current point where text will be drawn

abstract AbstractGraphicsContext.show_text(text, point=None)

Draw the specified string at the current point

abstract AbstractGraphicsContext.show_text_at_point(x, y)

Draw text at the absolute position specified by the point

abstract AbstractGraphicsContext.get_text_extent(text)

Return a rectangle which encloses the specified text

The rectangle (x, y, w, h) is relative to an origin which is at the baseline of the text and at the left of the first character rendered. In other words, x is the leading and y the descent.

abstract AbstractGraphicsContext.get_full_text_extent(string)

Get the text extent as a tuple (w, h, x, y)

Note

This method is deprecated: you should use get_text_extent() instead. This order is provided for backwards-compatibility with existing Enable code.

abstract AbstractGraphicsContext.set_character_spacing(spacing)

Set the spacing between characters when drawing text

Parameters

spacing (float) – units of space extra space to add between text coordinates. It is specified in text coordinate system.

abstract AbstractGraphicsContext.get_character_spacing()

Get the current spacing between characters when drawing text

abstract AbstractGraphicsContext.select_font(name, size=12, style='regular', encoding=None)

Set the font based on the provided parameters

Parameters

• name – The name of a font. E.g.: “Times New Roman”

• size – The font size in points.

• style – One of “regular”, “bold”, “italic”, “bold italic”

• encoding –

  A 4 letter encoding name. Common ones are:

  • ”unic” – unicode

  • ”armn” – apple roman

  • ”symb” – symbol

  Not all fonts support all encodings. If none is specified, fonts that have unicode encodings default to unicode. Symbol is the second choice. If neither are available, the encoding defaults to the first one returned in the FreeType charmap list for the font face.

abstract AbstractGraphicsContext.set_font(font)

Set the font with a kiva.fonttools.font.Font object

abstract AbstractGraphicsContext.get_font()

Get the current font

abstract AbstractGraphicsContext.set_font_size(size)

Set the size of the current font

Misc functions

abstract AbstractGraphicsContext.width()

Returns the width of the graphics context.

abstract AbstractGraphicsContext.height()

Returns the height of the graphics context.

abstract AbstractGraphicsContext.flush()

Render all pending draw operations immediately

This only makes sense in GUI window contexts (eg. Quartz or QPainter).

abstract AbstractGraphicsContext.synchronize()

A deferred version of flush()

Also only relevant in window contexts.

abstract AbstractGraphicsContext.begin_page()

Start rendering in a new page

abstract AbstractGraphicsContext.end_page()

Finish rendering in a page

abstract AbstractGraphicsContext.clear_rect(rect)

Set rectangle to background colour

Note

This may not be available in some backends, such as PDF or PostScript.

abstract AbstractGraphicsContext.save(filename, file_format=None, pil_options=None)

Save the graphics context to a file

Data is always saved in RGB or RGBA format, and converted to that format if not already in it.

If the file_format argument is None, then the file format is inferred from the filename extension, and so is not usually needed.

The pil_options argument is a dictionary of format-specific options that can be passed directly to PIL’s image file writers. For example, this can be used to control the compression level of JPEG or PNG output. Unrecognized options are silently ignored.

Types

Primitive types

The following conventions are used to describe input and output types:

color:

Either a 3-tuple or 4-tuple. The represented color depends on the graphics context’s pixel format.

rect:

(origin_x, origin_y, width, height)

bool:

an int that is 1 or 0

point_array:

an array/sequence of length-2 arrays, e.g. ((x, y), (x2, y2),…)

rect_array:

an array/sequence of rects ((x, y, w, h), (x2, y2, w2, h2), …)

color_stop_array:

an array/sequence of color stops ((offset, r, g, b, a), (offset2, r2, g2, b2, a2), …) where offset is some number between 0 and 1 inclusive and the entries are sorted from lowest offset to highest.

AffineMatrix

All of the following member functions modify the instance on which they are called:

• __init__(v0, v1, v2, v3, v4, v5)

  also __init__()

• reset()

  Sets this matrix to the identity

• multiply(AffineMatrix)

  multiples this matrix by another.

• invert()

  sets this matrix to the inverse of itself

• flip_x()

  mirrors around X

• flip_y()

  mirrors around Y

The rest of the member functions return information about the matrix.

• scale() -> float

  returns the average scale of this matrix

• determinant() -> float

  returns the determinant

• asarray() -> array

  returns the matrix as a 1D numpy array of floats

The following factory methods are available in the top-level “agg” namespace to create specific kinds of AffineMatrix instances:

• translation_matrix(float x, float x)

• rotation_matrix(float angle_in_radians)

• scaling_matrix(float x_scale, float y_scale)

• skewing_matrix(float x_shear, float y_shear)

Enumerations

The following enumerations are represented by top-level constants in the “agg” namespace. They are fundamentally integers. Some of them also have dicts that map between their names and integer values

line_cap:

CAP_BUTT, CAP_ROUND, CAP_SQUARE

line_join:

JOIN_ROUND, JOIN_BEVEL, JOIN_MITER

draw_mode:

FILL, EOF_FILL, STROKE, FILL_STROKE, EOF_FILL_STROKE

text_style:

NORMAL, ITALIC

text_weight:

WEIGHT_NORMAL, WEIGHT_BOLD (some backends support additional weights)

text_draw_mode:

TEXT_FILL, TEXT_STROKE, TEXT_FILL_STROKE, TEXT_INVISIBLE, TEXT_FILL_CLIP, TEXT_STROKE_CLIP, TEXT_FILL_STROKE_CLIP, TEXT_CLIP

pix_format:

(NOTE: the strings in the dicts omit the pix_format_ prefix)

dicts:

pix_format_string_map, pix_format_enum_map

values:

pix_format_gray8, pix_format_rgb555, pix_format_rgb565, pix_format_rgb24, pix_format_bgr24, pix_format_rgba32, pix_format_argb32, pix_format_abgr32, pix_format_bgra32

interpolation:

dicts:

interp_enum_map, interp_string_map

values:

nearest, bilinear, bicubic, spline16, spline36, sinc64, sinc144, sinc256, blackman64, blackman100, blackman256

marker:

(NOTE: the strings in the dicts omit the marker_ prefix)

dicts:

marker_string_map, marker_enum_map

values:

marker_circle, marker_cross, marker_crossed_circle, marker_dash, marker_diamond, marker_dot, marker_four_rays, marker_pixel, marker_semiellipse_down, marker_semiellipse_left, marker_x, marker_semiellipse_right, marker_semiellipse_up, marker_square, marker_triangle_down, marker_triangle_left, marker_triangle_right, marker_triangle_up

path_cmd and path_flags are low-level Agg path attributes. See the Agg documentation for more information about them. We just pass them through in Kiva.

path_cmd:

path_cmd_curve3, path_cmd_curve4, path_cmd_end_poly, path_cmd_line_to, path_cmd_mask, path_cmd_move_to, path_cmd_stop

path_flags:

path_flags, path_flags_ccw, path_flags_close, path_flags_cw, path_flags_mask, path_flags_none