PingPong Simulation

Physics-based 3D ping-pong ball trajectory simulation system, implementing complete aerodynamics, collision detection, and racket interaction.

✨ Core Features

• 🔬 Realistic Physics Model: Air drag, Magnus effect, gravity, collision dynamics
• 🎯 Precise Simulation: Based on ITTF standard parameters, supports various stroke techniques
• 📊 Complete Data Output: CSV trajectory data + 3D visualization animations
• 🎮 Dual Player Interaction: Intelligent racket AI, supports multi-rally gameplay
• 🔧 Modular Design: Easy to extend to other ball sports

🚀 Quick Start

Install Dependencies

pip install -r requirements.txt

Basic Usage

# Serve simulation
python pingpong_main.py --serve-mode fh_under

# Custom stroke
python pingpong_main.py --serve-mode custom --pos -1.2 0 0.9 --vel 8 0 3 --omega 0 150 0

# Trajectory analysis
python analyze_impact.py --speed 5.0 --angle 30.0 --spin 0 150 0

📖 Detailed Documentation

• User Guide - Complete usage tutorial and parameter description
• API Reference - Detailed function and class documentation
• Architecture Document - System design and module description
• Physics Model - Mathematical model and formula derivation
• Developer Guide - Code contribution and development standards

🎯 Supported Simulation Scenarios

Scenario	Description
fh_under	Forehand underspin serve
fast_long	Fast long serve
custom	Custom initial conditions

📊 Output Formats

• Trajectory Data: CSV format (position, velocity, angular velocity, events)
• Visualization: 3D animations (MP4) + static plots
• Analysis Reports: Physics parameter statistics and performance metrics

🔧 Technology Stack

• Language: Python 3.8+
• Core Libraries: NumPy, Matplotlib, Pandas
• Algorithms: RK4 numerical integration, impulse-momentum collision model
• Architecture: Modular design with complete type hints

🤝 Contributing

Welcome to contribute code! Please check:

• Contribution Guide - How to participate in project development
• Developer Guide - Code standards and best practices
• Code of Conduct - Community standards and expectations
• Security Policy - How to report security vulnerabilities
• Issues - Report issues or suggest new features

📄 License

This project uses the MIT License open source license.

🙏 Acknowledgments

• Based on ITTF official standard parameters
• Physics model references published scientific literature
• Thanks to the open source community

Star History

---

⭐ If this project is helpful to you, please give it a star!