ootk 5.0.0 → 5.1.1

package/src/time/TimeStamped.ts

@@ -1,32 +1,28 @@
 /**
- * @author Theodore Kruczek.
- * @license MIT
- * @copyright (c) 2022-2025 Theodore Kruczek Permission is
- * hereby granted, free of charge, to any person obtaining a copy of this
- * software and associated documentation files (the "Software"), to deal in the
- * Software without restriction, including without limitation the rights to use,
- * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
- * the Software, and to permit persons to whom the Software is furnished to do
- * so, subject to the following conditions:
+ * @author 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
  *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
+ * 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.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
+ * 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 type { EpochUTC } from './EpochUTC.js';
 
-/**
- * Time stamped value container.
- * TODO: #10 Is TimeStamped class needed?
- */
 export class TimeStamped<T> {
   /**
    * Create a new time stamped value container at the provided epoch.

package/src/time/index.ts

@@ -1,26 +1,3 @@
-/**
- * @author Theodore Kruczek.
- * @license MIT
- * @copyright (c) 2022-2025 Theodore Kruczek Permission is
- * hereby granted, free of charge, to any person obtaining a copy of this
- * software and associated documentation files (the "Software"), to deal in the
- * Software without restriction, including without limitation the rights to use,
- * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
- * the Software, and to permit persons to whom the Software is furnished to do
- * so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-
 export { Epoch } from './Epoch.js';
 export { EpochGPS } from './EpochGPS.js';
 export { EpochTAI } from './EpochTAI.js';

package/src/transforms/TransformCache.ts

@@ -1,24 +1,24 @@
 /**
- * @author Theodore Kruczek.
- * @license MIT
- * @copyright (c) 2022-2025 Theodore Kruczek Permission is
- * hereby granted, free of charge, to any person obtaining a copy of this
- * software and associated documentation files (the "Software"), to deal in the
- * Software without restriction, including without limitation the rights to use,
- * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
- * the Software, and to permit persons to whom the Software is furnished to do
- * so, subject to the following conditions:
+ * @author 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
  *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
+ * 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.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
+ * 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 class TransformCache {

package/src/transforms/conversions.ts

@@ -1,24 +1,24 @@
 /**
- * @author Theodore Kruczek.
- * @license MIT
- * @copyright (c) 2022-2025 Theodore Kruczek Permission is
- * hereby granted, free of charge, to any person obtaining a copy of this
- * software and associated documentation files (the "Software"), to deal in the
- * Software without restriction, including without limitation the rights to use,
- * copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
- * the Software, and to permit persons to whom the Software is furnished to do
- * so, subject to the following conditions:
+ * @author 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
  *
- * The above copyright notice and this permission notice shall be included in
- * all copies or substantial portions of the Software.
+ * 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.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
+ * 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 { DEG2RAD, Degrees, PI, RAD2DEG, Radians } from '../main.js';

package/src/types/types.ts

@@ -1,7 +1,7 @@
 /**
  * @author @thkruz Theodore Kruczek
  * @license AGPL-3.0-or-later
- * @copyright (c) 2020-2024 Theodore Kruczek
+ * @copyright (c) 2025 Kruczek Labs LLC
  *
  * 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
@@ -712,7 +712,7 @@ export type StringifiedNumber = `${number}.${number}`;
 /**
  * Represents a set of data containing both Line 1 and Line 2 TLE information.
  *
- * TODO: #22 TleParams types should be more consistent.
+ * TODO: TleParams types should be more consistent.
  */
 export type TleParams = {
   sat?: Satellite;

package/src/utils/create-covariance-from-tle.ts

@@ -0,0 +1,75 @@
+import { Tle, CovarianceSample, CovarianceFrame, StateCovariance } from '../main.js';
+
+/**
+ * Creates a 6x6 state covariance matrix from a TLE
+ * @param tleLine1 The first line of the TLE
+ * @param tleLine2 The second line of the TLE
+ * @param frame The covariance frame (CovarianceFrame.ECI or CovarianceFrame.RIC)
+ * @param sigmaScale Scaling factor for the sigmas (default: 1.0)
+ * @returns A StateCovariance object containing the 6x6 covariance matrix
+ */
+export function createCovarianceFromTle(
+  tleLine1: string,
+  tleLine2: string,
+  frame: CovarianceFrame = CovarianceFrame.RIC,
+  sigmaScale: number = 1.0,
+): StateCovariance {
+  // Parse the TLE and get the state vector
+  const tle = new Tle(tleLine1, tleLine2);
+  const temeState = tle.state;
+  const j2000State = temeState.toJ2000();
+
+  // eslint-disable-next-line no-console
+  console.log('J2000 State:', j2000State);
+
+  /*
+   * Determine appropriate sigma values based on TLE
+   * These are rough estimates and can be adjusted based on your needs
+   */
+  const positionSigma = 1.0 * sigmaScale; // km
+  const velocitySigma = 0.001 * sigmaScale; // km/s
+
+  // Create a diagonal covariance matrix with sigma values
+  const sigmas = [
+    positionSigma, positionSigma, positionSigma,
+    velocitySigma, velocitySigma, velocitySigma,
+  ];
+
+  // Generate the covariance matrix in the desired frame
+  return StateCovariance.fromSigmas(sigmas, frame);
+}
+
+/**
+ * Creates a sample-based covariance from a TLE with more realistic uncertainties
+ * @param tleLine1 The first line of the TLE
+ * @param tleLine2 The second line of the TLE
+ * @param frame The covariance frame (CovarianceFrame.ECI or CovarianceFrame.RIC)
+ * @returns A StateCovariance object
+ */
+export function createSampleCovarianceFromTle(
+  tleLine1: string,
+  tleLine2: string,
+  frame: CovarianceFrame = CovarianceFrame.RIC,
+): StateCovariance {
+  // Parse the TLE and get the state vector
+  const tle = new Tle(tleLine1, tleLine2);
+  const temeState = tle.state;
+  const j2000State = temeState.toJ2000();
+
+  /*
+   * Create initial covariance with basic sigma values
+   * Position uncertainties are higher in-track than radial/cross-track
+   * for most space catalog objects
+   */
+  const sigmas = frame === CovarianceFrame.RIC
+    ? [0.12, 1.0, 0.1, 0.00012, 0.001, 0.0001] // RIC frame: [R,I,C,Rdot,Idot,Cdot]
+    : [0.6, 0.6, 0.6, 0.0006, 0.0006, 0.0006]; // ECI frame: [x,y,z,vx,vy,vz]
+
+  const covariance = StateCovariance.fromSigmas(sigmas, frame);
+
+  // Create a covariance sample that will be used to generate a more realistic covariance
+  const sample = new CovarianceSample(j2000State, covariance, tle);
+
+  // Return the desample in the appropriate frame
+  return frame === CovarianceFrame.RIC ? sample.desampleRIC() : sample.desampleJ2000();
+}

package/src/utils/functions.ts

@@ -92,10 +92,10 @@ export function copySign(mag: number, sgn: number): number {
  * @returns The result of evaluating the polynomial at the given value.
  */
 export function evalPoly(x: number, coeffs: Float64Array): number {
-  let result: number = coeffs[0] as number;
+  let result: number = coeffs[0];
 
   for (let i = 1; i < coeffs.length; i++) {
-    result = result * x + coeffs[i]!;
+    result = result * x + coeffs[i];
   }
 
   return result;
@@ -293,7 +293,7 @@ export function covariance(a: number[], b: number[], isSample = false): number {
   let result = 0.0;
 
   for (let i = 0; i < n; i++) {
-    result += (a[i]! - am) * (b[i]! - bm);
+    result += (a[i] - am) * (b[i] - bm);
   }
   const m = isSample ? 1 : 0;
 

package/src/utils/index.ts

@@ -2,3 +2,4 @@ export * from './functions.js';
 export * from './constants.js';
 export * from './linearDistance.js';
 export * from './jacobian.js';
+export * from './create-covariance-from-tle.js';

package/src/utils/jacobian.ts

@@ -1,10 +1,14 @@
 import { array2d, Matrix, Vector } from '../main.js';
 import { JacobianFunction } from '../types/types.js';
 
-// TODO: #11 Expand documentation of Jacobian function.
-
 /**
  * Calculates the Jacobian matrix of a given Jacobian function.
+ *
+ * The function calculates how small perturbations in each input variable affect all output variables,
+ * using a second-order accurate central difference approximation.
+ *
+ * In orbital mechanics applications, this matrix is essential for solving complex problems like
+ * orbit transfers, trajectory optimization, and precise orbital determination.
  * @param f The Jacobian function.
  * @param m The number of rows in the Jacobian matrix.
  * @param x0 The initial values of the variables.