lutopia 0.2.0__tar.gz

lutopia-0.2.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.3
+Name: lutopia
+Version: 0.2.0
+Summary: Tool-agnostic LUT and colormap management for Python
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# lutopia
+
+**Tool-agnostic LUT and colormap management for Python.**
+
+Lutopia treats every palette — smooth gradient or legacy 256-step table — as a single unified continuous function. One API, zero fragmentation across visualization ecosystems.
+
+```python
+import lutopia as lt
+
+# Matplotlib
+from matplotlib.colors import ListedColormap
+cmap = ListedColormap(lt.viridis.plt)
+
+# Seaborn
+sns.heatmap(data, cmap=lt.viridis.sns)
+
+# Plotly
+fig.update_traces(colorscale=lt.viridis.plotly)
+```
+
+---
+
+## Features
+
+- **297 palettes out of the box** — matplotlib's full catalog + the entire colorcet scientific collection
+- **Unified engine** — smooth gradients and legacy step-function LUTs share one interface
+- **Zero visualization dependencies** — runtime package requires only `numpy` and `scipy`
+- **Native consumer outputs** — `.plt`, `.mpl`, `.sns`, `.plotly` return exactly what each library expects, no adapters needed
+- **Interactive palette picker** — `uvx lutopia` opens a live GUI browser with one-click code generation
+- **`src` layout, `uv_build` backend** — modern packaging, ships a clean wheel
+
+---
+
+## Installation
+
+```bash
+pip install lutopia
+# or
+uv add lutopia
+```
+
+---
+
+## Quick Start
+
+```python
+import lutopia as lt
+
+# List all available palettes
+print(dir(lt))  # ['accent', 'afmhot', 'autumn', ..., 'viridis', ...]
+
+# Sample raw float values (N × 3 array, values in [0, 1])
+arr = lt.viridis.sample(256)   # numpy array, shape (256, 3)
+
+# Get hex strings
+hexes = lt.plasma.to_hex_list(64)  # ['#0d0887', '#2d0594', ...]
+```
+
+---
+
+## Consumer Properties
+
+Every palette exposes three ready-to-use consumer properties. No third-party imports are required by the library itself.
+
+### Matplotlib
+
+```python
+from matplotlib.colors import ListedColormap
+import matplotlib.pyplot as plt
+import lutopia as lt
+
+cmap = ListedColormap(lt.inferno.plt)
+plt.imshow(data, cmap=cmap)
+plt.colorbar()
+```
+
+`.plt` / `.mpl` / `.matplotlib` all return the same `(256, 3)` float64 NumPy array that `ListedColormap` and `LinearSegmentedColormap` accept directly.
+
+### Seaborn
+
+```python
+import seaborn as sns
+import lutopia as lt
+
+sns.heatmap(data, cmap=lt.magma.sns)
+```
+
+`.sns` / `.seaborn` return a list of 256 hex strings, which Seaborn accepts for both `palette=` and `cmap=` arguments.
+
+### Plotly
+
+```python
+import plotly.graph_objects as go
+import lutopia as lt
+
+fig = go.Figure(go.Heatmap(z=data, colorscale=lt.turbo.plotly))
+```
+
+`.plotly` returns a native Plotly colorscale — a list of `[fraction, "#rrggbb"]` pairs spanning `[0.0, 1.0]`.
+
+---
+
+## Palette Browser
+
+The interactive palette picker is available as an ephemeral tool — no install needed:
+
+```bash
+uvx lutopia
+# or, if already installed:
+lutopia
+```
+
+A tkinter window opens showing all 297 palettes as color swatches. Click any palette to open a code snippet dialog:
+
+- Choose your target ecosystem (Matplotlib, Seaborn, Plotly, or Raw Hex)
+- Copy the generated snippet directly to your clipboard
+
+---
+
+## Available Palettes
+
+Lutopia ships with palettes sourced from:
+
+| Source | Count | Examples |
+|--------|-------|---------|
+| **Matplotlib** | ~90 | `viridis`, `plasma`, `inferno`, `magma`, `cividis`, `jet`, `hot`, `coolwarm`, `spectral`, `tab10` |
+| **Colorcet** | ~200 | `fire`, `rainbow4`, `bmy`, `bgyw`, `isolum`, `gouldian`, `kbc`, `dimgray` |
+
+All palettes are available immediately after install — no scraping, no network calls.
+
+---
+
+## How It Works
+
+All palettes are stored as compact JSON anchor files in `lutopia/palettes/`. A continuous `UnifiedPalette` engine evaluates them on demand:
+
+- **Linear interpolation** for smooth gradient maps (e.g. viridis, plasma)
+- **Nearest-neighbor / step** for discrete legacy tables (e.g. ImageJ `.lut` files)
+
+```json
+{
+  "name": "viridis",
+  "interpolation": "linear",
+  "anchors": [
+    [0.0,   [68, 1, 84]],
+    [0.5,   [33, 145, 140]],
+    [1.0,   [253, 231, 37]]
+  ]
+}
+```
+
+Palettes are loaded lazily on first access and cached for the lifetime of the interpreter session.
+
+---
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/bryanbarcelona/lutopia.git
+cd lutopia
+uv sync
+```
+
+### Tooling
+
+```bash
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run ty check src/lutopia  # type check
+uv run pytest                # tests
+```
+
+### Adding Palettes
+
+**From matplotlib / colorcet:**
+
+```bash
+uv run python scripts/scrape_ecosystems.py
+```
+
+Reads upstream colormap libraries, reduces continuous maps to sparse anchor points (max error < 1/255), and writes JSON assets to `src/lutopia/palettes/`. Run with `--overwrite` to force regeneration.
+
+**From a binary ImageJ / Fiji `.lut` file:**
+
+```bash
+uv run python scripts/parse_legacy_lut.py path/to/fire.lut [name]
+```
+
+Parses the standard 768-byte RGB block and writes a step-interpolation JSON asset.
+
+After adding palettes, commit the new JSON files and they will be included in the next release.
+
+### Releasing
+
+Releases are fully automated via CI. Every merge to `main` triggers:
+
+1. Commitizen bumps the version and generates a changelog entry
+2. `uv build` produces the wheel and sdist
+3. `uv publish` pushes to PyPI via trusted publishing (OIDC, no API keys)
+4. A GitHub Release is created and tagged
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+cz commit
+```
+
+---
+
+## License
+
+MIT

lutopia-0.2.0/README.md

@@ -0,0 +1,214 @@
+# lutopia
+
+**Tool-agnostic LUT and colormap management for Python.**
+
+Lutopia treats every palette — smooth gradient or legacy 256-step table — as a single unified continuous function. One API, zero fragmentation across visualization ecosystems.
+
+```python
+import lutopia as lt
+
+# Matplotlib
+from matplotlib.colors import ListedColormap
+cmap = ListedColormap(lt.viridis.plt)
+
+# Seaborn
+sns.heatmap(data, cmap=lt.viridis.sns)
+
+# Plotly
+fig.update_traces(colorscale=lt.viridis.plotly)
+```
+
+---
+
+## Features
+
+- **297 palettes out of the box** — matplotlib's full catalog + the entire colorcet scientific collection
+- **Unified engine** — smooth gradients and legacy step-function LUTs share one interface
+- **Zero visualization dependencies** — runtime package requires only `numpy` and `scipy`
+- **Native consumer outputs** — `.plt`, `.mpl`, `.sns`, `.plotly` return exactly what each library expects, no adapters needed
+- **Interactive palette picker** — `uvx lutopia` opens a live GUI browser with one-click code generation
+- **`src` layout, `uv_build` backend** — modern packaging, ships a clean wheel
+
+---
+
+## Installation
+
+```bash
+pip install lutopia
+# or
+uv add lutopia
+```
+
+---
+
+## Quick Start
+
+```python
+import lutopia as lt
+
+# List all available palettes
+print(dir(lt))  # ['accent', 'afmhot', 'autumn', ..., 'viridis', ...]
+
+# Sample raw float values (N × 3 array, values in [0, 1])
+arr = lt.viridis.sample(256)   # numpy array, shape (256, 3)
+
+# Get hex strings
+hexes = lt.plasma.to_hex_list(64)  # ['#0d0887', '#2d0594', ...]
+```
+
+---
+
+## Consumer Properties
+
+Every palette exposes three ready-to-use consumer properties. No third-party imports are required by the library itself.
+
+### Matplotlib
+
+```python
+from matplotlib.colors import ListedColormap
+import matplotlib.pyplot as plt
+import lutopia as lt
+
+cmap = ListedColormap(lt.inferno.plt)
+plt.imshow(data, cmap=cmap)
+plt.colorbar()
+```
+
+`.plt` / `.mpl` / `.matplotlib` all return the same `(256, 3)` float64 NumPy array that `ListedColormap` and `LinearSegmentedColormap` accept directly.
+
+### Seaborn
+
+```python
+import seaborn as sns
+import lutopia as lt
+
+sns.heatmap(data, cmap=lt.magma.sns)
+```
+
+`.sns` / `.seaborn` return a list of 256 hex strings, which Seaborn accepts for both `palette=` and `cmap=` arguments.
+
+### Plotly
+
+```python
+import plotly.graph_objects as go
+import lutopia as lt
+
+fig = go.Figure(go.Heatmap(z=data, colorscale=lt.turbo.plotly))
+```
+
+`.plotly` returns a native Plotly colorscale — a list of `[fraction, "#rrggbb"]` pairs spanning `[0.0, 1.0]`.
+
+---
+
+## Palette Browser
+
+The interactive palette picker is available as an ephemeral tool — no install needed:
+
+```bash
+uvx lutopia
+# or, if already installed:
+lutopia
+```
+
+A tkinter window opens showing all 297 palettes as color swatches. Click any palette to open a code snippet dialog:
+
+- Choose your target ecosystem (Matplotlib, Seaborn, Plotly, or Raw Hex)
+- Copy the generated snippet directly to your clipboard
+
+---
+
+## Available Palettes
+
+Lutopia ships with palettes sourced from:
+
+| Source | Count | Examples |
+|--------|-------|---------|
+| **Matplotlib** | ~90 | `viridis`, `plasma`, `inferno`, `magma`, `cividis`, `jet`, `hot`, `coolwarm`, `spectral`, `tab10` |
+| **Colorcet** | ~200 | `fire`, `rainbow4`, `bmy`, `bgyw`, `isolum`, `gouldian`, `kbc`, `dimgray` |
+
+All palettes are available immediately after install — no scraping, no network calls.
+
+---
+
+## How It Works
+
+All palettes are stored as compact JSON anchor files in `lutopia/palettes/`. A continuous `UnifiedPalette` engine evaluates them on demand:
+
+- **Linear interpolation** for smooth gradient maps (e.g. viridis, plasma)
+- **Nearest-neighbor / step** for discrete legacy tables (e.g. ImageJ `.lut` files)
+
+```json
+{
+  "name": "viridis",
+  "interpolation": "linear",
+  "anchors": [
+    [0.0,   [68, 1, 84]],
+    [0.5,   [33, 145, 140]],
+    [1.0,   [253, 231, 37]]
+  ]
+}
+```
+
+Palettes are loaded lazily on first access and cached for the lifetime of the interpreter session.
+
+---
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/bryanbarcelona/lutopia.git
+cd lutopia
+uv sync
+```
+
+### Tooling
+
+```bash
+uv run ruff check .          # lint
+uv run ruff format .         # format
+uv run ty check src/lutopia  # type check
+uv run pytest                # tests
+```
+
+### Adding Palettes
+
+**From matplotlib / colorcet:**
+
+```bash
+uv run python scripts/scrape_ecosystems.py
+```
+
+Reads upstream colormap libraries, reduces continuous maps to sparse anchor points (max error < 1/255), and writes JSON assets to `src/lutopia/palettes/`. Run with `--overwrite` to force regeneration.
+
+**From a binary ImageJ / Fiji `.lut` file:**
+
+```bash
+uv run python scripts/parse_legacy_lut.py path/to/fire.lut [name]
+```
+
+Parses the standard 768-byte RGB block and writes a step-interpolation JSON asset.
+
+After adding palettes, commit the new JSON files and they will be included in the next release.
+
+### Releasing
+
+Releases are fully automated via CI. Every merge to `main` triggers:
+
+1. Commitizen bumps the version and generates a changelog entry
+2. `uv build` produces the wheel and sdist
+3. `uv publish` pushes to PyPI via trusted publishing (OIDC, no API keys)
+4. A GitHub Release is created and tagged
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+cz commit
+```
+
+---
+
+## License
+
+MIT

lutopia-0.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "lutopia"
+version = "0.2.0"
+description = "Tool-agnostic LUT and colormap management for Python"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+]
+
+[project.scripts]
+lutopia = "lutopia.viewer:main"
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "matplotlib>=3.7",
+    "seaborn>=0.12",
+    "colorcet>=3.0",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "commitizen>=3.0",
+    "ruff>=0.4",
+    "ty>=0.0.0a1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["N"]
+"scripts/*" = ["N"]
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version_provider = "pep621"
+tag_format = "v$version"
+update_changelog_on_bump = true
+
+[tool.ty.environment]
+python-version = "3.12"

lutopia-0.2.0/src/lutopia/__init__.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lutopia.core import UnifiedPalette
+
+_PALETTES_DIR = Path(__file__).parent / "palettes"
+_cache: dict[str, UnifiedPalette] = {}
+_names: list[str] | None = None
+
+
+def _palette_names() -> list[str]:
+    global _names
+    if _names is None:
+        _names = sorted(p.stem for p in _PALETTES_DIR.glob("*.json"))
+    return _names
+
+
+def __getattr__(name: str) -> UnifiedPalette:
+    if name.startswith("_"):
+        raise AttributeError(name)
+    names = _palette_names()
+    if name not in names:
+        available = ", ".join(names[:8]) + ("..." if len(names) > 8 else "")
+        raise AttributeError(f"lutopia has no palette {name!r}. Available: {available}")
+    if name not in _cache:
+        from lutopia.core import UnifiedPalette
+
+        raw = (_PALETTES_DIR / f"{name}.json").read_bytes()
+        _cache[name] = UnifiedPalette(json.loads(raw))
+    return _cache[name]
+
+
+def __dir__() -> list[str]:
+    return _palette_names()
+
+
+__all__ = _palette_names()

lutopia-0.2.0/src/lutopia/core.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from scipy.interpolate import interp1d
+
+
+class UnifiedPalette:
+    def __init__(self, json_data: dict[str, Any]) -> None:
+        self.name: str = json_data["name"]
+        self.mode: str = json_data["interpolation"]  # "linear" or "step"
+
+        anchors: list[list] = json_data["anchors"]
+        self.domain: np.ndarray = np.array([a[0] for a in anchors], dtype=float)
+        self.colors: np.ndarray = np.array([a[1] for a in anchors], dtype=float) / 255.0
+
+        kind = "linear" if self.mode == "linear" else "nearest"
+        self._evaluator: interp1d = interp1d(
+            self.domain,
+            self.colors,
+            axis=0,
+            kind=kind,
+            bounds_error=False,
+            fill_value=(self.colors[0], self.colors[-1]),
+        )
+
+    def sample(self, steps: int = 256) -> np.ndarray:
+        """Evaluate the continuous function at N evenly distributed steps."""
+        target_domain = np.linspace(self.domain[0], self.domain[-1], steps)
+        return np.clip(self._evaluator(target_domain), 0.0, 1.0)
+
+    def to_hex_list(self, steps: int = 256) -> list[str]:
+        """Return hex color strings for N samples."""
+        rgb = np.round(self.sample(steps) * 255).astype(np.uint8)
+        return [f"#{r:02x}{g:02x}{b:02x}" for r, g, b in rgb]
+
+    # --- NATIVE CONSUMER SHAPING PROPERTIES (no third-party imports) ---
+
+    @property
+    def matplotlib(self) -> np.ndarray:
+        """Normalized (256, 3) float array for ListedColormap."""
+        return self.sample(256)
+
+    @property
+    def plt(self) -> np.ndarray:
+        return self.matplotlib
+
+    @property
+    def mpl(self) -> np.ndarray:
+        return self.matplotlib
+
+    @property
+    def seaborn(self) -> list[str]:
+        """List of 256 hex strings for Seaborn palette/cmap signatures."""
+        return self.to_hex_list(256)
+
+    @property
+    def sns(self) -> list[str]:
+        return self.seaborn
+
+    @property
+    def plotly(self) -> list[list]:
+        """Plotly colorscale: [[fraction, hex], ...] over 256 steps."""
+        hex_list = self.to_hex_list(256)
+        n = len(hex_list)
+        return [[i / (n - 1), hex_list[i]] for i in range(n)]

lutopia-0.2.0/src/lutopia/palettes/accent.json

@@ -0,0 +1,70 @@
+{
+  "name": "accent",
+  "interpolation": "step",
+  "anchors": [
+    [
+      0,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      1,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      2,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      3,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      4,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      5,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      6,
+      [
+        127,
+        201,
+        127
+      ]
+    ],
+    [
+      7,
+      [
+        127,
+        201,
+        127
+      ]
+    ]
+  ]
+}

lutopia-0.2.0/src/lutopia/palettes/afmhot.json

@@ -0,0 +1,46 @@
+{
+  "name": "afmhot",
+  "interpolation": "linear",
+  "anchors": [
+    [
+      0.0,
+      [
+        0,
+        0,
+        0
+      ]
+    ],
+    [
+      0.25098,
+      [
+        128,
+        0,
+        0
+      ]
+    ],
+    [
+      0.498039,
+      [
+        254,
+        126,
+        0
+      ]
+    ],
+    [
+      0.74902,
+      [
+        255,
+        254,
+        127
+      ]
+    ],
+    [
+      1.0,
+      [
+        255,
+        255,
+        255
+      ]
+    ]
+  ]
+}