Contents

Installation

Installation

This tutorial guides you through the steps to install and set up GEOGEN on your local computer. Alternatively, we can skip installation and configuration and use GEOGEN on the Training JupyterHub.

Software requirements

You need a computer environment where the following software are already installed.

  • Conda (required to manage Python packages, dependencies and environment)

  • Git (required to download and update the psa_geo and tamn software packages)

  • Docker (required to install and run the TAMN server application)

Known working environments

  • OS: OS X, Linux

  • CPU: 64bit

Note

You will also need read access to the psa_geo and tamn Bitbucket repositories. If you don’t, please contact the ESA SPICE Service.

Deployment environments

  • PSA testing environment

  • PSA operational environment

  • Your local environment

  • Training JupyterHub

Steps

1. Create your working directory

Create a directory which will contain the psa_geo package, your local configuration and data files (input PLF files, addendum kernels, and output Coverage GeoJSON and B3F files), and from which you will run the geogen script. For example:

mkdir -p {/path/to}/geogen

2. Create and activate your virtual environment

conda create --name geogen python=3.7
conda activate geogen

3. Download and install psa_geo package

To download (or update) the psa_geo package, you need read access to the psa_geo Bitbucket repository. You will be asked to input your username and password.

Clone the latest master (operational) version in your local working directory:

cd {/path/to}/geogen
git clone https://repos.cosmos.esa.int/socci/scm/spice/psa_geo.git

Or clone a specific branch or tag (version), for example:

git clone --branch v5.0.0-rc1 https://repos.cosmos.esa.int/socci/scm/spice/psa_geo.git
git clone --branch dev https://repos.cosmos.esa.int/socci/scm/spice/psa_geo.git

Then, install package:

pip install --editable psa_geo

Quickly test that installation was successfull by checking the GEOGEN version:

$ geogen --version
geogen, version 5.0.0rc2

Looks OK? Nice.

4. Install and run TAMN

Now, install TAMN from your working directory:

cd {/path/to/}geogen
git clone https://repos.cosmos.esa.int/socci/scm/spice/tamn.git
cd tamn
./deploy

If everything goes well, the installation process should end with the following message:

[INFO] Tamn server running on port 3333

If your go to http://localhost:3333, you should see the following message:

{"message":"Welcome to The AntiMeridian Nightmare server"}

Note

Alternatively you can rely on the ESAC TAMN server instance if you use your computer within ESAC secured network (see 6. Set environment variables and init script).

5. Download SPICE kernels

The psa_geo package doesn’t contain mission SPICE kernels. If you don’t already have them on your local environment, you must download them from the ESA’s SPICE Service Bitbucket SPICE Kernels repositories.

Choose of a top-level location for all your mission ESA’s SPICE Kernels Datasets (SKD), for example: {/path/to}/spice_kernels. You will later set the required ESA_SPICE_KERNELS environment variable to this location.

Create your SPICE kernels directory and download the mission SKDs of your choice:

mkdir -p {/path/to}/spice_kernels
cd {/path/to}/spice_kernels

git clone --depth 1 https://repos.cosmos.esa.int/socci/scm/spice_kernels/mars-express.git
git clone --depth 1 https://repos.cosmos.esa.int/socci/scm/spice_kernels/rosetta.git
git clone --depth 1 https://repos.cosmos.esa.int/socci/scm/spice_kernels/exomars2016.git
git clone --depth 1 https://repos.cosmos.esa.int/socci/scm/spice_kernels/bepicolombo.git

Note

The --depth 1 option allows you to only download the latest version of a repository, and therefore reduce the required disk space in your local environment.

Alternatively you can download SKDs as a .zip file which contains the same kernels as the BitBucket repository and the download might be faster than the git clone. For example:

6. Set environment variables and init script

Copy the init_geogen.sh script from the psa_geo package into your working directory:

cd {/path/to}/geogen
cp psa_geo/init_geogen.sh .

Edit your init_geogen.sh script to update the values of the required ESA_SPICE_KERNELS and TAMN_URL environment variables. Example:

#!/bin/bash

# Activate GEOGEN conda environment.
#
conda activate geogen

# Set path to the parent directory containing the ESA's SPICE Kernels Datasets (SKDs)
# download/updated from https://repos.cosmos.esa.int/socci/scm/spice_kernels/.
#
export ESA_SPICE_KERNELS=/Users/nmanaud/workspace/git-repos/spice_kernels/

# Set TAMN API end-point URL (default is http://localhost:3333/ when not set)
#
#export TAMN_URL='http://psaintdocker.n1vs.lan:3333/'

Run your init_geogen.sh script:

source init_geogen.sh

Note

You must run the init_geogen.sh script everytime you start a GEOGEN session.

7. Setup your data directory

Create your data directory in your working directory:

cd {/path/to}/geogen
mkdir data

Copy the content psa_geo package PLF data subdirectory into your data directory to start off with some PLF examples that you can modify:

cp -r psa_geo/data/plf data

The other geojson, b3f and log data subdirectories will be automatically created and populated when running computations.

8. Check your configuration

Run the GEOGEN config command from your working directory to quickly check that it is configured as expected:

geogen config

In this example, our working directory is /Users/nmanaud/workspace/geogen, ESA’s mission SPICE kernels top-level directory is /Users/nmanaud/workspace/git-repos/spice_kernels/ and we use TAMN local web application instance.

Config file: /Users/nmanaud/workspace/geogen/psa_geo/psa_config.json
ESA SPICE Kernels: /Users/nmanaud/workspace/git-repos/spice_kernels/
TAMN URL: http://localhost:3333/ [OK]
Directories:
  B3F:      /Users/nmanaud/workspace/geogen/data/b3f/
  GEOJSON:  /Users/nmanaud/workspace/geogen/data/geojson/
  LOG:      /Users/nmanaud/workspace/geogen/data/log/
  ADDENDUM: /Users/nmanaud/workspace/geogen/psa_geo/data/addendum/

Missions: ['MEX', 'ROSETTA', 'TGO', 'S1', 'VEX']

Note

GEOGEN does not check the existence of ESA’s mission SPICE kernels directories.

Congratulation if you made it up to here!

previous

Troubleshooting

next

Getting started