celestia-gnss/README.md

# Spacecruft Celestia GNSS
Celestia is a "real-time space simulation that lets you experience our
universe in three dimensions".

Celestia contains many celestial objects, but few that are man made, such
as Hubble. It has a TLE for the ISS, but it doesn't update it.

The present repo contains a script to import GNSS ("GPS") satellite
TLE files into Celestia. It could be easily updated for any other source
of TLEs.

![celestia-gnss-screenshot](pics/celestia-gnss-screenshot.png)


# Quick & Dirty Install
If you just want to import the pre-generated file into Celestia for
a look, just copy this file into your `extras` folder or similar.

* https://spacecruft.org/spacecruft/celestia-gnss/raw/branch/main/extras/gnss/gnss.ssc


# Install celestia-gnss
Install thusly to generate your own `.ssc` files.

```
git clone https://spacecruft.org/spacecruft/celestia-gnss
cd celestia-gnss
sudo apt update
sudo apt install python3-pip
# Many ways to do python setup, here is one:
pip3 install --upgrade --user pip
# Make sure your path includes `~/.local/bin`, if not, add it.
which pip
# Should be ~/.local/bin/pip
pip install --user -r requirements.txt
```

# Run celestia-gnss
Example (crufty example, if you have perms):

```
./tle2ssc > /usr/share/celestia/extras-standard/gnss/gnss.ssc
```


# Use in Celestia
Then copy the satellites you want into your Celestia extras dir.
Crufty bad way to do it, example:

```
sudo cp -a extras/gnss/gnss.ssc /usr/share/celestia/extras-standard/
```

Each system, GPS, Galileo, Glonass, Beidou, or the GNSS files can
be used which include all four.

# See Also

## Spacecruft
Spacecruft:

* https://spacecruft.org/spacecruft/gnss-earth

* https://spacecruft.org/spacecruft/celestia

## Celestia
Upstream Celestia:

* https://celestia.space/

* https://github.com/CelestiaProject/Celestia

Celestia forum thread about celestia-gnss:

* https://celestia.space/forum/viewtopic.php?f=6&t=22559

## TLE Conversion

TLE Conversion Spreadsheet by Grant Hutchison from July 2003,
the basis for the formulas in the `tle2ssc` script.

* https://www.classe.cornell.edu/~seb/celestia/hutchison/spreadsheets.html

* https://www.classe.cornell.edu/~seb/celestia/hutchison/tle-xls.zip

Useful formula from here too:

* https://kaitlyn.guru/projects/two-line-elements-tle/

I had this exact printout on my desk (trimmed to size!) when I came across
this gem from @fisadev via Poliastro docs:

<img src="pics/wtf-tle.jpg" width="600">

*How are satellite orbits disseminated?*

* https://docs.poliastro.space/en/latest/examples/Loading%20OMM%20and%20TLE%20satellite%20data.html

## Solar System Catalog
*"Solar System Catalog" files are primarily used to define the objects which
can be found in a stellar system, such as planets, moons, asteroids, comets,
and spacecraft. They also have four other uses: they can define alternative
surface textures, locations on or near an object, and orbital reference points.
An SSC file can also edit objects which have been defined in other SSC catalog files.*

Info on `.ssc` files:

* https://www.classe.cornell.edu/~seb/celestia/creating-ssc-files.html

* https://en.wikibooks.org/wiki/Celestia/SSC_File

In Celestia name "Galileo" is used for the *other* spacecraft, not
for the EU GNSS. So the name used in development here adds `-gnss`,
ala, `galileo-gnss.ssc`, whereas the other GNSS don't.

Example `.ssc` file contents:

```
"1997-035A" "Sol/Earth" {
  Class "spacecraft"
  # Mesh
  Radius  0.005

  EllipticalOrbit {
    Epoch  2459718.94467728
    Period  0.49859567
    SemiMajorAxis  26560.345
    Eccentricity  0.0057297
    Inclination  55.5062
    AscendingNode  156.8049
    ArgOfPericenter  51.2220
   MeanAnomaly  309.3262
  }
  Obliquity  55.5062
  EquatorAscendingNode  156.8049
  RotationOffset  80.2289
  # Orientation  [  ]
}
```

## TLE Sources

GNSS (All)
* https://celestrak.com/NORAD/elements/gnss.txt

Beidou (China)
* https://celestrak.com/NORAD/elements/beidou.txt

Galileo (Europe)
* https://celestrak.com/NORAD/elements/galileo.txt

Glonass (Russia)
* https://celestrak.com/NORAD/elements/glo-ops.txt

GPS (USA)
* https://celestrak.com/NORAD/elements/gps-ops.txt

## Spice
Spice TLE:
"Evaluate NORAD two-line element data for earth orbiting spacecraft."

* https://naif.jpl.nasa.gov/pub/naif/toolkit_docs/FORTRAN/spicelib/evsgp4.html

## SGP4
SPG4

*  https://pypi.org/project/sgp4/

## Skyfield
Skyfield

* https://rhodesmill.org/skyfield/earth-satellites.html


# 3D Models
Celestia uses an old 3D proprietary format from an old 3D application in
`.3ds` format. It also has it's own format `.cmod`.

## Galileo
Galileo 3D models are from the ESA:

* https://gssc.esa.int/education/galileo3d/

![celestia-galileo-screenshot](pics/celestia-galileo-screenshot.png)

## 3D Model Conversion
The `galileo.obj` file from the ESA can be read by `cmodview` in
the `celestia-tools` package. The file can be saved in `cmodview`
as `galileo-gnss.cmod` and then read by Celestia.

### Blender
`blender-2.79b` didn't work to convert a `.obj` file to `.3ds`
that rendered in Celestia.


# TODO
Do.

* All GNSS satellites are using the Galileo 3D model.

* Textures need to be added to 3D models.

* Orientation of satellite 3D models is incorrect.

* Confirm orbits are reasonably correct.


# Status
Alpha, under development.

Output works in Celestia. Orbits are not confirmed correct.


# License / Copyright
Upstream sources under their respective copyrights.

Copyright (C) 2022 Jeff Moe.

License: GPLv2 or any later version.