Provided modular architecture for animated bouncing ball analysis
- Organized project into src directory with subpackages (analysis, data, visualization, utils) - Added comprehensive README with project overview and structure - Implemented data loading, bounce detection, and visualization modules - Created example scripts and Jupyter notebook for project usage - Added requirements.txt for dependency management - Included output files for different ball types (golf, lacrosse, metal)
This commit is contained in:
170
README.md
170
README.md
@@ -1,3 +1,169 @@
|
||||
# bounce
|
||||
# Bouncing Ball Analysis
|
||||
|
||||
lab2
|
||||
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 better 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:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Running the Analysis
|
||||
|
||||
### Using the New Structure
|
||||
|
||||
To run the complete analysis with the new modular structure:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
python src/lab2_part1.py
|
||||
```
|
||||
|
||||
To run the detailed analysis with bounce detection and COR calculation:
|
||||
```bash
|
||||
python src/lab2_part2.py
|
||||
```
|
||||
|
||||
#### Animated Visualizations
|
||||
|
||||
The easiest way to run the animations is using the combined script:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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`
|
||||
Reference in New Issue
Block a user