@typescriptify/sweph 1.0.0

package/src/SwissEph/UseCases/Planetocentric.md

@@ -0,0 +1,278 @@
+# Planetocentric Positions
+
+**Planetocentric coordinates** give you the position of a celestial body as seen from a planet other than Earth. Normal astronomical calculations are **geocentric** -- they describe positions as seen from Earth's center. But what if you wanted to know where Jupiter appears in the sky as seen from Mars? Or where Earth is positioned from the perspective of Venus?
+
+The `calcPlanetocentric()` method lets you place your virtual observer on any planet and look at the sky from there.
+
+This is useful for:
+- **Space mission planning**: understanding what the sky looks like from another planet's reference frame
+- **Comparative planetology**: how do planetary configurations (conjunctions, oppositions, etc.) look from other vantage points?
+- **Science fiction worldbuilding**: if you are writing a story set on Mars, what constellations and planetary motions would your characters observe?
+- **Educational purposes**: illustrating that geocentric positions are not absolute -- they depend on where you are standing
+- **Verification**: geocentric positions of a planet should closely match planetocentric positions computed "from Earth" -- this serves as a sanity check
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS, SE_JUPITER } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 6, 15, 12);
+
+// Where does Jupiter appear as seen from Mars?
+const jupFromMars = swe.calcPlanetocentric(jd, SE_JUPITER, SE_MARS);
+
+console.log(`Jupiter as seen from Mars:`);
+console.log(`  Longitude: ${jupFromMars.longitude.toFixed(4)} deg`);
+console.log(`  Latitude:  ${jupFromMars.latitude.toFixed(4)} deg`);
+console.log(`  Distance:  ${jupFromMars.distance.toFixed(6)} AU`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### Earth as seen from Mars
+
+What would a Martian astronomer observe when looking at Earth? Earth would appear as a bright inner planet (similar to how we see Venus), going through phases and never straying far from the Sun.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_EARTH, SE_MARS } from '../../constants';
+
+const swe = new SwissEph();
+
+// Track Earth's position as seen from Mars over one Martian year (~687 days)
+const startJd = SwissEph.julianDay(2025, 1, 1, 0);
+
+const signs = ['Ari','Tau','Gem','Can','Leo','Vir','Lib','Sco','Sag','Cap','Aqu','Pis'];
+
+console.log('Earth as seen from Mars (monthly snapshots):');
+for (let i = 0; i < 24; i++) {
+  const jd = startJd + i * 30;
+  const earth = swe.calcPlanetocentric(jd, SE_EARTH, SE_MARS);
+  const date = SwissEph.fromJulianDay(jd);
+
+  const signIdx = Math.floor(earth.longitude / 30);
+  const degInSign = earth.longitude - signIdx * 30;
+
+  console.log(
+    `  ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}  ` +
+    `${degInSign.toFixed(1).padStart(5)} ${signs[signIdx]}  ` +
+    `dist=${earth.distance.toFixed(4)} AU  ` +
+    `speed=${earth.longitudeSpeed.toFixed(4)} deg/day`
+  );
+}
+
+swe.close();
+```
+
+### Verifying: Mars from Earth vs geocentric Mars
+
+Geocentric positions are simply planetocentric positions "from Earth." Calculating Mars from Earth using `calcPlanetocentric()` should produce results nearly identical to a regular `calc()` call.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_MARS, SE_EARTH } from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 6, 15, 12);
+
+// Standard geocentric calculation
+const marsGeo = swe.calc(jd, SE_MARS);
+
+// Planetocentric: Mars as seen from Earth
+const marsPctr = swe.calcPlanetocentric(jd, SE_MARS, SE_EARTH);
+
+console.log('Mars positions comparison:');
+console.log(`  Geocentric longitude:      ${marsGeo.longitude.toFixed(6)} deg`);
+console.log(`  Planetocentric (Earth):    ${marsPctr.longitude.toFixed(6)} deg`);
+console.log(`  Difference:                ${Math.abs(marsGeo.longitude - marsPctr.longitude).toFixed(6)} deg`);
+// The difference should be very small (< 0.01 deg)
+
+console.log(`\n  Geocentric distance:       ${marsGeo.distance.toFixed(6)} AU`);
+console.log(`  Planetocentric distance:   ${marsPctr.distance.toFixed(6)} AU`);
+
+swe.close();
+```
+
+### The Sun as seen from different planets
+
+How does the Sun's apparent position differ when viewed from different planets?
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_SUN, SE_MERCURY, SE_VENUS, SE_MARS,
+  SE_JUPITER, SE_SATURN,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 3, 20, 12); // near vernal equinox
+
+const observers = [
+  { id: SE_MERCURY, name: 'Mercury' },
+  { id: SE_VENUS,   name: 'Venus' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_JUPITER, name: 'Jupiter' },
+  { id: SE_SATURN,  name: 'Saturn' },
+];
+
+console.log('The Sun as seen from each planet:');
+for (const obs of observers) {
+  const sun = swe.calcPlanetocentric(jd, SE_SUN, obs.id);
+  console.log(
+    `  From ${obs.name.padEnd(8)}:  ` +
+    `lon=${sun.longitude.toFixed(2).padStart(7)} deg  ` +
+    `dist=${sun.distance.toFixed(4)} AU`
+  );
+}
+
+// For reference: the Sun from Earth (geocentric)
+const sunGeo = swe.calc(jd, SE_SUN);
+console.log(
+  `  From Earth   :  ` +
+  `lon=${sunGeo.longitude.toFixed(2).padStart(7)} deg  ` +
+  `dist=${sunGeo.distance.toFixed(4)} AU`
+);
+
+swe.close();
+```
+
+### Retrograde motion from a different planet
+
+On Earth, Mars appears retrograde for about 2 months every ~26 months. What does Jupiter's motion look like from Mars?
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_JUPITER, SE_MARS } from '../../constants';
+
+const swe = new SwissEph();
+
+// Check Jupiter's speed as seen from Mars over two years
+const startJd = SwissEph.julianDay(2025, 1, 1, 0);
+
+console.log('Jupiter longitude speed as seen from Mars:');
+for (let i = 0; i < 24; i++) {
+  const jd = startJd + i * 30;
+  const jup = swe.calcPlanetocentric(jd, SE_JUPITER, SE_MARS);
+  const date = SwissEph.fromJulianDay(jd);
+  const direction = jup.longitudeSpeed < 0 ? 'RETRO' : 'direct';
+  console.log(
+    `  ${date.year}-${String(date.month).padStart(2,'0')}-${String(date.day).padStart(2,'0')}  ` +
+    `speed=${jup.longitudeSpeed.toFixed(4).padStart(8)} deg/day  ${direction}`
+  );
+}
+
+swe.close();
+```
+
+### Multiple bodies from Jupiter
+
+View the inner solar system from Jupiter's perspective -- all the inner planets and the Sun.
+
+```typescript
+import { SwissEph } from '../index';
+import {
+  SE_SUN, SE_MERCURY, SE_VENUS, SE_EARTH, SE_MARS,
+  SE_SATURN, SE_JUPITER,
+} from '../../constants';
+
+const swe = new SwissEph();
+const jd = SwissEph.julianDay(2025, 7, 4, 12);
+
+const targets = [
+  { id: SE_SUN,     name: 'Sun' },
+  { id: SE_MERCURY, name: 'Mercury' },
+  { id: SE_VENUS,   name: 'Venus' },
+  { id: SE_EARTH,   name: 'Earth' },
+  { id: SE_MARS,    name: 'Mars' },
+  { id: SE_SATURN,  name: 'Saturn' },
+];
+
+console.log('Sky from Jupiter on 2025-Jul-04:');
+for (const t of targets) {
+  const pos = swe.calcPlanetocentric(jd, t.id, SE_JUPITER);
+  console.log(
+    `  ${t.name.padEnd(8)}  ` +
+    `lon=${pos.longitude.toFixed(2).padStart(7)}  ` +
+    `lat=${pos.latitude.toFixed(2).padStart(6)}  ` +
+    `dist=${pos.distance.toFixed(3).padStart(7)} AU`
+  );
+}
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### What "planetocentric" means
+
+In standard (geocentric) astronomy, all positions are computed relative to the center of the Earth. The Earth is the implied observer. **Planetocentric** means the observer is at the center of a different planet. The computation is conceptually the same -- it is a coordinate transformation that shifts the origin from Earth to the specified planet.
+
+Mathematically, if you know the heliocentric position of both the target body and the observer body, the planetocentric position is:
+
+```
+target_from_observer = target_heliocentric - observer_heliocentric
+```
+
+The Swiss Ephemeris then applies the same corrections it normally does (light-time, aberration, etc.) but relative to the new observer position.
+
+### Why results differ from geocentric
+
+When you compute Mars from Earth (geocentric) and Mars from Jupiter (Jupitocentric), you get very different results because:
+
+1. **Different vantage point**: You are looking at Mars from a completely different position in space. The ecliptic longitude of Mars depends on the angle between the observer and Mars, which changes dramatically depending on where the observer is.
+
+2. **Different distance**: The distance to Mars is different from Earth vs from Jupiter, which affects light-time correction and apparent position.
+
+3. **Different retrograde patterns**: Retrograde motion is an apparent effect caused by the observer's own orbital motion. Since different planets move at different speeds and in different sized orbits, the retrograde patterns of other planets look completely different from each vantage point.
+
+### The center parameter
+
+The `center` parameter specifies which planet the observer is on. Use the standard planet constants:
+
+| Constant | Value | Observer is on |
+|----------|-------|---------------|
+| `SE_MERCURY` | 2 | Mercury |
+| `SE_VENUS` | 3 | Venus |
+| `SE_EARTH` | 14 | Earth (equivalent to geocentric `calc()`) |
+| `SE_MARS` | 4 | Mars |
+| `SE_JUPITER` | 5 | Jupiter |
+| `SE_SATURN` | 6 | Saturn |
+| `SE_URANUS` | 7 | Uranus |
+| `SE_NEPTUNE` | 8 | Neptune |
+| `SE_PLUTO` | 9 | Pluto |
+
+You cannot use the Sun as the center (use `SEFLG_HELCTR` in `calc()` for heliocentric positions). You also cannot use the Moon as the center because it is a satellite of Earth, not an independent heliocentric body in this context.
+
+### Relationship to geocentric and heliocentric
+
+The three main reference frames in positional astronomy are:
+
+- **Heliocentric**: positions relative to the Sun's center. Pure orbital mechanics. No observer effects. Get this with `calc(jd, planet, SEFLG_HELCTR)`.
+- **Geocentric**: positions relative to Earth's center. This is the standard for Earth-based astronomy and astrology. Get this with `calc(jd, planet)`.
+- **Planetocentric**: positions relative to another planet's center. Get this with `calcPlanetocentric(jd, planet, center)`.
+
+Geocentric is simply the special case of planetocentric where the center is Earth (`SE_EARTH`).
+
+### Limitations
+
+- Not all flag combinations may work with `calcPlanetocentric()`. The basic ecliptic coordinates are always available. Equatorial coordinates (`SEFLG_EQUATORIAL`) should work. Sidereal mode (`SEFLG_SIDEREAL`) works but uses Earth's precession/ayanamsa, not the other planet's.
+- You cannot compute the position of a planet as seen from itself (e.g., `calcPlanetocentric(jd, SE_MARS, SE_MARS)` is meaningless and will produce zero or an error).
+- The calculation does not account for the **topography** of the other planet -- it places the observer at the planet's center, not on its surface. There is no "topocentric from Mars" capability.
+
+### Practical uses
+
+**Space missions**: When a spacecraft is orbiting or approaching Mars, mission planners need to know where other bodies appear in the Martian sky. While actual mission planning uses more sophisticated tools, planetocentric calculations provide a useful first approximation.
+
+**Astrology from other planets**: Some astrologers have experimented with computing charts for other planets -- for example, a "Martian natal chart" for a Mars rover landing. Planetocentric positions would be the basis for such a chart.
+
+**Understanding parallax**: Comparing geocentric and planetocentric positions for the same target illustrates the concept of parallax on a solar-system scale. The Sun is at nearly the same ecliptic longitude from all planets, but the direction shifts by 180 degrees for the inner planets (because you are looking "back" toward the Sun from the other side).

package/src/SwissEph/UseCases/Refraction.md

@@ -0,0 +1,314 @@
+# Refraction
+
+**Atmospheric refraction** is the bending of light as it passes through Earth's atmosphere. Because the atmosphere acts like a giant lens -- denser near the ground, thinner higher up -- light from celestial objects follows a slightly curved path rather than a straight line. The result is that objects in the sky appear **higher** than they actually are.
+
+The effect is dramatic near the horizon and negligible high in the sky:
+
+- At the horizon (0 degrees altitude), refraction lifts an object by about **34 arcminutes** -- which is larger than the Sun's or Moon's apparent diameter (~31 arcminutes). This means that when you see the Sun sitting right on the horizon at sunset, its geometric center has actually already dropped below the horizon. The "sunset" you see is an atmospheric illusion.
+- At 10 degrees altitude, refraction is about 5 arcminutes.
+- At 45 degrees altitude, refraction is about 1 arcminute.
+- At the zenith (90 degrees altitude), refraction is zero.
+
+The Swiss Ephemeris provides a `refraction()` function to compute this correction in both directions: given the true (geometric) altitude, compute the apparent (observed) altitude, and vice versa.
+
+---
+
+## Quick Example
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_TRUE_TO_APP, SE_APP_TO_TRUE } from '../../constants';
+
+const swe = new SwissEph();
+
+// An object at true altitude 0 degrees (geometric horizon)
+// What apparent altitude does it appear at?
+const apparent = swe.refraction(0, 1013.25, 15, SE_TRUE_TO_APP);
+console.log(`True alt 0 deg -> Apparent alt: ${(apparent * 60).toFixed(1)} arcmin above horizon`);
+// ~34.5 arcminutes
+
+// An object observed at apparent altitude 1 degree
+// What is its true geometric altitude?
+const correction = swe.refraction(1, 1013.25, 15, SE_APP_TO_TRUE);
+const trueAlt = 1 + correction;  // correction is negative for APP_TO_TRUE
+console.log(`Apparent alt 1 deg -> True alt: ${(trueAlt * 60).toFixed(1)} arcmin`);
+
+swe.close();
+```
+
+---
+
+## Detailed Examples
+
+### True-to-apparent: how high does an object appear?
+
+When you know the true (geometric) altitude and want to know where the object appears in the refracted sky:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_TRUE_TO_APP } from '../../constants';
+
+const swe = new SwissEph();
+
+// Standard atmosphere: 1013.25 mbar, 15 degrees C
+const pressure = 1013.25;
+const temperature = 15;
+
+console.log('True Altitude    Apparent Altitude    Refraction');
+console.log('-------------    -----------------    ----------');
+
+const altitudes = [0, 0.5, 1, 2, 5, 10, 15, 20, 30, 45, 60, 90];
+
+for (const trueAlt of altitudes) {
+  const apparentAlt = swe.refraction(trueAlt, pressure, temperature, SE_TRUE_TO_APP);
+  const refraction = apparentAlt - trueAlt;
+  console.log(
+    `${trueAlt.toFixed(1).padStart(8)} deg` +
+    `${apparentAlt.toFixed(4).padStart(14)} deg` +
+    `${(refraction * 60).toFixed(2).padStart(12)} arcmin`
+  );
+}
+
+swe.close();
+```
+
+Expected approximate output:
+
+| True Altitude | Apparent Altitude | Refraction  |
+|---------------|-------------------|-------------|
+| 0.0 deg       | 0.575 deg         | 34.5 arcmin |
+| 0.5 deg       | 1.038 deg         | 32.3 arcmin |
+| 1.0 deg       | 1.478 deg         | 28.7 arcmin |
+| 2.0 deg       | 2.353 deg         | 21.2 arcmin |
+| 5.0 deg       | 5.159 deg         | 9.5 arcmin  |
+| 10.0 deg      | 10.088 deg        | 5.3 arcmin  |
+| 20.0 deg      | 20.044 deg        | 2.6 arcmin  |
+| 45.0 deg      | 45.016 deg        | 1.0 arcmin  |
+| 90.0 deg      | 90.000 deg        | 0.0 arcmin  |
+
+### Apparent-to-true: where is an object really?
+
+When you have observed an object at a certain apparent altitude and want to know its true geometric altitude:
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_APP_TO_TRUE } from '../../constants';
+
+const swe = new SwissEph();
+
+// Standard atmosphere
+const pressure = 1013.25;
+const temperature = 15;
+
+// I observed a star at apparent altitude 2 degrees.
+// What is its true altitude?
+const apparentAlt = 2;
+const correction = swe.refraction(apparentAlt, pressure, temperature, SE_APP_TO_TRUE);
+
+// For SE_APP_TO_TRUE, the function returns a negative correction value.
+// Add it to the apparent altitude to get the true altitude.
+const trueAlt = apparentAlt + correction;
+
+console.log(`Observed (apparent) altitude: ${apparentAlt.toFixed(4)} deg`);
+console.log(`Refraction correction:       ${(correction * 60).toFixed(2)} arcmin`);
+console.log(`True (geometric) altitude:   ${trueAlt.toFixed(4)} deg`);
+
+swe.close();
+```
+
+### Effect of pressure and temperature
+
+Atmospheric refraction depends on air density, which is controlled by pressure and temperature. Higher pressure and lower temperature both mean denser air and more refraction.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_TRUE_TO_APP } from '../../constants';
+
+const swe = new SwissEph();
+
+const trueAlt = 0; // Horizon -- where the effect is most pronounced
+
+const conditions = [
+  { label: 'Standard atmosphere (sea level, mild)', pressure: 1013.25, temp: 15 },
+  { label: 'Hot sea level (tropical noon)',         pressure: 1013.25, temp: 40 },
+  { label: 'Cold sea level (arctic winter)',        pressure: 1013.25, temp: -30 },
+  { label: 'Mountain (3000m, cool)',                pressure: 700,     temp: 5 },
+  { label: 'High mountain (5000m, cold)',           pressure: 540,     temp: -15 },
+  { label: 'No atmosphere (vacuum)',                pressure: 0,       temp: 0 },
+];
+
+console.log('Refraction at the horizon under different conditions:');
+console.log('');
+
+for (const c of conditions) {
+  const apparentAlt = swe.refraction(trueAlt, c.pressure, c.temp, SE_TRUE_TO_APP);
+  const refractionArcmin = apparentAlt * 60;
+  console.log(`${c.label}`);
+  console.log(`  Pressure: ${c.pressure} mbar, Temp: ${c.temp} C`);
+  console.log(`  Refraction: ${refractionArcmin.toFixed(1)} arcmin`);
+  console.log('');
+}
+
+swe.close();
+```
+
+### Why sunset is later than you think
+
+The Sun's apparent diameter is about 32 arcminutes. The standard definition of sunrise/sunset is when the Sun's upper limb touches the apparent horizon. The geometric center of the Sun at this moment is about 50 arcminutes (34' refraction + 16' solar semi-diameter) below the geometric horizon.
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_TRUE_TO_APP } from '../../constants';
+
+const swe = new SwissEph();
+
+// At standard sunset, the Sun's center is at about -0.833 degrees true altitude
+// (-50 arcminutes: -34' refraction + -16' semi-diameter)
+const sunsetTrueAlt = -50 / 60; // -0.833 degrees
+
+const apparentAlt = swe.refraction(Math.abs(sunsetTrueAlt), 1013.25, 15, SE_TRUE_TO_APP);
+console.log(`At sunset, the Sun's true altitude:     ${sunsetTrueAlt.toFixed(3)} deg`);
+console.log(`Refraction at the horizon:              ${(0.575 * 60).toFixed(1)} arcmin`);
+console.log(`Sun's semi-diameter:                    ~16 arcmin`);
+console.log(`Total geometric depression at sunset:   ~50 arcmin`);
+console.log('');
+console.log('This means the Sun is already geometrically below the horizon');
+console.log('when you see it touching the horizon at sunset!');
+
+// How much time does this add?
+// The Sun moves about 1 degree per day = 4 minutes per degree
+// 50 arcminutes = 0.833 degrees, so sunset is delayed by:
+const delayMinutes = (50 / 60) * 4;
+console.log(`\nSunset is delayed by approximately ${delayMinutes.toFixed(1)} minutes due to refraction`);
+
+swe.close();
+```
+
+### Building a refraction table
+
+```typescript
+import { SwissEph } from '../index';
+import { SE_TRUE_TO_APP } from '../../constants';
+
+const swe = new SwissEph();
+
+console.log('Refraction Table (Standard Atmosphere: 1013.25 mbar, 15 C)');
+console.log('==========================================================');
+console.log('True Alt (deg)   Refraction (arcmin)   Refraction (deg)');
+console.log('--------------   -------------------   ----------------');
+
+// Fine steps near the horizon, coarser steps higher up
+const altitudes = [
+  -1, -0.5, 0, 0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4, 5,
+  7, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90,
+];
+
+for (const alt of altitudes) {
+  const apparentAlt = swe.refraction(alt, 1013.25, 15, SE_TRUE_TO_APP);
+  const refraction = apparentAlt - alt;
+  console.log(
+    `${alt.toFixed(2).padStart(10)}` +
+    `${(refraction * 60).toFixed(2).padStart(18)}` +
+    `${refraction.toFixed(5).padStart(20)}`
+  );
+}
+
+swe.close();
+```
+
+---
+
+## Deep Explanation
+
+### How refraction works physically
+
+Earth's atmosphere is a gas whose density decreases with altitude -- dense and thick at sea level, thinning to essentially vacuum in space. When light passes from a less dense medium to a more dense medium (or through a medium with a continuous density gradient), it bends toward the denser region. This is the same principle as Snell's law of refraction, applied continuously rather than at a single surface.
+
+A ray of light from a celestial object enters the top of the atmosphere traveling in a straight line. As it descends into progressively denser air, it curves gently downward (toward the Earth's surface). By the time it reaches the observer's eye, it is arriving at a steeper angle than it originally entered the atmosphere. The observer, tracing the light ray backward in a straight line, perceives the object as being higher in the sky than it geometrically is.
+
+The atmosphere can be modeled as a stack of thin concentric shells, each with a slightly different refractive index. The total bending is the integral of all these small refractions. For objects high in the sky, the light passes through less atmosphere (shorter path) and at a steeper angle (less bending per layer), so refraction is small. Near the horizon, the light passes through a maximum amount of atmosphere and grazes the layers at a shallow angle, producing the largest bending.
+
+### Bennett's formula
+
+The Swiss Ephemeris uses a formula based on Bennett (1982) for computing refraction. For the true-to-apparent direction, the refraction R (in arcminutes) at true altitude h (in degrees) is approximately:
+
+```
+R = 1 / tan(h + 7.31 / (h + 4.4))
+```
+
+This gives the refraction in arcminutes for standard conditions (1013.25 mbar, 10 degrees C in Bennett's original; the Swiss Ephemeris adjusts to 15 degrees C). For non-standard pressure P (in mbar) and temperature T (in Celsius), the result is scaled:
+
+```
+R_actual = R * (P / 1010) * (283 / (273 + T))
+```
+
+The formula is an empirical fit, accurate to about 0.1 arcminute for altitudes above 1 degree. Below 1 degree (very near the horizon), refraction becomes increasingly unpredictable.
+
+### SE_TRUE_TO_APP vs SE_APP_TO_TRUE
+
+| Flag              | Value | Input              | Output                           |
+|-------------------|-------|--------------------|----------------------------------|
+| `SE_TRUE_TO_APP`  | 0     | True (geometric) altitude | Returns the apparent (refracted) altitude |
+| `SE_APP_TO_TRUE`  | 1     | Apparent (observed) altitude | Returns a negative correction to add to apparent altitude to get true altitude |
+
+Note the asymmetry: `SE_TRUE_TO_APP` returns the full apparent altitude directly, while `SE_APP_TO_TRUE` returns a negative correction that you add to the input:
+
+```typescript
+// True to apparent (direct result)
+const apparentAlt = swe.refraction(trueAlt, P, T, SE_TRUE_TO_APP);
+
+// Apparent to true (correction to add)
+const correction = swe.refraction(apparentAlt, P, T, SE_APP_TO_TRUE);
+const trueAlt = apparentAlt + correction; // correction is negative
+```
+
+### Why refraction is unreliable near the horizon
+
+Below about 1 degree altitude, the standard refraction formula becomes increasingly inaccurate because:
+
+1. **Temperature inversions**: Normally, air temperature decreases with altitude. But near the ground, temperature inversions (warm air above cool air) can occur, creating abnormal density profiles that bend light in unusual ways. This is the cause of **mirages** -- the shimmering "water" on hot roads, or the occasional inverted images of distant ships.
+
+2. **Turbulence**: Near the horizon, light passes through the maximum thickness of atmosphere and encounters more turbulent layers, causing the image to shimmer and distort unpredictably.
+
+3. **The green flash**: Under rare conditions, the differential refraction of different colors (atmospheric dispersion) produces a momentary green flash at the very top of the setting Sun. Red light is refracted less than green/blue light, so the last sliver of sunlight to disappear is skewed toward green.
+
+4. **Ducting**: In extreme inversions, light can be "ducted" along a layer, allowing you to see objects far beyond the normal geometric horizon. This can make refraction effectively infinite at the horizon.
+
+For these reasons, the standard refraction formula should be treated as an approximation below about 1 degree altitude, and as unreliable below about 0 degrees (below the geometric horizon). The actual refraction at any given moment depends on the specific atmospheric conditions, which vary from minute to minute.
+
+### Standard atmosphere values
+
+The standard values used as defaults are:
+
+| Parameter    | Standard Value | Unit  |
+|-------------|----------------|-------|
+| Pressure     | 1013.25        | mbar (= hPa) |
+| Temperature  | 15             | degrees C     |
+
+These represent average sea-level conditions (the ISA -- International Standard Atmosphere). If you set pressure to 0, the function returns 0 refraction (vacuum, no atmosphere).
+
+Approximate pressure at altitude (assuming standard lapse rate):
+
+| Elevation | Pressure | Refraction at horizon |
+|-----------|----------|----------------------|
+| Sea level | 1013 mbar | ~34 arcmin           |
+| 1000 m    | 899 mbar  | ~30 arcmin           |
+| 2000 m    | 795 mbar  | ~27 arcmin           |
+| 3000 m    | 701 mbar  | ~24 arcmin           |
+| 5000 m    | 540 mbar  | ~18 arcmin           |
+
+### Practical applications
+
+- **Rise and set times**: The standard definition of sunrise/sunset uses -50 arcminutes for the Sun's center (-34' refraction - 16' semi-diameter) and -34 arcminutes for stars and planets. The `rise()` and `set()` methods in SwissEph already account for refraction internally.
+
+- **Telescope pointing**: If your telescope's mount uses true (geometric) coordinates from an ephemeris, you need to add refraction to point accurately at low-altitude targets. Most modern Go-To mounts have built-in refraction correction.
+
+- **Satellite tracking**: For low-Earth orbit satellites near the horizon, refraction must be corrected to accurately predict their apparent positions.
+
+- **Surveying and navigation**: Celestial navigation (sextant observations) requires refraction corrections, especially for objects measured near the horizon. Traditional navigation tables include refraction corrections for this purpose.
+
+- **Atmospheric science**: The amount of refraction at a given altitude can be used to estimate atmospheric conditions (temperature profile, density). Monitoring refraction over time can reveal changes in atmospheric structure.
+
+### Relationship to azalt()
+
+The `azalt()` method in SwissEph already applies refraction automatically, returning both `trueAltitude` and `apparentAltitude`. You only need the standalone `refraction()` function when you want to apply refraction corrections independently, for example when working with altitude values from external sources, when building lookup tables, or when you need fine control over the atmospheric parameters.