porypal-fe8 0.1.1__tar.gz

porypal_fe8-0.1.1/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 laqieer
+
+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.
+
+
+--------------------------------------------------------------------------------
+Acknowledgements
+
+porypal-fe8 is an independent, clean-room reimplementation inspired by the
+reusable palette core of Loxed's Porypal (https://github.com/Loxed/porypal):
+the idea of k-means colour quantization in a perceptual colour space and the
+JASC ".pal" round-trip. Porypal is licensed under the GPL-3.0, which is
+incompatible with this MIT distribution, so no Porypal source code was copied;
+only the high-level approach was reused. Credit and thanks to Loxed.

porypal_fe8-0.1.1/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: porypal-fe8
+Version: 0.1.1
+Summary: FE8 palette tool: PNG -> 16-colour JASC .pal extraction & apply (fireemblem8u; inspired by Loxed's Porypal)
+Author: laqieer
+License: MIT License
+        
+        Copyright (c) 2026 laqieer
+        
+        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.
+        
+        
+        --------------------------------------------------------------------------------
+        Acknowledgements
+        
+        porypal-fe8 is an independent, clean-room reimplementation inspired by the
+        reusable palette core of Loxed's Porypal (https://github.com/Loxed/porypal):
+        the idea of k-means colour quantization in a perceptual colour space and the
+        JASC ".pal" round-trip. Porypal is licensed under the GPL-3.0, which is
+        incompatible with this MIT distribution, so no Porypal source code was copied;
+        only the high-level approach was reused. Credit and thanks to Loxed.
+        
+Project-URL: Homepage, https://github.com/laqieer/porypal-fe8
+Keywords: gba,fireemblem,palette,jasc,decomp,fe8
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=9.0
+Requires-Dist: numpy>=1.21
+Dynamic: license-file
+
+# porypal-fe8
+
+A small, FE8-oriented palette CLI for the
+[`fireemblem8u`](https://github.com/FireEmblemUniverse/fireemblem8u) decomp
+graphics pipeline. It does two things:
+
+- **`extract`** — quantize a PNG down to **≤16 colours** and write a GBA-style
+  **JASC `.pal`** palette.
+- **`apply`** — remap every pixel of a PNG to its nearest colour in a given
+  `.pal` and save an **indexed PNG**, ready for `gbagfx`.
+
+It is a focused, clean reimplementation of the *reusable core* of
+[Loxed's Porypal](https://github.com/Loxed/porypal) — k-means colour
+quantization in a perceptual colour space (Oklab) plus JASC `.pal` I/O — with
+all the Pokémon-specific and UI parts dropped. See
+[Credits & license](#credits--license).
+
+## Why this exists (honest note)
+
+For day-to-day FE8 graphics work you usually **do not need this tool**:
+
+- [**Usenti**](https://www.coranac.com/projects/usenti/) handles palette
+  editing, reduction, and indexed-PNG export interactively.
+- The decomp's own **`gbagfx`** already converts between `.png`, `.pal`,
+  `.gbapal`, and `.4bpp`.
+
+`porypal-fe8` is for **batch / automated quantization** — e.g. scripting the
+reduction of many full-colour PNGs to 16-colour palettes in a build or asset
+pipeline, where a headless CLI is more convenient than a GUI.
+
+## Install
+
+Requires Python 3.9+.
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+# optional: install the `porypal-fe8` console command
+pip install .
+```
+
+Without installing, you can run the module directly:
+
+```sh
+python3 palette_tool.py extract IN.png -o OUT.pal
+```
+
+## Install / Releases
+
+Once published to PyPI:
+
+```sh
+pip install porypal-fe8
+```
+
+Each `v*` tag also produces a **GitHub Release** with the built wheel and sdist
+attached (under [Releases](https://github.com/laqieer/porypal-fe8/releases)),
+so you can `pip install` a downloaded artifact even without PyPI.
+
+> **Note:** PyPI publishing uses [OIDC trusted
+> publishing](https://docs.pypi.org/trusted-publishers/) (no API token). It
+> requires a **trusted publisher** to be configured on PyPI for project
+> `porypal-fe8`, owner `laqieer`, workflow `release.yml`, environment `pypi`.
+> The GitHub Release job is independent and succeeds even before that is set up.
+
+## Usage
+
+### Extract a palette
+
+```sh
+porypal-fe8 extract IN.png -o OUT.pal [-n 16]
+```
+
+Quantizes `IN.png` to at most `-n` colours (default 16, the GBA 4bpp limit) and
+writes a JASC `.pal`:
+
+```
+JASC-PAL
+0100
+16
+115 131 164
+255 255 255
+...
+```
+
+### Apply a palette
+
+```sh
+porypal-fe8 apply IN.png PALETTE.pal -o OUT.png
+```
+
+Remaps every pixel of `IN.png` to the nearest colour in `PALETTE.pal` (nearest
+in Oklab) and saves an indexed (`P`-mode) PNG whose colours are exactly the
+palette.
+
+## How it fits the FE8 pipeline
+
+The decomp stores graphics as PNGs and JASC `.pal` palettes, and its Makefile
+drives `gbagfx` to turn those into the GBA's native formats:
+
+```
+            porypal-fe8 extract              gbagfx (pal2gbapal)
+   IN.png ───────────────────────▶  OUT.pal ───────────────────▶  .gbapal   (32 bytes for 16 colours)
+
+            porypal-fe8 apply                gbagfx (png2gbagfx)
+   IN.png ───────────────────────▶  OUT.png ───────────────────▶  .4bpp
+   (+ .pal)                         (indexed)
+```
+
+Relevant Makefile rules in the decomp:
+
+```make
+%.gbapal: %.pal ; $(PAL2GBAPAL) $< $@
+%.gbapal: %.png ; $(GBAGFX) $< $@
+```
+
+A 16-colour JASC `.pal` converts to exactly **32 bytes** of `.gbapal`
+(16 colours × 2 bytes, the GBA's 15-bit BGR555 format). Palettes are written
+with **CRLF** line endings to match the decomp's `.pal` files — `gbagfx`
+rejects LF-only palettes. See the
+[`fireemblem8u`](https://github.com/FireEmblemUniverse/fireemblem8u) repo and
+[`gbagfx`](https://github.com/pret/pokeemerald/tree/master/tools/gbagfx) for the
+full graphics flow.
+
+## How it works
+
+- **Quantization** clusters the image's pixels with **k-means++** in **Oklab**,
+  a perceptually uniform colour space, so the chosen colours match how the eye
+  groups them. Each cluster centre is then snapped to the nearest *actual*
+  colour in the source image, so every palette entry really occurs in the PNG.
+  If the image already has ≤ N colours, they are kept verbatim.
+- **Apply** assigns each pixel to the nearest palette colour, again measured in
+  Oklab.
+
+## Credits & license
+
+The colour-quantization approach and JASC `.pal` round-trip are **inspired by**
+[Loxed's Porypal](https://github.com/Loxed/porypal). Porypal is licensed under
+the **GPL-3.0**, which is incompatible with this project's MIT license, so
+**no Porypal source code was copied** — this is an independent reimplementation
+of the high-level idea only. Credit and thanks to Loxed.
+
+porypal-fe8 itself is released under the [MIT License](LICENSE).

porypal_fe8-0.1.1/README.md

@@ -0,0 +1,143 @@
+# porypal-fe8
+
+A small, FE8-oriented palette CLI for the
+[`fireemblem8u`](https://github.com/FireEmblemUniverse/fireemblem8u) decomp
+graphics pipeline. It does two things:
+
+- **`extract`** — quantize a PNG down to **≤16 colours** and write a GBA-style
+  **JASC `.pal`** palette.
+- **`apply`** — remap every pixel of a PNG to its nearest colour in a given
+  `.pal` and save an **indexed PNG**, ready for `gbagfx`.
+
+It is a focused, clean reimplementation of the *reusable core* of
+[Loxed's Porypal](https://github.com/Loxed/porypal) — k-means colour
+quantization in a perceptual colour space (Oklab) plus JASC `.pal` I/O — with
+all the Pokémon-specific and UI parts dropped. See
+[Credits & license](#credits--license).
+
+## Why this exists (honest note)
+
+For day-to-day FE8 graphics work you usually **do not need this tool**:
+
+- [**Usenti**](https://www.coranac.com/projects/usenti/) handles palette
+  editing, reduction, and indexed-PNG export interactively.
+- The decomp's own **`gbagfx`** already converts between `.png`, `.pal`,
+  `.gbapal`, and `.4bpp`.
+
+`porypal-fe8` is for **batch / automated quantization** — e.g. scripting the
+reduction of many full-colour PNGs to 16-colour palettes in a build or asset
+pipeline, where a headless CLI is more convenient than a GUI.
+
+## Install
+
+Requires Python 3.9+.
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+# optional: install the `porypal-fe8` console command
+pip install .
+```
+
+Without installing, you can run the module directly:
+
+```sh
+python3 palette_tool.py extract IN.png -o OUT.pal
+```
+
+## Install / Releases
+
+Once published to PyPI:
+
+```sh
+pip install porypal-fe8
+```
+
+Each `v*` tag also produces a **GitHub Release** with the built wheel and sdist
+attached (under [Releases](https://github.com/laqieer/porypal-fe8/releases)),
+so you can `pip install` a downloaded artifact even without PyPI.
+
+> **Note:** PyPI publishing uses [OIDC trusted
+> publishing](https://docs.pypi.org/trusted-publishers/) (no API token). It
+> requires a **trusted publisher** to be configured on PyPI for project
+> `porypal-fe8`, owner `laqieer`, workflow `release.yml`, environment `pypi`.
+> The GitHub Release job is independent and succeeds even before that is set up.
+
+## Usage
+
+### Extract a palette
+
+```sh
+porypal-fe8 extract IN.png -o OUT.pal [-n 16]
+```
+
+Quantizes `IN.png` to at most `-n` colours (default 16, the GBA 4bpp limit) and
+writes a JASC `.pal`:
+
+```
+JASC-PAL
+0100
+16
+115 131 164
+255 255 255
+...
+```
+
+### Apply a palette
+
+```sh
+porypal-fe8 apply IN.png PALETTE.pal -o OUT.png
+```
+
+Remaps every pixel of `IN.png` to the nearest colour in `PALETTE.pal` (nearest
+in Oklab) and saves an indexed (`P`-mode) PNG whose colours are exactly the
+palette.
+
+## How it fits the FE8 pipeline
+
+The decomp stores graphics as PNGs and JASC `.pal` palettes, and its Makefile
+drives `gbagfx` to turn those into the GBA's native formats:
+
+```
+            porypal-fe8 extract              gbagfx (pal2gbapal)
+   IN.png ───────────────────────▶  OUT.pal ───────────────────▶  .gbapal   (32 bytes for 16 colours)
+
+            porypal-fe8 apply                gbagfx (png2gbagfx)
+   IN.png ───────────────────────▶  OUT.png ───────────────────▶  .4bpp
+   (+ .pal)                         (indexed)
+```
+
+Relevant Makefile rules in the decomp:
+
+```make
+%.gbapal: %.pal ; $(PAL2GBAPAL) $< $@
+%.gbapal: %.png ; $(GBAGFX) $< $@
+```
+
+A 16-colour JASC `.pal` converts to exactly **32 bytes** of `.gbapal`
+(16 colours × 2 bytes, the GBA's 15-bit BGR555 format). Palettes are written
+with **CRLF** line endings to match the decomp's `.pal` files — `gbagfx`
+rejects LF-only palettes. See the
+[`fireemblem8u`](https://github.com/FireEmblemUniverse/fireemblem8u) repo and
+[`gbagfx`](https://github.com/pret/pokeemerald/tree/master/tools/gbagfx) for the
+full graphics flow.
+
+## How it works
+
+- **Quantization** clusters the image's pixels with **k-means++** in **Oklab**,
+  a perceptually uniform colour space, so the chosen colours match how the eye
+  groups them. Each cluster centre is then snapped to the nearest *actual*
+  colour in the source image, so every palette entry really occurs in the PNG.
+  If the image already has ≤ N colours, they are kept verbatim.
+- **Apply** assigns each pixel to the nearest palette colour, again measured in
+  Oklab.
+
+## Credits & license
+
+The colour-quantization approach and JASC `.pal` round-trip are **inspired by**
+[Loxed's Porypal](https://github.com/Loxed/porypal). Porypal is licensed under
+the **GPL-3.0**, which is incompatible with this project's MIT license, so
+**no Porypal source code was copied** — this is an independent reimplementation
+of the high-level idea only. Credit and thanks to Loxed.
+
+porypal-fe8 itself is released under the [MIT License](LICENSE).

porypal_fe8-0.1.1/palette_tool.py

@@ -0,0 +1,356 @@
+#!/usr/bin/env python3
+"""porypal-fe8: an FE8-oriented palette tool.
+
+A focused command-line tool for the ``fireemblem8u`` decomp graphics pipeline.
+It does two things:
+
+* ``extract`` -- quantize a PNG down to <=16 representative colours and write a
+  GBA-style JASC ``.pal`` palette (the format the decomp's hundreds of ``.pal``
+  files use, which ``tools/gbagfx`` converts to ``.gbapal``).
+* ``apply`` -- remap every pixel of a PNG to its nearest colour in a given
+  ``.pal`` and save an indexed PNG (ready for ``gbagfx`` to turn into ``.4bpp``).
+
+The colour-quantization idea (k-means over pixels in a perceptual colour space)
+and the JASC ``.pal`` round-trip are inspired by Loxed's Porypal
+(https://github.com/Loxed/porypal). Porypal is GPL-3.0 and Pokemon-specific;
+this is a clean, independent reimplementation of just that reusable core,
+distributed under the MIT license. Credit to Loxed for the approach.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Sequence, Tuple
+
+import numpy as np
+from PIL import Image
+
+# Maximum number of colours in a GBA 16-colour (4bpp) palette.
+GBA_MAX_COLORS = 16
+
+RGB = Tuple[int, int, int]
+
+
+# ---------------------------------------------------------------------------
+# JASC .pal I/O
+# ---------------------------------------------------------------------------
+def read_pal(path: str) -> List[RGB]:
+    """Read a JASC-PAL file and return a list of (R, G, B) tuples.
+
+    The JASC format is::
+
+        JASC-PAL
+        0100
+        <count>
+        R G B
+        ...
+
+    Raises ValueError if the file is not a well-formed JASC palette.
+    """
+    with open(path, "r", encoding="utf-8") as fh:
+        lines = [line.strip() for line in fh.read().splitlines()]
+
+    # Drop trailing blank lines (decomp pals often end with one).
+    while lines and lines[-1] == "":
+        lines.pop()
+
+    if len(lines) < 3:
+        raise ValueError(f"{path}: too short to be a JASC palette")
+    if lines[0] != "JASC-PAL":
+        raise ValueError(f"{path}: missing 'JASC-PAL' magic header")
+    if lines[1] != "0100":
+        raise ValueError(f"{path}: unexpected version '{lines[1]}' (expected 0100)")
+
+    try:
+        count = int(lines[2])
+    except ValueError as exc:
+        raise ValueError(f"{path}: invalid colour count '{lines[2]}'") from exc
+
+    colour_lines = lines[3:]
+    if len(colour_lines) < count:
+        raise ValueError(
+            f"{path}: header declares {count} colours but only "
+            f"{len(colour_lines)} colour lines are present"
+        )
+
+    colours: List[RGB] = []
+    for i in range(count):
+        parts = colour_lines[i].split()
+        if len(parts) != 3:
+            raise ValueError(
+                f"{path}: colour line {i + 1} ('{colour_lines[i]}') is not 'R G B'"
+            )
+        try:
+            r, g, b = (int(p) for p in parts)
+        except ValueError as exc:
+            raise ValueError(
+                f"{path}: colour line {i + 1} has non-integer component"
+            ) from exc
+        for value, name in ((r, "R"), (g, "G"), (b, "B")):
+            if not 0 <= value <= 255:
+                raise ValueError(
+                    f"{path}: {name}={value} on colour line {i + 1} out of range 0..255"
+                )
+        colours.append((r, g, b))
+
+    return colours
+
+
+def write_pal(path: str, colours: Sequence[RGB]) -> None:
+    """Write a list of (R, G, B) tuples to a JASC-PAL file.
+
+    Uses CRLF (``\\r\\n``) line endings: that is what the decomp's ``.pal``
+    files use, and ``gbagfx`` rejects LF-only palettes ("LF line endings aren't
+    supported"). ``newline=""`` stops Python from re-translating them.
+    """
+    if not colours:
+        raise ValueError("refusing to write an empty palette")
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write("JASC-PAL\r\n")
+        fh.write("0100\r\n")
+        fh.write(f"{len(colours)}\r\n")
+        for r, g, b in colours:
+            fh.write(f"{r} {g} {b}\r\n")
+
+
+# ---------------------------------------------------------------------------
+# Colour space: sRGB <-> Oklab
+# ---------------------------------------------------------------------------
+# Oklab (https://bottosson.github.io/posts/oklab/) is a perceptually uniform
+# colour space, so Euclidean distance in it matches human perception far better
+# than raw RGB. We cluster and find nearest colours in Oklab.
+def _srgb_to_linear(rgb: np.ndarray) -> np.ndarray:
+    """Convert sRGB in [0, 1] to linear-light RGB."""
+    return np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+
+
+def rgb_to_oklab(rgb_u8: np.ndarray) -> np.ndarray:
+    """Convert an (N, 3) array of 0..255 sRGB values to (N, 3) Oklab."""
+    rgb = _srgb_to_linear(rgb_u8.astype(np.float64) / 255.0)
+    r, g, b = rgb[:, 0], rgb[:, 1], rgb[:, 2]
+
+    l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
+    m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
+    s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
+
+    l_ = np.cbrt(l)
+    m_ = np.cbrt(m)
+    s_ = np.cbrt(s)
+
+    return np.stack(
+        [
+            0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_,
+            1.9779984951 * l_ - 2.4285922050 * m_ + 0.4505937099 * s_,
+            0.0259040371 * l_ + 0.7827717662 * m_ - 0.8086757660 * s_,
+        ],
+        axis=1,
+    )
+
+
+# ---------------------------------------------------------------------------
+# K-means quantization
+# ---------------------------------------------------------------------------
+def _kmeans(
+    points: np.ndarray,
+    k: int,
+    *,
+    weights: np.ndarray | None = None,
+    seed: int = 0,
+    max_iter: int = 100,
+) -> np.ndarray:
+    """Run weighted k-means on (N, D) points; return (k, D) cluster centres.
+
+    ``weights`` (length N, default all-ones) lets a single point stand in for
+    many identical ones -- e.g. clustering an image's distinct colours weighted
+    by how many pixels have each, which is equivalent to clustering every pixel
+    but far cheaper. Uses k-means++ seeding for stable, good-quality centres.
+    ``k`` is clamped to the number of distinct points so we never produce empty
+    clusters.
+    """
+    rng = np.random.default_rng(seed)
+    n = points.shape[0]
+    k = min(k, n)
+    if weights is None:
+        weights = np.ones(n, dtype=np.float64)
+
+    # k-means++ initialisation (sampling weighted by D^2 * pixel count).
+    centres = np.empty((k, points.shape[1]), dtype=points.dtype)
+    centres[0] = points[rng.integers(n)]
+    closest_sq = np.sum((points - centres[0]) ** 2, axis=1)
+    for i in range(1, k):
+        scored = closest_sq * weights
+        total = scored.sum()
+        if total <= 0:
+            # All remaining points coincide with chosen centres; pad arbitrarily.
+            centres[i] = points[rng.integers(n)]
+        else:
+            centres[i] = points[rng.choice(n, p=scored / total)]
+        new_dist = np.sum((points - centres[i]) ** 2, axis=1)
+        closest_sq = np.minimum(closest_sq, new_dist)
+
+    labels = np.zeros(n, dtype=np.int64)
+    for _ in range(max_iter):
+        # Assign each point to the nearest centre.
+        dists = np.sum((points[:, None, :] - centres[None, :, :]) ** 2, axis=2)
+        new_labels = np.argmin(dists, axis=1)
+        if np.array_equal(new_labels, labels):
+            break
+        labels = new_labels
+        # Recompute centres as the weighted mean of their members; keep empties put.
+        for c in range(k):
+            mask = labels == c
+            w = weights[mask]
+            wsum = w.sum()
+            if wsum > 0:
+                centres[c] = (points[mask] * w[:, None]).sum(axis=0) / wsum
+
+    return centres
+
+
+def quantize_image(img: Image.Image, n_colors: int) -> List[RGB]:
+    """Return up to ``n_colors`` representative RGB colours for ``img``.
+
+    Clusters the image's distinct colours -- weighted by how many pixels carry
+    each, so common colours dominate -- in Oklab for perceptual accuracy, then
+    maps each centre back to the nearest *actual* image colour so every palette
+    entry exists in the source. Weighting the distinct colours is equivalent to
+    clustering every pixel but costs only as much as the (small) palette of
+    distinct colours.
+    """
+    if n_colors < 1:
+        raise ValueError("n_colors must be >= 1")
+
+    rgb = np.asarray(img.convert("RGB"), dtype=np.uint8).reshape(-1, 3)
+    unique, counts = np.unique(rgb, axis=0, return_counts=True)
+
+    if len(unique) <= n_colors:
+        # Already within budget -- keep every colour, sorted for determinism.
+        ordered = unique[np.lexsort((unique[:, 2], unique[:, 1], unique[:, 0]))]
+        return [tuple(int(v) for v in row) for row in ordered]
+
+    # Cluster the distinct colours, weighted by pixel frequency, in Oklab space.
+    unique_lab = rgb_to_oklab(unique)
+    centres_lab = _kmeans(unique_lab, n_colors, weights=counts.astype(np.float64))
+
+    # Snap each cluster centre to the nearest real image colour (in Oklab).
+    palette: List[RGB] = []
+    seen = set()
+    for centre in centres_lab:
+        idx = int(np.argmin(np.sum((unique_lab - centre) ** 2, axis=1)))
+        colour = tuple(int(v) for v in unique[idx])
+        if colour not in seen:
+            seen.add(colour)
+            palette.append(colour)
+
+    palette.sort()
+    return palette
+
+
+# ---------------------------------------------------------------------------
+# Apply a palette to an image
+# ---------------------------------------------------------------------------
+def apply_palette(img: Image.Image, palette: Sequence[RGB]) -> Image.Image:
+    """Remap every pixel of ``img`` to its nearest palette colour (in Oklab).
+
+    Returns a paletted ('P' mode) image whose colours are exactly ``palette``,
+    so ``gbagfx`` can convert it to indexed GBA graphics.
+    """
+    if not palette:
+        raise ValueError("cannot apply an empty palette")
+    if len(palette) > 256:
+        raise ValueError("a paletted PNG supports at most 256 colours")
+
+    rgb = np.asarray(img.convert("RGB"), dtype=np.uint8)
+    h, w, _ = rgb.shape
+    flat = rgb.reshape(-1, 3)
+
+    pal_arr = np.asarray(palette, dtype=np.uint8)
+    pixels_lab = rgb_to_oklab(flat)
+    pal_lab = rgb_to_oklab(pal_arr)
+
+    dists = np.sum((pixels_lab[:, None, :] - pal_lab[None, :, :]) ** 2, axis=2)
+    indices = np.argmin(dists, axis=1).astype(np.uint8)
+
+    out = Image.fromarray(indices.reshape(h, w), mode="P")
+    # PIL palettes hold 256 entries; pad the unused tail with zeros.
+    flat_palette: List[int] = []
+    for r, g, b in palette:
+        flat_palette.extend((r, g, b))
+    flat_palette.extend([0] * (256 * 3 - len(flat_palette)))
+    out.putpalette(flat_palette)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+def cmd_extract(args: argparse.Namespace) -> int:
+    if not 1 <= args.n <= GBA_MAX_COLORS:
+        print(
+            f"error: -n must be between 1 and {GBA_MAX_COLORS} "
+            f"(a GBA 4bpp palette holds at most {GBA_MAX_COLORS} colours)",
+            file=sys.stderr,
+        )
+        return 2
+    img = Image.open(args.input)
+    palette = quantize_image(img, args.n)
+    write_pal(args.output, palette)
+    print(f"wrote {args.output}: {len(palette)} colours")
+    return 0
+
+
+def cmd_apply(args: argparse.Namespace) -> int:
+    palette = read_pal(args.palette)
+    img = Image.open(args.input)
+    out = apply_palette(img, palette)
+    out.save(args.output)
+    print(f"wrote {args.output}: remapped to {len(palette)} palette colours")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="porypal-fe8",
+        description="FE8 palette tool: PNG <-> 16-colour JASC .pal.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_extract = sub.add_parser(
+        "extract",
+        help="quantize a PNG to <=16 colours and write a JASC .pal",
+    )
+    p_extract.add_argument("input", help="input PNG path")
+    p_extract.add_argument("-o", "--output", required=True, help="output .pal path")
+    p_extract.add_argument(
+        "-n",
+        type=int,
+        default=GBA_MAX_COLORS,
+        help=f"max colours (1..{GBA_MAX_COLORS}, default {GBA_MAX_COLORS})",
+    )
+    p_extract.set_defaults(func=cmd_extract)
+
+    p_apply = sub.add_parser(
+        "apply",
+        help="remap a PNG to a .pal palette and save an indexed PNG",
+    )
+    p_apply.add_argument("input", help="input PNG path")
+    p_apply.add_argument("palette", help="JASC .pal path")
+    p_apply.add_argument("-o", "--output", required=True, help="output PNG path")
+    p_apply.set_defaults(func=cmd_apply)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (OSError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

porypal_fe8-0.1.1/porypal_fe8.egg-info/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: porypal-fe8
+Version: 0.1.1
+Summary: FE8 palette tool: PNG -> 16-colour JASC .pal extraction & apply (fireemblem8u; inspired by Loxed's Porypal)
+Author: laqieer
+License: MIT License
+        
+        Copyright (c) 2026 laqieer
+        
+        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.
+        
+        
+        --------------------------------------------------------------------------------
+        Acknowledgements
+        
+        porypal-fe8 is an independent, clean-room reimplementation inspired by the
+        reusable palette core of Loxed's Porypal (https://github.com/Loxed/porypal):
+        the idea of k-means colour quantization in a perceptual colour space and the
+        JASC ".pal" round-trip. Porypal is licensed under the GPL-3.0, which is
+        incompatible with this MIT distribution, so no Porypal source code was copied;
+        only the high-level approach was reused. Credit and thanks to Loxed.
+        
+Project-URL: Homepage, https://github.com/laqieer/porypal-fe8
+Keywords: gba,fireemblem,palette,jasc,decomp,fe8
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pillow>=9.0
+Requires-Dist: numpy>=1.21
+Dynamic: license-file
+
+# porypal-fe8
+
+A small, FE8-oriented palette CLI for the
+[`fireemblem8u`](https://github.com/FireEmblemUniverse/fireemblem8u) decomp
+graphics pipeline. It does two things:
+
+- **`extract`** — quantize a PNG down to **≤16 colours** and write a GBA-style
+  **JASC `.pal`** palette.
+- **`apply`** — remap every pixel of a PNG to its nearest colour in a given
+  `.pal` and save an **indexed PNG**, ready for `gbagfx`.
+
+It is a focused, clean reimplementation of the *reusable core* of
+[Loxed's Porypal](https://github.com/Loxed/porypal) — k-means colour
+quantization in a perceptual colour space (Oklab) plus JASC `.pal` I/O — with
+all the Pokémon-specific and UI parts dropped. See
+[Credits & license](#credits--license).
+
+## Why this exists (honest note)
+
+For day-to-day FE8 graphics work you usually **do not need this tool**:
+
+- [**Usenti**](https://www.coranac.com/projects/usenti/) handles palette
+  editing, reduction, and indexed-PNG export interactively.
+- The decomp's own **`gbagfx`** already converts between `.png`, `.pal`,
+  `.gbapal`, and `.4bpp`.
+
+`porypal-fe8` is for **batch / automated quantization** — e.g. scripting the
+reduction of many full-colour PNGs to 16-colour palettes in a build or asset
+pipeline, where a headless CLI is more convenient than a GUI.
+
+## Install
+
+Requires Python 3.9+.
+
+```sh
+python3 -m venv .venv && . .venv/bin/activate
+pip install -r requirements.txt
+# optional: install the `porypal-fe8` console command
+pip install .
+```
+
+Without installing, you can run the module directly:
+
+```sh
+python3 palette_tool.py extract IN.png -o OUT.pal
+```
+
+## Install / Releases
+
+Once published to PyPI:
+
+```sh
+pip install porypal-fe8
+```
+
+Each `v*` tag also produces a **GitHub Release** with the built wheel and sdist
+attached (under [Releases](https://github.com/laqieer/porypal-fe8/releases)),
+so you can `pip install` a downloaded artifact even without PyPI.
+
+> **Note:** PyPI publishing uses [OIDC trusted
+> publishing](https://docs.pypi.org/trusted-publishers/) (no API token). It
+> requires a **trusted publisher** to be configured on PyPI for project
+> `porypal-fe8`, owner `laqieer`, workflow `release.yml`, environment `pypi`.
+> The GitHub Release job is independent and succeeds even before that is set up.
+
+## Usage
+
+### Extract a palette
+
+```sh
+porypal-fe8 extract IN.png -o OUT.pal [-n 16]
+```
+
+Quantizes `IN.png` to at most `-n` colours (default 16, the GBA 4bpp limit) and
+writes a JASC `.pal`:
+
+```
+JASC-PAL
+0100
+16
+115 131 164
+255 255 255
+...
+```
+
+### Apply a palette
+
+```sh
+porypal-fe8 apply IN.png PALETTE.pal -o OUT.png
+```
+
+Remaps every pixel of `IN.png` to the nearest colour in `PALETTE.pal` (nearest
+in Oklab) and saves an indexed (`P`-mode) PNG whose colours are exactly the
+palette.
+
+## How it fits the FE8 pipeline
+
+The decomp stores graphics as PNGs and JASC `.pal` palettes, and its Makefile
+drives `gbagfx` to turn those into the GBA's native formats:
+
+```
+            porypal-fe8 extract              gbagfx (pal2gbapal)
+   IN.png ───────────────────────▶  OUT.pal ───────────────────▶  .gbapal   (32 bytes for 16 colours)
+
+            porypal-fe8 apply                gbagfx (png2gbagfx)
+   IN.png ───────────────────────▶  OUT.png ───────────────────▶  .4bpp
+   (+ .pal)                         (indexed)
+```
+
+Relevant Makefile rules in the decomp:
+
+```make
+%.gbapal: %.pal ; $(PAL2GBAPAL) $< $@
+%.gbapal: %.png ; $(GBAGFX) $< $@
+```
+
+A 16-colour JASC `.pal` converts to exactly **32 bytes** of `.gbapal`
+(16 colours × 2 bytes, the GBA's 15-bit BGR555 format). Palettes are written
+with **CRLF** line endings to match the decomp's `.pal` files — `gbagfx`
+rejects LF-only palettes. See the
+[`fireemblem8u`](https://github.com/FireEmblemUniverse/fireemblem8u) repo and
+[`gbagfx`](https://github.com/pret/pokeemerald/tree/master/tools/gbagfx) for the
+full graphics flow.
+
+## How it works
+
+- **Quantization** clusters the image's pixels with **k-means++** in **Oklab**,
+  a perceptually uniform colour space, so the chosen colours match how the eye
+  groups them. Each cluster centre is then snapped to the nearest *actual*
+  colour in the source image, so every palette entry really occurs in the PNG.
+  If the image already has ≤ N colours, they are kept verbatim.
+- **Apply** assigns each pixel to the nearest palette colour, again measured in
+  Oklab.
+
+## Credits & license
+
+The colour-quantization approach and JASC `.pal` round-trip are **inspired by**
+[Loxed's Porypal](https://github.com/Loxed/porypal). Porypal is licensed under
+the **GPL-3.0**, which is incompatible with this project's MIT license, so
+**no Porypal source code was copied** — this is an independent reimplementation
+of the high-level idea only. Credit and thanks to Loxed.
+
+porypal-fe8 itself is released under the [MIT License](LICENSE).

porypal_fe8-0.1.1/porypal_fe8.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+palette_tool.py
+pyproject.toml
+porypal_fe8.egg-info/PKG-INFO
+porypal_fe8.egg-info/SOURCES.txt
+porypal_fe8.egg-info/dependency_links.txt
+porypal_fe8.egg-info/entry_points.txt
+porypal_fe8.egg-info/requires.txt
+porypal_fe8.egg-info/top_level.txt

porypal_fe8-0.1.1/porypal_fe8.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

porypal_fe8-0.1.1/porypal_fe8.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+porypal-fe8 = palette_tool:main

porypal_fe8-0.1.1/porypal_fe8.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pillow>=9.0
+numpy>=1.21

porypal_fe8-0.1.1/porypal_fe8.egg-info/top_level.txt

@@ -0,0 +1 @@
+palette_tool

porypal_fe8-0.1.1/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "porypal-fe8"
+version = "0.1.1"
+description = "FE8 palette tool: PNG -> 16-colour JASC .pal extraction & apply (fireemblem8u; inspired by Loxed's Porypal)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "laqieer" }]
+keywords = ["gba", "fireemblem", "palette", "jasc", "decomp", "fe8"]
+dependencies = [
+    "pillow>=9.0",
+    "numpy>=1.21",
+]
+
+[project.urls]
+Homepage = "https://github.com/laqieer/porypal-fe8"
+
+[project.scripts]
+porypal-fe8 = "palette_tool:main"
+
+[tool.setuptools]
+py-modules = ["palette_tool"]

porypal_fe8-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+