"""Tumbling Projectile Examples - Orientation-Dependent Drag.
Demonstrates how object orientation affects aerodynamic drag using Rapier simulations.
This shows realistic physics for objects like footballs, frisbees, and other projectiles
that have dramatically different drag depending on their orientation.
Requires: PHYSICS_PROVIDER=rapier and Rapier service running
"""
import asyncio
import math
import os
os.environ["RAPIER_SERVICE_URL"] = "https://rapier.chukai.io"
os.environ["PHYSICS_PROVIDER"] = "rapier"
from chuk_mcp_physics.server import (
create_simulation,
add_rigid_body,
step_simulation,
destroy_simulation,
)
async def football_spiral_vs_tumble():
"""Compare football with perfect spiral (low drag) vs tumbling end-over-end (high drag).
A football in a perfect spiral has minimal drag because it's streamlined along
the direction of motion. When tumbling, it presents a much larger cross-section
and experiences significantly more drag, reducing range dramatically.
Football specs:
- Mass: 0.42 kg (NFL regulation)
- Length: 0.28 m
- Diameter: 0.17 m
- Cd (streamlined): ~0.05-0.15
- Cd (broadside): ~0.5-0.8
"""
print("\n" + "=" * 80)
print("FOOTBALL: Perfect Spiral vs End-Over-End Tumble")
print("=" * 80)
# Initial velocity for 50 yard throw (~45 m)
v0 = 25.0 # m/s (~56 mph)
angle = 30.0 # degrees
vx = v0 * math.cos(math.radians(angle))
vy = v0 * math.sin(math.radians(angle))
# Football dimensions
mass = 0.42 # kg
length = 0.28 # m
diameter = 0.17 # m
# Cross-sectional areas
area_streamlined = math.pi * (diameter / 2) ** 2 # ~0.023 m²
area_broadside = length * diameter # ~0.048 m²
# Drag coefficients
cd_streamlined = 0.1 # Low drag when pointed into wind
cd_broadside = 0.6 # High drag when sideways
# ========================================================================
# Scenario 1: Perfect Spiral (stable orientation, streamlined)
# ========================================================================
print("\n--- Scenario 1: PERFECT SPIRAL ---")
print("Football maintains streamlined orientation (like a well-thrown pass)")
sim_spiral = await create_simulation(gravity_y=-9.81)
sim_id_spiral = sim_spiral.sim_id
# For a spiral, the football is streamlined along its velocity direction
# We use drag_axis_ratios to make drag much lower along the long axis (Y)
await add_rigid_body(
sim_id=sim_id_spiral,
body_id="football_spiral",
body_type="dynamic",
shape="sphere", # Using sphere for simplicity (capsule would be more accurate)
size=[diameter / 2],
mass=mass,
position=[0.0, 2.0, 0.0], # 2m high (QB release)
velocity=[vx, vy, 0.0],
angular_velocity=[0.0, 126.0, 0.0], # 20 rev/s spiral
linear_damping=0.0, # No artificial damping (physics handles drag)
angular_damping=0.1, # Slight spin decay
# Orientation-dependent drag parameters
drag_coefficient=cd_streamlined, # Base Cd
drag_area=area_streamlined, # Reference area
drag_axis_ratios=[1.0, 0.2, 1.0], # Much lower drag along Y (flight direction)
fluid_density=1.225, # Sea level air
)
# Run simulation
trajectory_spiral = []
for _ in range(200): # ~2 seconds at 0.01s steps
step = await step_simulation(sim_id=sim_id_spiral, dt=0.01)
body_state = next(b for b in step.bodies if b.id == "football_spiral")
trajectory_spiral.append((body_state.position[0], body_state.position[1]))
# Stop when hits ground
if body_state.position[1] < 0:
break
# Use max x (not final x) to avoid negative ranges from solver jitter at impact
xs_spiral = [x for x, y in trajectory_spiral]
ys_spiral = [y for x, y in trajectory_spiral]
range_spiral = max(xs_spiral)
max_height_spiral = max(ys_spiral)
print(f" Range: {range_spiral:.1f} m ({range_spiral * 1.09361:.1f} yards)")
print(f" Max height: {max_height_spiral:.1f} m")
print(f" Trajectory points: {len(trajectory_spiral)}")
await destroy_simulation(sim_id=sim_id_spiral)
# ========================================================================
# Scenario 2: End-Over-End Tumble (rotating, high drag)
# ========================================================================
print("\n--- Scenario 2: END-OVER-END TUMBLE ---")
print("Football tumbles (like a bad pass or punt)")
sim_tumble = await create_simulation(gravity_y=-9.81)
sim_id_tumble = sim_tumble.sim_id
# For tumbling, the football constantly changes orientation
# Use higher base Cd and less variation (averages out)
await add_rigid_body(
sim_id=sim_id_tumble,
body_id="football_tumble",
body_type="dynamic",
shape="sphere",
size=[diameter / 2],
mass=mass,
position=[0.0, 2.0, 0.0],
velocity=[vx, vy, 0.0],
angular_velocity=[31.4, 0.0, 0.0], # Tumbling rotation (5 rev/s around X)
linear_damping=0.0,
angular_damping=0.05,
# Orientation-dependent drag - averages to higher drag
drag_coefficient=cd_broadside, # Higher base Cd
drag_area=area_broadside, # Larger reference area
drag_axis_ratios=[0.8, 1.0, 0.8], # Less streamlining effect
fluid_density=1.225,
)
# Run simulation
trajectory_tumble = []
for _ in range(200):
step = await step_simulation(sim_id=sim_id_tumble, dt=0.01)
body_state = next(b for b in step.bodies if b.id == "football_tumble")
trajectory_tumble.append((body_state.position[0], body_state.position[1]))
if body_state.position[1] < 0:
break
xs_tumble = [x for x, y in trajectory_tumble]
ys_tumble = [y for x, y in trajectory_tumble]
range_tumble = max(xs_tumble)
max_height_tumble = max(ys_tumble)
print(f" Range: {range_tumble:.1f} m ({range_tumble * 1.09361:.1f} yards)")
print(f" Max height: {max_height_tumble:.1f} m")
print(f" Trajectory points: {len(trajectory_tumble)}")
await destroy_simulation(sim_id=sim_id_tumble)
# ========================================================================
# Comparison
# ========================================================================
print("\n" + "-" * 80)
print("COMPARISON:")
print(f" Spiral range: {range_spiral:.1f} m ({range_spiral * 1.09361:.1f} yd)")
print(f" Tumble range: {range_tumble:.1f} m ({range_tumble * 1.09361:.1f} yd)")
print(f" Range reduction: {(1 - range_tumble / range_spiral) * 100:.1f}%")
print(
f" Extra distance: {range_spiral - range_tumble:.1f} m ({(range_spiral - range_tumble) * 1.09361:.1f} yd)"
)
print("\nConclusion: A perfect spiral can gain 20-40% more distance!")
async def frisbee_stable_vs_wobble():
"""Compare frisbee with stable flight vs wobbling flight.
A frisbee relies on gyroscopic stability from spin. When spinning fast and stable,
it maintains a flat orientation with low drag. When wobbling or flying at an angle,
drag increases significantly.
Frisbee specs:
- Mass: 0.175 kg
- Diameter: 0.27 m
- Thickness: 0.025 m
- Cd (flat): ~0.08
- Cd (edge): ~1.2
"""
print("\n" + "=" * 80)
print("FRISBEE: Stable Flight vs Wobbling")
print("=" * 80)
# Initial velocity for long throw
v0 = 20.0 # m/s
angle = 10.0 # degrees (frisbees are thrown fairly flat)
vx = v0 * math.cos(math.radians(angle))
vy = v0 * math.sin(math.radians(angle))
# Frisbee dimensions
mass = 0.175 # kg
diameter = 0.27 # m
thickness = 0.025 # m
area_flat = math.pi * (diameter / 2) ** 2 # ~0.057 m²
area_edge = diameter * thickness # ~0.007 m²
cd_flat = 0.08
cd_edge = 1.2
# ========================================================================
# Scenario 1: Stable Flight (fast spin, flat orientation)
# ========================================================================
print("\n--- Scenario 1: STABLE FLIGHT ---")
print("Frisbee spins fast and maintains flat orientation")
sim_stable = await create_simulation(gravity_y=-9.81)
sim_id_stable = sim_stable.sim_id
await add_rigid_body(
sim_id=sim_id_stable,
body_id="frisbee_stable",
body_type="dynamic",
shape="sphere",
size=[diameter / 2],
mass=mass,
position=[0.0, 1.5, 0.0],
velocity=[vx, vy, 0.0],
angular_velocity=[0.0, 62.8, 0.0], # Fast spin (600 rpm)
linear_damping=0.0,
angular_damping=0.05,
# Orientation-dependent drag - very low when flat (Y axis up)
drag_coefficient=cd_flat,
drag_area=area_flat,
drag_axis_ratios=[1.0, 0.1, 1.0], # Very low drag along Y (vertical)
fluid_density=1.225,
)
trajectory_stable = []
for _ in range(500): # Longer flight
step = await step_simulation(sim_id=sim_id_stable, dt=0.01)
body_state = next(b for b in step.bodies if b.id == "frisbee_stable")
trajectory_stable.append((body_state.position[0], body_state.position[1]))
if body_state.position[1] < 0:
break
xs_stable = [x for x, y in trajectory_stable]
ys_stable = [y for x, y in trajectory_stable]
range_stable = max(xs_stable)
max_height_stable = max(ys_stable)
flight_time_stable = len(trajectory_stable) * 0.01
print(f" Range: {range_stable:.1f} m")
print(f" Max height: {max_height_stable:.1f} m")
print(f" Flight time: {flight_time_stable:.1f} s")
await destroy_simulation(sim_id=sim_id_stable)
# ========================================================================
# Scenario 2: Wobbling Flight (slow spin, unstable)
# ========================================================================
print("\n--- Scenario 2: WOBBLING FLIGHT ---")
print("Frisbee wobbles with slow spin")
sim_wobble = await create_simulation(gravity_y=-9.81)
sim_id_wobble = sim_wobble.sim_id
await add_rigid_body(
sim_id=sim_id_wobble,
body_id="frisbee_wobble",
body_type="dynamic",
shape="sphere",
size=[diameter / 2],
mass=mass,
position=[0.0, 1.5, 0.0],
velocity=[vx, vy, 0.0],
angular_velocity=[5.0, 20.9, 5.0], # Slow spin + wobble
linear_damping=0.0,
angular_damping=0.1,
# Higher drag due to tilted orientation
drag_coefficient=(cd_flat + cd_edge) / 2, # Average
drag_area=(area_flat + area_edge) / 2,
drag_axis_ratios=[0.6, 0.8, 0.6], # More uniform (less streamlining)
fluid_density=1.225,
)
trajectory_wobble = []
for _ in range(500):
step = await step_simulation(sim_id=sim_id_wobble, dt=0.01)
body_state = next(b for b in step.bodies if b.id == "frisbee_wobble")
trajectory_wobble.append((body_state.position[0], body_state.position[1]))
if body_state.position[1] < 0:
break
xs_wobble = [x for x, y in trajectory_wobble]
ys_wobble = [y for x, y in trajectory_wobble]
range_wobble = max(xs_wobble)
max_height_wobble = max(ys_wobble)
flight_time_wobble = len(trajectory_wobble) * 0.01
print(f" Range: {range_wobble:.1f} m")
print(f" Max height: {max_height_wobble:.1f} m")
print(f" Flight time: {flight_time_wobble:.1f} s")
await destroy_simulation(sim_id=sim_id_wobble)
# ========================================================================
# Comparison
# ========================================================================
print("\n" + "-" * 80)
print("COMPARISON:")
print(f" Stable range: {range_stable:.1f} m")
print(f" Wobble range: {range_wobble:.1f} m")
print(f" Range reduction: {(1 - range_wobble / range_stable) * 100:.1f}%")
print(f" Extra distance: {range_stable - range_wobble:.1f} m")
print("\nConclusion: Stable spin maintains flat orientation for much better range!")
async def javelin_optimal_angle():
"""Demonstrate javelin throw with orientation-dependent drag.
A javelin must maintain a specific angle of attack for optimal flight.
Too flat or too steep and drag increases. This example shows how
orientation affects the throw distance.
Javelin specs:
- Mass: 0.8 kg (men's)
- Length: 2.6 m
- Diameter: 0.025 m
- Cd (optimal angle): ~0.35
- Cd (broadside): ~1.2
"""
print("\n" + "=" * 80)
print("JAVELIN: Optimal Angle vs Poor Angle")
print("=" * 80)
# Release velocity for good throw
v0 = 30.0 # m/s (~67 mph)
release_angle = 35.0 # degrees
vx = v0 * math.cos(math.radians(release_angle))
vy = v0 * math.sin(math.radians(release_angle))
# Javelin dimensions
mass = 0.8 # kg
length = 2.6 # m
diameter = 0.025 # m
area_end = math.pi * (diameter / 2) ** 2 # ~0.0005 m²
area_side = length * diameter # ~0.065 m²
cd_optimal = 0.35
cd_broadside = 1.2
# ========================================================================
# Scenario 1: Optimal Flight (javelin pointed into wind)
# ========================================================================
print("\n--- Scenario 1: OPTIMAL FLIGHT ---")
print("Javelin maintains optimal angle of attack (~35°)")
sim_optimal = await create_simulation(gravity_y=-9.81)
sim_id_optimal = sim_optimal.sim_id
await add_rigid_body(
sim_id=sim_id_optimal,
body_id="javelin_optimal",
body_type="dynamic",
shape="sphere",
size=[diameter],
mass=mass,
position=[0.0, 2.0, 0.0], # Release height
velocity=[vx, vy, 0.0],
angular_velocity=[0.0, 5.0, 0.0], # Slight rotation for stability
linear_damping=0.0,
angular_damping=0.1,
# Streamlined along long axis (Y)
drag_coefficient=cd_optimal,
drag_area=area_end,
drag_axis_ratios=[1.5, 0.2, 1.5], # Very streamlined along Y
fluid_density=1.225,
)
trajectory_optimal = []
for _ in range(400):
step = await step_simulation(sim_id=sim_id_optimal, dt=0.01)
body_state = next(b for b in step.bodies if b.id == "javelin_optimal")
trajectory_optimal.append((body_state.position[0], body_state.position[1]))
if body_state.position[1] < 0:
break
xs_opt = [x for x, y in trajectory_optimal]
ys_opt = [y for x, y in trajectory_optimal]
range_optimal = max(xs_opt)
max_height_optimal = max(ys_opt)
print(f" Range: {range_optimal:.1f} m")
print(f" Max height: {max_height_optimal:.1f} m")
await destroy_simulation(sim_id=sim_id_optimal)
# ========================================================================
# Scenario 2: Poor Release (javelin at bad angle, tumbling)
# ========================================================================
print("\n--- Scenario 2: POOR RELEASE ---")
print("Javelin tumbles and presents broadside to wind")
sim_poor = await create_simulation(gravity_y=-9.81)
sim_id_poor = sim_poor.sim_id
await add_rigid_body(
sim_id=sim_id_poor,
body_id="javelin_poor",
body_type="dynamic",
shape="sphere",
size=[diameter],
mass=mass,
position=[0.0, 2.0, 0.0],
velocity=[vx, vy, 0.0],
angular_velocity=[10.0, 2.0, 5.0], # Tumbling
linear_damping=0.0,
angular_damping=0.05,
# Much higher drag due to tumbling
drag_coefficient=cd_broadside,
drag_area=area_side,
drag_axis_ratios=[0.8, 1.0, 0.8], # Less streamlining
fluid_density=1.225,
)
trajectory_poor = []
for _ in range(400):
step = await step_simulation(sim_id=sim_id_poor, dt=0.01)
body_state = next(b for b in step.bodies if b.id == "javelin_poor")
trajectory_poor.append((body_state.position[0], body_state.position[1]))
if body_state.position[1] < 0:
break
xs_poor = [x for x, y in trajectory_poor]
ys_poor = [y for x, y in trajectory_poor]
range_poor = max(xs_poor)
max_height_poor = max(ys_poor)
print(f" Range: {range_poor:.1f} m")
print(f" Max height: {max_height_poor:.1f} m")
await destroy_simulation(sim_id=sim_id_poor)
# ========================================================================
# Comparison
# ========================================================================
print("\n" + "-" * 80)
print("COMPARISON:")
print(f" Optimal range: {range_optimal:.1f} m")
print(f" Poor range: {range_poor:.1f} m")
print(f" Range reduction: {(1 - range_poor / range_optimal) * 100:.1f}%")
print(f" Distance lost: {range_optimal - range_poor:.1f} m")
print("\nConclusion: Proper technique and orientation is crucial for distance!")
async def main():
"""Run all tumbling projectile examples."""
print("\n" + "=" * 80)
print("TUMBLING PROJECTILE EXAMPLES")
print("Demonstrating Orientation-Dependent Drag with Rapier Physics")
print("=" * 80)
print("\nThese examples show how object orientation dramatically affects")
print("aerodynamic drag and range. Real-world sports rely on this physics!")
try:
await football_spiral_vs_tumble()
await frisbee_stable_vs_wobble()
await javelin_optimal_angle()
print("\n" + "=" * 80)
print("All examples completed successfully!")
print("=" * 80)
except Exception as e:
print(f"\n❌ Error running examples: {e}")
print("\nMake sure:")
print(" 1. PHYSICS_PROVIDER=rapier environment variable is set")
print(" 2. Rapier service is running and accessible")
print(" 3. Rapier service implements orientation-dependent drag")
if __name__ == "__main__":
asyncio.run(main())
