Metadata-Version: 2.4
Name: fastlbp
Version: 0.3.4
Summary: fastLBP: parallelised and GPU-powered multi-radii Local Binary Patterns computation
Author-email: Dmytro Horyslavets <nepotlet@gmail.com>, Mykhailo Koreshkov <koreshov.m@gmail.com>
Maintainer-email: Dmytro Horyslavets <nepotlet@gmail.com>
Project-URL: Homepage, https://github.com/imbg-ua/fastLBP
Project-URL: Bug Tracker, https://github.com/imbg-ua/fastLBP/issues
Keywords: local binary patterns,visual descriptor,computer vision,image processing,parallel
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: POSIX
Classifier: Operating System :: POSIX :: Linux
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wheel
Requires-Dist: scikit-image>=0.22.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: Pillow>=10.0.1
Requires-Dist: pandas>=2.1.1
Requires-Dist: psutil
Dynamic: license-file

[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-darkgreen)](https://github.com/imbg-ua/fastLBP/blob/main/LICENSE)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fastlbp)
![PyPI - Status](https://img.shields.io/pypi/status/fastlbp)
![GitHub release](https://img.shields.io/github/v/release/imbg-ua/fastLBP)
[![PyPI](https://img.shields.io/pypi/v/fastlbp)](https://pypi.org/project/fastlbp)

# fastLBP

Highly parallel LBP implementation

> **Important pre-release warning**:
> If aborted mid-execution, this software sometimes create a lot of orphan processes that needs to be killed manually.
> Please, note down the name of your python script, search for `Python` in your task manager and look for the processes that correspond to your python script.

## Requirements

FastLBP is tested with Python 3.11 on Windows 10, Debian 11, and Ubuntu 22.04

Python requirements are:

- numpy >= 1.26.0
- Cython (to build the binary modules, will be optional in the future)
- scikit-image >= 0.22.0 (mostly for testing, we plan making this requirement optional in the future)
- pandas >= 2.1.1
- psutil

## Installation

- Activate or create a Python 3.11 environment (e.g. using `conda create -y -n p11 python=3.11 && conda activate p11`)
- Verify you are using the right env
  - `python --version` and `pip --version`
- Install a stable version from PyPI  
  `pip install fastlbp`
- Or build the latest version from sources
  ```
  git clone git@github.com:imbg-ua/fastLBP.git
  cd fastLBP
  # git checkout <branchname> # if you need a specific branch
  pip install . # this will install the fastlbp package in the current env
  ```
- You can use `import fastlbp as fastlbp` now

### GPU (CUDA) optional install

- CPU-only install (default):
  ```bash
  pip install fastlbp
  ```
- GPU build (opt-in): ensure CUDA is discoverable by setting `CUDA_HOME` (or having `nvcc` on PATH) and install the extra:
  ```bash
  export CUDA_HOME=/usr/local/cuda  # adjust to your CUDA install
  pip install fastlbp
  ```
- To hard-require CUDA and fail if not found, set:
  ```bash
  FORCE_CUDA=1 pip install fastlbp
  ```

If CUDA isn’t detected, the build will proceed with CPU-only features. At runtime, you can check availability:

```python
import fastlbp
fastlbp.fastlbp.is_cuda_available()  # -> True/False
```

## Testing

```
# in repo root
conda activate fastlbp
pip install -e .
python -m unittest
```

## Bug reporting

You can report a bug or suggest an improvement using [our github issues](https://github.com/imbg-ua/fastLBP/issues)

## Implemented modules

### run_fastlbp

Computes multiradial LBP of a single multichannel image in a parallel fashion.

Features:

- Powered by `fastlbp.lbp`, our implementation of `skimage.feature.local_binary_pattern`
- Concurrency is managed by Python's [`multiprocessing`](https://docs.python.org/3/library/multiprocessing.html) module
- Parallel computation via `multiprocessing.Pool` of size `ncpus`
- Efficient memory usage via `multiprocessing.shared_memory` to make sure processes do not create redundant copies of data
- If `save_intermediate_results=False` then computes everything in RAM, no filesystem usage

TODO:

- Use `max_ram` parameter to estimate optimal number of sub-processes and collect memory stats. Now `max_ram` **is ignored**.

## Planned modules

### run_chunked_skimage

Similar to [1. run_fastlbp](#1-run_fastlbp), but each subprocess should compute LBP for its image chunk, not the whole image.

### run_dask and run_chunked_dask

Similar to [1. run_fastlbp](#1-run_fastlbp), but use [Dask](https://docs.dask.org/en/stable/) and [`dask.array.map_overlap`](https://docs.dask.org/en/stable/generated/dask.array.map_overlap.html#dask.array.map_overlap) for parallelisation instead of `multiprocessing` and manual data wrangling
