Create app.py

app.py

@@ -0,0 +1,831 @@
+# ============================================================
+# FLC v1.3 — Standalone Fibonacci Lattice Compression
+#   + Real .flc file format (v2 header)
+#   + Hologram preview PNG
+#   + "Holographic Unzip" progressive GIF (REAL partial reconstructions)
+#   + max_bands horizon control
+#   + Fibonacci spiral unfold layout (right panel)
+#   + NEW: Event-horizon ring overlay (left panel)
+#   + NEW: Fibonacci tile outlines (right panel)
+#
+# Notebook usage:
+#   enc = flc_encode_file("in.bin","out.flc","preview.png", unzip_gif="unzip.gif",
+#                         block_len=1024, n_bands=10, base_step=0.004)
+#   dec = flc_decode_file("out.flc","recovered.bin", unzip_gif="decode_unzip.gif", max_bands=None)
+#
+# Partial/horizon:
+#   decp = flc_decode_file("out.flc","partial.bin", unzip_gif="partial_unzip.gif", max_bands=4)
+#
+# Depends: numpy, pillow
+# ============================================================
+
+import os, struct, math, argparse
+import numpy as np
+from PIL import Image, ImageDraw
+
+PHI = (1.0 + 5.0**0.5) / 2.0
+MAGIC = b"FLC1\x00\x00\x00\x00"  # 8 bytes
+VER_V2 = 2  # float64 params
+
+# --------------------------
+# Fibonacci utilities
+# --------------------------
+def fibonacci_sequence(n):
+    fibs = [1, 2]
+    while len(fibs) < n:
+        fibs.append(fibs[-1] + fibs[-2])
+    return np.array(fibs[:n], dtype=np.int64)
+
+def fibonacci_sequence_std(n):
+    fibs = [1, 1]
+    while len(fibs) < n:
+        fibs.append(fibs[-1] + fibs[-2])
+    return np.array(fibs[:n], dtype=np.int64)
+
+def fibonacci_frequency_boundaries(n_coeffs: int, n_bands: int):
+    """
+    Strict: returns exactly n_bands+1 boundaries => exactly n_bands intervals.
+    Deterministic repair enforces strict monotone boundaries.
+    """
+    if n_bands < 2:
+        return [0, n_coeffs]
+
+    fibs = fibonacci_sequence(n_bands).astype(np.float64)
+    w = fibs / (fibs.sum() + 1e-12)
+    cum = np.cumsum(w)
+
+    b = [0]
+    for i in range(n_bands - 1):
+        bi = int(round(n_coeffs * cum[i]))
+        b.append(bi)
+    b.append(n_coeffs)
+
+    b = [max(0, min(n_coeffs, int(x))) for x in b]
+    b[0] = 0
+    b[-1] = n_coeffs
+
+    # strictify forward
+    for i in range(1, len(b) - 1):
+        if b[i] <= b[i-1]:
+            b[i] = b[i-1] + 1
+    # strictify backward
+    for i in range(len(b) - 2, 0, -1):
+        if b[i] >= b[i+1]:
+            b[i] = b[i+1] - 1
+
+    # remove invalid interior points
+    b = [0] + [x for x in b[1:-1] if 0 < x < n_coeffs] + [n_coeffs]
+
+    # repack if we lost points (n_coeffs small or rounding)
+    while len(b) < n_bands + 1:
+        gaps = [(b[i+1] - b[i], i) for i in range(len(b) - 1)]
+        gaps.sort(reverse=True)
+        _, gi = gaps[0]
+        mid = (b[gi] + b[gi+1]) // 2
+        if mid == b[gi] or mid == b[gi+1]:
+            break
+        b.insert(gi+1, mid)
+
+    # trim if we have too many
+    while len(b) > n_bands + 1:
+        gaps = [(b[i+1] - b[i], i) for i in range(len(b) - 1)]
+        gaps.sort()  # smallest first
+        _, gi = gaps[0]
+        if 0 < gi+1 < len(b)-1:
+            b.pop(gi+1)
+        else:
+            break
+
+    return b
+
+# --------------------------
+# Orthonormal DCT-II / IDCT (no scipy)
+# --------------------------
+def dct_ortho_1d(x: np.ndarray) -> np.ndarray:
+    x = np.asarray(x, dtype=np.float64)
+    N = x.shape[0]
+    v = np.concatenate([x, x[::-1]])
+    V = np.fft.fft(v)
+    k = np.arange(N)
+    X = np.real(V[:N] * np.exp(-1j * np.pi * k / (2 * N)))
+    X *= 2.0
+    X[0] *= (1.0 / math.sqrt(4 * N))
+    X[1:] *= (1.0 / math.sqrt(2 * N))
+    return X
+
+def idct_ortho_1d(X: np.ndarray) -> np.ndarray:
+    X = np.asarray(X, dtype=np.float64)
+    N = X.shape[0]
+    x = X.copy()
+
+    x0 = x[0] * math.sqrt(4 * N)
+    xr = x[1:] * math.sqrt(2 * N)
+    c = np.empty(N, dtype=np.complex128)
+    c[0] = x0 / 2.0
+    c[1:] = xr / 2.0
+
+    k = np.arange(N)
+    c = c * np.exp(1j * np.pi * k / (2 * N))
+
+    V = np.zeros(2 * N, dtype=np.complex128)
+    V[:N] = c
+    V[N+1:] = np.conj(c[1:][::-1])
+    v = np.fft.ifft(V).real
+    return v[:N]
+
+def dct_blocks_ortho(x_blocks: np.ndarray) -> np.ndarray:
+    B, L = x_blocks.shape
+    out = np.empty((B, L), dtype=np.float64)
+    for i in range(B):
+        out[i] = dct_ortho_1d(x_blocks[i])
+    return out
+
+def idct_blocks_ortho(X_blocks: np.ndarray) -> np.ndarray:
+    B, L = X_blocks.shape
+    out = np.empty((B, L), dtype=np.float64)
+    for i in range(B):
+        out[i] = idct_ortho_1d(X_blocks[i])
+    return out
+
+# --------------------------
+# Bit IO
+# --------------------------
+class BitWriter:
+    def __init__(self):
+        self.buf = bytearray()
+        self.acc = 0
+        self.nbits = 0
+
+    def write_bit(self, b: int):
+        self.acc = (self.acc << 1) | (b & 1)
+        self.nbits += 1
+        if self.nbits == 8:
+            self.buf.append(self.acc & 0xFF)
+            self.acc = 0
+            self.nbits = 0
+
+    def finish(self) -> bytes:
+        if self.nbits:
+            self.acc <<= (8 - self.nbits)
+            self.buf.append(self.acc & 0xFF)
+            self.acc = 0
+            self.nbits = 0
+        return bytes(self.buf)
+
+class BitReader:
+    def __init__(self, data: bytes):
+        self.data = data
+        self.i = 0
+        self.acc = 0
+        self.nbits = 0
+
+    def read_bit(self) -> int:
+        if self.nbits == 0:
+            if self.i >= len(self.data):
+                raise EOFError("BitReader EOF")
+            self.acc = self.data[self.i]
+            self.i += 1
+            self.nbits = 8
+        b = (self.acc >> (self.nbits - 1)) & 1
+        self.nbits -= 1
+        return b
+
+# --------------------------
+# Fibonacci coding
+# --------------------------
+def _fib_numbers_upto(n: int):
+    fibs = [1, 2]
+    while fibs[-1] <= n:
+        fibs.append(fibs[-1] + fibs[-2])
+    return fibs
+
+def fib_encode_nonneg(bw: BitWriter, n: int):
+    m = int(n) + 1
+    fibs = _fib_numbers_upto(m)
+    bits = [0] * (len(fibs) - 1)
+    rem = m
+    for i in reversed(range(len(bits))):
+        f = fibs[i]
+        if f <= rem:
+            bits[i] = 1
+            rem -= f
+    hi = max((i for i, b in enumerate(bits) if b), default=0)
+    for i in range(hi + 1):
+        bw.write_bit(bits[i])
+    bw.write_bit(1)
+
+def fib_decode_nonneg(br: BitReader) -> int:
+    fibs = [1, 2]
+    bits = []
+    prev = 0
+    while True:
+        b = br.read_bit()
+        bits.append(b)
+        if prev == 1 and b == 1:
+            break
+        prev = b
+        if len(bits) > len(fibs):
+            fibs.append(fibs[-1] + fibs[-2])
+    payload = bits[:-1]
+    while len(fibs) < len(payload):
+        fibs.append(fibs[-1] + fibs[-2])
+    m = 0
+    for i, bi in enumerate(payload):
+        if bi:
+            m += fibs[i]
+    return m - 1
+
+def zigzag_encode_i64(x: int) -> int:
+    x = int(x)
+    return (x << 1) ^ (x >> 63)
+
+def zigzag_decode_i64(u: int) -> int:
+    u = int(u)
+    return (u >> 1) ^ (-(u & 1))
+
+def rle_fib_encode_ints(ints: np.ndarray) -> bytes:
+    bw = BitWriter()
+    ints = ints.astype(np.int64, copy=False)
+    zrun = 0
+    for v in ints:
+        if v == 0:
+            zrun += 1
+            continue
+        if zrun:
+            bw.write_bit(0)
+            fib_encode_nonneg(bw, zrun)
+            zrun = 0
+        bw.write_bit(1)
+        fib_encode_nonneg(bw, zigzag_encode_i64(int(v)))
+    if zrun:
+        bw.write_bit(0)
+        fib_encode_nonneg(bw, zrun)
+    return bw.finish()
+
+def rle_fib_decode_ints(payload: bytes, n_out: int) -> np.ndarray:
+    br = BitReader(payload)
+    out = np.zeros(n_out, dtype=np.int64)
+    i = 0
+    while i < n_out:
+        tag = br.read_bit()
+        if tag == 0:
+            k = fib_decode_nonneg(br)
+            i = min(n_out, i + k)
+        else:
+            u = fib_decode_nonneg(br)
+            out[i] = zigzag_decode_i64(u)
+            i += 1
+    return out
+
+def delta1d(x: np.ndarray) -> np.ndarray:
+    x = x.astype(np.int64, copy=False)
+    out = np.empty_like(x, dtype=np.int64)
+    prev = 0
+    for i, v in enumerate(x):
+        out[i] = int(v) - prev
+        prev = int(v)
+    return out
+
+def inv_delta1d(d: np.ndarray) -> np.ndarray:
+    d = d.astype(np.int64, copy=False)
+    out = np.empty_like(d, dtype=np.int64)
+    acc = 0
+    for i, v in enumerate(d):
+        acc += int(v)
+        out[i] = acc
+    return out
+
+# --------------------------
+# φ-scaled band quantization
+# --------------------------
+def band_quantize_dct(coeffs: np.ndarray, boundaries, base_step: float, phi: float = PHI):
+    B, L = coeffs.shape
+    q = np.zeros((B, L), dtype=np.int32)
+    for bi in range(len(boundaries) - 1):
+        a, b = boundaries[bi], boundaries[bi + 1]
+        if a >= b:
+            continue
+        step = base_step * (phi ** bi)
+        q[:, a:b] = np.round(coeffs[:, a:b] / step).astype(np.int32)
+    return q
+
+def band_dequantize_dct(q: np.ndarray, boundaries, base_step: float, phi: float = PHI):
+    B, L = q.shape
+    coeffs = np.zeros((B, L), dtype=np.float64)
+    for bi in range(len(boundaries) - 1):
+        a, b = boundaries[bi], boundaries[bi + 1]
+        if a >= b:
+            continue
+        step = base_step * (phi ** bi)
+        coeffs[:, a:b] = q[:, a:b].astype(np.float64) * step
+    return coeffs
+
+# --------------------------
+# Hologram (left panel) + horizon ring overlay
+# --------------------------
+def choose_fib_grid(n_symbols: int) -> int:
+    N = int(math.ceil(math.sqrt(n_symbols)))
+    fibs = [1, 2]
+    while fibs[-1] < N:
+        fibs.append(fibs[-1] + fibs[-2])
+    return fibs[-1]
+
+def ints_to_constellation(zints: np.ndarray):
+    zints = zints.astype(np.int64)
+    v = np.tanh(zints / 32.0).astype(np.float64)
+    k = np.arange(v.size, dtype=np.float64)
+    golden = 2 * math.pi / (PHI**2)
+    theta = golden * k + 2.0 * math.pi * (v * 0.25)
+    r = 1.0 + 0.35 * np.abs(v)
+    return (r * np.cos(theta) + 1j * r * np.sin(theta)).astype(np.complex64)
+
+def hologram_spectrum_image(zints: np.ndarray, max_symbols: int = 262144):
+    if zints.size > max_symbols:
+        zints = zints[:max_symbols]
+    syms = ints_to_constellation(zints)
+    N = choose_fib_grid(syms.size)
+    total = N * N
+    if syms.size < total:
+        syms = np.pad(syms, (0, total - syms.size), constant_values=(1+0j)).astype(np.complex64)
+    U = syms.reshape(N, N)
+    F = np.fft.fftshift(np.fft.fft2(U))
+    mag = np.log1p(np.abs(F)).astype(np.float32)
+    mag -= mag.min()
+    mag /= (mag.max() + 1e-12)
+    return (mag * 255).astype(np.uint8)
+
+def make_hologram_preview(zints: np.ndarray, out_png: str, max_symbols: int = 262144):
+    img = hologram_spectrum_image(zints, max_symbols=max_symbols)
+    Image.fromarray(img).save(out_png)
+
+def overlay_event_horizon_ring(imL: Image.Image, t: int, T: int):
+    """
+    Draw a glowing event-horizon ring (as 3 concentric ellipses) on the hologram.
+    Radius expands with progress t/T.
+    """
+    W, H = imL.size
+    cx, cy = W // 2, H // 2
+    # start small, expand
+    r0 = int(0.08 * min(W, H))
+    r1 = int((0.45 * min(W, H)) * (t / max(1, T)) + r0)
+
+    rgb = imL.convert("RGB")
+    d = ImageDraw.Draw(rgb)
+
+    # glow: 3 rings
+    for k, alpha in [(0, 255), (3, 170), (6, 90)]:
+        rr = r1 + k
+        bbox = (cx - rr, cy - rr, cx + rr, cy + rr)
+        # gold-ish ring
+        col = (255, 215, 0) if alpha == 255 else (220, 180, 0)
+        d.ellipse(bbox, outline=col, width=2)
+
+    # center dot (singularity hint)
+    d.ellipse((cx-2, cy-2, cx+2, cy+2), fill=(255, 215, 0))
+    return rgb
+
+# --------------------------
+# Fibonacci spiral unfold (right panel) + tile outlines
+# --------------------------
+def fibonacci_spiral_tiles_for_area(n_pixels: int, max_tiles: int = 30):
+    fibs = fibonacci_sequence_std(max_tiles)  # 1,1,2,3,5...
+    sizes = []
+    area = 0
+    for s in fibs:
+        sizes.append(int(s))
+        area += int(s) * int(s)
+        if area >= n_pixels:
+            break
+    return sizes
+
+def fibonacci_spiral_tile_positions(sizes):
+    tiles = []
+    s0 = sizes[0]
+    minx, miny, maxx, maxy = 0, 0, s0, s0
+    tiles.append((0, 0, s0))
+
+    for i in range(1, len(sizes)):
+        s = sizes[i]
+        d = (i - 1) % 4  # right, up, left, down
+        if d == 0:      # right
+            x, y = maxx, miny
+        elif d == 1:    # up
+            x, y = maxx - s, maxy
+        elif d == 2:    # left
+            x, y = minx - s, maxy - s
+        else:           # down
+            x, y = minx, miny - s
+
+        tiles.append((x, y, s))
+        minx = min(minx, x)
+        miny = min(miny, y)
+        maxx = max(maxx, x + s)
+        maxy = max(maxy, y + s)
+
+    bbox = (minx, miny, maxx, maxy)
+    return tiles, bbox
+
+def bytes_to_fib_spiral_image(data: bytes, max_pixels: int = 262144, want_tiles=False):
+    arr = np.frombuffer(data, dtype=np.uint8)
+    if arr.size > max_pixels:
+        arr = arr[:max_pixels]
+    n = int(arr.size)
+    if n == 0:
+        if want_tiles:
+            return np.zeros((1, 1), dtype=np.uint8), [(0,0,1)], (0,0,1,1)
+        return np.zeros((1, 1), dtype=np.uint8)
+
+    sizes = fibonacci_spiral_tiles_for_area(n_pixels=n, max_tiles=32)
+    tiles, (minx, miny, maxx, maxy) = fibonacci_spiral_tile_positions(sizes)
+
+    W = int(maxx - minx)
+    H = int(maxy - miny)
+    img = np.zeros((H, W), dtype=np.uint8)
+    idx = 0
+
+    for (x, y, s) in tiles:
+        if idx >= n:
+            break
+        x0 = int(x - minx)
+        y0_up = int(y - miny)
+        y0 = int((H - (y0_up + s)))
+
+        take = min(s * s, n - idx)
+        block = arr[idx:idx + take]
+        if take < s * s:
+            block = np.pad(block, (0, s * s - take), constant_values=0)
+        block2d = block.reshape(s, s)
+        img[y0:y0+s, x0:x0+s] = block2d
+        idx += take
+
+    if want_tiles:
+        return img, tiles, (minx, miny, maxx, maxy)
+    return img
+
+def overlay_tile_outlines(imL: Image.Image, tiles, bbox_info, outline=(120,120,120)):
+    """
+    Draw square outlines for the Fibonacci tiling on the right panel.
+    `tiles` are in y-up coords with original bbox min offsets.
+    """
+    rgb = imL.convert("RGB")
+    d = ImageDraw.Draw(rgb)
+    # rebuild H,W from image
+    W, H = rgb.size
+
+    # bbox is y-up coords: minx,miny,maxx,maxy
+    minx, miny, maxx, maxy = bbox_info
+    # For each tile, map y-up to y-down in image coords
+    for (x, y, s) in tiles:
+        x0 = int(x - minx)
+        y0_up = int(y - miny)
+        y0 = int((H - (y0_up + s)))
+        d.rectangle((x0, y0, x0 + s - 1, y0 + s - 1), outline=outline, width=1)
+    return rgb
+
+# --------------------------
+# GIF assembly
+# --------------------------
+def save_gif(frames, out_gif: str, duration=90):
+    if not frames:
+        return
+    frames[0].save(out_gif, save_all=True, append_images=frames[1:], duration=duration, loop=0, optimize=True)
+
+def make_unzip_gif_from_Q(Q_full: np.ndarray,
+                          boundaries,
+                          base_step: float,
+                          mu: float,
+                          n_bytes: int,
+                          out_gif: str,
+                          max_bands: int = None,
+                          gif_scale: int = 2,
+                          max_symbols: int = 262144,
+                          max_pixels: int = 262144,
+                          draw_outlines: bool = True,
+                          draw_horizon: bool = True):
+    n_total_bands = len(boundaries) - 1
+    T = n_total_bands if max_bands is None else max(0, min(int(max_bands), n_total_bands))
+    if T == 0:
+        T = 1
+
+    frames = []
+    band_slices = [(boundaries[i], boundaries[i+1]) for i in range(n_total_bands)]
+
+    for t in range(1, T + 1):
+        Q_part = np.zeros_like(Q_full)
+        for bi in range(t):
+            a, b = band_slices[bi]
+            if a < b:
+                Q_part[:, a:b] = Q_full[:, a:b]
+
+        # partial recon bytes
+        C_part = band_dequantize_dct(Q_part, boundaries, base_step=base_step, phi=PHI)
+        X_part = idct_blocks_ortho(C_part)
+        x = X_part.reshape(-1)[:n_bytes]
+        x = (x * 127.5) + float(mu)
+        x = np.clip(np.round(x), 0, 255).astype(np.uint8).tobytes()
+
+        # left hologram
+        qflat = Q_part.reshape(-1).astype(np.int64)
+        holo_u8 = hologram_spectrum_image(qflat, max_symbols=max_symbols)
+        A = Image.fromarray(holo_u8).convert("L")
+        if gif_scale != 1:
+            A = A.resize((A.size[0]*gif_scale, A.size[1]*gif_scale), Image.NEAREST)
+
+        # horizon ring overlay
+        if draw_horizon:
+            A_rgb = overlay_event_horizon_ring(A, t=t, T=T)
+        else:
+            A_rgb = A.convert("RGB")
+
+        # right spiral image
+        field_u8, tiles, bbox_info = bytes_to_fib_spiral_image(x, max_pixels=max_pixels, want_tiles=True)
+        Bimg = Image.fromarray(field_u8).convert("L")
+        if gif_scale != 1:
+            Bimg = Bimg.resize((Bimg.size[0]*gif_scale, Bimg.size[1]*gif_scale), Image.NEAREST)
+
+        if draw_outlines:
+            # scale tile coordinates too (by rendering outlines after scaling)
+            # easiest: draw outlines on scaled image using scaled bbox & tiles
+            # so adjust bbox and tiles by gif_scale
+            minx, miny, maxx, maxy = bbox_info
+            tiles_s = [(x*gif_scale, y*gif_scale, s*gif_scale) for (x,y,s) in tiles]
+            bbox_s = (minx*gif_scale, miny*gif_scale, maxx*gif_scale, maxy*gif_scale)
+            B_rgb = overlay_tile_outlines(Bimg, tiles_s, bbox_s, outline=(120,120,120))
+        else:
+            B_rgb = Bimg.convert("RGB")
+
+        # match heights by padding
+        H = max(A_rgb.size[1], B_rgb.size[1])
+        def pad_to_h_rgb(im, H):
+            if im.size[1] == H:
+                return im
+            canvas = Image.new("RGB", (im.size[0], H), (0,0,0))
+            canvas.paste(im, (0, (H - im.size[1])//2))
+            return canvas
+        A_rgb = pad_to_h_rgb(A_rgb, H)
+        B_rgb = pad_to_h_rgb(B_rgb, H)
+
+        W = A_rgb.size[0]
+        canvas = Image.new("RGB", (W*2, H + 44), (0, 0, 0))
+        canvas.paste(A_rgb, (0, 44))
+        canvas.paste(B_rgb, (W, 44))
+
+        draw = ImageDraw.Draw(canvas)
+        draw.text((12, 10), f"FLC HOLOGRAPHIC UNZIP  |  bands {t}/{T}  (horizon={T})", fill=(255, 215, 0))
+        draw.text((12, 26), "LEFT: hologram + event horizon  |  RIGHT: Fibonacci spiral + tile outlines", fill=(180, 180, 180))
+        frames.append(canvas)
+
+    save_gif(frames, out_gif, duration=90)
+
+# ============================================================
+# Encoder / Decoder
+# ============================================================
+def flc_encode_file(in_path: str,
+                    out_flc: str,
+                    preview_png: str = None,
+                    unzip_gif: str = None,
+                    block_len: int = 1024,
+                    n_bands: int = 10,
+                    base_step: float = 0.004,
+                    use_mean_center: bool = True,
+                    gif_scale: int = 2,
+                    gif_horizon: int = None,
+                    draw_horizon: bool = True,
+                    draw_outlines: bool = True):
+    raw = open(in_path, "rb").read()
+    n_bytes = len(raw)
+
+    x = np.frombuffer(raw, dtype=np.uint8).astype(np.float64)
+    mu = float(np.mean(x)) if use_mean_center else 127.5
+    x = (x - mu) / 127.5
+
+    pad = (-x.size) % block_len
+    if pad:
+        x = np.pad(x, (0, pad), constant_values=0.0)
+    n_blocks = x.size // block_len
+    X = x.reshape(n_blocks, block_len)
+
+    C = dct_blocks_ortho(X)
+    boundaries = fibonacci_frequency_boundaries(block_len, n_bands)
+    Q = band_quantize_dct(C, boundaries, base_step=base_step, phi=PHI)
+
+    q_flat = Q.reshape(-1).astype(np.int64)
+    d = delta1d(q_flat)
+    payload = rle_fib_encode_ints(d)
+
+    header = struct.pack(
+        "<8sH Q I I H d d H",
+        MAGIC, VER_V2,
+        int(n_bytes),
+        int(block_len),
+        int(n_blocks),
+        int(n_bands),
+        float(base_step),
+        float(mu),
+        int(len(boundaries)),
+    )
+    bnds = struct.pack("<" + "I"*len(boundaries), *[int(b) for b in boundaries])
+    paylen = struct.pack("<I", int(len(payload)))
+
+    with open(out_flc, "wb") as f:
+        f.write(header)
+        f.write(bnds)
+        f.write(paylen)
+        f.write(payload)
+
+    if preview_png is not None:
+        make_hologram_preview(q_flat, preview_png)
+
+    if unzip_gif is not None:
+        make_unzip_gif_from_Q(
+            Q_full=Q,
+            boundaries=boundaries,
+            base_step=float(base_step),
+            mu=float(mu),
+            n_bytes=int(n_bytes),
+            out_gif=unzip_gif,
+            max_bands=gif_horizon,
+            gif_scale=gif_scale,
+            draw_horizon=draw_horizon,
+            draw_outlines=draw_outlines,
+        )
+
+    return {
+        "n_bytes": int(n_bytes),
+        "block_len": int(block_len),
+        "n_blocks": int(n_blocks),
+        "n_bands": int(n_bands),
+        "base_step": float(base_step),
+        "mu": float(mu),
+        "payload_len": int(len(payload)),
+        "out_flc": out_flc,
+        "preview_png": preview_png,
+        "unzip_gif": unzip_gif,
+        "ratio": (os.path.getsize(out_flc) / max(1, n_bytes)),
+    }
+
+def flc_decode_file(in_flc: str,
+                    out_path: str,
+                    unzip_gif: str = None,
+                    max_bands: int = None,
+                    gif_scale: int = 2,
+                    draw_horizon: bool = True,
+                    draw_outlines: bool = True):
+    blob = open(in_flc, "rb").read()
+    off = 0
+
+    (magic, ver, n_bytes, block_len, n_blocks, n_bands, base_step, mu, bnd_len) = struct.unpack_from(
+        "<8sH Q I I H d d H", blob, off
+    )
+    off += struct.calcsize("<8sH Q I I H d d H")
+    if magic != MAGIC:
+        raise ValueError("Bad magic (not FLC1)")
+    if ver != VER_V2:
+        raise ValueError(f"Unsupported version {ver}")
+
+    boundaries = list(struct.unpack_from("<" + "I"*bnd_len, blob, off))
+    off += 4 * bnd_len
+
+    (payload_len,) = struct.unpack_from("<I", blob, off)
+    off += 4
+    payload = blob[off:off+payload_len]
+    off += payload_len
+
+    n_coeffs = int(n_blocks) * int(block_len)
+    d = rle_fib_decode_ints(payload, n_coeffs)
+    q_flat = inv_delta1d(d).astype(np.int64)
+    Q_full = q_flat.reshape(int(n_blocks), int(block_len)).astype(np.int32)
+
+    # horizon
+    n_total_bands = len(boundaries) - 1
+    bands_to_apply = n_total_bands if max_bands is None else max(0, min(int(max_bands), n_total_bands))
+
+    if bands_to_apply < n_total_bands:
+        Q_use = np.zeros_like(Q_full)
+        for bi in range(bands_to_apply):
+            a, b = boundaries[bi], boundaries[bi+1]
+            if a < b:
+                Q_use[:, a:b] = Q_full[:, a:b]
+    else:
+        Q_use = Q_full
+
+    C = band_dequantize_dct(Q_use, boundaries, base_step=float(base_step), phi=PHI)
+    X = idct_blocks_ortho(C)
+
+    x = X.reshape(-1)[:int(n_bytes)]
+    x = (x * 127.5) + float(mu)
+    x = np.clip(np.round(x), 0, 255).astype(np.uint8)
+
+    with open(out_path, "wb") as f:
+        f.write(x.tobytes())
+
+    if unzip_gif is not None:
+        make_unzip_gif_from_Q(
+            Q_full=Q_full,
+            boundaries=boundaries,
+            base_step=float(base_step),
+            mu=float(mu),
+            n_bytes=int(n_bytes),
+            out_gif=unzip_gif,
+            max_bands=(bands_to_apply if bands_to_apply > 0 else 1),
+            gif_scale=gif_scale,
+            draw_horizon=draw_horizon,
+            draw_outlines=draw_outlines,
+        )
+
+    return {
+        "n_bytes": int(n_bytes),
+        "block_len": int(block_len),
+        "n_blocks": int(n_blocks),
+        "n_bands": int(n_bands),
+        "base_step": float(base_step),
+        "mu": float(mu),
+        "payload_len": int(payload_len),
+        "out_path": out_path,
+        "unzip_gif": unzip_gif,
+        "bands_applied": int(bands_to_apply),
+    }
+
+# --------------------------
+# Quality metric
+# --------------------------
+def cosine_similarity_bytes(a: bytes, b: bytes) -> float:
+    x = np.frombuffer(a, dtype=np.uint8).astype(np.float64)
+    y = np.frombuffer(b, dtype=np.uint8).astype(np.float64)
+    n = min(x.size, y.size)
+    x = x[:n]; y = y[:n]
+    x -= x.mean(); y -= y.mean()
+    nx = np.linalg.norm(x) + 1e-12
+    ny = np.linalg.norm(y) + 1e-12
+    return float(np.dot(x, y) / (nx * ny))
+
+# --------------------------
+# CLI wrapper (call explicitly)
+# --------------------------
+def flc_cli(argv=None):
+    ap = argparse.ArgumentParser(description="FLC v1.3: Fibonacci-banded DCT + φ quant + Fibonacci coding + horizon ring + tile outlines")
+    ap.add_argument("inp", type=str)
+    ap.add_argument("out_flc", type=str)
+    ap.add_argument("preview_png", type=str)
+    ap.add_argument("unzip_gif", type=str)
+    ap.add_argument("out_recovered", type=str)
+    ap.add_argument("--block", type=int, default=1024)
+    ap.add_argument("--bands", type=int, default=10)
+    ap.add_argument("--step", type=float, default=0.004)
+    ap.add_argument("--no_center", action="store_true")
+    ap.add_argument("--horizon", type=int, default=None)
+    ap.add_argument("--gif_scale", type=int, default=2)
+    ap.add_argument("--no_ring", action="store_true")
+    ap.add_argument("--no_outlines", action="store_true")
+    args = ap.parse_args(argv)
+
+    enc = flc_encode_file(
+        args.inp, args.out_flc, args.preview_png, unzip_gif=args.unzip_gif,
+        block_len=args.block, n_bands=args.bands, base_step=args.step,
+        use_mean_center=(not args.no_center),
+        gif_scale=args.gif_scale,
+        gif_horizon=None,
+        draw_horizon=(not args.no_ring),
+        draw_outlines=(not args.no_outlines),
+    )
+    print("ENC:", enc)
+
+    dec = flc_decode_file(
+        args.out_flc, args.out_recovered,
+        unzip_gif="decode_" + os.path.basename(args.unzip_gif),
+        max_bands=args.horizon,
+        gif_scale=args.gif_scale,
+        draw_horizon=(not args.no_ring),
+        draw_outlines=(not args.no_outlines),
+    )
+    print("DEC:", dec)
+
+    a = open(args.inp, "rb").read()
+    b = open(args.out_recovered, "rb").read()
+    cs = cosine_similarity_bytes(a, b)
+    print("Cosine similarity (bytes):", cs, " => ", cs*100, "%")
+    print("ORIG:", os.path.getsize(args.inp), "FLC:", os.path.getsize(args.out_flc),
+          "RATIO:", os.path.getsize(args.out_flc)/max(1, os.path.getsize(args.inp)))
+
+# ============================================================
+# Notebook demo (run manually)
+# ============================================================
+with open("test_input.bin","wb") as f:
+    f.write(b"Black hole horizon unzip meets Fibonacci spiral. " * 220)
+enc = flc_encode_file("test_input.bin","test_output.flc","test_preview.png",
+                      unzip_gif="test_unzip.gif",
+                      block_len=1024, n_bands=10, base_step=0.004,
+                       gif_scale=2, draw_horizon=True, draw_outlines=True)
+print("ENC:", enc)
+dec = flc_decode_file("test_output.flc","test_recovered.bin",
+                      unzip_gif="test_decode_unzip.gif",
+                      max_bands=None, gif_scale=2,
+                      draw_horizon=True, draw_outlines=True)
+print("DEC:", dec)
+a = open("test_input.bin","rb").read()
+b = open("test_recovered.bin","rb").read()
+print("Cosine similarity:", cosine_similarity_bytes(a,b))
+decp = flc_decode_file("test_output.flc","test_partial.bin",
+                       unzip_gif="test_partial_unzip.gif",
+                       max_bands=4, gif_scale=2,
+                       draw_horizon