README.md

FibeR-CNN

This repository demonstrates the deep learning-based analysis of individual, agglomerated, looped and/or occluded fibers. It accompanies the following publication:
FibeR-CNN: Expanding Mask R-CNN to Improve Image-Based Fiber Analysis

The utilized region-based convolutional neural network (R-CNN) was inspired by the Mask R-CNN and Keypoint R-CNN architecture, developed by He et al. and is based on an implementation of Wu et al., realized with PyTorch.

Table of Contents

• FibeR-CNN
• Table of Contents
• Examples
• Citation
• Setup
• Getting started

Examples

Detection

Fiber Width and Length Measurement

Citation

If you use this repository for a publication, then please cite it using the following bibtex-entry:

@article{Frei.2021,
	title = {{FibeR}-{CNN}: {Expanding} {Mask} {R}-{CNN} to improve image-based fiber analysis},
	volume = {377},
	issn = {0032-5910},
	url = {https://doi.org/10.1016/j.powtec.2020.08.034},
	doi = {10.1016/j.powtec.2020.08.034},
	journal = {Powder Technology},
	author = {Frei, M. and Kruis, F. E.},
	year = {2021},
	pages = {974--991}
}

Setup

The setup assumes that you have an Nvidia GPU in your system. However, it should be possible to run the code without a compatible GPU, by adjusting the relevant packages (pytorch and detectron2). As of now, detectron2 does not officially support Windows. However, there have been reports that it can be run on Windows with some tweaks (see this repository and the accompanying tutorial).

Docker

1. Install docker.
2. Install docker-compose.
3. Install nvidia-docker.
4. Open a command line.
5. Clone this repository:
   git clone https://github.com/maxfrei750/FibeR-CNN.git
6. Change into the folder of the repository:
   cd FibeR-CNN
7. Follow the instructions in the docker/README.md file.

Conda

1. Install conda.
2. Open a command line.
3. Clone this repository:
   git clone https://github.com/maxfrei750/FibeR-CNN.git
4. Change into the folder of the repository:
   cd FibeR-CNN
5. Create a new conda environment:
   conda env create --file environment.yaml
6. Activate the new conda environment:
   activate FibeR-CNN
7. Manually install detectron2:
   pip install detectron2==0.1 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu101/torch1.4/index.html

Getting started

Depending on your use case, the following scripts are good starting points:
demo.py
train_model.py
evaluate_model.py

Annotating your own data

If applying the pretrained FibeR-CNN to your dataset does not achieve good enough results, it can be helpful to re-train it on your own data. To annotate your data, our FiberAnnotator application might be helpful.