| Name | mapa JSON |
| Version |
0.12.0
JSON |
| download |
| home_page | https://github.com/fgebhart/mapa |
| Summary | 🌍 Create 3d-printable STLs from satellite elevation data 🌏 |
| upload_time | 2023-07-25 19:04:26 |
| maintainer | |
| docs_url | None |
| author | Fabian Gebhart |
| requires_python | >=3.8.1,<3.11 |
| license | |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mapa 🌍
[](https://badge.fury.io/py/mapa)
[](https://badge.fury.io/py/mapa)
[](https://pepy.tech/project/mapa)
[](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
```
pip install mapa
```
## Usage
`mapa` provides the following approaches for creating STL files:
### 1. Using the `mapa` streamlit web app 🎈
Certainly the easiest way to interact with `mapa` is to use the streamlit web app. No need to install anything. Simply
access it via your browser. It is based on the [mapa-streamlit repo](https://github.com/fgebhart/mapa-streamlit) and can
be accessed at:
https://3dmaps.streamlit.app/
Note, that the streamlit web app however, does not use the maximal available resolution of the ALOS DEM GeoTIFFs, as it
would take too much time and cloud resources to compute STL files of e.g. multiple GBs. If you are keen in getting STL
files with the highest resolution possible, I'd recommend following the next step.
### 2. Using the `mapa` interactive map 🗺
The second easiest way is using the `mapa` cli. After installing `mapa`, simply type
```
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
:-------------------------:|:-------------------------:
 | 
Slice STL file | 3D print
:-------------------------:|:-------------------------:
 | 
### 3. 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:
```
dem2stl --demo
```
If you have your tiff file at hand, you may run something like
```
dem2stl --input your_file.tiff --output output.stl --model-size 200 --z-offset 3.0 --z-scale 1.5
```
The full list of options and their intention can be found with `dem2stl --help`:
```
Usage: dem2stl [OPTIONS]
🌍 Convert DEM data into STL files 🌏
Options:
--input TEXT Path to input TIFF file.
--output TEXT Path to output STL file.
--as-ascii Save output STL as ascii file. If not provided, output
file will be binary.
--model-size INTEGER Desired size of the (larger side of the) generated 3d
model in millimeter.
--max-res Whether maximum resolution should be used. Note, that
this flag potentially increases compute time
dramatically. The default behavior (i.e.
max_res=False) should return 3d models with sufficient
resolution, while the output stl file should be < ~400
MB.
--z-offset FLOAT Offset distance in millimeter to be put below the 3d
model. Defaults to 4.0. Is not influenced by z-scale.
--z-scale FLOAT Value to be multiplied to the z-axis elevation data to
scale up the height of the model. Defaults to 1.0.
--demo Converts a demo tif of Hawaii into a STL file.
--ensure-squared Flag to toggle whether the output model should be
squared in x- and y-dimension. When enabled it will
remove pixels from one side to ensure same length for
both sides.
--version Show the version and exit.
--help Show this message and exit.
```
### 4. Using `mapa` as python library 📚
In case you are building your own application you can simply use `mapa`'s functionality within your application by importing the functions of the module.
```python
from mapa import convert_tiff_to_stl
path_to_stl = convert_tiff_to_stl(
input_file="path/to/your/input_file.tiff",
as_ascii=False,
model_size=200,
output_file="path/to/your/output_file.stl",
max_res=False,
z_offset=3.0,
z_scale=1.5,
ensure_squared: bool = False,
)
```
## Algorithm Deep Dive
In case you are curios about the algorithm which turns a GeoTIFF into a STL file, I'd recommend reading the header of
[`algorithm.py`](https://github.com/fgebhart/mapa/blob/main/mapa/algorithm.py).
## Changelog
See [Releases](https://github.com/fgebhart/mapa/releases).
## Contributing
Contributions, feedback or issues are welcome.
Raw data
{
"_id": null,
"home_page": "https://github.com/fgebhart/mapa",
"name": "mapa",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<3.11",
"maintainer_email": "",
"keywords": "",
"author": "Fabian Gebhart",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/a3/d2/c4a8afc23e4f64cf71ef26f9ccd4e1504cefbe1b11a93bbd268ca9202e02/mapa-0.12.0.tar.gz",
"platform": null,
"description": "# mapa \ud83c\udf0d\n\n[](https://badge.fury.io/py/mapa)\n[](https://badge.fury.io/py/mapa)\n[](https://pepy.tech/project/mapa)\n[](https://github.com/fgebhart/mapa/actions/workflows/test.yml)\n\n`mapa` let's you create 3d-printable [STL](https://en.wikipedia.org/wiki/STL_(file_format)) files from satellite\nelevation data (using [DEM](https://en.wikipedia.org/wiki/Digital_elevation_model) data).\n\nUnder the hood `mapa` uses:\n* [numpy](https://numpy.org/) and [numba](https://numba.pydata.org/) to crunch large amounts of data in little time\n* [ALOS DEM](https://planetarycomputer.microsoft.com/dataset/alos-dem) satellite data (max resolution of 30m) provided by\n [Planetary Computer](https://planetarycomputer.microsoft.com/)\n\n\n## Installation\n```\npip install mapa\n```\n\n## Usage\n`mapa` provides the following approaches for creating STL files:\n\n### 1. Using the `mapa` streamlit web app \ud83c\udf88\nCertainly the easiest way to interact with `mapa` is to use the streamlit web app. No need to install anything. Simply\naccess it via your browser. It is based on the [mapa-streamlit repo](https://github.com/fgebhart/mapa-streamlit) and can\nbe accessed at:\n\nhttps://3dmaps.streamlit.app/\n\nNote, that the streamlit web app however, does not use the maximal available resolution of the ALOS DEM GeoTIFFs, as it\nwould take too much time and cloud resources to compute STL files of e.g. multiple GBs. If you are keen in getting STL\nfiles with the highest resolution possible, I'd recommend following the next step.\n\n### 2. Using the `mapa` interactive map \ud83d\uddfa\nThe second easiest way is using the `mapa` cli. After installing `mapa`, simply type\n```\nmapa\n```\nA [jupyter notebook](https://jupyter.org/) will be started with an interactive map. Follow the described steps by\nexecuting the cells to create a 3d model of whatever place you like.\n\n Choose bounding box | Create STL file\n:-------------------------:|:-------------------------:\n | \n\n Slice STL file | 3D print\n:-------------------------:|:-------------------------:\n | \n\n### 3. Using the dem2stl cli \ud83d\udcbb\nThe `dem2stl` cli lets you create a 3d-printable STL file based on your tiff file. You can run a demo computation to get\na feeling of how the output STL will look like:\n```\ndem2stl --demo\n```\nIf you have your tiff file at hand, you may run something like\n```\ndem2stl --input your_file.tiff --output output.stl --model-size 200 --z-offset 3.0 --z-scale 1.5\n```\nThe full list of options and their intention can be found with `dem2stl --help`:\n```\nUsage: dem2stl [OPTIONS]\n\n \ud83c\udf0d Convert DEM data into STL files \ud83c\udf0f\n\nOptions:\n --input TEXT Path to input TIFF file.\n --output TEXT Path to output STL file.\n --as-ascii Save output STL as ascii file. If not provided, output\n file will be binary.\n --model-size INTEGER Desired size of the (larger side of the) generated 3d\n model in millimeter.\n --max-res Whether maximum resolution should be used. Note, that\n this flag potentially increases compute time\n dramatically. The default behavior (i.e.\n max_res=False) should return 3d models with sufficient\n resolution, while the output stl file should be < ~400\n MB.\n --z-offset FLOAT Offset distance in millimeter to be put below the 3d\n model. Defaults to 4.0. Is not influenced by z-scale.\n --z-scale FLOAT Value to be multiplied to the z-axis elevation data to\n scale up the height of the model. Defaults to 1.0.\n --demo Converts a demo tif of Hawaii into a STL file.\n --ensure-squared Flag to toggle whether the output model should be\n squared in x- and y-dimension. When enabled it will\n remove pixels from one side to ensure same length for\n both sides.\n --version Show the version and exit.\n --help Show this message and exit.\n```\n\n### 4. Using `mapa` as python library \ud83d\udcda\nIn case you are building your own application you can simply use `mapa`'s functionality within your application by importing the functions of the module.\n```python\nfrom mapa import convert_tiff_to_stl\n\npath_to_stl = convert_tiff_to_stl(\n input_file=\"path/to/your/input_file.tiff\",\n as_ascii=False,\n model_size=200,\n output_file=\"path/to/your/output_file.stl\",\n max_res=False,\n z_offset=3.0,\n z_scale=1.5,\n ensure_squared: bool = False,\n)\n```\n\n\n## Algorithm Deep Dive\n\nIn case you are curios about the algorithm which turns a GeoTIFF into a STL file, I'd recommend reading the header of\n[`algorithm.py`](https://github.com/fgebhart/mapa/blob/main/mapa/algorithm.py).\n\n\n## Changelog\n\nSee [Releases](https://github.com/fgebhart/mapa/releases).\n\n\n## Contributing\n\nContributions, feedback or issues are welcome.\n",
"bugtrack_url": null,
"license": "",
"summary": "\ud83c\udf0d Create 3d-printable STLs from satellite elevation data \ud83c\udf0f",
"version": "0.12.0",
"project_urls": {
"Homepage": "https://github.com/fgebhart/mapa",
"Repository": "https://github.com/fgebhart/mapa"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93dd07ef35e3ae482a61901ae05a10332a03b5605a65d4ef363915385816d1b1",
"md5": "9e70e1e73dff42902fd50179d09b7320",
"sha256": "f9173f5c346a94a0ca70180024e853e8e5be415059646060f81c8db94acbea34"
},
"downloads": -1,
"filename": "mapa-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e70e1e73dff42902fd50179d09b7320",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<3.11",
"size": 23830,
"upload_time": "2023-07-25T19:04:24",
"upload_time_iso_8601": "2023-07-25T19:04:24.764695Z",
"url": "https://files.pythonhosted.org/packages/93/dd/07ef35e3ae482a61901ae05a10332a03b5605a65d4ef363915385816d1b1/mapa-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a3d2c4a8afc23e4f64cf71ef26f9ccd4e1504cefbe1b11a93bbd268ca9202e02",
"md5": "863cd904365aa3ac95304834614ba7d3",
"sha256": "9858c903b808a93d18b315f1b1ad9b52326f2109d0244464f59d078b7b5ba7e2"
},
"downloads": -1,
"filename": "mapa-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "863cd904365aa3ac95304834614ba7d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<3.11",
"size": 20732,
"upload_time": "2023-07-25T19:04:26",
"upload_time_iso_8601": "2023-07-25T19:04:26.453936Z",
"url": "https://files.pythonhosted.org/packages/a3/d2/c4a8afc23e4f64cf71ef26f9ccd4e1504cefbe1b11a93bbd268ca9202e02/mapa-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-25 19:04:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fgebhart",
"github_project": "mapa",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mapa"
}
