From f0d05d6dcc5aac51bbfad33e5bd6d117de8d1553 Mon Sep 17 00:00:00 2001 From: Fabian Gebhart Date: Sun, 6 Feb 2022 21:09:07 +0100 Subject: [PATCH] DOC: enhace readme to provide more details and example screenshots (#3) --- README.md | 31 +++++++++++++++++++++++-------- mapa/mapa.ipynb | 20 ++++++++++---------- 2 files changed, 33 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 4dc1210..605fec4 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,17 @@ # mapa 🌍 -Create 3d-printable STLs from satellite elevation data + +[![PyPI](https://badge.fury.io/py/mapa.svg)](https://badge.fury.io/py/mapa) +[![Python](https://img.shields.io/pypi/pyversions/mapa.svg?style=plastic)](https://badge.fury.io/py/mapa) +[![Downloads](https://pepy.tech/badge/mapa/month)](https://pepy.tech/project/mapa) +[![Python Tests](https://github.com/fgebhart/mapa/actions/workflows/test.yml/badge.svg)](https://github.com/fgebhart/mapa/actions/workflows/test.yml) + +`mapa` let's you create 3d-printable [STL](https://en.wikipedia.org/wiki/STL_(file_format)) files from satellite +elevation data (using [DEM](https://en.wikipedia.org/wiki/Digital_elevation_model) data). + +Under the hood `mapa` uses: +* [numpy](https://numpy.org/) and [numba](https://numba.pydata.org/) to crunch large amounts of data in little time +* [ALOS DEM](https://planetarycomputer.microsoft.com/dataset/alos-dem) satellite data (max resolution of 30m) provided by + [Planetary Computer](https://planetarycomputer.microsoft.com/) ## Installation @@ -8,11 +20,9 @@ pip install mapa ``` ## Usage -mapa uses numpy and numba under the hood to crunch large amounts of data in little time. +`mapa` provides the following approaches for creating STL files: -mapa provides the following approaches for creating STL files: - -### 1. Using the mapa interactive map +### 1. Using the `mapa` interactive map The easiest way is using the `mapa` cli. Simply type ``` mapa @@ -20,6 +30,11 @@ mapa A [jupyter notebook](https://jupyter.org/) will be started with an interactive map. Follow the described steps by executing the cells to create a 3d model of whatever place you like. + Choose bounding box | Create STL file +:-------------------------:|:-------------------------: +![](https://i.imgur.com/76hcx9N.jpg) | ![](https://i.imgur.com/llvxlrk.png) + + ### 2. Using the dem2stl cli The `dem2stl` cli lets you create a 3d-printable STL file based on your tiff file. You can run a demo computation to get a feeling of how the output STL will look like: @@ -59,8 +74,8 @@ Options: --help Show this message and exit. ``` -### 3. Using mapa as python library -In case you are building your own application you can simply use mapa's functionality as a within your application by importing the modules functions. +### 3. Using `mapa` as python library +In case you are building your own application you can simply use `mapa`'s functionality as a within your application by importing the modules functions. ```python from mapa import convert_tif_to_stl @@ -74,4 +89,4 @@ See [Releases](https://github.com/fgebhart/mapa/releases). ## Contributing -Contributions are welcome. +Contributions, feedback or issues are welcome. diff --git a/mapa/mapa.ipynb b/mapa/mapa.ipynb index 4d316b7..f9a5fc0 100644 --- a/mapa/mapa.ipynb +++ b/mapa/mapa.ipynb @@ -32,7 +32,7 @@ { "data": { "application/vnd.jupyter.widget-view+json": { - "model_id": "5f831a2f22394f3cbd4495ea109e6d50", + "model_id": "35f380dc46ef48569c75ee954c7db798", "version_major": 2, "version_minor": 0 }, @@ -66,7 +66,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 4, "id": "39c8fef3", "metadata": { "scrolled": true @@ -78,14 +78,14 @@ "text": [ "⏳ converting bounding box to STL file... \n", "\n", - "🏞 fetching tiff from 1 stac item(s)... ✅ (6.0s) \n", - "🔪 clipping region of interest... ✅ (0.1s) \n", - "🗺 creating base raster for tiff... ✅ (0.6s) \n", - "⛰ computing triangles of 3d surface... ✅ (1.2s) \n", - "📐 computing triangles of body sides... ✅ (0.2s) \n", - "💾 saving data to stl file... ✅ (0.9s) \n", + "🚀 using cached tiff... ✅ (0.0s)\n", + "🔍 reducing image resolution... ✅ (0.1s) \n", + "🗺 creating base raster for tiff... ✅ (0.0s) \n", + "⛰ computing triangles of 3d surface... ✅ (0.2s) \n", + "📐 computing triangles of body sides... ✅ (0.4s) \n", + "💾 saving data to stl file... ✅ (1.0s) \n", "\n", - "🎉 successfully generated STL file: /Users/ppqw/dev/geospacial/mapa/dem2stl/alps.stl\n" + "🎉 successfully generated STL file: /Users/ppqw/dev/geospacial/mapa/mapa/alps.stl\n" ] } ], @@ -97,7 +97,7 @@ " output_file=stl_file_name,\n", " model_size=200, # in millimeter\n", " z_offset=3.0, # in millimeter\n", - " z_scale=2.0,\n", + " z_scale=3.0,\n", " max_res=False,\n", " make_square=False,\n", ")"