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.

Sign up for GitHub

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

Jump to bottom

Update readme (installation section) #740

Merged
merged 7 commits into from
Sep 6, 2023
Merged

Update readme (installation section) #740

Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
194792f
updates to the eo-learn readme
Sep 5, 2023
594e5e4
readme improvements
Sep 5, 2023
2cbb03d
update extra dependency list, mention extra-tasks in eo-learn-examples
Sep 5, 2023
e915a81
Update README.md
Sep 6, 2023
b8f5645
resolve review comments
Sep 6, 2023
508ccaa
remove brackets
Sep 6, 2023
6d872e8
shorten list
Sep 6, 2023
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
93 changes: 47 additions & 46 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,47 +35,31 @@ 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:

```bash
pip install eo-learn
```
### Requirements

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/):

Expand All @@ -86,9 +70,38 @@ 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, than feel free to install it 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[ALL]"
```

This will install the package and all the default modules. Otherwise, if you're interested in a super light, core-only installation of `eo-learn`, then install it via:

```bash
pip install eo-learn
# pip install "eo-learn[CORE]" # this does the same thing
mlubej marked this conversation as resolved.
Show resolved Hide resolved
```

In order to avoid heavy environments, it is possible to install various scopes of package dependencies. Dependencies for each of the subfolders above (or their extra dependencies) can be installed via e.g.:

```bash
pip install "eo-learn[FEATURES]"
pip install "eo-learn[FEATURES_EXTRA]"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would perhaps structure this differently. More in a way of:
"To better control your dependencies you can install just the core dependencies of eolearn with pip install eo-learn or you can customize, which modules you want operational by providing the corresponding extras, e.g. pip install eo-learn[IO, MASK] if you are only interested in the io and mask submodules.

And then i'd also have a list of all these subpackage extras and their extra extras? I feel like this is the place to have this information, we shouldn't expect users to rummage through our pyproject.toml

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

updated and added the list

```

Collections of dependencies are also available, some of them are:

- `[ALL]` for installing the basic dependencies without extras
zigaLuksic marked this conversation as resolved.
Show resolved Hide resolved
- `[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 +112,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 +144,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. When the mission and purpose of `eo-learn` changed, 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), in order to keep `eo-learn` light and easier to maintain.
mlubej marked this conversation as resolved.
Show resolved Hide resolved

## Contributions

Expand Down