Skip to main content

Serron

Mathematical Morphology module for PyTorch (CUDA), providing differentiable operators and learnable network layers.

Install

Prebuilt wheels are published for CPython 3.12–3.14 on Linux (x86_64, aarch64) and Windows (x86_64). A working CUDA-enabled PyTorch (torch >= 2.12) must already be installed in the environment.

pip install serron

Usage

Alpha: the CUDA kernels are not wired up yet, so the operators below currently raise NotImplementedError.

Serron works on standard PyTorch tensors laid out as (N, C, H, W) and living on a CUDA device.

Functional operators

Stateless operators live in serron.functional and are re-exported at the top level. Each takes an input tensor, a structuring element, and an optional border mode:

import torch
import serron
from serron import BorderMode
from serron import structuring_element as se

x = torch.rand(1, 1, 256, 256, device="cuda")
kernel = se.disk(3, device="cuda")

eroded = serron.erosion(x, kernel)
dilated = serron.dilatation(x, kernel)
opened = serron.opening(x, kernel)
closed = serron.closing(x, kernel)

# Derived operators
grad = serron.gradient(x, kernel)  # dilate(x) - erode(x)
white = serron.top_hat(x, kernel)  # x - open(x)
black = serron.black_hat(x, kernel)  # close(x) - x

# Control border handling
eroded_reflect = serron.erosion(x, kernel, border=BorderMode.REFLECT)

Available operators: erosion, dilatation, opening, closing, gradient, top_hat, black_hat.

Structuring elements

serron.structuring_element builds common SE shapes on the requested device:

from serron import structuring_element as se

se.square(5, device="cuda")  # (5, 5) full square
se.cross(5, device="cuda")  # (5, 5) plus shape
se.disk(3, device="cuda")  # (7, 7) disk, radius 3
se.diamond(3, device="cuda")  # (7, 7) diamond, radius 3
se.from_tensor(my_weights)  # wrap an arbitrary 2-D tensor as a grayscale SE

Border modes

BorderMode controls how out-of-bounds neighbors are handled:

Mode Behavior
BorderMode.REPLICATE Repeat the edge value (default)
BorderMode.REFLECT Mirror across the edge
BorderMode.CONSTANT Pad with a constant

Learnable layers

serron also exposes torch.nn.Module layers with a learnable structuring element, so morphology can be trained end-to-end inside a network. Each layer takes the number of channels and a kernel_size:

import torch
from serron import Erosion2d, Dilation2d, Opening2d, Closing2d
from serron import BorderMode

layer = Erosion2d(channels=3, kernel_size=5, border=BorderMode.REPLICATE).cuda()

x = torch.rand(8, 3, 64, 64, device="cuda")
y = layer(x)  # forward pass; layer.weight is a trainable (C, k, k) SE
y.sum().backward()  # gradients flow into layer.weight

Available layers: Erosion2d, Dilation2d, Opening2d, Closing2d.

Building from source

Clone repo

git clone git@github.com:vhrabar/serron.git
cd serron

Choosing a torch build

torch is pulled from a specific wheel index via mutually-exclusive extras. Pick the one matching your machine — plain uv sync (no extra) falls back to the default CUDA-enabled wheel from PyPI:

uv sync --extra cu132   # CUDA build
uv sync --extra cpu     # CPU-only build

Building the wheel

Building the CUDA extension from source needs the CUDA 13.X toolkit (nvcc):

uv sync --package serron --no-dev --group build --extra cu132
uv build --package serron --wheel --no-build-isolation

On a GPU-less machine, sync the CPU torch build instead, the extension then builds C++ only (no nvcc required):

uv sync --package serron --no-dev --group build --extra cpu
uv build --package serron --wheel --no-build-isolation

License

MIT

Copyright © 2026 Vedran Hrabar.

Download files

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

Source Distribution

serron-0.2.0.tar.gz (16.2 kB view details)

Uploaded Source

Built Distributions

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

serron-0.2.0-cp314-cp314-win_amd64.whl (706.2 kB view details)

Uploaded CPython 3.14Windows x86-64

serron-0.2.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (46.7 MB view details)

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

serron-0.2.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (44.4 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

serron-0.2.0-cp313-cp313-win_amd64.whl (714.6 kB view details)

Uploaded CPython 3.13Windows x86-64

serron-0.2.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (46.7 MB view details)

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

serron-0.2.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (44.4 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

serron-0.2.0-cp312-cp312-win_amd64.whl (714.6 kB view details)

Uploaded CPython 3.12Windows x86-64

serron-0.2.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (46.7 MB view details)

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

serron-0.2.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl (44.4 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.24+ ARM64manylinux: glibc 2.28+ ARM64

File details

Details for the file serron-0.2.0.tar.gz.

File metadata

  • Download URL: serron-0.2.0.tar.gz
  • Upload date:
  • Size: 16.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for serron-0.2.0.tar.gz
Algorithm Hash digest
SHA256 3036066581ce6fa30e949733147e9f7673b0e26b01c38cce362fedd9aef43e10
MD5 e389727fea9464da2a72399e06237611
BLAKE2b-256 09f665fafc3325cf7fe4f8e95ef0fe16b01c89d7d96e222753311f390ad35c52

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0.tar.gz:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp314-cp314-win_amd64.whl.

File metadata

  • Download URL: serron-0.2.0-cp314-cp314-win_amd64.whl
  • Upload date:
  • Size: 706.2 kB
  • Tags: CPython 3.14, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for serron-0.2.0-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 484ba2be119bd51564f6bc95db46d7b3456d50ec0ee97dd620ae35f6ad498624
MD5 99634c71fdbec040ec0a59c2aed1dd3c
BLAKE2b-256 7b0597408c704f5ecefc9f79e9a3843000c4eb03365888ccff10da0647452e29

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp314-cp314-win_amd64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for serron-0.2.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2dc44df34a89938e7bda3847460605591d136b3e4c64ddd7894c30ca4c1f7c6f
MD5 e57b7ad366e703537f1d8919b5e62d44
BLAKE2b-256 6833471bcb239b16be962a490d503994e38e08e8dd26f50b6a11b3e0f6de10b2

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for serron-0.2.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 76f12ddb5f38474d75bc57f1c495f74a2abdca605e27da071e9bd98080aa96a0
MD5 2fc2534ce165861517808a28e12fc412
BLAKE2b-256 e79f7f6b6b4ae30cde065dffd96ef46f1571eca3a3011291c2c6ba5c25c9b0be

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: serron-0.2.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 714.6 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for serron-0.2.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 4067d2c4329bfdc049845da5b81213bb324aa41e02402a5194b8132e7e6bff5d
MD5 9701b715ce7ab639b75f9b7f41057bcb
BLAKE2b-256 c10e22ec4396eec73c2d3068deb159a2b3270c124775422ac02a04b8ad887f68

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp313-cp313-win_amd64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for serron-0.2.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 079fb6c226b2673d07a646a87ccdd25f27fbc58204f1a0c0b8859cfb5118a3a4
MD5 55c78b648a6cdc2f0c1b99c600938d1d
BLAKE2b-256 2120109c1eb72b0c159d33263c693249fe142454d46272196f476fa566b11b16

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for serron-0.2.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 f2862fefb4b842d15c5cd11060b19ec1f9b57c835b54aaaea9684041a218ee86
MD5 6739cefeefd5103c715287bb290c2b84
BLAKE2b-256 ab0703fa5066a8ed10446e175801ef6119e18912c63b0e85bd85952b785bcf08

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp313-cp313-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: serron-0.2.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 714.6 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for serron-0.2.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 93bc0fb3c2ede809eae47568e4d6a104240bb274c783f29658d7b35de206bd5a
MD5 00ea143db4d927bd5f89396a982d18a1
BLAKE2b-256 7d3cab92e3813cd594427824fe7f39d80732595b6bdfbbdfffaf99f2db72c9da

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp312-cp312-win_amd64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for serron-0.2.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 54d9b308f32d7e73f51246ca0b923e5436f7a33ae3b751cd5757bbfebf4eb083
MD5 56fe27db33e2838993ff8a5d6eaadc66
BLAKE2b-256 f5ae146fd8ddccf0b29443723e8affbee6a33eb16a1d1bb19ac542f0df75118e

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file serron-0.2.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for serron-0.2.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 8e3443537b1e47d0b998e71d058b1448f42c8e0e07ba58cfbabe13b8d983ebd7
MD5 48e70087640a1f4deeb3923cd33a3b97
BLAKE2b-256 89fa12501945dea06d680b49c9202cfa883f1b9db4c2da3a904e5b4076eb1221

See more details on using hashes here.

Provenance

The following attestation bundles were made for serron-0.2.0-cp312-cp312-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl:

Publisher: publish-pypi.yml on vhrabar/serron

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.1

10 files

This release

0.2.0 This release

10 files

0.1.1

10 files

0.1.0

10 files

0.0.1

10 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