elevation 2.0.0rc2__tar.gz → 2.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. {elevation-2.0.0rc2 → elevation-2.0.1}/.github/workflows/on-push.yml +44 -21
  2. elevation-2.0.1/.readthedocs.yaml +22 -0
  3. {elevation-2.0.0rc2 → elevation-2.0.1}/CHANGELOG.rst +50 -16
  4. {elevation-2.0.0rc2 → elevation-2.0.1}/CITATION.cff +3 -1
  5. {elevation-2.0.0rc2 → elevation-2.0.1}/Makefile +4 -1
  6. elevation-2.0.1/PKG-INFO +353 -0
  7. elevation-2.0.1/README.md +322 -0
  8. {elevation-2.0.0rc2 → elevation-2.0.1}/docs/conf.py +9 -3
  9. {elevation-2.0.0rc2 → elevation-2.0.1}/docs/index.md +3 -4
  10. elevation-2.0.1/docs/migration.md +43 -0
  11. {elevation-2.0.0rc2 → elevation-2.0.1}/docs/quickstart.md +0 -2
  12. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation/__init__.py +9 -6
  13. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation/__main__.py +67 -12
  14. elevation-2.0.1/elevation/cache.py +120 -0
  15. elevation-2.0.1/elevation/datasets/AW3D30.yaml +65 -0
  16. elevation-2.0.1/elevation/datasets/GLO-30.yaml +75 -0
  17. elevation-2.0.1/elevation/datasets/GLO-90.yaml +75 -0
  18. elevation-2.0.1/elevation/datasets/MAPZEN.yaml +57 -0
  19. elevation-2.0.1/elevation/datasets/SRTM1_ELLIP.yaml +64 -0
  20. elevation-2.0.1/elevation/datasets/SRTM1_GEOID.yaml +67 -0
  21. elevation-2.0.1/elevation/datasets/SRTM3.yaml +59 -0
  22. elevation-2.0.1/elevation/datasets/elevation.yaml +42 -0
  23. elevation-2.0.1/elevation/datasource.py +475 -0
  24. elevation-2.0.1/elevation/spatial.py +183 -0
  25. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation/version.py +1 -1
  26. elevation-2.0.1/elevation.egg-info/PKG-INFO +353 -0
  27. elevation-2.0.1/elevation.egg-info/SOURCES.txt +96 -0
  28. elevation-2.0.1/elevation.egg-info/requires.txt +3 -0
  29. elevation-2.0.1/elevation.egg-info/scm_file_list.json +91 -0
  30. elevation-2.0.1/elevation.egg-info/scm_version.json +8 -0
  31. {elevation-2.0.0rc2 → elevation-2.0.1}/pyproject.toml +13 -8
  32. {elevation-2.0.0rc2 → elevation-2.0.1}/tests/conftest.py +6 -14
  33. elevation-2.0.1/tests/data/AW3D30/ne_rome.tif +0 -0
  34. elevation-2.0.1/tests/data/AW3D30/nw_san_francisco.tif +0 -0
  35. elevation-2.0.1/tests/data/AW3D30/se_sydney.tif +0 -0
  36. elevation-2.0.1/tests/data/AW3D30/se_tasman_sea.tif +0 -0
  37. elevation-2.0.1/tests/data/AW3D30/sw_santiago.tif +0 -0
  38. elevation-2.0.1/tests/data/GLO-30/ne_rome.tif +0 -0
  39. elevation-2.0.1/tests/data/GLO-30/nw_san_francisco.tif +0 -0
  40. elevation-2.0.1/tests/data/GLO-30/se_sydney.tif +0 -0
  41. elevation-2.0.1/tests/data/GLO-30/sw_santiago.tif +0 -0
  42. elevation-2.0.1/tests/data/GLO-90/ne_rome.tif +0 -0
  43. elevation-2.0.1/tests/data/GLO-90/nw_san_francisco.tif +0 -0
  44. elevation-2.0.1/tests/data/GLO-90/se_sydney.tif +0 -0
  45. elevation-2.0.1/tests/data/GLO-90/sw_santiago.tif +0 -0
  46. elevation-2.0.1/tests/data/SRTM1_ELLIP/se_tasman_sea.tif +0 -0
  47. elevation-2.0.1/tests/data/SRTM1_GEOID/se_tasman_sea.tif +0 -0
  48. elevation-2.0.1/tests/data/SRTM3/nw_pacific.tif +0 -0
  49. elevation-2.0.1/tests/data/reference.bad +1 -0
  50. elevation-2.0.1/tests/data/reference.geojson +21 -0
  51. elevation-2.0.1/tests/data/reference.tif +0 -0
  52. elevation-2.0.1/tests/data/reference.tif.gz +0 -0
  53. elevation-2.0.1/tests/data/reference.zip +0 -0
  54. elevation-2.0.1/tests/integration_aw3d30.py +41 -0
  55. elevation-2.0.1/tests/integration_glo_30.py +40 -0
  56. elevation-2.0.1/tests/integration_glo_90.py +41 -0
  57. elevation-2.0.0rc2/tests/integration_terrain_tiles.py → elevation-2.0.1/tests/integration_mapzen.py +7 -7
  58. {elevation-2.0.0rc2 → elevation-2.0.1}/tests/integration_srtm1_ellip.py +7 -1
  59. {elevation-2.0.0rc2 → elevation-2.0.1}/tests/integration_srtm1_geoid.py +7 -1
  60. {elevation-2.0.0rc2 → elevation-2.0.1}/tests/integration_srtm3.py +7 -1
  61. elevation-2.0.1/tests/test_10_spatial.py +162 -0
  62. elevation-2.0.1/tests/test_15_cache.py +39 -0
  63. elevation-2.0.1/tests/test_20_datasource.py +457 -0
  64. elevation-2.0.1/tests/test_40_main.py +233 -0
  65. {elevation-2.0.0rc2 → elevation-2.0.1}/uv.lock +407 -701
  66. elevation-2.0.0rc2/PKG-INFO +0 -266
  67. elevation-2.0.0rc2/README.md +0 -232
  68. elevation-2.0.0rc2/docs/migration.md +0 -57
  69. elevation-2.0.0rc2/elevation/datasource.mk +0 -61
  70. elevation-2.0.0rc2/elevation/datasource.py +0 -387
  71. elevation-2.0.0rc2/elevation/spatial.py +0 -49
  72. elevation-2.0.0rc2/elevation/util.py +0 -118
  73. elevation-2.0.0rc2/elevation.egg-info/PKG-INFO +0 -266
  74. elevation-2.0.0rc2/elevation.egg-info/SOURCES.txt +0 -63
  75. elevation-2.0.0rc2/elevation.egg-info/requires.txt +0 -7
  76. elevation-2.0.0rc2/elevation.egg-info/scm_file_list.json +0 -58
  77. elevation-2.0.0rc2/elevation.egg-info/scm_version.json +0 -8
  78. elevation-2.0.0rc2/tests/test_10_util.py +0 -65
  79. elevation-2.0.0rc2/tests/test_20_datasource.py +0 -187
  80. elevation-2.0.0rc2/tests/test_40_main.py +0 -144
  81. {elevation-2.0.0rc2 → elevation-2.0.1}/.github/dependabot.yml +0 -0
  82. {elevation-2.0.0rc2 → elevation-2.0.1}/.gitignore +0 -0
  83. {elevation-2.0.0rc2 → elevation-2.0.1}/.pre-commit-config.yaml +0 -0
  84. {elevation-2.0.0rc2 → elevation-2.0.1}/.python-version +0 -0
  85. {elevation-2.0.0rc2 → elevation-2.0.1}/CONTRIBUTING.rst +0 -0
  86. {elevation-2.0.0rc2 → elevation-2.0.1}/LICENSE +0 -0
  87. {elevation-2.0.0rc2 → elevation-2.0.1}/docs/_static/.gitkeep +0 -0
  88. {elevation-2.0.0rc2 → elevation-2.0.1}/docs/_templates/.gitkeep +0 -0
  89. {elevation-2.0.0rc2 → elevation-2.0.1}/docs/design.md +0 -0
  90. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation/py.typed +0 -0
  91. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation.egg-info/dependency_links.txt +0 -0
  92. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation.egg-info/entry_points.txt +0 -0
  93. {elevation-2.0.0rc2 → elevation-2.0.1}/elevation.egg-info/top_level.txt +0 -0
  94. {elevation-2.0.0rc2 → elevation-2.0.1}/setup.cfg +0 -0
  95. {elevation-2.0.0rc2/tests/data/srtm1_geoid → elevation-2.0.1/tests/data/MAPZEN}/ne_rome.tif +0 -0
  96. {elevation-2.0.0rc2/tests/data/terrain_tiles → elevation-2.0.1/tests/data/MAPZEN}/nw_iceland.tif +0 -0
  97. {elevation-2.0.0rc2/tests/data/terrain_tiles → elevation-2.0.1/tests/data/MAPZEN}/nw_san_francisco.tif +0 -0
  98. {elevation-2.0.0rc2/tests/data/terrain_tiles → elevation-2.0.1/tests/data/MAPZEN}/se_sydney.tif +0 -0
  99. {elevation-2.0.0rc2/tests/data/terrain_tiles → elevation-2.0.1/tests/data/MAPZEN}/sw_santiago.tif +0 -0
  100. {elevation-2.0.0rc2/tests/data/srtm1_ellip → elevation-2.0.1/tests/data/SRTM1_ELLIP}/ne_rome.tif +0 -0
  101. {elevation-2.0.0rc2/tests/data/srtm1_ellip → elevation-2.0.1/tests/data/SRTM1_ELLIP}/nw_bogota.tif +0 -0
  102. {elevation-2.0.0rc2/tests/data/srtm1_ellip → elevation-2.0.1/tests/data/SRTM1_ELLIP}/nw_san_francisco.tif +0 -0
  103. {elevation-2.0.0rc2/tests/data/srtm1_ellip → elevation-2.0.1/tests/data/SRTM1_ELLIP}/se_sydney.tif +0 -0
  104. {elevation-2.0.0rc2/tests/data/srtm1_ellip → elevation-2.0.1/tests/data/SRTM1_ELLIP}/sw_santiago.tif +0 -0
  105. {elevation-2.0.0rc2/tests/data/terrain_tiles → elevation-2.0.1/tests/data/SRTM1_GEOID}/ne_rome.tif +0 -0
  106. {elevation-2.0.0rc2/tests/data/srtm1_geoid → elevation-2.0.1/tests/data/SRTM1_GEOID}/nw_san_francisco.tif +0 -0
  107. {elevation-2.0.0rc2/tests/data/srtm1_geoid → elevation-2.0.1/tests/data/SRTM1_GEOID}/se_sydney.tif +0 -0
  108. {elevation-2.0.0rc2/tests/data/srtm1_geoid → elevation-2.0.1/tests/data/SRTM1_GEOID}/sw_santiago.tif +0 -0
  109. {elevation-2.0.0rc2/tests/data/srtm3 → elevation-2.0.1/tests/data/SRTM3}/ne_rome.tif +0 -0
  110. {elevation-2.0.0rc2/tests/data/srtm3 → elevation-2.0.1/tests/data/SRTM3}/nw_san_francisco.tif +0 -0
  111. {elevation-2.0.0rc2/tests/data/srtm3 → elevation-2.0.1/tests/data/SRTM3}/se_sydney.tif +0 -0
  112. {elevation-2.0.0rc2/tests/data/srtm3 → elevation-2.0.1/tests/data/SRTM3}/sw_santiago.tif +0 -0
  113. {elevation-2.0.0rc2 → elevation-2.0.1}/tests/test_00_version.py +0 -0
@@ -14,10 +14,6 @@ concurrency:
14
14
  group: ${{ github.workflow }}-${{ github.ref }}
15
15
  cancel-in-progress: true
16
16
 
17
- defaults:
18
- run:
19
- shell: bash -l {0}
20
-
21
17
  jobs:
22
18
  pre-commit:
23
19
  runs-on: ubuntu-latest
@@ -29,7 +25,6 @@ jobs:
29
25
  - uses: pre-commit/action@v3.0.1
30
26
 
31
27
  unit-tests:
32
- name: unit-tests
33
28
  runs-on: ubuntu-latest
34
29
  strategy:
35
30
  matrix:
@@ -44,11 +39,41 @@ jobs:
44
39
  - name: Install uv and set the python version
45
40
  uses: astral-sh/setup-uv@v7
46
41
  with:
47
- version: '0.11.17'
42
+ version: '0.13.4'
48
43
  enable-cache: true
49
44
  python-version: ${{ matrix.python-version }}
50
45
 
46
+ - name: Install the GDAL command line tools
47
+ run: sudo apt-get update && sudo apt-get install -y gdal-bin
48
+
49
+ - name: Run unit tests
50
+ run: make unit-tests COV_REPORT=xml
51
+
52
+ unit-tests-windows:
53
+ runs-on: windows-latest
54
+
55
+ steps:
56
+ - uses: actions/checkout@v7
57
+
58
+ - name: Install the GDAL command line tools and make
59
+ uses: mamba-org/setup-micromamba@v3
60
+ with:
61
+ environment-name: gdal
62
+ create-args: >-
63
+ gdal
64
+ make
65
+ init-shell: bash
66
+ cache-environment: true
67
+
68
+ - name: Install uv and set the python version
69
+ uses: astral-sh/setup-uv@v7
70
+ with:
71
+ version: '0.13.4'
72
+ enable-cache: true
73
+ python-version: '3.14'
74
+
51
75
  - name: Run unit tests
76
+ shell: bash -el {0}
52
77
  run: make unit-tests COV_REPORT=xml
53
78
 
54
79
  check-typing:
@@ -60,7 +85,7 @@ jobs:
60
85
  - name: Install uv and set the python version
61
86
  uses: astral-sh/setup-uv@v7
62
87
  with:
63
- version: '0.11.17'
88
+ version: '0.13.4'
64
89
  enable-cache: true
65
90
  python-version: '3.14'
66
91
  - name: Run type checks
@@ -75,7 +100,7 @@ jobs:
75
100
  - name: Install uv
76
101
  uses: astral-sh/setup-uv@v7
77
102
  with:
78
- version: '0.11.17'
103
+ version: '0.13.4'
79
104
  enable-cache: true
80
105
  python-version: '3.14'
81
106
  - name: Build documentation
@@ -91,20 +116,19 @@ jobs:
91
116
  - name: Install uv and set the python version
92
117
  uses: astral-sh/setup-uv@v7
93
118
  with:
94
- version: '0.11.17'
119
+ version: '0.13.4'
95
120
  enable-cache: true
96
121
  python-version: '3.14'
122
+
123
+ - name: Install the GDAL command line tools
124
+ run: sudo apt-get update && sudo apt-get install -y gdal-bin
125
+
97
126
  - name: Run tests
98
127
  run: make minver-tests
99
128
 
100
129
  distribution:
101
130
  runs-on: ubuntu-latest
102
- needs: [unit-tests, check-typing, docs-build]
103
- if: |
104
- always() &&
105
- needs.unit-tests.result == 'success' &&
106
- needs.check-typing.result == 'success' &&
107
- needs.docs-build.result == 'success'
131
+ needs: [unit-tests, unit-tests-windows, check-typing, docs-build, minver-tests]
108
132
 
109
133
  steps:
110
134
  - uses: actions/checkout@v7
@@ -119,12 +143,11 @@ jobs:
119
143
  run: |
120
144
  python -m build
121
145
  - name: Check wheels
146
+ working-directory: dist
122
147
  run: |
123
- cd dist || exit
124
- python -m pip install elevation*.whl || exit
125
- python -m twine check --strict * || exit
126
- python -c "import elevation" || exit
127
- cd ..
148
+ python -m pip install elevation*.whl
149
+ python -m twine check --strict *
150
+ python -c "import elevation"
128
151
  - uses: actions/upload-artifact@v7
129
152
  with:
130
153
  name: distribution
@@ -134,7 +157,7 @@ jobs:
134
157
  runs-on: ubuntu-latest
135
158
  needs: distribution
136
159
  if: |
137
- always() && true &&
160
+ always() &&
138
161
  needs.distribution.result == 'success' &&
139
162
  github.event_name == 'push' &&
140
163
  startsWith(github.ref, 'refs/tags')
@@ -0,0 +1,22 @@
1
+ version: 2
2
+
3
+ build:
4
+ os: ubuntu-24.04
5
+ tools:
6
+ python: '3.14'
7
+ jobs:
8
+ post_checkout:
9
+ # setuptools_scm needs the history and the tags to compute the version
10
+ - git fetch --unshallow --tags || true
11
+ pre_create_environment:
12
+ - asdf plugin add uv
13
+ - asdf install uv latest
14
+ - asdf global uv latest
15
+ create_environment:
16
+ - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
17
+ install:
18
+ - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen
19
+
20
+ sphinx:
21
+ configuration: docs/conf.py
22
+ fail_on_warning: true
@@ -1,36 +1,70 @@
1
1
 
2
- 2.0.0rc2 (unreleased)
2
+ 2.0.0 (unreleased)
3
3
  ---------------------
4
4
 
5
5
  - Honour the ``EIO_CACHE_DIR`` environment variable in the Python API, not only in the
6
6
  ``eio`` command line.
7
- - Add the ``--make_options`` option and the ``EIO_MAKE_OPTIONS`` variable to pass options
8
- through to every ``make`` invocation.
7
+ - Replace the datasource ``Makefile`` with Python: tiles are read remotely through
8
+ GDAL ``/vsicurl/`` and written to the cache and clipped with ``gdal_translate``,
9
+ the mosaic is still built with ``gdalbuildvrt``.
10
+ - Drop the ``make``, ``curl``, ``unzip`` and ``gunzip`` dependencies: tile downloads are
11
+ now sequential.
12
+ - Make caching the tiles missing upstream, e.g. ocean tiles, more robust.
13
+ - Drop the ``reference`` optional dependencies: the bounds of a reference data source
14
+ are read with the ``gdalinfo`` and ``ogrinfo`` command line tools.
15
+ - Replace the unmaintained ``appdirs`` dependency with ``platformdirs``: the default
16
+ cache folder is unchanged, except that recent ``platformdirs`` versions honour
17
+ ``XDG_CACHE_HOME`` on macOS.
18
+ - Add the ``--gdal-options`` option and the ``EIO_CLIP_GDAL_OPTIONS`` variable to pass
19
+ GDAL creation options, e.g. ``-co COMPRESS=LZW``, to the clip.
9
20
  - Download the original SRTM GL1 data from OpenTopography for the ``SRTM1_GEOID`` product.
10
- - Add the ``TERRAIN_TILES`` product for the global Mapzen terrain tiles mosaic and make
21
+ - Add the ``MAPZEN`` product for the global Mapzen terrain tiles mosaic and make
11
22
  it the default product.
23
+ - Add the ``GLO-30`` and ``GLO-90`` products for the Copernicus DEM global 30m and 90m
24
+ DSM on the EGM2008 geoid. They are distributed by the Earth Data Hub as a cloud-hosted
25
+ Zarr store that is read in place, one chunk at a time, and cached as GeoTIFF tiles
26
+ like the other products, so the credentials in ``~/.netrc`` are used and GDAL 3.8 or
27
+ later is required.
28
+ - Add the ``AW3D30`` product for the ALOS World 3D global 30m v3.2 DSM on the EGM96
29
+ geoid, distributed by OpenTopography.
12
30
  - Retire the ``SRTM1`` product name: requesting it raises an error pointing to the
13
31
  migration notes.
14
32
  - Accept ``str`` or ``Path`` for all path-valued arguments.
33
+ - Support cache and output paths with spaces.
15
34
  - Resolve relative ``output`` and cache folder paths against the current working
16
35
  directory.
17
-
18
-
19
- 2.0.0rc1 (2026-09-28)
20
- ---------------------
21
-
36
+ - Expand ``~`` to the user home in the cache folder path, e.g. in ``EIO_CACHE_DIR``.
37
+ - Add the ``eio dataset`` command and the ``elevation.dataset`` function to show the
38
+ STAC metadata of the datasets.
39
+ - Add the ``--verbose`` option to ``eio selfcheck`` to show the tools as they are tested.
40
+ - Add the ``--margin`` option to ``eio seed`` and the ``margin`` argument to
41
+ ``elevation.seed``.
42
+ - Add the ``--max_download_tiles`` option and the ``EIO_SEED_MAX_DOWNLOAD_TILES``
43
+ and ``EIO_CLIP_MAX_DOWNLOAD_TILES`` variables to the ``seed`` and ``clip``
44
+ commands to limit the number of tiles to download, counting only the tiles that
45
+ are not cached yet; the default is raised from 9 to 25.
22
46
  - Drop support for Python 3.6-3.10: only Python >= 3.11 is supported.
23
47
  - Move the packaging metadata to ``pyproject.toml`` and remove ``setup.py``
24
48
  and ``setup.cfg``.
25
- - Manage the development environment and dependencies with ``uv`` and add a
26
- ``Makefile`` with ``qa``, ``unit-tests``, ``check-typing``, ``docs-build``
27
- and ``minver-tests`` targets.
49
+ - Manage the development environment and dependencies with ``uv`` and a ``Makefile``.
28
50
  - Replace ``black``, ``isort`` and ``flake8`` with ``ruff`` and add ``mypy``
29
51
  strict type checking.
30
- - Add lower bounds to the dependencies, pinned to versions available in 2022.
52
+ - Add lower bounds to the dependencies, checked by the ``minver-tests`` job.
31
53
  - Build the documentation with Sphinx through ``make docs-build``.
32
- - Modernise the CI with uv-based jobs, pre-commit checks and a PyPI
33
- trusted-publishing release job.
54
+ - Modernise the CI with uv-based jobs, pre-commit checks, a Windows unit-tests job
55
+ and a PyPI trusted-publishing release job.
56
+
57
+
58
+ 1.1.4 (2026-09-30)
59
+ ------------------
60
+
61
+ - Document that the ``SRTM1`` product name is a misnomer and that it downloads
62
+ the Terrain Tiles dataset, not the official SRTM GL1 one.
63
+ - Fix the ``eio distclean`` crash when the cache holds sub-folders.
64
+ - Fix the ``eio clip`` crash when neither ``--bounds`` nor ``--reference`` is given.
65
+ - Resolve a relative ``output`` against the current working directory.
66
+ - Fix the VRT mutex in ``clip``: ``do_clip`` locked the wrong file unless ``product``
67
+ was passed explicitly.
34
68
 
35
69
 
36
70
  1.1.3 (2021-04-08)
@@ -105,7 +139,7 @@
105
139
  -------------------
106
140
 
107
141
  - Revert the default product back to ``SRTM1`` by downloading from the
108
- `Amazon Terrain Tiles on AWS service <https://aws.amazon.com/public-data-sets/terrain>`_.
142
+ `Amazon Terrain Tiles on AWS service <https://aws.amazon.com/public-data-sets/terrain>`_.
109
143
  Closes issue `#18 <https://github.com/bopen/elevation/issues/18>`_.
110
144
 
111
145
 
@@ -2,7 +2,7 @@ cff-version: 1.2.0
2
2
  message: "If you use this software, please cite it as below."
3
3
  type: software
4
4
  title: elevation
5
- abstract: "Download, cache and clip global terrain digital elevation models: Terrain Tiles, SRTM 30m, SRTM 90m and SRTM GL1 ellipsoidal DEMs."
5
+ abstract: "Download, cache and clip global terrain digital elevation models: Mapzen terrain tiles, Copernicus DEM, ALOS World 3D and SRTM 30m and 90m DEMs."
6
6
  authors:
7
7
  - family-names: Amici
8
8
  given-names: Alessandro
@@ -11,10 +11,12 @@ authors:
11
11
  website: "https://linkedin.com/in/alexamici"
12
12
  - name: "B-Open"
13
13
  website: "https://bopen.eu"
14
+ doi: 10.5281/zenodo.23065529
14
15
  repository-code: "https://github.com/bopen/elevation"
15
16
  url: "https://elevation.bopen.eu"
16
17
  license: Apache-2.0
17
18
  keywords:
19
+ - Copernicus DEM
18
20
  - DEM
19
21
  - DTM
20
22
  - SRTM
@@ -10,7 +10,10 @@ unit-tests:
10
10
  $(PYTHON) -m pytest -vv --cov=. --cov-report=$(COV_REPORT)
11
11
 
12
12
  integration-tests:
13
- $(PYTHON) -m pytest -vv tests/integration*.py
13
+ $(PYTHON) -m pytest -vv --cov=. --cov-report=$(COV_REPORT) tests/integration*.py
14
+
15
+ all-tests:
16
+ $(PYTHON) -m pytest -vv -n auto --cov=. --cov-report=$(COV_REPORT) tests/test*.py tests/integration*.py
14
17
 
15
18
  check-typing:
16
19
  $(PYTHON) -m mypy .
@@ -0,0 +1,353 @@
1
+ Metadata-Version: 2.4
2
+ Name: elevation
3
+ Version: 2.0.1
4
+ Summary: Download, cache and clip global terrain digital elevation models: Mapzen terrain tiles, Copernicus DEM, ALOS World 3D and SRTM 30m and 90m DEMs.
5
+ Author: Alessandro Amici, B-Open
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://elevation.bopen.eu
8
+ Project-URL: Repository, https://github.com/bopen/elevation
9
+ Project-URL: Sponsor, https://bopen.eu
10
+ Keywords: Copernicus DEM,DEM,DTM,SRTM,digital elevation,download,geospatial,global,terrain model,terrain tiles
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Programming Language :: Python :: Implementation :: CPython
23
+ Classifier: Topic :: Scientific/Engineering :: GIS
24
+ Requires-Python: >=3.11
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Requires-Dist: fasteners>=0.18
28
+ Requires-Dist: platformdirs>=2.6.0
29
+ Requires-Dist: typer>=0.26.7
30
+ Dynamic: license-file
31
+
32
+ # elevation
33
+
34
+ Global geographic elevation data made easy.
35
+
36
+ > **Upgrading from 1.x?** *elevation* 2.0 is not fully backward compatible,
37
+ > read the [migration guide](https://elevation.bopen.eu/en/stable/migration.html).
38
+
39
+ Elevation provides easy download, cache and access of the global datasets:
40
+
41
+ - `MAPZEN`: [Terrain Tiles global 30m v1](https://registry.opendata.aws/terrain-tiles/)
42
+ assembled by Mapzen from several open data providers and hosted on [Amazon](https://aws.amazon.com/public-data-sets/terrain),
43
+ with 30m heights on the EGM96 geoid,
44
+ includes data from NASA/NGA SRTM, USGS 3DEP, EUDEM, ArcticDEM, GMTED2010 and ETOPO1.
45
+ - `GLO-30`: [Copernicus DEM global 30m (2021)](https://doi.org/10.5270/ESA-c5d3d65)
46
+ produced by ESA and the European Union and hosted on [Earth Data Hub](https://earthdatahub.destine.eu/collections/copernicus-dem), with 30m heights on the EGM2008 geoid.
47
+ - `AW3D30`: [ALOS World 3D global 30m v3.2](https://doi.org/10.5069/G94M92HB)
48
+ produced by JAXA and hosted on [OpenTopography](https://portal.opentopography.org/raster?opentopoID=OTALOS.112016.4326.2),
49
+ with 30m heights on the EGM96 geoid.
50
+ - `SRTM1_GEOID`: [SRTM global 30m v3](https://lpdaac.usgs.gov/products/srtmgl1nv003/)
51
+ produced by NASA and NGA hosted on [OpenTopography](https://portal.opentopography.org/raster?opentopoID=OTSRTM.082015.4326.1),
52
+ with 30m heights on the EGM96 geoid.
53
+ - `SRTM1_ELLIP`: [SRTM global 30m v3 ellipsoidal](https://portal.opentopography.org/raster?opentopoID=OTSRTM.082016.4326.1)
54
+ the companion of `SRTM1_GEOID`, with 30m heights on the WGS84 ellipsoid.
55
+ - `GLO-90`: [Copernicus DEM global 90m (2021)](https://doi.org/10.5270/ESA-c5d3d65)
56
+ the 90m companion of `GLO-30`.
57
+ - `SRTM3`: [SRTM global 90m v4.1](https://bigdata.cgiar.org/srtm-90m-digital-elevation-database/)
58
+ produced and hosted by CGIAR-CSI, with 90m heights on the EGM96 geoid.
59
+
60
+ Note that any download policies and attribution requirements of the respective providers apply.
61
+
62
+ This Open Source project is sponsored by B-Open - <https://bopen.eu>.
63
+
64
+ ## Installation
65
+
66
+ Install the [latest version of Elevation](https://pypi.org/project/elevation)
67
+ from the Python Package Index:
68
+
69
+ ```console
70
+ $ pip install elevation
71
+ ```
72
+
73
+ The following dependencies need to be installed and working:
74
+
75
+ - [GDAL](https://www.gdal.org/) command line tools, i.e. `gdal_translate`, `gdalbuildvrt`,
76
+ `gdalinfo` and `ogrinfo`
77
+
78
+ The following command runs some basic checks and reports common issues:
79
+
80
+ ```console
81
+ $ eio selfcheck --verbose
82
+ Checking 'gdal_translate' ...
83
+ Checking 'gdalbuildvrt' ...
84
+ Checking 'gdalinfo' ...
85
+ Checking 'ogrinfo' ...
86
+ Your system is ready.
87
+ ```
88
+
89
+ The best way to install GDAL command line tools varies across operating systems
90
+ and distributions, please refer to the
91
+ [GDAL install documentation](https://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries).
92
+
93
+ Note that *elevation* v2.0 requires Python 3.11 or later.
94
+
95
+ Our target platforms are Linux and MacOS. Windows is only lightly tested.
96
+
97
+ ## Command line usage
98
+
99
+ Identify the geographic bounds of the area of interest and fetch the DEM with the `eio` command.
100
+ For example to clip the 30m DEM of Rome, around 41.9N 12.5E, to the `Rome-MAPZEN-DEM.tif` file
101
+ using the default `MAPZEN` product:
102
+
103
+ ```console
104
+ $ eio clip -o Rome-MAPZEN-DEM.tif --bounds 12.35 41.8 12.65 42
105
+ ```
106
+
107
+ For the Copernicus DEM global 30m or 90m DEMs use:
108
+
109
+ ```console
110
+ $ eio --product GLO-30 clip -o Rome-GLO-30-DEM.tif --bounds 12.35 41.8 12.65 42
111
+ $ eio --product GLO-90 clip -o Rome-GLO-90-DEM.tif --bounds 12.35 41.8 12.65 42
112
+ ```
113
+
114
+ The `GLO-30` and `GLO-90` products are distributed by the Earth Data Hub as a
115
+ single cloud-hosted Zarr store that is read in place and cached one chunk at a
116
+ time instead of downloading whole tiles, and the credentials of the account
117
+ stored in `~/.netrc` are used to access it:
118
+
119
+ ```console
120
+ machine data.earthdatahub.destine.eu
121
+ password <your EDH API key>
122
+ ```
123
+
124
+ See the Earth Data Hub [Getting started](https://earthdatahub.destine.eu/getting-started)
125
+ page to create an account and set up the credentials.
126
+
127
+ Reading the store needs GDAL 3.8 or later.
128
+
129
+ For the ALOS World 3D global 30m v3.2 DEM use:
130
+
131
+ ```console
132
+ $ eio --product AW3D30 clip -o Rome-AW3D30-DEM.tif --bounds 12.35 41.8 12.65 42
133
+ ```
134
+
135
+ For the SRTM global 30m v3 geoid or ellipsoidal DEMs use:
136
+
137
+ ```console
138
+ $ eio --product SRTM1_GEOID clip -o Rome-SRTM1_GEOID-DEM.tif --bounds 12.35 41.8 12.65 42
139
+ $ eio --product SRTM1_ELLIP clip -o Rome-SRTM1_ELLIP-DEM.tif --bounds 12.35 41.8 12.65 42
140
+ ```
141
+
142
+ For the SRTM global 90m v4.1 DEM use:
143
+
144
+ ```console
145
+ $ eio --product SRTM3 clip -o Rome-SRTM3-DEM.tif --bounds 12.35 41.8 12.65 42
146
+ ```
147
+
148
+ The `--bounds` option accepts latitude and longitude coordinates
149
+ (more precisely in geodetic coordinates in the WGS84 reference system EPSG:4326 for those who care)
150
+ given as `left bottom right top`.
151
+
152
+ The `--reference` option clips a DEM on the same extent of any other geospatial data source
153
+ supported by GDAL and OGR, for example if you have a georeferenced image `MyImage.tif`
154
+ you can clip the corresponding DEM with:
155
+
156
+ ```console
157
+ $ eio clip -o MyImage-DEM.tif --reference MyImage.tif
158
+ ```
159
+
160
+ The `--reference` option can also take vector data as input:
161
+
162
+ ```console
163
+ $ eio clip -o MyShapefile-DEM.tif --reference MyShapefile.shp
164
+ ```
165
+
166
+ The first time an area is accessed Elevation downloads the data tiles from
167
+ the AWS S3, CGIAR-CSI, OpenTopography or Earth Data Hub servers and
168
+ caches them in GeoTIFF compressed formats,
169
+ subsequent accesses to the same and nearby areas are much faster.
170
+
171
+ The `seed` and `clip` sub-commands refuse to download more than `--max_download_tiles`
172
+ (`25` by default) tiles at a time to prevent bulk downloads,
173
+ please refer to the upstream providers' websites to learn the preferred procedures for bulk download.
174
+
175
+ To show the STAC metadata of the datasets use:
176
+
177
+ ```console
178
+ $ eio dataset
179
+ ```
180
+
181
+ The optional argument selects a single dataset by id, e.g. `eio dataset SRTM3`.
182
+
183
+ To show info about the product cache use:
184
+
185
+ ```console
186
+ $ eio info
187
+ ```
188
+
189
+ To clean up the product cache from temporary files use:
190
+
191
+ ```console
192
+ $ eio clean
193
+ ```
194
+
195
+ To remove the product cache entirely use:
196
+
197
+ ```console
198
+ $ eio distclean
199
+ ```
200
+
201
+ ## Command line reference
202
+
203
+ The `eio` command has the following sub-commands and options:
204
+
205
+ ```text
206
+ $ eio --help
207
+
208
+ Usage: eio [OPTIONS] COMMAND [ARGS]...
209
+
210
+ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
211
+ │ --version Show the version and exit. │
212
+ │ [env var: EIO_VERSION] │
213
+ │ --product [MAPZEN|GLO-30|AW3D30|SRTM1_GEOID|SRT DEM product choice. │
214
+ │ M1_ELLIP|GLO-90|SRTM3] [env var: EIO_PRODUCT] │
215
+ │ [default: MAPZEN] │
216
+ │ --cache_dir <directory> Root of the DEM cache folder. │
217
+ │ [env var: EIO_CACHE_DIR] │
218
+ │ [default: <user cache folder>] │
219
+ │ --help Show this message and exit. │
220
+ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
221
+ ╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
222
+ │ selfcheck Audit the system for common issues. │
223
+ │ info Show info about the product cache. │
224
+ │ dataset Show the STAC metadata of the datasets. │
225
+ │ seed Seed the DEM to given bounds. │
226
+ │ clip Clip the DEM to given bounds. │
227
+ │ clean Clean up the product cache from temporary files. │
228
+ │ distclean Remove the product cache entirely. │
229
+ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
230
+ ```
231
+
232
+ The `clip` sub-command:
233
+
234
+ ```text
235
+ $ eio clip --help
236
+
237
+ Usage: eio clip [OPTIONS]
238
+
239
+ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
240
+ │ --output -o <file> Path to output file. Existing files │
241
+ │ will be overwritten. │
242
+ │ [env var: EIO_CLIP_OUTPUT] │
243
+ │ [default: out.tif] │
244
+ │ --bounds <float float float float>... Output bounds in 'left bottom right │
245
+ │ top' order. │
246
+ │ [env var: EIO_CLIP_BOUNDS] │
247
+ │ --margin -m <str> Decimal degree margin added to the │
248
+ │ bounds. Use '%' for percent margin. │
249
+ │ [env var: EIO_CLIP_MARGIN] │
250
+ │ [default: 0] │
251
+ │ --reference -r <path> Use the extent of a reference │
252
+ │ GDAL/OGR data source as output │
253
+ │ bounds. │
254
+ │ [env var: EIO_CLIP_REFERENCE] │
255
+ │ --gdal-options <str> GDAL creation options of the output │
256
+ │ file, e.g. '-co COMPRESS=LZW'. │
257
+ │ [env var: EIO_CLIP_GDAL_OPTIONS] │
258
+ │ [default: -co TILED=YES -co │
259
+ │ COMPRESS=DEFLATE -co ZLEVEL=9 -co │
260
+ │ NUM_THREADS=ALL_CPUS] │
261
+ │ --max_download_tiles <int> Maximum number of tiles to download. │
262
+ │ [env var: │
263
+ │ EIO_CLIP_MAX_DOWNLOAD_TILES] │
264
+ │ [default: 25] │
265
+ │ --help Show this message and exit. │
266
+ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
267
+ ```
268
+
269
+ The `seed` sub-command downloads and caches the tiles that cover the bounds
270
+ without producing any output file:
271
+
272
+ ```text
273
+ $ eio seed --help
274
+
275
+ Usage: eio seed [OPTIONS]
276
+
277
+ ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────╮
278
+ │ --bounds <float float float float>... Output bounds in 'left bottom right │
279
+ │ top' order. │
280
+ │ [env var: EIO_SEED_BOUNDS] │
281
+ │ --margin -m <str> Decimal degree margin added to the │
282
+ │ bounds. Use '%' for percent margin. │
283
+ │ [env var: EIO_SEED_MARGIN] │
284
+ │ [default: 0] │
285
+ │ --max_download_tiles <int> Maximum number of tiles to download. │
286
+ │ [env var: │
287
+ │ EIO_SEED_MAX_DOWNLOAD_TILES] │
288
+ │ [default: 25] │
289
+ │ --help Show this message and exit. │
290
+ ╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
291
+ ```
292
+
293
+ Defaults can be defined by setting environment variables prefixed with `EIO`,
294
+ e.g. `EIO_PRODUCT=SRTM3`, `EIO_CLIP_MARGIN=10%` and `EIO_CACHE_DIR=/tmp/elevation`.
295
+ `EIO_CACHE_DIR` selects the DEM cache folder and is honoured by the Python API as well.
296
+ The default is the `elevation` folder of the operating system user cache directory.
297
+
298
+ ## Python API
299
+
300
+ Every command has a corresponding API function in the `elevation` module:
301
+
302
+ ```python
303
+ >>> import elevation
304
+ >>> # clip the 30m DEM of Rome and save it to Rome-DEM.tif
305
+ >>> elevation.clip(bounds=(12.35, 41.8, 12.65, 42), output="Rome-DEM.tif")
306
+ >>> # clean up the product cache from temporary files
307
+ >>> elevation.clean()
308
+
309
+ ```
310
+
311
+ ## Project resources
312
+
313
+ | Resource | Link |
314
+ | --- | --- |
315
+ | Documentation | <https://elevation.bopen.eu> |
316
+ | Development | <https://github.com/bopen/elevation> |
317
+ | Download | <https://pypi.org/project/elevation> |
318
+
319
+ ## Contributing
320
+
321
+ The main repository is hosted on GitHub.
322
+ Testing, bug reports and contributions are highly welcomed and appreciated:
323
+
324
+ https://github.com/bopen/elevation
325
+
326
+ Lead developer:
327
+
328
+ - [Alessandro Amici](https://github.com/alexamici) - [B-Open](https://bopen.eu)
329
+
330
+ See also the list of [contributors](https://github.com/bopen/elevation/contributors) who participated in this project.
331
+
332
+ ## Sponsoring
333
+
334
+ [B-Open](https://bopen.eu) commits to maintain the project long term and we are
335
+ happy to accept sponsorships to develop new features.
336
+
337
+ ## License
338
+
339
+ ```
340
+ Copyright 2016-2026 B-Open Solutions srl
341
+
342
+ Licensed under the Apache License, Version 2.0 (the "License");
343
+ you may not use this file except in compliance with the License.
344
+ You may obtain a copy of the License at
345
+
346
+ http://www.apache.org/licenses/LICENSE-2.0
347
+
348
+ Unless required by applicable law or agreed to in writing, software
349
+ distributed under the License is distributed on an "AS IS" BASIS,
350
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
351
+ See the License for the specific language governing permissions and
352
+ limitations under the License.
353
+ ```