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 #230

Merged
merged 3 commits into from
Feb 19, 2024
Merged

Update README #230

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
69f1e0c
Update README.md
raphaelquast Feb 13, 2024
ad578e2
Update README.md
raphaelquast Feb 16, 2024
962c689
Update README.md
raphaelquast Feb 16, 2024
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
144 changes: 78 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,121 +14,133 @@

----

# EOmaps - Interactive maps in python!
<h3 align="center">A python package to visualize and analyze geographical datasets.</h3>

**EOmaps** is a <tt>python</tt> package to visualize and analyze geographical datasets.
<table>
<tr><td>
<i><b>EOmaps</b> aims to provide a comprehensive, flexible, well-documented and easy-to-use API to create publication-ready maps that can directly be used for interactive data analysis.</i>
</td></tr>
</table>

## What can I do with EOmaps?

It is built on top of [matplotlib](https://matplotlib.org/) and [cartopy](https://scitools.org.uk/cartopy/docs/latest/) and provides an intuitive and easy-to-use interface to speed up and simplify the creation and comparison of maps.
**EOmaps** is built on top of [matplotlib](https://matplotlib.org/) and [cartopy](https://scitools.org.uk/cartopy/docs/latest/) and integrates well with the scientific python infrastructure (e.g., [numpy](https://numpy.org/), [pandas](https://pandas.pydata.org/), [geopandas](https://geopandas.org/), [xarray](https://xarray.dev/) etc.), allowing you to visualize point-, raster- or vector-datasets provided in almost any format you can imagine, no matter if you're dealing with just a few unsorted datapoints or multi-dimensional stacks of global high-resolution datasets.

Figures created with EOmaps are multi-layered, so you can (transparently) overlay and interactively compare your datasets with ease. With the accompanying GUI widget, you can quickly switch layers, change the layout, examine the large collection of features and web-map services, and explore the capabilities of EOmaps.
Once you're map is ready, you can export it as high-resolution image or vector-graphic for further editing.
Leveraging the powers of matplotlib, you can also embed interactive maps in Jupyter Notebooks, on a webpage or in GUI frameworks like Qt, tkinter etc..

> [!IMPORTANT]
>
> EOmaps is 100% free and open-source.
> As such, acknowledgement is extremely important to allow continued support and development of the package.
>
> Did EOmaps help in your research? $\Rightarrow$ **Add a ✔️ Citation to your publication!**
>
> <a href="https://doi.org/10.5281/zenodo.6459598"><img src="https://zenodo.org/badge/410829039.svg" alt="https://zenodo.org/badge/latestdoi/410829039" align="left"></a>
>
> <details>
> <summary>BibTeX</summary>
> <br>
> The following BibTeX entry uses a DOI that always points to the latest release of EOmaps!<br>
> (You can get the DOI for a specific version form the <a href="https://doi.org/10.5281/zenodo.6459598">zenodo-page</a>)
>
> ```bibtex
> @software{eomaps,
> author = {Raphael Quast},
> title = {EOmaps: A python package to visualize and analyze geographical datasets.},
> doi = {10.5281/zenodo.6459598},
> url = {https://doi.org/10.5281/zenodo.6459598}
> }
> ```
>
> </details>
>

## 🚀 Getting started

Head over to the start-page of the <a href=https://eomaps.readthedocs.io/en/latest><b>📖 Documentation </b></a> to get an overview of all available features and functionalities!

> [!TIP]
> For a quick hands-on introduction, checkout this article on dev.to:
> [Geographic data visualization and analysis with EOmaps: Interactive maps in python!](https://dev.to/raphaelquast/geographic-data-visualization-and-analysis-with-eomaps-interactive-maps-in-python-48e1)
>
> ---

### What can EOmaps do for you?

- Create [▤ multi-layered maps](https://eomaps.readthedocs.io/en/latest/api_basics.html#layer-management) and interactively compare different layers with each other
- [🔴 Visualize datasets](https://eomaps.readthedocs.io/en/latest/api_data_visualization.html) with millions of datapoints and handle reprojections
- Provide a comprehensive set of tools to customize the map
- [🌵NaturalEarth features](https://eomaps.readthedocs.io/en/latest/api_naturalearth_features.html)
- [📏Scalebars](https://eomaps.readthedocs.io/en/latest/api_scalebar.html)
- [▦ Gridlines](https://eomaps.readthedocs.io/en/latest/api_gridlines.html)
- [🛰 WebMap layers](https://eomaps.readthedocs.io/en/latest/api_webmaps.html)
- [🏕 Annotations, Markers, Lines, Logos...](https://eomaps.readthedocs.io/en/latest/api_annotations_markers_etc.html)
- . . .
- Get a useful [🧰 CompanionWidget](https://eomaps.readthedocs.io/en/latest/api_companion_widget.html) GUI
- Use [🛸 Callbacks](https://eomaps.readthedocs.io/en/latest/api_callbacks.html) to interact with the figure
- Interactively re-arrange multiple maps in a figure with the [🏗️ LayoutEditor](https://eomaps.readthedocs.io/en/latest/api_layout_editor.html)
- [🗺 Export](https://eomaps.readthedocs.io/en/latest/api_basics.html#image-export-jpeg-png-svg-etc) publication ready high resolution images (png, jpeg, tiff, ...)
or export figures as vector graphics (svg, eps, pdf ...)
- . . . and much more!

Checkout the [🌱 Basics](https://eomaps.readthedocs.io/en/latest/api_basics.html) in the documentation to get started!

<img src=https://eomaps.readthedocs.io/en/latest/_images/intro.png width=50%>


## 🔨 Installation

To install EOmaps (and all its dependencies) via the [conda](https://docs.conda.io/projects/conda/en/stable/) package-manager, simply use:
To install **EOmaps** (and all its dependencies) with the [conda](https://docs.conda.io/projects/conda/en/stable/) package-manager, simply use:
```python
conda install -c conda-forge eomaps
```
> ... to get a <u>**huge speedup**</u>, use [mamba](https://mamba.readthedocs.io/en/latest/) to solve the dependencies!

> [!TIP]
> To get a <u>**huge speedup**</u>, use [mamba](https://mamba.readthedocs.io/en/latest/) to solve the dependencies!
> ```python
> conda install -c conda-forge mamba
> mamba install -c conda-forge eomaps
> ```
Need more information?
- Have a look at the [🐛Installation](https://eomaps.readthedocs.io/en/latest/installation.html) instructions in the docs.
- Checkout the quickstart guide [🚀 From 0 to EOmaps](https://eomaps.readthedocs.io/en/latest/FAQ.html#from-0-to-eomaps-a-quickstart-guide).

## 📖 Documentation

Make sure to have a look at the <a href=https://eomaps.readthedocs.io/en/latest><b>📖 Documentation </b></a> which provides a lot of <a href=https://eomaps.readthedocs.io/en/latest/EOmaps_examples.html><b>🌐Examples</b></a> on how to create awesome interactive maps (incl. 🐍 source code)!

## ✔️ Citation
Did EOmaps help in your research?
Support the development and add a citation to your publication!
> Advanced users can also use `pip` to install **EOmaps** (and selectively install optional dependency groups)
> ```pyhton
> pip install eomaps # install only minimal required dependencies
> pip install eomaps[all] # install all optional dependencies
> ...
> ```

[![https://doi.org/10.5281/zenodo.6459598](https://zenodo.org/badge/410829039.svg)](https://zenodo.org/badge/latestdoi/410829039)
For more detailes, have a look at the [Installation Instructions](https://eomaps.readthedocs.io/en/latest/installation.html) or the quickstart guide ["From 0 to EOmaps"](https://eomaps.readthedocs.io/en/latest/FAQ.html#from-0-to-eomaps-a-quickstart-guide)!


## 🌟 Contribute

Interested in contributing to EOmaps? Awesome!

- Checkout the [🚀 Contribution Guide](https://eomaps.readthedocs.io/en/latest/contribute.html) on how to get started!
Interested in contributing to EOmaps? **Awesome!**
You can find detailed instructions on how to setup EOmaps for development in the [Contribution Guide](https://eomaps.readthedocs.io/en/latest/contribute.html)!

> Found a bug or got an idea for an interesting feature?
> Open an [issue](https://github.com/raphaelquast/EOmaps/issues) or start a [discussion](https://github.com/raphaelquast/EOmaps/discussions), and I'll see what I can do!


---------------


<center><img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/minigifs/companion_widget.gif?raw=true" alt="EOmaps example 6" width=50%></center>


<table>
<tr>
<td valign="center" style="width:50%">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/fig6.gif?raw=true" alt="EOmaps example 6">
</td>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/minigifs/advanced_wms.gif?raw=true" alt="EOmaps example 2">
</td>
</tr>
<tr>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/fig9.gif?raw=true" alt="EOmaps example 9">
<td colspan=2 valign="center">
<a href="https://eomaps.readthedocs.io/en/dev/api_companion_widget.html"><img src="https://github.com/raphaelquast/EOmaps/assets/22773387/fe27e290-019e-4179-929d-d33bc590758e" alt="EOmaps GUI Example"></a>
</td>
<td valign="center">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-timeseries"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_timeseries.gif?raw=true" alt="EOmaps Timeseries Example"></a>
</td>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/fig4.gif?raw=true" alt="EOmaps example 4">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-callbacks"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_callbacks.gif?raw=true" alt="EOmaps Callbacks Example"></a>
</td>
</tr>
<tr>
<td valign="center" style="width:50%">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-webmaps"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_webmaps.gif?raw=true" alt="EOmaps Webmaps Example"></a>
</td>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/fig7.gif?raw=true" alt="EOmaps example 7">
<a href="[https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html](https://eomaps.readthedocs.io/en/dev/api_webmaps.html#setting-date-style-and-other-webmap-properties)"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/minigifs/advanced_wms.gif?raw=true" alt="EOmaps Webmaps Example 2"></a>
</td>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/fig3.gif?raw=true" alt="EOmaps example 8">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-scalebars"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_scalebars.gif?raw=true" alt="EOmaps Scalebars Example"></a>
</td>
<td valign="center">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-multiple-maps"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_multiple_maps.gif?raw=true" alt="EOmaps Multiple Maps Example"></a>
</td>
</tr>
<tr>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/minigifs/layout_editor.gif?raw=true" alt="EOmaps inset-maps">
<a href="https://eomaps.readthedocs.io/en/dev/api_layout_editor.html"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/minigifs/layout_editor.gif?raw=true" alt="EOmaps LayoutEditor Example"></a>
</td>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/fig8.gif?raw=true" alt="EOmaps example 3">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-vector-data"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_vector_data.gif?raw=true" alt="EOmaps Vector Data Example"></a>
</td>
</tr>
<tr>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/example_lines.png?raw=true" alt="EOmaps example 9">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-lines"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_lines.png?raw=true" alt="EOmaps Lines Example"></a>
</td>
<td valign="center">
<img src="https://github.com/raphaelquast/EOmaps/blob/master/docs/_static/inset_maps.png?raw=true" alt="EOmaps example 4">
<a href="https://eomaps.readthedocs.io/en/dev/EOmaps_examples.html#example-inset-maps"><img src="https://github.com/raphaelquast/EOmaps/blob/dev/docs/_static/example_images/example_inset_maps.png?raw=true" alt="EOmaps InsetMaps Example"></a>
</td>

</tr>
</table>

Expand Down
Loading