Python SDK

Latest releases: S2DR3 s2dr3-20261012 and S2DR4 s2dr4-20261014

The Python SDK runs two Gamma Earth models on your own GPU: S2DR3, which super-resolves a Sentinel-2 image to 1 m per pixel, and S2DR4, which does the same and also removes the clouds by combining several recent images of the same area. Both use the same API key and the same credits.

Changelog

S2DR4, release s2dr4-20261014.1

• S2DR4 now uses your API key and credits, at the same price as S2DR3 and from the same balance. An API key is required.
• Credits are reserved when the run starts and returned if it fails. Running the same area for the same date again with the same key is free.
• Clear messages instead of an error code or list index out of range when a job is refused or there are not enough usable images.
• The run prints the images it used and the credits reserved.
• A new preview page for S2DR4 results.
• A newer-version notice: when a newer wheel exists, the run prints the install command. It starts to appear with the release after this one.

S2DR3, release s2dr3-20261012.1

• The image is chosen by Gamma Earth, the same way as in the API. Earlier wheels chose the image on your computer (the clearest, with a soft cloud limit) and --date was described as an exact scene date. Now --date is the target date and the rule in How the Image Is Chosen applies. By default you still get the clearest image of the period; the difference is that equally clear images go to the one closest to your date.
• --max_clouds is a strict limit. Before, if no image met the limit the run silently used a cloudier one. Now the run stops and explains.
• Clear messages when a job is refused (no image, not enough credits, invalid key, invalid value), instead of a status code followed by an unrelated error.
• The run prints the image used (date and cloud cover over the AOI) and the credits reserved.
• Credits: reserved when the run starts, charged on completion, returned on failure; repeating the same area and image date with the same API key is free.
• Newer-version notice: when a newer wheel exists, the run prints the install command (in Colab, with a reminder to restart the runtime). It starts to appear with the release after this one.
• Failed uploads are reported instead of being hidden.
• Public Colab demo: no longer sets a cloud limit.

The wheels are built for Python 3.13 (cp313). Earlier S2DR3 releases are listed under Old Versions.

Requirements

• Linux (x86, x64).
• Python 3.13 or later.
• NVIDIA GPU tested by Gamma Earth: T4, P100, V100, or A100. S2DR4 has been tested on the T4 of Google Colab.
• 16 GB VRAM.
• 16 GB RAM minimum; 32 GB RAM preferred.
• A Gamma Earth API key with credits. See API Access & Keys.

Install the SDK

Install GDAL, then the wheel of the model you use (or both):

apt install -qq pip gdal-bin
pip -q install https://storage.googleapis.com/0x7ff601307fa5/s2dr3-20261012.1-cp313-cp313-linux_x86_64.whl
pip -q install https://storage.googleapis.com/0x7ff601307fa5/s2dr4-20261014.1-cp313-cp313-linux_x86_64.whl

If you already use an earlier wheel, run the pip line again. Your existing infer.py keeps working without changes.

Set Up the Script

Each model has its own script, sent to you with your SDK access: infer.py for S2DR3 and infer_s2dr4.py for S2DR4. In both, the API key is read from GE_API_KEY: either set the environment variable, or write your key in the line near the top of the script.

For infer.py, set the key and the default paths for input data, output data and logs:

os.environ['GE_API_KEY'] = <YOUR-API-KEY>

parser.add_argument("--datapath", type=str, default="/home/ubuntu/data/datapath", help="Input image or folder")
parser.add_argument("--savepath", type=str, default="/home/ubuntu/data/savepath", help="Output image or folder")
parser.add_argument("--logpath", type=str, default="/home/ubuntu/data/logs", help="Path for logging")

Sentinel-2 data is downloaded automatically to datapath. infer_s2dr4.py takes the same three paths as options (see Parameters).

Run GPU Inference

S2DR3:

cd <path-to-the-infer.py>
python infer.py -f --date <YYYY-MM-DD> --aoi <W S E N>

Example:

python infer.py -f --date 2024-01-31 --date_range 30 --aoi -74.165 4.690 -74.125 4.715

When the job starts, the run prints the image that was chosen and the credits used, for example:

Image date: 20240118, 1% cloud cover over the AOI
Credits reserved: 8 (992 left)

S2DR4:

python infer_s2dr4.py --date <YYYY-MM-DD> --aoi <W S E N>
python infer_s2dr4.py --date <YYYY-MM-DD> --lonlat <LON LAT> --radius 2

Example:

python infer_s2dr4.py --date 2025-04-01 --aoi 123.7075 13.1279 123.7445 13.1641

The run prints the credits reserved and the dates of the images it combined:

Credits reserved: 9 (351 left)
Images used: 20250302, 20250312, 20250314, 20250327, 20250401

You can also call the models from Python. The demo functions are the ones the public notebooks run:

import s2dr3.inferutils
s2dr3.inferutils.test((-74.145, 4.703), '2024-01-31')

import s2dr4.inferutils
s2dr4.inferutils.test(lonlat=(121.9058, 17.2165), date='2025-04-01')

On Google Colab the API key is the Colab secret GE_API_KEY.

How the Image Is Chosen

S2DR3 uses one image, chosen by Gamma Earth with the same rule as in the API and the other tools. Gamma Earth looks at the Sentinel-2 images from --date_range days before --date up to 3 days after it, with cloud cover measured over your AOI:

If no image qualifies, the run stops and prints the reason. Nothing is charged.

S2DR4 chooses its own images; there is no --date_range or --max_clouds. It looks at the Sentinel-2 images of the 180 days before the target date (and up to 3 days after it), measures the cloud cover over your area, leaves out the images with 99% cloud or more, and takes the most recent of the rest. Up to 5 images are aligned to the clearest one and combined by the model, which removes the clouds from the most recent image. If fewer than 5 can be used, the run stops and says why.

Parameters

Used by both scripts:

Only S2DR3 (infer.py):

Only S2DR4 (infer_s2dr4.py):

Options of infer.py:

Credits

Each run uses credits from the balance of your API key, from the same balance for S2DR3 and S2DR4 and at the same price. The amount depends on the area of your AOI and its region; see How Credits Work.

• The job is registered before any data is downloaded, so a refusal costs neither credits nor time.
• Credits are reserved when the run starts, charged when it completes and returned if it fails.
• Running the same area for the same date again with the same API key is free, for each model separately: an S2DR3 run never makes an S2DR4 run free, or the other way round. The run prints No credits charged in that case. For S2DR3 the date is that of the image used; for S2DR4 it is the date you requested.
• If your balance is not enough, the run stops with Not enough credits: this job needs N credits and you have M.

Results

The products are written to --savepath. The file name starts with S2L2Ax10_ for S2DR3 and S2L3Ax10_ for S2DR4:

The multispectral band order is B02, B03, B04, B05, B06, B07, B08, B8A, B11 and B12. At the end of a run with a preview (always for S2DR4, with the -p option for S2DR3), the script prints a link where you can view the result on a map.

When a Run Stops

When something prevents the run, it stops with a short message from Gamma Earth, in a line that starts with ERROR:.

Old Versions

Articles for earlier releases of the SDK, kept for reference:

• s2dr3-20260907
• s2dr3-20260903
• s2dr3-20260827