s1aux 0.9
Sentinel-1 auxiliary (AUX) products reader.
License: Apache-2.0
Requires Python: >=3.10
Keywords: satellite, sentinel-1, esa, sar, sar-mpc

s1aux
=====

.. badges

|PyPI Status| |GHA Status| |Python Versions| |License|

.. |PyPI Status| image:: https://img.shields.io/pypi/v/s1aux.svg
    :target: https://pypi.org/project/s1aux
    :alt: PyPI Status
.. |GHA Status| image:: https://github.com/avalentino/s1aux/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/avalentino/s1aux/actions
    :alt: GitHub Actions Status
.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/s1aux
    :target: https://pypi.org/project/s1aux
    :alt: Supported Python versions
.. |License| image:: https://img.shields.io/pypi/l/s1aux
    :target: https://pypi.org/project/s1aux
    :alt: License

.. description

High level tools for reading Sentinel-1 auxiliary data produced by the
ESA SAR Mission Performance Cluster (SAR-MPC_).

`s1aux` exploits the `xsdata` Python package to read the XML files included
in the `data` folder of the Sentinel-1 Auxiliary Products.


.. _SAR-MPC: https://sar-mpc.eu


Usage
-----

The recommended way to load S1 AUX files is to use the ``s1aux.load``
function::

  >>> import s1aux
  >>> filename = (
        "S1A_AUX_INS_V20190228T092500_G20211103T111906.SAFE/data/s1a-aux-ins.xml"
      )
  >>> auxins_data = s1aux.load(filename)

The ``s1aux.load`` function automatically detects the version of the
relevant auxiliary product specification returns a ``dataclasses.dataclass``
instance generated by the underling ``xsdata`` package.

The information can be accessed through the attributes of the returned object::

  >>> import pprint
  >>> pprint.pprint(
        auxins.timeline_list.timeline[0].swath_map_list
      )

  SwathMapListType(swath_map=(SwathMapType(swath_number=0,
                                           swath=<SwathType.S1: 'S1'>),
                              SwathMapType(swath_number=50,
                                           swath=<SwathType.S1: 'S1'>),
                              SwathMapType(swath_number=36,
                                           swath=<SwathType.S1: 'S1'>),
                              SwathMapType(swath_number=86,
                                           swath=<SwathType.S1: 'S1'>)),
                   count=4)

It is also possie to use the ``xsdata`` API to read the AUX data for a
specific version of the auxiliary product specification::

   >>> from xsdata.formats.dataclass.parsers import XmlParser
   >>> auxins = parser.parse(filename, AuxiliaryInstrument)


Download
--------

The ``s1aux`` source code can be downloaded from the Git_
repository on GitHub_ at https://github.com/avalentino/s1aux
or from PyPI_: https://pypi.org/project/s1aux.


.. _Git: https://git-scm.com
.. _GitHub: https://github.com
.. _PyPI: https://pypi.org


Installation
------------

The pip_ tool can be used to install the package::

  $ python3 -m pip install s1aux


.. _Pip: https://pip.pypa.io


Testing
-------

``s1aux`` includes a quite complete test suite.
It is recommended to use the pytest_ tool to run the tests::

  $ python3 -m pytest tests


.. _pytest: https://docs.pytest.org


License
-------

Copyright (c) 2024-2025 Antonio Valentino

The `s1aux` package is distributed under the Apache-2.0 License
(see the `LICENSE` file).

The package also include test data that are distributed under the terms
of use of the Copernicus Sentinel Data and Service Information legal
notice as described in
https://sentinels.copernicus.eu/documents/247904/690755/Sentinel_Data_Legal_Notice

The text of the Copernicus Sentinel Data and Service Information legal
notice is also reported in `tests/data/LICENSE.txt`.