ootk 4.0.9 → 5.1.0

package/dist/observation/RadecGeocentric.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @description Orbital Object ToolKit (ootk) is a collection of tools for working
+ * with satellites and other orbital objects.
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2025 Kruczek Labs LLC
+ *
+ * Many of the classes are based off of the work of @david-rc-dayton and his
+ * Pious Squid library (https://github.com/david-rc-dayton/pious_squid) which
+ * is licensed under the MIT license.
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+import { Degrees, DegreesPerSecond, Kilometers, KilometersPerSecond, Radians, RadiansPerSecond } from '../main.js';
+import { J2000 } from '../coordinate/J2000.js';
+import { AngularDistanceMethod } from '../enums/AngularDistanceMethod.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { EpochUTC } from '../time/EpochUTC.js';
+/**
+ * Represents a geocentric right ascension and declination observation.
+ *
+ * In geocentric coordinates, observations are considered from the Earth's center. This approach simplifies calculations
+ * for distant celestial objects, as it assumes a uniform observation point that ignores the observer's specific
+ * location on Earth.
+ */
+export declare class RadecGeocentric {
+    epoch: EpochUTC;
+    rightAscension: Radians;
+    declination: Radians;
+    range?: Kilometers | undefined;
+    rightAscensionRate?: (RadiansPerSecond | null) | undefined;
+    declinationRate?: (RadiansPerSecond | null) | undefined;
+    rangeRate?: (KilometersPerSecond | null) | undefined;
+    constructor(epoch: EpochUTC, rightAscension: Radians, declination: Radians, range?: Kilometers | undefined, rightAscensionRate?: (RadiansPerSecond | null) | undefined, declinationRate?: (RadiansPerSecond | null) | undefined, rangeRate?: (KilometersPerSecond | null) | undefined);
+    /**
+     * Creates a RadecGeocentric object from the given parameters in degrees.
+     * @param epoch - The epoch in UTC.
+     * @param rightAscensionDegrees - The right ascension in degrees.
+     * @param declinationDegrees - The declination in degrees.
+     * @param range - The range in kilometers (optional).
+     * @param rightAscensionRateDegrees - The right ascension rate in degrees per second (optional).
+     * @param declinationRateDegrees - The declination rate in degrees per second (optional).
+     * @param rangeRate - The range rate in kilometers per second (optional).
+     * @returns A new RadecGeocentric object.
+     */
+    static fromDegrees(epoch: EpochUTC, rightAscensionDegrees: Degrees, declinationDegrees: Degrees, range?: Kilometers, rightAscensionRateDegrees?: Degrees, declinationRateDegrees?: Degrees, rangeRate?: KilometersPerSecond): RadecGeocentric;
+    /**
+     * Creates a RadecGeocentric object from a state vector in J2000 coordinates.
+     * @param state - The J2000 state vector.
+     * @returns A new RadecGeocentric object.
+     */
+    static fromStateVector(state: J2000): RadecGeocentric;
+    /**
+     * Gets the right ascension in degrees.
+     * @returns The right ascension in degrees.
+     */
+    get rightAscensionDegrees(): Degrees;
+    /**
+     * Gets the declination in degrees.
+     * @returns The declination in degrees.
+     */
+    get declinationDegrees(): Degrees;
+    /**
+     * Gets the right ascension rate in degrees per second.
+     * @returns The right ascension rate in degrees per second, or null if it is not available.
+     */
+    get rightAscensionRateDegrees(): DegreesPerSecond | null;
+    /**
+     * Gets the rate of change of declination in degrees per second.
+     * @returns The rate of change of declination in degrees per second, or null if not available.
+     */
+    get declinationRateDegrees(): DegreesPerSecond | null;
+    /**
+     * Calculates the position vector in geocentric coordinates.
+     * @param range - The range in kilometers (optional). If not provided, it uses the default range or 1.0 kilometer.
+     * @returns The position vector in geocentric coordinates.
+     */
+    position(range?: Kilometers): Vector3D<Kilometers>;
+    /**
+     * Calculates the velocity vector of the celestial object.
+     * @param range - The range of the celestial object in kilometers. If not provided, it uses the stored range value.
+     * @param rangeRate - The range rate of the celestial object in kilometers per second.
+     * If not provided, it uses the stored range rate value.
+     * @returns The velocity vector of the celestial object in kilometers per second.
+     * @throws Error if the right ascension rate or declination rate is missing.
+     */
+    velocity(range?: Kilometers, rangeRate?: KilometersPerSecond): Vector3D<KilometersPerSecond>;
+    /**
+     * Calculates the angular distance between two celestial coordinates (RA and Dec).
+     * @param radec - The celestial coordinates to compare with.
+     * @param method - The method to use for calculating the angular distance. Default is `AngularDistanceMethod.Cosine`.
+     * @returns The angular distance between the two celestial coordinates in radians.
+     */
+    angle(radec: RadecGeocentric, method?: AngularDistanceMethod): Radians;
+    /**
+     * Calculates the angle in degrees between two RadecGeocentric objects.
+     * @param radec - The RadecGeocentric object to calculate the angle with.
+     * @param method - The method to use for calculating the angular distance. Default is AngularDistanceMethod.Cosine.
+     * @returns The angle in degrees.
+     */
+    angleDegrees(radec: RadecGeocentric, method?: AngularDistanceMethod): Degrees;
+}

package/dist/observation/RadecGeocentric.js

@@ -0,0 +1,169 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @description Orbital Object ToolKit (ootk) is a collection of tools for working
+ * with satellites and other orbital objects.
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2025 Kruczek Labs LLC
+ *
+ * Many of the classes are based off of the work of @david-rc-dayton and his
+ * Pious Squid library (https://github.com/david-rc-dayton/pious_squid) which
+ * is licensed under the MIT license.
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+import { AngularDistanceMethod } from '../enums/AngularDistanceMethod.js';
+import { DEG2RAD, RAD2DEG, TAU } from '../utils/constants.js';
+import { angularDistance } from '../utils/functions.js';
+import { radecToPosition, radecToVelocity } from './ObservationUtils.js';
+/**
+ * Represents a geocentric right ascension and declination observation.
+ *
+ * In geocentric coordinates, observations are considered from the Earth's center. This approach simplifies calculations
+ * for distant celestial objects, as it assumes a uniform observation point that ignores the observer's specific
+ * location on Earth.
+ */
+export class RadecGeocentric {
+    epoch;
+    rightAscension;
+    declination;
+    range;
+    rightAscensionRate;
+    declinationRate;
+    rangeRate;
+    constructor(epoch, rightAscension, declination, range, rightAscensionRate, declinationRate, rangeRate) {
+        this.epoch = epoch;
+        this.rightAscension = rightAscension;
+        this.declination = declination;
+        this.range = range;
+        this.rightAscensionRate = rightAscensionRate;
+        this.declinationRate = declinationRate;
+        this.rangeRate = rangeRate;
+        // Nothing to do here.
+    }
+    /**
+     * Creates a RadecGeocentric object from the given parameters in degrees.
+     * @param epoch - The epoch in UTC.
+     * @param rightAscensionDegrees - The right ascension in degrees.
+     * @param declinationDegrees - The declination in degrees.
+     * @param range - The range in kilometers (optional).
+     * @param rightAscensionRateDegrees - The right ascension rate in degrees per second (optional).
+     * @param declinationRateDegrees - The declination rate in degrees per second (optional).
+     * @param rangeRate - The range rate in kilometers per second (optional).
+     * @returns A new RadecGeocentric object.
+     */
+    static fromDegrees(epoch, rightAscensionDegrees, declinationDegrees, range, rightAscensionRateDegrees, declinationRateDegrees, rangeRate) {
+        const rightAscensionRate = rightAscensionRateDegrees
+            ? rightAscensionRateDegrees * DEG2RAD
+            : null;
+        const declinationRate = declinationRateDegrees ? declinationRateDegrees * DEG2RAD : null;
+        return new RadecGeocentric(epoch, rightAscensionDegrees * DEG2RAD, declinationDegrees * DEG2RAD, range, rightAscensionRate, declinationRate, rangeRate);
+    }
+    /**
+     * Creates a RadecGeocentric object from a state vector in J2000 coordinates.
+     * @param state - The J2000 state vector.
+     * @returns A new RadecGeocentric object.
+     */
+    static fromStateVector(state) {
+        const rI = state.position.x;
+        const rJ = state.position.y;
+        const rK = state.position.z;
+        const vI = state.velocity.x;
+        const vJ = state.velocity.y;
+        const vK = state.velocity.z;
+        const rMag = state.position.magnitude();
+        const declination = Math.asin(rK / rMag);
+        const rIJMag = Math.sqrt(rI * rI + rJ * rJ);
+        let rightAscension;
+        if (rIJMag !== 0) {
+            rightAscension = Math.atan2(rJ, rI);
+        }
+        else {
+            rightAscension = Math.atan2(vJ, vI);
+        }
+        const rangeRate = state.position.dot(state.velocity) / rMag;
+        const rightAscensionRate = (vI * rJ - vJ * rI) / (-(rJ * rJ) - rI * rI);
+        const declinationRate = (vK - rangeRate * (rK / rMag)) / rIJMag;
+        return new RadecGeocentric(state.epoch, rightAscension % TAU, declination, rMag, rightAscensionRate, declinationRate, rangeRate);
+    }
+    /**
+     * Gets the right ascension in degrees.
+     * @returns The right ascension in degrees.
+     */
+    get rightAscensionDegrees() {
+        return this.rightAscension * RAD2DEG;
+    }
+    /**
+     * Gets the declination in degrees.
+     * @returns The declination in degrees.
+     */
+    get declinationDegrees() {
+        return this.declination * RAD2DEG;
+    }
+    /**
+     * Gets the right ascension rate in degrees per second.
+     * @returns The right ascension rate in degrees per second, or null if it is not available.
+     */
+    get rightAscensionRateDegrees() {
+        return this.rightAscensionRate ? this.rightAscensionRate * RAD2DEG : null;
+    }
+    /**
+     * Gets the rate of change of declination in degrees per second.
+     * @returns The rate of change of declination in degrees per second, or null if not available.
+     */
+    get declinationRateDegrees() {
+        return this.declinationRate ? this.declinationRate * RAD2DEG : null;
+    }
+    /**
+     * Calculates the position vector in geocentric coordinates.
+     * @param range - The range in kilometers (optional). If not provided, it uses the default range or 1.0 kilometer.
+     * @returns The position vector in geocentric coordinates.
+     */
+    position(range) {
+        const r = range ?? this.range ?? 1.0;
+        return radecToPosition(this.rightAscension, this.declination, r);
+    }
+    /**
+     * Calculates the velocity vector of the celestial object.
+     * @param range - The range of the celestial object in kilometers. If not provided, it uses the stored range value.
+     * @param rangeRate - The range rate of the celestial object in kilometers per second.
+     * If not provided, it uses the stored range rate value.
+     * @returns The velocity vector of the celestial object in kilometers per second.
+     * @throws Error if the right ascension rate or declination rate is missing.
+     */
+    velocity(range, rangeRate) {
+        if (!this.rightAscensionRate || !this.declinationRate) {
+            throw new Error('Velocity unsolvable, missing ra/dec rates.');
+        }
+        const r = range ?? this.range ?? 1.0;
+        const rd = rangeRate ?? this.rangeRate ?? 0.0;
+        return radecToVelocity(this.rightAscension, this.declination, r, this.rightAscensionRate, this.declinationRate, rd);
+    }
+    /**
+     * Calculates the angular distance between two celestial coordinates (RA and Dec).
+     * @param radec - The celestial coordinates to compare with.
+     * @param method - The method to use for calculating the angular distance. Default is `AngularDistanceMethod.Cosine`.
+     * @returns The angular distance between the two celestial coordinates in radians.
+     */
+    angle(radec, method = AngularDistanceMethod.Cosine) {
+        return angularDistance(this.rightAscension, this.declination, radec.rightAscension, radec.declination, method);
+    }
+    /**
+     * Calculates the angle in degrees between two RadecGeocentric objects.
+     * @param radec - The RadecGeocentric object to calculate the angle with.
+     * @param method - The method to use for calculating the angular distance. Default is AngularDistanceMethod.Cosine.
+     * @returns The angle in degrees.
+     */
+    angleDegrees(radec, method = AngularDistanceMethod.Cosine) {
+        return this.angle(radec, method) * RAD2DEG;
+    }
+}
+//# sourceMappingURL=RadecGeocentric.js.map

package/dist/observation/RadecGeocentric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RadecGeocentric.js","sourceRoot":"","sources":["../../src/observation/RadecGeocentric.ts"],"names":[],"mappings":"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"}

package/dist/observation/RadecTopocentric.d.ts

@@ -0,0 +1,123 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @description Orbital Object ToolKit (ootk) is a collection of tools for working
+ * with satellites and other orbital objects.
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2025 Kruczek Labs LLC
+ *
+ * Many of the classes are based off of the work of @david-rc-dayton and his
+ * Pious Squid library (https://github.com/david-rc-dayton/pious_squid) which
+ * is licensed under the MIT license.
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+import { Degrees, DegreesPerSecond, Kilometers, KilometersPerSecond, Radians, RadiansPerSecond } from '../main.js';
+import { J2000 } from '../coordinate/J2000.js';
+import { AngularDistanceMethod } from '../enums/AngularDistanceMethod.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { EpochUTC } from '../time/EpochUTC.js';
+/**
+ * Represents a topocentric right ascension and declination observation.
+ *
+ * Topocentric coordinates take into account the observer's exact location on the Earth's surface. This model is crucial
+ * for precise measurements of local astronomical events and nearby celestial objects, where the observer's latitude,
+ * longitude, and altitude can significantly affect the observed position due to parallax. Topocentric coordinates are
+ * particularly important for observations of the Moon, planets, and artificial satellites.
+ */
+export declare class RadecTopocentric {
+    epoch: EpochUTC;
+    rightAscension: Radians;
+    declination: Radians;
+    range?: Kilometers | undefined;
+    rightAscensionRate?: (RadiansPerSecond | null) | undefined;
+    declinationRate?: (RadiansPerSecond | null) | undefined;
+    rangeRate?: (KilometersPerSecond | null) | undefined;
+    constructor(epoch: EpochUTC, rightAscension: Radians, declination: Radians, range?: Kilometers | undefined, rightAscensionRate?: (RadiansPerSecond | null) | undefined, declinationRate?: (RadiansPerSecond | null) | undefined, rangeRate?: (KilometersPerSecond | null) | undefined);
+    /**
+     * Create a new RadecTopocentric object, using degrees for the angular values.
+     * @param epoch UTC epoch.
+     * @param rightAscensionDegrees Right-ascension in degrees.
+     * @param declinationDegrees Declination in degrees.
+     * @param range Range in km.
+     * @param rightAscensionRateDegrees Right-ascension rate in degrees per second.
+     * @param declinationRateDegrees Declination rate in degrees per second.
+     * @param rangeRate Range rate in km/s.
+     * @returns A new RadecTopocentric object.
+     */
+    static fromDegrees(epoch: EpochUTC, rightAscensionDegrees: Degrees, declinationDegrees: Degrees, range?: Kilometers, rightAscensionRateDegrees?: DegreesPerSecond, declinationRateDegrees?: DegreesPerSecond, rangeRate?: KilometersPerSecond): RadecTopocentric;
+    /**
+     * Create a new RadecTopocentric object from a J2000 state vector.
+     * @param state Inertial state vector.
+     * @param site Site vector.
+     * @returns A new RadecTopocentric object.
+     */
+    static fromStateVector(state: J2000, site: J2000): RadecTopocentric;
+    /**
+     * Gets the right ascension in degrees.
+     * @returns The right ascension in degrees.
+     */
+    get rightAscensionDegrees(): Degrees;
+    /**
+     * Gets the declination in degrees.
+     * @returns The declination in degrees.
+     */
+    get declinationDegrees(): Degrees;
+    /**
+     * Gets the right ascension rate in degrees per second.
+     * @returns The right ascension rate in degrees per second, or null if it is not available.
+     */
+    get rightAscensionRateDegrees(): DegreesPerSecond | null;
+    /**
+     * Gets the rate of change of declination in degrees per second.
+     * @returns The rate of change of declination in degrees per second, or null if the declination rate is not defined.
+     */
+    get declinationRateDegrees(): DegreesPerSecond | null;
+    /**
+     * Return the position relative to the observer site.
+     *
+     * An optional range value can be passed to override the value contained in this observation.
+     * @param site Observer site.
+     * @param range Range in km.
+     * @returns A Vector3D object.
+     */
+    position(site: J2000, range?: Kilometers): Vector3D<Kilometers>;
+    /**
+     * Return the velocity relative to the observer site.
+     *
+     * An optional range and rangeRate value can be passed to override the values contained in this observation.
+     * @param site Observer site.
+     * @param range Range in km.
+     * @param rangeRate Range rate in km/s.
+     * @returns A Vector3D object.
+     */
+    velocity(site: J2000, range?: Kilometers, rangeRate?: KilometersPerSecond): Vector3D<KilometersPerSecond>;
+    /**
+     * Calculates the line of sight vector in the topocentric coordinate system.
+     * The line of sight vector points from the observer's location towards the celestial object.
+     * @returns The line of sight vector as a Vector3D object.
+     */
+    lineOfSight(): Vector3D;
+    /**
+     * Calculate the angular distance between this and another RadecTopocentric object.
+     * @param radec - The other RadecTopocentric object.
+     * @param method - The angular distance method to use.
+     * @returns The angular distance.
+     */
+    angle(radec: RadecTopocentric, method?: AngularDistanceMethod): Radians;
+    /**
+     * Calculate the angular distance between this and another RadecTopocentric object.
+     * @param radec - The other RadecTopocentric object.
+     * @param method - The angular distance method to use.
+     * @returns The angular distance
+     */
+    angleDegrees(radec: RadecTopocentric, method?: AngularDistanceMethod): Degrees;
+}

package/dist/observation/RadecTopocentric.js

@@ -0,0 +1,196 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @description Orbital Object ToolKit (ootk) is a collection of tools for working
+ * with satellites and other orbital objects.
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2025 Kruczek Labs LLC
+ *
+ * Many of the classes are based off of the work of @david-rc-dayton and his
+ * Pious Squid library (https://github.com/david-rc-dayton/pious_squid) which
+ * is licensed under the MIT license.
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+import { AngularDistanceMethod } from '../enums/AngularDistanceMethod.js';
+import { Vector3D } from '../operations/Vector3D.js';
+import { DEG2RAD, RAD2DEG, TAU } from '../utils/constants.js';
+import { angularDistance } from '../utils/functions.js';
+import { radecToPosition, radecToVelocity } from './ObservationUtils.js';
+/**
+ * Represents a topocentric right ascension and declination observation.
+ *
+ * Topocentric coordinates take into account the observer's exact location on the Earth's surface. This model is crucial
+ * for precise measurements of local astronomical events and nearby celestial objects, where the observer's latitude,
+ * longitude, and altitude can significantly affect the observed position due to parallax. Topocentric coordinates are
+ * particularly important for observations of the Moon, planets, and artificial satellites.
+ */
+export class RadecTopocentric {
+    epoch;
+    rightAscension;
+    declination;
+    range;
+    rightAscensionRate;
+    declinationRate;
+    rangeRate;
+    constructor(epoch, rightAscension, declination, range, rightAscensionRate, declinationRate, rangeRate) {
+        this.epoch = epoch;
+        this.rightAscension = rightAscension;
+        this.declination = declination;
+        this.range = range;
+        this.rightAscensionRate = rightAscensionRate;
+        this.declinationRate = declinationRate;
+        this.rangeRate = rangeRate;
+        // Nothing to do here.
+    }
+    /**
+     * Create a new RadecTopocentric object, using degrees for the angular values.
+     * @param epoch UTC epoch.
+     * @param rightAscensionDegrees Right-ascension in degrees.
+     * @param declinationDegrees Declination in degrees.
+     * @param range Range in km.
+     * @param rightAscensionRateDegrees Right-ascension rate in degrees per second.
+     * @param declinationRateDegrees Declination rate in degrees per second.
+     * @param rangeRate Range rate in km/s.
+     * @returns A new RadecTopocentric object.
+     */
+    static fromDegrees(epoch, rightAscensionDegrees, declinationDegrees, range, rightAscensionRateDegrees, declinationRateDegrees, rangeRate) {
+        const rightAscensionRate = rightAscensionRateDegrees
+            ? rightAscensionRateDegrees * DEG2RAD
+            : null;
+        const declinationRate = declinationRateDegrees
+            ? declinationRateDegrees * DEG2RAD
+            : null;
+        return new RadecTopocentric(epoch, rightAscensionDegrees * DEG2RAD, declinationDegrees * DEG2RAD, range, rightAscensionRate, declinationRate, rangeRate);
+    }
+    /**
+     * Create a new RadecTopocentric object from a J2000 state vector.
+     * @param state Inertial state vector.
+     * @param site Site vector.
+     * @returns A new RadecTopocentric object.
+     */
+    static fromStateVector(state, site) {
+        const p = state.position.subtract(site.position);
+        const pI = p.x;
+        const pJ = p.y;
+        const pK = p.z;
+        const pMag = p.magnitude();
+        const declination = Math.asin(pK / pMag);
+        const pDot = state.velocity.subtract(site.velocity);
+        const pIDot = pDot.x;
+        const pJDot = pDot.y;
+        const pKDot = pDot.z;
+        const pIJMag = Math.sqrt(pI * pI + pJ * pJ);
+        let rightAscension;
+        if (pIJMag !== 0) {
+            rightAscension = Math.atan2(pJ, pI);
+        }
+        else {
+            rightAscension = Math.atan2(pJDot, pIDot);
+        }
+        const rangeRate = p.dot(pDot) / pMag;
+        const rightAscensionRate = (pIDot * pJ - pJDot * pI) / (-(pJ * pJ) - pI * pI);
+        const declinationRate = (pKDot - rangeRate * Math.sin(declination)) / pIJMag;
+        return new RadecTopocentric(state.epoch, rightAscension % TAU, declination, pMag, rightAscensionRate, declinationRate, rangeRate);
+    }
+    /**
+     * Gets the right ascension in degrees.
+     * @returns The right ascension in degrees.
+     */
+    get rightAscensionDegrees() {
+        return this.rightAscension * RAD2DEG;
+    }
+    /**
+     * Gets the declination in degrees.
+     * @returns The declination in degrees.
+     */
+    get declinationDegrees() {
+        return this.declination * RAD2DEG;
+    }
+    /**
+     * Gets the right ascension rate in degrees per second.
+     * @returns The right ascension rate in degrees per second, or null if it is not available.
+     */
+    get rightAscensionRateDegrees() {
+        return this.rightAscensionRate
+            ? this.rightAscensionRate * RAD2DEG
+            : null;
+    }
+    /**
+     * Gets the rate of change of declination in degrees per second.
+     * @returns The rate of change of declination in degrees per second, or null if the declination rate is not defined.
+     */
+    get declinationRateDegrees() {
+        return this.declinationRate
+            ? this.declinationRate * RAD2DEG
+            : null;
+    }
+    /**
+     * Return the position relative to the observer site.
+     *
+     * An optional range value can be passed to override the value contained in this observation.
+     * @param site Observer site.
+     * @param range Range in km.
+     * @returns A Vector3D object.
+     */
+    position(site, range) {
+        const r = range ?? this.range ?? 1.0;
+        return radecToPosition(this.rightAscension, this.declination, r).add(site.position);
+    }
+    /**
+     * Return the velocity relative to the observer site.
+     *
+     * An optional range and rangeRate value can be passed to override the values contained in this observation.
+     * @param site Observer site.
+     * @param range Range in km.
+     * @param rangeRate Range rate in km/s.
+     * @returns A Vector3D object.
+     */
+    velocity(site, range, rangeRate) {
+        if (!this.rightAscensionRate || !this.declinationRate) {
+            throw new Error('Velocity unsolvable, missing ra/dec rates.');
+        }
+        const r = range ?? this.range ?? 1.0;
+        const rd = rangeRate ?? this.rangeRate ?? 0.0;
+        return radecToVelocity(this.rightAscension, this.declination, r, this.rightAscensionRate, this.declinationRate, rd).add(site.velocity);
+    }
+    /**
+     * Calculates the line of sight vector in the topocentric coordinate system.
+     * The line of sight vector points from the observer's location towards the celestial object.
+     * @returns The line of sight vector as a Vector3D object.
+     */
+    lineOfSight() {
+        const ca = Math.cos(this.rightAscension);
+        const cd = Math.cos(this.declination);
+        const sa = Math.sin(this.rightAscension);
+        const sd = Math.sin(this.declination);
+        return new Vector3D(cd * ca, cd * sa, sd);
+    }
+    /**
+     * Calculate the angular distance between this and another RadecTopocentric object.
+     * @param radec - The other RadecTopocentric object.
+     * @param method - The angular distance method to use.
+     * @returns The angular distance.
+     */
+    angle(radec, method = AngularDistanceMethod.Cosine) {
+        return angularDistance(this.rightAscension, this.declination, radec.rightAscension, radec.declination, method);
+    }
+    /**
+     * Calculate the angular distance between this and another RadecTopocentric object.
+     * @param radec - The other RadecTopocentric object.
+     * @param method - The angular distance method to use.
+     * @returns The angular distance
+     */
+    angleDegrees(radec, method = AngularDistanceMethod.Cosine) {
+        return this.angle(radec, method) * RAD2DEG;
+    }
+}
+//# sourceMappingURL=RadecTopocentric.js.map

package/dist/observation/RadecTopocentric.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RadecTopocentric.js","sourceRoot":"","sources":["../../src/observation/RadecTopocentric.ts"],"names":[],"mappings":"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"}

package/dist/observation/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @author @thkruz Theodore Kruczek
+ * @description Orbital Object ToolKit (ootk) is a collection of tools for working
+ * with satellites and other orbital objects.
+ * @license AGPL-3.0-or-later
+ * @copyright (c) 2025 Kruczek Labs LLC
+ *
+ * Many of the classes are based off of the work of @david-rc-dayton and his
+ * Pious Squid library (https://github.com/david-rc-dayton/pious_squid) which
+ * is licensed under the MIT license.
+ *
+ * Orbital Object ToolKit is free software: you can redistribute it and/or modify it under the
+ * terms of the GNU Affero General Public License as published by the Free Software
+ * Foundation, either version 3 of the License, or (at your option) any later version.
+ *
+ * Orbital Object ToolKit is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+ * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ * See the GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License along with
+ * Orbital Object ToolKit. If not, see <http://www.gnu.org/licenses/>.
+ */
+export * from './ObservationUtils.js';
+export { RadecGeocentric } from './RadecGeocentric.js';
+export { RadecTopocentric } from './RadecTopocentric.js';
+export { RAE } from './RAE.js';