normal-grain-merge 0.1.3__cp311-cp311-win_amd64.whl

normal_grain_merge/normal_grain_merge.pyi

@@ -0,0 +1,28 @@
+# ngm/normal_grain_merge.pyi
+from typing import Literal
+import numpy as np
+from .kernel_kind import KernelKind
+
+def normal_grain_merge(
+    base: np.ndarray,
+    texture: np.ndarray,
+    skin: np.ndarray,
+    im_alpha: np.ndarray,
+    kernel: Literal["auto", "scalar", "sse42", "avx2"] | KernelKind = "auto",
+) -> np.ndarray:
+    """
+    Performs a combined merge: grain merge of skin and texture,
+    then a normal merge of that result on base.
+    Channel ordering doesn't matter as long as it is consistent.
+    :param base: The base RGB image.
+    :param texture: The texture, either RGB or RGBA.
+    :param skin: The RGB skin cutout.
+    :param im_alpha: The alpha from the cutout.
+    :param kernel: Which kernel to use.
+    The `auto` kernel chooses between avx2 and sse4.2 when compiled with gcc and uses `scaler` on Windows.
+    The `scalar` kernel is a portable implementation that relies on the compiler for SIMD.
+    The `sse42` kernel uses SSE4.2 intrinsics.
+    The `avx2` kernel uses AVX2 intrinsics.
+    :return: RGB np.ndarray.
+    """
+    ...

normal_grain_merge-0.1.3.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: normal_grain_merge
+Version: 0.1.3
+Summary: Fused normal and grain merge C extension
+Author: Samuel Howard
+License: MIT
+Project-URL: Homepage, https://github.com/samhaswon/normal_grain_merge
+Project-URL: Bug Tracker, https://github.com/samhaswon/normal_grain_merge/issues
+Keywords: image,processing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: license-file
+
+# normal_grain_merge
+
+This implements a combined version of the blend modes normal and grain merge.
+Grain merge is performed on *s* and *t* with the result normal-merged with *b*.
+Subscripts indicate channels, with alpha (α) channels broadcast to three channels.
+
+$$
+(((\mathrm{t_{rgb}} + \mathrm{s_{rgb}} - 0.5) * \mathrm{t_\alpha} + \mathrm{t_{rgb}} * (1 - \mathrm{t_\alpha})) * (1 - 0.3) + \mathrm{s_{rgb}} * 0.3) * \mathrm{t_\alpha} + \mathrm{b_{rgb}} * (1 - \mathrm{t_\alpha})
+$$
+
+## Installation
+
+```shell
+pip install normal-grain-merge
+```
+
+## Usage
+```py
+import numpy as np
+from normal_grain_merge import normal_grain_merge, KernelKind
+
+
+# Example arrays
+base = np.zeros((100, 100, 3), dtype=np.uint8)
+texture = np.zeros((100, 100, 3), dtype=np.uint8)
+skin = np.zeros((100, 100, 4), dtype=np.uint8)
+im_alpha = np.zeros((100, 100), dtype=np.uint8)
+
+result_scalar = normal_grain_merge(base, texture, skin, im_alpha, KernelKind.KERNEL_SCALAR.value)
+print(result_scalar.shape, result_scalar.dtype)
+```
+
+There are three kernels implemented in this module as defined in `KernelKind`.
+
+- `KERNEL_AUTO`: Automatically chooses the kernel, preferring AVX2
+- `KERNEL_SCALAR`: Portable scalar implementation.
+- `KERNEL_SSE42`: SSE4.2 intrinsics kernel. Likely better on AMD CPUs.
+- `KERNEL_AVX2`: AVX2 intrinsics kernel. Likely better on Intel CPUs.
+
+### Parameters
+
+All input matrices should have the same height and width.
+
+#### `base`
+
+RGB or RGBA, dropping the alpha channel if it exists.
+The base image for application.
+
+#### `texture`
+
+RGB or RGBA, applying the alpha if it exists.
+This is the texture to be applied.
+
+#### `skin`
+
+RGBA, the segmented portion of base to texture.
+The "skin" of the object the texture is to be applied to.
+
+#### `im_alpha`
+
+The alpha of parameter `skin`. 
+This is mostly a holdover from the Python implementation to deal with NumPy.
+
+#### `kernel`
+
+One of `KernelKind`.
+
+## Performance
+
+The entire reason for me writing this was NumPy being slow when this operation is in the hot path.
+So, I decided to write a SIMD version that does the type casting outside NumPy with only the intermediate values being in FP32.
+
+How much of a speedup is this? All numbers are from a Ryzen 7 4800H running Ubuntu 24.04 and Python 3.12.3.
+
+| Method/Kernel     | Average Iteration Time (RGB) | Average Iteration Time (RGBA) |
+|-------------------|------------------------------|-------------------------------|
+| C scalar kernel   | 0.016109s                    | 0.016679s                     |
+| C SSE4.2 kernel   | 0.002446s                    | 0.002478s                     |
+| C AVX2 kernel     | 0.002336s                    | 0.002520s                     |
+| NumPy version     | 0.160623s                    | 0.258044s                     |
+| Old NumPy version | 0.248160s                    | 0.232046s                     |
+
+| Method Comparison  | Speedup (RGB) | Speedup (RGBA) |
+|--------------------|---------------|----------------|
+| NumPy -> scalar    | 89.9709%      | 93.5363%       |
+| NumPy -> SSE4.2    | 98.4769%      | 99.0397%       |
+| NumPy -> AVX2      | 98.5454%      | 99.0235%       |
+| Old np -> SSE4.2   | 99.0142%      | 98.9321%       |
+| Old np -> AVX2     | 99.0585%      | 98.9141%       |
+| C scalar -> SSE4.2 | 84.8135%      | 85.1437%       |
+| C scalar -> AVX2   | 85.4964%      | 84.8923%       |

normal_grain_merge-0.1.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+normal_grain_merge/__init__.py,sha256=Roc1wQ7_13LG_Z3Bd82zhk8wn7R1BrcO63fCdsvnnJU,89
+normal_grain_merge/kernel_kind.py,sha256=3cP4WRQSG9ZZeHsrXpXJ5Kcc8wABsmRSgex0rwRT8K4,162
+normal_grain_merge/normal_grain_merge.c,sha256=FtrCLe8ajPrd9mSFLloFwKaxfYgjTKKOo5nvSpu2lcQ,56968
+normal_grain_merge/normal_grain_merge.cp311-win_amd64.pyd,sha256=C3ko9jsBFj9DgW_Zm0HzrwKGBSv0lzPdSdtemFoV4c0,28672
+normal_grain_merge/normal_grain_merge.pyi,sha256=HXa55A0wdcmzPpJzi7qgJws5y2q_uGjdJZQXzTkw9vc,1089
+normal_grain_merge-0.1.3.dist-info/licenses/LICENSE,sha256=qbUDFP46iOpV1ouBhpqjX-kS_cCVMHgrLBNcdTlq7Qc,1089
+normal_grain_merge-0.1.3.dist-info/METADATA,sha256=Cml2gzBTWhL3Fua_ftXqdBFXPw76ej6Dwk3GXnnkmDU,4055
+normal_grain_merge-0.1.3.dist-info/WHEEL,sha256=bVDps4tOb0nHmbMU4uK7h9NZsZJmyTqcRbrvK3TZLY4,102
+normal_grain_merge-0.1.3.dist-info/top_level.txt,sha256=jfUAUKWrxBshHvZ0xTu3uF5VJsUpbWp5NkxUj8OXqu8,19
+normal_grain_merge-0.1.3.dist-info/RECORD,,

normal_grain_merge-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: false
+Tag: cp311-cp311-win_amd64
+

normal_grain_merge-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Samuel Howard
+
+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.

normal_grain_merge-0.1.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+normal_grain_merge