thkruz/keeptrack.space

🌎📡 TypeScript Astrodynamics Software for Non-Engineers. 3D Visualization of satellite data and the sensors that track them.

Table of Contents

• Project Overview
• Who Should Use KeepTrack?
• Features
• Screenshots
• Installation
• Usage
• Code Structure
• Previous Versions
• Contributors
• License

Project Overview

Welcome to KeepTrack, an ambitious project aiming to make orbital analysis tools accessible to all. Keep Track is the only astrodynamics tool designed for non-engineers. It provides a simplified and streamlined experience for learning and interacting with satellites and space debris. Keep Track is built from the ground up with custom WebGL shaders and a high-performance render loop. It can simulate 2.5 million pieces of debris at 60fps. The core app is only 7 Mb and loads in 2 seconds. It's free, open source, and works on any modern browser.

Who is KeepTrack for?

Keep Track is used in operations centers, classrooms, and outreach programs. Here are some examples of how different groups use Keep Track:

Operations Centers

• Get popup alerts when a satellite will pass through a sensor
• Find when sensors can see a priority satellite in seconds
• Easily simulate new launches for mission planning

Education

• Learn through hands-on interaction, making learning engaging
• Use Xbox controllers for classroom demonstrations
• Experience AAA video game quality graphics

Outreach

• Embed Keep Track on your website for free
• Show your satellite design in orbit before launch
• Explain space sustainability and the problem of debris

Features

The feature set rivals those of expensive toolkits, such as AGI's STK, and includes the ability to:

• View comprehensive satellite data
• Perform advanced field of view calculations
• Create notional maneuvers
• Model satellite breakups
• Simulate new satellite launches
• And much more

Screenshots

Installation

A github page is automatically deployed with the most-current version of the main branch to https://thkruz.github.io/keeptrack.space/. Periodically the most stable version will be pushed to https://keeptrack.space from the CI/CD pipeline.

Prerequisites

KeepTrack.Space is built using ES6+ modules and assembled with Webpack. If you would like to build it locally, you need to install git and npm.

Setting up a Local Copy

git clone https://github.com/thkruz/keeptrack.space       #Clone the github files.
cd ./keeptrack.space/                                     #Switch into the directory.
npm i                                                     #Install the dependencies.
npm run build                                             #Build the project.
npm start                                                 #Start the server.

Launching Offline Mode

KeepTrack was designed to run without the need for a server. On Windows, close all open copies of chrome and then launch the included KeepTrack.bat file. This will launch the index.html file inside of chrome with the "--allow-file-access-from-files" flag temporarily enabled. This is necessary to allow loading the catalog .json files from your computer.

NOTE: You MUST compile the code first. Opening the index.html file in the src folder will not work. If that feels overwhelming, take a look at https://github.com/thkruz/keeptrack.space/tree/gh-pages for a built version that can be downloaded and launched without the need to build it.

Usage

The main index.html page loads a canvas element set to the size of the window that displays the earth, satellites, and stars. The UI is loaded in DOM elements on top of the canvas element. Two webworkers are loaded (positionCruncher.ts and orbitCruncher.ts) to handle constant calculation of satellite locations and updating orbit lines when an object is highlighted.

The main draw loop (drawManager.ts) has been optimized to reduce memory leaks and to keep FPS high. This is commonly done by having functions modify global variables vs returning a variable and using long functions rather than splitting them into pieces - this is definitely intentional.

Any modifications to a satellite require that information to be passed to the positionCruncher webworker to ensure the UI calculations match the dot on the screen. Most calculations utilize a brute-force method of guess and check (lookangle times, missile trajectories, etc). Optimizing the loop for those calculations is critcal to keeping the project responsive. One trick to improve performance is that satSet creates a dictionary of index -> Norad ID number and index -> COSPAR number to allow rapid lookup of satellite data.

There are Typescript files for generating TLE.json that are not included, but http://keeptrack.space/tle/TLE2.json can be referenced for an up-to-date catalog.

Previous Versions

• Version 7.2 - Nebula Navigator
• Version 7.0 - Vega Viewpoint
• Version 6.0 - Celestial Symphony
• Version 5.4 - Orion Overhaul
• Version 5.0 - Apollo Augments

Contributors

• @Le-Roi777
• @hkruczek
• @cwang-pivotal

License

Copyright (C) 2016-2024 Theodore Kruczek
Copyright (C) 2020-2024 Heather Kruczek

KeepTrack.Space is licensed under the GNU Affero General Public License. This means you can freely use, modify, and distribute it, provided you adhere to the terms of the license. For more details, see the Full License.

keeptrack.space's Issues

Replacing TLE.json with a Real Database

The current .json database works but is 9MB and is slow to load. It is known to become corrupted on occasion (work-around in place) and is problematic during updates. Would like to convert to a mysql database or something similar.

Possible Collisions Side Menu Not Removed When Selecting Other Side Menus

Needs to be added to the hidesidemenu function.

Change Color Scheme from Settings

Four global variables for payload, r/b, debris, and inview objects that can be changed from the settings menu.

Launch Calendar

Launch calendar still relies on a manual update method from October 2016. This needs to be replaced with similar code from the SOCRATES cron job so that it can be updated automatically every 12 hours. Unclear how to handle a smooth transition into 2017, but maybe that part is just manual.

TLE.json Updates

There are a series of admin files that are currently not public. These include a few cron jobs that run every two hours to update TLEs. Until they are uploaded the TLE.json file only be updated when a new commit is added.

Calculate Distance Between Objects

I want to add a feature that allows you to type two object numbers in a menu and then calculate the distance between them at the current time. Should be as simple as determining the scale of the x, y, z coordinate system and then doing some subtraction.

Cron Job to Parse RCS Data

https://celestrak.com/pub/satcat.txt contains RCS values for all orbital satellites in m^2. This could be utilized to supplement the small, medium, large values.

Search Filters Unnecessary

Search filter for satellites currently pushes unnecessary data. Needs refined.

Lookangles Broken When Clock Froze

Lookangles won't generate when proprate = 0.

Weather Menu for Sensors without Weather Maps

Better handling is needed for when a sensor without a weather map is selected to display terrestrial weather.

Links in Sat Box not Working

Clicking find objects from this launch and objects near this satellite don't work.

Lookangles Start-Stop Style

Option in settings for start-stop style lookangles.

Reduce TLE.json Size

Replace most strings in the arrays with numerical values that can be decoded in main.js to drastically reduce database size.

Hard part is making a php script to convert the current database quickly.

ISS Stream Blocks Other Menus

Either need to hide it when other menus visible or move it somewhere else.

NORAD Number in Search

Would be nice to replace international designators in the search bar with NORAD numbers. Maybe another setting that toggles between the two?

Nominal Creation

Using a for loop a TLE with inclination and epoch day set to current day may have its R value and true anomaly adjusted until the current Lat Long matches a picked launch site.

TLE Change Detection

It would be useful if the script that updates the TLEs compared the new TLE to the old TLE and flagged large changes in inclination or period.

Disable Look Angles Until Sensor Selected

Currently it just opens an empty menu. Disable until sensor selected.

ELSETS not Updating in 2017

cron-ParseTLE.php doesn't seem to be working.

Disable All Buttons Until Orbits Generated

Currently the buttons can be pressed before everything is loaded. Can be clunky and would look much better if they were disabled until loading is finished.

Sat Info Box Tooltips

Replace default windows tooltips on the Sat Info Box with the same popups that are displayed when highlighting an object.

Analyst Mode

Long term it would be extremely useful to have a mode/page that runs the satcruncher without utilizing opengl or the satellite-orbit-worker. This would be a lot of menus with forms to do things like lookangles, elset comparisons, and collision calculations without taxing a slower computer with opengl.

Launch Icon Showing Disabled

New Launch shows disabled if the same satellite is selected, deselected, and reselected again.

Non-Selectable Objects Transparency

It would be helpful if non-selectable objects can be made more transparent using a setting on the page.

index.htm Organization

Currently the divs in index.htm are all over the place. They need to be sorted/organized.

Set Max Orbits in Settings Menu

Adjust max orbits variable from the settings menu.

Display Static Dots for Launch Sites

It would be nice to be able to display dots (similar to the satellites) in a static position on the earth to visually represent the launch sites. Added bonus if they are selectable to display information about the launch complexes.

Music and/or Sound Effects

Long term this might be something worth exploring. Music could be pulled from the open source project to do dynamic symphony music based on satellites in FOV.

Next Pass on Highlight

When highlighting an object after selecting a sensor, the popup should display the next pass time or if the object is currently in FOV.

Add Satellites

Add a case to sat-cruncher.js may allow main.js to send a new TLE to be added to satcache.

Imagery from On-Orbit Satellites

I would like to be able to see the most current imagery from any satellite that publishes images. This might be best in a menu that lists all the satellites that publish images and then a box that pops up when you select those satellites.

Social Media Integration

As we get closer to version 1.0 it would be smart to add social media integration so that you can share/tweet details that you are looking at and get more visitors.

Quick Look at All Sensors for Upcoming Passes

An alternative lookangles menu that displays the next few passes for each sensor to help identify which sensor will see an object next.

Start Time of Each Pass for 3 Days on One Sensor

Allow people to see each pass for a satellite at a given sensor.

Duplicate menu-radar ids

Four menus are all named menu-radar. They need to have different names and any code referencing them should probably be referencing the class instead.

Replace Observer Latitude Check with an Actual Variable

Currently there are checks to see if an observer's latitude is set to determine whether a sensor is selected or not. This should be replaced with a check to see if an actual variable is flagged. Will reduce potential bugs later.

Launch Nominals Going the Wrong Direction

The current algorith does not account for moving in a north or south direction. Conditional needed that factors in current latitude with last latitude to determine current heading.

Lookangles Adjustable Interval

Text box with adjustable interval for lookangles and multi site lookangles.

Deselecting Satellites Disables Look Angles and Multi-site Look Angles but leaves the Menu Open

Code needs to be added to the right click function to close the menu or a more elegant check to see if the menu should be disabled after right click has happened and the menu has been closed.

Developer Mode

There should eventually be a mode that can be accessed by passing a flag with the GET method when accessing index.htm. In this mode there would be many things that are tripped by a global DEVELOPER_MODE such as console log statements and raw data values.

Next Pass Time in Sat Box

Show the next pass time in the sat box. Code is already made for show next pass time on hover.

Rotate Around Object Instead of Earth

Modifying the free camera view to lock the x, y, z coordinates but allow the view to be rotated should accomplish this. This view will be useful for explaining how optical satellites can view other satellites.

Right mouse click not working.

Clicking the right mouse click is not firing the mouseup function.

Full SSN/Foreign View

Option to view what the whole SSN or all Russian/PRC tracking stations can view. This could be then leveraged to see what objects are out of view ("Dark Space") and for how long. Modifying satcruncher to do a full network check similar to how the SSN lookangles function works would enable this. It would require passing a binary variable to the web worker when the settings menu is modified.

Read Me Needs Updated

Read me is lacking. Needs better explanation of features and code.

Error Checking for Nominal Creator

Some objects end up inside the earth using the nominal creator. Should save the original TLEs and do a perigee check at the end of the nominal creation to decide whether or not to commit the new TLE.

Tooltips Margin Not Uniform

Margins on some of the bottom design elements are not transferred to the tooltips leaving an non-uniform look. Minor issue.

Use Custom Sensor

There is currently code to type in a custom sensor in the url, but it should be moved to a menu that appears when you select "Custom" from the drop downs at the top. This will set the ground for telescope users to calculate lookangles for backyard astronomy.

SOCRATES Camera Changes

Socrates method in main.js currently calls three other methods that all have camera changes. This causes the camera to bounce around unnecessarily.

Feedback on Disabled Button Click

Currently there is no feedback when you click the disabled buttons at the bottom. Perhaps a small jquery shake effect.