Metadata-Version: 2.4
Name: bulldozer-dtm
Version: 1.2.0
Summary: Bulldozer is a DTM extraction tool requiring only a DSM as input
Home-page: https://github.com/CNES/bulldozer
Author: CNES
Author-email: dimitri.lallement@cnes.fr
License: Apache V2.0
Keywords: bulldozer,DTM,DSM,3D,Photogrammetry,Remote Sensing,LiDAR,CARS
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Cython
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Cython>=0.29.14
Requires-Dist: numpy>=1.22.2
Requires-Dist: rasterio>=1.2.10
Requires-Dist: scipy>=1.8.0
Requires-Dist: scikit-image
Requires-Dist: PyYAML
Requires-Dist: tqdm
Requires-Dist: argcomplete
Requires-Dist: psutil
Requires-Dist: pylint
Provides-Extra: dev
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: isort>=5.8.0; extra == "dev"
Requires-Dist: black>=24.1a1; extra == "dev"
Requires-Dist: flake8>=3.9.1; extra == "dev"
Requires-Dist: flake8-comprehensions>=3.4.0; extra == "dev"
Requires-Dist: flake8-bugbear>=21.4.3; extra == "dev"
Requires-Dist: flake8-pyproject; extra == "dev"
Requires-Dist: pylint>=2.8.12; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-sugar; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Provides-Extra: notebook
Requires-Dist: matplotlib; extra == "notebook"
Requires-Dist: jupyterlab; extra == "notebook"
Dynamic: license-file

<div align="center">
    <img src="https://raw.githubusercontent.com/CNES/bulldozer/master/docs/source/images/logo_with_text.png" width=600>

**Bulldozer, a DTM extraction tool that requires only a DSM as input.**

[![pypi](https://img.shields.io/pypi/v/bulldozer-dtm?color=%2334D058&label=pypi)](https://pypi.org/project/bulldozer-dtm/)
[![docker](https://badgen.net/docker/size/cnes/bulldozer?icon=docker&label=image%20size)](https://hub.docker.com/r/cnes/bulldozer)
[![contributions welcome](https://img.shields.io/badge/contributions-welcome-orange.svg)](CONTRIBUTING.md)
[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
</div>


# Overview
<div align="center">
<img src="https://raw.githubusercontent.com/CNES/bulldozer/master/docs/source/images/result_overview.gif" alt="demo" width="400"/>
</div>
 
**Bulldozer** is a pipeline designed to extract a *Digital Terrain Model* (DTM) from a *Digital Surface Model* (DSM). It supports both noisy satellite DSMs and high-quality LiDAR DSMs.

# Quick Start

## Installation
You can install **Bulldozer** by running the following command:
```sh
pip install bulldozer-dtm
```
Or you can clone the github repository and use the `Makefile`:
```sh
# Clone the project
git clone https://github.com/CNES/bulldozer.git
cd bulldozer/

# Create the virtual environment and install required depencies
make install

# Activate the virtual env
source bulldozer_venv/bin/activate
```
## Run **Bulldozer**

There are different ways to launch **Bulldozer**:

1. Using the CLI *(Command Line Interface)* - Run the folowing command line after updating the parameters `input_dsm.tif` and `output_dir`:
```console
bulldozer -dsm input_dsm.tif -out output_dir
```
*You can also add optional parameters such as `-dhm`, please refer to the  helper (`bulldozer -h`) command to see all the options.*  

✅ Done! Your DTM is available in the `output_dir`.

2. Using the Python API - You can directly provide the input parameters to the `dsm_to_dtm` function:
```python
from bulldozer.pipeline.bulldozer_pipeline import dsm_to_dtm

dsm_to_dtm(dsm_path="input_dsm.tif", output_dir="output_dir")
```
✅ Done! Your DTM is available in the `output_dir`.

3. Using a configuration file (CLI) - Based on provided [configuration file](conf) templates, you can run the following command line:
```console
bulldozer conf/configuration_template.yaml
```
✅ Done! Your DTM is available in the directory defined in the configuration file.

## **Bulldozer** docker image

**Bulldozer** is available on Docker Hub and can be downloaded using:
``` bash
docker pull cnes/bulldozer
```
And you can run **Bulldozer** with the following command:
``` bash
docker run --user $(id -u):$(id -g) -v <path>:/data cnes/bulldozer:latest /data/<conf>.yaml
```
⚠️ You have to change the `<path>` to provide a valide absolute path to a directory where the input data are stored and where **Bulldozer** will write the ouput DTM. You also have to provide a configuration file (and rename `<conf>.yaml` in the command line) in this directory with an `ouput_dir` value using the `data` folder given to docker, e.g.: `output_dir : "/data/outputdir"`.  



# License

**Bulldozer**  is licensed under Apache License v2.0. Please refer to the [LICENSE](LICENSE) file for more details.

# <a name="Citation"></a>Citation
If you use **Bulldozer** in your research, please cite the following paper:
```text
@article{bulldozer2023,
  title={Bulldozer, a free open source scalable software for DTM extraction},
  author={Dimitri, Lallement and Pierre, Lassalle and Yannick, Ott},
  journal = {The International Archives of the Photogrammetry, Remote Sensing and Spatial Information Sciences},
  volume = {XLVIII-4/W7-2023},
  year = {2023},
  pages = {89--94},
  url = {https://isprs-archives.copernicus.org/articles/XLVIII-4-W7-2023/89/2023/},
  doi = {10.5194/isprs-archives-XLVIII-4-W7-2023-89-2023}
}
```
