# Morphocore
Morphocore is a Python library designed to integrate mathematical morphology into neural networks. It provides differentiable (float and double) and optimized morphological operations, enabling deep learning architectures to leverage powerful image processing tools from mathematical morphology.
## Main Features
- Primary morphological operations (dilation, erosion)
- Smorph (An alpha softmax based approximation of dilation or erosion : https://www.lre.epita.fr/dload/papers/hermary.22.jmiv.pdf)
- CPU and CUDA implementations (Related work: https://github.com/Manza12/nnMorpho)
## Installation
### Installation from PyPi:
```bash
pip install morphocore
```
❗If you have compatibility issue with the version compile on Pypi please compile the library from source like below !
### Installation from source:
```bash
git clone git@gitlab.lre.epita.fr:aurelien.hurand/morphocore.git
cd morphocore
pip install . --no-build-isolation
```
## API Reference
### Functional Interface
#### `dilation(input, weight, channel_merge_mode="max")`
Performs morphological dilation on the input tensor.
**Parameters:**
- `input` (Tensor): Input tensor of shape (B, C, H, W)
- `weight` (Tensor): Structuring element of shape (out_channels, in_channels, kH, kW)
- `channel_merge_mode` (str): Channel combination method - "max", "min", "sum", or "mean"
**Returns:**
- `output` (Tensor): Dilated tensor of shape (B, out_channels, H, W)
```python
from morphocore.functional import dilation
# Basic usage
result = dilation(image, structuring_element, "sum")
# With different merge modes
max_result = dilation(image, kernel, "max") # Maximum across channels
sum_result = dilation(image, kernel, "sum") # Sum across channels
mean_result = dilation(image, kernel, "mean") # Average across channels
```
#### `erosion(input, weight, channel_merge_mode="max")`
Performs morphological erosion on the input tensor.
**Parameters:** Same as `dilation()`
**Returns:** Same as `dilation()`
```python
from morphocore.functional import erosion
result = erosion(image, structuring_element, "sum")
```
#### `smorph(input, weight, channel_merge_mode="max", alpha=0.0)`
Smooth approximation of morphological operations using softmax.
**Parameters:**
- Same as `dilation()` plus:
- `alpha` (float): Control parameter for either dilation or erosion behaviour
- When alpha is large -> smorph behaves like dilation
- When alpha is very negative -> smorph behaves like erosion
- When alpha is close to 0 -> then smorph is something between an erosion and a dilation.
```python
from morphocore.functional import smorph
# Soft approximation of morphological operations
result = smorph(image, kernel, "sum", alpha=0.0)
```
### Neural Network Modules
#### `Mnn.Dilation(in_channels, out_channels, kernel_size, channel_merge_mode="max")`
Learnable dilation layer for neural networks.
**Parameters:**
- `in_channels` (int): Number of input channels
- `out_channels` (int): Number of output channels
- `kernel_size` (int or tuple): Size of the morphological kernel
- `channel_merge_mode` (str): Channel merge strategy
```python
import morphocore.nn as Mnn
# Create a learnable dilation layer
dilation_layer = Mnn.Dilation(
in_channels=3,
out_channels=16,
kernel_size=(3, 3),
channel_merge_mode="sum"
)
output = dilation_layer(input_tensor)
```
#### `Mnn.Erosion(in_channels, out_channels, kernel_size, channel_merge_mode="max")`
Learnable erosion layer for neural networks.
```python
erosion_layer = Mnn.Erosion(
in_channels=3,
out_channels=16,
kernel_size=(5, 5),
channel_merge_mode="mean"
)
output = erosion_layer(input_tensor)
```
#### `Mnn.Smorph(in_channels, out_channels, kernel_size, channel_merge_mode="max", alpha=1.0)`
Smooth morphological layer using softmax approximation.
```python
smorph_layer = Mnn.Smorph(
in_channels=3,
out_channels=8,
kernel_size=(3, 3),
channel_merge_mode="sum",
alpha=2.0
)
output = smorph_layer(input_tensor)
```
## Channel Merge Modes Explained
- **"max"**: Takes the maximum value across input channels
- **"min"**: Takes the minimum value across input channels
- **"sum"**: Sums values across input channels
- **"mean"**: Averages values across input channels
## Project Structure
- `morphocore/functional/`: Basic morphological functions
- `morphocore/nn/`: PyTorch modules for neural networks
- `morphocore/functional/csrc/`: C++/CUDA source code for acceleration
- `tests/`: Unit, functional and benchmark tests
## Dependencies
- Python >= 3.8
- PyTorch
- NumPy
## Contributing
Contributions are welcome! Please submit issues and pull requests.
## License
This project is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "morphocore",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "morphology, cuda, pytorch, computer-vision",
"author": null,
"author_email": "Aurelien HURAND <aurelien.hurand@gmail.com>",
"download_url": null,
"platform": null,
"description": "# Morphocore\n\nMorphocore is a Python library designed to integrate mathematical morphology into neural networks. It provides differentiable (float and double) and optimized morphological operations, enabling deep learning architectures to leverage powerful image processing tools from mathematical morphology.\n\n## Main Features\n- Primary morphological operations (dilation, erosion)\n- Smorph (An alpha softmax based approximation of dilation or erosion : https://www.lre.epita.fr/dload/papers/hermary.22.jmiv.pdf)\n- CPU and CUDA implementations (Related work: https://github.com/Manza12/nnMorpho)\n\n## Installation\n\n### Installation from PyPi:\n\n```bash\npip install morphocore\n```\n\n\u2757If you have compatibility issue with the version compile on Pypi please compile the library from source like below !\n\n### Installation from source: \n\n```bash\ngit clone git@gitlab.lre.epita.fr:aurelien.hurand/morphocore.git\ncd morphocore\npip install . --no-build-isolation\n```\n\n## API Reference\n\n### Functional Interface\n\n#### `dilation(input, weight, channel_merge_mode=\"max\")`\nPerforms morphological dilation on the input tensor.\n\n**Parameters:**\n- `input` (Tensor): Input tensor of shape (B, C, H, W)\n- `weight` (Tensor): Structuring element of shape (out_channels, in_channels, kH, kW)\n- `channel_merge_mode` (str): Channel combination method - \"max\", \"min\", \"sum\", or \"mean\"\n\n**Returns:**\n- `output` (Tensor): Dilated tensor of shape (B, out_channels, H, W)\n\n```python\nfrom morphocore.functional import dilation\n\n# Basic usage\nresult = dilation(image, structuring_element, \"sum\")\n\n# With different merge modes\nmax_result = dilation(image, kernel, \"max\") # Maximum across channels\nsum_result = dilation(image, kernel, \"sum\") # Sum across channels\nmean_result = dilation(image, kernel, \"mean\") # Average across channels\n```\n\n#### `erosion(input, weight, channel_merge_mode=\"max\")`\nPerforms morphological erosion on the input tensor.\n\n**Parameters:** Same as `dilation()`\n**Returns:** Same as `dilation()`\n\n```python\nfrom morphocore.functional import erosion\n\nresult = erosion(image, structuring_element, \"sum\")\n```\n\n#### `smorph(input, weight, channel_merge_mode=\"max\", alpha=0.0)`\nSmooth approximation of morphological operations using softmax.\n\n**Parameters:**\n- Same as `dilation()` plus:\n- `alpha` (float): Control parameter for either dilation or erosion behaviour\n - When alpha is large -> smorph behaves like dilation\n - When alpha is very negative -> smorph behaves like erosion\n - When alpha is close to 0 -> then smorph is something between an erosion and a dilation.\n\n```python\nfrom morphocore.functional import smorph\n\n# Soft approximation of morphological operations\nresult = smorph(image, kernel, \"sum\", alpha=0.0)\n```\n\n### Neural Network Modules\n\n#### `Mnn.Dilation(in_channels, out_channels, kernel_size, channel_merge_mode=\"max\")`\nLearnable dilation layer for neural networks.\n\n**Parameters:**\n- `in_channels` (int): Number of input channels\n- `out_channels` (int): Number of output channels \n- `kernel_size` (int or tuple): Size of the morphological kernel\n- `channel_merge_mode` (str): Channel merge strategy\n\n```python\nimport morphocore.nn as Mnn\n\n# Create a learnable dilation layer\ndilation_layer = Mnn.Dilation(\n in_channels=3, \n out_channels=16, \n kernel_size=(3, 3), \n channel_merge_mode=\"sum\"\n)\noutput = dilation_layer(input_tensor)\n```\n\n#### `Mnn.Erosion(in_channels, out_channels, kernel_size, channel_merge_mode=\"max\")`\nLearnable erosion layer for neural networks.\n\n```python\nerosion_layer = Mnn.Erosion(\n in_channels=3, \n out_channels=16, \n kernel_size=(5, 5), \n channel_merge_mode=\"mean\"\n)\noutput = erosion_layer(input_tensor)\n```\n\n#### `Mnn.Smorph(in_channels, out_channels, kernel_size, channel_merge_mode=\"max\", alpha=1.0)`\nSmooth morphological layer using softmax approximation.\n\n```python\nsmorph_layer = Mnn.Smorph(\n in_channels=3, \n out_channels=8, \n kernel_size=(3, 3), \n channel_merge_mode=\"sum\",\n alpha=2.0\n)\noutput = smorph_layer(input_tensor)\n```\n\n## Channel Merge Modes Explained\n\n- **\"max\"**: Takes the maximum value across input channels\n- **\"min\"**: Takes the minimum value across input channels \n- **\"sum\"**: Sums values across input channels\n- **\"mean\"**: Averages values across input channels\n\n## Project Structure\n- `morphocore/functional/`: Basic morphological functions\n- `morphocore/nn/`: PyTorch modules for neural networks\n- `morphocore/functional/csrc/`: C++/CUDA source code for acceleration\n- `tests/`: Unit, functional and benchmark tests\n\n## Dependencies\n- Python >= 3.8\n- PyTorch\n- NumPy\n\n## Contributing\nContributions are welcome! Please submit issues and pull requests.\n\n## License\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Morphological operations with CUDA acceleration",
"version": "0.4.0.29",
"project_urls": {
"Bug Reports": "https://gitlab.lre.epita.fr/aurelien.hurand/morphocore/-/issues",
"Homepage": "https://gitlab.lre.epita.fr/aurelien.hurand/morphocore",
"Source": "https://gitlab.lre.epita.fr/aurelien.hurand/morphocore"
},
"split_keywords": [
"morphology",
" cuda",
" pytorch",
" computer-vision"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1abfa5acec43e34c4198793839ded4810e90b149528d855512d3341f3d6a38a2",
"md5": "d8a6b08b1372d31fbc3216b5cccec8fe",
"sha256": "c883246b927e3e4b97c650e002c1b1f586848659d2b365945e72462896542148"
},
"downloads": -1,
"filename": "morphocore-0.4.0.29-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "d8a6b08b1372d31fbc3216b5cccec8fe",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.10",
"size": 13843685,
"upload_time": "2025-10-21T11:36:29",
"upload_time_iso_8601": "2025-10-21T11:36:29.488861Z",
"url": "https://files.pythonhosted.org/packages/1a/bf/a5acec43e34c4198793839ded4810e90b149528d855512d3341f3d6a38a2/morphocore-0.4.0.29-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "876c021e07dde3e7ce87b5821caf431b369f9288349052cacfd29802af7111a9",
"md5": "3ee4f9e21ffe5f5b04a1fc65e9b9c0da",
"sha256": "c2cf7219d84604f8c047262f21d6ebc8705b791fdbd1e7bbf87f37ea00d9dfa0"
},
"downloads": -1,
"filename": "morphocore-0.4.0.29-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "3ee4f9e21ffe5f5b04a1fc65e9b9c0da",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.10",
"size": 13897172,
"upload_time": "2025-10-21T11:36:33",
"upload_time_iso_8601": "2025-10-21T11:36:33.025802Z",
"url": "https://files.pythonhosted.org/packages/87/6c/021e07dde3e7ce87b5821caf431b369f9288349052cacfd29802af7111a9/morphocore-0.4.0.29-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd43b2df6ca60916b0e8981f9bf754f26fad5fe0508dfe5ff488ccf563139118",
"md5": "745f555bb19b7db9ba3493b100defe74",
"sha256": "82d09c2a744d617845d8e59819ea2f2cb96180fbc414a151fbf37a2740d40b6d"
},
"downloads": -1,
"filename": "morphocore-0.4.0.29-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "745f555bb19b7db9ba3493b100defe74",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.10",
"size": 13892392,
"upload_time": "2025-10-21T11:36:37",
"upload_time_iso_8601": "2025-10-21T11:36:37.891900Z",
"url": "https://files.pythonhosted.org/packages/dd/43/b2df6ca60916b0e8981f9bf754f26fad5fe0508dfe5ff488ccf563139118/morphocore-0.4.0.29-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 11:36:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "morphocore"
}
JSON