GPS timestamps
==============
Siril can manage GPS timestamps and metadata coming from QHY PRO cameras. Two
completely different systems exist:

* the all-in-one global shutter cameras, like the famous QHY174GPS and the
  infrared 990 and 991 PRO versions,

* the rolling shutter cameras with the external GPSBOX, like the QHY268PRO,
  QHY600PRO and other high end models.

Their data is managed quite differently, refer to the sections below. But in
both cases, the camera writes GPS metadata in the form of 44 bytes at the start
of the image pixel data, generally appearing much brighter than the rest of the
image and displayed at the bottom because FITS images are displayed bottom-up.
Siril can either read this data or use the already extracted data from an
acquisition software like `NINA <https://nighttime-imaging.eu/>`_ that would
have saved it in the agreed-upon FITS headers. This code has been contributed
to both software by the `OurSky company <https://oursky.ai>`_.

.. warning::
   Make sure your GPS antenna is not moving with the telescope, mounted in a
   safe place with a clear view of the sky. Otherwise, data will be erroneous,
   which is often indicated by a bad lock status value (it must be 3) or a bad
   PPS value (it must be slightly below 10000000).

   Many cameras have problems and produce erroneous data once in a while, for
   unknown reasons. Using firmware and SDK versions more recent than 2022 is a
   good idea for this and metadata bug fixes.

To cover the various use cases, data can be extracted or displayed using the
``gps`` command. For rolling shutter cameras, it is expected that in the near
future the GPS timestamps will automatically be used in photometric extraction,
this is not currently the case and requires manual use of this command.

.. admonition:: Siril command line
   :class: sirilcommand
  
   .. include:: ./commands/gps_use.rst

   .. include:: ./commands/gps.rst
  

Global shutter cameras
----------------------

These cameras require extensive calibration and set-up, but once working, all
needed data is in the so-called metadata at the start of image pixel data. This
data is quite simple and can be summarized as GPS lock status, an exposure
start date and an exposure length. If the lock is good and all data looks
valid, extracting it in Siril will replace ``DATE-OBS`` and ``EXPTIME``, so any
image timestamp usage will use the GPS time. To indicate that this replacement
has been done, another key is added: ``DATE-GPS``, taking a boolean value.

To extract the metadata, simply use the ``gps`` command with no argument on a
raw loaded image. Data will be read and if looks valid, it will be used and
removed from the image by cropping the first row of pixels, to avoid disturbing
image statistics with it (also because after image processing they will not
mean anything anymore).

To verify the extracted metadata from previous uses or from the acquisition
software, use the ``gps -header`` command.

Rolling shutter cameras
-----------------------

In addition to the metadata found in the start of image pixel data, rolling
shutter cameras require QHY SDK calls to obtain rolling shutter information for
the camera and the gain mode being used. Siril cannot know that from a random
image unless the capture software captured this information and stored it in
the FITS header. NINA does that. While the keys representing the GPS metadata
are named with the ``GPS_`` prefix, those keys are named with the ``QHY_``
prefix.

Rolling shutter information is important if one wants to compute accurate
timestamp of a pixel of the image. It is very significant for short exposures
as the rolling shutter can take in the order of 250 ms to capture the entire
image, meaning there would be a difference in timestamps of 250 ms between
first and last row of pixels in this example.

For this reason, ``DATE-OBS`` is not overwritten with GPS data. Also, because
the metadata of global and rolling shutter cameras are in the same format, some
of it is meaningless with rolling shutter cameras: the start and end capture
times are the same, so computed exposure is always 0. This is normal.

Siril can compute the timestamp for a pixel row (1000 in this example) of a
rolling shutter image using the command ``gps 1000``.

Flipping, cropping and re-binning the image is supported, Siril keeps track of
these operations to keep timestamps accurate.