Geometry helper module for orbital mechanics and spatial calculations #130

New Issue

john · 2025-10-31T02:49:37Z

john commented

2025-10-31 02:49:37 +00:00

Feature Request

Add a geometry helper module to simplify common spatial calculations like orbital mechanics, line intersections, angle calculations, and distance measurements.

Use Case: PINSHIPS Game

The PINSHIPS space roguelike requires complex spatial calculations:

Orbital arc calculations: Points along a circular arc around a planet
Line intersection: Check if movement path crosses obstacles
Angle calculations: Ship heading, firing angles, orbital entry angles
Distance/proximity checks: Weapon range, sensor detection
Velocity vectors: Ship momentum, orbital velocity

Current Workaround

Pure Python math:

import math

def circle_points(center, radius, start_angle, end_angle, num_points=20):
    """Calculate points along an arc - pure Python"""
    points = []
    for i in range(num_points):
        t = start_angle + (end_angle - start_angle) * i / (num_points - 1)
        rad = math.radians(t)
        x = center[0] + radius * math.cos(rad)
        y = center[1] + radius * math.sin(rad)
        points.append((x, y))
    return points

def distance(p1, p2):
    dx = p2[0] - p1[0]
    dy = p2[1] - p1[1]
    return math.sqrt(dx*dx + dy*dy)

def angle_between(p1, p2):
    dx = p2[0] - p1[0]
    dy = p2[1] - p1[1]
    return math.degrees(math.atan2(dy, dx))

This is totally acceptable! Pure Python math works fine for game logic.

When C++ Helpers Are Useful

C++ geometry helpers become valuable when:

Performance critical paths: Calculating thousands of arc points per frame
Integration with rendering: Arc points fed directly to Line/Arc drawing
Vector operations: If mcrfpy.Vector becomes a core type, geometry helpers naturally extend it

Proposed API

from mcrfpy.geometry import (
    circle_points,      # Points along circular arc
    arc_points,         # Alias for circle_points
    line_intersection,  # Where do two line segments intersect?
    distance,           # Euclidean distance
    distance_squared,   # Faster (no sqrt)
    angle_between,      # Angle from point A to point B
    rotate_point,       # Rotate point around origin
    lerp,              # Linear interpolation
    clamp,             # Clamp value to range
)

# Calculate orbital arc
arc = circle_points(center=(50, 50), radius=10, 
                   start_angle=45, end_angle=135, num_points=20)

# Check if paths intersect
hit = line_intersection(
    line1_start=(10, 10), line1_end=(50, 50),
    line2_start=(10, 50), line2_end=(50, 10)
)
if hit:
    print(f"Collision at {hit}")

# Ship heading
angle = angle_between(ship_pos, target_pos)
ship.rotation = angle

Implementation Options

Option A: Pure Python Module (RECOMMENDED)

Lives in build/scripts/mcrfpy/geometry.py
Zero C++ code needed
Easy to iterate and debug
Performance adequate for PINSHIPS scale

Option B: C++ Extension Module

Create src/Geometry.cpp with helper functions
Expose via McRFPy_API.cpp
Better performance for large-scale calculations
More complex to maintain

Option C: Hybrid Approach

Core functions in Python
Performance-critical functions in C++ (if profiling shows need)
Best of both worlds

Priority

Tier 2 Foundation - Nice to have, but pure Python is acceptable

Start with Option A - Create Python module first, profile later

Benefits

Cleaner game code: arc_points(...) vs manual trig
Less error-prone: Well-tested geometry functions
Reusable: Other projects can use the same helpers
Optional: Game can use pure Python math if preferred

Complements #128 (Line/Arc) by providing point calculations for rendering
Extends #109 (Vector convenience) with spatial operations
Foundation for potential physics systems

Implementation Steps

Create build/scripts/mcrfpy/geometry.py with pure Python implementations
Test with PINSHIPS orbital mechanics
Profile during Week 2-3 development
Move performance-critical functions to C++ only if needed (unlikely)

Labels

[Minor Feature] [priority:tier2-foundation] [system:python-binding]

## Feature Request Add a geometry helper module to simplify common spatial calculations like orbital mechanics, line intersections, angle calculations, and distance measurements. ## Use Case: PINSHIPS Game The PINSHIPS space roguelike requires complex spatial calculations: - **Orbital arc calculations**: Points along a circular arc around a planet - **Line intersection**: Check if movement path crosses obstacles - **Angle calculations**: Ship heading, firing angles, orbital entry angles - **Distance/proximity checks**: Weapon range, sensor detection - **Velocity vectors**: Ship momentum, orbital velocity ## Current Workaround Pure Python math: ```python import math def circle_points(center, radius, start_angle, end_angle, num_points=20): """Calculate points along an arc - pure Python""" points = [] for i in range(num_points): t = start_angle + (end_angle - start_angle) * i / (num_points - 1) rad = math.radians(t) x = center[0] + radius * math.cos(rad) y = center[1] + radius * math.sin(rad) points.append((x, y)) return points def distance(p1, p2): dx = p2[0] - p1[0] dy = p2[1] - p1[1] return math.sqrt(dx*dx + dy*dy) def angle_between(p1, p2): dx = p2[0] - p1[0] dy = p2[1] - p1[1] return math.degrees(math.atan2(dy, dx)) ``` **This is totally acceptable!** Pure Python math works fine for game logic. ## When C++ Helpers Are Useful C++ geometry helpers become valuable when: - **Performance critical paths**: Calculating thousands of arc points per frame - **Integration with rendering**: Arc points fed directly to Line/Arc drawing - **Vector operations**: If `mcrfpy.Vector` becomes a core type, geometry helpers naturally extend it ## Proposed API ```python from mcrfpy.geometry import ( circle_points, # Points along circular arc arc_points, # Alias for circle_points line_intersection, # Where do two line segments intersect? distance, # Euclidean distance distance_squared, # Faster (no sqrt) angle_between, # Angle from point A to point B rotate_point, # Rotate point around origin lerp, # Linear interpolation clamp, # Clamp value to range ) # Calculate orbital arc arc = circle_points(center=(50, 50), radius=10, start_angle=45, end_angle=135, num_points=20) # Check if paths intersect hit = line_intersection( line1_start=(10, 10), line1_end=(50, 50), line2_start=(10, 50), line2_end=(50, 10) ) if hit: print(f"Collision at {hit}") # Ship heading angle = angle_between(ship_pos, target_pos) ship.rotation = angle ``` ## Implementation Options ### Option A: Pure Python Module (RECOMMENDED) - Lives in `build/scripts/mcrfpy/geometry.py` - Zero C++ code needed - Easy to iterate and debug - Performance adequate for PINSHIPS scale ### Option B: C++ Extension Module - Create `src/Geometry.cpp` with helper functions - Expose via `McRFPy_API.cpp` - Better performance for large-scale calculations - More complex to maintain ### Option C: Hybrid Approach - Core functions in Python - Performance-critical functions in C++ (if profiling shows need) - Best of both worlds ## Priority **Tier 2 Foundation** - Nice to have, but pure Python is acceptable **Start with Option A** - Create Python module first, profile later ## Benefits - **Cleaner game code**: `arc_points(...)` vs manual trig - **Less error-prone**: Well-tested geometry functions - **Reusable**: Other projects can use the same helpers - **Optional**: Game can use pure Python math if preferred ## Related Issues - Complements #128 (Line/Arc) by providing point calculations for rendering - Extends #109 (Vector convenience) with spatial operations - Foundation for potential physics systems ## Implementation Steps 1. Create `build/scripts/mcrfpy/geometry.py` with pure Python implementations 2. Test with PINSHIPS orbital mechanics 3. Profile during Week 2-3 development 4. Move performance-critical functions to C++ only if needed (unlikely) ## Labels `[Minor Feature]` `[priority:tier2-foundation]` `[system:python-binding]`

john added the

Alpha Release Requirement

Bugfix

system:input

labels 2025-10-31 12:16:17 +00:00

john removed the

Alpha Release Requirement

Bugfix

system:input

labels 2025-10-31 12:44:52 +00:00

john added the

Alpha Release Requirement