apftool 1.1.3__tar.gz → 1.2.0__tar.gz

{apftool-1.1.3 → apftool-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apftool
-Version: 1.1.3
+Version: 1.2.0
 Summary: Encoder and decoder for Aperture Science Image Format (apf), Aperture Science Image Format 2 (apf2), Wireless Bitmap (wbmp), Over-The-Air Bitmap (otb), and FaceDev's .bruh format
 Author: Mari (kbity)
 Requires-Python: >=3.10
@@ -96,10 +96,12 @@ apftool provides many extensions tuples:
 
 `PIL (pillow)` is required
 
-`numpy` and `scikit-learn` are needed for high-speed APF2-1994 257+ Color Encoding, if missing the code will use a very slow fallback.
+`numpy` and `scipy` are needed for high-quality, high-speed APF2 encoding, if missing the code will use a very slow and low quality fallback.
 
 ## changelog:
 
+1.2.0 - increase apfcli verbosity, add lossy encoding options. Allow apfcli to take its own formats as inputs and outputs, also adds a much better quantization algorithm and removes the limitations on indexed animations.
+
 1.1.3 - add version field, add width and height options to apf2 encoding
 
 1.1.2 - fix apftool

{apftool-1.1.3 → apftool-1.2.0}/README.md

@@ -85,10 +85,12 @@ apftool provides many extensions tuples:
 
 `PIL (pillow)` is required
 
-`numpy` and `scikit-learn` are needed for high-speed APF2-1994 257+ Color Encoding, if missing the code will use a very slow fallback.
+`numpy` and `scipy` are needed for high-quality, high-speed APF2 encoding, if missing the code will use a very slow and low quality fallback.
 
 ## changelog:
 
+1.2.0 - increase apfcli verbosity, add lossy encoding options. Allow apfcli to take its own formats as inputs and outputs, also adds a much better quantization algorithm and removes the limitations on indexed animations.
+
 1.1.3 - add version field, add width and height options to apf2 encoding
 
 1.1.2 - fix apftool

{apftool-1.1.3 → apftool-1.2.0}/apftool/__init__.py

@@ -13,7 +13,7 @@ extensions_mqif = (".mqif", ".mqi")
 
 extensions_txt = (".txt", ".text") # txt is seen as a generic container for apf/apf2 because they're just txt files
 
-version = "1.1.3"
+version = "1.2.0"
 
 extensions_all = []
 extensions_all.extend(extensions_apf+extensions_apf2+extensions_wbmp+extensions_otb+extensions_bruh+extensions_mqif)

{apftool-1.1.3 → apftool-1.2.0}/apftool/apf2.py

@@ -1,17 +1,16 @@
 from PIL import Image, ImageSequence
 from collections import Counter
-import io, textwrap
+import io, textwrap, math
 
 qmf = "basic"
 
 # try numpy and sklearn
 try:
     import numpy as np
-    from sklearn.cluster import MiniBatchKMeans
-    from sklearn.metrics import pairwise_distances_argmin
+    from .apf2quant import quantize_perceptual
     qmf = "sk"
 except Exception as e:
-    print(f"Importing sklearn or numpy failed, high-color images and images with alpha may encode slowly or not at all, and dithering will be unavailable for them!\n{e}")
+    print(f"Importing scipy or numpy failed, high-color images and images with alpha may encode slowly or not at all, dithering will be unavailable for them, and quality will be worse!\n{e}")
 
 # width and height are 320x200 for standard apf files
 apf2headertext = "APERTURE IMAGE FORMAT (c) 1993" # apf2 header
@@ -27,73 +26,8 @@ mapping = []
 for i in range(256):
     mapping.append(chr(quant_to_base95(i)+32))
 
-# fast sklearn version
-def quantize_most_frequent_sk(img: Image.Image, n_colors: int, palette: list = None, dither: bool = False):
-    img = img.convert("RGBA")
-    arr = np.array(img, dtype=np.uint8)
-    flat = arr.reshape(-1, 4).astype(np.float32)
-
-    if palette is not None:
-        # ---- FIXED PALETTE MODE ----
-        palette_arr = np.array(palette, dtype=np.uint8)
-    else:
-        # ---- KMEANS MODE ----
-        kmeans = MiniBatchKMeans(
-            n_clusters=n_colors,
-            batch_size=10_000,
-            n_init="auto",
-            random_state=0
-        )
-        kmeans.fit(flat)
-        palette_arr = kmeans.cluster_centers_.astype(np.uint8)
-
-    if dither:
-        # Floyd-Steinberg dithering — operate on a float copy to accumulate error
-        h, w = arr.shape[:2]
-        buf = arr.astype(np.float32)  # (H, W, 4)
-
-        out_indices = np.empty((h, w), dtype=np.int32)
-
-        for y in range(h):
-            # Serpentine scan (alternating direction) reduces directional bias
-            xs = range(w) if y % 2 == 0 else range(w - 1, -1, -1)
-            for x in xs:
-                old = buf[y, x]
-                idx = pairwise_distances_argmin(old[np.newaxis], palette_arr)[0]
-                out_indices[y, x] = idx
-                new = palette_arr[idx].astype(np.float32)
-                err = old - new
-
-                # Distribute error to 4 neighbours (Floyd-Steinberg weights)
-                if y % 2 == 0:  # left-to-right
-                    if x + 1 < w:
-                        buf[y,     x + 1] += err * (7 / 16)
-                    if y + 1 < h:
-                        if x - 1 >= 0:
-                            buf[y + 1, x - 1] += err * (3 / 16)
-                        buf[y + 1, x    ] += err * (5 / 16)
-                        if x + 1 < w:
-                            buf[y + 1, x + 1] += err * (1 / 16)
-                else:           # right-to-left
-                    if x - 1 >= 0:
-                        buf[y,     x - 1] += err * (7 / 16)
-                    if y + 1 < h:
-                        if x + 1 < w:
-                            buf[y + 1, x + 1] += err * (3 / 16)
-                        buf[y + 1, x    ] += err * (5 / 16)
-                        if x - 1 >= 0:
-                            buf[y + 1, x - 1] += err * (1 / 16)
-
-        quantized = palette_arr[out_indices].reshape(arr.shape)
-    else:
-        labels = pairwise_distances_argmin(flat, palette_arr)
-        quantized = palette_arr[labels].reshape(arr.shape)
-
-    palette_out = [tuple(map(int, x)) for x in palette_arr]
-    return Image.fromarray(quantized, "RGBA"), palette_out
-
 # slow pure python version
-def quantize_most_frequent_basic(img: Image.Image, n_colors: int, palette: list = None, dither: bool = False): # for use with A and P>256 images, dithering unsupported for basic mode
+def quantize_most_frequent_basic(img: Image.Image, n_colors: int, palette: list = None, dither: bool = False, dither_mode: str = None): # for use with A and P>256 images, dithering unsupported for basic mode
     img = img.convert("RGBA")  # ensures consistent format
     pixels = list(img.getdata())
 
@@ -126,7 +60,9 @@ def quantize_most_frequent_basic(img: Image.Image, n_colors: int, palette: list
     return out, palette
 
 if qmf == "sk":
-    quantize_most_frequent = quantize_most_frequent_sk
+    quantize_most_frequent = quantize_perceptual
+#if qmf == "sk": replaced by claude's perceptual quantizer. don't feel sad, the old one was also vibecoded.
+#    quantize_most_frequent = quantize_most_frequent_sk
 #elif qmf == "numpy":   removed the numpy backend because it was having problems
 #    quantize_most_frequent = quantize_most_frequent_numpy
 else:
@@ -207,6 +143,9 @@ def flexTypeToRGB(inpt: str, mode: int, trans: bool = False):
     # 4 - near-truecolor with alpha
     # 5 - truecolor (can be paired with t to store 3 levels of alpha)
     # 6 - truecolor with alpha
+
+    # 7 - 95-level Grayscale
+    # 8 - 8-bit Grayscale
     if mode == 3:
         r = mapping.index(inpt[0])
         g = mapping.index(inpt[1])
@@ -258,6 +197,15 @@ def flexTypeToRGB(inpt: str, mode: int, trans: bool = False):
         ac = (c//27)%3
 
         return r+rc, g+gc, b+bc, a+ac
+
+    elif mode == 7:
+        r = mapping.index(inpt[0])
+        return [r, r, r]
+
+    elif mode == 8:
+        ind = (ord(inpt[0])-32)*95
+        ind += (ord(inpt[1])-32)
+        return [ind, ind, ind]
     else:
         raise ValueError("Invalid/Unsupported Mode")
 
@@ -660,73 +608,60 @@ def slice_frames(img: Image, animated, trans):
     else:
         return img, None
 
-def reduce_to_apf2_quality(img: Image, num_colors: int = 95, animated: bool = False, trans = 0, prepalette: list = None, dodithering: bool = False):
+def reduce_to_apf2_quality(img: Image, num_colors: int = 95, animated: bool = False, trans = 0, prepalette: list = None, dodithering: bool = False, useadvancedquant: bool = False, dither_mode: str = "fs", verbose: bool = False):
     trans = int(trans)
     if animated:
-        # avoid expensive repeated hi-color quantize computing of every frame
-        if trans == 2:
-            trans = 1
-        if num_colors > 256:
-            num_colors = 256
-            if trans:
-                num_colors = 255
-            print("Animation Detected, capping colors to 255/256")
-        if dodithering:
-            print("Animated APF2s do not get dithered, sorry.")
-
-        ifuckinghatequantize = (255, 0, 255)
-
         frames = []
         frametiming = 0
-        if trans:
-            for frame in ImageSequence.Iterator(img):
-                if not frametiming:
-                    frametiming = frame.info.get("duration", img.info.get("duration", 0))
-
-                frame = frame.convert("RGBA")
-                background = Image.new("RGBA", frame.size, ifuckinghatequantize + (255,))
-                composited = Image.alpha_composite(background, frame)
-                frames.append(composited.convert("RGB"))
-        else:
-            for frame in ImageSequence.Iterator(img):
-                if not frametiming:
-                    frametiming = frame.info.get("duration", img.info.get("duration", 0))
-                frames.append(frame.copy().convert("RGB"))
+
+        for frame in ImageSequence.Iterator(img):
+            if not frametiming:
+                frametiming = int(frame.info.get("duration", img.info.get("duration", 0)))
+            frames.append(frame.copy())
 
         widths, heights = zip(*(f.size for f in frames))
         total_width = max(widths)
         total_height = sum(heights)
-        combined = Image.new("RGB", (total_width, total_height))
+        if trans == 2:
+            combined = Image.new("RGBA", (total_width, total_height))
+        else:
+            combined = Image.new("RGB", (total_width, total_height))
         y_offset = 0
 
         for frame in frames:
             combined.paste(frame, (0, y_offset))
             y_offset += frame.height
 
-        if trans:
-            combined_p = combined.convert("P", palette=Image.ADAPTIVE, colors=num_colors-1, dither=Image.NONE)
-
-            pal = combined_p.getpalette()
-            pal = [255, 0, 255] + pal
-            combined_p.putpalette(pal)
+        if trans == 2:
+            _, prepalette = quantize_most_frequent(combined, num_colors-1, prepalette)
+            prepalette = [(0, 0, 0, 0)] + prepalette # hack to make cross-frame trans = 2 not break
+        elif trans == 1:
+            _, prepalette = quantize_most_frequent(combined, num_colors-1, prepalette)
+            prepalette = [(255, 0, 255, 0)] + prepalette
         else:
-            combined_p = combined.convert("P", palette=Image.ADAPTIVE, colors=num_colors-1, dither=Image.NONE)
+            _, prepalette = quantize_most_frequent(combined, num_colors, prepalette)
+        if verbose:
+            print("Generated Animation Palette!")
 
         frames_p = []
-        for frame in frames:
-            f_p = frame.quantize(palette=combined_p, dither=Image.NONE)
-            if trans:
-                f_p.info["transparency"] = 0
+        for i, frame in enumerate(frames):
+            f_p, _ = quantize_most_frequent(frame, num_colors, prepalette, dodithering, dither_mode = dither_mode)
             frames_p.append(f_p)
+            if verbose:
+                print(f"Quantized frame {i+1}/{len(frames)}")
 
-        raw_palette = combined_p.getpalette()[:num_colors*3]
         seen = set()
-        palette = [tuple(raw_palette[i:i+3]) for i in range(0, len(raw_palette), 3) if not (tuple(raw_palette[i:i+3]) in seen or seen.add(tuple(raw_palette[i:i+3])))]
 
-        return frames_p, palette, frametiming, trans
+        npp = []
+        if not trans == 2: # remove whatever
+            for ind in prepalette:
+                npp.append((ind[0], ind[1], ind[2]))
+            prepalette = npp
+
+        return frames_p, prepalette, frametiming, trans
     else:
-        if trans == 2 or num_colors > 256 or prepalette:
-            img, palette = quantize_most_frequent(img, num_colors, prepalette, dodithering)
+        if trans == 2 or num_colors > 256 or prepalette or useadvancedquant:
+            img, palette = quantize_most_frequent(img, num_colors, prepalette, dodithering, dither_mode = dither_mode)
             if trans != 2:
                 palette_na = []
                 for col in palette:
@@ -855,7 +790,26 @@ def order_pixels(bitmap, h, lineskip, topside_first):
 
     return revmap
 
-def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, compress: bool, topside_first: bool, mode: int, combine: bool = False, prevframe: list = None, avoid_run_breaks: bool = False, transmag: bool = False):
+def calc_error(currentrun, pixel, maxerror, foofcontrol = False):
+    if foofcontrol and pixel == (255, 0, 255):
+        if (pixel == currentrun):
+            return True
+        else:
+            return False
+
+    if currentrun is None:
+        return False
+
+    if len(currentrun) == 4 and len(pixel) == 4:
+        if currentrun[3] != pixel[3]:
+            return False
+
+    re = abs(currentrun[0]-pixel[0])
+    ge = abs(currentrun[1]-pixel[1])
+    be = abs(currentrun[2]-pixel[2])
+    return (( re * 2 + ge * 4 + be ) / 5) <= maxerror
+
+def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, compress: bool, topside_first: bool, mode: int, combine: bool = False, prevframe: list = None, avoid_run_breaks: bool = False, transmag: bool = False, maxmotionerror: float = 0, maxrunerror: float = 0):
     if mode <3: # heart
         raise ValueError("Modes 0, 1, and 2 should not be flex encoded!")
 
@@ -881,6 +835,7 @@ def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, com
 
     runcounter = 0
     currentrun = None
+    currentrun_pixel = None # for error thing
     runlens = []
 
     revmap = order_pixels(bitmap, h, lineskip, topside_first)
@@ -909,7 +864,13 @@ def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, com
             pixel = revmap[y][x]
             if prevrev:
                 if not avoid_run_breaks or (not (runcounter>1 and not currentrun in transtuples)):
-                    if pixel == prevrev[y][x]:
+                   # lossy motion encoding mode
+                    if maxmotionerror:
+                        cont = calc_error(prevrev[y][x], pixel, maxmotionerror)
+                    else:
+                        cont = (pixel == prevrev[y][x])
+
+                    if cont:
                         pixel = (255, 0, 255) if transmag else (0,0,0,0)
                         isTransPix = True
 
@@ -957,7 +918,13 @@ def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, com
                 if not isTransPix and (transmag and curpixval == "~ ~"):
                     curpixval = "~!~"
 
-            if currentrun == curpixval:
+            # lossy RLE encoding mode
+            if maxrunerror and not (runcounter+1 > 94):
+                cont = calc_error(currentrun_pixel, pixel, maxrunerror, transmag)
+            else:
+                cont = (currentrun == curpixval)
+
+            if cont:
                 if (runcounter+1 > 94) or (not compress): # dont compress
                     if currentrun is not None:
                         runlens.append([curpixval, runcounter])
@@ -971,6 +938,9 @@ def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, com
                     runlens.append([currentrun, runcounter])
                 runcounter = 1
                 currentrun = curpixval
+                currentrun_pixel = pixel
+                if not isTransPix and (transmag and pixel == (255, 0, 255)):
+                    currentrun_pixel = (255, 2, 255)
 
     if runcounter > 0:
         if trans and currentrun[3] == 0:
@@ -983,7 +953,7 @@ def generate_runs_apf2_f(bitmap: list, lineskip: int, w: int, h: int, trans, com
     total = sum(rldb)
     return runlens
 
-def generate_runs_apf2(bitmap: list, palette: list, lineskip: int, w: int, h: int, trans = 0, dim: bool = False, prepalette: str = None, compress: bool = True, topside_first: bool = False, palette_only: bool = False, combine: bool = False, prevframe: list = None, avoid_run_breaks: bool = False):
+def generate_runs_apf2(bitmap: list, palette: list, lineskip: int, w: int, h: int, trans = 0, dim: bool = False, prepalette: str = None, compress: bool = True, topside_first: bool = False, palette_only: bool = False, combine: bool = False, prevframe: list = None, avoid_run_breaks: bool = False, maxmotionerror: float = 0, maxrunerror: float = 0, useadvancedquant: bool = False):
     trans = int(trans)
     colpal = {}
     colpalbnr = {}
@@ -1066,10 +1036,21 @@ def generate_runs_apf2(bitmap: list, palette: list, lineskip: int, w: int, h: in
             pixel = revmap[y][x]
             if prevrev:
                 if not avoid_run_breaks or (not (runcounter>1 and not currentrun == (0,0,0,0))):
-                    if pixel == prevrev[y][x]:
+                   # lossy motion encoding mode
+                    if maxmotionerror:
+                        cont = calc_error(prevrev[y][x], pixel, maxmotionerror)
+                    else:
+                        cont = (pixel == prevrev[y][x])
+                    if cont:
                         pixel = (0,0,0,0)
 
-            if currentrun == pixel:
+            # lossy RLE encoding mode
+            if maxrunerror and not (runcounter+1 > 94):
+                cont = calc_error(currentrun, pixel, maxrunerror)
+            else:
+                cont = (currentrun == pixel)
+
+            if cont:
                 if (runcounter+1 > 94) or (not compress): # dont compress
                     if currentrun is not None:
                         if not currentrun in colpalbnr:
@@ -1101,12 +1082,17 @@ def generate_runs_apf2(bitmap: list, palette: list, lineskip: int, w: int, h: in
     return runlens, apf2pal
 
 # wrapper function to encode the data
-def encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_first, bg, trans, avoid_run_breaks, transmag, mode, combine, palette, dim, prepalette, compress):
+def encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_first, bg, trans, avoid_run_breaks, transmag, mode, combine, palette, dim, prepalette, compress, verbose, maxmotionerror, maxrunerror):
     apf2pal = None
 
     if legacy:
         outputs = []
+        animated = (len(bitmaps) > 1)
+        inc = 0
         for bitmap in bitmaps:
+            if verbose and animated:
+                print(f"Encoding frame {inc+1}/{len(bitmaps)}...")
+            inc+=1
             temp = []
             runlens = generate_runs_apf2_l(bitmap, lineskip, w, h, topside_first, bg, trans)
             for num in runlens:
@@ -1118,13 +1104,17 @@ def encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_fir
 
     elif gray or truecolor:
         outputs = []
+        animated = (len(bitmaps) > 1)
+
         for bm in range(len(bitmaps)):
+            if verbose and animated:
+                print(f"Encoding frame {bm+1}/{len(bitmaps)}...")
             temp = []
             prevframe = None
             if bm != 0 and combine:
                 prevframe = bitmaps[bm-1]
 
-            runlens = generate_runs_apf2_f(bitmaps[bm], lineskip, w, h, trans, compress, topside_first, mode, combine, prevframe, avoid_run_breaks, transmag)
+            runlens = generate_runs_apf2_f(bitmaps[bm], lineskip, w, h, trans, compress, topside_first, mode, combine, prevframe, avoid_run_breaks, transmag, maxmotionerror, maxrunerror)
             for num in runlens:
                 temp.append(num[0])
                 if compress:
@@ -1139,14 +1129,17 @@ def encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_fir
     else:
         outputs = []
         _, apf2pal = generate_runs_apf2(bitmaps[0], palette, lineskip, w, h, trans, dim, prepalette, compress, topside_first, True)
+        animated = (len(bitmaps) > 1)
 
         for bm in range(len(bitmaps)):
+            if verbose and animated:
+                print(f"Encoding frame {bm+1}/{len(bitmaps)}...")
             temp = []
             prevframe = None
             if bm != 0 and combine:
                 prevframe = bitmaps[bm-1]
 
-            runlens, _ = generate_runs_apf2(bitmaps[bm], palette, lineskip, w, h, trans, dim, prepalette, compress, topside_first, False, combine, prevframe, avoid_run_breaks)
+            runlens, _ = generate_runs_apf2(bitmaps[bm], palette, lineskip, w, h, trans, dim, prepalette, compress, topside_first, False, combine, prevframe, avoid_run_breaks, maxmotionerror, maxrunerror)
             for num in runlens:
                 temp.append(num[0])
                 if compress:
@@ -1166,7 +1159,7 @@ def encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_fir
 
     return output, apf2pal
 
-def encode(img: bytes | Image.Image, lineskip: int = None, findbestlineskip: bool = False, legacy: bool = False, trans = False, pal: int = 95, desc: str = "", prepalette: str = None, dodithering: bool = False, returnbytes: bool = False, compress: bool = True, topside_first: bool = False, emit_redundant_flag: bool = False, mode: int = None, combine: bool = False, avoid_run_breaks: bool = False, width: int = None, height: int = None):
+def encode(img: bytes | Image.Image, lineskip: int = None, findbestlineskip: bool = False, legacy: bool = False, trans = False, pal: int = 95, desc: str = "", prepalette: str = None, dodithering: bool = False, returnbytes: bool = False, compress: bool = True, topside_first: bool = False, emit_redundant_flag: bool = False, mode: int = None, combine: bool = False, avoid_run_breaks: bool = False, width: int = None, height: int = None, maxrunerror: float = 0, maxmotionerror: float = 0, verbose: bool = False, useadvancedquant: bool = True, dither_mode: str = "fs"):
     frametiming = None
     bakedpal = None
     dim = False
@@ -1276,7 +1269,7 @@ def encode(img: bytes | Image.Image, lineskip: int = None, findbestlineskip: boo
     if legacy and not find_bgfg:
         img, frametiming = reduce_to_apf_in_apf2_quality(img, animated)
     elif not truecolor and not gray:
-        img, palette, frametiming, trans = reduce_to_apf2_quality(img, pal, animated, trans, bakedpal, dodithering)
+        img, palette, frametiming, trans = reduce_to_apf2_quality(img, pal, animated, trans, bakedpal, dodithering, useadvancedquant, dither_mode, verbose)
     else:
         img, frametiming = slice_frames(img, animated, trans)
 
@@ -1427,16 +1420,20 @@ def encode(img: bytes | Image.Image, lineskip: int = None, findbestlineskip: boo
 
         for lsk in range(lineskip):
             lsk+=1
-            output, apf2pal = encode_wrapper(legacy, bitmaps, gray, truecolor, lsk, w, h, topside_first, bg, trans, avoid_run_breaks, transmag, mode, combine, palette, dim, prepalette, compress)
+            if verbose:
+                print(f"trying lineskip = {lsk}")
+            output, apf2pal = encode_wrapper(legacy, bitmaps, gray, truecolor, lsk, w, h, topside_first, bg, trans, avoid_run_breaks, transmag, mode, combine, palette, dim, prepalette, compress, verbose, maxmotionerror, maxrunerror)
             all_outputs[str(lsk)] = output
         for lsk in all_outputs:
             if outsize > len(all_outputs[lsk])+len(lsk):
                 output = all_outputs[lsk]
                 outsize = len(all_outputs[lsk])+len(lsk)
                 lineskip = int(lsk)
+            if verbose:
+                print(f"Smallest: {lineskip}")
         metadata.append(str(lineskip))
     else:
-        output, apf2pal = encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_first, bg, trans, avoid_run_breaks, transmag, mode, combine, palette, dim, prepalette, compress)
+        output, apf2pal = encode_wrapper(legacy, bitmaps, gray, truecolor, lineskip, w, h, topside_first, bg, trans, avoid_run_breaks, transmag, mode, combine, palette, dim, prepalette, compress, verbose, maxmotionerror, maxrunerror)
 
 
     if desc or frametiming:
@@ -1468,6 +1465,17 @@ def encode(img: bytes | Image.Image, lineskip: int = None, findbestlineskip: boo
 
     apflist.append(output)
     apftext = "\n".join(apflist)
+
+    if verbose:
+        if uses2000extensions:
+            version = 2000
+        elif uses1994extensions:
+            version = 1994
+        else:
+            version = 1993
+        print(f"APF2 Version: {version}")
+        print(f"APF2 Header Line: {apflist[1]}")
+
     if returnbytes:
         return apftext.encode()
     else:

apftool-1.2.0/apftool/apf2quant.py

@@ -0,0 +1,236 @@
+# This code was generated by Claude
+"""
+Perceptual palette quantizer: drop-in upgrade for quantize_most_frequent_sk.
+
+Pipeline
+  1. Collapse the image to its unique RGBA colors + pixel counts (fast, and makes
+     everything frequency-weighted for free).
+  2. Convert to Oklab so distances approximate perceived difference.
+  3. Seed a palette with weighted median-cut (splits the box with the largest
+     weighted squared error), then refine with a few weighted Lloyd iterations.
+     If the image has <= n_colors unique colors the palette is exact (lossless).
+  4. Optionally order the palette for index locality (helps RLE / delta coding).
+  5. Map pixels with a KD-tree in Oklab, with optional dithering:
+       - "ordered": Bayer matrix, fully vectorised, run-friendly
+       - "fs":      serpentine Floyd-Steinberg in Oklab with error clamping
+"""
+import heapq
+
+import numpy as np
+from PIL import Image
+from scipy.spatial import cKDTree
+
+# ---------------------------------------------------------------- Oklab ----
+_M1 = np.array([[0.4122214708, 0.5363325363, 0.0514459929],
+                [0.2119034982, 0.6806995451, 0.1073969566],
+                [0.0883024619, 0.2817188376, 0.6299787005]])
+_M2 = np.array([[0.2104542553, 0.7936177850, -0.0040720468],
+                [1.9779984951, -2.4285922050, 0.4505937099],
+                [0.0259040371, 0.7827717662, -0.8086757660]])
+_M1_INV = np.linalg.inv(_M1)
+_M2_INV = np.linalg.inv(_M2)
+
+
+def _srgb_to_oklab(rgb_u8):
+    c = rgb_u8.astype(np.float64) / 255.0
+    lin = np.where(c <= 0.04045, c / 12.92, ((c + 0.055) / 1.055) ** 2.4)
+    lms = np.cbrt(lin @ _M1.T)
+    return lms @ _M2.T
+
+
+def _oklab_to_srgb(lab):
+    lms = (lab @ _M2_INV.T) ** 3
+    lin = np.clip(lms @ _M1_INV.T, 0.0, 1.0)
+    c = np.where(lin <= 0.0031308, lin * 12.92, 1.055 * lin ** (1 / 2.4) - 0.055)
+    return np.clip(np.rint(c * 255.0), 0, 255).astype(np.uint8)
+
+
+def _to_features(rgba, wvec):
+    """RGBA uint8 (N,4) -> weighted [L, a, b, alpha] float64 (N,4)."""
+    lab = _srgb_to_oklab(rgba[:, :3])
+    lab[rgba[:, 3] == 0] = 0.0  # colour of fully transparent pixels is meaningless
+    feat = np.empty((len(rgba), 4), dtype=np.float64)
+    feat[:, :3] = lab
+    feat[:, 3] = rgba[:, 3] / 255.0
+    return feat * wvec
+
+
+def _from_features(feat, wvec):
+    f = feat / wvec
+    rgba = np.empty((len(f), 4), dtype=np.uint8)
+    rgba[:, :3] = _oklab_to_srgb(f[:, :3])
+    rgba[:, 3] = np.clip(np.rint(f[:, 3] * 255.0), 0, 255).astype(np.uint8)
+    return rgba
+
+
+# ------------------------------------------------------ palette building ----
+def _median_cut(pts, w, k):
+    """Weighted median cut; always splits the box with the largest SSE."""
+    def stats(idx):
+        bw, bp = w[idx], pts[idx]
+        mean = (bp * bw[:, None]).sum(0) / bw.sum()
+        return (((bp - mean) ** 2) * bw[:, None]).sum(0)
+
+    heap, done, n = [], [], 0
+    root = np.arange(len(pts))
+    var = stats(root)
+    heapq.heappush(heap, (-var.sum(), n, root, var))
+    while heap and len(heap) + len(done) < k:
+        _, _, idx, var = heapq.heappop(heap)
+        if len(idx) < 2:
+            done.append(idx)
+            continue
+        axis = int(np.argmax(var))
+        order = idx[np.argsort(pts[idx, axis], kind="stable")]
+        cw = np.cumsum(w[order])
+        s = int(np.searchsorted(cw, cw[-1] / 2)) + 1
+        s = min(max(s, 1), len(order) - 1)
+        for part in (order[:s], order[s:]):
+            n += 1
+            v = stats(part)
+            heapq.heappush(heap, (-v.sum(), n, part, v))
+    boxes = [h[2] for h in heap] + done
+    return np.stack([(pts[b] * w[b, None]).sum(0) / w[b].sum() for b in boxes])
+
+
+def _lloyd(pts, w, centers, iters):
+    k = len(centers)
+    for _ in range(iters):
+        _, lab = cKDTree(centers).query(pts, workers=-1)
+        ws = np.bincount(lab, weights=w, minlength=k)
+        new = np.stack([np.bincount(lab, weights=w * pts[:, d], minlength=k)
+                        for d in range(pts.shape[1])], axis=1)
+        m = ws > 0
+        centers[m] = new[m] / ws[m, None]
+    return centers
+
+
+def _locality_order(feat):
+    """Order palette so neighbouring indices are perceptually close:
+    lightness bands, then hue sweeps alternating direction per band."""
+    n = len(feat)
+    bands = max(1, int(np.sqrt(n) / 2))
+    rank = np.empty(n, dtype=np.int64)
+    rank[np.argsort(feat[:, 0], kind="stable")] = np.arange(n)
+    band = rank * bands // n
+    hue = np.arctan2(feat[:, 2], feat[:, 1])
+    hue = np.where(band % 2 == 0, hue, -hue)
+    return np.lexsort((hue, band))
+
+
+# --------------------------------------------------------------- dithering --
+def _bayer(n):
+    m = np.array([[0]])
+    while m.shape[0] < n:
+        m = np.block([[4 * m, 4 * m + 2], [4 * m + 3, 4 * m + 1]])
+    return (m + 0.5) / (n * n) - 0.5  # centred on 0, range (-0.5, 0.5)
+
+
+def _palette_spacing(pal_feat):
+    """Median nearest-neighbour distance between palette entries (colour axes)."""
+    if len(pal_feat) < 2:
+        return 0.0
+    d, _ = cKDTree(pal_feat[:, :3]).query(pal_feat[:, :3], k=2)
+    return float(np.median(d[:, 1]))
+
+
+# --------------------------------------------------------------- public API --
+def quantize_perceptual(img: Image.Image, n_colors: int, palette: list = None,
+                        dither: bool = False, *, dither_mode: str = "ordered",
+                        dither_strength: float = 0.8, kmeans_iters: int = 6,
+                        lightness_weight: float = 1.0, alpha_weight: float = 1.0,
+                        sort_palette: bool = True):
+    """Returns (RGBA PIL image, palette as list of (r,g,b,a) tuples).
+
+    palette          fixed palette; skips palette generation (and sorting)
+    dither_mode      "ordered" (Bayer, run-friendly) or "fs" (Floyd-Steinberg)
+    dither_strength  0..1+, scales the dither amplitude / diffused error
+    lightness_weight >1 spends more palette on luminance detail
+    alpha_weight     how much alpha differences count versus colour
+    """
+    img = img.convert("RGBA")
+    arr = np.ascontiguousarray(np.array(img, dtype=np.uint8))
+    h, w = arr.shape[:2]
+    flat = arr.reshape(-1, 4)
+    wvec = np.array([lightness_weight, 1.0, 1.0, alpha_weight])
+
+    # unique colours + counts
+    packed = flat.view(np.uint32).ravel()
+    uniq, inv, counts = np.unique(packed, return_inverse=True, return_counts=True)
+    inv = inv.ravel()
+    uniq_rgba = np.ascontiguousarray(uniq).view(np.uint8).reshape(-1, 4)
+    uniq_feat = _to_features(uniq_rgba, wvec)
+
+    # palette
+    if palette is not None:
+        pal_rgba = np.array(palette, dtype=np.uint8)
+        if pal_rgba.shape[1] == 3:
+            pal_rgba = np.concatenate(
+                [pal_rgba, np.full((len(pal_rgba), 1), 255, np.uint8)], axis=1)
+    elif len(uniq_rgba) <= n_colors:
+        pal_rgba = uniq_rgba.copy()
+    else:
+        cnt = counts.astype(np.float64)
+        centers = _median_cut(uniq_feat, cnt, n_colors)
+        centers = _lloyd(uniq_feat, cnt, centers, kmeans_iters)
+        pal_rgba = _from_features(centers, wvec)
+    pal_feat = _to_features(pal_rgba, wvec)  # use the *actual* 8-bit palette
+    if palette is None and sort_palette:
+        order = _locality_order(pal_feat)
+        pal_rgba, pal_feat = pal_rgba[order], pal_feat[order]
+
+    tree = cKDTree(pal_feat)
+    _, base_u = tree.query(uniq_feat, workers=-1)
+    base_idx = base_u[inv]  # plain nearest-colour index per pixel
+
+    if not dither or len(pal_rgba) < 2:
+        idx = base_idx
+    else:
+        spacing = _palette_spacing(pal_feat)
+        feat_all = uniq_feat[inv]  # (N,4)
+        opaque = flat[:, 3] > 0
+
+        if dither_mode == "ordered":
+            tile = _bayer(8)
+            thr = np.tile(tile, (h // 8 + 1, w // 8 + 1))[:h, :w].reshape(-1)
+            shifted = feat_all.copy()
+            # thr spans (-0.5, 0.5); nearest-neighbour spacing underestimates the
+            # real cell width in a sparse 3D palette, so scale by 2 (+/- 1 step at 1.0)
+            shifted[:, :3] += (thr * 2.0 * spacing * dither_strength)[:, None]
+            _, idx = tree.query(shifted, workers=-1)
+            idx = np.where(opaque, idx, base_idx)
+
+        elif dither_mode == "fs":
+            buf = feat_all.reshape(h, w, 4).copy()
+            opq = opaque.reshape(h, w)
+            base2d = base_idx.reshape(h, w)
+            out = np.empty((h, w), dtype=np.int64)
+            lim = spacing  # clamp so error cannot snowball past one palette step
+            for y in range(h):
+                ltr = (y % 2 == 0)
+                xs = range(w) if ltr else range(w - 1, -1, -1)
+                dx = 1 if ltr else -1
+                for x in xs:
+                    if not opq[y, x]:
+                        out[y, x] = base2d[y, x]
+                        continue
+                    old = buf[y, x]
+                    _, i = tree.query(old)
+                    out[y, x] = i
+                    err = np.clip(old[:3] - pal_feat[i, :3], -lim, lim) * dither_strength
+                    xn = x + dx
+                    if 0 <= xn < w:
+                        buf[y, xn, :3] += err * (7 / 16)
+                    if y + 1 < h:
+                        xb = x - dx
+                        if 0 <= xb < w:
+                            buf[y + 1, xb, :3] += err * (3 / 16)
+                        buf[y + 1, x, :3] += err * (5 / 16)
+                        if 0 <= xn < w:
+                            buf[y + 1, xn, :3] += err * (1 / 16)
+            idx = out.reshape(-1)
+        else:
+            raise ValueError("dither_mode must be 'ordered' or 'fs'")
+
+    quantized = pal_rgba[idx].reshape(h, w, 4)
+    return Image.fromarray(quantized, "RGBA"), [tuple(int(v) for v in c) for c in pal_rgba]

{apftool-1.1.3 → apftool-1.2.0}/apftool/apfcli.py

@@ -21,17 +21,22 @@ encoding:
 --lineskip=INT - (APF/APF2) how many lines are skipped in progressive scanning. (default is 1)
 --findbestlineskip - (APF/APF2) finds the lineskip value with the smallest file size. (APF2) search is limited to supplied lineskip argument (default is 10)
 
---desc=STR - (APF2) file description
+--desc=STR - (APF2) file description [Alias: -D=STR]
 --legacy - (APF2) use bi-level runs
 --transparent - (APF2) alias for --transmode=1
---transmode=INT - (APF2) sets transparency mode. 0 is off, 1 is index 0 is 00000000, 2 is 8-bit alpha in palette
+--transmode=INT - (APF2) sets transparency mode. 0 is off, 1 is index 0 is 00000000, 2 is 8-bit alpha in palette [Alias: -T=INT]
 --palette=INT - (APF2) sets max colors. 2 will use legacy + bg.fg, >95 will use dual-indexed mode. 9025 is max.
---dither - (APF2) enables dithering (off by default outside of legacy)
+--dither - (APF2) enables dithering (off by default outside of legacy) [Alias: -D]
 --topdown - (APF2) reverses scan order
 --uncompressed - (APF2) disables RLE (not applicable for legacy mode)
---combine - (APF2) apply cross-frame compression. Implicitly sets transmode to 1, except for mode 3 where it uses FE00FE as transparency. Unsupported on legacy.
---avoidrunbreaks - (APF2) avoid breaking runs on combine mode. May improve or harm efficiency.
---mode=INT - (APF2) color mode (specified in A2K) for APF2.
+--combine - (APF2) apply cross-frame compression. Implicitly sets transmode to 1, except for mode 3 where it uses FE00FE as transparency. Unsupported on legacy. [Alias: -C]
+--avoidrunbreaks - (APF2) avoid breaking runs on combine mode. May improve or harm efficiency (usually harm, as it is not tuned).
+--run-quality=INT - (APF2) (0 to 100) allows for lossy RLE compression
+--motion-quality=INT - (APF2) (0 to 100) allows for lossy motion compression (for --combine)
+--quality=INT - (APF2) (0 to 100) sets both --run-quality and --motion-quality [Alias: -Q=INT]
+--pillow - (APF2) use pillow's quantizer [Alias: -P]
+--bayer - (APF2) use faster bayer/ordered dithering for perceptual mode instead of the slower, but prettier floyd-steinberg
+--mode=INT - (APF2) color mode (specified in A2K) for APF2. [Alias: -M=INT]
     0 - 2 colors
     1 - 95 colors
     2 - 9025 colors
@@ -42,8 +47,8 @@ encoding:
     7 - Mode 1-based Grayscale
     8 - Mode 2-based Grayscale
 
---width - (OTB/APF2) sets width (default is 255)
---height - (OTB/APF2) sets height (default is 255)
+--width - (OTB/APF2) sets width (default is 255 for OTB, no scaling for APF2) [Alias: -W=INT]
+--height - (OTB/APF2) sets height (default is 255 for OTB, no scaling for APF2) [Alias: -H=INT]
 
 --transcolor - (MQIF) sets color to be made transparent (default is None)
 
@@ -82,6 +87,10 @@ TODO: MQIF encoding
     mode = None
     combine = False
     avoid_run_breaks = False
+    maxmotionerror = 0
+    maxrunerror = 0
+    useadvancedquant = True
+    dither_mode = "fs"
     if args:
         if "--findbestlineskip" in args:
             fbls = True
@@ -89,35 +98,57 @@ TODO: MQIF encoding
             legacy = True
         if "--transparent" in args:
             trans = 1
-        if "--dither" in args:
+        if "--dither" in args or "-D" in args:
             dither = True
         if "--topdown" in args:
             flip = True
         if "--uncompressed" in args:
             compress = False
-        if "--combine" in args:
+        if "--combine" in args or "-C" in args:
             combine = True
         if "--magenta" in args:
             magenta = True
         if "--avoidrunbreaks" in args:
             avoid_run_breaks = True
+        if "--pillow" in args or "-P" in args:
+            useadvancedquant = False
+        if "--bayer" in args:
+            dither_mode = "ordered"
         for arg in args:
-            if arg.startswith("--desc="):
-                description = arg.replace("--desc=", "")
+            if arg.startswith("--desc=") or arg.startswith("-D="):
+                description = arg.replace("--desc=", "").replace("-D=", "")
             if arg.startswith("--format="):
                 forma = arg.replace("--format=", "")
-            if arg.startswith("--transmode="):
-                trans = int(arg.replace("--transmode=", ""))
+            if arg.startswith("--transmode=") or arg.startswith("-T="):
+                trans = int(arg.replace("--transmode=", "").replace("-T=", ""))
             if arg.startswith("--palette="):
                 maxpalette = int(arg.replace("--palette=", ""))
             if arg.startswith("--lineskip="):
                 lineskip = int(arg.replace("--lineskip=", ""))
-            if arg.startswith("--width="):
-                wid = int(arg.replace("--width=", ""))
-            if arg.startswith("--height="):
-                hei = int(arg.replace("--height=", ""))
+
+            if arg.startswith("--width=") or arg.startswith("-W="):
+                wid = int(arg.replace("--width=", "").replace("-W=", ""))
+            if arg.startswith("--height=") or arg.startswith("-H="):
+                hei = int(arg.replace("--height=", "").replace("-H=", ""))
+
             if arg.startswith("--mode="):
                 mode = int(arg.replace("--mode=", ""))
+            if arg.startswith("-M="):
+                mode = int(arg.replace("-M=", ""))
+
+            if arg.startswith("--quality=") or arg.startswith("-Q="):
+                qual = int(arg.replace("--quality=", "").replace("-Q=", ""))/2
+                maxmotionerror = 50-qual
+                maxrunerror = maxmotionerror
+
+            if arg.startswith("--run-quality="):
+                qual = int(arg.replace("--run-quality=", ""))/2
+                maxrunerror = 50-qual
+
+            if arg.startswith("--motion-quality="):
+                qual = int(arg.replace("--motion-quality=", ""))/2
+                maxmotionerror = 50-qual
+
             if arg.startswith("--transcolor="):
                 transcolor_hex = arg.replace("--transcolor=", "").replace("#", "")
                 tcr = int(transcolor_hex[0:2], 16)
@@ -133,9 +164,29 @@ TODO: MQIF encoding
                 maxpalette = 95
                 mode = 6 if trans == 2 else 5
 
+    assert maxrunerror >= 0, f"Quality cannot be above 100 (got {maxrunerror})"
+    assert maxmotionerror >= 0, f"Quality cannot be above 100 (got {maxrunerror})"
+
+    res = f"Converting {input_path} to {output_path}..."
+    if opext in apftool.extensions_apf2:
+        md = mode
+        if not md:
+            if legacy:
+                md = 0
+            elif maxpalette > 95:
+                md = 2
+            else:
+                md = 1
+        res+= f" [Max Run Error: {maxrunerror}, Max Motion Error: {maxmotionerror}, Mode {md}]"
+    print(res)
+
     # PNG to APF/APF2
-    if ext in supported_extensions:
-        img_bytes = Image.open(input_path)
+    if opext in apftool.extensions_all:
+        if ext in supported_extensions:
+            img_bytes = Image.open(input_path)
+        else:
+            with open(input_path, "rb") as f:
+                img_bytes = apftool.decode(f.read(), forma)
 
         if opext in apftool.extensions_apf:
             encoded = apftool.apf.encode(img_bytes, lineskip=lineskip, findbestlineskip=fbls)
@@ -153,7 +204,7 @@ TODO: MQIF encoding
             encoded = apftool.mqif.encode(img_bytes, transcolor)
 
         elif opext in apftool.extensions_apf2:
-            encoded = apftool.apf2.encode(img_bytes, lineskip=lineskip, findbestlineskip=fbls, legacy=legacy, trans=trans, pal=maxpalette, desc=description, prepalette= None, dodithering=dither, returnbytes=True, compress=compress, topside_first=flip, mode=mode, combine=combine, avoid_run_breaks=avoid_run_breaks, width=wid, height=hei)
+            encoded = apftool.apf2.encode(img_bytes, lineskip=lineskip, findbestlineskip=fbls, legacy=legacy, trans=trans, pal=maxpalette, desc=description, prepalette= None, dodithering=dither, returnbytes=True, compress=compress, topside_first=flip, mode=mode, combine=combine, avoid_run_breaks=avoid_run_breaks, width=wid, height=hei, maxrunerror = maxrunerror, maxmotionerror = maxmotionerror, verbose = True, useadvancedquant=useadvancedquant, dither_mode=dither_mode)
 
         else:
             raise ValueError("Unsupported Image Format!")
@@ -162,7 +213,7 @@ TODO: MQIF encoding
         print(f"Encoded {input_path} -> {output_path}")
 
     # APF/APF2 to PNG
-    elif ext in apftool.extensions_all:
+    elif opext in supported_extensions:
         with open(input_path, "rb") as f:
             apf_content = f.read()
         decoded_bytes = apftool.decode(apf_content, forma)

{apftool-1.1.3 → apftool-1.2.0}/apftool.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apftool
-Version: 1.1.3
+Version: 1.2.0
 Summary: Encoder and decoder for Aperture Science Image Format (apf), Aperture Science Image Format 2 (apf2), Wireless Bitmap (wbmp), Over-The-Air Bitmap (otb), and FaceDev's .bruh format
 Author: Mari (kbity)
 Requires-Python: >=3.10
@@ -96,10 +96,12 @@ apftool provides many extensions tuples:
 
 `PIL (pillow)` is required
 
-`numpy` and `scikit-learn` are needed for high-speed APF2-1994 257+ Color Encoding, if missing the code will use a very slow fallback.
+`numpy` and `scipy` are needed for high-quality, high-speed APF2 encoding, if missing the code will use a very slow and low quality fallback.
 
 ## changelog:
 
+1.2.0 - increase apfcli verbosity, add lossy encoding options. Allow apfcli to take its own formats as inputs and outputs, also adds a much better quantization algorithm and removes the limitations on indexed animations.
+
 1.1.3 - add version field, add width and height options to apf2 encoding
 
 1.1.2 - fix apftool

{apftool-1.1.3 → apftool-1.2.0}/apftool.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ setup.cfg
 apftool/__init__.py
 apftool/apf.py
 apftool/apf2.py
+apftool/apf2quant.py
 apftool/apfcli.py
 apftool/bittools.py
 apftool/bruh.py

{apftool-1.1.3 → apftool-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "apftool"
-version = "1.1.3"
+version = "1.2.0"
 description = "Encoder and decoder for Aperture Science Image Format (apf), Aperture Science Image Format 2 (apf2), Wireless Bitmap (wbmp), Over-The-Air Bitmap (otb), and FaceDev's .bruh format"
 authors = [{name = "Mari (kbity)"}]
 readme = "README.md"