sattools/README.md

# sattools
This is a fork of cbassa's sattools to try to get it to work with
free software giza instead of proprietary and unmaintained pgplot.


# Install
In Debian: `libgiza0 giza-dev` etc.


# Giza
Here are two examples of how `skymap` should render, in this case using
`pgplot` (thx Pierros and Cees):

![skymap-pgplot-pierros](img/skymap-pgplot-pierros.png)

![skymap-pgplot-cees](img/skymap-pgplot-cees.png)

This is how `skymap` renders "out-of-the-box" using `giza` as a
drop-in replacement for `pgplot`:

![skymap-giza rev 0](img/skymap-giza-0.png)

Stars fix:

![skymap-giza rev 1](img/skymap-giza-1.png)

Text fix:

![skymap-giza rev 2](img/skymap-giza-2.png)

Rectangle fix, and grey:

![skymap-giza rev 4](img/skymap-giza-4.png)

More `pgplot` colors.

![skymap-giza rev 5](img/skymap-giza-5.png)

Giza sizing needs fixing...

![skymap-giza rev 6](img/skymap-giza-6.png)

SatNOGS TLE loads and renders.

![skymap-giza rev 7](img/skymap-giza-7.png)

There is an error that spams out to the console:

```
%giza - Warning - giza_set_character_height: Invalid character height, character height not set
```

The character heights are set to various values, typically `0.6`, `0.8`, and
`1.0`. Only `1.0` doesn't produce the error. But it renders much larger...
This has no errors, but looks bad. Overall need new font.

![skymap-giza rev 8](img/skymap-giza-8.png)

Satellite orbit lines rendering.

![skymap-giza rev 9](img/skymap-giza-9.png)

More, but not rendering so great...

![skymap-giza rev 11](img/skymap-giza-11.png)

Grid, but rendering with dots, not lines...

![skymap-giza rev 12](img/skymap-giza-12.png)

Rest of grid (blue background during day).

![skymap-giza rev 13](img/skymap-giza-13.png)

Equatorial. Hit `o` when `skymap` first launches, then it will re-render
with a faint equatorial "dot line circle"...

![skymap-giza rev 14](img/skymap-giza-14.png)

Remove broken constellations looks better for now.

![skymap-giza rev 15](img/skymap-giza-15.png)

fix orbit lines, maybe correct. need to confirm against main version.

![skymap-giza rev 16](img/skymap-giza-16.png)

Revert back to original size. Pierros has larger window somehow...

![skymap-giza rev 17](img/skymap-giza-17.png)


# Works
Testing/dev in Debian Bookworm (testing), with `giza` version `1.3.2`.

Out of box, this works:
* Sun.
* Moon.
* Besides the display, all the other functionality works.
  Can load a `satnogs.tle`, get satellite info, schedule, etc.


# Fixed
* Stars.
* Text header with date, observer, lat/lon/elevation.
* Footer with R, D etc.
* Rectangle.
* Apex renders, but as dots not lines.
* Grid renders, but as dots not lines.
* Satellites' colors.
* Orbit lines.
* FOV (but disabled by default upstream).


# TODO
* Lines are dots not lines.
* Small window size with giza.
* Constellations only partially rendered. Disabled.
* Apex rendering needs adjusting.
* Check license status of `sgdp4.c` and `sgdp4h.h`.
* Font.


# Functions
These are `pgplot` functions used by `skymap`.

```
cpgbox
cpgcirc
cpgconl
cpgcont
cpgcurs
cpgdraw
cpgend
cpgeras
cpgmove
cpgmtxt
cpgopen
cpgpap
cpgpt1
cpgqch
cpgqci
cpgqls
cpgrect
cpgsch
cpgsci
cpgscr
cpgsfs
cpgsls
cpgslw
cpgsvp
cpgtext
cpgwnad
```


# Color
Colors 1-15 are used in the color index, documented here:

* https://sites.astro.caltech.edu/~tjp/pgplot/fig51.html

Colors are off because giza uses it's own palette by default.
What is needed is to add `giza.h` and set this to use pgplot colors:

```
giza_set_colour_palette(1);
```


# Upstream
See `README-upstream.md`.


# License
Same as upstream license, GPLv3.

*Copyright (C) 2022, Jeff Moe*