Bouncing Ball Analysis

This project analyzes the bouncing behavior of different types of balls (golf, lacrosse, and metal) dropped from various heights. It includes both static analysis and animated visualizations to help understand the physics of bouncing balls and calculate the Coefficient of Restitution (COR).

Project Structure

The project has been organized into a modular structure for maintainability:

bouncing-ball-analysis/
├── src/                    # Source code directory
│   ├── data/               # Data files and loaders
│   │   ├── golf/           # Golf ball data files
│   │   ├── lacrosse/       # Lacrosse ball data files
│   │   ├── metal/          # Metal ball data files
│   │   ├── images/         # Image files
│   │   └── loader.py       # Data loading utilities
│   ├── analysis/           # Analysis modules
│   │   └── bounce_detection.py  # Bounce detection and COR calculation
│   ├── visualization/      # Visualization modules
│   │   ├── static_plots.py      # Static visualization functions
│   │   ├── animation.py         # Animation functions
│   │   └── lab2_part*_animated.py  # Original animation scripts
│   ├── utils/              # Utility functions
│   │   ├── helpers.py           # Helper functions
│   │   └── organize_files.py    # File organization script
│   ├── main.py             # Main entry point for analysis
│   └── lab2_part*.py       # Original analysis scripts
├── output/                 # Output directory for results
├── requirements.txt        # Project dependencies
└── README.md               # This file

Original Files

The original scripts have been preserved for reference:

Analysis Scripts

• src/lab2_part1.py: Static position vs. time plots for each ball type and height
• src/lab2_part2.py: Detailed analysis with bounce detection and COR calculation

Animated Visualization Scripts

• src/visualization/lab2_part1_animated.py: Animated version of the position vs. time plots
• src/visualization/lab2_part2_animated.py: Animated visualization of bouncing balls with physics simulation
• src/visualization/animate_bouncing_balls.py: Combined script with command-line interface to run either animation type

Setup Instructions

Setting Up a Virtual Environment

It's recommended to use a virtual environment to run this project. Here's how to set it up:

For macOS/Linux:

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

For Windows:

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Installing Dependencies Directly

If you prefer not to use a virtual environment, you can install the dependencies directly:

pip install -r requirements.txt

Running the Analysis

Using the New Structure

To run the complete analysis with the new modular structure:

# Organize files into the new structure (only needed once)
python src/utils/organize_files.py

# Run the main analysis script
python src/main.py

This will:

1. Load data for all ball types
2. Detect bounces and calculate COR values
3. Generate static plots and animations
4. Save results to the output directory

Using the Original Scripts

You can still run the original scripts if preferred:

Static Analysis

To run the basic position vs. time plots:

python src/lab2_part1.py

To run the detailed analysis with bounce detection and COR calculation:

python src/lab2_part2.py

Animated Visualizations

The easiest way to run the animations is using the combined script:

# Run position vs. time animations
python src/visualization/animate_bouncing_balls.py position

# Run bouncing ball physics animations
python src/visualization/animate_bouncing_balls.py bounce

Additional options:

# Run animations for a specific ball type
python src/visualization/animate_bouncing_balls.py position --ball golf
python src/visualization/animate_bouncing_balls.py bounce --ball lacrosse

# Save animations as GIF files
python src/visualization/animate_bouncing_balls.py position --save
python src/visualization/animate_bouncing_balls.py bounce --ball metal --save

For help with command-line options:

python src/visualization/animate_bouncing_balls.py --help

Physics Background

The scripts calculate the Coefficient of Restitution (COR) for each bounce, which is a measure of the "bounciness" of the ball. The COR is calculated as:

COR = sqrt(h_{n+1} / h_n)

Where:

• h_n is the height of the nth bounce
• h_{n+1} is the height of the next bounce

A COR of 1.0 would mean a perfectly elastic collision (no energy loss), while a COR of 0.0 would mean a completely inelastic collision (all energy lost).

Customization

You can customize various parameters in the scripts:

• Animation speed: Modify the fps parameter in the animation functions
• Ball size: Change the ball_radius parameter in the animation functions
• Simulation parameters: Adjust the physics parameters like gravity (g) or time step (dt)
• Bounce detection: Adjust the parameters in the BALL_PARAMS dictionary in src/analysis/bounce_detection.py