florin: Flexible Learning-Free Reconstruction of Neural Circuits

FLoRIN is a framework for carrying out computer vision pipelines locally or at
scale.

Why FLoRIN?

Designed from the ground up for large-scale image processing (think images
with 10^4, 10^5, 10^6+ pixels).
Provides the custom N-Dimensional Neighborhood Thresholding method, which has
been shown to outperform other thresholding methods at segmenting neural
microsopy data.
Out of the box serial, parallel, and distributed processing.
Utilizes CPU (numpy) vectorized operations and methods from scientific python
libraries.
Enables pipeline reuse. Create one image processing pipeline, serialize it,
and move it to another machine running FLoRIN.

Target Audience

FLoRIN was originally designed as a pipeline for segmenting and reconstructing
volumes of neural microscopy data, allowing neuroscientists to quickly process
large volumes of data without needing to use any machine learning.
but has since been applied to iris biometrics as well. In its
current form, FLoRIN is appropriate for any computer vision application that
seeks to scale or be reproduced in multiple locations.

Installation

FLoRIN is compatible with Python 3.4+. To install FLoRIN, run

# pip
pip install florin

Documentation

Full documentation of the FLoRIN pipeline may be found at https://florin.readthedocs.io

Getting Started

A simple segmentation pipeline for microCT X-Ray data that uses multiprocessing
for subsets of operations looks like:

import florin
import florin.classify
import florin.conncomp as conncomp
import florin.morphology as morphology
import florin.thresholding as thresholding
pipeline = florin.Serial(
    # Load in the data to process
    florin.load('/path/to/my/volume'),
    # Subdivide the data into sub-arrays
    florin.tile(shape=(10, 64, 64), stride=(5, 32, 32)),
    # Segment multiple tiles independently in parallel.
    florin.Multiprocess(
        # Threshold with NDNT
        thresholding.ndnt(shape=(10, 64, 64), threshold=0.3),
        # Clean up the binarized image
        morphology.binary_opening()
    ),
    # Find connected components ad get their properties
    conncomp.label(),
    morphology.binary_fill_holes(min_size=50),
    conncomp.regionprops(),
    # Classify the connected components concurrently.
    florin.Multithread(
        # Bin connected components based on their properties
        florin.classify(
            # If 100 <= obj.area <= 500 and 25 <= obj.width <= 55 and
            # 25 <= obj <= 55 and 5 <= obj.depth <= 10, consider the connected
            # component a cell. Otherwise, consider it vasculature.
            florin.bounds_classifier(
                'cells',
                area=(100, 500),
                width=(25, 55),
                height=(25, 55),
                depth=(5, 10)),
            florin.bounds_classifier('vasculature')
        )
    ),
    # Save the output with class labels
    florin.save('segmented.tiff')
)
out = pipeline()

Maintainers

Jeff Kinnison

Contributing

To contribute, fork the main repo, add your code, and submit a pull request! FLoRIN follows PEP-8 guidelines and uses numpydoc style for documentation.

Issues

If you run across a bug, open an issue with a description, system information, and a code snippet that reprodices the error.

License

MIT License

Cite FLoRIN

The original FLoRIN paper

@article{shahbazi2018flexible,
  title={Flexible Learning-Free Segmentation and Reconstruction of Neural Volumes},
  author={Shahbazi, Ali and Kinnison, Jeffery and Vescovi, Rafael and Du, Ming and Hill, Robert and J{\"o}sch, Maximilian and Takeno, Marc and Zeng, Hongkui and Da Costa, Nuno Ma{\c{c}}arico and Grutzendler, Jaime and Kasthuri, Narayanan and Scheirer, Walter},
  journal={Scientific reports},
  volume={8},
  number={1},
  pages={14247},
  year={2018},
  publisher={Nature Publishing Group}
}

Special Thanks

A number of people contributed to FLoRIN’s development who deserve a shout out:

Original Concept

Early Development (Pre-Alpha)

FLoRIN Experimental Code

The code for the original FLoRIN paper can be found here.

The code for “Learning-Free Iris Segmentation Revisited: A First Step Toward Fast Volumetric Operation Over Video Samples” can be found here.

We are in the process of reimplementing these code bases using the official FLoRIN package here and will provide that code as a separate branch in each repository on completion.