Metadata-Version: 2.4
Name: tree-ring-analyzer
Version: 0.1.3.1
Summary: A package that allows to segment tree rings.
Author-email: Thi-Thu-Khiet DANG <dangthithukhiet7988@gmail.com>, "Clément H. BENEDETTI" <clement.benedetti@mri.cnrs.fr>, Volker Baecker <volker.baecker@mri.cnrs.fr>
License: 
        The MIT License (MIT)
        
        Copyright (c) 2024 Clément H. BENEDETTI
        
        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.
        
Project-URL: Bug Tracker, https://github.com/MontpellierRessourcesImagerie/tree-ring-analyzer/issues
Project-URL: Documentation, https://github.com/MontpellierRessourcesImagerie/tree-ring-analyzer#README.md
Project-URL: Source Code, https://github.com/MontpellierRessourcesImagerie/tree-ring-analyzer
Project-URL: User Support, https://github.com/MontpellierRessourcesImagerie/tree-ring-analyzer/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scikit-image
Requires-Dist: opencv-python-headless
Requires-Dist: tifffile
Requires-Dist: tensorflow==2.17.0
Requires-Dist: python-polylabel
Provides-Extra: testing
Requires-Dist: tox; extra == "testing"
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-cov; extra == "testing"
Requires-Dist: numpy; extra == "testing"
Requires-Dist: scikit-image; extra == "testing"
Requires-Dist: opencv-python-headless; extra == "testing"
Requires-Dist: pint; extra == "testing"
Requires-Dist: tifffile; extra == "testing"
Requires-Dist: tensorflow==2.17.0; extra == "testing"
Requires-Dist: python-polylabel; extra == "testing"
Dynamic: license-file

# Tree Ring Analyzer

Tree Ring Analyzer is an automatic framework that allows the segmentation and detection of tree rings on 2D stained microscopy images.

## Preparations
### Dataset
The input image should be stained microscopy cross-sectional tree-ring image with the format of TIF file.

### Downloading dependencies
Run the following command to install the necessary libraries
```
pip install -e .
```

### Pre-processing
Please run the file `preprocessing.py` to generate pre-processed data before training, in which:
- input_path: directory of original images
- mask_path: directory of ground truths
- pith_path: directory of pre-processed images for training pith-prediction model. If None, the pith dataset would not be generated.
- tile_path: directory of pre-processed images for training ring-regression model. If None, the ring dataset would not be generated.
- pithWhole: True/False. If True, the pith image would not be cropped (default is False).
- whiteHoles: True/False. If True, the white holes would be added into ring dataset for augmentation (default is True).
- gaussianHoles: True/False. If True, the gaussian holes would be added into ring dataset for augmentation (default is False).
- changeColor: True/False. If True, the order of image channels would be changed for augmentation (default is False).
- dilate: an interger. If not None, the tree rings in ground truth would be dilated with the given number of iterations before calculating the distance map (default is True).
- distance: True/False. If True, distance map would be calculated.
- skeleton: True/False. If True, the tree rings in ground truth would be skeletonized.

## Training
Please run the file `training.py` to train the pith-prediction or ring-regression models, in which:
- train_input_path: directory of training input path
- train_mask_path: directory of training mask path
- val_input_path: directory of validation input path
- val_mask_path: directory of validation mask path
- filter_num: the number of filters in UNet architecture (default is [16, 24, 40, 80, 960])
- attention: True/False. If True, the model would be Attention UNet.
- output_activation: output activation. In pith prediction, the recommended output activation is 'sigmoid', while in the ring regression, the recommended output activation is 'linear'.
- loss: loss function. In pith prediction, the recommended loss function is bce_dice_loss(bce_coef=0.5), while in the ring regression, the recommended loss function is 'mse'. 
- name: name of the saved model
- numEpochs: number of epochs. In pith prediction, the recommended number is 100, while in the ring regression, the recommended number is 30. 
- input_size: size of input. Default is (256, 256, 1).

The outputs would include:
- models in keras and H5 formats (saved in models folder).
- history in JSON format (saved in history folder)

## Testing
Please run the file `test_segmentation.py` to test, in which:
- input_folder: directory of original input path (no pre-processing)
- mask_folder: directory of original mask path (no pre-processing)
- output_folder: directory of output path
- checkpoint_ring_path: directory of trained ring-regression model
- checkpoint_pith_path: directory of trained pith-prediction model
- csv_file: directory of output csv file
- pithWhole: True/False. If True, the pith image would not be cropped (default is False).
- rotate: True/False. If True, FDRS algorithm would be used (default is True).
- removeRing: True/False. If True, IRR algorithm would be used (default is True).
- lossType: the type of heuristic function, including 'H0', 'H01', and 'H02' (default is 'H0').
- thickness: the thickness of output ring

The outputs would include the predicted rings in output folder and csv file (containing the results of the evaluation metrics, including Hausdorff distance, mAR, ARAND, recall, precision, accuracy).

[🐛 Found a bug?]: https://github.com/MontpellierRessourcesImagerie/tree-ring-analyzer/issues
[🔍 Need some help?]: mri-cia@mri.cnrs.fr
