Metadata-Version: 2.4
Name: mtlearn
Version: 1.0.11
Summary: Morphological tree learning utilities with a stable morphology facade
Author-Email: Wonder Alexandre Luz Alves <worderalexandre@gmail.com>
License-Expression: GPL-3.0-only
License-File: LICENSE
Classifier: Programming Language :: Python
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Project-URL: Source, https://github.com/wonderalexandre/MTLearn
Project-URL: Issues, https://github.com/wonderalexandre/MTLearn/issues
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23
Requires-Dist: opencv-python-headless>=4.8
Requires-Dist: torch<2.3,>=2.2.2; sys_platform == "darwin" and platform_machine == "x86_64" and python_version < "3.13"
Requires-Dist: torch<2.9,>=2.8; sys_platform == "darwin" and platform_machine == "arm64" and python_version < "3.10"
Requires-Dist: torch<2.12,>=2.10; sys_platform == "darwin" and platform_machine == "arm64" and python_version >= "3.10" and python_version < "3.14"
Requires-Dist: torch<2.12,>=2.11; sys_platform == "darwin" and platform_machine == "arm64" and python_version >= "3.14"
Requires-Dist: torch<2.9,>=2.8; sys_platform != "darwin" and python_version < "3.10"
Requires-Dist: torch<2.12,>=2.10; sys_platform != "darwin" and python_version >= "3.10" and python_version < "3.14"
Requires-Dist: torch<2.12,>=2.11; sys_platform != "darwin" and python_version >= "3.14"
Provides-Extra: notebooks
Requires-Dist: ipykernel; extra == "notebooks"
Requires-Dist: matplotlib; extra == "notebooks"
Requires-Dist: nbformat>=5; extra == "notebooks"
Requires-Dist: papermill>=2.4; extra == "notebooks"
Requires-Dist: pandas; extra == "notebooks"
Requires-Dist: scikit-learn; extra == "notebooks"
Requires-Dist: scipy; extra == "notebooks"
Requires-Dist: segmentation-models-pytorch; extra == "notebooks"
Requires-Dist: tqdm>=4.66; extra == "notebooks"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Description-Content-Type: text/markdown

# MTLearn

[![CI](https://github.com/wonderalexandre/MTLearn/actions/workflows/ci.yml/badge.svg)](https://github.com/wonderalexandre/MTLearn/actions/workflows/ci.yml)
[![Package](https://github.com/wonderalexandre/MTLearn/actions/workflows/package.yml/badge.svg)](https://github.com/wonderalexandre/MTLearn/actions/workflows/package.yml)

**MTLearn** (*Morphological Tree Learning*) is a C++/Python research library for
learnable connected operators based on morphological trees. The Python package
is published as `mtlearn`.

The library explores a simple idea: connected morphology can become a structural
prior for deep neural networks. Instead of processing images only through local
pixel-wise operations, connected operators reason over components, regions,
shape, contrast, and hierarchy. This makes them naturally interpretable and
well-suited for tasks where structure matters.

Classical connected filters are powerful, but they usually depend on hard
keep/discard decisions and manually selected attribute thresholds. This limits
their integration into end-to-end trainable neural architectures.

**MTLearn** provides a stable implementation platform for this research direction.
It currently includes Connected Filter Preprocessing (CFP), and is intended to
grow toward trainable connected-operator layers, differentiable or learnable
attribute criteria, self-dual tree representations, intermediate network
insertions, and scalable implementations.

## Main Features

- **Connected Filter Preprocessing (CFP):** the current main model, available as
  `mtlearn.layers.ConnectedFilterPreprocessingLayer`. CFP replaces hard
  connected-filter decisions with a differentiable sigmoid gate over normalized
  tree-node attributes.

- **Stable morphology interface:** `mtlearn.morphology` builds max-trees,
  min-trees, and tree-of-shapes through a backend-independent API.

- **PyTorch integration:** CFP layers are `torch.nn.Module` objects with
  trainable parameters, checkpoint helpers, and dataset-level normalization
  utilities.

- **Validation utilities:** includes C++ tests, Python tests, gradient checks,
  reference implementations, notebook utilities, and registered dataset download
  helpers.

## Install

The Python package is available from PyPI as `mtlearn`:

```bash
pip install mtlearn
```

See [docs/installation.md](docs/installation.md) for installation instructions
and [docs/development.md](docs/development.md) for source builds, validation,
and releases.

## Quick Start

Create a CFP layer and run a forward pass:

```python
import torch
from mtlearn import morphology
from mtlearn.layers import ConnectedFilterPreprocessingLayer

cfp_layer = ConnectedFilterPreprocessingLayer(
    in_channels=1,
    filter_specs=[
        {
            "tree_type": morphology.TreeType.MAX_TREE,
            "attributes": (
                morphology.AttributeType.AREA,
                morphology.AttributeType.CIRCULARITY,
            ),
        }
    ],
    device="cpu",
    scale_mode="none",
)

x = torch.tensor([[[[1, 2], [3, 4]]]], dtype=torch.float32)
y = cfp_layer(x)

assert y.shape == x.shape
```

For tree-of-shapes specs, normalization, caching, checkpoint helpers, and
attribute selection, see the guides listed below.

## Documentation

The main documentation is built with Sphinx from `docs/source`.

- [Installation](docs/installation.md)
- [Guides](docs/source/guides/index.md)
- [Python API reference](docs/source/api/python/index.rst)
- [C++ API notes](docs/source/api/cpp/index.rst)
- [Development and validation](docs/development.md)

## Examples and Reproducibility

Executable examples are available in `notebooks/`. Notebook dependency setup is
documented in [docs/installation.md](docs/installation.md).

For ICPR 2026 Reproducible Research in Pattern Recognition (RRPR) review, use
[notebooks/ICPR2026/README.md](notebooks/ICPR2026/README.md) as the canonical
guide for setup, datasets, notebook execution, hardware notes, and current
reproducibility scope.

## Scope and API Boundaries

**MTLearn** is a research-oriented library. CFP is the current validated
trainable connected-operator layer, with support for max-tree, min-tree, and
tree-of-shapes workflows; mixed tree specs; multi-attribute dataset-level
normalization; cached preprocessing; and PyTorch forward/backward for CFP
parameters on CPU or CUDA tensors.

User code should interact with morphology through the public Python facade
`mtlearn.morphology` and the primary CFP layer in `mtlearn.layers`, rather than
depending on backend-specific APIs. The backend is
[`MorphologicalAttributeFilters`](https://github.com/wonderalexandre/MorphologicalAttributeFilters)
/ `mmcfilters`, but the top-level Python package `mmcfilters` is not required
as a runtime dependency of `mtlearn`.

## Citation

If you use the CFP layer in your work, please cite:

> Wonder A. L. Alves, Lucas de P. O. Santos, Ronaldo F. Hashimoto, Nicolas Passat, Anderson H. R. Souza, Dennis J. Silva, Yukiko Kenmochi. **A trainable connected filter preprocessing layer based on component trees.** International Conference on Pattern Recognition (ICPR), 2026, Lyon, France. ⟨[hal-05575141](https://hal.science/hal-05575141/)⟩
