Installation#

Prerequisites#

Operating System:

  • Linux (RedHat and Debian flavors officially supported)

  • MacOS (Not officially supported)

  • Windows with WSL2 (Not officially supported)

Python version 3.11 or higher. We recommend using Mamba, Miniconda, or Anaconda to manage your python environment, but any Python 3.11+ installation should work. Please see the system requirements for more information.

Installing from Pypi#

The simplest way to install GeoIPS is using pip to install from PyPI.

   pip install geoips

If you have difficulty with pip installation, please see the troubleshooting section at the end of this page.

Environment Setup#

GeoIPS requires a minimum of two environment variables to be set. There are a number of other environment variables that control other features of GeoIPS, but GEOIPS_OUTDIRS and GEOIPS_TESTDATA_DIR are required.

GEOIPS_OUTDIRS tells GeoIPS where it should store output files including final products as well as cache files used to reduce recomputation of commonly used variables like geostationary geolocation data.

GEOIPS_TESTDATA_DIR tells GeoIPS where to download and look for test data.

It is important to choose a location that has sufficient space. Unfortunately, “sufficient” differs based on your use case. Please see the system requirements for more information.

   export GEOIPS_OUTDIRS=$HOME/geoips_output
   export GEOIPS_TESTDATA_DIR=$HOME/geoips_test_data
   mkdir -p $GEOIPS_OUTDIRS $GEOIPS_TESTDATA

Tip

These environment variables can be persisted either by adding them to your shell environment (e.g. .bashrc) or by adding them to your conda environment using conda env config vars set GEOIPS_OUTDIRS=$HOME/geoips_output.

Testing Your Installation#

There are a number of test datasets available for GeoIPS. The test below downloads some calibrated level-1 data from GOES-18 ABI, then attempts to produce an infrared imagery over the continental United States.

   geoips config install test_data_abi

   geoips run single_source \
       $GEOIPS_TESTDATA_DIR/test_data_abi/data/goes16_20200918_1950/OR_ABI-L1b-RadF-M6C* \
       --reader_name abi_netcdf \
       --product_name Infrared \
       --output_formatter imagery_annotated \
       --sector_list conus

The end of the output should appear as below. The final line should display Return value: 0.

   # Truncated log output from the script run
   .......
   11_191109    log_setup.py:162  INTERACTIVE: SINGLESOURCESUCCESS ${GEOIPS_OUTDIRS}/preprocessed/annotated_imagery/NorthAmerica-UnitedStates-Continental/x-x-x/Infrared/abi/20200918.195020.goes-16.abi.Infrared.conus.97p12.noaa.3p0.png
   11_191109    log_setup.py:162  INTERACTIVE: READER_NAME: abi_netcdf
   11_191109    log_setup.py:162  INTERACTIVE: PRODUCT_NAME: Infrared
   11_191109    log_setup.py:162  INTERACTIVE: NUM_PRODUCTS: 1
   11_191109    log_setup.py:162  INTERACTIVE: NUM_DELETED_PRODUCTS: 0
   11_191109    log_setup.py:162  INTERACTIVE: Completed geoips PROCFLOW single_source processing, done!
   11_191109    log_setup.py:162  INTERACTIVE: Total time: 0:00:24.911853
   11_191109    log_setup.py:162  INTERACTIVE: Return value: 0

Troubleshooting#

The most common installation issue is caused by inconsistent libraries. To resolve this, we recommend installing the following packages using conda from the conda-forge channel:

  • xarray

  • netcdf4

  • h5py

  • pyhdf

   conda install -c conda-forge xarray netcdf4 h5py pyhdf

Other installation issues (e.g. dependency, architecture, or OS issues) may be solved by cloning the GeoIPS git repository and installing in editable mode from source.

    git clone https://github.com/NRLMMD-GEOIPS/geoips.git
    cd geoips
    pip install -e .

If you continue having difficulties, please open an issue on the GEOIPS GitHub repository.