gemf-map 1.0.2__tar.gz → 1.0.4__tar.gz

{gemf_map-1.0.2 → gemf_map-1.0.4}/.gitignore

@@ -158,9 +158,9 @@ dmypy.json
 cython_debug/
 
 # custom
+notes.md
 dev/
 docs/build/
-docs/source/
 data/
 external/
 tests/test_output/

{gemf_map-1.0.2 → gemf_map-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemf_map
-Version: 1.0.2
+Version: 1.0.4
 Summary: Python library for reading and writing GEMF map tile files.
 Project-URL: Homepage, https://github.com/ColinMoldenhauer/GEMF
 Project-URL: Documentation, https://gemf.readthedocs.io
@@ -22,12 +22,12 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.9
 Requires-Dist: mercantile
 Requires-Dist: numpy
+Requires-Dist: pillow
 Provides-Extra: all
 Requires-Dist: folium; extra == 'all'
 Requires-Dist: matplotlib; extra == 'all'
 Requires-Dist: mkdocs-material; extra == 'all'
 Requires-Dist: mkdocstrings[python]; extra == 'all'
-Requires-Dist: pillow; extra == 'all'
 Requires-Dist: pytest-cov; extra == 'all'
 Requires-Dist: pytest>=8.0; extra == 'all'
 Requires-Dist: shapely; extra == 'all'
@@ -39,7 +39,6 @@ Requires-Dist: shapely; extra == 'geometry'
 Provides-Extra: plot
 Requires-Dist: folium; extra == 'plot'
 Requires-Dist: matplotlib; extra == 'plot'
-Requires-Dist: pillow; extra == 'plot'
 Provides-Extra: test
 Requires-Dist: pytest-cov; extra == 'test'
 Requires-Dist: pytest>=8.0; extra == 'test'
@@ -71,13 +70,12 @@ pip install gemf-map
 - spatially subset (crop) a .gemf file
 - extracting image tiles from binary `.gemf` files via the `save_tiles()` method
 - adding tiles to an existing `.gemf` file (TODO)
+- combining `GEMF` objects via `stack()`/`+`, `merge()`/`|`, `intersect()`/`&` and `difference()`/`-`
 
 **Visualization features**:
 - show the tiles of a .gemf file on a `folium` map
 - show tile boundaries on a map
 
-<!-- TODO: explain lazy laoding -->
-
 # Usage
 
 ## Core
@@ -97,12 +95,57 @@ new_gemf = GEMF.from_tiles("PATH/TO/TILEDIR")
 new_gemf.write("PATH/TO/GEMF_FILE.gemf")
 ```
 
+## Lazy loading
+`GEMF.from_file()` and `GEMF.from_tiles()` accept a `lazy` argument (default `False`).
+
+With `lazy=False` (the default), the per-tile range details (location and size of every
+tile's data) are read/computed immediately. This gives access to the full range of
+features, but may take a while for files with a large number of tiles.
+
+With `lazy=True`, this step is skipped. The following are available right away without
+extra loading:
+- `gemf.num_sources`
+- `gemf.num_tiles`
+- `gemf.get_zoom_levels()`
+- inspecting `gemf.header.range_data` (the per-zoom-level bounding boxes)
+
+Any operation that needs per-tile data (e.g. `save_tiles()`, `write()`, `crop()`,
+`set_tile()`, the arithmetic operators) raises `DetailsNotLoadedError` on a lazily loaded
+`GEMF`. Call `gemf.load_details()` first to load the range details on demand:
+
+```python
+my_gemf = GEMF.from_file("MY_GEMF.gemf", lazy=True)
+
+# cheap, available immediately
+print(my_gemf.num_tiles)
+
+# load range details before performing per-tile operations
+my_gemf.load_details()
+my_gemf.save_tiles("PATH/TO/TILEDIR")
+```
+
 ## Manipulation
 ```python
 # crop to bounding box (all zoom levels will be cropped accordingly)
 gemf_crop = my_gemf.crop(7, 60, 62, 36, 38)
 ```
 
+## Combining GEMF objects
+```python
+# stack: add all sources of gemf2 onto gemf1 as new sources
+combined = gemf1 + gemf2
+
+# merge: union of tiles for sources present in both (matched by name)
+# on conflicting tiles, "|" keeps gemf1's tile by default
+merged = gemf1 | gemf2
+
+# intersect: keep only tiles present in both, for shared sources
+shared = gemf1 & gemf2
+
+# difference: keep gemf1's tiles that are not present in gemf2's matching source
+diff = gemf1 - gemf2
+```
+
 
 ## Visualization
 <!-- TODO: limitations for large gemf files -->

{gemf_map-1.0.2 → gemf_map-1.0.4}/README.md

@@ -24,13 +24,12 @@ pip install gemf-map
 - spatially subset (crop) a .gemf file
 - extracting image tiles from binary `.gemf` files via the `save_tiles()` method
 - adding tiles to an existing `.gemf` file (TODO)
+- combining `GEMF` objects via `stack()`/`+`, `merge()`/`|`, `intersect()`/`&` and `difference()`/`-`
 
 **Visualization features**:
 - show the tiles of a .gemf file on a `folium` map
 - show tile boundaries on a map
 
-<!-- TODO: explain lazy laoding -->
-
 # Usage
 
 ## Core
@@ -50,12 +49,57 @@ new_gemf = GEMF.from_tiles("PATH/TO/TILEDIR")
 new_gemf.write("PATH/TO/GEMF_FILE.gemf")
 ```
 
+## Lazy loading
+`GEMF.from_file()` and `GEMF.from_tiles()` accept a `lazy` argument (default `False`).
+
+With `lazy=False` (the default), the per-tile range details (location and size of every
+tile's data) are read/computed immediately. This gives access to the full range of
+features, but may take a while for files with a large number of tiles.
+
+With `lazy=True`, this step is skipped. The following are available right away without
+extra loading:
+- `gemf.num_sources`
+- `gemf.num_tiles`
+- `gemf.get_zoom_levels()`
+- inspecting `gemf.header.range_data` (the per-zoom-level bounding boxes)
+
+Any operation that needs per-tile data (e.g. `save_tiles()`, `write()`, `crop()`,
+`set_tile()`, the arithmetic operators) raises `DetailsNotLoadedError` on a lazily loaded
+`GEMF`. Call `gemf.load_details()` first to load the range details on demand:
+
+```python
+my_gemf = GEMF.from_file("MY_GEMF.gemf", lazy=True)
+
+# cheap, available immediately
+print(my_gemf.num_tiles)
+
+# load range details before performing per-tile operations
+my_gemf.load_details()
+my_gemf.save_tiles("PATH/TO/TILEDIR")
+```
+
 ## Manipulation
 ```python
 # crop to bounding box (all zoom levels will be cropped accordingly)
 gemf_crop = my_gemf.crop(7, 60, 62, 36, 38)
 ```
 
+## Combining GEMF objects
+```python
+# stack: add all sources of gemf2 onto gemf1 as new sources
+combined = gemf1 + gemf2
+
+# merge: union of tiles for sources present in both (matched by name)
+# on conflicting tiles, "|" keeps gemf1's tile by default
+merged = gemf1 | gemf2
+
+# intersect: keep only tiles present in both, for shared sources
+shared = gemf1 & gemf2
+
+# difference: keep gemf1's tiles that are not present in gemf2's matching source
+diff = gemf1 - gemf2
+```
+
 
 ## Visualization
 <!-- TODO: limitations for large gemf files -->

{gemf_map-1.0.2 → gemf_map-1.0.4}/gemf/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.2'
-__version_tuple__ = version_tuple = (1, 0, 2)
+__version__ = version = '1.0.4'
+__version_tuple__ = version_tuple = (1, 0, 4)
 
 __commit_id__ = commit_id = None