Metadata-Version: 2.1
Name: deeptrees
Version: 1.6.0
Summary: Tree crown segmentation and analysis in remote sensing imagery with PyTorch
Home-page: https://codebase.helmholtz.cloud/taimur.khan/DeepTrees
Author: Taimur Khan, Caroline Arnold, Harsh Grover
Author-email: taimur.khan@ufz.de
License: MIT
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10.0
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch==2.4.0
Requires-Dist: numpy==1.26.0
Requires-Dist: segmentation-models-pytorch==0.3.3
Requires-Dist: torchvision>=0.19
Requires-Dist: torchmetrics>=1.6
Requires-Dist: xarray==2022.3.0
Requires-Dist: rasterio==1.4a3
Requires-Dist: rioxarray==0.17.0
Requires-Dist: shapely==2.0.5
Requires-Dist: scipy==1.14.0
Requires-Dist: scikit-image==0.24.0
Requires-Dist: hyperopt==0.2.7
Requires-Dist: fiona==1.9.6
Requires-Dist: psutil==6.0.0
Requires-Dist: geojson==3.1.0
Requires-Dist: geoplot==0.5.1
Requires-Dist: folium==0.17.0
Requires-Dist: hydra-core==1.3
Requires-Dist: lightning==2.4.0
Requires-Dist: onnx==1.16.2
Requires-Dist: rootutils>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: mlflow==2.18.0
Requires-Dist: ipykernel
Requires-Dist: jsonschema2md>=1.3
Provides-Extra: test
Requires-Dist: pytest; extra == "test"


 <div align="center" style="text-align:center">
  <h1 > DeepTrees 🌳</h1>
  <b>Tree Crown Segmentation and Analysis in Remote Sensing Imagery with PyTorch</b>  
    <br/>
<img src="./static/header.png" alt="DeepTrees" width="300"/>
<br/>
</div>


## Installation

To install the package, clone the repository and install the dependencies.

```bash
git clone https://codebase.helmholtz.cloud/ai-consultants-dkrz/DeepTrees.git
cd DeepTrees

## create a new conda environment
conda create --name deeptree
conda activate deeptree
conda install -c conda-forge gdal==3.9.2 pip
pip install -r requirements.txt
```
or from pip.

```bash
pip install deeptrees
```

## Documentation

This library is documented using Sphinx. To build the documentation, run the following command.

```bash
sphinx-apidoc -o docs/source deeptrees 
cd docs
make html
```

This will create the documentation in the `docs/build` directory. Open the `index.html` file in your browser to view the documentation.

## Predict on a list of images

Run the inference script with the corresponding config file on list of images.

```bash
from deeptrees import predict

predict(image_path=["list of image_paths"],  config_path = "config_path")
```


## Scripts

### Preprocessing

#### Expected Directory structure

The root folder is `/work/ka1176/shared_data/2024-ufz-deeptree/polygon-labelling/`. Sync the folder `tiles` and `labels` with the labeled tiles provided by UFZ. The unlabeled tiles go into `pool_tiles`.

```
|-- tiles
|   |-- tile_0_0.tif
|   |-- tile_0_1.tif
|   |-- ...
|-- labels
|   |-- label_tile_0_0.shp
|   |-- label_tile_0_1.shp
|   |-- ...
|-- pool_tiles
|   |-- tile_4_7.tif
|   |-- tile_4_8.tif
|   |-- ...
```

Create the new empty directories

```
|-- masks
|-- outlines
|-- dist_trafo
```

### Training

Adapt your own config file based on the defaults in `train_halle.yaml` as needed. For inspiration for a derived config file for finetuning, check `finetune_halle.yaml`.

Run the script like this:

```bash
python scripts/train.py # this is the default config that trains from scratch
python scripts/train.py --config-name=finetune_halle # finetune with pretrained model
python scripts/train.py --config-name=yourconfig # with your own config
```

To re-generate the ground truth for training, make sure to pass the label directory in `data.ground_truth_labels`. To turn it off, pass `data.ground_truth_labels=null`.

You can overwrite individual parameters on the command line, e.g.

```bash
python scripts/train.py trainer.fast_dev_run=True
```

To resume training from a checkpoint, take care to pass the hydra arguments in quotes to avoid the shell intercepting the string (pretrained model contains `=`):

```bash
python scripts/train.py 'model.pretrained_model="Unet-resnet18_epochs=209_lr=0.0001_width=224_bs=32_divby=255_custom_color_augs_k=0_jitted.pt"'
```

#### Training Logs

View the MLFlow logs that were created during training.

TODO

### Inference

Run the inference script with the corresponding config file. Adjust as needed.

```bash
python scripts/test.py --config-name=inference_halle
```


## Semantic Versioning
This reposirotry has auto semantic versionining enabled. To create new releases, we need to merge into the default `finetuning-halle` branch. 

Semantic Versionining, or SemVer, is a versioning standard for software ([SemVer website](https://semver.org/)). Given a version number MAJOR.MINOR.PATCH, increment the:

- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backward compatible manner
- PATCH version when you make backward compatible bug fixes
- Additional labels for pre-release and build metad

See the SemVer rules and all possible commit prefixes in the [.releaserc.json](.releaserc.json) file. 

| Prefix | Explanation                                                                                                                                                                                                                                     | Example                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| feat   | A new feature was implemented as part of the commit, <br>so the [Minor](https://mobiuscode.dev/posts/Automatic-Semantic-Versioning-for-GitLab-Projects/#minor) part of the version will be increased once <br>this is merged to the main branch | feat: model training updated                                            |
| fix    | A bug was fixed, so the [Patch](https://mobiuscode.dev/posts/Automatic-Semantic-Versioning-for-GitLab-Projects/#patch) part of the version will be <br>increased once this is merged to the main branch                                         | fix: fix a bug that causes the user to not <br>be properly informed when a job<br>finishes |

The implementation is based on. https://mobiuscode.dev/posts/Automatic-Semantic-Versioning-for-GitLab-Projects/


# License

This repository is licensed under the MIT License. For more information, see the [LICENSE.md](LICENSE.md) file.

# Cite as

```bib
@article{khan2025torchtrees,
        author    = {Taimur Khan and Caroline Arnold and Harsh Grover},
        title     = {DeepTrees: Tree Crown Segmentation and Analysis in Remote Sensing Imagery with PyTorch},
        journal   = {arXiv},
        year      = {2025},
        archivePrefix = {arXiv},
        eprint    = {XXXXX.YYYYY},  
        primaryClass = {cs.CV}      
      }
```
