loading...
running...
How to use
Pick a preset or move the sliders; all of them are live except the ones marked as applying on Restart. The central picture is the spacecraft with its body axes (x red, y green, z blue, solid) and the target attitude (dashed). The arrows show the magnetic field B, the direction to Earth (nadir), the total angular momentum H and the angular velocity w. The right side shows the orbit, the three reaction wheels (spokes spin with the wheel; the bar shows how full each wheel is) and the three magnetorquer dipoles. The graphs below show the pointing error, body rates, wheel fill, wheel torque and magnetorquer dipole.
Things to try: (1) preset “Slew 90 degrees”: raise the damping to 2, then drop it to 0.2 and compare the overshoot with the predicted value in the readout; (2) “Detumble”: raise or lower the B-dot gain, then lower the dipole limit and see the detumble slow down; set the inclination to 0 and note that the field direction hardly changes, so detumbling about the field line becomes slow; (3) “PD leaves an offset”: switch the law to PID; (4) “Wheel saturation” against “Wheels with momentum dumping”; (5) “Intermediate-axis flip”: change the spin axis to x or z and compare the stability; (6) press Kick to hit the spacecraft with a 2 deg/s impulse and watch the recovery; (7) press Target +30 deg yaw repeatedly for a staircase of commands. Drag to orbit, wheel to zoom. Space pauses, R restarts.
The spacecraft (bus with gold thermal blanket and honeycomb panels, two solar wings with cell grids, antenna dish, star tracker, sun sensors, thrusters, a cutaway with three reaction wheels, three magnetorquer rods and a gyro box) and the Earth with baked clouds and city lights were modelled in Blender 5.2 and exported as one Draco GLB with baked PBR textures. Three.js r160 moves the real model with the same quaternion as the 2D page, spins the wheels at their true speed, draws the field, momentum and target frame, and flies the Earth past as the orbit advances.
The science
A satellite changes its orientation only by exchanging angular momentum: with its own wheels, with the Earth's magnetic field, or with the environment. There is nothing to push against in vacuum. This lab integrates the full rigid-body equations and lets you close the loop with the same actuators a small spacecraft really carries.
1. Attitude kinematics (quaternion). The orientation is a unit quaternion q = (w, x, y, z) from the body to the inertial frame. With the body angular velocity ω:
dq/dt = (1/2) q ⊗ (0, ω), |q| = 1
Quaternions have no gimbal lock and are cheap to integrate. q and −q are the same attitude, so the controller always uses the shorter rotation (it flips the sign when w < 0).
2. Dynamics with reaction wheels (Euler's equation). The total angular momentum in the body frame is H = Jω + h, where J is the inertia tensor of the spacecraft body (principal axes here) and h the angular momentum stored in the wheels. The wheel torque on the body is u = −dh/dt:
J dω/dt = −ω × (Jω + h) − dh/dt + τgg + τmag + τdist
The term ω × H is the gyroscopic coupling. Without any torque, |H| and the kinetic energy are conserved. A spin about the axis of largest or smallest inertia is stable, a spin about the intermediate axis is not (the “tennis racket” flip, preset “Intermediate-axis flip”).
3. Quaternion PD / PID control. With the error quaternion qe = qtarget−1 ⊗ q (vector part qev, about half the error angle) and the rate error ωe:
u = −Kp (2 qev) − Kd ωe − Ki ∫ 2 qev dt, Kp = J ωn2, Kd = 2 ζ J ωn
For a small rotation about a principal axis this is a second-order system with natural frequency ωn and damping ratio ζ: overshoot = exp(−πζ/√(1−ζ2)) and settling time about 4/(ζ ωn). The integral term removes the steady offset a constant torque would otherwise leave (Kp θ = τ). It is clamped (anti-windup) so a saturated wheel does not accumulate a huge integral. The optional feed-forward adds ω × H to cancel the gyroscopic term in fast slews.
4. Wheel limits. A wheel can give only a limited torque and can store only a limited momentum (hmax = Iw Ωmax; here Iw = 0.001 kg m²). A constant external torque makes the stored momentum grow without limit: the wheels saturate and the spacecraft loses authority. The remedy is to dump momentum with an external torque.
5. Magnetorquers. A coil with dipole moment m in the geomagnetic field B feels τ = m × B. The torque is always perpendicular to B, so it cannot act about the field line at that instant, but the field direction changes along the orbit. The field is a centred dipole, B = B0(RE/r)3[3(&zhat;·r̂)r̂ − &zhat;], B0 = 31.2 μT.
B-dot detumbling: m = −k dB/dt (measured in the body frame), |mi| ≤ mmax
Momentum dumping: m = −(1/Td) (B × h) / |B|2 ⇒ τ = −h⊥B / Td
Because dB/dt in the body frame is about −ω × B, the B-dot law acts like a damper that turns the spacecraft rate into heat-free momentum exchange with the field. It needs only a magnetometer, no star tracker and no gyro, which is why nearly every CubeSat uses it right after release.
6. Gravity gradient. The Earth pulls the near end of the body harder than the far end: τgg = 3n2 r̂ × (J r̂), with r̂ the unit vector to the Earth centre in the body frame and n = √(μ/r3) the orbit rate. A body with its smallest inertia along the vertical librates about the nadir with pitch frequency n√(3(Jx−Jz)/Jy).
Numerics. Fourth-order Runge-Kutta, 25 ms step, quaternion renormalised each step; the controller runs at 20 Hz with zero-order hold. Sensor noise is Gaussian with a fixed seed.
Numerical checks run in the page. (1) Torque-free tumble: |H| and the kinetic energy stay constant to better than 1e-6; (2) an axisymmetric body precesses at (Jz−Jx)/Jx · ω3 in the body frame; (3) the simulated overshoot of a 10 degree PD step equals the second-order formula; (4) the total inertial angular momentum is conserved during a 60 degree wheel slew; (5) the gravity-gradient libration period equals 2π/(n√(3(Jx−Jz)/Jy)); (6) B-dot reduces the rate and the magnetic torque is perpendicular to B.
Simplifications. Principal-axis inertia (no products of inertia); three orthogonal wheels, not a four-wheel pyramid; ideal torque-controlled wheels without friction or jitter; a centred, non-rotating dipole field and a circular orbit; no atmosphere model (drag and solar pressure are replaced by a constant torque you set; the default presets use larger values than a real 500 km orbit so that saturation takes minutes instead of days); no eclipse, no flexible panels, no fuel slosh; the inertia values are illustrative, not those of a particular mission. Nothing here is a flight-software design.