<div align="center">
<img src="https://raw.githubusercontent.com/CNES/bulldozer/master/docs/source/images/bulldozer_logo.png" width=256>
**Bulldozer, a DTM extraction tool requiring only a DSM as input.**
[](https://www.python.org/downloads/release/python-380/)
[](CONTRIBUTING.md)
[](https://opensource.org/licenses/Apache-2.0)
[](https://pypi.org/project/bulldozer-dtm/)
<p align="center">
<a href="#key-features">Key Features</a> •
<a href="#installation">Installation</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#documentation">Documentation</a> •
<a href="#contribute">Contribute</a> •
<a href="#licence">Licence</a> •
<a href="#reference">Reference</a>
</p>
</div>
---
## Key features
<div align="center">
<img src="docs/source/images/result_overview.gif" alt="demo" width="400"/>
</div>
**Bulldozer** is designed as a pipeline of standalone functions that aims to extract a *Digital Terrain Model* (DTM) from a *Digital Surface Model* (DSM).
But you can also use one of the following function without running the full pipeline:
* **DSM preprocessing**
* **Nodata extraction:** a group of methods to differentiate and extract nodata related to failed correlations during the DSM computation and those of the image border
* **Disturbed areas detection:** a method to locate disturbed areas. These noisy areas are mainly related to areas in which the correlator has incorrectly estimated the elevation (water or shadow areas).
* **DTM extraction**
* **DTM computation:** the main method that extracts the DTM from the preprocessed DSM.
* **DTM postprocessing**
* **Pits detection:** a method to detect pits in the provided raster and return the corresponding mask.
* **Pits filling:** a method to fill pits in the generated DTM (or input raster).
* **DHM computation:** a method to extract the *Digital Height Model* (DHM).
For more information about these functions and how to call them, please refer to the <a href="#notebooks">notebook documentation section</a>.
## Installation
### Using Pypi
You can install **Bulldozer** by running the following command:
```sh
pip install bulldozer-dtm
```
### Using Github
It is recommended to install **Bulldozer** into a virtual environment, like [conda](https://docs.conda.io/en/latest/) or [virtualenv](https://virtualenv.pypa.io/en/latest/).
* Installation with `virtualenv`:
```sh
# Clone the project
git clone https://github.com/CNES/bulldozer.git
cd bulldozer/
# Create the environment
python -m venv bulldozer_venv
source bulldozer_venv/bin/activate
# Install the library
pip install .
```
## Quick Start
1. First you have to create a configuration file or edit the `configuration_template.yaml` available in the `conf` directory. You have to update at least the following parameters:
```yaml
# Input DSM path (expected format: "<folder_1>/<folder_2>/<file>.<[tif/tiff]>")
dsm_path : "<input_dsm.tif>"
# Output directory path (if the directory doesn't exist, create it)
output_dir : "<output_dir>"
```
2. Run the pipeline:
* Through CLI *(Command Line Interface)*
```console
bulldozer --conf conf/configuration_template.yaml
```
* Through Python API using the config file
```python
from bulldozer.pipeline.bulldozer_pipeline import dsm_to_dtm
dsm_to_dtm(config_path="conf/configuration_template.yaml")
```
* Through Python API providing directly the input parameters (missing parameters will be replaced by default values)
```python
from bulldozer.pipeline.bulldozer_pipeline import dsm_to_dtm
# Example with a specific number of workers
dsm_to_dtm(dsm_path="<input_dsm.tif>", output_dir="<output_dir>", nb_max_workers=16)
```
3. ✅ Done! Your DTM is available in the *<output_dir>*
## Documentation
### Notebooks
For each section described in <a href="#key-features">Key Features</a> section you can follow one of the tutorial notebook:
* [Running Bulldozer (full pipeline)](docs/notebooks/0_bulldozer_pipeline.ipynb)
* [Preprocessing standalone functions](docs/notebooks/1_preprocess.ipynb)
* [Extraction step](docs/notebooks/2_DTM_extraction.ipynb)
* [Postprocessing standalone functions](docs/notebooks/3_postprocess.ipynb)
### Full documentation (WIP)
**Bulldozer** also has a more detailed documentation.
A high-level overview of how it’s organized will help you know where to look for certain things:
* [Tutorials](docs/tutorials/index.md) take you by the hand through a series of steps to create a DLCooker application. Start here if you’re new to DLCooker.
* [How-to guides](docs/how-to/index.md) are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how DLCooker works.
* [Explanation guides](docs/explanation/index.md) discuss key topics and concepts at a fairly high level and provide useful background information and explanation.
> **_NOTE:_** The documentation is not available online yet, it needs to be built manually.
To do so, please execute the following command at the root:
```console
mkdocs serve
```
## Contribute
To do a bug report or a contribution, see the [**Contribution Guide**](CONTRIBUTING.md).
for any help or suggestion, feel free to contact the authors:
- Dimitri Lallement : dimitri.lallement@cnes.fr
- Pierre Lassalle : pierre.lassalle@cnes.fr
## Licence
**Bulldozer** has a Apache V2.0 license, as found in the [LICENSE](LICENSE) file.
## Credits
Please refer to the [Authors file](AUTHORS.md).
## Reference
[D. Lallement, P. Lassalle, Y. Ott, R. Demortier, and J. Delvit, 2022. BULLDOZER: AN AUTOMATIC SELF-DRIVEN LARGE SCALE DTM EXTRACTION METHOD FROM DIGITAL SURFACE MODEL. ISPRS - International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences.](https://www.int-arch-photogramm-remote-sens-spatial-inf-sci.net/XLIII-B2-2022/409/2022/)
Raw data
{
"_id": null,
"home_page": "https://github.com/CNES/bulldozer",
"name": "bulldozer-dtm",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "bulldozer,DTM,DSM,3D,Photogrammetry,Remote Sensing,LiDar,CARS",
"author": "CNES",
"author_email": "pierre.lassalle@cnes.fr,dimitri.lallement@cnes.fr,yannick.ott@thalesgroup.com",
"download_url": "https://files.pythonhosted.org/packages/7f/29/26fb0eded2138b7eb3fa5326b03f762c1b26f67cd9c84e2029e895954a5d/bulldozer-dtm-1.0.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/CNES/bulldozer/master/docs/source/images/bulldozer_logo.png\" width=256>\n\n**Bulldozer, a DTM extraction tool requiring only a DSM as input.**\n\n[](https://www.python.org/downloads/release/python-380/)\n[](CONTRIBUTING.md)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://pypi.org/project/bulldozer-dtm/)\n\n\n<p align=\"center\">\n <a href=\"#key-features\">Key Features</a> \u2022\n <a href=\"#installation\">Installation</a> \u2022 \n <a href=\"#quick-start\">Quick Start</a> \u2022\n <a href=\"#documentation\">Documentation</a> \u2022\n <a href=\"#contribute\">Contribute</a> \u2022\n <a href=\"#licence\">Licence</a> \u2022\n <a href=\"#reference\">Reference</a>\n</p>\n\n</div>\n\n---\n\n## Key features\n\n<div align=\"center\">\n<img src=\"docs/source/images/result_overview.gif\" alt=\"demo\" width=\"400\"/>\n</div>\n\n**Bulldozer** is designed as a pipeline of standalone functions that aims to extract a *Digital Terrain Model* (DTM) from a *Digital Surface Model* (DSM). \nBut you can also use one of the following function without running the full pipeline:\n* **DSM preprocessing**\n * **Nodata extraction:** a group of methods to differentiate and extract nodata related to failed correlations during the DSM computation and those of the image border\n * **Disturbed areas detection:** a method to locate disturbed areas. These noisy areas are mainly related to areas in which the correlator has incorrectly estimated the elevation (water or shadow areas).\n* **DTM extraction**\n * **DTM computation:** the main method that extracts the DTM from the preprocessed DSM.\n* **DTM postprocessing**\n * **Pits detection:** a method to detect pits in the provided raster and return the corresponding mask.\n * **Pits filling:** a method to fill pits in the generated DTM (or input raster).\n * **DHM computation:** a method to extract the *Digital Height Model* (DHM).\n\nFor more information about these functions and how to call them, please refer to the <a href=\"#notebooks\">notebook documentation section</a>.\n\n## Installation\n\n### Using Pypi\nYou can install **Bulldozer** by running the following command:\n```sh\npip install bulldozer-dtm\n```\n### Using Github\n\nIt is recommended to install **Bulldozer** into a virtual environment, like [conda](https://docs.conda.io/en/latest/) or [virtualenv](https://virtualenv.pypa.io/en/latest/).\n\n* Installation with `virtualenv`:\n\n```sh\n# Clone the project\ngit clone https://github.com/CNES/bulldozer.git\ncd bulldozer/\n\n# Create the environment\npython -m venv bulldozer_venv\nsource bulldozer_venv/bin/activate\n\n# Install the library\npip install .\n```\n## Quick Start\n\n1. First you have to create a configuration file or edit the `configuration_template.yaml` available in the `conf` directory. You have to update at least the following parameters:\n```yaml\n# Input DSM path (expected format: \"<folder_1>/<folder_2>/<file>.<[tif/tiff]>\")\ndsm_path : \"<input_dsm.tif>\"\n# Output directory path (if the directory doesn't exist, create it)\noutput_dir : \"<output_dir>\"\n```\n2. Run the pipeline:\n * Through CLI *(Command Line Interface)*\n ```console\n bulldozer --conf conf/configuration_template.yaml\n ```\n * Through Python API using the config file\n ```python\n from bulldozer.pipeline.bulldozer_pipeline import dsm_to_dtm\n\n dsm_to_dtm(config_path=\"conf/configuration_template.yaml\")\n ```\n * Through Python API providing directly the input parameters (missing parameters will be replaced by default values)\n ```python\n from bulldozer.pipeline.bulldozer_pipeline import dsm_to_dtm\n # Example with a specific number of workers\n dsm_to_dtm(dsm_path=\"<input_dsm.tif>\", output_dir=\"<output_dir>\", nb_max_workers=16)\n ```\n\n3. \u2705 Done! Your DTM is available in the *<output_dir>*\n\n## Documentation\n\n### Notebooks\n\nFor each section described in <a href=\"#key-features\">Key Features</a> section you can follow one of the tutorial notebook:\n* [Running Bulldozer (full pipeline)](docs/notebooks/0_bulldozer_pipeline.ipynb)\n* [Preprocessing standalone functions](docs/notebooks/1_preprocess.ipynb)\n* [Extraction step](docs/notebooks/2_DTM_extraction.ipynb)\n* [Postprocessing standalone functions](docs/notebooks/3_postprocess.ipynb)\n\n### Full documentation (WIP)\n**Bulldozer** also has a more detailed documentation. \nA high-level overview of how it\u2019s organized will help you know where to look for certain things:\n\n* [Tutorials](docs/tutorials/index.md) take you by the hand through a series of steps to create a DLCooker application. Start here if you\u2019re new to DLCooker.\n* [How-to guides](docs/how-to/index.md) are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how DLCooker works.\n* [Explanation guides](docs/explanation/index.md) discuss key topics and concepts at a fairly high level and provide useful background information and explanation.\n\n> **_NOTE:_** The documentation is not available online yet, it needs to be built manually.\n\nTo do so, please execute the following command at the root:\n\n```console\nmkdocs serve\n```\n\n## Contribute\n\nTo do a bug report or a contribution, see the [**Contribution Guide**](CONTRIBUTING.md). \nfor any help or suggestion, feel free to contact the authors:\n\n- Dimitri Lallement : dimitri.lallement@cnes.fr\n- Pierre Lassalle : pierre.lassalle@cnes.fr\n## Licence\n\n**Bulldozer** has a Apache V2.0 license, as found in the [LICENSE](LICENSE) file.\n\n## Credits\n\nPlease refer to the [Authors file](AUTHORS.md).\n\n## Reference\n\n [D. Lallement, P. Lassalle, Y. Ott, R. Demortier, and J. Delvit, 2022. BULLDOZER: AN AUTOMATIC SELF-DRIVEN LARGE SCALE DTM EXTRACTION METHOD FROM DIGITAL SURFACE MODEL. ISPRS - International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences.](https://www.int-arch-photogramm-remote-sens-spatial-inf-sci.net/XLIII-B2-2022/409/2022/)\n",
"bugtrack_url": null,
"license": "Apache V2.0",
"summary": "Bulldozer is a DTM extraction tool requiring only a DSM as input",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/CNES/bulldozer"
},
"split_keywords": [
"bulldozer",
"dtm",
"dsm",
"3d",
"photogrammetry",
"remote sensing",
"lidar",
"cars"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f2926fb0eded2138b7eb3fa5326b03f762c1b26f67cd9c84e2029e895954a5d",
"md5": "cc49fd989f5b3e50a2549af8a557e2b5",
"sha256": "55aff15db3c1c5eab029c8fdda595c64a7cd8bbc3d00aa632e2f91e9767bc944"
},
"downloads": -1,
"filename": "bulldozer-dtm-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "cc49fd989f5b3e50a2549af8a557e2b5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 355490,
"upload_time": "2023-07-05T16:17:22",
"upload_time_iso_8601": "2023-07-05T16:17:22.395876Z",
"url": "https://files.pythonhosted.org/packages/7f/29/26fb0eded2138b7eb3fa5326b03f762c1b26f67cd9c84e2029e895954a5d/bulldozer-dtm-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-05 16:17:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CNES",
"github_project": "bulldozer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "bulldozer-dtm"
}
JSON
