Feature/improve spacecraft attitude (#280)

* Feature/improve spacecraft attitude computation by introducing GetBodyFront method and updating attitude classes to use it

* Feature/add validation for orbital normal computation in attitude classes

Author: sylvain-guillet

DEVELOPER_GUIDE.md

@@ -10,7 +10,7 @@ IO.Astrodynamics.Net is a .NET 8/10 astrodynamics framework for orbital mechanic
 - **Ephemeris Computation**: Read and write SPICE kernel files for celestial bodies and spacecraft
 - **Time Systems**: Handle multiple time frames (UTC, TDB, TAI, TDT, GPS, Local)
 - **Reference Frames**: Transform between inertial and body-fixed frames (ICRF, ECLIPTIC, IAU frames)
-- **Spacecraft Modeling**: Define spacecraft with instruments, engines, fuel tanks, and payloads
+- **Spacecraft Modeling**: Define spacecraft with instruments, engines, fuel tanks, payloads, and configurable body axes
 - **Orbital Propagation**: Propagate orbits using numerical integration with perturbation models
 - **Maneuver Planning**: Compute delta-V requirements, launch windows, Lambert transfers
 - **Geometry Finding**: Search for occultations, eclipses, visibility windows, illumination conditions
@@ -26,7 +26,7 @@ IO.Astrodynamics.Net is a .NET 8/10 astrodynamics framework for orbital mechanic
 - Thermal analysis
 - Power system modeling
 - Communication link budgets (beyond basic geometry)
-- Detailed attitude control system design
+- Detailed attitude control system design (attitude determination/planning is supported; closed-loop control is not)
 
 ## Standards and Units
 
@@ -1226,7 +1226,7 @@ Represents a spacecraft with components.
 
 | Constructor | Description |
 |------------|-------------|
-| `Spacecraft(int naifId, string name, double dryMass, double maxMass, Clock clock, OrbitalParameters orbit, double sectionalArea = 1.0, double dragCoeff = 2.2, string cosparId = null, double solarRadiationCoeff = 1.0)` | Create spacecraft |
+| `Spacecraft(int naifId, string name, double dryMass, double maxMass, Clock clock, OrbitalParameters orbit, double sectionalArea = 1.0, double dragCoeff = 2.2, string cosparId = null, double solarRadiationCoeff = 1.0, Vector3? bodyFront = null, Vector3? bodyRight = null, Vector3? bodyUp = null)` | Create spacecraft |
 
 | Property | Description |
 |----------|-------------|
@@ -1240,6 +1240,12 @@ Represents a spacecraft with components.
 | `SolarRadiationCoeff` | Solar radiation pressure coefficient Cr (default 1.0, range 1.0–2.0) |
 | `InitialOrbitalParameters` | Initial orbit |
 | `StateVectorsRelativeToICRF` | Propagated states |
+| `BodyFront` | Instance body front axis (default: +Y, same as `Spacecraft.Front`) |
+| `BodyRight` | Instance body right axis (default: +X, same as `Spacecraft.Right`) |
+| `BodyUp` | Instance body up axis (default: +Z, same as `Spacecraft.Up`) |
+| `BodyBack` / `BodyLeft` / `BodyDown` | Computed inverses of body axes |
+
+**Configurable body axes**: Pass `bodyFront`, `bodyRight`, `bodyUp` to the constructor to override the default body frame. Custom axes must be orthogonal and right-handed (`bodyRight.Cross(bodyFront) == bodyUp`). All attitude maneuvers automatically use per-instance body axes via `GetBodyFront()`.
 
 | Method | Description |
 |--------|-------------|
@@ -1385,9 +1391,13 @@ Base class for orbital maneuvers.
 - `RetrogradeAttitude`: Orient opposite to velocity
 - `ZenithAttitude`: Orient away from central body
 - `NadirAttitude`: Orient toward central body
+- `NormalAttitude`: Orient along orbital normal (h = r × v)
+- `AntiNormalAttitude`: Orient opposite to orbital normal (−h)
 - `InstrumentPointingAttitude`: Point instrument at target (single-vector, roll unconstrained)
 - `TriadAttitude`: Fully-constrained 3-DOF attitude using TRIAD algorithm (eliminates roll ambiguity)
 
+All attitude maneuvers support configurable body axes via `GetBodyFront()`, which reads per-instance axes from `Spacecraft.BodyFront` with fallback to the static default `Spacecraft.Front` (+Y).
+
 **TRIAD Attitude Determination**
 
 The `TriadAttitude` class uses two non-collinear observation vectors to fully constrain spacecraft attitude. Unlike single-vector pointing, TRIAD eliminates roll ambiguity by constraining all three degrees of freedom.
@@ -1406,12 +1416,29 @@ var attitude = new TriadAttitude(
     camera,                    // Uses camera boresight (primary) and refVector (secondary)
     earth, sun,                // Primary target, secondary target
     engine);
+
+// Using IAttitudeTarget (orbital directions and/or celestial bodies)
+var attitude = new TriadAttitude(
+    earth, epoch, duration,
+    Spacecraft.Front, OrbitalDirectionTarget.Prograde,       // Primary: prograde pointing
+    Spacecraft.Up, new CelestialAttitudeTarget(sun),         // Secondary: solar panel toward Sun
+    engine);
+
+// Factory methods for common operational attitudes
+var lvlh = TriadAttitude.CreateLVLH(earth, epoch, duration, engine);
+var sunTrack = TriadAttitude.CreateProgradeWithSunTracking(earth, epoch, duration, sun, engine);
 ```
 
+**IAttitudeTarget system**: The `IAttitudeTarget` interface enables orbital directions and celestial bodies to be used interchangeably as TRIAD targets:
+- `OrbitalDirectionTarget` — predefined static instances: `.Prograde`, `.Retrograde`, `.Nadir`, `.Zenith`, `.Normal`, `.AntiNormal`
+- `CelestialAttitudeTarget` — wraps `ILocalizable`, computes direction via ephemeris with light-time correction
+- `OrbitalDirection` enum: `Prograde`, `Retrograde`, `Nadir`, `Zenith`, `Normal`, `AntiNormal`
+
 Key features:
 - Minimum 5-degree separation required between body vectors and reference vectors
-- Uses spacecraft body frame: Front (+Y), Right (+X), Up (+Z)
-- Three constructor overloads: single instrument, dual instruments, explicit vectors
+- Uses spacecraft body frame: Front (+Y), Right (+X), Up (+Z) — or per-instance `BodyFront`, `BodyRight`, `BodyUp`
+- Four constructor overloads: single instrument, dual instruments, explicit vectors, IAttitudeTarget
+- Factory methods: `CreateLVLH()`, `CreateProgradeWithSunTracking()`
 
 #### Impulse maneuvers
 
@@ -2712,8 +2739,25 @@ Console.WriteLine("Spacecraft maintains nadir pointing with roll constrained tow
 ```
 
 **When to use TRIAD vs single-vector attitude:**
-- Use `InstrumentPointingToAttitude`, `NadirAttitude`, etc. when roll is unconstrained (simpler, faster)
+- Use `InstrumentPointingToAttitude`, `NadirAttitude`, `NormalAttitude`, etc. when roll is unconstrained (simpler, faster)
+- Use `NormalAttitude` / `AntiNormalAttitude` for plane-change burns (h = r × v)
 - Use `TriadAttitude` when you need specific roll orientation (solar panels, thermal control, dual instruments)
+- Use `TriadAttitude` with `IAttitudeTarget` to mix orbital directions and celestial targets:
+
+```csharp
+// LVLH attitude using factory method
+var lvlh = TriadAttitude.CreateLVLH(earth, epoch, duration, engine);
+
+// Prograde with sun tracking using factory method
+var sunTrack = TriadAttitude.CreateProgradeWithSunTracking(earth, epoch, duration, sun, engine);
+
+// Custom: nadir pointing with normal constraint (using OrbitalDirectionTarget)
+var customLvlh = new TriadAttitude(
+    earth, epoch, duration,
+    Spacecraft.Down, OrbitalDirectionTarget.Nadir,
+    Spacecraft.Front, OrbitalDirectionTarget.Prograde,
+    engine);
+```
 
 ---
 

IO.Astrodynamics.Net/.claude/settings.local.json

@@ -39,7 +39,9 @@
       "Bash(dotnet run:*)",
       "Bash(echo:*)",
       "WebFetch(domain:docs.json-everything.net)",
-      "Bash(dotnet restore:*)"
+      "Bash(dotnet restore:*)",
+      "Bash(/home/sw/Applications/Cspice/exe/brief IO.Astrodynamics.Tests/Data/SolarSystem/earth_latest_high_prec.bpc)",
+      "Bash(git -C /home/sw/Sources/Astrodynamics/IO.Astrodynamics.Net stash)"
     ],
     "deny": [],
     "ask": []

IO.Astrodynamics.Net/CLAUDE.md

@@ -68,7 +68,7 @@ dotnet tool install --global --add-source ./IO.Astrodynamics.CLI/bin/Debug IO.As
 - `IO.Astrodynamics.OrbitalParameters.TLE`: Two-Line Element sets and OMM support
 - `IO.Astrodynamics.CCSDS.OMM`: CCSDS Orbit Mean-elements Message support (read/write/validate/convert)
 - `IO.Astrodynamics.CCSDS.OPM`: CCSDS Orbit Parameter Message support (read/write/validate/convert)
-- `IO.Astrodynamics.Maneuver`: Lambert solvers, launch windows, maneuver planning, attitude maneuvers
+- `IO.Astrodynamics.Maneuver`: Lambert solvers, launch windows, maneuver planning, attitude maneuvers, IAttitudeTarget system (orbital direction targets, celestial attitude targets)
 - `IO.Astrodynamics.Frames`: Reference frames and transformations
 - `IO.Astrodynamics.TimeSystem`: Time frames (UTC, TDB, TAI, etc.)
 - `IO.Astrodynamics.Propagator`: Orbital propagation and integration (Velocity-Verlet symplectic integrator)
@@ -480,6 +480,8 @@ The framework provides a family of attitude maneuvers for spacecraft orientation
 - `ZenithAttitude`: Points toward zenith (away from central body)
 - `ProgradeAttitude`: Velocity-direction pointing
 - `RetrogradeAttitude`: Anti-velocity pointing
+- `NormalAttitude`: Orbital normal pointing (h = r × v)
+- `AntiNormalAttitude`: Anti-normal pointing (−h)
 - `InstrumentPointingToAttitude`: Single-vector instrument pointing at a target
 - `TriadAttitude`: Two-vector fully-constrained attitude (eliminates roll ambiguity)
 
@@ -493,11 +495,30 @@ The `TriadAttitude` class implements the TRIAD algorithm for fully-constrained 3
 - **Minimum vector separation**: Default 5 degrees; prevents numerical instability from near-collinear vectors
 
 **Spacecraft Body Frame Convention**
+
+Default body axes (static fields, backward-compatible):
 - Front (+Y): `Spacecraft.Front`
 - Right (+X): `Spacecraft.Right`
 - Up (+Z): `Spacecraft.Up`
 - Down (-Z): `Spacecraft.Down`
 
+**Configurable Body Axes** — per-instance overrides for non-standard body frames (e.g., +X forward):
+- `BodyFront`, `BodyRight`, `BodyUp` — instance properties (default to static values)
+- `BodyBack`, `BodyLeft`, `BodyDown` — computed inverses
+- Passed via optional constructor parameters: `bodyFront`, `bodyRight`, `bodyUp`
+- Validation enforces orthogonality and right-handedness when custom axes are provided
+- All attitude maneuvers use `GetBodyFront()` (protected helper on `Maneuver` base class) which reads per-instance axes with static fallback
+
+```csharp
+// Spacecraft with +X as front (e.g., matching a SPICE FK convention)
+var spacecraft = new Spacecraft(-1001, "Sat", 1000, 5000, clock, orbit,
+    bodyFront: Vector3.VectorX, bodyRight: Vector3.VectorY.Inverse(), bodyUp: Vector3.VectorZ);
+
+// All attitude maneuvers automatically use BodyFront instead of Spacecraft.Front
+var prograde = new ProgradeAttitude(earth, epoch, duration, engine);
+// → orients spacecraft.BodyFront (+X) along velocity vector
+```
+
 **Constructor Options**
 
 1. **Single Instrument**: Uses instrument's boresight (primary) and refVector (secondary)
@@ -529,6 +550,47 @@ var attitude = new TriadAttitude(
     engine);
 ```
 
+4. **IAttitudeTarget (orbital directions and/or celestial bodies)**: Uses `IAttitudeTarget` interface for polymorphic targets
+```csharp
+// Point prograde with solar panels toward Sun
+var attitude = new TriadAttitude(
+    earth, epoch, duration,
+    Spacecraft.Front, OrbitalDirectionTarget.Prograde,
+    Spacecraft.Up, new CelestialAttitudeTarget(sun),
+    engine);
+
+// Full LVLH attitude (nadir pointing with prograde constraint)
+var lvlh = new TriadAttitude(
+    earth, epoch, duration,
+    Spacecraft.Down, OrbitalDirectionTarget.Nadir,
+    Spacecraft.Front, OrbitalDirectionTarget.Prograde,
+    engine);
+```
+
+**IAttitudeTarget System**
+
+The `IAttitudeTarget` interface enables orbital directions and celestial bodies to be used interchangeably as TRIAD targets:
+- `IAttitudeTarget.GetDirection(StateVector)` — returns a unit vector in the inertial frame
+- `IAttitudeTarget.Name` — human-readable target name
+
+**Implementations:**
+- `OrbitalDirectionTarget` — computes direction from state vector (prograde, nadir, normal, etc.)
+  - Predefined static instances: `OrbitalDirectionTarget.Prograde`, `.Retrograde`, `.Nadir`, `.Zenith`, `.Normal`, `.AntiNormal`
+- `CelestialAttitudeTarget` — wraps `ILocalizable`, computes direction via ephemeris with `Aberration.LT`
+
+**`OrbitalDirection` enum**: `Prograde`, `Retrograde`, `Nadir`, `Zenith`, `Normal`, `AntiNormal`
+
+**Factory Methods**
+
+Convenience factories for common operational attitudes:
+```csharp
+// LVLH: Front→Prograde, Down→Nadir
+var lvlh = TriadAttitude.CreateLVLH(earth, epoch, duration, engine);
+
+// Prograde with sun tracking: Front→Prograde, Up→Sun
+var sunTrack = TriadAttitude.CreateProgradeWithSunTracking(earth, epoch, duration, sun, engine);
+```
+
 **Use Case Examples**
 
 *Earth Observation with Sun Tracking*
@@ -551,6 +613,12 @@ var observation = new TriadAttitude(
     engine);
 ```
 
+*Plane-Change Attitude (Normal Pointing)*
+```csharp
+// Orient for plane-change burn: front along orbital normal
+var normalAttitude = new NormalAttitude(earth, epoch, duration, engine);
+```
+
 **Instrument Enhancements**
 
 The `Instrument` class now provides:
@@ -602,9 +670,14 @@ Test data files are in `Data/SolarSystem/` and copied to output directory.
    - User-defined parameters support custom mission-specific data
 9. **Attitude Maneuvers**: When implementing attitude control:
    - Use `TriadAttitude` for fully-constrained orientation (eliminates roll ambiguity)
-   - Use single-vector attitudes (`NadirAttitude`, `InstrumentPointingToAttitude`) only when roll is unconstrained
+   - Use single-vector attitudes (`NadirAttitude`, `ProgradeAttitude`, `NormalAttitude`, etc.) only when roll is unconstrained
+   - Use `NormalAttitude` / `AntiNormalAttitude` for plane-change burns (h = r × v)
    - Ensure body vectors and reference vectors are not collinear (minimum 5 degrees separation)
-   - Use `Spacecraft.Front`, `Spacecraft.Up`, etc. for standard body frame directions
+   - Use `Spacecraft.Front`, `Spacecraft.Up`, etc. for standard body frame directions; use instance `BodyFront`, `BodyRight`, `BodyUp` for non-standard frames
+   - Custom body axes must be orthogonal and right-handed (`BodyRight.Cross(BodyFront) == BodyUp`)
+   - All attitude maneuvers use `GetBodyFront()` which reads per-instance axes with static fallback
+   - Use `IAttitudeTarget` with `TriadAttitude` to mix orbital directions (`OrbitalDirectionTarget.Prograde`, etc.) and celestial targets (`CelestialAttitudeTarget`)
+   - Use factory methods `TriadAttitude.CreateLVLH()` and `CreateProgradeWithSunTracking()` for common operational attitudes
    - Use `Instrument.GetBoresightInSpacecraftFrame()` and `GetRefVectorInSpacecraftFrame()` for instrument-based pointing
 10. **Geopotential Gravity**: When working with spherical harmonic gravity models:
    - Pass `GeopotentialModelParameters` to `CelestialBody` constructor to enable geopotential

IO.Astrodynamics.Net/IO.Astrodynamics.CLI/IO.Astrodynamics.CLI.csproj

@@ -9,7 +9,7 @@
         <FileVersion>0.0.1</FileVersion>
         <PackAsTool>true</PackAsTool>
         <ToolCommandName>astro</ToolCommandName>
-        <Version>0.8.3.2</Version>
+        <Version>0.8.4.0-preview</Version>
         <Title>Astrodynamics command line interface</Title>
         <Authors>Sylvain Guillet</Authors>
         <Description>This CLI allows end user to exploit IO.Astrodynamics framework </Description>

IO.Astrodynamics.Net/IO.Astrodynamics.ConformanceRunner/Properties/launchSettings.json

@@ -2,11 +2,11 @@
   "profiles": {
     "ConformanceRunner": {
       "commandName": "Project",
-      "commandLineArgs": "/home/sw/CLionProjects/conformance-tests /home/sw/CLionProjects/Astrodynamics/IO.Astrodynamics.Net/IO.Astrodynamics.Tests/Data/SolarSystem /tmp/conformance-report.json"
+      "commandLineArgs": "/home/sw/Sources/conformance-tests /home/sw/Sources/Astrodynamics/IO.Astrodynamics.Net/IO.Astrodynamics.Tests/Data/SolarSystem /tmp/conformance-report.json"
     },
     "SmokeTest": {
       "commandName": "Project",
-      "commandLineArgs": "--smoke-test /home/sw/CLionProjects/Astrodynamics/IO.Astrodynamics.Net/IO.Astrodynamics.Tests/Data/SolarSystem"
+      "commandLineArgs": "--smoke-test /home/sw/Sources/Astrodynamics/IO.Astrodynamics.Net/IO.Astrodynamics.Tests/Data/SolarSystem"
     }
   }
 }

IO.Astrodynamics.Net/IO.Astrodynamics.ConformanceRunner/Solvers/EclipseSolver.cs

@@ -8,6 +8,7 @@
 using IO.Astrodynamics.Frames;
 using IO.Astrodynamics.Math;
 using IO.Astrodynamics.OrbitalParameters;
+using IO.Astrodynamics.SolarSystemObjects;
 using IO.Astrodynamics.TimeSystem;
 
 namespace IO.Astrodynamics.ConformanceRunner.Solvers;
@@ -36,7 +37,10 @@ public Dictionary<string, object> Solve(CaseInput caseInput)
             new Clock("ConfClk", 65536), sv);
 
         spacecraft.Propagate(searchWindow,
-            [occultingBody],
+            [
+                occultingBody, lightSource, PlanetsAndMoons.MOON_BODY, Barycenters.JUPITER_BARYCENTER, Barycenters.MARS_BARYCENTER, Barycenters.MERCURY_BARYCENTER,
+                Barycenters.SATURN_BARYCENTER, Barycenters.URANUS_BARYCENTER, Barycenters.VENUS_BARYCENTER
+            ],
             false, false, TimeSpan.FromSeconds(1.0));
 
         var stepSize = TimeSpan.FromSeconds(60.0);
@@ -128,4 +132,4 @@ private static StateVector BuildStateVector(object orbit, CelestialBody observer
 
         throw new ArgumentException("Unknown orbit type");
     }
-}
+}