{"id":13738235,"url":"https://github.com/preligens-lab/buzzard","last_synced_at":"2025-05-08T16:33:09.236Z","repository":{"id":36953724,"uuid":"220638925","full_name":"preligens-lab/buzzard","owner":"preligens-lab","description":"Advanced raster and geometry manipulations","archived":false,"fork":false,"pushed_at":"2024-12-26T20:13:40.000Z","size":11669,"stargazers_count":39,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-08T05:01:48.278Z","etag":null,"topics":["data-science","footprint","gdal","geometry","geospatial","gis","image","ogr","osr","python","raster","raster-pipelines","vector"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/preligens-lab.png","metadata":{"files":{"readme":"README.md","changelog":"changes.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.md","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-09T12:27:43.000Z","updated_at":"2024-12-26T20:13:44.000Z","dependencies_parsed_at":"2024-06-02T16:10:32.483Z","dependency_job_id":"fe0f5b75-c4bb-4fc4-b4e7-f5cd1c057ea2","html_url":"https://github.com/preligens-lab/buzzard","commit_stats":{"total_commits":721,"total_committers":13,"mean_commits":55.46153846153846,"dds":0.2787794729542302,"last_synced_commit":"f4d56370e60b63bd26dcdbb1ae859bb25e3d4d50"},"previous_names":["earthcube-lab/buzzard"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preligens-lab%2Fbuzzard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preligens-lab%2Fbuzzard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preligens-lab%2Fbuzzard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/preligens-lab%2Fbuzzard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/preligens-lab","download_url":"https://codeload.github.com/preligens-lab/buzzard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253105423,"owners_count":21855023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-science","footprint","gdal","geometry","geospatial","gis","image","ogr","osr","python","raster","raster-pipelines","vector"],"created_at":"2024-08-03T03:02:15.285Z","updated_at":"2025-05-08T16:33:08.319Z","avatar_url":"https://github.com/preligens-lab.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# `buzzard`\nIn a nutshell, the `buzzard` library provides powerful abstractions to manipulate together images and geometries that come from different kind of sources (`GeoTIFF`, `PNG`, `GeoJSON`, `Shapefile`, `numpy array`, `buzzard pipelines`, ...).\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/earthcube-lab/buzzard/raw/master/img/buzzard.png\"\u003e\u003cbr\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/earthcube-lab/buzzard/blob/master/LICENSE)[![CircleCI](https://circleci.com/gh/earthcube-lab/buzzard/tree/master.svg?style=shield\u0026circle-token=9d41310f0eb3f8ff120a7103ba2d7ee5d5d628b7)](https://circleci.com/gh/earthcube-lab/buzzard/tree/master)[![codecov](https://codecov.io/gh/earthcube-lab/buzzard/branch/master/graph/badge.svg?token=FbWmLGplCq)](https://codecov.io/gh/earthcube-lab/buzzard)[![readthedoc](https://readthedocs.org/projects/buzzard/badge/?version=latest\u0026style=flat)](https://buzzard.readthedocs.io/en/latest)\n\n[\n![Join us on Slack!](https://cdn.brandfolder.io/5H442O3W/as/pl54cs-bd9mhs-3jsgg0/btn-add-to-slack_1x.png?height=25)\n](https://join.slack.com/t/buzzard-python/shared_invite/enQtNjY0NDQ2MzU3MzgzLTJhNTZhNjAwOGIyM2RkOTdkZGE5MGUwZGEzZGQwODkyMzY2N2YwMTg5ZmI1NDc2MjY2MGM2ZTdhNDc3M2E1YTI)\n\n\u003c!-- [![Requirements Status](https://requires.io/github/airware/buzzard/requirements.svg?branch=master)](https://requires.io/github/airware/buzzard/requirements/?branch=master) --\u003e\n\n## `buzzard` is\n- A _python_ library.\n- Primarily designed to hide all cumbersome operations when doing data-science with [GIS](https://en.wikipedia.org/wiki/Geographic_information_system) files.\n- A multipurpose computer vision library, it can be used in all kind of situations where images or geometries are involved.\n- A pythonic wrapper for _osgeo_'s _gdal_/_ogr_/_osr_.\n- A solution to work with arbitrary large images by simplifying and automating the manipulation of image slices.\n\n## `buzzard` contains\n- A [`Dataset`](https://buzzard.readthedocs.io/en/latest/dataset.html) class that oversees a set of opened raster and vector files.\n- An immutable toolbox class, the [`Footprint`](https://buzzard.readthedocs.io/en/latest/footprint.html), designed to locate a rectangle in both an image space and a geometry space.\n\n## How to open and read files\nThis example demonstrates how to visualize a large raster polygon per polygon.\n\n```py\nimport buzzard as buzz\nimport numpy as np\nimport matplotlib.pyplot as plt\n\n# Open the files. Only metadata are kept in memory\nr = buzz.open_raster('path/to/rgba-image.tif')\nv = buzz.open_vector('path/to/polygons.geojson', driver='GeoJSON')\n\n\n# Load the polygons from disk one by one as shapely objects\nfor poly in v.iter_data():\n\n    # Compute the Footprint bounding `poly`\n    fp = r.fp.intersection(poly)\n    print(fp)\n\n    # Load the image from disk at `fp` to a numpy array\n    rgb = r.get_data(fp=fp, channels=(0, 1, 2))\n    alpha = r.get_data(fp=fp, channels=3)\n\n    # Create a boolean mask as a numpy array from the shapely polygon\n    mask = np.invert(fp.burn_polygons(poly))\n\n    # Darken pixels outside of polygon and set transparent pixels to orange\n    rgb[mask] = (rgb[mask] * 0.5).astype(np.uint8)\n    rgb[alpha == 0] = [236, 120, 57]\n\n    # Show the result with matplotlib\n    plt.imshow(rgb)\n    plt.show()\n\n```\nImages from the [ISPRS's Potsdam dataset](http://www2.isprs.org/commissions/comm3/wg4/2d-sem-label-potsdam.html).\n\n`Footprint(tl=(3183.600000, -914.550000), br=(3689.700000, -1170.450000), size=(506.100000, 255.900000), rsize=(3374, 1706))`\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/earthcube-lab/buzzard/raw/master/img/ex0-img0.jpg\" width=\"80%\"\u003e\u003cbr\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n`Footprint(tl=(3171.600000, -1321.500000), br=(4553.400000, -2400.000000), size=(1381.800000, 1078.500000), rsize=(9212, 7190))`\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/earthcube-lab/buzzard/raw/master/img/ex0-img1.jpg\" width=\"70%\"\u003e\u003cbr\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n## How to create files and manipulate _Footprints_\n```py\nimport buzzard as buzz\nimport numpy as np\nimport matplotlib.pyplot as plt\nimport keras\n\nr = buzz.open_raster('path/to/rgba-image.tif')\nkm = keras.models.load_model('path/to/deep-learning-model.hdf5')\n\n# Chunk the raster's Footprint to Footprints of size\n# 1920 x 1080 pixels stored in a 2d numpy array\ntiles = r.fp.tile((1920, 1080))\n\nall_roads = []\n\n# Perform an inference for each tile\nfor i, fp in enumerate(tiles.flat):\n    rgb = r.get_data(fp=fp, channels=(0, 1, 2))\n\n    # Perform pixelwise semantic segmentation with a keras model\n    predictions_heatmap = km.predict(rgb[np.newaxis, ...])[0]\n    predictions_top1 = np.argmax(predictions_heatmap, axis=-1)\n\n    # Save the prediction to a `geotiff`\n    path = f'predictions_{i}.tif'\n    with buzz.create_raster(path=path, fp=fp, dtype='uint8', channel_count=1).close as out:\n        out.set_data(predictions_top1)\n\n    # Extract the road polygons by transforming a numpy boolean mask to shapely polygons\n    road_polygons = fp.find_polygons(predictions_top1 == 3)\n    all_roads += road_polygons\n\n    # Show the result with matplotlib for one tile\n    if i == 2:\n        plt.imshow(rgb)\n        plt.imshow(predictions_top1)\n        plt.show()\n\n# Save all roads found to a single `shapefile`\nwith buzz.create_vector(path='roads.shp', type='polygon').close as out:\n    for poly in all_roads:\n        out.insert_data(poly)\n\n```\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/earthcube-lab/buzzard/raw/master/img/ex1-img0.jpg\" width=\"80%\"\u003e\u003cbr\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/earthcube-lab/buzzard/raw/master/img/ex1-img1.jpg\" width=\"80%\"\u003e\u003cbr\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n## Advanced examples\nAdditional examples can be found here:\n- [Files and _Footprints_ in depth](https://github.com/earthcube-lab/buzzard/blob/master/doc/examples.ipynb)\n- [_async rasters_ in depth](https://github.com/earthcube-lab/buzzard/blob/master/doc/notebook2/async_rasters.ipynb)\n\n## `buzzard` allows\n- Opening and creating [raster](https://buzzard.readthedocs.io/en/latest/dataset_raster.html) and [vector](https://buzzard.readthedocs.io/en/latest/dataset_vector.html) files. Supports all [GDAL drivers (GTiff, PNG, ...)](https://www.gdal.org/formats_list.html) and all [OGR drivers (GeoJSON, DXF, Shapefile, ...)](https://www.gdal.org/ogr_formats.html).\n- [Reading](https://buzzard.readthedocs.io/en/latest/source_gdal_file_raster.html#raster-file-get-data) raster files pixels from disk to _numpy.ndarray_.\n  - _Options:_ `sub-rectangle reading`, `rotated and scaled sub-rectangle reading (thanks to on-the-fly remapping with OpenCV)`, `automatic parallelization of read and remapping (soon)`, `async (soon)`, `be the source of an image processing pipeline (soon)`.\n  - _Properties:_ `thread-safe parallel reads`.\n- [Writing](https://buzzard.readthedocs.io/en/latest/source_gdal_file_raster.html#raster-file-set-data) raster files pixels to disk from _numpy.ndarray_.\n  - _Options:_ `sub-rectangle writing`, `rotated and scaled sub-rectangle writing (thanks to on-the-fly remapping with OpenCV)`, `masked writing (slow)`.\n- [Reading](https://buzzard.readthedocs.io/en/latest/source_gdal_file_vector.html#vector-file-iter-data) vector files geometries from disk to _shapely objects_, _geojson dict_ and _raw coordinates_.\n  - _Options:_ `masking`.\n  - _Properties:_ `thread-safe parallel reads`.\n- [Writing](https://buzzard.readthedocs.io/en/latest/source_gdal_file_vector.html#vector-file-insert-data) vector files geometries to disk from _shapely objects_, _geojson dict_ and _raw coordinates_.\n- Powerful manipulations of [raster windows](https://buzzard.readthedocs.io/en/latest/footprint.html)\n- [Instantiation](https://buzzard.readthedocs.io/en/latest/dataset_recipe.html#buzzard.Dataset.create_raster_recipe) of image processing pipelines where each node is a raster, and each edge is a user defined python function transforming _numpy.ndarray_ objects (beta, partially implemented).\n  - _Options:_ `automatic parallelization using user defined thread or process pools`, `disk caching`.\n  - _Properties:_ `lazy evaluation`, `deterministic`, `automatic tasks chunking into tiles`, `fine grain task prioritization`, `backpressure prevention`.\n- [Spatial reference homogenization](https://buzzard.readthedocs.io/en/latest/dataset.html#on-the-fly-re-projections-in-buzzard) between opened files like a GIS software does (beta)\n\n## Documentation\nhttps://buzzard.readthedocs.io/\n\n## Dependencies\nThe following table lists dependencies along with the minimum version, their status for the project and the related license.\n\n| Library                | Version  | Mandatory | License                                                                              | Comment                                                       |\n|------------------------|----------|-----------|--------------------------------------------------------------------------------------|---------------------------------------------------------------|\n| gdal                   | \u003e=2.3.3  | Yes       | [MIT/X](https://gdal.org/license.html)                                               | Hard to install. Will be included in `buzzard` wheels         |\n| opencv-python-headless | \u003e=3.1.0  | Yes       | [3-clause BSD](http://opencv.org/license.html)                                       | Easy to install with `opencv-python-headless` wheels.         |\n| shapely                | \u003e=1.6.1  | Yes       | [3-clause BSD](https://github.com/Toblerity/Shapely/blob/master/LICENSE.txt)         |                                                               |\n| affine                 | \u003e=2.0.0  | Yes       | [3-clause BSD](https://github.com/sgillies/affine/blob/master/LICENSE.txt)           |                                                               |\n| numpy                  | \u003e=1.15.0 | Yes       | [numpy](https://numpy.org/doc/stable/license.html)                                   |                                                               |\n| scipy                  | \u003e=0.19.1 | Yes       | [scipy](https://www.scipy.org/scipylib/license.html)                                 |                                                               |\n| pint                   | \u003e=0.8.1  | Yes       | [3-clause BSD](https://github.com/hgrecco/pint/blob/master/LICENSE)                  |                                                               |\n| sortedcontainers       | \u003e=1.5.9  | Yes       | [apache](https://github.com/grantjenks/python-sortedcontainers/blob/master/LICENSE)  |                                                               |\n| Rtree                  | \u003e=0.8.3  | Yes       | [MIT](https://github.com/Toblerity/rtree/blob/master/LICENSE.txt)                    |                                                               |\n| scikit-image           | \u003e=0.14.0 | Yes       | [scikit-image](https://github.com/scikit-image/scikit-image/blob/master/LICENSE.txt) |                                                               |\n| pytest                 | \u003e=3.2.2  | No        | [MIT](https://docs.pytest.org/en/latest/license.html)                                | Only for tests                                                |\n\n## How to install from terminal\n### Anaconda and pip\n```sh\n# Step 1 - Install Anaconda\n# https://www.anaconda.com/download/\n\n# Step 2 - Create env\nconda create -n buzz python gdal\u003e=2.3.3 shapely rtree -c 'conda-forge'\n\n# Step 3 - Activate env\nconda activate buzz\n\n# Step 4 - Install buzzard\npip install buzzard\n```\n\n### Docker\n```sh\ndocker build -t buzz --build-arg PYTHON_VERSION=3.7 https://raw.githubusercontent.com/earthcube-lab/buzzard/master/.circleci/images/base-python/Dockerfile\ndocker run -it --rm buzz bash\npip install buzzard\n\n```\n\n### Package manager and pip\n```sh\n# Step 1 - Install GDAL and rtree ******************************************* **\n# Windows\n# https://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal\n# https://www.lfd.uci.edu/~gohlke/pythonlibs/#rtree\n\n# MacOS\nbrew install gdal\nbrew tap osgeo/osgeo4mac\nbrew tap --repair\nbrew install gdal2\nbrew install spatialindex\nexport PATH=\"/usr/local/opt/gdal2/bin:$PATH\"\npython3 -m pip install 'gdal==2.3.3'\n\n# Ubuntu\n# Run the commands from the following Dockerfile:\n# https://github.com/earthcube-lab/buzzard/blob/master/doc/ubuntu_install/Dockerfile\n\n# Step 2 - Install buzzard ************************************************** **\npython3 -m pip install buzzard\n\n```\n\n## Supported Python versions\nTo enjoy the latest buzzard features, update your python!\n\n#### Full python support\n- Latest tested version: `3.8` (June 2018)\n- Oldest tested version: `3.6` (Sept 2015)\n\n#### Partial python support\n- For python `2.7`: use buzzard version `0.4.4`\n- For python `3.4`: use buzzard version `0.6.3`\n- For python `3.5`: use buzzard version `0.6.4`\n\n## Slack\nYou want some help? You have a question? You want to contribute? Join us on Slack!\n\n[\n![Join us on Slack!](https://cdn.brandfolder.io/5H442O3W/as/pl54cs-bd9mhs-3jsgg0/btn-add-to-slack_1x.png?height=42)\n](https://join.slack.com/t/buzzard-python/shared_invite/enQtNjY0NDQ2MzU3MzgzLTJhNTZhNjAwOGIyM2RkOTdkZGE5MGUwZGEzZGQwODkyMzY2N2YwMTg5ZmI1NDc2MjY2MGM2ZTdhNDc3M2E1YTI)\n\n## How to test\n```sh\ngit clone https://github.com/earthcube-lab/buzzard\npip install -r buzzard/requirements-dev.txt\npytest buzzard/buzzard/test\n```\n\n## How to build documentation\n```sh\ncd docs\nmake html\nopen _build/html/index.html\n```\n\n## Contributions and feedback\nWelcome to the `buzzard` project! We appreciate any contribution and feedback, your proposals and pull requests will be considered and responded to. For more information, see the [`CONTRIBUTING.md`](./CONTRIBUTING.md) file.\n\n## Authors\nSee [AUTHORS](./AUTHORS.md)\n\n## License and Notice\nSee [LICENSE](./LICENSE) and [NOTICE](./NOTICE).\n\n## Other pages\n- [TODO](https://www.notion.so/buzzard/2c94ef6ee8da4d6280834129cc00f4d2?v=334ead18796342feb32ba85ccdfcf69f) on `notion.so`\n\n------------------------------------------------------------------------------------------------------------------------\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreligens-lab%2Fbuzzard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpreligens-lab%2Fbuzzard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpreligens-lab%2Fbuzzard/lists"}