deeptrees 1.6.0__tar.gz

deeptrees-1.6.0/LICENSE

@@ -0,0 +1,13 @@
+
+```
+MIT License
+
+Copyright (c) 2025 Taimur Khan (UFZ), Caroline Arnold, Harsh Grover (both Helmholtz-Zentrum Hereon and Helmholtz AI)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+

deeptrees-1.6.0/PKG-INFO

@@ -0,0 +1,179 @@
+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
+Provides-Extra: test
+License-File: LICENSE
+
+
+ <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}      
+      }
+```

deeptrees-1.6.0/README.md

@@ -0,0 +1,161 @@
+ <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}      
+      }
+```

deeptrees-1.6.0/deeptrees/__init__.py

@@ -0,0 +1,43 @@
+__version__ = "v1.6.0"
+
+from . import model
+from . import modules
+from . import dataloading
+
+from .model.deeptrees_model import TreeCrownDelineationModel
+
+from .inference import TreeCrownPredictor
+
+from .pretrained import freudenberg2022
+
+import os
+
+
+def predict(image_path: list[str], config_path: str):
+    """
+    Run tree crown delineation prediction on the provided image paths using the given configuration.
+
+    Args:
+        image_path (list[str]): A list of file paths to the images to be processed.
+        config_path (str): The file path to the configuration file for the prediction.
+
+    Returns:
+        None: This function does not return any value. It performs the prediction in-place.
+    """
+    predictor = TreeCrownPredictor(image_path=image_path, config_path=config_path)  # Uses default config path and name
+    predictor.predict()
+
+
+def download_pre_trained_model_weights():
+    """
+    Downloads the pretrained model weights for the Freudenberg et al. 2022 model.
+    
+    Args:
+        download_path (str): The path to save the downloaded model weights to.
+    """
+    
+    os.makedirs('./pretrained_models', exist_ok=True)
+    
+    file_name = os.path.join('./pretrained_models', "lUnet-resnet18_epochs=209_lr=0.0001_width=224_bs=32_divby=255_custom_color_augs_k=3_jitted.pt")
+    
+    freudenberg2022(file_name)