Skip to content

Commit

Permalink
Merge pull request #230 from raphaelquast/update_readme
Browse files Browse the repository at this point in the history
Update README
  • Loading branch information
raphaelquast authored Feb 19, 2024
2 parents 9032227 + 962c689 commit 246d272
Showing 1 changed file with 78 additions and 66 deletions.
144 changes: 78 additions & 66 deletions README.md
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

0 comments on commit 246d272

Please sign in to comment.