From 9da7e80a90412443cb054d8dea2b3146b53f1e6f Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Wed, 4 Feb 2026 19:20:53 -0500 Subject: [PATCH] docs: Add maneuver UI controls implementation plan --- docs/planning/maneuver_ui_controls.md | 149 ++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/planning/maneuver_ui_controls.md diff --git a/docs/planning/maneuver_ui_controls.md b/docs/planning/maneuver_ui_controls.md new file mode 100644 index 0000000..82c7caf --- /dev/null +++ b/docs/planning/maneuver_ui_controls.md @@ -0,0 +1,149 @@ +# Maneuver UI Controls - Implementation Plan + +## Overview +Add functionality to the maneuver.h module to support UI controls for creating and managing maneuvers in the graphical simulation. + +## Current Interface Analysis + +The maneuver module currently has: +- **Burn direction functions**: `calculate_prograde_dir()`, `calculate_normal_dir()`, etc. +- **Burn application**: `apply_impulsive_burn()`, `apply_custom_burn()` +- **Maneuver execution**: `check_maneuver_trigger()`, `execute_maneuver()` +- **No dynamic maneuver management**: Maneuvers are only loaded from config files + +## Recommended Additions to maneuver.h + +### 1. Maneuver Creation and Management + +```cpp +// Create a new maneuver structure from parameters +Maneuver create_maneuver(const char* name, int craft_index, BurnDirection direction, + double delta_v, TriggerType trigger_type, double trigger_value); + +// Add maneuver to simulation (returns index or -1 on error) +int add_maneuver_to_simulation(SimulationState* sim, Maneuver maneuver); + +// Remove maneuver by name or index +bool remove_maneuver_by_name(SimulationState* sim, const char* name); +bool remove_maneuver_by_index(SimulationState* sim, int index); + +// Clear all unexecuted maneuvers for a spacecraft +void clear_pending_maneuvers(SimulationState* sim, int craft_index); +``` + +### 2. Burn Preview/Optimization + +```cpp +// Preview burn result without executing (returns new orbital elements) +OrbitalElements preview_burn_result(Spacecraft* craft, BurnDirection direction, + double delta_v, double parent_mass); + +// Calculate required delta-v for target orbital elements +double calculate_delta_v_for_elements(Spacecraft* craft, OrbitalElements target_elements, + double parent_mass); + +// Calculate Hohmann transfer delta-v (two burns) +struct HohmannTransfer { + double dv1; // First burn delta-v + double dv2; // Second burn delta-v + double transfer_time; // Time to apoapsis + double true_anomaly_2; // True anomaly for second burn +}; +HohmannTransfer calculate_hohmann_transfer(double r1, double r2, double central_mass); +``` + +### 3. Maneuver Information and Validation + +```cpp +// Get descriptive string for burn direction +const char* get_burn_direction_name(BurnDirection direction); + +// Get descriptive string for trigger type +const char* get_trigger_type_name(TriggerType trigger_type); + +// Check if a burn is feasible (e.g., not exceeding escape velocity if unintended) +bool validate_burn_parameters(Spacecraft* craft, BurnDirection direction, + double delta_v, double parent_mass); + +// Calculate time until true anomaly trigger +double calculate_time_to_true_anomaly(Spacecraft* craft, double target_anomaly, + double parent_mass); +``` + +### 4. Undo/Snapshot Support + +```cpp +// Save spacecraft state before burn +struct SpacecraftSnapshot { + OrbitalElements orbit; + Vec3 local_position; + Vec3 local_velocity; +}; +SpacecraftSnapshot save_spacecraft_snapshot(Spacecraft* craft); + +// Restore spacecraft state +void restore_spacecraft_snapshot(Spacecraft* craft, SpacecraftSnapshot snapshot); + +// Create reversible maneuver structure +struct ReversibleManeuver { + Maneuver maneuver; + SpacecraftSnapshot pre_burn_state; +}; +``` + +### 5. Maneuver Query Functions + +```cpp +// Find maneuver by name (already exists in tests but not in header) +int find_maneuver_by_name(SimulationState* sim, const char* name); + +// Get next pending maneuver for a spacecraft +Maneuver* get_next_pending_maneuver(SimulationState* sim, int craft_index); + +// Get count of pending maneuvers for a spacecraft +int get_pending_maneuver_count(SimulationState* sim, int craft_index); + +// Get all pending maneuvers for a spacecraft (returns array and count) +Maneuver** get_pending_maneuvers_for_craft(SimulationState* sim, int craft_index, int* out_count); +``` + +### 6. Burn Direction Visualization + +```cpp +// Get burn direction vector at specific orbital position +Vec3 get_burn_direction_at_anomaly(Spacecraft* craft, BurnDirection direction, + double true_anomaly, double parent_mass); +``` + +## Implementation Considerations + +1. **Dynamic array management**: Since `SimulationState` has `max_maneuvers`, the add function should check capacity before adding. + +2. **Name uniqueness**: The config loader already enforces unique names; the UI should too. + +3. **Craft index validation**: When adding maneuvers via UI, verify the craft index is valid. + +4. **UI integration points**: These functions would be called from: + - **Main loop**: When user adds/edits maneuvers + - **UI renderer**: For displaying burn previews and validation feedback + - **Config saving**: To export UI-created maneuvers to TOML + +## Priority Recommendations + +**High Priority** (core UI functionality): +1. `add_maneuver_to_simulation()` - Essential for UI creation +2. `remove_maneuver_by_index()` - For editing/deleting +3. `create_maneuver()` - Helper for constructing maneuvers +4. `get_burn_direction_name()` - For UI labels + +**Medium Priority** (enhanced UX): +5. `preview_burn_result()` - Show result before committing +6. `calculate_hohmann_transfer()` - Common operation +7. `validate_burn_parameters()` - Prevent errors + +**Lower Priority** (advanced features): +8. Snapshot/undo functions +9. Time-to-trigger calculations +10. Reversible maneuvers + +This follows the existing C-style patterns in the codebase (structs, enums, simple functions) and provides the core functionality needed for a maneuver creation UI.