trusat/trusat-orbit

Python utilities for processing satellite position observations and managing TLEs

trusat-orbit

Convert satellite observations to orbit predictions

This repo supports the analyses of IOD/RDE/UK positional formatting formats and generation of TLEs at TruSat.org.

TruSat is a citizen-powered open-source tool for space sustainability, crowdsourcing satellite observations to form an independent record of objects orbiting Earth.

• Visit TruSat.org to see the live app
• View the docs to learn more about the project
• Join the Discord to follow the development discussion

Currently, this orbit propagation code is based on a Python port of Scott Campbell's C++ satfit code base. After initial prototyping, it is an aim of this repo to include OREKit and related tools for more advanced processing of orbit-related calculations.

Getting started with TruSat-orbit

First, we recommend setting up a python virtual environment

We're still working on a clean environment setup following conversion of the project to a pip-installable packages. A quick start looks something like:

pip3 install git+https://github.com/TruSat/[email protected]#egg=trusat_backend-1.1.0
pip3 install trusat
python -m trusat.satfit

Contents

• iod.py - Utilities for importing, validating, and operating on IOD/RDE/UK positional formatting formats
• tle_util.py - Utilities to import, export, validate and operate on Two-Line Element sets
• satfit.py - Suite of utilities based on and extending Scott Campbell's C++ satfit code base for reading visual observations and updating TLEs
  • satid.py - Search TLE catalog for possible match to an UNIDentified satellite TLE
  • elfind.py - Generate a provisional TLE from 2-3 IOD records

Tests - Unit tests for the above

• tests_iod.py
• tests_satfit.py
• tests_TLE.py
• tests_profile.py

Run with python -m unittest discover tests/

Dependencies

• Uses Brandon Rhodes python-sgp4 with C++ accelerations
• (Currently) requires Cython for the c-accelerated analyses module
• (Currently) assumes a connection to a database, see [this PR] (TruSat/trusat-backend#111) for setting up your own local copy
• (Currently) requires pulling trusat-backend into the same parent directory as trusat-orbit

Coding Style

Follow PEP 8 for any Python code and the style guide recommended for any other language.

Additionally see Best of the Best Practices

Maintaining Repo

Style Guide With the addition of commits to the master branch are done through PRs (Pull Request).

Releasing Versions

1. Checkout master
2. pull from repo
3. run the unittests
4. create a tag with the new version number, starting with a 'v'. eg:

git tag v0.1.1 -m "Version 0.1.1 Version Numbering 5. push changes to github git push --follow-tags 7. check verification tools

trusat-orbit's Issues

International Designators are not handled properly with analyst objects

TLE with catalog numbers in the 80,000 range do not import because tle_util.py is expecting a launch number / launch piece.

Restore IOD-file processing workflow in satfit.py:main()

satfit.py has been primarily extended to interact with and process records originating from the TruSat database via https://github.com/consensys-space/trusat-backend/

A few small tweaks would restore the capability to operate from file records.

Angle parsing should handle Epoch=0 when provided AZ/EL observation

https://github.com/consensys-space/trusat-orbit/blob/00bf2f2a9f674e03e4b01fbc73fb1bb48e6df494/iod.py#L422

This may also have implications on downstream use of RA/DEC as a default, and instead should operate with the angle as specified, or handle this case by asserting an EPOCH when creating an RA/DEC from an AZ/EL.

Implement algorithm to derive approximate orbit number when not provided from TLE

Probably cover in tle_util.py derived_values() if it does not exist.

Legitamate IOD formats are not being accepted

1. When a user submits an IOD that doesn't contain Angle Code or Epoch Code:

• The default value for Angle format code is set to -1
• The default value for Epoch code is set to -1

This can be tested by submitting a Clouded out submission, which sends empty values for both Angle Code and Epoch Code. This causes problems because both of these values are expected to be one character in length in the database table.

2. The IOD RegEx is expecting values for both right ascension and declination if a value of + or - for declination/elevation sign is present (+ it is automatically entered for the user on the front-end)

Finish iod.py:write_uk_line() functionality

The following function is incomplete:
https://github.com/consensys-space/trusat-orbit/blob/3e5c7f7b6d16e32778c22fc0f7d31b8ae3e0c670/iod.py#L1520

Completion of this would allow for the conversion of RDE-formatted observations to single-instance records more easily processed by satfit tools, and from database queries.

new_rde_data_line_re.search() stalls

This was previously TruSat/trusat-backend#26 as follows:

Following unit test updates, both SeeSat archive import scripts appear to be "paused," in a Ctrl-S terminal way, in the process of importing. Ctrl-C in the terminal allows them to continue, but it is unclear what is the underlying cause, or if data loss happens because of the Ctrl-C.

Debugger sessions have yet to refine the location of the problem itself.

From terminal feedback with the -V flag:
https://github.com/consensys-space/trusat-backend/blob/257bf4606147dbd927f3c3b9acf453b475c22656/database_tools/read_seesat_mbox.py#L346

...the script appears to consistently "pause" after the following lines:

Found  67 IOD obs in msg: 2015-03-19 23:23:00+01:00 LB Obs 2015 Mar 19
Found 162 IOD obs in msg: 2018-04-21 10:05:40+02:00 LB Obs 2018 Apr 20-21 night
Found   2 IOD obs in msg: 2019-03-27 22:56:50+01:00 Obs 2019 Mar 27 pm
Found   3 IOD obs in msg: 2019-09-20 07:28:25-04:00 slow moving unid seen on Sept 19

and has been traced to the following regex in iod.py:

https://github.com/consensys-space/trusat-orbit/blob/ea82c90af2645183318f7fc716a901960e0d5c65/iod.py#L760-L784

Re-writing the regex with no extraneous whitespace (to disallow the OR'ed flags for re.MULTILINE and re.VERBOSE) did not solve the problem.

It could be due to a problem with exponential possibilities on possible matches, referenced in https://bugs.python.org/issue29977

An interim "solution" is to use the previous RDE-block matching regexp (rde_format_re), which is not as comprehensive.

TLE formatting issues

As report by @cbassa at https://discuss.trusat.org/t/trusat-org-operations-updates/44/14

1. Leading zeros are missing in the NORAD ID (column 2 of lines 1 and 2)

2. Some satellites have negative inclination (take the absolute value and increment RAAN by 180 deg)

3. The first derivative of mean motion (column 5 of line 1) has no leading 0. This offsets later columns by one character, leading to bad predictions

Setting bstar = 0 does not work

Should be able to reset bstar to zero in the interactive commands, but it does not recognize 0 or 0.0 as valid input and uses the previous value.

Angle Regex catches too wide angles

This regex still needs a little work, as it still tries to process angles that are off by one character, or one character too wide.

https://github.com/consensys-space/trusat-orbit/blob/ea82c90af2645183318f7fc716a901960e0d5c65/iod.py#L32-L43

Problem angle: '1711809-682410' - Offending line:
39462 13 072A 0899 G 20171020002300180 17 25 1711809-6824100 37 S

Add creation of epoch_year and epoch_day variables when initialized from satrec

The value exists when created from a TLE, but not when created from an SGP4 satrec.

https://github.com/consensys-space/trusat-orbit/blob/00bf2f2a9f674e03e4b01fbc73fb1bb48e6df494/tle_util.py#L422

Create routine to calculate local time of observation

Most likely implemented in satfit.py - may have to "guess" at timezone of user from station location (lat/lon to timezone conversion)

IOD regex rejecting seemingly valid entries

https://github.com/consensys-space/trusat-orbit/blob/b5604c6025dca0ce05e89c18f39fbfd389b2e657/iod.py#L661

See https://regex101.com/r/nSuRNo/1 for missed entries.
Front-end rejected the same lines as reported "not matched" at regex101

elfind.py and satid.py depend on v1_4 python-sgp4

Version string in Cythonized python-sgp4 was updated to version = '1.4_cython' to distinguish it from the regular version.

Probably should update @interplanetarychris port of python-skyfield to accept this version and include it in the requirements.txt file

These utilities won't work in the default environment until that is fixed.

Create ability to plot value of elements over time

Be able to visualize the 6 classical orbital elements, as well as the individual two-line elements as a function of time.

This would allow for observing trends in satellite properties, and potentially assist in better fits to observations over time.

Implement weighting for individual IODs for both orbit-fit and rms-reporting

Create mechanism to provided weighted consideration of individual IODs, with concepts ranging from:

1. all "100%" (all equal)
2. heavier weight to most-recent observations
3. heavier weight to higher-ranked observers
4. Low/zero weight to outlier observations from low-ranked observers
5. Equal weight to observation sessions with min number of observations (e.g. 100 observations on one pass have the same weight as 3 observations on another pass)

First implementation of this would provide for manual specification of weights from UI in satfit.py

Create subroutine to identify observation clusters

In preparing for an increased level of automation on making TLEs from observations, it would be useful to have algorithm access to "clusters" of observations.

This is most likely implemented in a python function with scans a list of IODs returned from the database, and groups by:

1. Observations from a single station
2. Observations within (X) time of each other -- X could be hard-coded (less than 15 minutes from the same station), or made variable by the characteristics of the satellite mean motion.

It would be useful for the clusters to be identified by an index, as well as a "average(?)" obs time, which would allow removing older clusters of observations from the current set, until some minimum RMS is achieved, or the number of clusters and their spacing prevents further reduction.

Explore move_epoch_to_jd_new() as a mechanism to determine quality of satobs fit

In manual processing, sometimes resetting the the epoch to the value of the most recent epoch greatly increase the RMS value of the fit.

This may be an indicator of the quality of the TLE elements fit, and could potentially be used as a "quick test" to see how a delta of 1 (day, week, month) might indicate the quality of the TLE, by looking at the "back-fit" of this artificially generated epoch.

Word of warning, it could also reflect underlying problems with the move_epoch_to_jd_new() function to change the TLE epoch.

Add in derived values for ndot and nddot if not obtained from TLE

Derive mean_motion_derivative (ndot) and mean_motion_sec_derivative (nddot) if not available from TLE.

https://github.com/consensys-space/trusat-orbit/blob/00bf2f2a9f674e03e4b01fbc73fb1bb48e6df494/tle_util.py#L422

SGP4 units:
satrec.ndot = satrec.ndot / (xpdotp1440.0);
satrec.nddot= satrec.nddot / (xpdotp1440.0*1440);

iod.parse_iod_line() breaks when seconds are passed the expected boundaries of 0-59

When calling iod.parse_iod_line(), an error is thrown when the seconds in the observation are set to 60. This is a valid number but not supported in datetime.strptime() when called in DateTime_frompacket().