fuzcolor 0.1.0__tar.gz

fuzcolor-0.1.0/LICENSE

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

fuzcolor-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: fuzcolor
+Version: 0.1.0
+Summary: Simple and easy to use Python library for fuzzy color models.
+Keywords: fuzzy,fuzzy-logic,color,color-naming,color-palette,hsi,colibri
+Author: coredegon
+Author-email: coredegon <valikalik15@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Dist: fuzlog==0.3.1
+Requires-Dist: matplotlib>=3.9
+Requires-Dist: numpy>=2.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/coredegon/fuzcolor
+Project-URL: Documentation, https://github.com/coredegon/fuzcolor/tree/main/docs
+Project-URL: Issues, https://github.com/coredegon/fuzcolor/issues
+Description-Content-Type: text/markdown
+
+# fuzcolor
+
+Simple and easy to use Python library for fuzzy color models: a pixel belongs
+to every named color to a degree. Built on
+[fuzlog](https://github.com/coredegon/fuzlog) and NumPy, typed, Python 3.12+.
+
+```sh
+pip install fuzcolor
+```
+
+```python
+import numpy as np
+import fuzcolor as fc
+from fuzcolor.models import COLIBRI
+
+image = np.array(
+    [[[200, 30, 30], [250, 220, 40]], [[30, 60, 200], [60, 60, 60]]], dtype=np.uint8
+)
+
+print(COLIBRI)  # Model('COLIBRI', HSI: 81 chromatic, 5 achromatic)
+print(COLIBRI.label([200, 30, 30]))  # red/high/dark
+print(COLIBRI.label(image).tolist())
+# [['red/high/dark', 'yellow/high/light'], ['blue/high/medium', 'dark gray']]
+
+weights = fc.palette(COLIBRI, image)  # the share of the image in each of 86 colors
+fc.pie(COLIBRI, weights)
+```
+
+![An image, the color of every pixel and the palette of the image](https://raw.githubusercontent.com/coredegon/fuzcolor/main/docs/img/palette.png)
+
+## Inside
+
+| | |
+|---|---|
+| **Models** | `Model` names colors as combinations of the terms of fuzlog variables |
+| **Spaces** | `Space` describes the channels of a color space; `HSI` comes with the library |
+| **Features** | `palette` describes an image, `tabulate` works a model out for every 8-bit color, `plot`, `swatches` and `pie` draw |
+| **`fuzcolor.models`** | the models that come with the library: `COLIBRI` |
+| **`fuzcolor.math`** | the color conversions as plain NumPy functions |
+
+## Documentation
+
+- [Guide](https://github.com/coredegon/fuzcolor/blob/main/docs/guide.md): how to use a model and how to build one
+- [COLIBRI](https://github.com/coredegon/fuzcolor/blob/main/docs/colibri.md): the model, its colors and its parameters
+- [Reference](https://github.com/coredegon/fuzcolor/blob/main/docs/reference.md): every public name on one page
+
+## Development
+
+```sh
+uv sync                 # environment with the dev tools
+uv run pytest           # tests, including every example in the documentation
+uv run ruff check       # lint; `uv run ruff format` formats
+uv run ty check         # types
+```
+
+MIT license.

fuzcolor-0.1.0/README.md

@@ -0,0 +1,56 @@
+# fuzcolor
+
+Simple and easy to use Python library for fuzzy color models: a pixel belongs
+to every named color to a degree. Built on
+[fuzlog](https://github.com/coredegon/fuzlog) and NumPy, typed, Python 3.12+.
+
+```sh
+pip install fuzcolor
+```
+
+```python
+import numpy as np
+import fuzcolor as fc
+from fuzcolor.models import COLIBRI
+
+image = np.array(
+    [[[200, 30, 30], [250, 220, 40]], [[30, 60, 200], [60, 60, 60]]], dtype=np.uint8
+)
+
+print(COLIBRI)  # Model('COLIBRI', HSI: 81 chromatic, 5 achromatic)
+print(COLIBRI.label([200, 30, 30]))  # red/high/dark
+print(COLIBRI.label(image).tolist())
+# [['red/high/dark', 'yellow/high/light'], ['blue/high/medium', 'dark gray']]
+
+weights = fc.palette(COLIBRI, image)  # the share of the image in each of 86 colors
+fc.pie(COLIBRI, weights)
+```
+
+![An image, the color of every pixel and the palette of the image](https://raw.githubusercontent.com/coredegon/fuzcolor/main/docs/img/palette.png)
+
+## Inside
+
+| | |
+|---|---|
+| **Models** | `Model` names colors as combinations of the terms of fuzlog variables |
+| **Spaces** | `Space` describes the channels of a color space; `HSI` comes with the library |
+| **Features** | `palette` describes an image, `tabulate` works a model out for every 8-bit color, `plot`, `swatches` and `pie` draw |
+| **`fuzcolor.models`** | the models that come with the library: `COLIBRI` |
+| **`fuzcolor.math`** | the color conversions as plain NumPy functions |
+
+## Documentation
+
+- [Guide](https://github.com/coredegon/fuzcolor/blob/main/docs/guide.md): how to use a model and how to build one
+- [COLIBRI](https://github.com/coredegon/fuzcolor/blob/main/docs/colibri.md): the model, its colors and its parameters
+- [Reference](https://github.com/coredegon/fuzcolor/blob/main/docs/reference.md): every public name on one page
+
+## Development
+
+```sh
+uv sync                 # environment with the dev tools
+uv run pytest           # tests, including every example in the documentation
+uv run ruff check       # lint; `uv run ruff format` formats
+uv run ty check         # types
+```
+
+MIT license.

fuzcolor-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "fuzcolor"
+version = "0.1.0"
+description = "Simple and easy to use Python library for fuzzy color models."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "fuzlog==0.3.1",
+    "matplotlib>=3.9",
+    "numpy>=2.0",
+]
+keywords = [
+    "fuzzy",
+    "fuzzy-logic",
+    "color",
+    "color-naming",
+    "color-palette",
+    "hsi",
+    "colibri",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "coredegon"
+email = "valikalik15@gmail.com"
+
+[project.urls]
+Repository = "https://github.com/coredegon/fuzcolor"
+Documentation = "https://github.com/coredegon/fuzcolor/tree/main/docs"
+Issues = "https://github.com/coredegon/fuzcolor/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "ruff>=0.17.5",
+    "ty>=0.0.104",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "N",
+    "D",
+    "UP",
+    "B",
+    "C4",
+    "SIM",
+    "PT",
+    "NPY",
+    "PERF",
+    "RUF",
+]
+ignore = [
+    "D105",
+    "D107",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+"docs/*" = ["D"]
+
+[tool.pytest]
+minversion = "9.0"
+strict = true
+testpaths = ["tests"]
+filterwarnings = ["error::RuntimeWarning"]

fuzcolor-0.1.0/pyproject.toml.orig

@@ -0,0 +1,92 @@
+[project]
+name = "fuzcolor"
+version = "0.1.0"
+description = "Simple and easy to use Python library for fuzzy color models."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "coredegon", email = "valikalik15@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fuzlog==0.3.1",  # its interface is not stable yet
+    "matplotlib>=3.9",
+    "numpy>=2.0",
+]
+keywords = [
+    "fuzzy",
+    "fuzzy-logic",
+    "color",
+    "color-naming",
+    "color-palette",
+    "hsi",
+    "colibri",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/coredegon/fuzcolor"
+Documentation = "https://github.com/coredegon/fuzcolor/tree/main/docs"
+Issues = "https://github.com/coredegon/fuzcolor/issues"
+
+[build-system]
+requires = ["uv_build>=0.13.7,<0.14.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.2.0",
+    "ruff>=0.17.5",
+    "ty>=0.0.104",
+]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",  # pycodestyle
+    "F",       # pyflakes
+    "I",       # import order
+    "N",       # naming
+    "D",       # docstrings
+    "UP",      # modern syntax
+    "B",       # likely bugs
+    "C4",      # comprehensions
+    "SIM",     # simplifications
+    "PT",      # pytest style
+    "NPY",     # numpy
+    "PERF",    # performance
+    "RUF",     # ruff's own
+]
+ignore = [
+    "D105",  # operators are documented by their class
+    "D107",  # and so is __init__
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+"docs/*" = ["D"]
+
+# ty needs no table: it checks against the oldest Python in `requires-python`
+# and fails on warnings by default.
+
+[tool.pytest]
+minversion = "9.0"
+strict = true
+testpaths = ["tests"]
+filterwarnings = ["error::RuntimeWarning"]  # a leaked overflow or 0/0 is a bug

fuzcolor-0.1.0/src/fuzcolor/__init__.py

@@ -0,0 +1,40 @@
+"""Fuzzy color models: the colors people name, as fuzzy sets.
+
+```python
+import fuzcolor as fc
+from fuzcolor.models import COLIBRI
+
+COLIBRI.label([200, 30, 30])            # "red/high/dark"
+weights = fc.palette(COLIBRI, image)    # the share of the image in every color
+fc.pie(COLIBRI, weights)
+```
+
+- models: `Model`, built from the variables of fuzlog;
+- spaces: `Space` and `HSI`;
+- features: `palette`, `tabulate` and `Table`, the plots `plot`, `swatches`, `pie`;
+- `fuzcolor.models`: the models that come with the library;
+- `fuzcolor.math`: the color conversions as plain NumPy functions.
+"""
+
+from fuzcolor import features, math, models
+from fuzcolor.features.palettes import palette
+from fuzcolor.features.plots import pie, plot, swatches
+from fuzcolor.features.tables import Table, tabulate
+from fuzcolor.model import Model, only
+from fuzcolor.spaces import HSI, Space
+
+__all__ = [
+    "HSI",
+    "Model",
+    "Space",
+    "Table",
+    "features",
+    "math",
+    "models",
+    "only",
+    "palette",
+    "pie",
+    "plot",
+    "swatches",
+    "tabulate",
+]

fuzcolor-0.1.0/src/fuzcolor/features/__init__.py

@@ -0,0 +1,6 @@
+"""What is built on top of a model: each feature stands on its own.
+
+- `palettes`: how much of an image belongs to each color;
+- `tables`: a model worked out for every 8-bit color;
+- `plots`: matplotlib views of models and palettes.
+"""

fuzcolor-0.1.0/src/fuzcolor/features/palettes.py

@@ -0,0 +1,41 @@
+"""Palettes: how much of an image belongs to each color of a model."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from fuzcolor.math import Array
+from fuzcolor.model import Model
+
+_BLOCK = 1 << 15  # pixels described at once: bounds the pixels x colors degrees
+
+
+def palette(model: Model, image: ArrayLike, *, crisp: bool = False) -> Array:
+    """Return the share of an image that belongs to each color of a model.
+
+    ```python
+    weights = fc.palette(model, image)       # weights[i] is of model.colors[i]
+    dict(zip(model.colors, weights))
+    ```
+
+    The image has shape `(..., 3)`: 8-bit integers or floats in [0, 1]. Every
+    pixel adds its degrees, so a weight is the mean degree of the pixels in
+    that color. With `crisp` a pixel counts for its strongest color only, and
+    the weights are fractions of the pixels.
+    """
+    pixels = np.asarray(image)
+    if pixels.ndim == 0 or pixels.shape[-1] != 3:
+        raise ValueError(f"RGB needs a last axis of 3 components, got {pixels.shape}")
+    pixels = pixels.reshape(-1, 3)
+    if not len(pixels):
+        raise ValueError("an image without pixels has no palette")
+    totals = np.zeros(len(model.colors))
+    for start in range(0, len(pixels), _BLOCK):
+        block = pixels[start : start + _BLOCK]
+        if crisp:
+            best = model.classify(block)
+            totals += np.bincount(best[best >= 0], minlength=len(totals))
+        else:
+            totals += model(block).sum(axis=1)
+    return totals / len(pixels)

fuzcolor-0.1.0/src/fuzcolor/features/plots.py

@@ -0,0 +1,153 @@
+"""Plots: matplotlib views of models and palettes.
+
+Fonts, sizes and the colour of text follow matplotlib's configuration; what is
+painted are the colors of the model themselves. Matplotlib is imported by the
+first plot.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+from typing import TYPE_CHECKING
+
+import fuzlog as fz
+import numpy as np
+from numpy.typing import ArrayLike
+
+from fuzcolor.model import Model
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+_OTHER = (0.76, 0.76, 0.72)  # the slice of the colors too small to show
+_EDGE = "#898781"
+
+
+def plot(model: Model) -> Figure:
+    """Draw the terms of a model: a row per family, a column per channel.
+
+    ```python
+    fc.plot(COLIBRI)
+    ```
+    """
+    import matplotlib.pyplot as plt
+
+    channels = list(model.space.channels)
+    figure, axes = plt.subplots(
+        len(model.families),
+        len(channels),
+        squeeze=False,
+        figsize=(4.2 * len(channels), 2.6 * len(model.families)),
+        layout="constrained",
+    )
+    for row, family in zip(axes, model.families, strict=True):
+        described = {variable.name: variable for variable in family.variables}
+        for ax, channel in zip(row, channels, strict=True):
+            if channel in described:
+                fz.plot(described[channel], ax)
+            else:
+                ax.set_axis_off()
+        shown = next(ax for ax in row if ax.axison)
+        shown.set_ylabel(f"{family.name}\nmembership")
+    figure.suptitle(f"{model.name}: {len(model.colors)} colors")
+    return figure
+
+
+def swatches(model: Model) -> Figure:
+    """Draw the typical color of every color of a model, a panel per family.
+
+    ```python
+    fc.swatches(COLIBRI)
+    ```
+
+    The terms of a family's first variable run across, the combinations of the
+    terms of its other variables run down.
+    """
+    import matplotlib.pyplot as plt
+
+    across = [len(family.variables[0].terms) for family in model.families]
+    down = [
+        len(family.colors) // n
+        for family, n in zip(model.families, across, strict=True)
+    ]
+    figure, axes = plt.subplots(
+        len(model.families),
+        1,
+        squeeze=False,
+        figsize=(1.1 * max(across) + 2.0, 0.45 * sum(down) + 0.9 * len(down)),
+        height_ratios=down,
+        layout="constrained",
+    )
+    blocks = np.split(model.prototypes(), np.cumsum(np.multiply(across, down))[:-1])
+    for ax, family, block, columns in zip(
+        axes[:, 0], model.families, blocks, across, strict=True
+    ):
+        first, *rest = family.variables
+        names = itertools.product(*(variable.terms for variable in rest))
+        grid = block.reshape(columns, -1, 3).swapaxes(0, 1)
+        ax.imshow(grid, aspect="auto")
+        ax.set_xticks(range(columns), labels=list(first.terms))
+        ax.set_yticks(range(len(grid)), labels=[", ".join(name) for name in names])
+        ax.xaxis.tick_top()
+        ax.set_xticks(np.arange(0.5, columns - 1), minor=True)
+        ax.set_yticks(np.arange(0.5, len(grid) - 1), minor=True)
+        ax.grid(which="minor", color=ax.get_facecolor(), linewidth=2)
+        ax.tick_params(which="both", length=0)
+        ax.set_title(family.name, loc="left")
+        ax.spines[:].set(color=_EDGE, linewidth=0.5)
+    figure.suptitle(f"{model.name}: {len(model.colors)} colors")
+    return figure
+
+
+def pie(
+    model: Model, weights: ArrayLike, ax: Axes | None = None, *, least: float = 0.02
+) -> Axes:
+    """Draw a palette as a pie whose slices wear the colors they stand for.
+
+    ```python
+    fc.pie(COLIBRI, fc.palette(COLIBRI, image))
+    ```
+
+    Colors with a share below `least` are summed into one gray slice.
+    """
+    import matplotlib.pyplot as plt
+
+    shares = np.asarray(weights, dtype=np.float64)
+    if shares.shape != (len(model.colors),):
+        raise ValueError(
+            f"a palette of {model.name} has {len(model.colors)} weights, "
+            f"got the shape {shares.shape}"
+        )
+    ranked = np.argsort(-shares, kind="stable")
+    shown = [int(i) for i in ranked if shares[i] > 0.0 and shares[i] >= least]
+    sizes = shares[shown].tolist()
+    names = [model.colors[i] for i in shown]
+    fills = [tuple(rgb) for rgb in model.prototypes()[shown].tolist()]
+    rest = float(shares.sum()) - sum(sizes)
+    if rest > 1e-9:
+        sizes.append(rest)
+        names.append("other")
+        fills.append(_OTHER)
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 6), layout="constrained")
+    _, _, percents = ax.pie(
+        sizes,
+        labels=names,
+        colors=fills,
+        autopct="%.0f%%",
+        pctdistance=0.8,
+        startangle=90,
+        counterclock=False,
+        wedgeprops={"edgecolor": _EDGE, "linewidth": 0.5},
+    )
+    for percent, fill in zip(percents, fills, strict=True):
+        dark = (
+            math.fsum(
+                w * c for w, c in zip((0.2126, 0.7152, 0.0722), fill, strict=True)
+            )
+            < 0.5
+        )
+        percent.set_color("white" if dark else "black")
+    return ax

fuzcolor-0.1.0/src/fuzcolor/features/tables.py

@@ -0,0 +1,64 @@
+"""Tables: a model worked out once for every 8-bit color."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import fuzlog as fz
+import numpy as np
+from numpy.typing import ArrayLike
+
+from fuzcolor.math import Array
+from fuzcolor.model import Model
+
+NONE = 255  # what a table holds for a pixel that belongs to no color
+
+
+class Table(fz.Table):
+    """The strongest color of every 8-bit pixel, looked up; `tabulate` makes one.
+
+    ```python
+    table = fc.tabulate(model)
+    table(image)                  # as model.classify(image), for 8-bit pixels
+    table.save("colibri.npz")
+    table = fc.Table.load("colibri.npz")
+    ```
+
+    It is a fuzlog table over `red`, `green` and `blue` that also takes pixels
+    of shape `(..., 3)`. It answers with `uint8` positions in `model.colors`,
+    and with `NONE`, 255, for a pixel that belongs to no color.
+    """
+
+    __slots__ = ()
+
+    def __call__(self, rgb: ArrayLike | None = None, /, **inputs: ArrayLike) -> Any:
+        """Look up the strongest color of 8-bit pixels."""
+        if rgb is None:
+            return super().__call__(**inputs)
+        pixels = np.asarray(rgb)
+        if pixels.dtype != np.uint8 or pixels.ndim == 0 or pixels.shape[-1] != 3:
+            raise TypeError(
+                f"a table takes 8-bit pixels of shape (..., 3), "
+                f"got {pixels.dtype} of shape {pixels.shape}"
+            )
+        return self.values[pixels[..., 0], pixels[..., 1], pixels[..., 2]]
+
+
+def tabulate(model: Model) -> Table:
+    """Classify every 8-bit color with a model and keep the answers in a `Table`.
+
+    ```python
+    table = fc.tabulate(model)    # 256 x 256 x 256 of uint8: 16 MB, in seconds
+    ```
+    """
+    if len(model.colors) > NONE:
+        raise ValueError(f"a table counts up to {NONE} colors, got {len(model.colors)}")
+
+    def strongest(red: Array, green: Array, blue: Array) -> Array:
+        best = model.classify(np.stack([red, green, blue], axis=-1) / 255.0)
+        return np.where(best < 0, NONE, best)
+
+    levels = (0, 255, 256)
+    axes = {"red": levels, "green": levels, "blue": levels}
+    made = fz.tabulate(strongest, axes, method="nearest", dtype=np.uint8)
+    return Table(made.axes, made.values, made.method, model.name)

fuzcolor-0.1.0/src/fuzcolor/math.py

@@ -0,0 +1,67 @@
+"""Color conversions as plain NumPy functions.
+
+Colors are arrays whose last axis holds the components. RGB with components in
+[0, 1] is the exchange format: every other space converts from and to it.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+type Array = NDArray[np.float64]
+
+_SQRT_3 = math.sqrt(3.0)
+
+
+def as_rgb(colors: ArrayLike) -> Array:
+    """Return colors as float RGB in [0, 1]: whole numbers are 8-bit levels."""
+    given = np.asarray(colors)
+    if given.ndim == 0 or given.shape[-1] != 3:
+        raise ValueError(f"RGB needs a last axis of 3 components, got {given.shape}")
+    if np.issubdtype(given.dtype, np.integer):
+        return given / 255.0
+    return given.astype(np.float64, copy=False)
+
+
+def rgb_to_hsi(rgb: Array) -> Array:
+    """Convert RGB in [0, 1] to hue in [0, 360), saturation and intensity in [0, 1].
+
+    Hue is the angle of the color around the gray axis, 0 for red. Grays get
+    hue 0 and black gets saturation 0.
+    """
+    red, green, blue = rgb[..., 0], rgb[..., 1], rgb[..., 2]
+    intensity = (red + green + blue) / 3.0
+    weakest = np.minimum(np.minimum(red, green), blue)
+    gray = np.divide(
+        weakest, intensity, out=np.ones_like(intensity), where=intensity > 0
+    )
+    saturation = np.clip(1.0 - gray, 0.0, 1.0)
+    angle = np.arctan2(_SQRT_3 * (green - blue), 2.0 * red - green - blue)
+    hue = np.mod(np.degrees(angle), 360.0)
+    hue = np.where(hue < 360.0, hue, 0.0)  # mod rounds tiny negative angles up to 360
+    return np.stack([hue, saturation, intensity], axis=-1)
+
+
+def hsi_to_rgb(hsi: Array) -> Array:
+    """Convert hue in degrees, saturation and intensity in [0, 1] to RGB.
+
+    Not every combination is a color: a light one cannot be saturated. Such
+    combinations give components above 1.
+    """
+    hue, saturation, intensity = hsi[..., 0], hsi[..., 1], hsi[..., 2]
+    # Each third of the hue circle has its own weakest primary: blue, red, green.
+    third = np.floor_divide(hue, 120.0) % 3
+    angle = np.radians(hue - 120.0 * third)
+    weakest = intensity * (1.0 - saturation)
+    leading = intensity * (
+        1.0 + saturation * np.cos(angle) / np.cos(math.pi / 3 - angle)
+    )
+    remaining = 3.0 * intensity - (weakest + leading)
+    first, second = third == 0, third == 1
+    red = np.select([first, second], [leading, weakest], remaining)
+    green = np.select([first, second], [remaining, leading], weakest)
+    blue = np.select([first, second], [weakest, remaining], leading)
+    return np.stack([red, green, blue], axis=-1)

fuzcolor-0.1.0/src/fuzcolor/model.py

@@ -0,0 +1,229 @@
+"""Fuzzy color models: colors as combinations of the terms of fuzlog variables."""
+
+from __future__ import annotations
+
+import itertools
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import fuzlog as fz
+import numpy as np
+from fuzlog.types import Norm
+from numpy.typing import ArrayLike, NDArray
+
+from fuzcolor.math import Array, as_rgb
+from fuzcolor.spaces import Space
+
+
+def only(variable: fz.Variable, *terms: str) -> fz.Variable:
+    """Return a variable with just the named terms of another, in that order.
+
+    ```python
+    only(saturation, "low", "medium", "high")
+    ```
+    """
+    unknown = [term for term in terms if term not in variable.terms]
+    if unknown or not terms:
+        raise ValueError(
+            f"{variable.name!r} has no terms {unknown}, only {list(variable.terms)}"
+        )
+    kept = {term: variable.terms[term] for term in terms}
+    return fz.Variable(
+        variable.name, variable.universe, kept, periodic=variable.periodic
+    )
+
+
+class Family:
+    """The colors made of one term from each variable; a `Model` makes its own.
+
+    A color is named after the terms that tell it apart from the others: a
+    variable with one term stays out of the name, and a family of one color
+    takes the name of the family.
+    """
+
+    __slots__ = ("colors", "name", "variables")
+
+    def __init__(self, name: str, *variables: fz.Variable) -> None:
+        channels = [variable.name for variable in variables]
+        if not variables or len(set(channels)) < len(channels):
+            raise ValueError(
+                f"the family {name!r} needs variables of different channels, "
+                f"got {channels}"
+            )
+        self.name = name
+        self.variables = variables
+        telling = [len(variable.terms) > 1 for variable in variables]
+        self.colors = tuple(
+            "/".join(itertools.compress(terms, telling)) or name
+            for terms in itertools.product(*(variable.terms for variable in variables))
+        )
+
+    def degrees(
+        self, channels: Mapping[str, Array], tnorm: Norm = np.multiply
+    ) -> Array:
+        """Return the degree of every color: shape `(len(colors), *shape)`.
+
+        `channels` holds the values of every channel by name; the degrees of
+        the terms of a color are joined by `tnorm`.
+        """
+        terms = [variable(channels[variable.name]) for variable in self.variables]
+        out = terms[0]
+        for more in terms[1:]:  # every color so far with every term of the next
+            out = tnorm(out[:, None], more[None]).reshape(-1, *more.shape[1:])
+        return out
+
+    def strongest(
+        self, channels: Mapping[str, Array], tnorm: Norm = np.multiply
+    ) -> tuple[NDArray[np.intp], Array]:
+        """Return the position of the strongest color and its degree.
+
+        A t-norm never decreases, so the strongest color is made of the
+        strongest term of every variable: no other color has to be worked out.
+        """
+        terms = [variable(channels[variable.name]) for variable in self.variables]
+        position, degree = terms[0].argmax(axis=0), terms[0].max(axis=0)
+        for more in terms[1:]:
+            position = position * len(more) + more.argmax(axis=0)
+            degree = tnorm(degree, more.max(axis=0))
+        return position, degree
+
+    def __repr__(self) -> str:
+        return f"Family({self.name!r}: {' x '.join(v.name for v in self.variables)})"
+
+
+class Model:
+    """A fuzzy color model: families of colors named in a color space.
+
+    ```python
+    model = fc.Model(
+        "toy",
+        fc.HSI,
+        tint=[hue, fc.only(saturation, "pale", "vivid")],
+        gray=[intensity, fc.only(saturation, "gray")],
+    )
+    model.colors                 # ("red/pale", "red/vivid", ..., "dark", "light")
+    model([200, 30, 30])         # the degree of the pixel in every color
+    model.label([200, 30, 30])   # "red/vivid": its strongest color
+    ```
+
+    A family is a list of fuzlog variables, each named after the channel of the
+    space that it describes; its colors take one term from each variable.
+    Pixels have shape `(..., 3)`: 8-bit integers or floats in [0, 1].
+
+    Args:
+        name: What the model is called.
+        space: The color space whose channels the variables describe.
+        tnorm: How the degrees of the terms of a color are joined. With the
+            product, families of partitions give degrees that sum to 1.
+        **families: The variables of every family, by the name of the family.
+    """
+
+    __slots__ = ("_names", "colors", "families", "name", "space", "tnorm")
+
+    def __init__(
+        self,
+        name: str,
+        space: Space,
+        /,
+        *,
+        tnorm: Norm = np.multiply,
+        **families: Sequence[fz.Variable],
+    ) -> None:
+        made = tuple(Family(key, *variables) for key, variables in families.items())
+        for family in made:
+            for variable in family.variables:
+                if space.channels.get(variable.name) != variable.universe:
+                    raise ValueError(
+                        f"{family.name!r}: {variable.name!r} on {variable.universe} "
+                        f"is not a channel of {space.name}: {space.channels}"
+                    )
+        colors = tuple(color for family in made for color in family.colors)
+        if not colors or len(set(colors)) < len(colors):
+            raise ValueError(f"{name!r} needs colors that differ, got {colors}")
+        self.name = name
+        self.space = space
+        self.families = made
+        self.tnorm = tnorm
+        self.colors = colors
+        self._names = np.array([*colors, ""])  # the last is what -1 counts to
+
+    def __call__(self, rgb: ArrayLike) -> Array:
+        """Return the degree of the pixels in every color.
+
+        The shape is `(len(colors), *rgb.shape[:-1])`, so the result unpacks
+        into one array per color.
+        """
+        channels = self._channels(rgb)
+        blocks = [family.degrees(channels, self.tnorm) for family in self.families]
+        return np.concatenate(blocks)
+
+    def classify(self, rgb: ArrayLike) -> NDArray[np.intp]:
+        """Return the position in `colors` of the strongest color of every pixel.
+
+        A pixel that belongs to no color gets -1.
+        """
+        channels = self._channels(rgb)
+        first = 0
+        best: NDArray[np.intp] = np.intp(-1)  # ty: ignore[invalid-assignment]
+        degree: Array = np.float64(0.0)  # ty: ignore[invalid-assignment]
+        for family in self.families:
+            position, strength = family.strongest(channels, self.tnorm)
+            best = np.where(strength > degree, first + position, best)
+            degree = np.maximum(degree, strength)
+            first += len(family.colors)
+        return best
+
+    def label(self, rgb: ArrayLike) -> Any:
+        """Return the name of the strongest color of every pixel.
+
+        One pixel gives a string, more give an array of strings; a pixel that
+        belongs to no color gets an empty name.
+        """
+        names = self._names[self.classify(rgb)]
+        return names if names.ndim else str(names)
+
+    def _channels(self, rgb: ArrayLike) -> dict[str, Array]:
+        """The values of every channel of the space, by name."""
+        values = self.space.from_rgb(as_rgb(rgb))
+        return {name: values[..., i] for i, name in enumerate(self.space.channels)}
+
+    def prototypes(self) -> Array:
+        """Return a typical RGB color for every color: shape `(len(colors), 3)`.
+
+        A channel takes the middle of the core of the color's term, or the
+        middle of its range if the family does not describe it. What is too
+        bright to be a color is darkened until it fits into RGB.
+        """
+        middle = [(low + high) / 2 for low, high in self.space.channels.values()]
+        places = {channel: i for i, channel in enumerate(self.space.channels)}
+        rows = []
+        for family in self.families:
+            centers = [_centers(variable).tolist() for variable in family.variables]
+            for values in itertools.product(*centers):
+                row = list(middle)
+                for variable, value in zip(family.variables, values, strict=True):
+                    row[places[variable.name]] = value
+                rows.append(row)
+        rgb = self.space.to_rgb(np.array(rows))
+        return np.clip(rgb / np.maximum(rgb.max(axis=-1, keepdims=True), 1.0), 0.0, 1.0)
+
+    def __repr__(self) -> str:
+        families = ", ".join(f"{len(f.colors)} {f.name}" for f in self.families)
+        return f"Model({self.name!r}, {self.space.name}: {families})"
+
+
+def _centers(variable: fz.Variable) -> Array:
+    """The most typical value of every term: the middle of where it is highest.
+
+    On a periodic universe the middle is found going around the circle.
+    """
+    x = variable.grid(4001)
+    degrees = variable(x)
+    core = (degrees >= degrees.max(axis=1, keepdims=True) - 1e-9).astype(np.float64)
+    if not variable.periodic:
+        return (core @ x) / core.sum(axis=1)
+    low, high = variable.universe
+    angle = (x - low) * (math.tau / (high - low))
+    middle = np.arctan2(core @ np.sin(angle), core @ np.cos(angle)) % math.tau
+    return low + middle * ((high - low) / math.tau)

fuzcolor-0.1.0/src/fuzcolor/models/__init__.py

@@ -0,0 +1,5 @@
+"""The models that come with the library, one module each."""
+
+from fuzcolor.models.colibri import COLIBRI
+
+__all__ = ["COLIBRI"]

fuzcolor-0.1.0/src/fuzcolor/models/colibri.py

@@ -0,0 +1,69 @@
+"""COLIBRI: the color categories of people, on the HSI space.
+
+P. Shamoi et al., "COLIBRI Fuzzy Model: Color Linguistic-Based Representation
+and Interpretation", IEEE Access 13, 2025 (arXiv:2507.11488). The partitions
+of hue, saturation and intensity come from a large survey of how people name
+colors.
+
+A color of very low saturation is achromatic and named after its intensity
+alone: black, dark gray, gray, light gray or white. Every other color is
+chromatic and named after its hue, its saturation and a coarser intensity,
+which gives 9 x 3 x 3 + 5 = 86 colors.
+"""
+
+import fuzlog as fz
+
+from fuzcolor.model import Model, only
+from fuzcolor.spaces import HSI
+
+HUE = fz.partition(
+    "hue",
+    (0, 360),
+    {
+        "red": (350, 5),
+        "orange": (20, 35),
+        "yellow": 45,
+        "green": (65, 130),
+        "cyan": 175,
+        "light blue": 190,
+        "blue": (215, 240),
+        "violet": (270, 280),
+        "magenta": (320, 330),
+    },
+    periodic=True,
+)
+
+SATURATION = fz.partition(
+    "saturation",
+    (0, 1),
+    {"very low": 0, "low": 0.15, "medium": (0.375, 0.45), "high": (0.725, 1)},
+)
+
+INTENSITY = fz.partition(
+    "intensity",
+    (0, 1),
+    {
+        "black": (0, 30 / 255),
+        "dark gray": 75 / 255,
+        "gray": (110 / 255, 115 / 255),
+        "light gray": (190 / 255, 215 / 255),
+        "white": 1,
+    },
+)
+
+# Black with dark gray, gray, light gray with white: neighbours of a partition
+# add up to a term whose core runs from the first core to the last.
+SHADE = fz.partition(
+    "intensity",
+    (0, 1),
+    dark=(0, 75 / 255),
+    medium=(110 / 255, 115 / 255),
+    light=(190 / 255, 1),
+)
+
+COLIBRI = Model(
+    "COLIBRI",
+    HSI,
+    chromatic=[HUE, only(SATURATION, "low", "medium", "high"), SHADE],
+    achromatic=[INTENSITY, only(SATURATION, "very low")],
+)

fuzcolor-0.1.0/src/fuzcolor/spaces.py

@@ -0,0 +1,39 @@
+"""Color spaces: named channels and the way from and to RGB."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import NamedTuple
+
+from fuzcolor.math import Array, hsi_to_rgb, rgb_to_hsi
+
+
+class Space(NamedTuple):
+    """A coordinate system for colors.
+
+    ```python
+    HSI = Space(
+        "HSI",
+        {"hue": (0, 360), "saturation": (0, 1), "intensity": (0, 1)},
+        rgb_to_hsi,
+        hsi_to_rgb,
+    )
+    ```
+
+    `channels` gives every coordinate its range, in the order of the last axis
+    that `from_rgb` returns and `to_rgb` takes. Both work on float arrays of
+    shape `(..., 3)`, with RGB in [0, 1].
+    """
+
+    name: str
+    channels: dict[str, tuple[float, float]]
+    from_rgb: Callable[[Array], Array]
+    to_rgb: Callable[[Array], Array]
+
+
+HSI = Space(
+    "HSI",
+    {"hue": (0.0, 360.0), "saturation": (0.0, 1.0), "intensity": (0.0, 1.0)},
+    rgb_to_hsi,
+    hsi_to_rgb,
+)