matlab-convert-aerospace-coordinates

# Aerospace Fundamentals

Core Aerospace Toolbox functions for unit conversions, time conversions, coordinate transformations, and rotation representations.

## When to Use

- Converting between aerospace unit systems (SI, imperial, nautical)
- Computing Julian dates, modified Julian dates, decimal years, or TDB time
- Transforming positions between ECEF, ECI, LLA, or flat Earth frames
- Converting between geodetic and geocentric latitude
- Building DCMs for frame transformations (ECI↔ECEF, ECEF↔NED, body↔wind, body↔stability)
- Converting between Euler angles, DCMs, quaternions, and Rodrigues vectors
- Using the `quaternion` object for rotation math, interpolation, or composition
- Identifying which coordinate frame data is expressed in

## When NOT to Use

- Atmosphere models (`atmosisa`, `atmoscoesa`) — not covered here
- Airspeed corrections (`correctairspeed`) — not covered here
- Orbit propagation or satellite maneuvers — use Aerospace Blockset or Satellite Communications Toolbox
- Navigation-specific transforms (`lla2enu`, `lla2ned`) — use Navigation Toolbox
- Simulink blocks — use `/model-based-design-core:building-simulink-models`

## Workflow

1. **Identify the coordinate frame** — Determine what frame your data is in and what frame you need. See `references/coordinate-systems.md` for frame definitions and decision guide.
2. **Convert units first** — Ensure inputs match the function's expected units before calling transforms.
3. **Apply the transformation** — Use the appropriate function with correct argument ordering.
4. **Verify** — Round-trip the result back to the original frame; error should be < 1e-10.

## Key Functions

### Unit Conversions

| Function | Converts | Units |
|----------|----------|-------|
| `convlength` | Length | `'ft'`, `'m'`, `'km'`, `'in'`, `'mi'`, `'naut mi'` |
| `convvel` | Velocity | `'ft/s'`, `'m/s'`, `'km/s'`, `'in/s'`, `'km/h'`, `'mph'`, `'kts'`, `'ft/min'` |
| `convang` | Angle | `'deg'`, `'rad'`, `'rev'` |
| `convacc` | Acceleration | `'ft/s^2'`, `'m/s^2'`, `'km/s^2'`, `'in/s^2'`, `'km/h-s'`, `'mph/s'`, `'G''s'` |
| `convangacc` | Angular acceleration | `'deg/s^2'`, `'rad/s^2'`, `'rpm/s'` |
| `convangvel` | Angular velocity | `'deg/s'`, `'rad/s'`, `'rpm'` |
| `convforce` | Force | `'N'`, `'lbf'` |
| `convmass` | Mass | `'kg'`, `'lbm'`, `'slug'` |
| `convpres` | Pressure | `'Pa'`, `'psi'`, `'psf'`, `'atm'` |
| `convtemp` | Temperature | `'K'`, `'R'`, `'F'`, `'C'` |
| `convdensity` | Density | `'kg/m^3'`, `'slug/ft^3'`, `'lbm/ft^3'`, `'lbm/in^3'` |

All conversion functions use the same signature: `output = convXXX(value, fromUnit, toUnit)`

### Time Conversions

| Function | Purpose | Since |
|----------|---------|-------|
| `juliandate` | Calendar → Julian Date | R2006b |
| `mjuliandate` | Calendar → Modified Julian Date (JD − 2400000.5) | R2006b |
| `decyear` | Calendar → decimal year | R2006b |
| `leapyear` | Test if year is leap year | R2006b |
| `tdbjuliandate` | Terrestrial Time → TDB Julian Date | R2015a |

### Coordinate Transformations

| Function | From | To | Since |
|----------|------|-----|-------|
| `lla2ecef` | LLA (geodetic) | ECEF | R2006b |
| `ecef2lla` | ECEF | LLA (geodetic) | R2006b |
| `lla2eci` | LLA | ECI | R2014a |
| `eci2lla` | ECI | LLA | R2014a |
| `ecef2eci` | ECEF (pos/vel/acc) | ECI | R2019a |
| `eci2ecef` | ECI (pos/vel/acc) | ECEF | R2019a |
| `eci2aer` | ECI | AER (azimuth, elevation, range) | R2015a |
| `lla2flat` | LLA | Flat Earth | R2011a |
| `flat2lla` | Flat Earth | LLA | R2011a |
| `geod2geoc` | Geodetic latitude | Geocentric latitude | R2006b |
| `geoc2geod` | Geocentric latitude | Geodetic latitude | R2006b |
| `dcmeci2ecef` | — | ECI-to-ECEF DCM | R2013b |
| `dcmecef2ned` | — | ECEF-to-NED DCM | R2006b |
| `dcm2latlon` | ECEF-to-NED DCM | Lat/Lon | R2006b |
| `dcmbody2wind` | Alpha, Beta | Body-to-Wind DCM | R2006b |
| `dcm2alphabeta` | Body-to-Wind DCM | Alpha, Beta | R2006b |
| `dcmbody2stability` | Alpha | Body-to-Stability DCM | R2022a |

### Rotation Representations

| Function | From | To | Since |
|----------|------|-----|-------|
| `angle2dcm` | Euler angles | DCM | R2006b |
| `dcm2angle` | DCM | Euler angles | R2006b |
| `angle2quat` | Euler angles | Quaternion (1×4) | R2006b |
| `quat2angle` | Quaternion (1×4) | Euler angles | R2007b |
| `dcm2quat` | DCM | Quaternion (1×4) | R2006b |
| `quat2dcm` | Quaternion (1×4) | DCM | R2006b |
| `angle2rod` | Euler angles | Rodrigues vector | R2017a |
| `rod2angle` | Rodrigues vector | Euler angles | R2017a |
| `dcm2rod` | DCM | Rodrigues vector | R2017a |
| `rod2dcm` | Rodrigues vector | DCM | R2017a |
| `quat2rod` | Quaternion (1×4) | Rodrigues vector | R2017a |
| `rod2quat` | Rodrigues vector | Quaternion (1×4) | R2017a |

### Quaternion Object

| Method | Purpose |
|--------|---------|
| `quaternion(E,'eulerd',RS,PF)` | Create from Euler angles (degrees) |
| `quaternion(E,'euler',RS,PF)` | Create from Euler angles (radians) |
| `quaternion(RM,'rotmat',PF)` | Create from rotation matrix |
| `quaternion(RV,'rotvec')` | Create from rotation vector (radians) |
| `compact(q)` | Extract [w x y z] array |
| `eulerd(q,RS,PF)` | Convert to Euler angles (degrees) |
| `euler(q,RS,PF)` | Convert to Euler angles (radians) |
| `rotmat(q,PF)` | Convert to rotation matrix |
| `rotvec(q)` / `rotvecd(q)` | Convert to rotation vector (rad/deg) |
| `rotatepoint(q,pts)` | Rotate points (active rotation) |
| `rotateframe(q,pts)` | Rotate frame (passive rotation) |
| `normalize(q)` | Normalize to unit quaternion |
| `slerp(q1,q2,t)` | Spherical linear interpolation |
| `meanrot(q)` | Mean rotation of array |
| `dist(q1,q2)` | Angular distance (radians) |
| `angvel(q,dt,PF)` | Angular velocity from quaternion array |
| `randrot(n)` | Uniform random rotations |

### Quaternion Math (Array-Based)

| Function | Purpose | Since |
|----------|---------|-------|
| `quatmultiply(q,r)` | Quaternion product (compose rotations) | R2006b |
| `quatconj(q)` | Conjugate (negate vector