mergechannels 0.2.0__cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

mergechannels/__init__.py

@@ -0,0 +1,13 @@
+# Import Rust functions
+from .mergechannels import (  # type: ignore
+	dispatch_single_channel,
+	dispatch_multi_channel,
+)
+from ._internal import merge
+
+
+__all__ = [
+	'dispatch_single_channel',
+	'dispatch_multi_channel',
+	'merge',
+]

mergechannels/__init__.pyi

@@ -0,0 +1,30 @@
+
+from typing import Literal, Sequence
+import numpy as np
+
+from python.mergechannels._blending import BLENDING_OPTIONS
+from python.mergechannels._luts import COLORMAPS
+
+
+def merge(
+    arrs: np.ndarray | Sequence[np.ndarray],
+    colors: Sequence[COLORMAPS] = (),
+    blending: Literal[BLENDING_OPTIONS] = 'max',
+    saturation_limits: tuple[float, float] = (0.2, 99.8),
+) -> np.ndarray:
+    ...
+
+def dispatch_single_channel(
+    array_reference: np.ndarray,
+    cmap_name: str,
+    limits: tuple[float, float],
+) -> np.ndarray:
+    ...
+
+def dispatch_multi_channel(
+    array_references: Sequence[np.ndarray],
+    cmap_names: Sequence[str],
+    blending: Literal[BLENDING_OPTIONS],
+    limits: Sequence[tuple[float, float]],
+) -> np.ndarray:
+    ...

mergechannels/_blending.py

@@ -0,0 +1,3 @@
+from typing import Literal
+
+BLENDING_OPTIONS = Literal['max', 'sum', 'mean', 'min']

mergechannels/_internal.py

@@ -0,0 +1,65 @@
+from typing import Sequence
+
+import numpy as np
+
+from mergechannels import (
+	dispatch_single_channel,
+	dispatch_multi_channel,
+)
+from ._luts import COLORMAPS
+from ._blending import BLENDING_OPTIONS
+
+def merge(
+	arrs: Sequence[np.ndarray],
+	colors: Sequence[COLORMAPS],
+	blending: BLENDING_OPTIONS = 'max',
+    saturation_limits: tuple[float, float] = (0.011, 0.999),
+) -> np.ndarray:
+	'''
+	apply cmaps to arrays and blend the colors
+	'''
+	# region validation
+	n_arrs = len(arrs)
+	n_colors = len(colors)
+	if not n_arrs == n_colors and n_arrs > 0:
+		raise ValueError(
+			'Expected an equal number of arrays to colorize and colormap names to apply. '
+			f'Got {n_arrs} arrays and {n_colors} colors'
+		)
+	arr_shapes = [arr.shape for arr in arrs]
+	if not len(set(arr_shapes)) == 1:
+		raise ValueError(
+			f'Expected every array to have the same shape, got {arr_shapes}'
+		)
+	if len(arr_shapes[0]) not in (2, 3):
+		raise ValueError(
+			f'Expected every array to be 2D or 3D, got {arr_shapes[0]}'
+		)
+	arr_dtypes = [arr.dtype for arr in arrs]
+	if not len(set(arr_dtypes)) == 1:
+		raise ValueError(
+			f'Expected every array to have the same dtype, got {arr_dtypes}'
+		)
+	# endregion
+	if n_arrs == 1:
+		if arrs[0].dtype == 'uint8':
+			limits = (0, 255)
+		else:
+			low, high = np.percentile(arrs[0], np.array(saturation_limits) * 100)
+			limits = (low, high)
+		return dispatch_single_channel(
+			array_reference=arrs[0],
+			cmap_name=colors[0],
+			limits=limits,
+		)
+	else:
+		if all(arr.dtype == 'uint8' for arr in arrs):
+			limits = (0, 255)
+		else:
+			limits = tuple(np.percentile(arr, np.array(saturation_limits) * 100) for arr in arrs)
+		return dispatch_multi_channel(
+			array_references=arrs,
+			cmap_names=colors,
+			blending=blending,
+			limits=limits,  # type: ignore
+		)

mergechannels/_luts.py

@@ -0,0 +1,81 @@
+from typing import Literal
+
+COLORMAPS = Literal[
+	'Rainbow RGB',
+	'3color-RMB',
+	'Red Hot',
+	'Yellow',
+	'betterRed',
+	'blue_orange_icb',
+	'mpl-inferno',
+	'I Blue',
+	'BOP purple',
+	'betterOrange',
+	'Blue',
+	'6_shades',
+	'OIMB3',
+	'Red/Green',
+	'Turbo',
+	'mpl-viridis',
+	'smart',
+	'Thermal',
+	'OIMB2',
+	'glow',
+	'OPF orange',
+	'physics',
+	'OIMB1',
+	'betterCyan',
+	'mpl-magma',
+	'edges',
+	'OPF purple',
+	'I Yellow',
+	'16_colors',
+	'sepia',
+	'ICA2',
+	'I Forest',
+	'ICA3',
+	'BOP orange',
+	'I Red',
+	'3color-CGY',
+	'I Green',
+	'Fire',
+	'Magenta Hot',
+	'Orange Hot',
+	'unionjack',
+	'I Cyan',
+	'Cyan Hot',
+	'I Magenta',
+	'Grays',
+	'Cyan',
+	'phase',
+	'gem',
+	'OPF fresh',
+	'betterGreen',
+	'3color-BMR',
+	'betterBlue',
+	'Magenta',
+	'Red',
+	'I Bordeaux',
+	'glasbey',
+	'glasbey_on_dark',
+	'mpl-plasma',
+	'3color-YGC',
+	'Green',
+	'ICA',
+	'Yellow Hot',
+	'thallium',
+	'Spectrum',
+	'royal',
+	'glasbey_inverted',
+	'betterYellow',
+	'HiLo',
+	'cool',
+	'Green Fire Blue',
+	'BOP blue',
+	'thal',
+	'Ice',
+	'brgbcmyw',
+	'I Purple',
+	'3-3-2 RGB',
+	'5_ramps',
+]

mergechannels-0.2.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: mergechannels
+Version: 0.2.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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
+Requires-Dist: numpy>1.25.0
+Provides-Extra: nvim
+License-File: LICENSE
+Summary: Apply and merge colormaps
+Author-email: Zac Swider <zac.swider@gmail.com>
+License: MIT
+Requires-Python: >=3.9, <=3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+[![CI](https://github.com/zacswider/mergechannels/actions/workflows/CI.yml/badge.svg)](https://github.com/zacswider/mergechannels/actions/workflows/CI.yml)
+![PyPI - License](https://img.shields.io/pypi/l/mergechannels)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mergechannels)
+![PyPI](https://img.shields.io/pypi/v/mergechannels)
+
+# mergechannels
+
+This project was originally conceived because I often find myself wanting to apply and blend colormaps to images while working from Python, and for historical reasons many of my favorite colormaps are distributed as [FIJI](https://imagej.net/software/fiji/) lookup tables. I also care about things likes speed and memory usage (e.g., not casting large arrays to floating point dtypes, not creating multiple whole arrays just to add them together), so I was interested in seeing if I could at least match matplotlib's colormapping performance with my own hand-rolled colorizer in Rust.
+
+
+
+## Installation
+
+Install pre-compiled binaries from [PyPI](https://pypi.org/project/mergechannels/):
+```bash
+pip install mergechannels
+```
+
+Build from source on your own machine:
+```bash
+pip install git+https://github.com/zacswider/mergechannels.git
+```
+
+## Usage
+*NOTE*: scikit-image is not a dependency of this project, but is used in the examples below to fetch images.
+
+### colorize a single image
+
+```python
+from skimage import data
+import mergechannels as mc
+
+img = data.camera()
+colorized = mc.apply_color_map(img, 'Red/Green')
+fig, axes = plt.subplots(1, 2, figsize=(6, 3), dpi=150)
+for ax in axes: ax.axis('off')
+(a, b) = axes
+a.imshow(img, cmap='gray')
+b.imshow(colorized)
+plt.show()
+print(colorized.shape, colorized.dtype)
+>> (512, 512, 3) uint8
+```
+![colorize a single image](https://raw.githubusercontent.com/zacswider/README_Images/main/camera_red-green.png)
+
+
+### apply a different colormap to each channel
+```python
+from skimage import data
+import matplotlib.pyplot as plt
+import mergechannels as mc
+
+cells, nuclei = data.cells3d().max(axis=0)
+assert cells.dtype == 'uint16' and nuclei.dtype == 'uint16'
+fig, axes = plt.subplots(1, 2, figsize=(3, 6), dpi=300)
+for ax in axes.ravel(): ax.axis('off')
+(a, b) = axes.ravel()
+a.imshow(mc.merge([cells, nuclei],['Orange Hot', 'Cyan Hot']))
+b.imshow(mc.merge([cells, nuclei],['I Blue', 'I Forest'], blending='min'))
+fig.tight_layout()
+plt.show()
+```
+![max and min multicolor blending](https://raw.githubusercontent.com/zacswider/README_Images/main/overlay_normal_and_inverted.png)
+
+### apply a colormap to a whole stack
+```python
+from skimage import data
+from matplotlib import pyplot as plt
+import mergechannels as mc
+
+volume = data.cells3d()
+cells = volume[:, 0]
+nuclei = volume[:, 1]
+merged = mc.merge([cells, nuclei],['Orange Hot', 'Cyan Hot'])
+plt.imshow(merged[24]); plt.show()
+```
+![colorize a whole stack of images](https://raw.githubusercontent.com/zacswider/README_Images/main/merged_stacks.png)
+
+### adjust the saturation limits when applying colormaps
+``` python
+from skimage import data
+import matplotlib.pyplot as plt
+import mergechannels as mc
+
+cells, nuclei = data.cells3d().max(axis=0)
+channels = [cells, nuclei]
+colormaps = ['I Blue', 'I Forest']
+fig, axes = plt.subplots(1, 2, figsize=(3, 6), dpi=300)
+for ax in axes.ravel(): ax.axis('off')
+(a, b) = axes.ravel()
+a.imshow(mc.merge(channels, colormaps, blending='min'))
+b.imshow(
+    mc.merge(
+        channels,
+        colormaps,
+        blending='min',
+        saturation_limits=(
+            0.01,  # bottom 1% of pixels set to black point
+            0.97,  # top 3% of pixels set to white point
+        ),
+    ),
+)
+fig.tight_layout()
+plt.show()
+```
+![adjust saturation limits](https://raw.githubusercontent.com/zacswider/README_Images/main/adjust_sat_lims.png)
+
+
+## Roadmap
+mergechannels is currently incredibly simple. It can apply one or more colormaps to one or more 2D and 3D 8-bit or 16-bit images and that's it.
+- Add support for any numerical dtype
+- Add option to return any colormap as a matplotlib colormap
+- Add option to pass external colormaps to mergechannels
+- Add support for directly passing matplotlib colormaps instead of colormap names
+- Parallelize colormap application on large images (if it's helpful)
+- Add option to overlay binary or instance masks onto colorized images
+
+## Acknowledgements
+
+There are other great colormapping libraries available (e.g., [microfilm](https://github.com/guiwitz/microfilm), [cmap](https://github.com/pyapp-kit/cmap)) that are more feature-rich than this one, but which don't address my goals. My hope is that this project can fill an un-met niche and otherwise maintain full compatibility with these and similar libraries.
+
+This project incorporates a number of colormaps that were hand-crafted by Christophe Leterrier and were originally distributed here under the MIT license: https://github.com/cleterrier/ChrisLUTs
+

mergechannels-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mergechannels-0.2.0.dist-info/METADATA,sha256=t-okrnqyvIiZxuLqTlubmCkXCxKz9U43u7bhSIEiNBc,5725
+mergechannels-0.2.0.dist-info/WHEEL,sha256=uhW5MjwJWhgG7tRveeDv2-hvQtvaPxbnARBNpsAjvcw,131
+mergechannels-0.2.0.dist-info/licenses/LICENSE,sha256=csvD60rgtSorbYEM3f8867qNyPCzmIXyFNj8h01Bd6c,1071
+mergechannels/__init__.py,sha256=TTNiDGOOJ6_-yR-qvX_nXph646Sz6-MEORc8ItksCRE,232
+mergechannels/__init__.pyi,sha256=tiDx6v14J0cedFdk6fzVRRyA21b4Z8eB_rtSTUjI804,749
+mergechannels/_blending.py,sha256=mE5Cr9wvVJRcwfymg_UUZUjdIKx2mldfLU8QJT95bVM,84
+mergechannels/_internal.py,sha256=ZcdBUFEq8k2Ve_ASOZLTuPBaFEEPqadc9LqAGmBqOas,1773
+mergechannels/_luts.py,sha256=DxwCMBnAAJc1ZX-D4cq8HabW-sLuBQpUqOWMWXqt_84,1035
+mergechannels/mergechannels.cpython-313-aarch64-linux-gnu.so,sha256=PQSvshvIjLQX899INU6ZvIblMF5obgU8H7QiHEy61tg,901680
+mergechannels/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mergechannels-0.2.0.dist-info/RECORD,,

mergechannels-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.6)
+Root-Is-Purelib: false
+Tag: cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64

mergechannels-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Zachary Swider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.