mirrorworld 0.1.0__tar.gz

mirrorworld-0.1.0/.gitignore

@@ -0,0 +1,138 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+.idea/
+
+*.ipynb
+*.csv
+
+*.jpg
+*.heic
+*.png

mirrorworld-0.1.0/CREDITS.md

@@ -0,0 +1,8 @@
+# Credits
+
+## Apple Look Around
+The authentication code has been translated from
+[retroplasma/flyover-reverse-engineering](https://github.com/retroplasma/flyover-reverse-engineering/blob/master/pkg/mps/auth/auth.go).
+
+## Google Street View
+The depth map parser is based on [this SO post by ted](https://stackoverflow.com/a/56245973), which is derived from [proog128/GSVPanoDepth.js](proog128/GSVPanoDepth.js).

mirrorworld-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 skzk (streetlevel)
+Copyright (c) 2026 alienpenguin10 (mirrorworld additions)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mirrorworld-0.1.0/PKG-INFO

@@ -0,0 +1,387 @@
+Metadata-Version: 2.5
+Name: mirrorworld
+Version: 0.1.0
+Summary: Fetch street-level, aerial, satellite, elevation, LiDAR and map data for any place
+Project-URL: Homepage, https://github.com/alienpenguin10/Mirrorworld
+Project-URL: Bug Tracker, https://github.com/alienpenguin10/Mirrorworld/issues
+Project-URL: Based on, https://github.com/sk-zk/streetlevel
+Author: alienpenguin10
+Author-email: sk-zk <sk-zk@users.noreply.github.com>
+Maintainer: alienpenguin10
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aerial imagery,elevation,gis,lidar,mapillary,remote sensing,satellite,street view
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Requires-Dist: aiohttp
+Requires-Dist: bd09convertor
+Requires-Dist: coordinatesconverter
+Requires-Dist: cython
+Requires-Dist: mapbox-vector-tile
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: protobuf>4
+Requires-Dist: pycryptodome
+Requires-Dist: pyequilib
+Requires-Dist: pyexiv2
+Requires-Dist: pyfrpc==0.2.13
+Requires-Dist: pyproj
+Requires-Dist: requests
+Requires-Dist: scipy
+Provides-Extra: all
+Requires-Dist: laspy[lazrs]; extra == 'all'
+Requires-Dist: rasterio; extra == 'all'
+Provides-Extra: lidar
+Requires-Dist: laspy[lazrs]; extra == 'lidar'
+Provides-Extra: raster
+Requires-Dist: rasterio; extra == 'raster'
+Description-Content-Type: text/markdown
+
+# mirrorworld
+**mirrorworld** fetches data about a place from many sources with one consistent API: street-level imagery
+(Google Street View, Apple Look Around, Mapillary, KartaView, Panoramax and more), detected street assets,
+aerial and satellite imagery, elevation models, LiDAR point clouds, any OGC/ArcGIS map service and
+OpenStreetMap features. Everything is downloaded on demand for a point or bounding box; nothing is hosted by
+this project.
+
+It is a fork of [streetlevel](https://github.com/sk-zk/streetlevel) by sk-zk, whose street-level providers use the
+services' internal APIs: no API keys are required for them, but they may break unexpectedly.
+
+(Nearly) all functions are available as either a sync function using `requests` or an async function
+using `aiohttp`, requiring a `ClientSession`.
+
+## Installation
+
+```sh
+pip install mirrorworld
+pip install "mirrorworld[all]"   # plus GeoTIFF (rasterio) and LiDAR (laspy) support
+```
+
+The extras can also be installed separately: `mirrorworld[raster]` for satellite, elevation and GeoTIFF output,
+`mirrorworld[lidar]` for point clouds.
+
+macOS users may need to install [additional dependencies](https://github.com/LeoHsiao1/pyexiv2/blob/master/docs/Tutorial.md#faq):
+
+```sh
+brew install gettext
+brew install inih
+```
+
+## Example
+Downloading the closest Google Street View panorama to a specific location, sync:
+
+```python
+from mirrorworld import streetview
+
+pano = streetview.find_panorama(46.883958, 12.169002)
+streetview.download_panorama(pano, f"{pano.id}.jpg")
+```
+
+Or async:
+
+```python
+from mirrorworld import streetview
+from aiohttp import ClientSession
+
+async with ClientSession() as session:
+    pano = await streetview.find_panorama_async(46.883958, 12.169002, session)
+    await streetview.download_panorama_async(pano, f"{pano.id}.jpg", session)
+```
+
+## More modalities for a place
+On top of streetlevel's providers, mirrorworld adds sources that researchers commonly need next to street-level panoramas. Everything is fetched on
+demand for a point or a bounding box (WGS84, lat/lon order) and nothing is hosted by us; results carry their
+georeferencing and source metadata. Sync and async variants are provided wherever the work is network-bound.
+
+| Modality | Module | Sources | Coverage | Key |
+|---|---|---|---|---|
+| Open street-level imagery | `mapillary`, `kartaview`, `panoramax` | Mapillary, KartaView, Panoramax (all CC BY-SA) | worldwide, crowd-sourced: Mapillary dense in cities (incl. UK); KartaView and Panoramax patchy (Panoramax strongest in France) | Mapillary: free token |
+| Detected street assets | `mapillary` (`find_map_features`, `get_detections`, `get_point_cloud`) | Mapillary map features (poles, manholes, junction boxes, signs, ...), segmentations, SfM point clouds | wherever Mapillary has imagery | free token |
+| Aerial imagery (web tiles) | `aerial.bing`, `aerial.google`, `aerial.esri`, `aerial.usgs` | Bing, Google, Esri World Imagery, USGS | worldwide (USGS: US only) | none |
+| Dated aerial imagery | `aerial.wayback` | Esri World Imagery Wayback, 2014 onwards | worldwide | none |
+| National orthophotos | `aerial.pdok` | Netherlands RGB + colour-infrared, 8 cm | Netherlands | none |
+| Satellite | `satellite.sentinel2`, `sentinel1`, `landsat`, `naip`, `worldcover`, generic `satellite.stac` | Earth Search, Microsoft Planetary Computer | worldwide (NAIP: US only) | none |
+| Elevation | `elevation.ea`, `elevation.wales`, `elevation.ahn`, `elevation.usgs3dep`, `elevation.copernicus` | Environment Agency LiDAR (1 m), Welsh Government LiDAR (1 m), AHN (0.5 m), USGS 3DEP, Copernicus GLO-30 | England, Wales, Netherlands, US, worldwide (30 m) | none |
+| LiDAR point clouds | `lidar.usgs3dep`, generic `lidar.ept` | USGS 3DEP on AWS | US (any EPT dataset elsewhere) | none |
+| Any map service | `services.wms`, `wmts`, `wcs`, `arcgis`, `raster.read_cog` | any OGC / ArcGIS server or cloud-optimized GeoTIFF | depends on the service | depends |
+| Vector map data | `vector.osm` | OpenStreetMap via Overpass (ODbL) | worldwide; tag completeness varies (UK street cabinets and poles are sparsely mapped) | none |
+
+```python
+from mirrorworld import mapillary, panoramax
+from mirrorworld.aerial import wayback, pdok
+from mirrorworld.satellite import sentinel2
+from mirrorworld.elevation import ahn
+from mirrorworld.lidar import usgs3dep
+from mirrorworld.vector import osm
+
+poles = mapillary.find_map_features(47.68, -122.30, radius=150, values=["object--support--utility-pole"])
+pics = panoramax.find_panoramas(51.5088, -0.127, radius=30)
+versions = wayback.find_versions(47.6062, -122.3321)            # dated imagery versions at a place
+pdok.download_raster(52.3736, 4.8915, 52.3728, 4.8932, "dam_cir.png", infrared=True)
+s2 = sentinel2.get_raster(47.615, -122.345, 47.600, -122.325, bands=("red", "nir"))
+heights = ahn.get_ndsm(52.3736, 4.8915, 52.3728, 4.8932)         # object heights above ground
+las = usgs3dep.get_points(47.6068, -122.3340, 47.6058, -122.3325, resolution=1.0)
+cabinets = osm.find_features(47.61, -122.34, 47.60, -122.33, {"man_made": "street_cabinet"})
+```
+
+Optional dependencies: `pip install "mirrorworld[raster]"` (rasterio: GeoTIFF/COG for satellite, elevation, WCS,
+ArcGIS) and `pip install "mirrorworld[lidar]"` (laspy with LAZ support). Mapillary reads its token from
+`access_token=` or `MAPILLARY_ACCESS_TOKEN`.
+
+Each source keeps its own terms (listed in each module's docstring and the docs). Bing and Google tiles use
+unofficial endpoints; check their terms before relying on them.
+
+## Documentation
+The API reference lives in [`docs/`](docs/) (Sphinx: `pip install -r docs/requirements.txt && make -C docs html`).
+The original streetlevel documentation is at [streetlevel.readthedocs.io](https://streetlevel.readthedocs.io/).
+
+## Functionality overview
+Services covering multiple countries are on the left; services covering one specific country are on the right.
+
+✔ implemented / available; 🟡 partially implemented; ❌ not implemented; ⚫ not available / not applicable
+
+<table>
+  <thead>
+    <th></th>
+    <th align="center">Google<br>Street&nbsp;View</th>
+    <th align="center">Apple<br>Look&nbsp;Around</th>
+    <th align="center">Yandex<br>Panorama</th>
+    <th align="center">Bing<br>Streetside</th>
+    <th></th>
+    <th align="center">🇨🇳 Baidu<br>Panorama</th>
+    <th align="center">🇰🇷 Kakao<br>Road&nbsp;View</th>
+    <th align="center">🇰🇷 Naver<br>Street&nbsp;View</th>
+    <th align="center">🇨🇿 Mapy.cz<br>Panorama</th>
+    <th align="center">🇮🇸 Já<br>360</th>
+  </thead>
+  <thead>
+    <td colspan="11" style="padding-top:20px"><br><b>Finding panoramas</b><br>
+      How panoramas can be retrieved through the API.
+    </td>
+  </thead>
+  <tr>
+    <td align="right">Find panoramas around a point</td>
+    <td align="center">✔<sup>1</sup></td>
+    <td align="center">⚫</td>
+    <td align="center">✔<sup>1</sup></td>
+    <td align="center">✔</td>
+    <td></td>
+    <td align="center">✔<sup>1</sup></td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>1</sup></td>
+    <td align="center">✔<sup>1</sup></td>
+    <td align="center">✔<sup>1</sup></td>
+  </tr>
+  <tr>
+    <td align="right">Find panoramas by map tile or bbox</td>
+    <td align="center">✔<sup>2</sup></td>
+    <td align="center">✔<sup>2</sup></td>
+    <td align="center">⚫</td>
+    <td align="center">✔<sup>3</sup></td>
+    <td></td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+  </tr>
+  <tr>
+    <td align="right">Get specific panorama by ID</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+  </tr>
+  <thead>
+    <td colspan="11" style="padding-top:20px"><br><b>Imagery</b><br>
+      The type of imagery returned by the service.
+    </td>
+  </thead>
+  <tr>
+    <td align="right">Panoramas</td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>4</sup></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+  </tr>
+  <tr>
+    <td align="right">Depth</td>
+    <td align="center">✔<sup>5</sup></td>
+    <td align="center">❌</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+    <td></td>
+    <td align="center">❌?<sup>10</sup></td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>14</sup></td>
+    <td align="center">⚫<br></td>
+    <td align="center">⚫<br></td>
+  </tr>
+  <tr>
+    <td align="right">Image projection</td>
+    <td align="center">Equirectangular</td>
+    <td align="center">???</td>
+    <td align="center">Equirectangular</td>
+    <td align="center">Cubemap</td>
+    <td></td>
+    <td align="center">Equirectangular</td>
+    <td align="center">Equirectangular</td>
+    <td align="center">Equirectangular/Cubemap<sup>13</sup></td>
+    <td align="center">Equirectangular</td>
+    <td align="center">Cubemap</td>
+  </tr>
+  <tr>
+    <td align="right">Image format</td>
+    <td align="center">JPEG</td>
+    <td align="center">HEIC</td>
+    <td align="center">JPEG</td>
+    <td align="center">JPEG</td>
+    <td></td>
+    <td align="center">JPEG</td>
+    <td align="center">JPEG</td>
+    <td align="center">JPEG</td>
+    <td align="center">JPEG</td>
+    <td align="center">JPEG</td>
+  </tr>
+  <thead>
+    <td colspan="11" style="padding-top:20px"><br><b>Available metadata</b><br>
+      Metadata returned by the API of the service alongside ID and location.
+    </td>
+  </thead>
+  <tr>
+    <td align="right">Capture date</td>
+    <td align="center">✔<sup>6</sup></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>9</sup></td>
+  </tr>
+  <tr>
+    <td align="right">Heading, pitch, roll</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>7</sup></td>
+    <td align="center">✔</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>7</sup></td>
+    <td align="center">✔<sup>11</sup></td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>7</sup></td>
+  </tr>
+  <tr>
+    <td align="right">Elevation</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫<sup>12</sup></td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+  </tr>
+  <tr>
+    <td align="right">Nearby / linked panoramas</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">✔<sup>8</sup></td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+  </tr>
+  <tr>
+    <td align="right">Historical panoramas</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+  </tr>
+  <tr>
+    <td align="right">Address</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td></td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+  </tr>
+  <tr>
+    <td align="right">PoIs</td>
+    <td align="center">✔</td>
+    <td align="center">❌</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td></td>
+    <td align="center">⚫</td>
+    <td align="center">❌</td>
+    <td align="center">❌</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+  </tr>
+  <tr>
+    <td align="right">Creator</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td></td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+    <td align="center">⚫</td>
+    <td align="center">✔</td>
+    <td align="center">⚫</td>
+  </tr>
+</table>
+
+1: Returns closest only  
+2: Tile, z=17  
+3: Bounding box  
+4: Unstitched  
+5: Appears to be a synthetic depth map created from elevation data and building footprints  
+6: Month and year only for official coverage, full date for inofficial coverage  
+7: Only heading; pitch/roll do not appear to be available  
+8: Previous and next image in sequence  
+9: Month and year only  
+10: There is a `has_depth` field in the raw metadata, but I've yet to find a panorama that actually has depth  
+11: Pitch/roll are only available for the new 3D imagery  
+12: Camera altitude is available, however  
+13: 3D imagery panos have both an equirectangular and a cubemap version; everything else is only available as cubemap  
+14: Non-3D imagery appears to use a synthetic depthmap created from elevation data and building footprints