https://github.com/worldbank/geometadatatools
Lightweight tools to extract, analyze, and visualize metadata from raster and vector geospatial datasets
https://github.com/worldbank/geometadatatools
geospatial gis metadata metadata-extractor raster vector-graphics
Last synced: about 1 month ago
JSON representation
Lightweight tools to extract, analyze, and visualize metadata from raster and vector geospatial datasets
- Host: GitHub
- URL: https://github.com/worldbank/geometadatatools
- Owner: worldbank
- License: mit
- Created: 2025-10-22T19:46:30.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-12-04T20:31:20.000Z (7 months ago)
- Last Synced: 2026-05-06T19:19:42.213Z (2 months ago)
- Topics: geospatial, gis, metadata, metadata-extractor, raster, vector-graphics
- Language: Jupyter Notebook
- Homepage: https://worldbank.github.io/metadata-editor-docs/quick_start_geographic.html
- Size: 905 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# GeoMetadataTools
GeoMetadataTools is a Python library designed to extract, analyze, and visualize metadata from geospatial datasets. It supports both raster and vector formats, providing enriched metadata, bounding box calculations, and thumbnail quality visualizations.
## Installation
To install GeoMetadataTools, use pip:
```bash
pip install geometadatatools
```
## Supported Formats
- **Vector**: GeoJSON, Shapefile (SHP), KML, GPKG, GDB
- **Raster**: NetCDF (NC), TIF, BIL, ASCII (XYZ), GeoPDF (PDF), JPG, GIF, ADF, OVR
We do not support zipped files directly; please unzip them before use. That includes KMZ which is the zipped version of KML.
## Importing the Library
```python
from geometadatatools import get_file_info, read_and_enrich, total_bounding_box_in_wgs84, get_images, get_data
```
## Examples
### Vector Data Example: GeoJSON File
```python
# Inspect the file
file_info = get_file_info("tests/sample_files/city_of_york_allotments.geojson")
print(file_info["file"]) # Basic file metadata
print(file_info["layers"]) # List of layer names
print(file_info["type"]) # GeoJSON is a 'vector' type file
# Calculate the total bounding box
bbox = total_bounding_box_in_wgs84("tests/sample_files/city_of_york_allotments.geojson")
print(bbox)
# Enrich the file
info = read_and_enrich("tests/sample_files/city_of_york_allotments.geojson",layer_name_or_band_index="Allotments")
print(info['crs']) # Coordinate Reference System used in the file
print(info['analytics']['layer']) # Layer bounding box, geohash, and number of features
print(info['analytics']['feature_types']) # Feature types present in the layer for example {'id': int, 'geom': 'geometry'}
print(info["analytics"]["feature_statistics"]) # Statistics for each feature attribute
img_strings = get_images("tests/sample_files/city_of_york_allotments.geojson") # List of base64-encoded images, one per layer
```
### Raster Data Example: TIF File
```python
# Inspect the file
file_info = get_file_info("tests/sample_files/small_tiff_sample.tif")
print(file_info["file"]) # Basic file metadata
print(file_info["raster_stats"]) # File level statistics specific to raster files - the number of rows and columns of pixels
print(file_info["layers"]) # List of band names
print(file_info["type"]) # TIF is a 'raster' type file
# Calculate the total bounding box
bbox = total_bounding_box_in_wgs84("tests/sample_files/small_tiff_sample.tif")
print(bbox)
# Enrich the file
info = read_and_enrich("tests/sample_files/small_tiff_sample.tif",layer_name_or_band_index=1)
print(info['projection']) # Raster files have projections rather than CRS
print(info["analytics"]["feature_statistics"]) # Statistics for the raster band such as min, max, mean, stddev, null value and units. Note thare raster files do not have 'features' like vector files do so there is no other layer or feature analytics.
img_strings = get_images("tests/sample_files/small_tiff_sample.tif") # List of base64-encoded images, one per band
```
## Key Functions
### `get_file_info`
Extracts metadata from a file, including file size, type, layers, and raster statistics (if applicable).
### `read_and_enrich`
Reads a specific layer or band from the file and enriches it with detailed metadata and analytics.
### `total_bounding_box_in_wgs84`
Calculates the total bounding box of the file in WGS84 projection.
### `get_images`
Generates visualizations of the data as base64-encoded images. There is one image per layer or band.
### `get_data`
Extracts the actual data from a specified layer or band in a structured format (for a vector file this is a geopandas GeoDataFrame, for a raster file this is a GDAL Dataset).
## Possible directions for future development
- Extract Z information
- Alternative colour schemes for images
## Contributing and Testing
The repository includes tests to ensure the functionality of the library. If you want to contribute, be sure to run unit and integration tests before creating a PR. To get set up we use UV for managing dependencies and virtual environments. After cloning the repository, run the following commands to set up the development environment and run the tests:
```bash
uv venv && uv sync --dev
uv run pytest tests/
```
Importantly, these tests are set up to download sample files when run, ensuring that the repository remains lightweight. The files and their sources are documented in `tests/file_manifest.yaml`.
The first time you run the tests, the necessary files will be downloaded automatically. Note that a shape file is included directly in the repo. This library is designed to work with shape files but not with zipped files which is the most common way shape files are shared. So an unzipped shape file is included for testing purposes.
Additional testing, for example on proprietary datasets, can be performed by placing files in the `tests/sample_files` directory. If these files are proprietary, be careful not to commit them to the repository.
If there are any changes to the dependencies, update the THIRD_PARTY_LICENSES.md file by running:
```bash
uv run pip-licenses --format=markdown --with-license-file \
| sed "s|$HOME|~|g" \
| sed "s|$(pwd)||g" \
> THIRD_PARTY_LICENSES.md
```
Just listing the third party licenses by name may not be sufficient for compliance with some open source licenses so ensure that the THIRD_PARTY_LICENSES.md file is kept up to date.
To get a list of third party licenses without the full license text, run:
```bash
uv run pip-licenses --format=markdown
```
## Acknowledgments
Parts of this repository were written with assistance from Large Language Models (LLMs).
Many thanks to the team at INEGI for useful feedback on the early versions of this library.
## Third Party licenses
Third-party libraries used by this project, and listed in pyproject.toml or uv.lock, have their licenses listed in THIRD_PARTY_LICENSES.md
## License
This project is licensed under the MIT License together with the [World Bank IGO Rider](WB-IGO-RIDER.md). The Rider is purely procedural: it reserves all privileges and immunities enjoyed by the World Bank, without adding restrictions to the MIT permissions. Please review both files before using, distributing or contributing.