physics_viz package

Submodules

physics_viz.camera module

Camera system for 2D physics visualization

Provides viewport transformation from world space to screen space.

class physics_viz.camera.Camera(screen_width, screen_height, pixels_per_meter=20.0)

Bases: object

2D camera with pan and zoom support

The camera transforms world coordinates (meters) to screen coordinates (pixels). Supports panning, zooming, and following objects.

world_to_screen(world_pos)

Convert world position (meters) to screen position (pixels)

Parameters:

world_pos – Vector2 in world space

Returns:

(x, y) in screen space

Return type:

tuple

screen_to_world(screen_pos)

Convert screen position (pixels) to world position (meters)

Parameters:

screen_pos – tuple (x, y) in screen space

Returns:

Vector2 in world space

world_to_screen_scalar(world_scalar)

Convert world distance (meters) to screen distance (pixels)

Parameters:

world_scalar – Distance in meters

Returns:

Distance in pixels

Return type:

int

screen_to_world_scalar(screen_scalar)

Convert screen distance (pixels) to world distance (meters)

Parameters:

screen_scalar – Distance in pixels

Returns:

Distance in meters

Return type:

float

pan(dx, dy)

Pan camera by screen offset

Parameters:

• dx – Horizontal pan in pixels

• dy – Vertical pan in pixels

zoom(factor, center=None)

Zoom camera by factor

Parameters:

• factor – Zoom multiplier (> 1 = zoom in, < 1 = zoom out)

• center – Optional screen position to zoom toward (tuple)

focus_on(world_pos)

Center camera on world position

Parameters:

world_pos – Vector2 in world space

get_view_bounds()

Get visible world bounds

Returns:

(min_x, max_x, min_y, max_y) in world space

Return type:

tuple

physics_viz.gif_recorder module

physics_viz.renderer module

Pygame renderer for 2D physics visualization

Renders rigid bodies, colliders, and debug information.

class physics_viz.renderer.Renderer(width=1280, height=720, title='2D Physics Simulator')

Bases: object

Pygame-based renderer for physics simulation

Handles rendering of rigid bodies, colliders, forces, and debug info. Supports camera transformations and multiple rendering modes.

COLORS = {'axis': (80, 80, 100), 'background': (20, 20, 30), 'collider': (150, 200, 255), 'dynamic_body': (100, 150, 255), 'force': (255, 200, 100), 'grid': (40, 40, 50), 'highlight': (255, 255, 100), 'static_body': (100, 100, 120), 'text': (200, 200, 200), 'velocity': (255, 100, 100)}

clear()

Clear screen with background color

draw_grid(spacing=1.0)

Draw grid lines

Parameters:

spacing – Grid spacing in meters

draw_circle_collider(body)

Draw a circle collider

Parameters:

body – RigidBody with CircleCollider

draw_box_collider(body)

Draw a box collider

Parameters:

body – RigidBody with BoxCollider

draw_body(body)

Draw a rigid body

Parameters:

body – RigidBody to draw

draw_velocity_vector(body, scale=0.5)

Draw velocity vector

Parameters:

• body – RigidBody

• scale – Vector scale factor

draw_world(world)

Draw entire physics world

Parameters:

world – PhysicsWorld to render

draw_stats(world)

Draw statistics overlay

Parameters:

world – PhysicsWorld

draw_text(text, position, font='small', color='text')

Draw text at position

Parameters:

• text – Text string

• position – Screen position (x, y)

• font – ‘small’ or ‘large’

• color – Color name from COLORS dict

draw_help()

Draw help overlay

flip()

Update display

tick(fps=60)

Limit frame rate

Parameters:

fps – Target frames per second

Returns:

Delta time in seconds

Return type:

float

quit()

Cleanup and quit

physics_viz.simulation module

Simulation runner for physics visualization

Manages the main simulation loop, input handling, and rendering.

class physics_viz.simulation.Simulation(width=1280, height=720, title='Physics Simulation', record_gif=None, record_duration=10)

Bases: object

Base class for physics simulations

Handles the main loop, input, timing, and rendering. Subclass this to create specific demo scenarios.

setup()

Setup simulation (override in subclasses)

Create bodies, set initial conditions, etc.

update(dt)

Update simulation logic (override in subclasses)

Parameters:

dt – Delta time in seconds

on_key_press(key)

Handle key press events (override in subclasses)

Parameters:

key – pygame key constant

on_mouse_click(pos, button)

Handle mouse click events (override in subclasses)

Parameters:

• pos – Mouse position (x, y) in screen space

• button – Mouse button (1=left, 2=middle, 3=right)

handle_input()

Process input events

handle_key_press(key)

Handle keyboard input

Parameters:

key – pygame key constant

reset()

Reset simulation to initial state

step_physics(dt)

Step physics simulation with fixed timestep

Uses accumulator for stable integration.

Parameters:

dt – Delta time in seconds

render()

Render frame

run()

Run simulation loop

class physics_viz.simulation.InteractiveSandbox

Bases: Simulation

Interactive physics sandbox

Click to spawn objects, drag to apply forces.

setup()

Setup sandbox with ground

on_mouse_click(pos, button)

Spawn object on click

Parameters:

• pos – Mouse position in screen space

• button – Mouse button

on_key_press(key)

Handle additional keys

Parameters:

key – pygame key constant

Module contents

Physics Visualization Package

This package provides a Python interface to the C++ physics engine, along with visualization tools using Pygame.

class physics_viz.Camera(screen_width, screen_height, pixels_per_meter=20.0)

Bases: object

2D camera with pan and zoom support

The camera transforms world coordinates (meters) to screen coordinates (pixels). Supports panning, zooming, and following objects.

focus_on(world_pos)

Center camera on world position

Parameters:

world_pos – Vector2 in world space

get_view_bounds()

Get visible world bounds

Returns:

(min_x, max_x, min_y, max_y) in world space

Return type:

tuple

pan(dx, dy)

Pan camera by screen offset

Parameters:

• dx – Horizontal pan in pixels

• dy – Vertical pan in pixels

screen_to_world(screen_pos)

Convert screen position (pixels) to world position (meters)

Parameters:

screen_pos – tuple (x, y) in screen space

Returns:

Vector2 in world space

screen_to_world_scalar(screen_scalar)

Convert screen distance (pixels) to world distance (meters)

Parameters:

screen_scalar – Distance in pixels

Returns:

Distance in meters

Return type:

float

world_to_screen(world_pos)

Convert world position (meters) to screen position (pixels)

Parameters:

world_pos – Vector2 in world space

Returns:

(x, y) in screen space

Return type:

tuple

world_to_screen_scalar(world_scalar)

Convert world distance (meters) to screen distance (pixels)

Parameters:

world_scalar – Distance in meters

Returns:

Distance in pixels

Return type:

int

zoom(factor, center=None)

Zoom camera by factor

Parameters:

• factor – Zoom multiplier (> 1 = zoom in, < 1 = zoom out)

• center – Optional screen position to zoom toward (tuple)

class physics_viz.Renderer(width=1280, height=720, title='2D Physics Simulator')

Bases: object

Pygame-based renderer for physics simulation

Handles rendering of rigid bodies, colliders, forces, and debug info. Supports camera transformations and multiple rendering modes.

COLORS = {'axis': (80, 80, 100), 'background': (20, 20, 30), 'collider': (150, 200, 255), 'dynamic_body': (100, 150, 255), 'force': (255, 200, 100), 'grid': (40, 40, 50), 'highlight': (255, 255, 100), 'static_body': (100, 100, 120), 'text': (200, 200, 200), 'velocity': (255, 100, 100)}

clear()

Clear screen with background color

draw_body(body)

Draw a rigid body

Parameters:

body – RigidBody to draw

draw_box_collider(body)

Draw a box collider

Parameters:

body – RigidBody with BoxCollider

draw_circle_collider(body)

Draw a circle collider

Parameters:

body – RigidBody with CircleCollider

draw_grid(spacing=1.0)

Draw grid lines

Parameters:

spacing – Grid spacing in meters

draw_help()

Draw help overlay

draw_stats(world)

Draw statistics overlay

Parameters:

world – PhysicsWorld

draw_text(text, position, font='small', color='text')

Draw text at position

Parameters:

• text – Text string

• position – Screen position (x, y)

• font – ‘small’ or ‘large’

• color – Color name from COLORS dict

draw_velocity_vector(body, scale=0.5)

Draw velocity vector

Parameters:

• body – RigidBody

• scale – Vector scale factor

draw_world(world)

Draw entire physics world

Parameters:

world – PhysicsWorld to render

flip()

Update display

quit()

Cleanup and quit

tick(fps=60)

Limit frame rate

Parameters:

fps – Target frames per second

Returns:

Delta time in seconds

Return type:

float

class physics_viz.Simulation(width=1280, height=720, title='Physics Simulation', record_gif=None, record_duration=10)

Bases: object

Base class for physics simulations

Handles the main loop, input, timing, and rendering. Subclass this to create specific demo scenarios.

handle_input()

Process input events

handle_key_press(key)

Handle keyboard input

Parameters:

key – pygame key constant

on_key_press(key)

Handle key press events (override in subclasses)

Parameters:

key – pygame key constant

on_mouse_click(pos, button)

Handle mouse click events (override in subclasses)

Parameters:

• pos – Mouse position (x, y) in screen space

• button – Mouse button (1=left, 2=middle, 3=right)

render()

Render frame

reset()

Reset simulation to initial state

run()

Run simulation loop

setup()

Setup simulation (override in subclasses)

Create bodies, set initial conditions, etc.

step_physics(dt)

Step physics simulation with fixed timestep

Uses accumulator for stable integration.

Parameters:

dt – Delta time in seconds

update(dt)

Update simulation logic (override in subclasses)

Parameters:

dt – Delta time in seconds

class physics_viz.InteractiveSandbox

Bases: Simulation

Interactive physics sandbox

Click to spawn objects, drag to apply forces.

on_key_press(key)

Handle additional keys

Parameters:

key – pygame key constant

on_mouse_click(pos, button)

Spawn object on click

Parameters:

• pos – Mouse position in screen space

• button – Mouse button

setup()

Setup sandbox with ground