Sketchingpy

Group	Badges
Status
Usage
Documentation

Tiny tools for creative coding and interactive science in Python. Supporting portability across desktop, web, mobile, Jupyter notebooks, and static images. Serving makers of all kinds from experienced designers and developers to educators and students. Includes tools for geospatial visualization.

Learn more online at https://sketchingpy.org.

Quickstart

A first sketch in 7 lines of code (edit and run this first sketch in your browser):

import sketchingpy

sketch = sketchingpy.Sketch2D(500, 500)

sketch.clear('#F0F0F0')
sketch.set_fill('#C0C0C0')
sketch.set_stroke('#000000')
sketch.draw_ellipse(250, 250, 20, 20)

sketch.show()

A tiny bit of example interactivity in just over 10 lines (edit and run this little drawing program in your browser):

import sketchingpy

sketch = sketchingpy.Sketch2D(500, 500)

def draw():
  mouse = sketch.get_mouse()
  
  x = mouse.get_x()
  y = mouse.get_y()
  
  sketch.set_fill('#C0C0C0')
  sketch.set_stroke('#333333')
  sketch.draw_ellipse(x, y, 20, 20)

sketch.on_step(draw)

sketch.clear('#FFFFFF')

sketch.show()

Install

There's multiple ways to use Sketchingpy with different dependencies for different platforms. It will try to operate with what is installed, turning off different functionality when libraries are not available. Note that sketchingpy in the browser will operate as a pure-Python wheel without additional requirements.

Online sketchbook

No installation needed! Just get your browser and start quickly using an online private sketchbook (coming soon but a slimmed down editor is available at https://sketchingpy.org/examples/web/example.html).

Plain Python: static sketches

Write Python scripts like you usually do and run them from the command line or your IDE. Just grab a few minimal dependencies:

$ pip install sketchingpy[static]

Note that this will use the Sketch2DStatic renderer by default. Learn more about using sketches inside standard Python programs.

Plain Python: interactive sketches

For interactive sketches, also install pygame-ce in addition to the static dependencies:

$ pip install sketchingpy[desktopall]

Note that this will use the Sketch2DApp renderer by default. Learn more about using sketches inside standard Python programs. A slightly slimmer distribution without dialog support can also be installed with sketchingpy[desktopall].

Jupyter Notebook

Code creatively in Jupyter notebooks with minimal dependencies:

$ pip install sketchingpy[notebook]

Go deeper and review the getting started instructions for Jupyter.

Custom web applications

Embed Sketchingpy in your own websites. Simply add this to your pyscript py-config:

"packages": ["sketchingpy"]

Review documentation about writing sketches for the browser or adding Sketchingpy into your own web pages. Note that no additional dependencies are needed and sketchingpy will install as a pure-Python wheel for maximum compatibility. Numpy, matplotlib, etc are not required.

Use

More educational resources coming soon. See examples and reference for now. After you've made something you want to share, take your creations to the web or export your work to stand-alone executables.

Purpose

This interactive coding tool enables anyone to start creative coding in minutes using Python across multiple platforms including desktop and web. Heavily inspired by Processing, Sketchingpy seeks to bring the philosophy of sketchingpy in code to portable technologies that allow programmers to take their work anywhere. We believe coding should be iterative, fun, and creative at any stage of someone's journey.

Goals

Specifically, this project seeks to:

• Enable creative expression in computation through Python.
• Be simple to use, friendly for everyone from beginners to experts.
• Support Mac, Windows, Linux, the browser, Jupyter, and static image generation in headless environments.
• Work in plain old 100% Python with Sketchingpy available as a library, supporting you anywhere in your programming journey.

We hope to reach developers of all skill levels.

Use cases

We imagine folks using Sketchingpy for:

• Interactive science
• Data visualization
• Visual art
• Immersive experience
• Simulation
• Sound design
• User experience (UX) prototyping
• Game development

We would love to see what you do and invite contributions to our showcase.

Audience

We aim to support teachers, students, artists, designers, developers, and other makers as they make creative programs including visual art, games needing a bit more flexibility, and more. Specifically, this project hopes to embrace a wide group of people:

• Serve programmers no matter where they are in their journey from beginner to expert.
• Support portabilty across desktop (Mac, Windows, Linux), web (browser), notebooks (Jupyter), and static image generation.
• Foster inclusive community across different disciplines within and outside computer science.
• Assist in both formal and informal educational contexts.

If you are interested in this mission, we invite a diverse set of collaborators to join us.

Scope

Currently we are only focused on 2D with no explicit console support though Steam Deck should work with the Linux builds.

Grow Sketchingpy

Thank you for your interest in our humble project. Here is how to build Sketchingpy itself and how to participate in our community including contributing code to the project.

Environment setup

The recommended packages for development can be installed with the following:

$ pip install .[dev]

Note that this assumes pypi and Python3 are installed.

Testing

There are multiple layers of tests to ensure code quality and stability:

• Standard unit tests: Executable with $ nose2, this will execute unit tests which do not require actual instantiation of a renderer.
• Static tests: Execution of most static Pillow-based examples to ensure no errors are generated using the Docker image in ci-image.
• App tests: Execution of most Pygame-ce-based examples to ensure no errors are generated using the Docker image in ci-image and xvfb.
• Web tests: Execution of select web-based examples to ensure no errors are generated using the Docker image in ci-image and Selenium. The number of examples is kept low due to resource intensiveness of this stage.

Please ensure all tests pass before merging.

Development standards

Please adhere to the following when contributing code to the project:

• Precedent is most important: please follow the conventions you see in the repository already.
• Where there isn't precedent, please use the Google Python Style Guide where possible.
• All private members should be prefaced with a single underscore.
• All public members should have Google-style docstrings.
• All public members should have type hints.
• Across these different options, the project aims for 90% code coverage.
• Getters and setters preferred over

The above represent our ambitions as a project. Please do not let those stop you from opening pull requests if you are not sure how to contribute. We will work with you! Note that we also have formalized some exceptions to those guidelines:

• Type hints are encouraged but not required for "renderer-native" types.
• Type hints and docstrings not required for test code.
• Guidelines encouraged but not required for "support" scripts that are not installed with the library itself.
• Guidelines encouraged but not required for examples. Authors should determine when the guidelines either improve or hinder readability.

Code should pass pyflakes (pyflakes sketchingpy/*.py) and pycodestyle (pycodestyle sketchingpy/*.py) should both pass. Furthermore, please ensure mypy succeeds before opening a PR (mypy sketchingpy/*.py).

Release

Please release using CI / CD where possible which is done automatically when merging to the main branch. However, if manual deployment is required:

pip install build twine
python3 -m build
twine check dist/*
python3 support/make_twine_config.py
twine upload --config-file ./pypirc dist/*

See support/make_twine_config.py for additional details.

Get involved

Sketchingpy hopes to foster an inclusive community of makers.

• Let us know about a bug or other issue.
• Contribute to the code of Sketchingpy itself.
• Help with documentation.
• Share your work in our showcase.

Also, join us in our Discord to share ideas!

Open Source

Sketchingpy both uses open source and is released under a permissive license.

Libraries used

We use and thank the following open source libraries:

• Ace Editor under the BSD License for the web editor.
• bezier under the Apache v2 License.
• Pillow under the HPND License for Sketch2D and Sketch2DStatic renderers.
• processing-geopoint under the BSD License.
• Pygame-ce under the LGPL License for Sketch2D renderer.
• Pyscript under the Apache v2 License for the Sketch2DWeb renderer.
• Pyodide under the MPL 2.0 License for the Sketch2DWeb renderer.

Other code and contributors listed in the code itself or within the people section of the website. Some documentation uses IBM Plex under the OFL 1.0. Also, some examples colors from ColorBrewer 2.0.

License

Sketchingpy is permissively BSD licensed meaning you can use it for commerical and non-commerical projects as well as for your hobbies and for your professional work.