py5 Reference Summary

py5 Reference Summary#

Drawing Shapes#

Basic Elements#

  • arc() - Draws an arc to the screen.

  • circle() - Draws a circle to the screen.

  • ellipse() - Draws an ellipse (oval) - to the screen.

  • ellipse_mode() - Modifies the location from which ellipses and circles are drawn by changing the way in which values given are interpreted.

  • line() - Draws a line (a direct path between two points) - to the screen.

  • lines() - Draw a collection of lines to the screen.

  • point() - Draws a point, a coordinate in space at the dimension of one pixel.

  • points() - Draw a collection of points, each a coordinate in space at the dimension of one pixel.

  • quad() - A quad is a quadrilateral, a four sided polygon.

  • rect() - Draws a rectangle to the screen.

  • rect_mode() - Modifies the location from which rectangles and squares are drawn by changing the way in which values given are interpreted.

  • square() - Draws a square to the screen.

  • triangle() - A triangle is a plane created by connecting three points.

3D Shapes#

  • box() - A box is an extruded rectangle. You’ll need to set the P3D renderer in size() to use it.

  • sphere() - A sphere is a hollow ball made from tessellated triangles. You’ll need the P3D renderer.

  • sphere_detail() - Controls the detail used to render a sphere by adjusting the number of vertices of the sphere mesh.

Vertex Based Shapes#

  • begin_closed_shape() - This method is used to start a custom closed shape.

  • begin_contour() - Use the begin_contour() and end_contour() methods to create negative shapes within shapes such as the center of the letter ‘O’.

  • begin_shape() - Using the begin_shape() and end_shape() functions allow creating more complex forms.

  • bezier_vertex() - Specifies vertex coordinates for Bezier curves.

  • bezier_vertices() - Create a collection of bezier vertices.

  • curve_vertex() - Specifies vertex coordinates for curves.

  • curve_vertices() - Create a collection of curve vertices.

  • end_contour() - Use the begin_contour() and end_contour() methods to create negative shapes within shapes such as the center of the letter ‘O’.

  • end_shape() - The end_shape() function is the companion to begin_shape() and may only be called after begin_shape().

  • quadratic_vertex() - Specifies vertex coordinates for quadratic Bezier curves.

  • quadratic_vertices() - Add a collection of quadratic vertices.

  • vertex() - Add a new vertex to a shape.

  • vertices() - Add a collection of vertices to a shape.

Standalone Curves#

  • bezier() - Draws a Bezier curve on the screen.

  • bezier_detail() - Sets the resolution at which Beziers display.

  • bezier_point() - Evaluates the Bezier at point t for points a, b, c, d.

  • bezier_tangent() - Calculates the tangent of a point on a Bezier curve.

  • curve() - Draws a curved line (Catmull-Rom spline) on the screen.

  • curve_detail() - Sets the resolution at which curves display.

  • curve_point() - Evaluates the curve at point t for points a, b, c, d.

  • curve_tangent() - Calculates the tangent of a point on a curve.

  • curve_tightness() - Modifies the quality of forms created with curve() and curve_vertex().

Creating and Displaying Shape Objects#

  • create_shape() - Used to define a new empty Py5Shape object.

  • load_shape() - Loads SVG or OBJ geometry making it available as a Py5Shape object.

  • convert_shape() - Converts Python objects into Py5Shape objects.

  • convert_cached_shape() - Converts Python objects into Py5Shape objects, but cache the results.

  • shape() - Draws shapes to the display window.

  • shape_mode() - Modifies the location from which shapes draw.

  • Py5Shape class - Datatype for storing shapes. Allows loading and displaying SVG and OBJ shapes.

Color and Other Graphic Attributes#

Creating and Setting Colors#

  • background() - Sets the color for the sketch background, also, paints over any previous drawing.

  • clear() - Clear the drawing surface by setting every pixel to black.

  • color_mode() - Changes the way py5 interprets color data, using the constants HSB, RGB and the range of the values to be used.

  • fill() - Sets the color used to fill shapes.

  • no_fill() - Disables filling geometry.

  • no_stroke() - Disables drawing the stroke (outline).

  • stroke() - Sets the color used to draw lines and borders around shapes.

  • color() - Creates colors for storing in variables of the color datatype (a 32 bit integer).

  • lerp_color() - Calculates a color between two colors at a specific increment.

Analyzing Colors#

  • hex_color() - Convert a color value to a hex color string.

  • alpha() - Extracts the alpha value from a color, scaled to match current color_mode().

  • blue() - Extracts the blue value from a color, scaled to match current color_mode().

  • brightness() - Extracts the brightness value from a color.

  • green() - Extracts the green value from a color, scaled to match current color_mode().

  • hue() - Extracts the hue value from a color.

  • red() - Extracts the red value from a color, scaled to match current color_mode().

  • saturation() - Extracts the saturation value from a color.

Stroke Attributes and Style Control#

  • stroke_weight() - Sets the width of the stroke used for lines, points, and the border around shapes.

  • stroke_cap() - Sets the style for rendering line endings.

  • stroke_join() - Sets the style of the joints which connect line segments.

  • pop_style() - The push_style() function saves the current style settings and pop_style() restores the prior settings; these functions are always used together.

  • push_style() - The push_style() function saves the current style settings and pop_style() restores the prior settings.

  • push() - combines push_style() and push_matrix() The push() function saves the current drawing style settings and transformations, while pop() restores these settings.

  • pop() - combines pop_style() and pop_matrix() The pop() function restores the previous drawing style settings and transformations after push() has changed them.

Inputs#

Reading Files#

Keyboard Variables#

  • is_key_pressed - The is_key_pressed variable stores whether or not a keyboard button is currently being pressed.

  • key - The variable key always contains the value of the most recent key on the keyboard that was used (either pressed or released). It will contain the constant CODED if it was a special key that can then be discriminated with key_code.

  • key_code - The variable key_code is used to detect special keys such as the arrow keys (UP, DOWN, LEFT, and RIGHT) - as well as ALT, CONTROL, and SHIFT.

Keyboard Event Functions#

  • key_pressed() - If defined, it will be called once when a keyboard key is pressed.

  • key_released() - If defined, it will be called once when a keyboard key is released.

  • key_typed() - If defined, it will be called once when a keyboard key is pressed and released.

  • Py5KeyEvent Class - A Py5KeyEvent object will be passed to user-defined keyboard event functions.

Mouse Variables#

  • is_mouse_pressed - The is_mouse_pressed variable stores whether or not a mouse button is currently being pressed.

  • mouse_button - When a mouse button is pressed, the variable mouse_button is set to either LEFT, RIGHT, or CENTER, depending on which button is pressed.

  • mouse_x - The variable mouse_x always contains the current horizontal coordinate of the mouse.

  • mouse_y - The variable mouse_y always contains the current vertical coordinate of the mouse.

  • pmouse_x - The variable pmouse_x always contains the horizontal position of the mouse in the frame previous to the current frame.

  • pmouse_y - The variable pmouse_y always contains the vertical position of the mouse in the frame previous to the current frame.

  • rmouse_x - The current horizontal coordinate of the mouse after activating scale invariant drawing.

  • rmouse_y - The current vertical coordinate of the mouse after activating scale invariant drawing.

Mouse Event Functions#

  • mouse_pressed() - If defined, it will be called once when a mouse button is pressed.

  • mouse_released() - If defined, it will be called once when a mouse button is pressed.

  • mouse_clicked() - If defined, it will be called once when a mouse button is clicked.

  • mouse_dragged() - If defined, it will be called many times as the mouse is moved while pressed.

  • mouse_wheel() - If defined, it will be called as the mouse wheel is rolled.

  • mouse_moved() - If defined, it will be called many times as the mouse is moved.

  • mouse_entered() - If defined, it will be called when the mouse enters the sketch area.

  • mouse_exited() - If defined, it will be called when the mouse leaves the sketch area.

  • Py5MouseEvent Class - A Py5MouseEvent object will be passed to user-defined mouse event functions.

Time & Date Helpers#

  • day() - Returns the current day as a value from 1 - 31 by consulting the clock on your computer.

  • hour() - Returns the current hour as a value from 0 to 23 by consulting the clock on your computer.

  • millis() - Returns the number of milliseconds (thousandths of a second) - since starting the program.

  • minute() - Returns the current minute as a value from 0 to 59 by consulting the clock on your computer.

  • month() - Returns the current month as a value from 1 to 12 by consulting the clock on your computer.

  • second() - Returns the current seconds as a value from 0 to 59 by consulting the clock on your computer.

  • year() - Returns the current year by consulting the clock on your computer.

Output#

Saving Files#

  • begin_raw() - To create vectors from 3D data, use the begin_raw() and end_raw() commands.

  • begin_record() - Opens a new file and all subsequent drawing functions are echoed to this file as well as the display window.

  • end_raw() - Complement to begin_raw(); they must always be used together.

  • end_record() - Stops the recording process started by begin_record() and closes the file.

  • save_bytes() - Save byte data to a file.

  • save_json() - Save JSON data to a file.

  • save_pickle() - Pickle a Python object to a file.

  • save_strings() - Save a list of strings to a file.

  • select_output() - Opens a file chooser dialog to select a file for output.

Image Output#

  • save() - Save the drawing surface to an image file.

  • save_frame() - Save the current frame as an image.

Text Area (Console)#

  • println() - Print text or other values to the console (not the sketch drawing area). Similar to Python’s print().

  • set_println_stream() - Customize where the output of println() goes.

Typography#

Drawing Text#

  • text() - Draws text on the screen, that is, the sketch drawing area.

  • text_align() - Sets the current alignment for drawing text.

  • text_leading() - Sets the spacing between lines of text in units of pixels.

  • text_mode() - Sets the way text draws to the screen, either as texture maps or as vector geometry.

  • text_size() - Sets the current font size.

Loading & Selecting Fonts#

  • create_font() - Dynamically converts a font to the format used by py5 from a .ttf or .otf file inside the Sketch’s “data” folder or a font that’s installed elsewhere on the computer.

  • load_font() - Loads a .vlw formatted font into a Py5Font object.

  • text_font() - Sets the current font that will be drawn with the text() function.

  • Py5Font - Py5Font is the font class for py5, stores font information in a way py5 can use.

Text Metrics#

  • text_width() - Calculates and returns the width of any character or text string.

  • text_ascent() - Returns ascent of the current font at its current size.

  • text_descent() - Returns descent of the current font at its current size.

Coordinate System Transformations#

Basic Operations#

  • push_matrix() - Saves the transformation matrix that describes the current coordinate system in the matrix stack so that it can be restored later with pop_matrix().

  • pop_matrix() - Retrieves the last transformation matrix stored in the matrix stack restoring a previous coordinate system state.

  • translate() - Specifies an amount to displace the coordinate system origin, displacing objects drawn within the display window. Can be used in 2D, translate(x, y), or 3D, translate(x, y, z).

  • rotate() - Rotates the coordinate system the amount specified by the angle parameter.

  • scale() - Increases or decreases the size of shapes by expanding and contracting the coordinate system.

  • shear_x() - Shears shapes around the x-axis the amount specified by the angle parameter.

  • shear_y() - Shears shapes around the y-axis the amount specified by the angle parameter.

3D Rotations#

  • rotate_x() - Rotates around the x-axis the amount specified by the angle parameter.

  • rotate_y() - Rotates around the y-axis the amount specified by the angle parameter.

  • rotate_z() - Rotates around the z-axis the amount specified by the angle parameter.

Matrix Operations#

  • apply_matrix() - Multiplies the current matrix by the one specified through the parameters.

  • get_matrix() - Get the current matrix as a numpy array.

  • print_matrix() - Prints the current matrix to standard output.

  • reset_matrix() - Replaces the current matrix with the identity matrix.

  • set_matrix() - Set the current matrix to the one specified through the parameter source.

Sketch Environment#

Setup and Variables#

  • size() - Must be called only once to define the sketch dimensions, width and height, in pixel units. Other than in static mode, it must be used inside setup() or settings().

  • full_screen() - Make the sketch use the full size of the computer’s display. Replaces size().

  • width - variable that stores the width of the display window.

  • height - variable that stores the height of the display window.

  • smooth() - Draws all geometry with smooth (anti-aliased) - edges. Must be used just after size().

  • no_smooth() - Draws all geometry and fonts with jagged (aliased) - edges and images with hard edges between the pixels when enlarged rather than interpolating pixels.

  • cursor() - Sets the cursor to a predefined symbol or an image, or makes it visible if already hidden.

  • no_cursor() - Hides the cursor from view.

  • frame_count - The variable frame_count contains the number of frames that have been displayed since the program started.

  • frame_rate() - Specifies the target number of frames to be displayed every second. If drawing a frame gets slow the target will not be met!

  • get_frame_rate() - Get the running Sketch’s current frame rate.

  • display_density() - This function returns the number “2” if the screen is a high-density screen (called a Retina display on macOS or high-dpi on Windows and Linux) - and a “1” if not.

  • pixel_density() - This function makes it possible for py5 to render using all of the pixels on high resolutions screens like Apple Retina displays and Windows High-DPI displays.

  • display_height - variable that stores the height of the entire screen display.

  • display_width - variable that stores the width of the entire screen display.

  • focused - Confirms if a py5 program is “focused”, meaning that it is active and will accept mouse or keyboard input.

  • sketch_path() - The Sketch’s current path.

Other Window Controls#

  • get_surface() - Get the Py5Surface object used for the Sketch window.

  • pixel_height - Height of the display window in pixels.

  • pixel_width - Width of the display window in pixels.

  • ratio_left - Width of the left section of the window that does not fit the desired aspect ratio of a scale invariant Sketch.

  • ratio_scale - Scaling factor used to maintain scale invariant drawing.

  • ratio_top - Height of the top section of the window that does not fit the desired aspect ratio of a scale invariant Sketch.

  • rheight - The height of the scale invariant display window.

  • rwidth - The width of the scale invariant display window.

  • window_move() - Set the Sketch’s window location.

  • window_ratio() - Set a window ratio to enable scale invariant drawing.

  • window_resizable() - Set the Sketch window as resizable by the user.

  • window_resize() - Set a new width and height for the Sketch window.

  • window_title() - Set the Sketch window’s title.

  • window_x - The x-coordinate of the current window location.

  • window_y - The y-coordinate of the current window location.

Working with Images#

Loading and Displaying#

  • image() - The image() function draws an image to the display window.

  • image_mode() - Modifies the location from which images are drawn by changing the way in which parameters given to image() are interpreted.

  • load_image() - Load an image into a variable of type Py5Image.

  • no_tint() - Removes the current fill value for displaying images and reverts to displaying images with their original hues.

  • tint() - Sets the fill value for displaying images.

Pixels#

  • apply_filter() - Filters the display window using a preset filter or with a custom shader.

  • blend() - Blends a region of pixels from one image into another (or in itself again) - with full alpha channel support.

  • copy() - Copies a region of pixels from the display window to another area of the display window and copies a region of pixels from an image used as the src_img parameter into the display window.

  • get_np_pixels() - Returns the contents of np_pixels[] as a numpy array.

  • get_pixels() - Reads the color of any pixel or grabs a section of the drawing surface.

  • load_np_pixels() - Loads the pixel data of the current display window into the np_pixels[] array.

  • load_pixels() - Loads the pixel data of the current display window into the pixels[] array.

  • np_pixels[] - The np_pixels[] array contains the values for all the pixels in the display window.

  • pixels[] - The pixels[] array contains the values for all the pixels in the display window.

  • set_np_pixels() - Set the entire contents of np_pixels[] to the contents of another properly sized and typed numpy array.

  • set_pixels() - Changes the color of any pixel or writes an image directly into the drawing surface.

  • to_pil() - Returns the drawing surface as a PIL Image object.

  • update_np_pixels() - Updates the display window with the data in the np_pixels[] array.

  • update_pixels() - Updates the display window with the data in the pixels[] array.

Textures#

  • texture() - Sets a texture to be applied to vertex points.

  • texture_mode() - Sets the coordinate space for texture mapping.

  • texture_wrap() - Defines if textures repeat or draw once within a texture map.

Image Objects#

3D Scene#

Camera#

  • begin_camera() - The begin_camera() and end_camera() functions enable advanced customization of the camera space.

  • camera() - Sets the position of the camera through setting the eye position, the center of the scene, and which axis is facing upward.

  • end_camera() - The begin_camera() and end_camera() methods enable advanced customization of the camera space.

  • frustum() - Sets a perspective matrix as defined by the parameters.

  • ortho() - Sets an orthographic projection and defines a parallel clipping volume.

  • perspective() - Sets a perspective projection applying foreshortening, making distant objects appear smaller than closer ones.

  • print_camera() - Prints the current camera matrix to standard output.

  • print_projection() - Prints the current projection matrix to standard output.

Coordinates#

  • model_x() - Returns the three-dimensional X, Y, Z position in model space.

  • model_y() - Returns the three-dimensional X, Y, Z position in model space.

  • model_z() - Returns the three-dimensional X, Y, Z position in model space.

  • screen_x() - Takes a three-dimensional X, Y, Z position and returns the X value for where it will appear on a (two-dimensional) - screen.

  • screen_y() - Takes a three-dimensional X, Y, Z position and returns the Y value for where it will appear on a (two-dimensional) - screen.

  • screen_z() - Takes a three-dimensional X, Y, Z position and returns the Z value for where it will appear on a (two-dimensional) - screen.

Lights#

Material Properties#

  • ambient() - Sets the ambient reflectance for shapes drawn to the screen.

  • emissive() - Sets the emissive color of the material used for drawing shapes drawn to the screen.

  • shininess() - Sets the amount of gloss in the surface of shapes.

  • specular() - Sets the specular color of the materials used for shapes drawn to the screen, which sets the color of highlights.

Rendering#

Graphics Context#

  • blend_mode() - Blends the pixels in the display window according to a defined mode.

  • clip() - Limits the rendering to the boundaries of a rectangle defined by the parameters.

  • create_graphics() - Creates and returns a new Py5Graphics object.

  • flush() - Flush drawing commands to the renderer.

  • get_graphics() - Get the Py5Graphics object used by the Sketch.

  • hint() - This function is used to enable or disable special features that control how graphics are drawn.

  • no_clip() - Disables the clipping previously started by the clip() function.

Shaders#

Sketch Execution#

Draw Loop Control#

  • loop() - By default, py5 loops through draw() continuously, executing the code within it.

  • no_loop() - Stops py5 from continuously executing the code within draw().

  • redraw() - Executes the code within draw() one time.

  • exit_sketch() - Quits/stops/exits the program.

  • exiting() - A function that, if defined by the user, will be called to be executed after the sketch stops.

Advanced Execution Control#

  • finished - Boolean variable reflecting if the Sketch has stopped permanently.

  • hot_reload_draw() - Perform a hot reload of the Sketch’s draw function.

  • is_dead - Boolean value reflecting if the Sketch has been run and has now stopped.

  • is_dead_from_error - Boolean value reflecting if the Sketch has been run and has now stopped because of an error.

  • is_ready - Boolean value reflecting if the Sketch is in the ready state.

  • is_running - Boolean value reflecting if the Sketch is in the running state.

  • pargs - List of strings passed to the Sketch through the call to run_sketch().

Performance Profiling#

  • print_line_profiler_stats() - Print the line profiler stats initiated with profile_draw() or profile_functions().

  • profile_draw() - Profile the execution times of the draw function with a line profiler.

  • profile_functions() - Profile the execution times of the Sketch’s functions with a line profiler.

Threading#

  • has_thread() - Determine if a thread of a given name exists and is currently running.

  • join_thread() - Join the Python thread associated with the given thread name.

  • launch_promise_thread() - Create a Py5Promise object that will store the returned result of a function when that function completes.

  • launch_repeating_thread() - Launch a new thread that will repeatedly execute a function in parallel with your Sketch code.

  • launch_thread() - Launch a new thread to execute a function in parallel with your Sketch code.

  • list_threads() - List the names of all of the currently running threads.

  • stop_all_threads() - Stop all running threads.

  • stop_thread() - Stop a thread of a given name.

JVM Constants#

py5 Classes and Other Tools#

Classes#

  • Py5Graphics - Main graphics and rendering context, as well as the base API implementation for Processing’s “core”.

  • Py5Image - A Datatype for storing images. Allows loading, converting and displaying external image formats as well as efficient manipulation of pixels as NumPy arrays.

  • Py5Shape - Datatype for storing shapes. Allows loading and displaying SVG (Scalable Vector Graphics) and OBJ shapes.

  • Py5Shader - This class encapsulates a GLSL shader program, including a vertex and a fragment shader.

  • Py5Surface - The Py5Surface object is the actual window py5 draws animations to. You can use this to interact with the window and change some of its characteristics, such as the window title or location.

  • Py5Font - Py5Font is the font class for py5. To create a font to use with py5, use create_font_file(). This will create a font in the format py5 requires.

  • Py5MouseEvent - A Py5MouseEvent object will be passed to user-defined mouse event functions. Useful for capturing all of a user’s mouse activity.

  • Py5KeyEvent - A Py5MouseEvent object will be passed to user-defined mouse event functions. Useful for capturing all of a user’s keyboard activity.

  • Py5Vector - Class to describe a 2D, 3D, or 4D vector. A vector is an entity that has both a magnitude and a direction. This datatype stores the components of the vector as a set of coordinates.

Tools#

  • Py5 Magics - The py5 Magics are Jupyter Notebook “meta-commands” that can be within Jupyter Notebooks to enhance py5’s ability to work within the notebook. The py5 magics will enable users to create Sketches and embed the results in the Notebook without defining any functions or calling the size() function.

  • Py5 Tools - The py5 Tools are extra utility functions not directly related to creating Sketches that help facilitate the use of py5. For example, you can use these to add jar files to the Java classpath before importing py5.

  • Py5 Functions - The py5 Functions are extra utility functions that make py5 easier to use. For example, you can use these to Processing’s vlw font files without having to use Processing’s IDE.

Contents