ASGARD

https://geolib.pages.eopf.copernicus.eu/asgard/
Admin
ASGARD is a sensor geometry modeling tool for Sentinel missions that performs geolocation and...
Tokens:353,267
Snippets:1,039
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Manual ASGARD Installation with Wheels (Bash)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs ASGARD, PyRugged, and Orekit-JCC by using pre-downloaded wheel files. This method requires manually obtaining the wheel files from their respective repositories and then installing them within a Python virtual environment.

```Bash
# Create a Virtual venv with python3.11 and activate it
python3.11 -m venv [VENV_NAME]
source path/to/[VENV_NAME]/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install orekit-jcc from wheel
pip install /path/to/orekit_jcc*.whl

# Install pyrugged from wheel
pip install /path/to/pyrugged*.whl

# Install asgard from wheel
pip install /path/to/asgard_eopf*.whl

# Activate the VENV (after initial installation)
source path/to/[VENV_NAME]/bin/activate

```

--------------------------------

### Pull ASGARD Docker Build Environment

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Pulls the pre-configured Docker image containing all necessary dependencies for building ASGARD, including EOCFI, GDAL with Java bindings, Java 8 JDK, JCC, and Maven. This image simplifies the setup for building ASGARD and its components.

```bash
docker pull registry.eopf.copernicus.eu/geolib/asgard-build-environment
```

--------------------------------

### Manual GEOLIB Installation using Wheels (Bash)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs GEOLIB packages (Orekit-JCC, PyRugged, ASGARD, SXGEO, ASGARD-Legacy) manually by installing pre-downloaded wheel files using pip within a Python virtual environment.

```shell
# Create a Virtual venv with python3.11 and activate it
python3.11 -m venv [VENV_NAME]
source path/to/[VENV_NAME]/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install orekit-jcc from wheel
pip install /path/to/orekit_jcc*.whl

# Install pyrugged from wheel
pip install /path/to/pyrugged*.whl

# Install ASGARD from wheel
pip install /path/to/asgard_eopf*.whl

# Install SXGEO from wheel
pip install /path/to/sxgeo*.whl

# Install ASGARD-Legacy from wheel
pip install /path/to/asgard_legacy*.whl
```

```shell
# Activate the VENV
source path/to/[VENV_NAME]/bin/activate
```

--------------------------------

### Install ASGARD Notebook Dependencies

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs additional dependencies required for using ASGARD within Jupyter notebooks. This is done using an editable install, specifying the 'notebook' group.

```bash
pip install -e . --group notebook
```

--------------------------------

### Develop ASGARD with Editable Install

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs ASGARD in editable mode (`-e`) from its local source code within a virtual environment. This allows for development changes to be reflected immediately without reinstallation. It also installs testing and other development-specific dependencies.

```bash
cd asgard

python3.11 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install pytest-xdist wheel cython

# Install orekit-jcc from GitLab packages
python3 -m pip install orekit-jcc --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/94/packages/pypi/simple

# Install pyRugged from GitLab packages
python3 -m pip install pyRugged --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/78/packages/pypi/simple

# Install ASGARD in editable mode with dev dependencies
python3 -m pip install -e . --group dev
```

--------------------------------

### Build ASGARD-Legacy from Sources

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

This procedure clones the ASGARD-Legacy repository, navigates into the directory, and then installs the package in editable mode using pip. This method is used to build the binary extensions for ASGARD-Legacy, requiring Cython and EOCFI binaries.

```bash
git clone https://gitlab.eopf.copernicus.eu/geolib/asgard-legacy.git
cd asgard-legacy
pip install -e .
```

--------------------------------

### Activate Existing Virtual Environment

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Activates a previously created Python virtual environment, making its Python interpreter and installed packages available in the current terminal session. This command is used after the initial setup.

```bash
source path/to/[VENV_NAME]/bin/activate
```

--------------------------------

### Install SXGeo Wheel Package

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

After successfully building the SXGeo project, this command installs the generated Python wheel package from the 'dist' directory. Replace '[...]' with the specific version and build details of your SXGeo wheel.

```bash
pip install dist/sxgeo-[...].whl
```

--------------------------------

### Install System Dependencies for Development

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs necessary system libraries and tools required for building ASGARD and its Python dependencies from source on Debian-based systems (like Ubuntu or Linux Mint).

```bash
sudo apt-get install python3.11-venv python3.11-dev gcc g++ git unzip
```

--------------------------------

### Setup Timestamp Models in Python

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/sensors/sentinel3/slstr

Creates and caches ScanningDetectorTimestampModel instances for each instrument. It calculates pixel start and period based on acquisition times, instrument view/group, and scaling factors, handling different pixel grid indexing (e.g., 500m).

```Python
def _build_timestamp_models(self):
    """
    Setup the map of ScanningDetectorTimestampModel
    """

    model_cache = {}
    time_delta = self.config["acquisition_times"]["pix10sync"] / JD_TO_MICROSECONDS
    nb_acq = self._constants["num_acq_per_scan"]
    for instr in self._instr_list:
        view, group, _ = instr.split("/")
        # handle cache, all detectors share the same timestamp model
        view_group = view + "/" + group
        if view_group in model_cache:
            self.timestamp_models[instr] = model_cache[view_group]  # noqa: B909
            continue

        # compute pixel start
        first_acq = self.config["acquisition_times"][view]["first_acquisition"]
        step = self.config["acquisition_times"][view]["step"]
        if group.startswith("05KM"):
            # shift to 500m pixel indexing
            scale = 2
            if step > 1:
                # for TPix grid (sub-sampled grid), we need to double the step
                step *= 2
            # For native instrument grid (step=1), we assume input coordinates already have 500m
            # indexing
        else:
            scale = 1

        if len(first_acq) == 1:
            first_acq = int(first_acq[0])
        pixel_start = (first_acq % nb_acq) * scale

        # compute pixel period
        pixel_period = time_delta / scale
        config_timestamp = {
            "scan_times": self.config["acquisition_times"][view]["scan_times"],
            "pixel_period": pixel_period,
            "pixel_start": pixel_start,
            "step": step,
        }

        model_cache[view_group] = ScanningDetectorTimestampModel(**config_timestamp)  # noqa: B909

```

--------------------------------

### Automatic ASGARD Installation using Pip (Bash)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs ASGARD, PyRugged, and Orekit-JCC directly from their private package repositories using pip. This requires specifying the custom index URLs for each package during the pip install command.

```Bash
# Create a Virtual venv with python3.11 and activate it
python3.11 -m venv [VENV_NAME]
source path/to/[VENV_NAME]/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install orekit-jcc from package repository
pip install orekit-jcc==[OREKIT_JCC_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/94/packages/pypi/simple

# Install pyrugged from package repository
pip install pyRugged==[PYRUGGED_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/78/packages/pypi/simple

# Install ASGARD from package repository
pip install asgard-eopf==[ASGARD_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/52/packages/pypi/simple

# Activate the VENV (after initial installation)
source path/to/[VENV_NAME]/bin/activate

```

--------------------------------

### Automatic GEOLIB Installation via Pip with Index URLs (Bash)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs GEOLIB packages by specifying their respective private package repository URLs directly in the pip install command within a Python virtual environment.

```shell
# Create a Virtual venv with python3.11 and activate it
python3.11 -m venv [VENV_NAME]
source path/to/[VENV_NAME]/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install orekit-jcc from package repository
pip install orekit-jcc==[OREKIT_JCC_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/94/packages/pypi/simple

# Install pyrugged from package repository
pip install pyRugged==[PYRUGGED_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/78/packages/pypi/simple

# Install ASGARD from package repository
pip install asgard-eopf==[ASGARD_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/52/packages/pypi/simple

# Install SXGEO from package repository
pip install sxgeo==[SXGEO_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/67/packages/pypi/simple

# Install ASGARD-Legacy from package repository
pip install asgard-legacy==[ASGARD_LEGACY_VERSION] --index-url https://gitlab.eopf.copernicus.eu/api/v4/projects/92/packages/pypi/simple
```

```shell
# Activate the VENV
source path/to/[VENV_NAME]/bin/activate
```

--------------------------------

### Install ASGARD and Dependencies via Pip

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs ASGARD and its core Python dependencies, orekit-jcc and pyrugged, from their respective package repositories. Specify the desired version for each package.

```bash
# Install orekit-jcc from package repository
pip install orekit-jcc==[OREKIT_JCC_VERSION]

# Install pyrugged from package repository
pip install pyRugged==[PYRUGGED_VERSION]

# Install ASGARD from package repository
pip install asgard-eopf==[ASGARD_VERSION]
```

--------------------------------

### Build SXGeo using Maven and JCC with GraalVM

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

This sequence of commands clones the SXGeo repository, builds the SXGeo JAR file using Maven, sets the GraalVM installation path, and then executes the Python script to build the JCC-wrapped project with GraalVM. The final output is a wheel package in the 'dist' folder.

```bash
git clone https://gitlab.eopf.copernicus.eu/geolib/sxgeo.git
cd sxgeo
make sxgeo-jar
export GRAALVM_INSTALL=/path/to/graalvm-community-openjdk-17.0.7+7.1
./python/build_jcc_graalvm.sh
```

--------------------------------

### Install ASGARD in Default Mode

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs ASGARD in the default mode, typically for runtime usage rather than development. This is achieved by running pip install with the editable flag but without specifying any additional groups.

```bash
pip install -e .
```

--------------------------------

### Run ASGARD Tests

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Executes the test suite for ASGARD to validate its installation and functionality. This command should be run after setting the ASGARD_DATA environment variable pointing to the test data.

```bash
export ASGARD_DATA=[PATH_TO_ASGARD_DATA]
pytest
```

--------------------------------

### Install Orekit-JCC Wheel Package

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Installs the Orekit-JCC Python wheel package after it has been built. The command uses pip to install the package from the local 'dist' directory. This step is crucial for integrating Orekit functionality into ASGARD.

```bash
pip install dist/orekit_jcc-[...].whl
```

--------------------------------

### Configure PIP_EXTRA_INDEX_URL for GEOLIB Installation (Bash)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Sets the PIP_EXTRA_INDEX_URL environment variable to include EOPF GitLab package repositories, allowing pip to find private packages without explicit index URLs in the install command. Includes persistence in .bashrc.

```shell
EOPF_ASGARD_EXTRA_INDEX_URL="https://gitlab.eopf.copernicus.eu/api/v4/projects/14/packages/pypi/simple"
EOPF_PYRUGGED_EXTRA_INDEX_URL="https://gitlab.eopf.copernicus.eu/api/v4/projects/78/packages/pypi/simple"
EOPF_OREKITJCC_EXTRA_INDEX_URL="https://gitlab.eopf.copernicus.eu/api/v4/projects/94/packages/pypi/simple"
EOPF_SXGEO_EXTRA_INDEX_URL="https://gitlab.eopf.copernicus.eu/api/v4/projects/67/packages/pypi/simple"
EOPF_ASGARD_LEGACY_EXTRA_INDEX_URL="https://gitlab.eopf.copernicus.eu/api/v4/projects/92/packages/pypi/simple"

export PIP_EXTRA_INDEX_URL="
${EOPF_ASGARD_EXTRA_INDEX_URL}
${EOPF_PYRUGGED_EXTRA_INDEX_URL}
${EOPF_OREKITJCC_EXTRA_INDEX_URL}
${EOPF_SXGEO_EXTRA_INDEX_URL}
${EOPF_ASGARD_LEGACY_EXTRA_INDEX_URL}
"
```

```shell
#Add the lines from the previous section at the end of the `.bashrc` file.
[ACTION_TO_COPY]

#Reload your `.bashrc` in your current session:
source ~/.bashrc
```

```shell
# Create a Virtual venv with python3.11 and activate it
python3.11 -m venv [VENV_NAME]
source path/to/[VENV_NAME]/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install orekit-jcc from package repository
pip install orekit-jcc==[OREKIT_JCC_VERSION]

# Install pyrugged from package repository
pip install pyRugged==[PYRUGGED_VERSION]

# Install ASGARD from package repository
pip install asgard-eopf==[ASGARD_VERSION]

# Install SXGEO from package repository
pip install sxgeo==[SXGEO_VERSION]

# Install ASGARD-Legacy from package repository
pip install asgard-legacy==[ASGARD_LEGACY_VERSION]
```

```shell
# Activate the VENV
source path/to/[VENV_NAME]/bin/activate
```

--------------------------------

### Setup Pointing Model

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/sensors/sentinel3/olci

Initializes the LineDetectorPointingModel using the provided pointing vectors (X and Y) which define the instrument's pointing direction.

```python
# Setup pointing model
        pointing_config = {
            "unit_vectors": self.init_pointing_angles(
                kwargs["pointing_vectors"]["X"],
                kwargs["pointing_vectors"]["Y"],
            )
        }
        self.pointing_model = LineDetectorPointingModel(**pointing_config)
```

--------------------------------

### ASGARD-Legacy S3 OLCI Geometry Initialization

Source: https://geolib.pages.eopf.copernicus.eu/asgard/user_manual

Example of initializing an S3 OLCI Geometry using ASGARD-Legacy with a Python dictionary.

```APIDOC
## Instantiate ASGARD-Legacy S3 OLCI Geometry

### Description
Initializes an S3 OLCI Geometry object from ASGARD-Legacy using a configuration dictionary.

### Method
Instantiation (via Python class constructor)

### Endpoint
N/A (Python library usage)

### Parameters
#### Request Body
- **config** (dict) - Required - A dictionary containing sensor-specific configuration data for S3 OLCI (same structure as ASGARD).

### Request Example
```python
from asgard_legacy.sensors.sentinel3 import S3OLCILegacyGeometry
import numpy as np

# config dictionary should be the same as the ASGARD example
config = {
    "sat": "SENTINEL_3",
    "orbit_aux_info": {
        "orbit_state_vectors": [
            {
                "times": {
                    "TAI": {"offsets": np.array([...])},
                    "UTC": {"offsets": np.array([...])},
                    "UT1": {"offsets": np.array([...])},
                },
                "positions": np.array([...]),
                "velocities": np.array([...]),
                "absolute_orbit": np.array([...]),
            },
        ],
    },
    "dem_config_file": "path_to_dem",
    "pointing_vectors": {
        "X": np.array([...]),
        "Y": np.array([...]),
    },
    "thermoelastic": {
        "julian_days": np.array([...]),
        "quaternions_1": np.array([...]),
        "quaternions_2": np.array([...]),
        "quaternions_3": np.array([...]),
        "quaternions_4": np.array([...]),
        "on_orbit_positions_angle": np.array([...]),
    },
    "frame": {
        "times": {"offsets": np.array([...])},
    },
}

my_product = S3OLCILegacyGeometry(**config)
```

### Response
#### Success Response (200)
- **my_product** (S3OLCILegacyGeometry) - The instantiated S3OLCILegacyGeometry object.

#### Response Example
(No direct response body, object is created in memory)
```

--------------------------------

### ASGARD S3 OLCI Geometry Initialization

Source: https://geolib.pages.eopf.copernicus.eu/asgard/user_manual

Example of initializing an S3 OLCI Geometry using ASGARD with a Python dictionary.

```APIDOC
## Instantiate ASGARD S3 OLCI Geometry

### Description
Initializes an S3 OLCI Geometry object from ASGARD using a configuration dictionary.

### Method
Instantiation (via Python class constructor)

### Endpoint
N/A (Python library usage)

### Parameters
#### Request Body
- **config** (dict) - Required - A dictionary containing sensor-specific configuration data for S3 OLCI.
  - **sat** (str) - Required - Satellite name (e.g., "SENTINEL_3").
  - **orbit_aux_info** (dict) - Optional - Information about orbit state vectors.
    - **orbit_state_vectors** (list) - Optional - List of orbit state vector entries.
      - **times** (dict) - Optional - Time information.
        - **TAI** (dict) - Optional - TAI time offsets.
          - **offsets** (np.array) - Optional - TAI time offsets.
        - **UTC** (dict) - Optional - UTC time offsets.
          - **offsets** (np.array) - Optional - UTC time offsets.
        - **UT1** (dict) - Optional - UT1 time offsets.
          - **offsets** (np.array) - Optional - UT1 time offsets.
      - **positions** (np.array) - Optional - Orbit positions.
      - **velocities** (np.array) - Optional - Orbit velocities.
      - **absolute_orbit** (np.array) - Optional - Absolute orbit number.
  - **dem_config_file** (str) - Optional - Path to the DEM configuration file.
  - **pointing_vectors** (dict) - Optional - Pointing vectors.
    - **X** (np.array) - Optional - X component of pointing vectors.
    - **Y** (np.array) - Optional - Y component of pointing vectors.
  - **thermoelastic** (dict) - Optional - Thermoelastic properties.
    - **julian_days** (np.array) - Optional - Julian days.
    - **quaternions_1** (np.array) - Optional - Quaternion component 1.
    - **quaternions_2** (np.array) - Optional - Quaternion component 2.
    - **quaternions_3** (np.array) - Optional - Quaternion component 3.
    - **quaternions_4** (np.array) - Optional - Quaternion component 4.
    - **on_orbit_positions_angle** (np.array) - Optional - On-orbit positions angle.
  - **frame** (dict) - Optional - Frame information.
    - **times** (dict) - Optional - Frame time information.
      - **offsets** (np.array) - Optional - Frame time offsets.

### Request Example
```python
from asgard.sensors.sentinel3 import S3OLCIGeometry
import numpy as np

config = {
    "sat": "SENTINEL_3",
    "orbit_aux_info": {
        "orbit_state_vectors": [
            {
                "times": {
                    "TAI": {"offsets": np.array([...])},
                    "UTC": {"offsets": np.array([...])},
                    "UT1": {"offsets": np.array([...])},
                },
                "positions": np.array([...]),
                "velocities": np.array([...]),
                "absolute_orbit": np.array([...]),
            },
        ],
    },
    "dem_config_file": "path_to_dem",
    "pointing_vectors": {
        "X": np.array([...]),
        "Y": np.array([...]),
    },
    "thermoelastic": {
        "julian_days": np.array([...]),
        "quaternions_1": np.array([...]),
        "quaternions_2": np.array([...]),
        "quaternions_3": np.array([...]),
        "quaternions_4": np.array([...]),
        "on_orbit_positions_angle": np.array([...]),
    },
    "frame": {
        "times": {"offsets": np.array([...])},
    },
}

my_product = S3OLCIGeometry(**config)
```

### Response
#### Success Response (200)
- **my_product** (S3OLCIGeometry) - The instantiated S3OLCIGeometry object.

#### Response Example
(No direct response body, object is created in memory)
```

--------------------------------

### Get Validity Range of OSF

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/orbit

Retrieves the validity range (start and end times) of the Orbit State File (OSF). It uses a time model to convert earliest and latest times into absolute dates, considering a specified epoch and unit.

```python
@property
def valid_range(self) -> Tuple[float, float]:
    """
    Get the validity range of the OSF
    """
    start = self._time_model.from_date(
        self._earliest_time,
        ref=TimeRef["UTC"],
        epoch=self._time["epoch"],
        unit=self._time["unit"],
    )
    end = self._time_model.from_date(
        self._latest_time,
        ref=TimeRef["UTC"],
        epoch=self._time["epoch"],
        unit=self._time["unit"],
    )
    return start, end
```

--------------------------------

### Clone ASGARD Project Repositories

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Clones the Git repositories for ASGARD, pyrugged, and orekit-jcc from their GitLab instances. This is the first step for developers who intend to build these projects from source.

```bash
git clone https://gitlab.eopf.copernicus.eu/geolib/asgard.git
git clone https://gitlab.eopf.copernicus.eu/geolib/orekit-jcc.git
git clone https://gitlab.eopf.copernicus.eu/geolib/pyrugged.git
```

--------------------------------

### Run ASGARD Docker Container

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Launches a Docker container with the ASGARD build environment. It mounts local directories and sets environment variables required for building and running ASGARD components. The container runs interactively and is removed upon exit.

```bash
docker run -it --rm --name asgard-legacy --user root --network host -v ~/.gitconfig:/root/.gitconfig2 -v ~/.m2:/root/.m2 -v $root_dir:$root_dir -e asgard_dir -e asgard_legacy_dir -e pyrugged_dir -e ASGARD_DATA registry.eopf.copernicus.eu/geolib/asgard-build-environment bash
```

--------------------------------

### Build Orekit-JCC from Source

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Provides instructions for building the Orekit-JCC wheel package from its source code. This involves cloning the repository, setting the GRAALVM_INSTALL environment variable, and executing a build script. The resulting wheel package is typically found in the 'dist' folder.

```bash
git clone https://gitlab.eopf.copernicus.eu/geolib/orekit-jcc.git
cd orekit-jcc
export GRAALVM_INSTALL=/path/to/graalvm-community-openjdk-17.0.7+7.1
bash ./build_jcc_graalvm.sh
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

This script demonstrates how to create a Python virtual environment using a specific Python version (3.11), activate it, and then upgrade pip. This ensures a clean and isolated environment for project dependencies.

```bash
python3.11 -m venv [VENV_NAME]
source path/to/[VENV_NAME]/bin/activate

pip install --upgrade pip
```

--------------------------------

### Prepare Scaling Configuration

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/sensors/sentinel2/msi

Prepares the scaling configuration, creating a scale vector for the Z-axis.

```python
        # prepare scaling (only for Z)
        scale_vector = np.array([1.0, 1.0, scale], dtype="float64")
        homothety_config = {"homothety": scale_vector}
```

--------------------------------

### Update Bashrc and Install Python Dependencies

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Customizes the bash shell environment within the Docker container by updating the .bashrc file with aliases and then installs necessary Python packages including pytest-xdist, cython, and project-specific packages like Orekit-JCC, SXGEO, pyrugged, and ASGARD.

```bash
# Update bashrc (optionnal)
cat << EOF >> ~/.bashrc
PS1='\u:\W\$ '
grep='grep --color=auto'
ll='ls -alh --color=always'
pytest="pytest -W=ignore::DeprecationWarning:importlib._bootstrap"
EOF

source ~/.bashrc

# Use of git credentials inside docker
cp ~/.gitconfig2 ~/.gitconfig

# Install pytest-xdist in order to run "pytest -n auto" in order to launch unit tests in multi-threads

python3 -m pip install --upgrade pip

pip install pytest-xdist
python3 -m pip install cython

# Add git safe directories
for d in "$asgard_dir" "$asgard_legacy_dir" "$pyrugged_dir"; do
    git config --global --add safe.directory "$d"
done

# Build orekit-jcc
python3 -m pip install path/to/orekit_jcc-*.whl

# Build SXGEO
python3 -m pip install path/to/sxgeo-*.whl

# Build pyrugged
python3 -m pip install $pyrugged_dir # Or install wheel package as orekit-jcc and sxgeo

# Build asgard
python3 -m pip install $asgard_dir

# Build asgard-legacy
cd $asgard_legacy_dir
python3 -m pip install -e . --group dev
```

--------------------------------

### AbstractGeometry Initialization

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/core/product

Initializes the AbstractGeometry class, setting up internal models for orbit, platform, and pointing, as well as default time settings and coordinate predictors. It also validates initialization arguments against a predefined schema.

```python
def __init__(self, **kwargs):
    """
    Constructor

    Initialize empty internal models, axes and coordinates (may be filled by derived classes).
    """
    # initialize empty models (to be replaced by derived classes)
    self.timestamp_models = {}
    self.body_model = None
    self.orbit_model = None
    self.platform_model = None
    self.pointing_model = None
    self.propagation_model = None

    # initialize default time settings (may be overriden by derived classes)
    self.default_time = {
        "ref": "GPS",
        "unit": "d",
        "epoch": "2000-01-01_00:00:00",
    }

    self.predictor: Dict[str, CoordinatePredictor] = {}

    # Axes names to reference the measurement in the product
    self.axes = []
    # accessible coordinates, per geometric unit, and per axis
    self.coordinates = {"default": {}}
    # validate kwargs schema
    schema.validate_or_throw(kwargs, self.init_schema())
    self.config = kwargs
    # Keep this cache for getting altitudes in inverse loc, in order not to rebuild the cache between each calls
    self._cache: Optional[TilesCache] = None
    self._max_cached_tiles = 8  # default value
```

--------------------------------

### Attitude Configuration Example (AOCS Mode)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/core/schema

An example of how to express attitude configuration, specifically highlighting the 'aocs_mode' property with supported values.

```python
{
  "aocs_mode": "GPM|LNP|YSM|ZDOPPLER"
}
```

--------------------------------

### ASGARD Geometries Initialization

Source: https://geolib.pages.eopf.copernicus.eu/asgard/introduction

Demonstrates how to initialize geometry objects for different Sentinel sensors using a configuration dictionary.

```APIDOC
## ASGARD Geometries Initialization

### Description
This section details the initialization process for ASGARD's sensor-specific geometry objects. Each geometry is derived from an `AbstractGeometry` class and is initialized using a custom dictionary containing necessary metadata extracted from product tree metadata files.

### Method
Initialization using constructor with keyword arguments (`**config`).

### Endpoint
N/A (This is a library usage example)

### Parameters
#### Request Body (Configuration Dictionary)
- **sat** (string) - Required - Sentinel mission identifier (e.g., "SENTINEL_3").
- **orbit_aux_info** (object) - Required - Contains orbit state vectors.
    - **orbit_state_vectors** (array) - Required - Array of orbit state vector objects.
        - **times** (object) - Required - Time information for the state vector.
            - **TAI** (object) - Optional - TAI time data.
                - **offsets** (array) - Required - Array of TAI offsets.
            - **UTC** (object) - Optional - UTC time data.
                - **offsets** (array) - Required - Array of UTC offsets.
            - **UT1** (object) - Optional - UT1 time data.
                - **offsets** (array) - Required - Array of UT1 offsets.
        - **positions** (array) - Required - Array of position vectors.
        - **velocities** (array) - Required - Array of velocity vectors.
        - **absolute_orbit** (array) - Required - Array of absolute orbit numbers.
- **dem_config_file** (string) - Required - Path to the Digital Elevation Model configuration file.
- **pointing_vectors** (object) - Required - Pointing vectors.
    - **X** (array) - Required - X component of pointing vectors.
    - **Y** (array) - Required - Y component of pointing vectors.
- **thermoelastic** (object) - Optional - Thermoelastic information.
    - **julian_days** (array) - Required - Julian days.
    - **quaternions_1** (array) - Required - Quaternion component 1.
    - **quaternions_2** (array) - Required - Quaternion component 2.
    - **quaternions_3** (array) - Required - Quaternion component 3.
    - **quaternions_4** (array) - Required - Quaternion component 4.
    - **on_orbit_positions_angle** (array) - Required - On-orbit positions angle.
- **frame** (object) - Required - Frame information.
    - **times** (object) - Required - Time information for the frame.
        - **offsets** (array) - Required - Array of frame time offsets.

### Request Example
```json
{
  "sat": "SENTINEL_3",
  "orbit_aux_info": {
    "orbit_state_vectors": [
      {
        "times": {
            "TAI": {"offsets": np.array([...])},
            "UTC": {"offsets": np.array([...])},
            "UT1": {"offsets": np.array([...])},
        },
        "positions": np.array([...]),
        "velocities": np.array([...]),
        "absolute_orbit": np.array([...]),
      },
    ],
  },
  "dem_config_file": "path_to_dem",
  "pointing_vectors": {
    "X": np.array([...]),
    "Y": np.array([...]),
  },
  "thermoelastic": {
    "julian_days": np.array([...]),
    "quaternions_1": np.array([...]),
    "quaternions_2": np.array([...]),
    "quaternions_3": np.array([...]),
    "quaternions_4": np.array([...]),
    "on_orbit_positions_angle": np.array([...]),
  },
  "frame": {
      "times": {"offsets": np.array([...])},
  }
}
```

### Response
#### Success Response (200)
An initialized geometry object (e.g., `S3OLCIGeometry`).

#### Response Example
```python
from asgard.sensors.sentinel3 import S3OLCIGeometry

# Assuming 'config' is defined as above
my_product = S3OLCIGeometry(**config)
print(type(my_product))
```

```

--------------------------------

### NumpyArrayEncoder Default Method Example

Source: https://geolib.pages.eopf.copernicus.eu/asgard/apidoc/asgard

Provides an example implementation for the `default` method of `NumpyArrayEncoder`, demonstrating how to handle iterable objects for JSON serialization.

```python
def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)
```

--------------------------------

### Schema for Frame and Start Date

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_downloads/c22fad64f70e86131aa3939ef8556256/S2MSIGeometry

Specifies the data types for the reference frame and the start date of a dataset. This helps in defining the coordinate system and temporal boundaries of the data.

```json
{
  "frame": {
    "type": "string"
  },
  "start_date": {
    "type": "string"
  }
}
```

--------------------------------

### Initialize GenericOrbitModel Instance

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/sensors/sentinel2/msi

Initializes the GenericOrbitModel with the prepared model arguments.

```python
# Init the GenericOrbitModel instance
        self.orbit_model = GenericOrbitModel(**model_kwargs)
```

--------------------------------

### Find Second Absolute Orbit Start

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/orbit

Determines the start of the second absolute orbit from a list of absolute orbit indices. Handles cases with insufficient data by searching for the next positive altitude increase.

```python
def _find_second_absolute_orbit_start(self):
    # check if we have at least two absolute orbits
    if len(absolute_orbit_indices) >= 2:
        return absolute_orbit_indices[1]

    # Else: Handle case when we have no absolute_orbit information => search for the 2nd sign increase on Z
    osvs = self._get_osv_samples_in(FrameId.EF)
    i_osvs = list(enumerate(osvs))  # -> zip(index + osv)
    if i_osvs[0][1].getPosition().getZ() < 0:  # unexpected situation, let's ignore the first points
        start = _next_positive_altitude(i_osvs, 0)
    else:  # situation expected
        start = 0
    # search one negative, then next positive
    dnx_idx = _next_negative_altitude(i_osvs, start)
    second_orbit = _next_positive_altitude(i_osvs, dnx_idx)
    return i_osvs[second_orbit][1].getDate()
```

--------------------------------

### Find Start of Second Orbit

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/orbit

Locates the starting point of the second absolute orbit within the cached OSV data. This function relies on the 'absolute_orbit_indices' which map absolute orbit numbers to their corresponding indices in the cached data.

```python
def _start_of_second_orbit(self) -> AbsoluteDate:
        """
        Search the start of the second (absolute) orbit
        """
        if "absolute_orbit" in self.config["orbit"]:
            absolute_orbit_indices = self._cached["absolute_orbit_indices"]
            assert len(

```

--------------------------------

### Configure ASGARD Project Environment Variables

Source: https://geolib.pages.eopf.copernicus.eu/asgard/installation

Sets up essential environment variables for the ASGARD project, defining the locations of the ASGARD, ASGARD-Legacy, and pyrugged directories, as well as the ASGARD data directory. These variables are crucial for the Docker container to locate project files.

```bash
cd $HOME/YOUR/PATH/
export root_dir=$(pwd)
export asgard_dir=$(realpath ./asgard)
export pyrugged_dir=$(realpath ./pyrugged)
export asgard_legacy_dir=$(realpath ./asgard-legacy)
export ASGARD_DATA=$(realpath ./ASGARD_DATA)
```

--------------------------------

### Example of Orbit State Vectors Data

Source: https://geolib.pages.eopf.copernicus.eu/asgard/user_manual

An example of how orbit state vectors data might be structured, including time scales, position, velocity, and absolute orbit arrays. This demonstrates the practical application of the ORBIT_STATE_VECTORS_SCHEMA.

```python
77orbit_aux_info = {
78    "orbit_state_vectors": [
79        {
80        "times": {
81            "TAI": {"offsets": np.array([...])},
82            "UTC": {"offsets": np.array([...])},
83            "UT1": {"offsets": np.array([...])},
84        },
85        "positions": np.array([...]),
86        "velocities": np.array([...]),
87        "absolute_orbit": np.array([...]),
88        },
89    ],
90}
```

--------------------------------

### Initialize Thermoelastic Model and Platform Configuration

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/sensors/sentinel3/olci

Sets up the ThermoelasticModel using orbit information and instrumental data. It inverts the thermoelastic quaternions and splits them for each camera, then appends them to the platform configuration states, including an average state for 'all_cam'.

```python
lut_oop = self.orbit_model.position_on_orbit({"offsets": lut_times})

        # Initialize computations for Sat_to_OLCI_Trans at JD_mid = JD_anx + Torb / 2
        thermoelastic = ThermoelasticModel(
            thermoelastic=kwargs["thermoelastic"],
            doy=(orb_info["utc_anx"] + orb_info["period_jd"] / 2.0) % 365.24,
            instruments=self._instr_list,
            lut_times=lut_times,
            lut_oop=lut_oop,
        )
        # Thermoelastic quaternions are in the direction OLCI_to_S3, but the thermoelastic model
        # already invert them, so we need to invert twice
        thermoelastic = thermoelastic.inv()
        # TODO : or we remove the inversion in ThermoelasticModel
        thermo_map = thermoelastic.split()

        for cam, thermo in thermo_map.items():
            platform_config["states"].append(
                {
                    "name": cam,
                    "origin": "platform",
                    "time_based_transform": thermo,
                }
            )
        # record a special state "all_cam" for the average of thermoelastic effects
        platform_config["states"].append(
            {
                "name": "all_cam",
                "origin": "platform",
                "time_based_transform": thermoelastic,
            }
        )
        self.platform_model = GenericPlatformModel(**platform_config)
```

--------------------------------

### Extend Circular Lookup Table

Source: https://geolib.pages.eopf.copernicus.eu/asgard/apidoc/asgard

Wraps a lookup table (LUT) to ensure full coverage of a specified range [start, end], guaranteeing that the LUT values at the start and end points are identical. Assumes input positions are sorted.

```python
asgard.core.math.extend_circular_lut(_positions_ , _values_ , _start =0_, _end =360_) → Tuple[ndarray, ndarray]
```

--------------------------------

### Filter Leap Seconds within a Time Range

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/time

Filters a list of UTC offsets to include only those within a specified start and end date. It extracts relevant information like seconds, date, and validity start date, formatting them into a list of tuples. Assumes UTC offsets are chronologically sorted.

```python
output = []
for offset in utc_offsets:
    date_offset = offset.getDate()
    if date_offset.isBefore(start_date):
        continue
    if date_offset.isAfter(end_date):
        break
    date = iso_to_legacy(date_offset)
    validity_offset = offset.getValidityStart()
    validity_start = iso_to_legacy(validity_offset)
    output.append((int(offset.getLeap().getSeconds()), date, validity_start))
```

--------------------------------

### Instrument Thermoelastic Model Setup

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/thermoelastic

Iterates through instruments to set up individual thermoelastic models using provided lookup tables and times. It creates a dictionary mapping each instrument to its configured model.

```python
for item in self.instruments:
            sub_model = super().__new__(ThermoelasticModel)
            quat_lut = {item: self.quaternion_lut[item]}
            oop_grid = {item: self.oop_grid[item]}
            sub_model.setup_model(self.pdoy, quat_lut, oop_grid, self.lut_times, self.lut_oop)
            output[item] = sub_model
        return output
```

--------------------------------

### Get States List

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/platform

Retrieves a list of all defined states within the GenericPlatformModel.

```APIDOC
## GET /api/states

### Description
Retrieves a comprehensive list of all states defined within the GenericPlatformModel.

### Method
GET

### Endpoint
/api/states

### Parameters
None

### Response
#### Success Response (200)
- **states** (array) - A list of state names.

#### Response Example
```json
{
  "states": ["state1", "state2", "state3"]
}
```
```

--------------------------------

### Setup Model in ThermoelasticModel (Python)

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/thermoelastic

Initializes the ThermoelasticModel with provided data including DOY, quaternions, OOR grid, and LUT times. This method stores the input parameters as instance attributes.

```Python
    def setup_model(
        self,
        pdoy,
        quaternion_lut,
        oop_grid,
        lut_times,
        lut_oop,
    ):
        """
        Record the computed input into the model
        """
        self.pdoy = pdoy
        self.quaternion_lut = quaternion_lut
        self.oop_grid = oop_grid
        self.lut_times = lut_times
        self.lut_oop = lut_oop

```

--------------------------------

### Get States Link

Source: https://geolib.pages.eopf.copernicus.eu/asgard/_modules/asgard/models/platform

Generates a graph representing the links and transformations between different states.

```APIDOC
## GET /api/states/links

### Description
Creates and returns a graph that illustrates the connections and transformations between various defined states.

### Method
GET

### Endpoint
/api/states/links

### Parameters
None

### Response
#### Success Response (200)
- **links** (array) - A list of state link objects, each containing 'name', 'origin', and 'transform' details.
- **graph** (object) - An adjacency list representation of the state connections.

#### Response Example
```json
{
  "links": [
    {
      "name": "state_a",
      "origin": "state_b",
      "transform": {"type": "RigidTransform", "translation": [0, 0, 0], "rotation": [0, 0, 0, 1]}
    }
  ],
  "graph": {
    "state_a": ["state_b"],
    "state_b": ["state_a"]
  }
}
```
```
Tokens:
Raw