🛰️ Satellite TLE tools in #"/davidcalhoun/tle.js/blob/main/LICENSE" data-analytics-event="{"category":"Repository Overview","action":"click","label":"location:sidebar;file:license"}" > MIT license
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Satellite TLE tools in JavaScript
npm add tle.js oryarn add tle.js
tle.js is designed to simplify satellite TLEs and SGP4 with a friendly interface, withsatellite.js doing the heavy lifting behind the scenes.
The origin of TLEs goes back to the punchcard days! ATLE, or two-line element set, is used bySGP4 propagatorsto determine spacecraft positioning information, taking into account gravity perturbations (themoon, etc).
Most users will probably want to simply get the latitude/longitude of a satellite (seegetLatLngObj) or get the look angles from a ground position, which can be used to trackwhere in the sky a satellite is visible (seegetSatelliteInfo). Users mayalso want to plot orbit lines (seegetGroundTracks).
Users may also be interested in grabbing specific values from a TLE. In this case, youcan use one of theTLE getters, for instancegetCOSPAR.
Note that TLEs should be updated at least daily to avoid drift in calculations. You can get them online atCelestrak, where they are updated every few hours.
More info on TLEs:
If you are using an older version of Node or a package that doesn't yet have ES Module support (and are getting the errorERR_REQUIRE_ESM), you will need to point to the special CommonJS build target. Simply change theimport format in the following examples to thisrequire format:
-import { getLatLngObj } from "tle.js";+const { getLatLngObj } = require("tle.js/dist/tlejs.cjs");
Please installtle.js version '3.x.x':
npm i tle.js@3
Let's start out with some code to define some variables which we'll use in many examples below.
// Satellite TLE; should be updated at least once a day for best results.// TLE source: http://celestrak.com/NORAD/elements/consttle=`ISS (ZARYA)1 25544U 98067A 17206.18396726 .00001961 00000-0 36771-4 0 99932 25544 51.6400 208.9163 0006317 69.9862 25.2906 15.54225995 67660`;
Two-line variants and an array of strings are also accepted.
Computes the latitude/longitude of a spacecraft. Defaults to the current local time ifoptionalTimestampMS is not passed in.
Note: the greater the difference between this timestamp and the TLE epoch (when the TLE was generated) will result in inaccuracies or even errors.
import{getLatLngObj}from"tle.js";constoptionalTimestampMS=1502342329860;constlatLonObj=getLatLngObj(tle,optionalTimestampMS);->{lat:-47.64247588153391,lng:-29.992233800623634}
Async function that returns a Promise that resolves with an array of longitude, latitude pairs for drawing the ground track (satellite path) for three orbits: one past orbit, one current orbit, and one future orbit.
Orbits start and stop at the international date line (antemeridian) because values passing overthat line is commonly problematic in mapping.
Note: the synchronous version of this function,getGroundTracksSync, has the same function signature (it accepts the same inputs).
import{getGroundTracks}from'tle.js';constthreeOrbitsArr=awaitgetGroundTracks({tle:tleStr,// Relative time to draw orbits from. This will be used as the "middle"/current orbit.startTimeMS:1502342329860,// Resolution of plotted points. Defaults to 1000 (plotting a point once for every second).stepMS:1000,// Returns points in [lng, lat] order when true, and [lat, lng] order when false.isLngLatFormat:true,});// Alternatively, if your setup doesn't support async/await:getGroundTracks({tle:tleStr,startTimeMS:1502342329860,stepMS:1000,isLngLatFormat:true,}).then(function(threeOrbitsArr){// Do stuff with three orbits array here.});// threeOrbitsArr contents[// previous orbit[[-179.93297540317567,45.85524291891481],// etc...],// current orbit[[-179.9398612198045,51.26165992503701],// etc...],// next orbit[[-179.9190165549038,51.0273714070371],// etc...],];
Get both look angles (for a ground observer) as well as a few more tidbits of satellite info.
import{getSatelliteInfo}from"tle.js";constsatInfo=getSatelliteInfo(tleStr,// Satellite TLE string or array.1501039265000,// Timestamp (ms)34.243889,// Observer latitude (degrees)-116.911389,// Observer longitude (degrees)0// Observer elevation (km));->{// satellite compass heading from observer in degrees (0 = north, 180 = south)azimuth:294.5780478624994,// satellite elevation from observer in degrees (90 is directly overhead)elevation:81.63903620330046,// km distance from observer to spacecraftrange:406.60211015810074,// spacecraft altitude in kmheight:402.9082788620108,// spacecraft latitude in degreeslat:34.45112876592785,// spacecraft longitude in degreeslng:-117.46176597710809,// spacecraft velocity (relative to observer) in km/svelocity:7.675627442183371}
Calculates satellites visible relative to an observer's position.
import{getVisibleSatellites}from"tle.js";constallVisible=getVisibleSatellites({observerLat:34.439283990227125,observerLng:-117.47561122364522,observerHeight:0,// Array of 3-line TLE arrays.tles:uniqTLES,// Filters satellites above a certain elevation (0 is horizon, 90 is directly overhead).// E.g. 75 will only return satellites 75 degrees or greater above the horizon.// Defaults to 0.elevationThreshold:75,// Defaults to current time.timestampMS:1570911182419});->[{tleArr:['COSMOS 2492 [GLONASS-M]','1 39620U 14012A 19285.51719791 -.00000065 00000-0 10000-3 0 9999','2 39620 65.6759 35.9755 0011670 324.9338 289.9534 2.13103291 43246'],info:{lng:-124.83404516738146,lat:32.070522714505586,elevation:81.2241916805502,azimuth:251.01601040118692,range:19217.756476304672,height:19161.979896618526,velocity:3.9490073154305385}},{tleArr:['GSAT0203 (GALILEO 7)','1 40544U 15017A 19284.43409211 -.00000061 00000-0 00000+0 0 9996','2 40544 56.2559 48.3427 0003736 223.0231 136.9337 1.70475323 28252'],info:{lng:-117.86836105927033,lat:29.08239877156373,elevation:83.16839172166615,azimuth:183.67559090645165,range:23256.47316878015,height:23221.387218003325,velocity:3.6703580049175333}}]
In addition to the powerful functions above, there are also helpful functions for gettingspecific information from a TLE itself.
For further reading, seeKelso's article.
consttle=`ISS (ZARYA)1 25544U 98067A 17206.18396726 .00001961 00000-0 36771-4 0 99932 25544 51.6400 208.9163 0006317 69.9862 25.2906 15.54225995 67660`;
Returns the name of the satellite. Note that this defaults to 'Unknown' for 2-line TLEs that lackthe satellite name on the first line.
import{getSatelliteName}from"tle.js";getSatelliteName(tle);->'ISS (ZARYA)'
Returns theNORAD satellite catalog number.Used since Sputnik was launched in 1957 (Sputnik's rocket was 00001, while Sputnik itself was00002).
import{getCatalogNumber}from"tle.js";getCatalogNumber(tle);->25544
Returns the COSPAR id string, akainternational designator.
import{getCOSPAR}from"tle.js";getCOSPAR(tle);->"1998-067A"
Returns the satellite classification.
import{getClassification}from"tle.js";getClassification(tle);->'U'
Launch year (last two digits) (international designator), which makes up part of the COSPAR id.
Note that a value between 57 and 99 means the launch year was in the 1900s, while a value between00 and 56 means the launch year was in the 2000s.
import{getIntDesignatorYear}from"tle.js";getIntDesignatorYear(tle);->98
Launch number of the year(international designator), which makes up part of the COSPAR id.
import{getIntDesignatorLaunchNumber}from"tle.js";getIntDesignatorLaunchNumber(tle);->67
Piece of the launch(international designator), which makes up part of the COSPAR id.
import{getIntDesignatorPieceOfLaunch}from"tle.js";getIntDesignatorPieceOfLaunch(tle);->'A'
TLE epoch year (last two digits) when the TLE was generated.
import{getEpochYear}from"tle.js";getEpochYear(tle);->17
TLE epoch day of the year (day of year with fractional portion of the day) when the TLE wasgenerated.
import{getEpochDay}from"tle.js";getEpochDay(tle);->206.18396726
Unix timestamp (in milliseconds) when the TLE was generated (the TLE epoch).
import{getEpochTimestamp}from"tle.js";getEpochTimestamp(tle);->1500956694771
First Time Derivative of theMean Motion divided bytwo, measured in orbits per day per day (orbits/day2). Defines how mean motion changesfrom day to day, so TLE propagators can still be used to make reasonable guesses when distantfrom the original TLE epoch.
import{getFirstTimeDerivative}from"tle.js";getFirstTimeDerivative(tle);->0.00001961
Second Time Derivative ofMean Motion divided by six,measured in orbits per day per day per day (orbits/day3). Similar to the first timederivative, it measures rate of change in theMean Motion Dotso software can make reasonable guesses when distant from the original TLE epoch.
Usually zero, unless the satellite is manuevering or in a decaying orbit.
import{getSecondTimeDerivative}from"tle.js";getSecondTimeDerivative(tle);->0
Note: the original value in TLE is00000-0 (=0.0 x 100 =0).
BSTAR drag term. This estimates the effects of atmosphericdrag on the satellite's motion.
import{getBstarDrag}from"tle.js";getBstarDrag(tle);->0.000036771
Note: the original value in TLE is '36771-4' (=0.36771 x 10-4 =0.000036771).
Private value - used by theUnited States Space Force to reference the orbit model used to generate theTLE. Will always be seen as zero externally (e.g. by "us", unless you are "them" - in which case,hello!).
import{getOrbitModel}from"tle.js";getOrbitModel(tle);->0
TLE element set number, incremented for each new TLE generated since launch. 999 seems to mean theTLE has maxed out.
import{getTleSetNumber}from"tle.js";getTleSetNumber(tle);->999
TLE line 1 checksum (modulo 10), for verifying the integrity of this line of the TLE. Note that letters, blanks, periods, and plus signs are counted as 0, while minus signs are counted as 1.
import{getChecksum1}from"tle.js";getChecksum1(tle);->3
Note that this simply reads the checksum baked into the TLE string. Compare this with the computed checksum to ensure data integrity:
import{getChecksum1,computeChecksum}from"tle.js";constexpectedChecksum=getChecksum1(tle);->3constcomputedChecksum=computeChecksum(tle[1]);->3expectedChecksum===computedChecksum;->true
Inclination relative to the Earth'sequatorial plane in degrees. 0 to 90 degrees is a prograde orbit and 90 to 180 degrees is aretrograde orbit.
import{getInclination}from"tle.js";getInclination(tle);->51.6400
Right ascension of the ascending nodein degrees. Essentially, this is the angle of the satellite as it crosses northward (ascending)across the Earth's equator (equatorial plane).
import{getRightAscension}from"tle.js";getRightAscension(tle);->208.9163
Orbital eccentricity, decimal point assumed.All artificial Earth satellites have an eccentricity between 0 (perfect circle) and 1 (parabolicorbit).
import{getEccentricity}from"tle.js";getEccentricity(tle);->0.0006317
Note that the value in the original TLE is0006317, with the preceding decimal point assumed(=0.0006317).
import{getPerigee}from"tle.js";getPerigee(tle);->69.9862
Mean Anomaly. Indicates where the satellite waslocated within its orbit at the time of the TLE epoch.
import{getMeanAnomaly}from"tle.js";getMeanAnomaly(tle);->25.2906
Revolutions around the Earth per day (mean motion).
import{getMeanMotion}from"tle.js";getMeanMotion(tle);->15.54225995
Total satellite revolutions when this TLE was generated. This number seems to roll over (e.g.99999 -> 0).
import{getRevNumberAtEpoch}from"tle.js";getRevNumberAtEpoch(tle);->6766
TLE line 2 checksum (modulo 10) for verifying the integrity of this line of the TLE.
import{getChecksum2}from"tle.js";getChecksum2(tle);->0
Note that this simply reads the checksum baked into the TLE string. Compare this with the computed checksum to ensure data integrity:
import{getChecksum2,computeChecksum}from"tle.js";constexpectedChecksum=getChecksum2(tle);->0constcomputedChecksum=computeChecksum(tle[2]);->0expectedChecksum===computedChecksum;->true
🛰️ Satellite TLE tools in #"/topics/javascript" title="Topic: javascript" data-view-component="true"> javascript space spacecraft gps tle sgp4 satellites orbital-mechanics
