Puppet Basketball

What You're Actually Looking At

Puppet Basketball is a Python-based framework built on top of Pygame and OpenCV that lets you map live webcam footage onto a rigged 2D character and animate it doing basketball moves. It wasn't designed as a production tool. It was built by a developer at a small indie studio to prototype character rigs quickly before committing to full skeletal animation. That context matters because the documentation reflects that origin story, and so does the way things behave when you push past the examples. The repo is hosted on GitHub. Clone it, set up a Python virtual environment with version 3.9 or later, and install the dependencies listed in requirements.txt. The critical packages are Pygame, OpenCV, NumPy, and dlib for facial landmark detection. Run the setup script and the example scene should load a default court background with a placeholder player rig already in position. I ran into a specific issue on my first build that took me about three hours to sort out. The OpenCV dependency was resolving to version 4.8.1, which conflicts with the dlib bindings the project expects. Face landmarks would return coordinates that were mirrored and scaled incorrectly, which made the puppet track your face but flip it horizontally and offset by roughly 40 percent. The workaround was pinning OpenCV to version 4.7.0 in your environment and reinstalling dlib from source rather than using a prebuilt wheel. Once that was fixed, the tracking stabilized within a second of starting the program.

After that, mapping your footage is straightforward enough. The program captures your webcam feed, runs it through the face detection pipeline, and projects those landmarks onto the character rig. Each joint on the puppet has a weight value that determines how much it responds to your real movements. Default values work fine for basic gestures. If you want sharper tracking on smaller movements, you lower the smoothing factor in the config file from the default of 0.7 down to around 0.3.

How It Actually Performs in Practice

The framework handles simple dribbling and shooting motions without much trouble. The rig has roughly eighteen joints covering the torso, arms, legs, and head. Each joint maps to corresponding regions in the webcam feed. The main limitation is that it treats everything as a 2D plane. Depth information doesn't exist in this system. When your character moves toward or away from the camera, the rig just scales up or down, which looks obviously fake after a few seconds. Beginners usually catch that quickly and move on to adjusting the camera angle instead of trying to force perspective that the tool can't actually render. A more subtle issue people don't notice until they try exporting longer sequences is frame pacing. The default output locks to whatever your webcam's native refresh rate is, which is often 30 fps but sometimes drops unpredictably depending on lighting conditions and USB bandwidth. Puppet Basketball doesn't interpolate missing frames. The result is a video that stutters on character landings and pivot turns. I found that running the capture at a fixed 60 fps and then dropping every other frame during export produced cleaner motion than letting it run at whatever the camera defaulted to. You control this in the capture settings before you start recording. Another thing that trips people up is the bone rig constraints. The elbows and knees bend in only one direction by default. If your tracked pose suggests a bent knee that would require reverse articulation, the rig just snaps to the nearest valid angle. This creates a visible pop in the animation. You can adjust the bend direction constraints in the rig JSON file, but the changes only apply to newly created sequences. Existing animations keep their original constraints baked in. If you need different joint behavior mid-project, you have to rebuild that portion rather than edit it.

When It Falls Short

Puppet Basketball isn't suitable for anything that requires realistic human movement. It's a prototype tool with prototype-level limitations. The character mesh doesn't support custom models unless you already know the required rig structure and joint naming convention. The default character is hardcoded into the distribution. If you want a different figure, you're building one from scratch, and the documentation on that process is roughly a paragraph long. For anyone needing actual character animation with depth, proper skeletal IK, or exported rigs that work in standard animation software, this isn't the right solution. You'd be better off looking at Blender's rigging tools or a dedicated motion capture pipeline if your budget allows. Puppet Basketball fills a very narrow use case: quick 2D puppet-style animation from a webcam with minimal setup. It does that reasonably well once you get past the initial dependency conflicts. Beyond that, it won't save you much time compared to just animating the same sequence by hand in a proper tool.