Skip to main content

MTLearn

CI Package

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:

pip install mtlearn

See the guides for installation and source builds:

Quick Start

Create a CFP layer and run a forward pass:

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.

Examples and Reproducibility

Executable examples are available in notebooks/. Notebook dependency setup is documented in docs/installation.md.

For ICPR 2026 Reproducible Research in Pattern Recognition (RRPR) review, use RRPR guide 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 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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mtlearn-1.1.0.tar.gz (625.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mtlearn-1.1.0-cp314-cp314-win_amd64.whl (774.1 kB view details)

Uploaded CPython 3.14Windows x86-64

mtlearn-1.1.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (629.5 kB view details)

Uploaded CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mtlearn-1.1.0-cp314-cp314-macosx_11_0_arm64.whl (496.6 kB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

mtlearn-1.1.0-cp313-cp313-win_amd64.whl (760.7 kB view details)

Uploaded CPython 3.13Windows x86-64

mtlearn-1.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (629.1 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mtlearn-1.1.0-cp313-cp313-macosx_11_0_arm64.whl (495.8 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

mtlearn-1.1.0-cp312-cp312-win_amd64.whl (760.7 kB view details)

Uploaded CPython 3.12Windows x86-64

mtlearn-1.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (629.1 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mtlearn-1.1.0-cp312-cp312-macosx_11_0_x86_64.whl (529.5 kB view details)

Uploaded CPython 3.12macOS 11.0+ x86-64

mtlearn-1.1.0-cp312-cp312-macosx_11_0_arm64.whl (495.8 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

mtlearn-1.1.0-cp311-cp311-win_amd64.whl (756.9 kB view details)

Uploaded CPython 3.11Windows x86-64

mtlearn-1.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (628.4 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mtlearn-1.1.0-cp311-cp311-macosx_11_0_x86_64.whl (525.3 kB view details)

Uploaded CPython 3.11macOS 11.0+ x86-64

mtlearn-1.1.0-cp311-cp311-macosx_11_0_arm64.whl (494.4 kB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

mtlearn-1.1.0-cp310-cp310-win_amd64.whl (755.7 kB view details)

Uploaded CPython 3.10Windows x86-64

mtlearn-1.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (627.4 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mtlearn-1.1.0-cp310-cp310-macosx_11_0_x86_64.whl (523.9 kB view details)

Uploaded CPython 3.10macOS 11.0+ x86-64

mtlearn-1.1.0-cp310-cp310-macosx_11_0_arm64.whl (492.7 kB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

mtlearn-1.1.0-cp39-cp39-win_amd64.whl (755.3 kB view details)

Uploaded CPython 3.9Windows x86-64

mtlearn-1.1.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (627.2 kB view details)

Uploaded CPython 3.9manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mtlearn-1.1.0-cp39-cp39-macosx_11_0_x86_64.whl (523.9 kB view details)

Uploaded CPython 3.9macOS 11.0+ x86-64

mtlearn-1.1.0-cp39-cp39-macosx_11_0_arm64.whl (493.3 kB view details)

Uploaded CPython 3.9macOS 11.0+ ARM64

File details

Details for the file mtlearn-1.1.0.tar.gz.

File metadata

  • Download URL: mtlearn-1.1.0.tar.gz
  • Upload date:
  • Size: 625.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0.tar.gz
Algorithm Hash digest
SHA256 77d92a8513facb72499e195395ce7414dcd4fbca5c4d0c027aea1ba94fdc73e4
MD5 cb2c523543636f1c75304c1e011594be
BLAKE2b-256 31e3bf3ba59786f3b019cc2bc25c6a5e9bbecf61f1e9ec4ca4c893ca4b3d94e3

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: mtlearn-1.1.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 774.1 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 c3d672f1d549c52205bf39d4e991e1f58144324cf166caa737c6ca90d93fd207
MD5 4592a0f30de1b3d7ba4e512f273e92f4
BLAKE2b-256 bafd41aaca5fe97eba788e21ccafd95b24fa12b0cd39380c21f738b2c8b557cb

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 bb209c6ea5784a3f7c8858999696587886936229c955d017df2c9daded4c0727
MD5 4fd9131d5a7aaa5acfbac820355612dc
BLAKE2b-256 53e7f73420ff0e7125ea4e3c5a4ad60b70e671c83ce5998f71bbea03e1a1bbf8

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0c6c4454b4b2d69fa5e7fd9bd099f5af8db7047b9e84fe8689d15b93fa582251
MD5 5ef66f827b1245d33eec398b7c81660e
BLAKE2b-256 3a318801fc8e9ae0b0951fa0559ffbd4bae404211afb02c0f42ae93baad84fc8

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: mtlearn-1.1.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 760.7 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 2847da7c852380750b6653c96ab9c03e8e4e3479e5a1030c78b2f5c5a1562579
MD5 909913a893ce7846b86370c2eb46cf27
BLAKE2b-256 b320a23d5fd48bae84d954a8e9ee095888b5cef9ef31e9b42843258eb741fb4f

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 066a4089b65ed19a512c7188e65eab500e8206304b52a1eab8fca0367f37aee4
MD5 88b80de87b4cb7cbf3e54587947d1c84
BLAKE2b-256 b913ff25d9929095ad581d1f6a2caa8785bc4cf8c572bc9c3e00c7818500053c

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1d034869efd0d74ba560d05f648a63936294036786a333ca818b3561cf687d41
MD5 1ede9dcd80ef3932a2d68695ff6a2009
BLAKE2b-256 72471a075dd77c6c92453651afbf749434af4e636b51e212bfde22a4afcca6ec

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: mtlearn-1.1.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 760.7 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 17866f79c4539107bed2aa980dd289d939d3536a97d61e39d7bf6e18dcd5026c
MD5 2bce5574b77fc35d38008a2c26608b4e
BLAKE2b-256 f12d5e887a8178e713af5aff69416e5a70de08002c3b771f2d99b0cef6cbe565

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d999861e560fc5bdf033287ba176f58dcb8a9db88dbc641ef0d3469594e8ced4
MD5 5c8457947df8377458541c3685ccfa35
BLAKE2b-256 b2c4a93a2a25a8c29f2e48f69de68ec9c3dd32eb6a38a0d5c4406426111cd87e

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp312-cp312-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp312-cp312-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 8277264b687fb358f6d3761ba990edc91d8d5f249af93818d42adf1a9a0d4fce
MD5 a5e766ac72a301c9848cf9895512ef67
BLAKE2b-256 bf387b196e19cd3407e29d4e323b19b440279e8248f7a96996d18e6ac62dde24

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 85c06ddc8d7478e4afe5131f991dc64837723f72c37fed7e45029b387c10486c
MD5 ad1799de7e9d014dd983c9e7ed2acc56
BLAKE2b-256 60af29adfc85f26eeb43897b30c851718a48289f636dfcdabbdbc85d06960366

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: mtlearn-1.1.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 756.9 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 d3c78540c434fa39f4747853960fccc0d20eb0acaab2f7a43c7d8f7e6bb35fe8
MD5 57c03fb20db044a3eb9dde57841962bf
BLAKE2b-256 fa730c4cbe1c2ca61cbe582b949c3000da4f7b0ffff922f082af13da1c4afb3d

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 5b403fbab8d31375bff60c522972a053770cde6a0fb64927383eb9327687fdd2
MD5 8656772765a48dfecb263e4b227403c5
BLAKE2b-256 7426b381e51dc50723a6e1403308ad6e4d2c32d6b62d68d193bd5d4edec69a5a

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp311-cp311-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp311-cp311-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 1ac28718a70137b68618681feb1030301610dfff7652aa8d016ecf0ca2568b2c
MD5 9b5f6a3ba66a6798f22412bad1cd6876
BLAKE2b-256 768586aba4dd2139f9522f27aae45111ca352b73a9cca356a269908f3cd5a139

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f6762a752c8874555b3260a799b8d470fac9dbb8126e70cc2512dae404ba0860
MD5 22a140b96832bb681d79ba1cc5def715
BLAKE2b-256 ebad61171f9340bc764c4180dc15c941b85aed18b1cd719f86cb2246e6fd3baf

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: mtlearn-1.1.0-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 755.7 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 5faf00cf6c1aadda7733e55ca98f9ac8d68ff7e5919a27a478dcabf8e6ae5724
MD5 ddeb77135900b8c673e571d5ee1bd083
BLAKE2b-256 fc43e7e9a6ed91ef14ab2879c611031ae0be67f16f807e2485c776624acfe7a9

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b5ad1774438441ae165a7673e82588de6aa9606251828796edd8d6287e841c69
MD5 3430912d41e9f1c6d10aacc58185d585
BLAKE2b-256 5a52cce26a7ef687b63302e99fa21fb93bfc9250ed4ed1bdc5bd6edbd8062ccc

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp310-cp310-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp310-cp310-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 a4f54439cc528539cdbf6b111fbb9173db1819736c00d3cd4fabc6c05244467e
MD5 500fbc558271a97a1070a542b958ac89
BLAKE2b-256 ea5689ef0de006c74222488fcc7ae353f909dae7b920d837407b5cbda3e29b44

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 66c9b036495a3cd578565ecab7cec38eed080c2ecbfb999c1e0e69ae38fc322b
MD5 2b26e8bb39583fce38d97ed2bccff69b
BLAKE2b-256 0e3552be6a11af538815eeb079eaf75a08e3f5dd9eb939c7cc38cf36830afbb2

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp39-cp39-win_amd64.whl.

File metadata

  • Download URL: mtlearn-1.1.0-cp39-cp39-win_amd64.whl
  • Upload date:
  • Size: 755.3 kB
  • Tags: CPython 3.9, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for mtlearn-1.1.0-cp39-cp39-win_amd64.whl
Algorithm Hash digest
SHA256 913b7659eb39e6a8010519f96e8aa89e4ee2dec783ea0d885ec128752a9d49e3
MD5 c79e4410cb0fefbde717694e7942744a
BLAKE2b-256 98b9efcec5c8d30124875e8843e77ab56814a265ed93ef395a3d02f696ac5fa7

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp39-cp39-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 de3a2b4247798ce9fe4d9789730113f70cc49edf6f75a9b63a5c4152bc0ebdaa
MD5 69e3ae93626d308adce66b4e5a40ab89
BLAKE2b-256 8a7aebadc8632e988fa9e369690d6adaa30eddac545a0c5df6a0ccb55c6ea090

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp39-cp39-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp39-cp39-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 657645fbb15922b1e0b1b32c3ffd2d86bcba8dd683f08c2a69fabbd43a5da1ee
MD5 3e0e719b669b3c9e08cc97f270611159
BLAKE2b-256 f1c510f9126a0e2753bb75f93497e47c5f028c1ab3f52dd52ba0ff78a309dad5

See more details on using hashes here.

File details

Details for the file mtlearn-1.1.0-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for mtlearn-1.1.0-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 af69da2833f0c1c3087c29290f109ffbae8594abc4236ebaa895d85b58501cd5
MD5 289fcfa822ba7e47e48c65d386a517d2
BLAKE2b-256 a6b635a179b515be3c619b23b04fe2946bbd6751ba25376277f34b4d27d863ec

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.1.0 This release

23 files

1.0.11

23 files

1.0.10

23 files

1.0.9

23 files

1.0.8

23 files

1.0.7

23 files

1.0.6

23 files

1.0.5

23 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page