cellects.image.filters
cellects.image.filters
2-D image filters with Numba-accelerated helper kernels.
This module provides 2-D grayscale image filtering functions for sharpening, smoothing, edge detection, median filtering, Hessian-based vesselness, and masked filtering. Public functions accept integer or floating-point images and return NumPy arrays.
The filters include classical linear filters, scale-space tubeness and vesselness filters, a frequency-domain Butterworth filter, and helper functions for masked Sato or Frangi filtering.
Functions:
| Name | Description |
|---|---|
sharpen_filter : Apply a 3x3 sharpen kernel. |
|
mexican_hat_filter : Apply a 5x5 Mexican-hat kernel. |
|
gaussian_filter : Apply Gaussian smoothing. |
|
butterworth_filter : Apply a Butterworth filter. |
|
farid_filter : Compute Farid edge magnitude. |
|
hessian_filter : Compute a Hessian vesselness response. |
|
laplace_filter : Apply Laplacian convolution. |
|
median_filter : Apply median filtering. |
|
meijering_filter : Compute a Meijering vesselness response. |
|
prewitt_filter : Compute Prewitt edge magnitude. |
|
roberts_filter : Compute Roberts edge magnitude. |
|
scharr_filter : Compute Scharr edge magnitude. |
|
sobel_filter : Compute Sobel edge magnitude. |
|
sato_filter : Apply the Sato tubeness filter. |
|
frangi_filter : Apply the Frangi vesselness filter. |
|
masked_vessel_filters : Apply Sato or Frangi inside a mask. |
|
Notes
Boundary handling is specific to each filter. Some functions use Numba-compiled loops for per-pixel Hessian and mask reflection work.
butterworth_filter(image, cutoff_frequency_ratio=0.005, high_pass=False, order=2.0, squared_butterworth=True, npad=0, preserve_range=False)
Summary
Apply a Butterworth low-pass or high-pass filter to a 2-D image.
Extended Description
The filter is applied in the frequency domain. Integer input is
converted to float64 without range scaling. preserve_range is
accepted for interface compatibility but does not affect this function.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
cutoff_frequency_ratio
|
float
|
Cutoff ratio relative to each image dimension. Must be greater than 0.0 and less than or equal to 0.5. |
0.005
|
high_pass
|
bool
|
If |
False
|
order
|
float
|
Butterworth filter order. |
2.0
|
squared_butterworth
|
bool
|
If |
True
|
npad
|
int
|
Number of edge pixels to pad before filtering and crop after filtering. |
0
|
preserve_range
|
bool
|
Accepted for compatibility; this function does not change behavior. |
False
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Filtered image with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
>>> result = butterworth_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 | |
farid_filter(image, mode='reflect', cval=0.0)
Summary
Compute Farid edge magnitude for a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
mode
|
str
|
Boundary mode used for convolution. |
'reflect'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Edge magnitude with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).
Examples:
>>> result = farid_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
frangi_filter(greyscale_image, sigmas)
Summary
Apply the 2-D Frangi vesselness filter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
greyscale_image
|
ndarray
|
2-D grayscale image. Integer and floating-point images are accepted. |
required |
sigmas
|
list[float]
|
Positive Gaussian scales in pixel units. |
required |
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Floating-point Frangi response in |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
The filter targets dark tubular structures and uses "reflect" image
boundary handling. It matches the scikit-image 0.26.0 2-D formulation
with black ridges. The structuredness parameter is chosen automatically
from the largest Hessian norm of the first scale.
Examples:
>>> image = [[0.0, 1.0, 1.0, 0.0]]
>>> sigmas = [1.0, 2.0]
>>> result = frangi_filter(image, sigmas)
>>> print(result.shape)
(1, 4)
Source code in src/cellects/image/filters.py
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 | |
gaussian_filter(image, sigma=1.0, preserve_range=False, mode='nearest', cval=0.0, truncate=4.0)
Summary
Apply Gaussian smoothing to a 2-D image.
Extended Description
When preserve_range is False, unsigned integer input is scaled to
[0.0, 1.0], signed integer input is scaled by the largest absolute
endpoint, and floating-point input is unchanged. When preserve_range
is True, integer input is converted to float64 without range
scaling.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
sigma
|
float
|
Gaussian standard deviation. |
1.0
|
preserve_range
|
bool
|
If |
False
|
mode
|
str
|
Boundary mode passed to the Gaussian filter. |
'nearest'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
truncate
|
float
|
Gaussian kernel truncation parameter. |
4.0
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Smoothed image with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
>>> result = gaussian_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8), 1.0)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
hessian_filter(image, sigmas=(1, 3, 5), alpha=0.5, beta=0.5, gamma=15.0, black_ridges=True)
Summary
Compute a Hessian-based vesselness response over multiple scales.
Extended Description
For black_ridges=``True``, dark linear structures produce positive
responses. Forblack_ridges=False, the input is negated before
filtering so that bright structures are detected. Responses are combined
by taking the maximum over sigmas. Locations with no positive response
are set to 1.0.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
sigmas
|
float or sequence[float]
|
Positive Gaussian scales. |
(1, 3, 5)
|
alpha
|
float
|
Accepted for compatibility; this parameter has no effect in this 2-D implementation. |
0.5
|
beta
|
float
|
Smoothing parameter for the ridge/blob ratio term. |
0.5
|
gamma
|
float
|
Structuredness threshold. |
15.0
|
black_ridges
|
bool
|
If |
True
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Vesselness-like response with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Uses a Numba-compiled helper for per-pixel eigenvalue computation.
Examples:
>>> result = hessian_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8), [1.0])
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 | |
laplace_filter(image, ksize=3)
Summary
Apply Laplacian convolution to a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
ksize
|
int
|
Odd convolution kernel size. |
3
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Laplacian response with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
ksize=3 uses the standard 3x3 Laplacian. Larger odd values use a
cross-shaped kernel. Unsigned integer input is scaled to [0.0, 1.0];
signed integer input is scaled by the largest absolute endpoint.
Examples:
>>> result = laplace_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
masked_vessel_filters(greyscale_image, filter_name, sigmas, mask_bool)
Summary
Apply a Sato or Frangi vesselness filter inside a 2-D mask.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
greyscale_image
|
ndarray
|
2-D grayscale image. Integer and floating-point images are accepted. |
required |
filter_name
|
str
|
Filter to apply. Must be |
required |
sigmas
|
list[float]
|
Positive Gaussian scales in pixel units. |
required |
mask_bool
|
ndarray of bool
|
2-D binary mask. |
required |
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Floating-point vesselness response with the same shape as
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Image borders use reflective boundary handling. The mask boundary is extended by reflection before computing the Gaussian Hessian. Repeated reflections are used for concave or thin mask regions. The reflection mapping uses Numba-compiled helpers for performance.
Examples:
>>> image = [[0.0, 1.0, 1.0, 0.0]]
>>> mask = [[False, True, True, False]]
>>> result = masked_vessel_filters(image, "Frangi", [1.0, 2.0], mask)
>>> print(result.shape)
(1, 4)
>>> print(result[0, 0])
0.0
Source code in src/cellects/image/filters.py
639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 | |
median_filter(image, footprint=None, mode='nearest', cval=0.0)
Summary
Apply median filtering to a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
footprint
|
ndarray of bool or None
|
Median filter footprint. If |
None
|
mode
|
str
|
Boundary mode passed to the median filter. |
'nearest'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Median-filtered image with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
>>> result = median_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8))
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
meijering_filter(image, sigmas=(1, 3, 5), alpha=None, black_ridges=True)
Summary
Compute a Meijering vesselness response over multiple scales.
Extended Description
For black_ridges=``True``, dark linear structures produce positive
responses. Forblack_ridges=False, the input is negated before
filtering so that bright structures are detected. Each scale response is
normalized by its maximum before combining scales by maximum.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
sigmas
|
float or sequence[float]
|
Positive Gaussian scales. |
(1, 3, 5)
|
alpha
|
float or None
|
Meijering weighting parameter. If |
None
|
black_ridges
|
bool
|
If |
True
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Vesselness response in [0.0, 1.0] with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Examples:
Source code in src/cellects/image/filters.py
1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 | |
prewitt_filter(image, mode='reflect', cval=0.0)
Summary
Compute Prewitt edge magnitude for a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
mode
|
str
|
Boundary mode used for convolution. |
'reflect'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Edge magnitude with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).
Examples:
>>> result = prewitt_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
roberts_filter(image, mode='reflect', cval=0.0)
Summary
Compute Roberts edge magnitude for a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
mode
|
str
|
Boundary mode used for convolution. |
'reflect'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Edge magnitude with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Uses two 2x2 diagonal difference kernels. Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).
Examples:
>>> result = roberts_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
sato_filter(greyscale_image, sigmas)
Summary
Apply the 2-D Sato tubeness filter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
greyscale_image
|
ndarray
|
2-D grayscale image. Integer and floating-point images are accepted. |
required |
sigmas
|
list[float]
|
Positive Gaussian scales in pixel units. |
required |
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Floating-point Sato response with the same shape as
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
The filter targets dark tubular structures and uses "reflect" image
boundary handling. It matches the scikit-image 0.26.0 2-D formulation
with black ridges. The per-pixel helper computations use Numba-compiled
functions for performance.
Examples:
>>> image = [[0.0, 1.0, 1.0, 0.0]]
>>> sigmas = [1.0, 2.0]
>>> result = sato_filter(image, sigmas)
>>> print(result.shape)
(1, 4)
Source code in src/cellects/image/filters.py
scharr_filter(image, mode='reflect', cval=0.0)
Summary
Compute Scharr edge magnitude for a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
mode
|
str
|
Boundary mode used for convolution. |
'reflect'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Edge magnitude with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).
Examples:
>>> result = scharr_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)
Source code in src/cellects/image/filters.py
sobel_filter(image, mode='reflect', cval=0.0)
Summary
Compute Sobel edge magnitude for a 2-D image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
image
|
array_like
|
2-D grayscale image. |
required |
mode
|
str
|
Boundary mode used for convolution. |
'reflect'
|
cval
|
float
|
Constant value used for boundary extension. |
0.0
|
Returns:
| Type | Description |
|---|---|
ndarray of float64
|
Edge magnitude with the same shape as |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Notes
Unsigned integer input is scaled to [0.0, 1.0]; signed integer input is scaled by the largest absolute endpoint. The two directional responses are combined and divided by sqrt(2).
Examples:
>>> result = sobel_filter(np.array([[0.0, 1.0], [1.0, 0.0]], dtype=np.uint8)
>>> print(result.shape)
# (2, 2)