Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme (installation section) #740

Merged
merged 7 commits into from
Sep 6, 2023
Merged
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 59 additions & 46 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,48 +35,33 @@ to use any of the available tasks and is encouraged to improve the, develop new

## Package Overview

**`eo-learn`** is divided into several subpackages according to different functionalities and external package dependencies. Therefore it is not necessary for user to install entire package but only the parts that he needs.
**`eo-learn`** package is structured into several modules according to different functionalities. Some modules contain extensions under the `extra` subfolder. Those modules typically require additional package dependencies which don't get installed by default, since they are usually very specific to the task.

At the moment there are the following subpackages:
The modules are:

- **`eo-learn-core`** - The main subpackage which implements basic building blocks (`EOPatch`, `EOTask` and `EOWorkflow`) and commonly used functionalities.
- **`eo-learn-coregistration`** - The subpackage that deals with image co-registration.
- **`eo-learn-features`** - A collection of utilities for extracting data properties and feature manipulation.
- **`eo-learn-geometry`** - Geometry subpackage used for geometric transformation and conversion between vector and raster data.
- **`eo-learn-io`** - Input/output subpackage that deals with obtaining data from Sentinel Hub services or saving and loading data locally.
- **`eo-learn-mask`** - The subpackage used for masking of data and calculation of cloud masks.
- **`eo-learn-ml-tools`** - Various tools that can be used before or after the machine learning process.
- **`eo-learn-visualization`** - Visualization tools for core elements of eo-learn.
- **`core`** - The main module which implements basic building blocks (`EOPatch`, `EOTask` and `EOWorkflow`) and commonly used functionalities.
- **`coregistration`** - Tasks which deal with image co-registration.
- **`features`** - A collection of utilities for extracting data properties and feature manipulation.
- **`geometry`** - Geometry-related tasks used for transformation and conversion between vector and raster data.
- **`io`** - Input/output tasks that deal with obtaining data from Sentinel Hub services or saving and loading data locally.
- **`mask`** - Tasks used for masking of data and calculation of cloud/snow/other masks.
- **`ml-tools`** - Various tools that can be used before or after the machine learning process.
- **`visualization`** - Visualization tools for the core elements of eo-learn.

## Installation

### PyPi distribution

The package requires Python version **>=3.8** . It can be installed with:
### Requirements

```bash
pip install eo-learn
```

In order to avoid heavy package dependencies it is possible to install each subpackage separately:

```bash
pip install eo-learn-core
pip install eo-learn-coregistration
pip install eo-learn-features
pip install eo-learn-geometry
pip install eo-learn-io
pip install eo-learn-mask
pip install eo-learn-ml-tools
pip install eo-learn-visualization
```
#### Linux / Mac OS

Before installing `eo-learn` on **Linux** it is recommended to install the following system libraries:
mlubej marked this conversation as resolved.
Show resolved Hide resolved

```bash
sudo apt-get install gcc libgdal-dev graphviz proj-bin libproj-dev libspatialindex-dev
```

#### Windows

Before installing `eo-learn` on **Windows** it is recommended to install the following packages from [Unofficial Windows wheels repository](https://www.lfd.uci.edu/~gohlke/pythonlibs/):

```bash
Expand All @@ -86,9 +71,49 @@ shapely
fiona
```

One of dependencies of `eo-learn-mask` subpackage is `lightgbm` package. On Windows it requires 64 bit Python distribution. If having problems during installation please check [LightGBM installation guide](https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html).
One of the `[MASK_EXTRA]` dependencies is the `lightgbm` package. On Windows it requires 64 bit Python distribution. If having problems during installation please check [LightGBM installation guide](https://lightgbm.readthedocs.io/en/latest/Installation-Guide.html).

### PyPi distribution

The package requires Python version **>=3.8** . If this is your first time installing `eo-learn`, or you aren't sure what kind of installation you require, then you can safely install it with:

```bash
pip install "eo-learn[ALL]"
```

To better control your dependencies, you can install just the core dependencies of `eo-learn` with:

Some subpackages contain extension modules under `extra` subfolder. Those modules typically require additional package dependencies which don't get installed by default.
```bash
pip install eo-learn
```

Alternatively, you can decide for yourself which modules you want to be operational by providing the corresponding extras. E.g., if you are only interested in the `io` and `mask` modules, or in the extra dependencies of the `features` module, you can install them with:

```bash
pip install "eo-learn[IO, MASK]"
pip install "eo-learn[FEATURES_EXTRA]"
```

Here is a full list of all the modules' dependencies and their extras:

- `COREGISTRATION`
- `FEATURES`
- `FEATURES_EXTRA`
mlubej marked this conversation as resolved.
Show resolved Hide resolved
- `GEOMETRY`
- `IO`
- `MASK`
- `MASK_EXTRA`
- `MLTOOLS`
- `VISUALIZATION`

We also provide a few collections of dependencies:

- `ALL` for installing the basic dependencies without extras
- `FULL` for installing every dependency, including the extras
- `RAY` for installing ray and its dependencies
- `ZARR` for installing the zarr functionality for chunked timestamp saving/loading.
- `DOCS` for developers, dependencies for building docs
- `DEV` for developers, dependencies for testing and contributing

### Conda Forge distribution

Expand All @@ -99,23 +124,9 @@ be installed using `conda-forge` as follows:

```bash
conda config --add channels conda-forge

conda install eo-learn
```

In order to avoid heavy package dependencies it is possible to install each subpackage separately:

```bash
conda install eo-learn-core
conda install eo-learn-coregistration
conda install eo-learn-features
conda install eo-learn-geometry
conda install eo-learn-io
conda install eo-learn-mask
conda install eo-learn-ml-tools
conda install eo-learn-visualization
```

### Run with Docker

A docker image with the latest released version of `eo-learn` is available at [Docker Hub](https://hub.docker.com/r/sentinelhub/eolearn). It provides a full installation of `eo-learn` together with a Jupyter notebook environment. You can pull and run it with:
Expand Down Expand Up @@ -145,7 +156,9 @@ For more information on the package content, visit [readthedocs](https://eo-lear

## More Examples

Examples and introductions to the package can be found [here](https://github.com/sentinel-hub/eo-learn/tree/master/examples). A large collection of examples is available at the [`eo-learn-examples`](https://github.com/sentinel-hub/eo-learn-examples) repository. While the examples there are not always up-to-date they can be a great source of ideas.
Examples and introductions to the package can be found [here](https://github.com/sentinel-hub/eo-learn/tree/master/examples). A larger collection of examples is available at the [`eo-learn-examples`](https://github.com/sentinel-hub/eo-learn-examples) repository. While the examples there are not always up-to-date they can be a great source of ideas.
mlubej marked this conversation as resolved.
Show resolved Hide resolved

In the past, `eo-learn` served as a collection of many useful tasks, originating from various contributors or projects. In order to keep `eo-learn` light and easy to maintain, we have decided to move these specific tasks to [`eo-learn-examples/extra-tasks`](https://github.com/sentinel-hub/eo-learn-examples/tree/main/extra-tasks), .

## Contributions

Expand Down