Shape¶

PShape¶

class p5.PShape(fill_color='auto', stroke_color='auto', stroke_weight='auto', stroke_join='auto', stroke_cap='auto', visible=False, children=None, contours=(), vertices=(), shape_type=<SType.TESS: 'TESS'>)¶

Custom shape class for p5.

Parameters:

vertices (list | np.ndarray) – List of (polygonal) vertices for the shape.
fill_color ('auto' | None | tuple | p5.Color) – Fill color of the shape (default: ‘auto’ i.e., the current renderer fill)
stroke_color ('auto' | None | tuple | p5.color) – Stroke color of the shape (default: ‘auto’ i.e., the current renderer stroke color)
visible (bool) – toggles shape visibility (default: False)
children (list) – List of sub-shapes for the current shape (default: [])

add_child(child)¶

Add a child shape to the current shape

Parameters:	child (PShape) – Child to be added

add_vertex(vertex)¶

Add a vertex to the current shape

Parameters:	vertex (tuple \| list \| p5.Vector \| np.ndarray) – The (next) vertex to add to the current shape.

apply_matrix(mat)¶

Apply the given transformation matrix to the shape.

Parameters:	mat ((4, 4) np.ndarray) – the 4x4 matrix to be applied to the current shape.

child_count¶

Number of children.

Returns:	The current number of children.
Return type:	int

edit(reset=True)¶

Put the shape in edit mode.

Parameters:	reset (bool) – Toggles whether the shape should be “reset” during editing. When set to True all existing shape vertices are cleared. When set to False the new vertices are appended at the end of the existing vertex list. (default: True)
Raises:	ValueError – if the shape is already being edited.

reset_matrix()¶: Reset the transformation matrix associated with the shape.

rotate(theta, axis=(0, 0, 1))¶

Rotate the shape by the given angle along the given axis.

Parameters:	theta (float) – The angle by which to rotate (in radians) axis (np.ndarray \| list) – The axis along which to rotate (defaults to the z-axis)
Returns:	The rotation matrix used to apply the transformation.
Return type:	np.ndarray

rotate_x(theta)¶

Rotate the shape along the x axis.

Parameters:	theta (float) – angle by which to rotate (in radians)
Returns:	The rotation matrix used to apply the transformation.
Return type:	np.ndarray

rotate_y(theta)¶

Rotate the shape along the y axis.

Parameters:	theta (float) – angle by which to rotate (in radians)
Returns:	The rotation matrix used to apply the transformation.
Return type:	np.ndarray

rotate_z(theta)¶

Rotate the shape along the z axis.

Parameters:	theta (float) – angle by which to rotate (in radians)
Returns:	The rotation matrix used to apply the transformation.
Return type:	np.ndarray

scale(sx, sy=None, sz=None)¶

Scale the shape by the given factor.

Parameters:	sx (float) – scale factor along the x-axis. sy (float) – scale factor along the y-axis (defaults to None) sz (float) – scale factor along the z-axis (defaults to None)
Returns:	The transformation matrix used to appy the transformation.
Return type:	np.ndarray

shear_x(theta)¶

Shear shape along the x-axis.

Parameters:	theta (float) – angle to shear by (in radians)
Returns:	The shear matrix used to apply the tranformation.
Return type:	np.ndarray

shear_y(theta)¶

Shear shape along the y-axis.

Parameters:	theta (float) – angle to shear by (in radians)
Returns:	The shear matrix used to apply the transformation.
Return type:	np.ndarray

translate(x, y, z=0)¶

Translate the shape origin to the given location.

Parameters:	x (int) – The displacement amount in the x-direction (controls the left/right displacement) y (int) – The displacement amount in the y-direction (controls the up/down displacement) z (int) – The displacement amount in the z-direction (0 by default). This controls the displacement away-from/towards the screen.
Returns:	The translation matrix applied to the transform matrix.
Return type:	np.ndarray

update_vertex(idx, vertex)¶

Edit an individual vertex.

Parameters:	idx (int) – index of the vertex to be edited vertex (tuple \| list \| p5.Vector \| np.ndarray) – The (next) vertex to add to the current shape.

2D Primitives¶

point()¶

p5.point(x, y, z=0)¶

Returns a point.

Parameters:	x (int or float) – x-coordinate of the shape. y (int or float) – y-coordinate of the shape. z (int or float) – z-coordinate of the shape (defaults to 0).
Returns:	A point PShape.
Return type:	PShape

line()¶

p5.line(x1, y1, x2, y2)

p5.line(x1, y1, z1, x2, y2, z2)

p5.line(p1, p2)¶

Returns a line.

Parameters:	x1 (float) – x-coordinate of the first point y1 (float) – y-coordinate of the first point z1 (float) – z-coordinate of the first point x2 (float) – x-coordinate of the first point y2 (float) – y-coordinate of the first point z2 (float) – z-coordinate of the first point p1 (tuple) – Coordinates of the starting point of the line. p2 (tuple) – Coordinates of the end point of the line.
Returns:	A line PShape.
Return type:	PShape

ellipse()¶

p5.ellipse(a, b, c, d, mode=None)

p5.ellipse(coordinate, *args, mode=None)¶

Return a ellipse.

Parameters:	a (float) – x-coordinate of the ellipse b (float) – y-coordinate of the ellipse c (float) – width of the ellipse d (float) – height of the ellipse coordinate (3-tuple) – Represents the center of the ellipse when mode is ‘CENTER’ (the default) or ‘RADIUS’, the lower-left corner of the ellipse when mode is ‘CORNER’ or, and an arbitrary corner when mode is ‘CORNERS’. args – For modes’CORNER’ or ‘CENTER’ this has the form (width, height); for the ‘RADIUS’ this has the form (x_radius, y_radius); and for the ‘CORNERS’ mode, args should be the corner opposite to coordinate. mode (str) – The drawing mode for the ellipse. Should be one of {‘CORNER’, ‘CORNERS’, ‘CENTER’, ‘RADIUS’} (defaults to the mode being used by the p5.renderer.)
Type:	tuple
Returns:	An ellipse
Return type:	Arc

circle()¶

p5.circle(x, y, radius, mode=None)

p5.circle(coordinate, radius, mode=None)¶

Return a circle.

Parameters:	x (float) – x-coordinate of the centre of the circle. y (float) – y-coordinate of the centre of the circle. coordinate (3-tuple) – Represents the center of the ellipse when mode is ‘CENTER’ (the default) or ‘RADIUS’, the lower-left corner of the ellipse when mode is ‘CORNER’ or, and an arbitrary corner when mode is ‘CORNERS’. diameter (float) – For modes’CORNER’ or ‘CENTER’ this actually represents the diameter; for the ‘RADIUS’ this represents the radius. mode (str) – The drawing mode for the ellipse. Should be one of {‘CORNER’, ‘CORNERS’, ‘CENTER’, ‘RADIUS’} (defaults to the mode being used by the p5.renderer.)
Returns:	A circle.
Return type:	Ellipse
Raises:	ValueError – When mode is set to ‘CORNERS’

arc()¶

p5.arc(x, y, width, height, start_angle, stop_angle, mode=None, ellipse_mode=None)

p5.arc(coordinate, width, height, start_angle, stop_angle, mode=None, ellipse_mode=None)¶

Return a ellipse.

Parameters:	x (float) – x-coordinate of the arc’s ellipse. y (float) – y-coordinate of the arc’s ellipse. coordinate (3-tuple) – Represents the center of the arc when mode is ‘CENTER’ (the default) or ‘RADIUS’, the lower-left corner of the ellipse when mode is ‘CORNER’. width (float) – For ellipse modes ‘CORNER’ or ‘CENTER’ this represents the width of the the ellipse of which the arc is a part. Represents the x-radius of the parent ellipse when ellipse mode is ‘RADIUS height (float) – For ellipse modes ‘CORNER’ or ‘CENTER’ this represents the height of the the ellipse of which the arc is a part. Represents the y-radius of the parent ellipse when ellipse mode is ‘RADIUS mode (str) – The mode used to draw an arc can be any of {None, ‘OPEN’, ‘CHORD’, ‘PIE’}. ellipse_mode – The drawing mode used for the ellipse. Should be one of {‘CORNER’, ‘CENTER’, ‘RADIUS’} (defaults to the mode being used by the p5.renderer.)
Returns:	An arc.
Return type:	Arc

triangle()¶

p5.triangle(x1, y1, x2, y2, x3, y3)

p5.triangle(p1, p2, p3)¶

Return a triangle.

Parameters:	x1 (float) – x-coordinate of the first point y1 (float) – y-coordinate of the first point x2 (float) – x-coordinate of the second point y2 (float) – y-coordinate of the second point x3 (float) – x-coordinate of the third point y3 (float) – y-coordinate of the third point p1 (tuple \| list \| p5.Vector) – coordinates of the first point of the triangle p2 (tuple \| list \| p5.Vector) – coordinates of the second point of the triangle p3 (tuple \| list \| p5.Vector) – coordinates of the third point of the triangle
Returns:	A triangle.
Return type:	p5.PShape

quad()¶

p5.quad(x1, y1, x2, y2, x3, y3, x4, y4)

p5.quad(p1, p2, p3, p4)¶

Return a quad.

Parameters:	x1 (float) – x-coordinate of the first point y1 (float) – y-coordinate of the first point x2 (float) – x-coordinate of the second point y2 (float) – y-coordinate of the second point x3 (float) – x-coordinate of the third point y3 (float) – y-coordinate of the third point x4 (float) – x-coordinate of the forth point y4 (float) – y-coordinate of the forth point p1 (tuple \| list \| p5.Vector) – coordinates of the first point of the quad p2 (tuple \| list \| p5.Vector) – coordinates of the second point of the quad p3 (tuple \| list \| p5.Vector) – coordinates of the third point of the quad p4 (tuple \| list \| p5.Vector) – coordinates of the fourth point of the quad
Returns:	A quad.
Return type:	PShape

rect()¶

p5.rect(x, y, w, h)

p5.rect(coordinate, *args, mode=None)¶

Return a rectangle.

Parameters:	x – x-coordinate of the rectangle by default y – y-coordinate of the rectangle by default w – width of the rectangle by default h – height of the rectangle by default coordinate (tuple \| list \| p5.Vector) – Represents the lower left corner of then rectangle when mode is ‘CORNER’, the center of the rectangle when mode is ‘CENTER’ or ‘RADIUS’, and an arbitrary corner when mode is ‘CORNERS’ args – For modes’CORNER’ or ‘CENTER’ this has the form (width, height); for the ‘RADIUS’ this has the form (half_width, half_height); and for the ‘CORNERS’ mode, args should be the corner opposite to coordinate. mode (str) – The drawing mode for the rectangle. Should be one of {‘CORNER’, ‘CORNERS’, ‘CENTER’, ‘RADIUS’} (defaults to the mode being used by the p5.renderer.)
Type:	tuple
Returns:	A rectangle.
Return type:	p5.PShape

TODO: Update docs for rect, we support border radius as well

square()¶

p5.square(x, y, side_length)

p5.square(coordinate, side_length, mode=None)¶

Return a square.

Parameters:	x – x-coordinate of the square by default y – y-coordinate of the square by default coordinate (tuple \| list \| p5.Vector) – When mode is set to ‘CORNER’, the coordinate represents the lower-left corner of the square. For modes ‘CENTER’ and ‘RADIUS’ the coordinate represents the center of the square. side_length (int or float) – The side_length of the square (for modes ‘CORNER’ and ‘CENTER’) or hald of the side length (for the ‘RADIUS’ mode) mode (str) – The drawing mode for the square. Should be one of {‘CORNER’, ‘CORNERS’, ‘CENTER’, ‘RADIUS’} (defaults to the mode being used by the p5.renderer.)
Returns:	A rectangle.
Return type:	p5.PShape
Raises:	ValueError – When the mode is set to ‘CORNERS’

Curves¶

bezier()¶

p5.bezier(x1, y1, x2, y2, x3, y3, x4, y4)

p5.bezier(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)

p5.bezier(start, control_point_1, control_point_2, stop)¶

Return a bezier path defined by two control points.

Parameters:	x1 (float) – x-coordinate of the first anchor point y1 (float) – y-coordinate of the first anchor point z1 (float) – z-coordinate of the first anchor point x2 (float) – x-coordinate of the first control point y2 (float) – y-coordinate of the first control point z2 (float) – z-coordinate of the first control point x3 (float) – x-coordinate of the second control point y3 (float) – y-coordinate of the second control point z3 (float) – z-coordinate of the second control point x4 (float) – x-coordinate of the second anchor point y4 (float) – y-coordinate of the second anchor point z4 (float) – z-coordinate of the second anchor point start (tuple.) – The starting point of the bezier curve. control_point_1 (tuple.) – The first control point of the bezier curve. control_point_2 (tuple.) – The second control point of the bezier curve. stop (tuple.) – The end point of the bezier curve.
Returns:	A bezier path.
Return type:	PShape.

bezier_detail()¶

p5.bezier_detail(detail_value)¶

Change the resolution used to draw bezier curves.

Parameters:	detail_value (int) – New resolution to be used.

bezier_point()¶

p5.bezier_point(start, control_1, control_2, stop, parameter)¶

Return the coordinate of a point along a bezier curve.

Parameters:	start (float or n-tuple) – The start point of the bezier curve control_1 (float or n-tuple) – The first control point of the bezier curve control_2 (float or n-tuple) – The second control point of the bezier curve stop (float or n-tuple) – The end point of the bezier curve parameter (float) – The parameter for the required location along the curve. Should be in the range [0.0, 1.0] where 0 indicates the start of the curve and 1 indicates the end of the curve.
Returns:	The coordinate of the point along the bezier curve.
Return type:	float or n-tuple

bezier_tangent()¶

p5.bezier_tangent(start, control_1, control_2, stop, parameter)¶

Return the tangent at a point along a bezier curve.

Parameters:	start (float or n-tuple.) – The start point of the bezier curve control_1 (float or n-tuple.) – The first control point of the bezier curve control_2 (float or n-tuple.) – The second control point of the bezier curve stop (float or n-tuple.) – The end point of the bezier curve parameter (float) – The parameter for the required tangent location along the curve. Should be in the range [0.0, 1.0] where 0 indicates the start of the curve and 1 indicates the end of the curve.
Returns:	The tangent at the required point along the bezier curve.
Return type:	float or n-tuple

curve()¶

p5.curve(x1, y1, x2, y2, x3, y3, x4, y4)

p5.curve(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)

p5.curve(point_1, point_2, point_3, point_4)¶

Return a Catmull-Rom curve defined by four points.

Parameters:	x1 (float) – x-coordinate of the beginning control point y1 (float) – y-coordinate of the beginning control point z1 (float) – z-coordinate of the beginning control point x2 (float) – x-coordinate of the first point y2 (float) – y-coordinate of the first point z2 (float) – z-coordinate of the first point x3 (float) – x-coordinate of the second point y3 (float) – y-coordinate of the second point z3 (float) – z-coordinate of the second point x4 (float) – x-coordinate of the ending control point y4 (float) – y-coordinate of the ending control point z4 (float) – z-coordinate of the ending control point point_1 (tuple) – The first point of the curve. point_2 (tuple) – The first point of the curve. point_3 (tuple) – The first point of the curve. point_4 (tuple) – The first point of the curve.
Returns:	A curved path.
Return type:	PShape

curve_detail()¶

p5.curve_detail(detail_value)¶

Change the resolution used to draw bezier curves.

Parameters:	detail_value (int) – New resolution to be used.

curve_point()¶

p5.curve_point(point_1, point_2, point_3, point_4, parameter)¶

Return the coordinates of a point along a curve.

Parameters:	point_1 (float or n-tuple.) – The first control point of the curve. point_2 (float or n-tuple.) – The second control point of the curve. point_3 (float or n-tuple.) – The third control point of the curve. point_4 (float or n-tuple.) – The fourth control point of the curve. parameter (float) – The parameter for the required point location along the curve. Should be in the range [0.0, 1.0] where 0 indicates the start of the curve and 1 indicates the end of the curve.
Returns:	The coordinate of the point at the required location along the curve.
Return type:	float or n-tuple

curve_tangent()¶

p5.curve_tangent(point_1, point_2, point_3, point_4, parameter)¶

Return the tangent at a point along a curve.

Parameters:	point_1 (float or n-tuple.) – The first control point of the curve. point_2 (float or n-tuple.) – The second control point of the curve. point_3 (float or n-tuple.) – The third control point of the curve. point_4 (float or n-tuple.) – The fourth control point of the curve. parameter (float) – The parameter for the required tangent location along the curve. Should be in the range [0.0, 1.0] where 0 indicates the start of the curve and 1 indicates the end of the curve.
Returns:	The tangent at the required point along the curve.
Return type:	float or n-tuple

curve_tightness()¶

p5.curve_tightness(amount)¶

Change the curve tightness used to draw curves.

Parameters:	amount (int) – new curve tightness amount.

Attributes¶

ellipse_mode()¶

p5.ellipse_mode(mode='CENTER')¶

Change the ellipse and circle drawing mode for the p5.renderer.

Parameters:	mode (str) – The new mode for drawing ellipses. Should be one of {‘CORNER’, ‘CORNERS’, ‘CENTER’, ‘RADIUS’}. This defaults to ‘CENTER’ so calling ellipse_mode without parameters will reset the sketch’s ellipse mode.

rect_mode()¶

p5.rect_mode(mode='CORNER')¶

Change the rect and square drawing mode for the p5.renderer.

Parameters:	mode (str) – The new mode for drawing rects. Should be one of {‘CORNER’, ‘CORNERS’, ‘CENTER’, ‘RADIUS’}. This defaults to ‘CORNER’ so calling rect_mode without parameters will reset the sketch’s rect mode.

3D Primitives¶

box()¶

p5.box(width, height, depth, detail_x=1, detail_y=1)¶

Draw a plane with given a width and height

Parameters:	width (float) – width of the box height (float) – height of the box depth (float) – depth of the box detail_x (integer) – Optional number of triangle subdivisions in x-dimension. Default is 1 detail_y (integer) – Optional number of triangle subdivisions in y-dimension. Default is 1

plane()¶

p5.plane(width, height, detail_x=1, detail_y=1)¶

Draw a plane with given a width and height

Parameters:	width (float) – width of the plane height (float) – height of the plane detail_x (integer) – Optional number of triangle subdivisions in x-dimension. Default is 1 detail_y (integer) – Optional number of triangle subdivisions in y-dimension. Default is 1

sphere()¶

p5.sphere(radius=50, detail_x=24, detail_y=16)¶

Draw a sphere with given radius

Parameters:	radius (float) – radius of circle detail_x (integer) – Optional number of triangle subdivisions in x-dimension. Default is 24 detail_y (integer) – Optional number of triangle subdivisions in y-dimension. Default is 16

ellipsoid()¶

p5.ellipsoid(radius_x, radius_y, radius_z, detail_x=24, detail_y=24)¶

Draw an ellipsoid with given radius

Parameters:	radius_x (float) – x-radius of ellipsoid radius_y (float) – y-radius of ellipsoid radius_z (float) – z-radius of ellipsoid detail_x (integer) – Optional number of triangle subdivisions in x-dimension. Default is 24 detail_y (integer) – Optional number of triangle subdivisions in y-dimension. Default is 16

cylinder()¶

p5.cylinder(radius=50, height=50, detail_x=24, detail_y=1, top_cap=True, bottom_cap=True)¶

Draw a cylinder with given radius and height

Parameters:

radius (float) – radius of the surface
height (float) – height of the cylinder
detail_x (integer) – Number of segments, the more segments the smoother geometry. Default is 24
detail_y (integer) – number of segments in y-dimension, the more segments the smoother geometry. Default is 1
bottom_cap (boolean) – whether to draw the bottom of the cylinder
top_cap (boolean) – whether to draw the top of the cylinder

cone()¶

p5.cone(radius=50, height=50, detail_x=24, detail_y=1, cap=True)¶

Draw a cone with given radius and height

Parameters:	radius (float) – radius of the bottom surface height (float) – height of the cone detail_x (integer) – Optional number of triangle subdivisions in x-dimension. Default is 24 detail_y (integer) – Optional number of triangle subdivisions in y-dimension. Default is 1

torus()¶

p5.torus(radius=50, tube_radius=10, detail_x=24, detail_y=16)¶

Draws torus on the window

Parameters:	radius (float) – radius of the whole ring tube_radius (float) – radius of the tube detail_x (integer) – Optional number of triangle subdivisions in x-dimension. Default is 24 detail_y (integer) – Optional number of triangle subdivisions in y-dimension. Default is 16

Vertex¶

begin_shape()¶

p5.begin_shape(kind=<SType.TESS: 'TESS'>)¶

Begin shape drawing. This is a helpful way of generating custom shapes quickly.

Parameters:	kind (SType) – TESS, POINTS, LINES, TRIANGLES, TRIANGLE_FAN, TRIANGLE_STRIP, QUADS, or QUAD_STRIP; defaults to TESS

end_shape()¶

p5.end_shape(mode='')¶

The endShape() function is the companion to beginShape() and may only be called after beginShape(). When endshape() is called, all of image data defined since the previous call to beginShape() is rendered.

Parameters:	mode (str) – use CLOSE to close the shape

begin_contour()¶

p5.begin_contour()¶: Use the beginContour() and endContour() functions to create negative shapes within shapes such as the center of the letter ‘O’. beginContour() begins recording vertices for the shape and endContour() stops recording. The vertices that define a negative shape must “wind” in the opposite direction from the exterior shape. First draw vertices for the exterior clockwise order, then for internal shapes, draw vertices shape in counter-clockwise.

end_contour()¶

p5.end_contour()¶

Ends the current contour.

For more info, see begin_contour.

vertex()¶

p5.vertex(x, y, z=0)¶

All shapes are constructed by connecting a series of vertices. vertex() is used to specify the vertex coordinates for points, lines, triangles, quads, and polygons. It is used exclusively within the beginShape() and endShape() functions.

Parameters:	x (float) – x-coordinate of the vertex y (float) – y-coordinate of the vertex z (float) – z-coordinate of the vertex

curve_vertex()¶

p5.curve_vertex(x, y, z=0)¶

Specifies vertex coordinates for curves. The first and last points in a series of curveVertex() lines will be used to guide the beginning and end of a the curve. A minimum of four points is required to draw a tiny curve between the second and third points. Adding a fifth point with curveVertex() will draw the curve between the second, third, and fourth points. The curveVertex() function is an implementation of Catmull-Rom splines.

Parameters:	x (float) – x-coordinate of the vertex y (float) – y-coordinate of the vertex z (float) – z-coordinate of the vertex

bezier_vertex()¶

p5.bezier_vertex(x2, y2, x3, y3, x4, y4)¶

Specifies vertex coordinates for Bezier curves

Parameters:	x2 (float) – x-coordinate of the first control point y2 (float) – y-coordinate of the first control point x3 (float) – x-coordinate of the second control point y3 (float) – y-coordinate of the second control point x4 (float) – x-coordinate of the anchor point y4 (float) – y-coordinate of the anchor point

quadratic_vertex()¶

p5.quadratic_vertex(cx, cy, x3, y3)¶

Specifies vertex coordinates for quadratic Bezier curves

Parameters:	cx (float) – x-coordinate of the control point cy (float) – y-coordinate of the control point x3 (float) – x-coordinate of the anchor point y3 (float) – y-coordinate of the anchor point