<p align="center">
<a href="https://github.com/ESDS-Leipzig/sen2nbar"><img src="https://github.com/ESDS-Leipzig/sen2nbar/raw/main/docs/_static/logo.png" alt="cubo"></a>
</p>
<p align="center">
<em>Nadir BRDF Adjusted Reflectance (NBAR) for Sentinel-2 in Python</em>
</p>
<p align="center">
<a href='https://pypi.python.org/pypi/sen2nbar'>
<img src='https://img.shields.io/pypi/v/sen2nbar.svg' alt='PyPI' />
</a>
<a href='https://anaconda.org/conda-forge/sen2nbar'>
<img src='https://img.shields.io/conda/vn/conda-forge/sen2nbar.svg' alt='conda-forge' />
</a>
<a href='https://sen2nbar.readthedocs.io/en/latest/?badge=latest'>
<img src='https://readthedocs.org/projects/sen2nbar/badge/?version=latest' alt='Documentation Status' />
</a>
<a href='https://arxiv.org/abs/2404.15812'>
<img src='https://img.shields.io/badge/arXiv-2404.15812-b31b1b.svg' alt='arXiv' />
</a>
<a href="https://github.com/ESDS-Leipzig/sen2nbar/actions/workflows/tests.yml" target="_blank">
<img src="https://github.com/ESDS-Leipzig/sen2nbar/actions/workflows/tests.yml/badge.svg" alt="Tests">
</a>
<a href="https://opensource.org/licenses/MIT" target="_blank">
<img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
</a>
<a href="https://github.com/sponsors/davemlz" target="_blank">
<img src="https://img.shields.io/badge/GitHub%20Sponsors-Donate-ff69b4.svg" alt="GitHub Sponsors">
</a>
<a href="https://www.buymeacoffee.com/davemlz" target="_blank">
<img src="https://img.shields.io/badge/Buy%20me%20a%20coffee-Donate-ff69b4.svg" alt="Buy me a coffee">
</a>
<a href="https://ko-fi.com/davemlz" target="_blank">
<img src="https://img.shields.io/badge/kofi-Donate-ff69b4.svg" alt="Ko-fi">
</a>
<a href="https://twitter.com/dmlmont" target="_blank">
<img src="https://img.shields.io/twitter/follow/dmlmont?style=social" alt="Twitter">
</a>
<a href="https://github.com/psf/black" target="_blank">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Black">
</a>
<a href="https://pycqa.github.io/isort/" target="_blank">
<img src="https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336" alt="isort">
</a>
</p>
---
**GitHub**: [https://github.com/ESDS-Leipzig/sen2nbar](https://github.com/ESDS-Leipzig/sen2nbar)
**Documentation**: [https://sen2nbar.readthedocs.io/](https://sen2nbar.readthedocs.io/)
**PyPI**: [https://pypi.org/project/sen2nbar/](https://pypi.org/project/sen2nbar/)
**Conda-forge**: [https://anaconda.org/conda-forge/sen2nbar](https://anaconda.org/conda-forge/sen2nbar)
**Tutorials**: [https://sen2nbar.readthedocs.io/en/latest/tutorials.html](https://sen2nbar.readthedocs.io/en/latest/tutorials.html)
**Paper**: [https://doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024](https://doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024)
---
> [!IMPORTANT]
> Our `sen2nbar` paper is out! Check it here: **[Montero, D., Mahecha, M.D., Aybar, C., Mosig, C., & Wieneke, S. (2024). Facilitating Advanced Sentinel-2 Analysis Through a Simplified Computation of Nadir BRDF Adjusted Reflectance.](https://doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024)**
## Overview
First, a super small glossary:
- **BRDF**: Bidirectional Reflectance Distribution Function.
- **DN**: Digital Number.
- **NBAR**: Nadir BRDF Adjusted Reflectance.
- **SR**: Surface Reflectance.
- **STAC**: SpatioTemporal Assets Catalogs.
Second, the amazing bibliography by David P. Roy et al., used to create this package:
- [Multi-temporal MODIS-Landsat data fusion for relative radiometric normalization, gap filling, and prediction of Landsat data.](https://doi.org/10.1016/j.rse.2008.03.009)
- [A general method to normalize Landsat reflectance data to nadir BRDF adjusted reflectance.](https://doi.org/10.1016/j.rse.2016.01.023)
- [Examination of Sentinel-2A multi-spectral instrument (MSI) reflectance anisotropy and the suitability of a general method to normalize MSI reflectance to nadir BRDF adjusted reflectance.](https://doi.org/10.1016/j.rse.2017.06.019)
- [Adjustment of sentinel-2 multi-spectral instrument (MSI) red-edge band reflectance to nadir BRDF adjusted reflectance (NBAR) and quantification of red-edge band BRDF effects.](https://doi.org/10.3390/rs9121325)
Third, the super useful bibliography by Lucht et al.,:
- [An algorithm for the retrieval of albedo from space using semiempirical BRDF models.](https://doi.org/10.1109/36.841980)
Given this, and in a few words, `sen2nbar` converts the **Sentinel-2 SR** (i.e., L2A) to **Sentinel-2 NBAR** via the **_c_-factor** method.
### SAFE
You can use `sen2nbar` to convert complete images via SAFE:
```python
from sen2nbar.nbar import nbar_SAFE
# Converted images are saved inside the SAFE path
nbar_SAFE("S2A_MSIL2A_20230223T075931_N0509_R035_T35HLC_20230223T120656.SAFE")
```
> **Note**
>
> Note that `sen2nbar` automatically shifts the DN of images with a processing baseline >= 04.00. This includes data cubes obtained via `stackstac` or `cubo`.
### stackstac
Or, if you are using STAC and retrieving images via `stackstac`:
```python
import pystac_client
import stackstac
import planetary_computer as pc
from sen2nbar.nbar import nbar_stackstac
# Important infor for later
endpoint = "https://planetarycomputer.microsoft.com/api/stac/v1"
collection = "sentinel-2-l2a"
bounds = (-148.565368, 60.800723, -147.443389, 61.183638)
# Open the STAC
catalog = pystac_client.Client.open(endpoint, modifier=pc.sign_inplace)
# Define your area
area_of_interest = {
"type": "Polygon",
"coordinates": [
[
[bounds[0], bounds[1]],
[bounds[2], bounds[1]],
[bounds[2], bounds[3]],
[bounds[0], bounds[3]],
[bounds[0], bounds[1]],
]
],
}
# Search the items
items = catalog.search(
collections=[collection],
intersects=area_of_interest,
datetime="2019-06-01/2019-08-01",
query={"eo:cloud_cover": {"lt": 10}},
).get_all_items()
# Retrieve all items as a xr.DataArray
stack = stackstac.stack(
items,
assets=["B05","B06","B07"], # Red Edge here, but you can use more!
bounds_latlon=bounds,
resolution=20
)
# Convert it to NBAR!
da = nbar_stackstac(
stack,
stac=endpoint,
collection=collection
)
```
> **Warning**
>
> These examples are done using `Planetary Computer`. If you are using data cubes retrieved via STAC (e.g., by using `stackstac` or `cubo`), we recommend you to use this provider. The provider `Element84` is not supported at the moment.
### cubo
And going deeper, if you are using `cubo`:
```python
import cubo
import xarray as xr
from sen2nbar.nbar import nbar_cubo
# Get your cube
da = cubo.create(
lat=47.84815,
lon=13.37949,
collection="sentinel-2-l2a",
bands=["B02","B03","B04"], # RGB here, but you can add more bands!
start_date="2020-01-01",
end_date="2021-01-01",
edge_size=64,
resolution=10,
query={"eo:cloud_cover": {"lt": 3}}
)
# Convert it to NBAR (This a xr.DataArray)
da = nbar_cubo(da)
```
## Bands
`sen2nbar` converts the following bands (if available in the input data):
- **RGB Bands**: 02, 03, 04.
- **Red Edge Bands**: 05, 06, 07.
- **Broad NIR Band**: 08.
- **SWIR Bands**: 11, 12.
## Installation
Install the latest version from PyPI:
```
pip install sen2nbar
```
Upgrade `sen2nbar` by running:
```
pip install -U sen2nbar
```
Install the latest version from conda-forge:
```
conda install -c conda-forge sen2nbar
```
Install the latest dev version from GitHub by running:
```
pip install git+https://github.com/davemlz/sen2nbar
```
## Citation
If you use this work, please consider citing the following paper:
```bibtex
@article{montero2024sen2nbar,
title = {Facilitating advanced Sentinel-2 analysis through a simplified computation of Nadir BRDF Adjusted Reflectance},
volume = {XLVIII-4/W12-2024},
ISSN = {2194-9034},
url = {http://dx.doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024},
DOI = {10.5194/isprs-archives-xlviii-4-w12-2024-105-2024},
journal = {The International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences},
publisher = {Copernicus GmbH},
author = {Montero, David and Mahecha, Miguel D. and Aybar, César and Mosig, Clemens and Wieneke, Sebastian},
year = {2024},
month = jun,
pages = {105–112}
}
```
## License
The project is licensed under the MIT license.
[](https://rsc4earth.de/authors/esds/)
Raw data
{
"_id": null,
"home_page": "https://github.com/ESDS-Leipzig/sen2nbar",
"name": "sen2nbar",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "David Montero Loaiza",
"author_email": "dml.mont@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0c/15/9ba4d6481e99e265c3218ddf1c27012f70c862322269e4cff5323c67fb88/sen2nbar-2024.6.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://github.com/ESDS-Leipzig/sen2nbar\"><img src=\"https://github.com/ESDS-Leipzig/sen2nbar/raw/main/docs/_static/logo.png\" alt=\"cubo\"></a>\n</p>\n<p align=\"center\">\n <em>Nadir BRDF Adjusted Reflectance (NBAR) for Sentinel-2 in Python</em>\n</p>\n<p align=\"center\">\n<a href='https://pypi.python.org/pypi/sen2nbar'>\n <img src='https://img.shields.io/pypi/v/sen2nbar.svg' alt='PyPI' />\n</a>\n<a href='https://anaconda.org/conda-forge/sen2nbar'>\n <img src='https://img.shields.io/conda/vn/conda-forge/sen2nbar.svg' alt='conda-forge' />\n</a>\n<a href='https://sen2nbar.readthedocs.io/en/latest/?badge=latest'>\n <img src='https://readthedocs.org/projects/sen2nbar/badge/?version=latest' alt='Documentation Status' />\n</a>\n<a href='https://arxiv.org/abs/2404.15812'>\n <img src='https://img.shields.io/badge/arXiv-2404.15812-b31b1b.svg' alt='arXiv' />\n</a>\n<a href=\"https://github.com/ESDS-Leipzig/sen2nbar/actions/workflows/tests.yml\" target=\"_blank\">\n <img src=\"https://github.com/ESDS-Leipzig/sen2nbar/actions/workflows/tests.yml/badge.svg\" alt=\"Tests\">\n</a>\n<a href=\"https://opensource.org/licenses/MIT\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License\">\n</a>\n<a href=\"https://github.com/sponsors/davemlz\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/GitHub%20Sponsors-Donate-ff69b4.svg\" alt=\"GitHub Sponsors\">\n</a>\n<a href=\"https://www.buymeacoffee.com/davemlz\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/Buy%20me%20a%20coffee-Donate-ff69b4.svg\" alt=\"Buy me a coffee\">\n</a>\n<a href=\"https://ko-fi.com/davemlz\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/kofi-Donate-ff69b4.svg\" alt=\"Ko-fi\">\n</a>\n<a href=\"https://twitter.com/dmlmont\" target=\"_blank\">\n <img src=\"https://img.shields.io/twitter/follow/dmlmont?style=social\" alt=\"Twitter\">\n</a>\n<a href=\"https://github.com/psf/black\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Black\">\n</a>\n<a href=\"https://pycqa.github.io/isort/\" target=\"_blank\">\n <img src=\"https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336\" alt=\"isort\">\n</a>\n</p>\n\n---\n\n**GitHub**: [https://github.com/ESDS-Leipzig/sen2nbar](https://github.com/ESDS-Leipzig/sen2nbar)\n\n**Documentation**: [https://sen2nbar.readthedocs.io/](https://sen2nbar.readthedocs.io/)\n\n**PyPI**: [https://pypi.org/project/sen2nbar/](https://pypi.org/project/sen2nbar/)\n\n**Conda-forge**: [https://anaconda.org/conda-forge/sen2nbar](https://anaconda.org/conda-forge/sen2nbar)\n\n**Tutorials**: [https://sen2nbar.readthedocs.io/en/latest/tutorials.html](https://sen2nbar.readthedocs.io/en/latest/tutorials.html)\n\n**Paper**: [https://doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024](https://doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024)\n\n---\n\n> [!IMPORTANT] \n> Our `sen2nbar` paper is out! Check it here: **[Montero, D., Mahecha, M.D., Aybar, C., Mosig, C., & Wieneke, S. (2024). Facilitating Advanced Sentinel-2 Analysis Through a Simplified Computation of Nadir BRDF Adjusted Reflectance.](https://doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024)**\n\n## Overview\n\nFirst, a super small glossary:\n\n- **BRDF**: Bidirectional Reflectance Distribution Function.\n- **DN**: Digital Number.\n- **NBAR**: Nadir BRDF Adjusted Reflectance.\n- **SR**: Surface Reflectance.\n- **STAC**: SpatioTemporal Assets Catalogs.\n\nSecond, the amazing bibliography by David P. Roy et al., used to create this package:\n\n- [Multi-temporal MODIS-Landsat data fusion for relative radiometric normalization, gap filling, and prediction of Landsat data.](https://doi.org/10.1016/j.rse.2008.03.009)\n- [A general method to normalize Landsat reflectance data to nadir BRDF adjusted reflectance.](https://doi.org/10.1016/j.rse.2016.01.023)\n- [Examination of Sentinel-2A multi-spectral instrument (MSI) reflectance anisotropy and the suitability of a general method to normalize MSI reflectance to nadir BRDF adjusted reflectance.](https://doi.org/10.1016/j.rse.2017.06.019)\n- [Adjustment of sentinel-2 multi-spectral instrument (MSI) red-edge band reflectance to nadir BRDF adjusted reflectance (NBAR) and quantification of red-edge band BRDF effects.](https://doi.org/10.3390/rs9121325)\n\nThird, the super useful bibliography by Lucht et al.,:\n\n- [An algorithm for the retrieval of albedo from space using semiempirical BRDF models.](https://doi.org/10.1109/36.841980)\n\nGiven this, and in a few words, `sen2nbar` converts the **Sentinel-2 SR** (i.e., L2A) to **Sentinel-2 NBAR** via the **_c_-factor** method.\n\n### SAFE\n\nYou can use `sen2nbar` to convert complete images via SAFE:\n\n```python\nfrom sen2nbar.nbar import nbar_SAFE\n\n# Converted images are saved inside the SAFE path\nnbar_SAFE(\"S2A_MSIL2A_20230223T075931_N0509_R035_T35HLC_20230223T120656.SAFE\")\n```\n\n> **Note**\n>\n> Note that `sen2nbar` automatically shifts the DN of images with a processing baseline >= 04.00. This includes data cubes obtained via `stackstac` or `cubo`.\n\n### stackstac\n\nOr, if you are using STAC and retrieving images via `stackstac`:\n\n```python\nimport pystac_client\nimport stackstac\nimport planetary_computer as pc\nfrom sen2nbar.nbar import nbar_stackstac\n\n# Important infor for later\nendpoint = \"https://planetarycomputer.microsoft.com/api/stac/v1\"\ncollection = \"sentinel-2-l2a\"\nbounds = (-148.565368, 60.800723, -147.443389, 61.183638)\n\n# Open the STAC\ncatalog = pystac_client.Client.open(endpoint, modifier=pc.sign_inplace)\n\n# Define your area\narea_of_interest = {\n \"type\": \"Polygon\",\n \"coordinates\": [\n [\n [bounds[0], bounds[1]],\n [bounds[2], bounds[1]],\n [bounds[2], bounds[3]],\n [bounds[0], bounds[3]],\n [bounds[0], bounds[1]],\n ]\n ],\n}\n\n# Search the items\nitems = catalog.search(\n collections=[collection],\n intersects=area_of_interest,\n datetime=\"2019-06-01/2019-08-01\",\n query={\"eo:cloud_cover\": {\"lt\": 10}},\n).get_all_items()\n\n# Retrieve all items as a xr.DataArray\nstack = stackstac.stack(\n items,\n assets=[\"B05\",\"B06\",\"B07\"], # Red Edge here, but you can use more!\n bounds_latlon=bounds,\n resolution=20\n)\n\n# Convert it to NBAR!\nda = nbar_stackstac(\n stack,\n stac=endpoint,\n collection=collection\n)\n```\n\n> **Warning**\n>\n> These examples are done using `Planetary Computer`. If you are using data cubes retrieved via STAC (e.g., by using `stackstac` or `cubo`), we recommend you to use this provider. The provider `Element84` is not supported at the moment.\n\n### cubo\n\nAnd going deeper, if you are using `cubo`:\n\n```python\nimport cubo\nimport xarray as xr\nfrom sen2nbar.nbar import nbar_cubo\n\n# Get your cube\nda = cubo.create(\n lat=47.84815,\n lon=13.37949,\n collection=\"sentinel-2-l2a\",\n bands=[\"B02\",\"B03\",\"B04\"], # RGB here, but you can add more bands!\n start_date=\"2020-01-01\",\n end_date=\"2021-01-01\",\n edge_size=64,\n resolution=10,\n query={\"eo:cloud_cover\": {\"lt\": 3}}\n)\n\n# Convert it to NBAR (This a xr.DataArray)\nda = nbar_cubo(da)\n```\n\n## Bands\n\n`sen2nbar` converts the following bands (if available in the input data):\n\n- **RGB Bands**: 02, 03, 04.\n- **Red Edge Bands**: 05, 06, 07.\n- **Broad NIR Band**: 08.\n- **SWIR Bands**: 11, 12.\n\n\n## Installation\n\nInstall the latest version from PyPI:\n\n```\npip install sen2nbar\n```\n\nUpgrade `sen2nbar` by running:\n\n```\npip install -U sen2nbar\n```\n\nInstall the latest version from conda-forge:\n\n```\nconda install -c conda-forge sen2nbar\n```\n\nInstall the latest dev version from GitHub by running:\n\n```\npip install git+https://github.com/davemlz/sen2nbar\n```\n\n## Citation\n\nIf you use this work, please consider citing the following paper:\n\n```bibtex\n@article{montero2024sen2nbar,\n title = {Facilitating advanced Sentinel-2 analysis through a simplified computation of Nadir BRDF Adjusted Reflectance},\n volume = {XLVIII-4/W12-2024},\n ISSN = {2194-9034},\n url = {http://dx.doi.org/10.5194/isprs-archives-XLVIII-4-W12-2024-105-2024},\n DOI = {10.5194/isprs-archives-xlviii-4-w12-2024-105-2024},\n journal = {The International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences},\n publisher = {Copernicus GmbH},\n author = {Montero, David and Mahecha, Miguel D. and Aybar, C\u00e9sar and Mosig, Clemens and Wieneke, Sebastian},\n year = {2024},\n month = jun,\n pages = {105\u2013112}\n}\n```\n\n## License\n\nThe project is licensed under the MIT license.\n\n[](https://rsc4earth.de/authors/esds/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Nadir BRDF Adjusted Reflectance (NBAR) for Sentinel-2 in Python",
"version": "2024.6.0",
"project_urls": {
"Homepage": "https://github.com/ESDS-Leipzig/sen2nbar"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0c159ba4d6481e99e265c3218ddf1c27012f70c862322269e4cff5323c67fb88",
"md5": "0370543c642f0cd9dbf72978d61a6b43",
"sha256": "4ed08e0c229765d36360c15172e8bd7cf99ef84c006df0a3fb8d15de6abd3dc1"
},
"downloads": -1,
"filename": "sen2nbar-2024.6.0.tar.gz",
"has_sig": false,
"md5_digest": "0370543c642f0cd9dbf72978d61a6b43",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15161,
"upload_time": "2024-06-23T14:45:00",
"upload_time_iso_8601": "2024-06-23T14:45:00.954871Z",
"url": "https://files.pythonhosted.org/packages/0c/15/9ba4d6481e99e265c3218ddf1c27012f70c862322269e4cff5323c67fb88/sen2nbar-2024.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-23 14:45:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ESDS-Leipzig",
"github_project": "sen2nbar",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "dask",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "rasterio",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "xarray",
"specs": []
},
{
"name": "xmltodict",
"specs": []
}
],
"tox": true,
"lcname": "sen2nbar"
}
JSON
