mergechannels 0.1.1__cp313-cp313t-musllinux_1_2_armv7l.whl

mergechannels/__init__.py

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

mergechannels/__init__.pyi

@@ -0,0 +1,27 @@
+from typing import Sequence, Literal
+
+import numpy as np
+
+from ._luts import COLORMAPS
+from ._blending import BLENDING_OPTIONS
+
+def merge(
+	arrs: Sequence[np.ndarray],
+	colors: Sequence[COLORMAPS] = (),
+	blending: Literal[BLENDING_OPTIONS] = 'max',
+    saturation_limits: tuple[float, float] = (0.2, 99.8),
+) -> np.ndarray:
+    ...
+
+def apply_color_map(
+    arr: np.ndarray,
+    cmap_name: COLORMAPS,
+    saturation_limits: tuple[float, float] = (0.2, 99.8),
+) -> np.ndarray: ...
+
+def apply_colors_and_merge_nc(
+    arrs: Sequence[np.ndarray],
+    colors: Sequence[COLORMAPS] = (),
+    blending: Literal[BLENDING_OPTIONS] = 'max',
+    saturation_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,47 @@
+from typing import Sequence
+
+import numpy as np
+
+from mergechannels import (
+	apply_color_map,
+	apply_colors_and_merge_nc,
+)
+from ._luts import COLORMAPS
+from ._blending import BLENDING_OPTIONS
+
+def merge(
+	arrs: Sequence[np.ndarray],
+	colors: Sequence[COLORMAPS],
+	blending: BLENDING_OPTIONS = 'max',
+) -> 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 not len(arr_shapes[0]) == 2:
+		raise ValueError(
+			f'Expected every array to be 2D, 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:
+		return apply_color_map(arr=arrs[0], cmap_name=colors[0])
+	else:
+		return apply_colors_and_merge_nc(arrs, colors, blending)

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.1.1.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: mergechannels
+Version: 0.1.1
+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
+License-File: LICENSE
+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)
+cells = to_uint8(cells)     # normalize your own arrays, mergechannels doesn't currently handle this
+nuclei = to_uint8(nuclei)   # normalize your own arrays, mergechannels doesn't currently handle this
+
+fig, axes = plt.subplots(2, 2, figsize=(6, 6), dpi=150)
+for ax in axes.ravel(): ax.axis('off')
+(a, b, c, d) = axes.ravel()
+a.imshow(cells, cmap='gray')
+b.imshow(nuclei, cmap='gray')
+c.imshow(
+    mc.merge(
+        [cells, nuclei],
+        ['Orange Hot', 'Cyan Hot'],  # maximum blending is the default
+    ),
+)
+d.imshow(
+    mc.merge(
+        [cells, nuclei],
+        ['I Blue', 'I Forest'],
+        blending='min',     # use minimum blending with inverted colormaps
+    ),
+)
+fig.tight_layout()
+plt.show()
+```
+![max and min multicolor blending](https://raw.githubusercontent.com/zacswider/README_Images/main/cells_multicolor.png)
+
+
+## Roadmap
+mergechannels is currently incredibly simple. It can apply one or more colormaps to one or more 2D 8-bit images and that's it.
+- Add support for any numerical dtype
+- Add support for 3D images
+- Add option to return any colormap as a matplotlib colormap
+- 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.1.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+mergechannels-0.1.1.dist-info/METADATA,sha256=KBR7A0EVV24esr7QQmnL-iFfqQGdjteFHX1z8Cj_6EU,4676
+mergechannels-0.1.1.dist-info/WHEEL,sha256=ZdoLgH9lcmexTAgYo3b2XEYu0Xl03VpVm_oICj2wvZ8,108
+mergechannels-0.1.1.dist-info/licenses/LICENSE,sha256=csvD60rgtSorbYEM3f8867qNyPCzmIXyFNj8h01Bd6c,1071
+mergechannels.libs/libgcc_s-5b5488a6.so.1,sha256=HGKUsVmTeNAxEdSy7Ua5Vh_I9FN3RCbPWzvZ7H_TrwE,2749061
+mergechannels/_luts.py,sha256=DxwCMBnAAJc1ZX-D4cq8HabW-sLuBQpUqOWMWXqt_84,1035
+mergechannels/_internal.py,sha256=Abzeacre5CQOcWn9WDIVuxFdEjTLIudEWQn8EsiH3oE,1243
+mergechannels/__init__.pyi,sha256=lSMX8eip_zkzoJPJKvxvAhOsewwagoAhS9H5gXJ2Da8,711
+mergechannels/__init__.py,sha256=jy8Qd3TOQ0mm-K64snjOqjdDQiSJ3gWjOjGZrliYy6k,222
+mergechannels/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mergechannels/_blending.py,sha256=mE5Cr9wvVJRcwfymg_UUZUjdIKx2mldfLU8QJT95bVM,84
+mergechannels/mergechannels.cpython-313t-arm-linux-musleabihf.so,sha256=bI3d2wKH9ENkNxlK0p2CpA5k8HeanRwIrN1KVsJEQ0k,875057
+mergechannels-0.1.1.dist-info/RECORD,,

mergechannels-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.8.3)
+Root-Is-Purelib: false
+Tag: cp313-cp313t-musllinux_1_2_armv7l

mergechannels-0.1.1.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.