Metadata-Version: 2.1
Name: sentinel_downloader
Version: 2.0.1
Summary: A Python package for downloading and processing Sentinel satellite images.
Author-email: Pedro Vaz de Moraes Pertusi <pedrovazpertusi@gmail.com>, João Lucas de Moraes Cadorniga <joaolucasmbcadorniga@gmail.com>, Eduardo Mendes Vaz <emendesvaz@gmail.com>, Alexandre Magno Maciel dos Santos <alemagno03@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/JoaoLucasMBC/open-flood.git
Project-URL: Repository, https://github.com/JoaoLucasMBC/open-flood.git
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aenum
Requires-Dist: affine
Requires-Dist: attrs
Requires-Dist: bqplot
Requires-Dist: branca
Requires-Dist: cachetools
Requires-Dist: certifi
Requires-Dist: charset-normalizer
Requires-Dist: click
Requires-Dist: click-plugins
Requires-Dist: cligj
Requires-Dist: colour
Requires-Dist: comm
Requires-Dist: contourpy
Requires-Dist: cycler
Requires-Dist: dataclasses-json
Requires-Dist: decorator
Requires-Dist: earthengine-api
Requires-Dist: eerepr
Requires-Dist: exceptiongroup
Requires-Dist: executing
Requires-Dist: folium
Requires-Dist: fonttools
Requires-Dist: future
Requires-Dist: geemap
Requires-Dist: geocoder
Requires-Dist: google-api-core
Requires-Dist: google-api-python-client
Requires-Dist: google-auth
Requires-Dist: google-auth-httplib2
Requires-Dist: google-cloud-core
Requires-Dist: google-cloud-storage
Requires-Dist: google-crc32c
Requires-Dist: google-resumable-media
Requires-Dist: googleapis-common-protos
Requires-Dist: httplib2
Requires-Dist: idna
Requires-Dist: ipyevents
Requires-Dist: ipyfilechooser
Requires-Dist: ipyleaflet
Requires-Dist: ipython
Requires-Dist: ipytree
Requires-Dist: ipywidgets
Requires-Dist: jedi
Requires-Dist: Jinja2
Requires-Dist: jupyter-leaflet
Requires-Dist: jupyterlab_widgets
Requires-Dist: kiwisolver
Requires-Dist: MarkupSafe
Requires-Dist: marshmallow
Requires-Dist: matplotlib
Requires-Dist: matplotlib-inline
Requires-Dist: mypy-extensions
Requires-Dist: numpy
Requires-Dist: oauthlib
Requires-Dist: packaging
Requires-Dist: pandas
Requires-Dist: parso
Requires-Dist: pexpect
Requires-Dist: pillow
Requires-Dist: plotly
Requires-Dist: prompt_toolkit
Requires-Dist: proto-plus
Requires-Dist: protobuf
Requires-Dist: ptyprocess
Requires-Dist: pure_eval
Requires-Dist: pyasn1
Requires-Dist: pyasn1_modules
Requires-Dist: Pygments
Requires-Dist: pyparsing
Requires-Dist: pyperclip
Requires-Dist: pyproj
Requires-Dist: pyshp
Requires-Dist: python-box
Requires-Dist: python-dateutil
Requires-Dist: python-dotenv
Requires-Dist: pytz
Requires-Dist: rasterio
Requires-Dist: ratelim
Requires-Dist: requests
Requires-Dist: requests-oauthlib
Requires-Dist: rsa
Requires-Dist: scooby
Requires-Dist: sentinelhub
Requires-Dist: shapely
Requires-Dist: six
Requires-Dist: stack-data
Requires-Dist: tenacity
Requires-Dist: tifffile
Requires-Dist: tomli
Requires-Dist: tomli_w
Requires-Dist: tqdm
Requires-Dist: traitlets
Requires-Dist: traittypes
Requires-Dist: typing-inspect
Requires-Dist: typing_extensions
Requires-Dist: tzdata
Requires-Dist: uritemplate
Requires-Dist: urllib3
Requires-Dist: utm
Requires-Dist: wcwidth
Requires-Dist: widgetsnbextension
Requires-Dist: xyzservices

# Sentinel Downloader
A Python API for downloading and processing Sentinel satellite images efficiently. **It can be used both as a python package and through Docker**.

![sentinel-downloader](https://badge.fury.io/py/sentinel-downloader.svg)

## Table of Contents
1. [Package Installation](#package-installation)
2. [Docker Setup](#docker-setup)
3. [Credential Setup](#credential-setup)
4. [Usage and Features](#usage-and-features)
5. [API Reference](#api-reference)
6. [Contributing](#contributing)
7. [License](#license)

## Package Installation
This section explains how to setup Sentinel Downloader as a python package. If you would rather setup to use it with Docker, go [here](#docker-setup)

Before using the `sentinel-downloader` package, follow these steps to set up a Python environment and install the package.

### 1. Set Up a Virtual Environment (Recommended)
It’s a good practice to create an isolated environment for your project to avoid conflicts with other packages. Here’s how you can do it using `venv` or `mamba`/`conda`:

#### Using `venv` (Python's built-in virtual environment):
```bash
# Create a virtual environment (python3 for Unix-like systems, python for Windows)
python3 -m venv sentinel-downloader-env

# Activate the environment:
# On macOS/Linux:
source sentinel-downloader-env/bin/activate
# On Windows:
sentinel-downloader-env\Scripts\activate

# Upgrade pip
pip install --upgrade pip
```
#### Using `mamba` or `conda`:
```bash
# Create a new environment with Python 3.x
mamba create -n sentinel-downloader-env python=3.x
# or use conda if you're not using mamba:
# conda create -n sentinel-downloader-env python=3.x

# Activate the environment
mamba activate sentinel-downloader-env
```

### 2. Install the `sentinel-downloader` Package:
After setting up your virtual environment, install the sentinel-downloader package using pip:
```bash:
pip install sentinel-downloader
```

## Docker Setup
This section explains how to setup Sentinel Downloader with Docker. If you would rather setup to use it as a package, go [here](#package-installation)

**You need to have [docker](https://docs.docker.com/get-started/get-docker/) installed to use Sentinel Downloader with Docker**.

### 1. Build the Docker Image
First, clone the repository:
```bash
# Clone the repository
git clone git@github.com:JoaoLucasMBC/open-flood.git
```

Once in the root of the cloned repository, navigate to the directory containing the Dockerfile, and then create the docker image:
```bash
cd sentinel-downloader

docker build -t sentinel-downloader:latest .
```

## Credential Setup
Sentinel Downloader improves upon two existing Sentinel Satellite Imagery collecting APIs: sentinelhub-py and earth-engine, 
and therefore you will need to obtain the credentials needed to make requests using these APIs to use it.

### Sentinel 1 - Earth Engine
If you only want to collect Sentinel 1 imagery, you only need to follow the steps described in this section.

-- TODO: ee credentials

### Sentinel 2 - SentinelHub
If you only want to collect Sentinel 1 imagery, you only need to follow the steps described in this section.

-- TODO: sentinelhub credentials

## Usage and Features
Once tou have all setup, you can use Sentinel Downloader by creating a `config.json` file on the same 
directory of the Dockerfile (if you are using it with Docker) or the same file where you will import the package, where you will input the arguments for the image downloading.

### Arguments received by the API
This `config.json` contains the arguments for image downloading. The arguments are as follows:

#### `satellite`
- **Description**: The satellite choosen for image downloading.
- **Type**: `string` in `[sentinel1, sen1, s1]` for only Sentinel 1 images, in `[sentinel2, sen2, s2]` for only Sentinel 2 images, or `both` for both satellites.
- **Required**: Yes
- **Example**: `"both"`

#### `coords`
- **Description**: The bounding box of coordinates that define the area from which you want to download images. If the bounding box is to big, it will be divided automatically
  into images of the size defined in `resolution`.
- **Type**: `tuple` of format `"(nw-lat, nw-lon, se-lat, se-lon)"`.
- **Required**: Yes
- **Example**: `"(-29.971442, -51.245041, -29.8334607725, -51.1070597725)"`

#### `time_interval`
- **Description**: The start and end dates for the interval in which images will be collected.
- **Type**: `tuple` of format `'("YYYY-MM-DD", "YYYY-MM-DD")'` where the first date is the starting date of the interval, and the second, the end date.
- **Required**: Yes
- **Example**: `"('2024-04-30', '2024-05-10')"`

#### `resolution`
- **Description**: The size of the images in pixels.
- **Type**: `integer` in `[128, 256, 512]` for Sentinel 1 or `[128, 256, 512, 1024, 2048]` for Sentinel 2. If you are collecting images from both satellites at the same time, the 
  resolution must fit both satellites, which means only the avaiable resolutions for Sentinel 1 are valid.
- **Required**: No
- **Default**: `512`
- **Example**: `512`

#### `save_dir`
- **Description**: The name of the directory created inside `output` to save the images.
- **Type**: any `string`.
- **Required**: No
- **Default**: The exact timestamp when the code was ran.
- **Example**: `canoas-images`

#### `filename`
- **Description**: The prefix of all files saved by Sentinel Downloader. It will be used to save images by their tiles (e.g. <filename>_0_0.png, <filename>_3_3.png)
- **Type**: any `string`.
- **Required**: No
- **Default**: `"file"`
- **Example**: `"canoas_images"`

#### `evalscript` (EXCLUSIVE TO SENTINEL 2)
- **Description**: Custom scripts to highlight specific pixels based on classifications provided by sentinelhub. The pixels are then painted with a representative color.
- **Type**: `string` in `["rgb", "water", "vegetation", "urban", "water"]`.
- **Required**: No
- **Default**: `"rgb"`
- **Example**: `"rgb"`

The evalscript paints over the classified pixels to highlight them:

--TODO: put images of evalscript being used


#### `cloud_removal` (EXCLUSIVE TO SENTINEL 2)
- **Description**: Usage of a script developed for Sentinel Downloader that chooses the least cloud obstructed image in the time interval selected.
- **Type**: `boolean` between `true`or `false`
- **Required**: No
- **Default**: `false`
- **Example**: `true`

The difference between the image returned by the API with and without the cloud removal script:

--TODO: put comparision of cloud obstructed image and clear image

### Example config.json file
An example of how your config.json file should look like is as follows:
```json
{
    "satellite": "both",
    "coords": "(-29.8334607725, -51.245041, -29.971442, -51.1070597725)",
    "time_interval": "('2024-04-30', '2024-05-10')",
    "save_dire": "canoas",
    "filename": "canoas_image",
    "evalscript": "vegetation",
    "cloud_removal": true
}
```

