Update src/app.py

src/app.py

@@ -2,6 +2,7 @@ import streamlit as st
 import pandas as pd
 import io
 import re
+import struct
 import numpy as np
 import openpyxl
 import base64
@@ -45,6 +46,127 @@ reverse_voyager_table = {v: k for k, v in voyager_table.items()}
 
 B64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
 
+# =========================
+# 4-bit Grayscale Helpers
+# =========================
+# 4-bit grayscale, uniform quantization in sRGB/BT.601 luma code space
+# (0=black, 15=white). Two pixels per byte, high-nibble first;
+# rows top-to-bottom, no row padding.
+# =========================
+
+def quantize_to_4bit(gray8: np.ndarray) -> np.ndarray:
+    """Quantize 8-bit grayscale (0..255) to 4-bit (0..15) with nearest rounding."""
+    v4 = np.round(gray8.astype(np.float32) * (15.0 / 255.0)).astype(np.uint8)
+    np.clip(v4, 0, 15, out=v4)
+    return v4
+
+def gray4_to_gray8(gray4: np.ndarray) -> np.ndarray:
+    """Expand 4-bit values (0..15) to 8-bit grayscale (0..255) for viewing."""
+    return np.round(gray4.astype(np.float32) * (255.0 / 15.0)).astype(np.uint8)
+
+def pack_4bpp_rows(gray4: np.ndarray) -> bytes:
+    """
+    Pack a 2D array of 4-bit values (0..15) into bytes: two pixels per byte.
+    High nibble = first pixel, Low nibble = second pixel.
+    If width is odd, pad the last low nibble with 0.
+    """
+    h, w = gray4.shape
+    bytes_per_row = (w + 1) // 2
+    out = bytearray(bytes_per_row * h)
+    idx = 0
+    for r in range(h):
+        row = gray4[r, :]
+        i = 0
+        while i < w:
+            hi = int(row[i] & 0x0F)
+            lo = int(row[i + 1] & 0x0F) if i + 1 < w else 0
+            out[idx] = (hi << 4) | lo
+            idx += 1
+            i += 2
+    return bytes(out)
+
+def unpack_4bpp_rows(packed: bytes, w: int, h: int) -> np.ndarray:
+    """
+    Unpack row-major 4bpp data into a 2D array (H, W) with values 0..15.
+    Two pixels per byte, high nibble first.
+    """
+    bytes_per_row = (w + 1) // 2
+    if len(packed) != bytes_per_row * h:
+        raise ValueError("Packed data length mismatch for given dimensions")
+    gray4 = np.zeros((h, w), dtype=np.uint8)
+    pos = 0
+    for r in range(h):
+        col = 0
+        for _ in range(bytes_per_row):
+            b = packed[pos]; pos += 1
+            hi = (b >> 4) & 0x0F
+            lo = b & 0x0F
+            gray4[r, col] = hi; col += 1
+            if col < w:
+                gray4[r, col] = lo; col += 1
+    return gray4
+
+def save_g4_bytes(gray4: np.ndarray) -> bytes:
+    """
+    Build a .g4 file in memory with a simple header and packed 4bpp payload.
+    Header (LE): magic 'G4' (2B), version (1B=1), width (uint32),
+    height (uint32), reserved (uint32=0).  Payload: ceil(width/2)*height bytes.
+    """
+    h, w = gray4.shape
+    payload = pack_4bpp_rows(gray4)
+    buf = io.BytesIO()
+    buf.write(b"G4")
+    buf.write(struct.pack("<B", 1))
+    buf.write(struct.pack("<I", w))
+    buf.write(struct.pack("<I", h))
+    buf.write(struct.pack("<I", 0))
+    buf.write(payload)
+    return buf.getvalue()
+
+def load_g4_bytes(data: bytes):
+    """
+    Load a .g4 file from bytes, returning (gray4, width, height).
+    """
+    offset = 0
+    if data[offset:offset+2] != b"G4":
+        raise ValueError("Not a G4 file")
+    offset += 2
+    version = data[offset]; offset += 1
+    if version != 1:
+        raise ValueError(f"Unsupported G4 version: {version}")
+    w = struct.unpack_from("<I", data, offset)[0]; offset += 4
+    h = struct.unpack_from("<I", data, offset)[0]; offset += 4
+    _reserved = struct.unpack_from("<I", data, offset)[0]; offset += 4
+    bytes_per_row = (w + 1) // 2
+    expected = bytes_per_row * h
+    payload = data[offset:offset+expected]
+    if len(payload) != expected:
+        raise ValueError("Payload length mismatch")
+    gray4 = unpack_4bpp_rows(payload, w=w, h=h)
+    return gray4, w, h
+
+def gray4_to_binary_flat(gray4: np.ndarray) -> list[int]:
+    """Convert 4-bit value matrix to flat binary list (4 bits per pixel, MSB first)."""
+    bits = []
+    for val in gray4.flatten():
+        v = int(val) & 0x0F
+        bits.extend([(v >> b) & 1 for b in range(3, -1, -1)])
+    return bits
+
+def binary_flat_to_gray4(bits: list[int], width: int) -> np.ndarray:
+    """Convert flat binary list (4 bits per pixel) back to 4-bit value matrix."""
+    n_pixels = len(bits) // 4
+    values = []
+    for i in range(0, n_pixels * 4, 4):
+        chunk = bits[i:i+4]
+        val = sum(b << (3 - j) for j, b in enumerate(chunk))
+        values.append(val)
+    height = max(1, int(np.ceil(n_pixels / width)))
+    padded = np.zeros(width * height, dtype=np.uint8)
+    padded[:len(values)] = values
+    return padded.reshape((height, width))
+
+
 # =========================
 # Encoding Functions
 # =========================
@@ -76,7 +198,6 @@ def encode_to_binary(text: str, scheme: str) -> tuple[list[int], list[str], list
         for byte in raw:
             bits.extend([(byte >> b) & 1 for b in range(7, -1, -1)])
         labels = [f"0x{b:02X}" for b in raw]
-        # Map each byte back to its source character
         source = []
         for ch in text:
             n_bytes = len(ch.encode("utf-8"))
@@ -92,7 +213,6 @@ def encode_to_binary(text: str, scheme: str) -> tuple[list[int], list[str], list
             val = B64_ALPHABET.index(c)
             bits.extend([(val >> b) & 1 for b in range(5, -1, -1)])
         labels = list(clean)
-        # Map each Base64 symbol to its primary source character
         byte_to_char = []
         for ch in text:
             n_bytes = len(ch.encode("utf-8"))
@@ -226,10 +346,8 @@ with tab1:
                 src = source_chars[i] if i < len(source_chars) else "?"
                 enc = display_units[i] if i < len(display_units) else "?"
                 if encoding_scheme == "Voyager 6-bit":
-                    # Voyager: direct char → binary (encoded label = uppercase of same char)
                     scroll_html += f"<div>'{src}' → {bits}</div>"
                 else:
-                    # Show original → encoded representation → binary
                     scroll_html += f"<div>'{src}' → '{enc}' → {bits}</div>"
             scroll_html += "</div>"
             st.markdown(scroll_html, unsafe_allow_html=True)
@@ -288,6 +406,18 @@ with tab1:
     else:
         st.subheader("Step 1 – Upload Image & Set Resolution")
 
+        image_type = st.selectbox(
+            "Image type:",
+            ["Black & White (1-bit)", "Grayscale (4-bit)"],
+            key="enc_image_type",
+            help=(
+                "**Black & White (1-bit)** — Each pixel = 1 bit (0 or 1). Uses a brightness threshold.\n\n"
+                "**Grayscale (4-bit)** — Each pixel = 4 bits (0–15 levels). "
+                "Uniform quantization in sRGB/BT.601 luma space. 0 = black, 15 = white. "
+                "Two pixels per byte, high-nibble first; rows top-to-bottom, no row padding."
+            )
+        )
+
         uploaded_img = st.file_uploader(
             "Upload an image (PNG, JPG, BMP, etc.):",
             type=["png", "jpg", "jpeg", "bmp", "gif", "tiff", "webp"],
@@ -301,106 +431,237 @@ with tab1:
 
             st.image(img, caption=f"Original (grayscale) — {orig_w}×{orig_h} px", use_container_width=True)
 
-            st.markdown("#### ⚙️ Resolution & Threshold")
+            st.markdown("#### ⚙️ Resolution")
             target_width = st.slider(
                 "Output width (pixels):",
                 min_value=8, max_value=min(orig_w, 256), value=min(64, orig_w), step=1,
-                help="Height is auto-calculated from aspect ratio. Each pixel = 1 bit."
+                help="Height is auto-calculated from aspect ratio."
             )
             target_height = max(1, int(round(target_width * aspect)))
-            total_bits = target_width * target_height
-            st.caption(f"Output size: **{target_width} × {target_height}** = **{total_bits:,}** bits (pixels)")
-
-            threshold = st.slider(
-                "Black/white threshold:",
-                min_value=0, max_value=255, value=128,
-                help="Pixels darker than this → 1 (black). Brighter → 0 (white)."
-            )
-
-            # Resize & threshold
             img_resized = img.resize((target_width, target_height), Image.LANCZOS)
             img_array = np.array(img_resized)
-            binary_matrix = (img_array < threshold).astype(int)  # dark = 1, light = 0
-
-            # Show preview
-            st.markdown("### Preview — Black & White Output")
-            col_prev1, col_prev2 = st.columns(2)
-            with col_prev1:
-                st.image(img_resized, caption=f"Resized grayscale ({target_width}×{target_height})", use_container_width=True)
-            with col_prev2:
-                bw_display = Image.fromarray(((1 - binary_matrix) * 255).astype(np.uint8))
-                st.image(bw_display, caption=f"Binary B&W ({target_width}×{target_height})", use_container_width=True)
-
-            # Flatten to binary labels
-            binary_labels = binary_matrix.flatten().tolist()
-            binary_concat = ''.join(map(str, binary_labels))
 
-            st.markdown("### Output 1 – Image Info")
-            st.markdown(
-                f"- **Dimensions:** {target_width} × {target_height}  \n"
-                f"- **Total bits:** {total_bits:,}  \n"
-                f"- **Black pixels (1s):** {sum(binary_labels):,}  \n"
-                f"- **White pixels (0s):** {total_bits - sum(binary_labels):,}"
-            )
+            # ===========================================================
+            # BLACK & WHITE (1-bit)
+            # ===========================================================
+            if image_type == "Black & White (1-bit)":
+                total_bits = target_width * target_height
+                st.caption(f"Output size: **{target_width} × {target_height}** = **{total_bits:,}** bits (1 bit/pixel)")
+
+                threshold = st.slider(
+                    "Black/white threshold:",
+                    min_value=0, max_value=255, value=128,
+                    help="Pixels darker than this → 1 (black). Brighter → 0 (white)."
+                )
 
-            st.download_button(
-                "⬇️ Download Concatenated Binary String",
-                data=binary_concat,
-                file_name="image_binary_full.txt",
-                mime="text/plain",
-                key="download_img_binary_txt"
-            )
+                binary_matrix = (img_array < threshold).astype(int)
+
+                st.markdown("### Preview — Black & White Output")
+                col_prev1, col_prev2 = st.columns(2)
+                with col_prev1:
+                    st.image(img_resized, caption=f"Resized grayscale ({target_width}×{target_height})", use_container_width=True)
+                with col_prev2:
+                    bw_display = Image.fromarray(((1 - binary_matrix) * 255).astype(np.uint8))
+                    st.image(bw_display, caption=f"Binary B&W ({target_width}×{target_height})", use_container_width=True)
+
+                binary_labels = binary_matrix.flatten().tolist()
+                binary_concat = ''.join(map(str, binary_labels))
+                n_ones = sum(binary_labels)
+
+                st.markdown("### Output 1 – Image Info")
+                st.markdown(
+                    f"- **Dimensions:** {target_width} × {target_height}  \n"
+                    f"- **Bits per pixel:** 1  \n"
+                    f"- **Total bits:** {total_bits:,}  \n"
+                    f"- **Black pixels (1):** {n_ones:,}  \n"
+                    f"- **White pixels (0):** {total_bits - n_ones:,}"
+                )
 
-            # Output as matrix with width = target_width
-            st.markdown("### Output 2 – Binary Matrix by dimension (Samples x Positions))")
-            columns = [f"Position {i+1}" for i in range(target_width)]
-            df_img = pd.DataFrame(binary_matrix, columns=columns)
-            df_img.insert(0, "Sample", range(1, len(df_img) + 1))
-            st.dataframe(df_img, width="stretch")
+                st.download_button(
+                    "⬇️ Download Concatenated Binary String",
+                    data=binary_concat,
+                    file_name="image_binary_full.txt",
+                    mime="text/plain",
+                    key="download_img_binary_txt"
+                )
 
-            st.download_button(
-                "⬇️ Download as CSV",
-                df_img.to_csv(index=False),
-                file_name=f"image_binary_{target_width}x{target_height}.csv",
-                mime="text/csv",
-                key="download_img_csv"
-            )
+                st.markdown("### Output 2 – Binary Matrix by dimension (Samples × Positions)")
+                columns = [f"Position {i+1}" for i in range(target_width)]
+                df_img = pd.DataFrame(binary_matrix, columns=columns)
+                df_img.insert(0, "Sample", range(1, len(df_img) + 1))
+                st.dataframe(df_img, width="stretch")
+
+                st.download_button(
+                    "⬇️ Download as CSV",
+                    df_img.to_csv(index=False),
+                    file_name=f"image_binary_{target_width}x{target_height}.csv",
+                    mime="text/csv",
+                    key="download_img_csv"
+                )
 
-            # Also offer custom grouping (same as text mode)
-            st.markdown("### Output 3 – Custom Grouped Matrix by Number of Target Positions")
-            col1, col2 = st.columns([2, 1])
-            with col1:
-                img_group_size = st.slider(
-                    "Select number of target positions:",
-                    min_value=12, max_value=128, value=target_width, key="img_group_slider"
+                st.markdown("### Output 3 – Custom Grouped Matrix by Number of Target Positions")
+                col1, col2 = st.columns([2, 1])
+                with col1:
+                    img_group_size = st.slider(
+                        "Select number of target positions:",
+                        min_value=12, max_value=128, value=target_width, key="img_group_slider"
+                    )
+                with col2:
+                    img_custom_cols = st.number_input(
+                        "Or enter custom number:",
+                        min_value=1, max_value=512, value=img_group_size, key="img_custom_cols"
+                    )
+                if img_custom_cols != img_group_size:
+                    img_group_size = img_custom_cols
+
+                groups = []
+                for i in range(0, len(binary_labels), img_group_size):
+                    group = binary_labels[i:i + img_group_size]
+                    if len(group) < img_group_size:
+                        group += [0] * (img_group_size - len(group))
+                    groups.append(group)
+
+                columns_g = [f"Position {i+1}" for i in range(img_group_size)]
+                df_grouped = pd.DataFrame(groups, columns=columns_g)
+                df_grouped.insert(0, "Sample", range(1, len(df_grouped) + 1))
+                st.dataframe(df_grouped, width="stretch")
+
+                st.download_button(
+                    "⬇️ Download Grouped CSV",
+                    df_grouped.to_csv(index=False),
+                    file_name=f"image_binary_grouped_{img_group_size}_positions.csv",
+                    mime="text/csv",
+                    key="download_img_grouped_csv"
                 )
-            with col2:
-                img_custom_cols = st.number_input(
-                    "Or enter custom number:",
-                    min_value=1, max_value=512, value=img_group_size, key="img_custom_cols"
+
+            # ===========================================================
+            # GRAYSCALE (4-bit)
+            # ===========================================================
+            else:
+                n_pixels = target_width * target_height
+                total_bits = n_pixels * 4
+                st.caption(
+                    f"Output size: **{target_width} × {target_height}** = **{n_pixels:,}** pixels × 4 bits = "
+                    f"**{total_bits:,}** bits"
                 )
-            if img_custom_cols != img_group_size:
-                img_group_size = img_custom_cols
 
-            groups = []
-            for i in range(0, len(binary_labels), img_group_size):
-                group = binary_labels[i:i + img_group_size]
-                if len(group) < img_group_size:
-                    group += [0] * (img_group_size - len(group))
-                groups.append(group)
+                gray4_matrix = quantize_to_4bit(img_array)
+                gray8_preview = gray4_to_gray8(gray4_matrix)
+
+                st.markdown("### Preview — 4-bit Grayscale (16 levels)")
+                col_prev1, col_prev2 = st.columns(2)
+                with col_prev1:
+                    st.image(img_resized, caption=f"Original resized ({target_width}×{target_height}, 256 levels)", use_container_width=True)
+                with col_prev2:
+                    st.image(
+                        Image.fromarray(gray8_preview),
+                        caption=f"4-bit quantized ({target_width}×{target_height}, 16 levels)",
+                        use_container_width=True
+                    )
 
-            columns_g = [f"Position {i+1}" for i in range(img_group_size)]
-            df_grouped = pd.DataFrame(groups, columns=columns_g)
-            df_grouped.insert(0, "Sample", range(1, len(df_grouped) + 1))
-            st.dataframe(df_grouped, width="stretch")
+                # Binary flat
+                binary_labels = gray4_to_binary_flat(gray4_matrix)
+                binary_concat = ''.join(map(str, binary_labels))
+
+                st.markdown("### Output 1 – Image Info")
+                unique_vals, counts = np.unique(gray4_matrix, return_counts=True)
+                st.markdown(
+                    f"- **Dimensions:** {target_width} × {target_height}  \n"
+                    f"- **Bits per pixel:** 4 (values 0–15)  \n"
+                    f"- **Total pixels:** {n_pixels:,}  \n"
+                    f"- **Total bits:** {total_bits:,}  \n"
+                    f"- **Unique levels used:** {len(unique_vals)} of 16"
+                )
 
-            st.download_button(
-                "⬇️ Download Grouped CSV",
-                df_grouped.to_csv(index=False),
-                file_name=f"image_binary_grouped_{img_group_size}_positions.csv",
-                mime="text/csv",
-                key="download_img_grouped_csv"
-            )
+                # Downloads: binary string, packed .g4 file
+                col_dl1, col_dl2 = st.columns(2)
+                with col_dl1:
+                    st.download_button(
+                        "⬇️ Download Binary String (.txt, 4 bits/pixel)",
+                        data=binary_concat,
+                        file_name="image_gray4_binary_full.txt",
+                        mime="text/plain",
+                        key="download_g4_binary_txt"
+                    )
+                with col_dl2:
+                    g4_bytes = save_g4_bytes(gray4_matrix)
+                    st.download_button(
+                        "⬇️ Download Packed .g4 File",
+                        data=g4_bytes,
+                        file_name=f"image_{target_width}x{target_height}.g4",
+                        mime="application/octet-stream",
+                        key="download_g4_file"
+                    )
+
+                # Value matrix (0-15 per pixel)
+                st.markdown("### Output 2 – Value Matrix (0–15 per pixel)")
+                st.caption("Each cell = one pixel's 4-bit grayscale level. 0 = black, 15 = white.")
+                columns_v = [f"Position {i+1}" for i in range(target_width)]
+                df_val = pd.DataFrame(gray4_matrix.astype(int), columns=columns_v)
+                df_val.insert(0, "Sample", range(1, len(df_val) + 1))
+                st.dataframe(df_val, width="stretch")
+
+                st.download_button(
+                    "⬇️ Download Value Matrix CSV (0–15)",
+                    df_val.to_csv(index=False),
+                    file_name=f"image_gray4_values_{target_width}x{target_height}.csv",
+                    mime="text/csv",
+                    key="download_g4_values_csv"
+                )
+
+                # Binary matrix (4 bits per pixel → width*4 binary columns per row)
+                st.markdown("### Output 3 – Binary Matrix (4 bits per pixel)")
+                st.caption("Each pixel expanded to 4 binary columns. Row width = image width × 4.")
+                bin_width = target_width * 4
+                bin_matrix = np.array(binary_labels).reshape((target_height, bin_width))
+                columns_b = [f"Position {i+1}" for i in range(bin_width)]
+                df_bin = pd.DataFrame(bin_matrix, columns=columns_b)
+                df_bin.insert(0, "Sample", range(1, len(df_bin) + 1))
+                st.dataframe(df_bin, width="stretch")
+
+                st.download_button(
+                    "⬇️ Download Binary Matrix CSV",
+                    df_bin.to_csv(index=False),
+                    file_name=f"image_gray4_binary_{target_width}x{target_height}.csv",
+                    mime="text/csv",
+                    key="download_g4_binary_csv"
+                )
+
+                # Custom grouped
+                st.markdown("### Output 4 – Custom Grouped Matrix by Number of Target Positions")
+                col1, col2 = st.columns([2, 1])
+                with col1:
+                    g4_group_size = st.slider(
+                        "Select number of target positions:",
+                        min_value=12, max_value=256, value=bin_width, key="g4_group_slider"
+                    )
+                with col2:
+                    g4_custom_cols = st.number_input(
+                        "Or enter custom number:",
+                        min_value=1, max_value=1024, value=g4_group_size, key="g4_custom_cols"
+                    )
+                if g4_custom_cols != g4_group_size:
+                    g4_group_size = g4_custom_cols
+
+                groups = []
+                for i in range(0, len(binary_labels), g4_group_size):
+                    group = binary_labels[i:i + g4_group_size]
+                    if len(group) < g4_group_size:
+                        group += [0] * (g4_group_size - len(group))
+                    groups.append(group)
+
+                columns_cg = [f"Position {i+1}" for i in range(g4_group_size)]
+                df_cg = pd.DataFrame(groups, columns=columns_cg)
+                df_cg.insert(0, "Sample", range(1, len(df_cg) + 1))
+                st.dataframe(df_cg, width="stretch")
+
+                st.download_button(
+                    "⬇️ Download Grouped CSV",
+                    df_cg.to_csv(index=False),
+                    file_name=f"image_gray4_grouped_{g4_group_size}_positions.csv",
+                    mime="text/csv",
+                    key="download_g4_grouped_csv"
+                )
         else:
             st.info("👆 Upload an image to encode it as binary.")
 
@@ -409,7 +670,7 @@ with tab1:
 # --------------------------------------------------
 with tab2:
     st.markdown("""
-    Decode binary data back into **text** or render it as a **black & white image**.
+    Decode binary data back into **text** or render it as an **image**.
     """)
 
     decode_mode = st.selectbox("Output mode:", ["Text", "Image"], key="decode_mode")
@@ -474,96 +735,259 @@ with tab2:
     # IMAGE DECODE MODE
     # =====================================================
     else:
-        st.markdown("""
-        Render binary data (0/1) as a **black & white image**.  
-        Upload a binary matrix CSV (rows × positions) or a concatenated binary `.txt` string.
-        """)
-
-        img_preview_file = st.file_uploader(
-            "📤 Upload binary data file (.csv, .xlsx, or .txt):",
-            type=["csv", "xlsx", "txt"],
-            key="img_preview_uploader"
+        dec_image_type = st.selectbox(
+            "Image type:",
+            ["Black & White (1-bit)", "Grayscale (4-bit)"],
+            key="dec_image_type",
+            help=(
+                "**Black & White** — Input is 0/1 binary data. Each value = 1 pixel.\n\n"
+                "**Grayscale (4-bit)** — Input is a **value matrix (0–15)**, **binary data** "
+                "(every 4 bits = one pixel), or a packed **.g4 file**."
+            )
         )
 
-        if img_preview_file is not None:
-            try:
-                # --- Load binary data ---
-                if img_preview_file.name.endswith(".csv"):
-                    idf = pd.read_csv(img_preview_file)
-                    if "Sample" in idf.columns or "sample" in idf.columns:
-                        idf = idf.drop(columns=[c for c in idf.columns if c.lower() == "sample"])
-                    bits_matrix = idf.values.flatten().astype(int)
-                    detected_width = len(idf.columns)
-                elif img_preview_file.name.endswith(".xlsx"):
-                    idf = pd.read_excel(img_preview_file)
-                    if "Sample" in idf.columns or "sample" in idf.columns:
-                        idf = idf.drop(columns=[c for c in idf.columns if c.lower() == "sample"])
-                    bits_matrix = idf.values.flatten().astype(int)
-                    detected_width = len(idf.columns)
-                elif img_preview_file.name.endswith(".txt"):
-                    content = img_preview_file.read().decode().strip()
-                    bits_matrix = np.array([int(b) for b in content if b in ['0', '1']])
-                    detected_width = None
-                else:
-                    bits_matrix = np.array([])
-                    detected_width = None
-
-                if len(bits_matrix) == 0:
-                    st.warning("No binary data detected.")
-                else:
-                    total_bits = len(bits_matrix)
-                    st.success(f"✅ Loaded **{total_bits:,}** bits.")
+        # ===========================================================
+        # DECODE: B&W (1-bit)
+        # ===========================================================
+        if dec_image_type == "Black & White (1-bit)":
+            st.markdown("""
+            Render binary data (0/1) as a **black & white image**.  
+            Upload a binary matrix CSV (rows × positions) or a concatenated binary `.txt` string.
+            """)
+
+            img_preview_file = st.file_uploader(
+                "📤 Upload binary data file (.csv, .xlsx, or .txt):",
+                type=["csv", "xlsx", "txt"],
+                key="img_preview_uploader"
+            )
 
-                    # --- Width control ---
-                    st.markdown("#### ⚙️ Image Dimensions")
+            if img_preview_file is not None:
+                try:
+                    if img_preview_file.name.endswith(".csv"):
+                        idf = pd.read_csv(img_preview_file)
+                        if "Sample" in idf.columns or "sample" in idf.columns:
+                            idf = idf.drop(columns=[c for c in idf.columns if c.lower() == "sample"])
+                        bits_matrix = idf.values.flatten().astype(int)
+                        detected_width = len(idf.columns)
+                    elif img_preview_file.name.endswith(".xlsx"):
+                        idf = pd.read_excel(img_preview_file)
+                        if "Sample" in idf.columns or "sample" in idf.columns:
+                            idf = idf.drop(columns=[c for c in idf.columns if c.lower() == "sample"])
+                        bits_matrix = idf.values.flatten().astype(int)
+                        detected_width = len(idf.columns)
+                    elif img_preview_file.name.endswith(".txt"):
+                        content = img_preview_file.read().decode().strip()
+                        bits_matrix = np.array([int(b) for b in content if b in ['0', '1']])
+                        detected_width = None
+                    else:
+                        bits_matrix = np.array([])
+                        detected_width = None
 
-                    if detected_width and detected_width > 1:
-                        default_w = detected_width
-                        st.caption(f"Auto-detected width from columns: **{detected_width}**")
+                    if len(bits_matrix) == 0:
+                        st.warning("No binary data detected.")
                     else:
-                        default_w = max(1, int(np.sqrt(total_bits)))
+                        total_bits = len(bits_matrix)
+                        st.success(f"✅ Loaded **{total_bits:,}** bits.")
+
+                        st.markdown("#### ⚙️ Image Dimensions")
+                        if detected_width and detected_width > 1:
+                            default_w = detected_width
+                            st.caption(f"Auto-detected width from columns: **{detected_width}**")
+                        else:
+                            default_w = max(1, int(np.sqrt(total_bits)))
+
+                        img_width = st.number_input(
+                            "Image width (pixels / positions per row):",
+                            min_value=1, max_value=total_bits, value=default_w, step=1,
+                            key="img_preview_width"
+                        )
+                        img_height = int(np.ceil(total_bits / img_width))
+                        st.caption(f"Image size: **{img_width} × {img_height}** = **{img_width * img_height:,}** pixels "
+                                   f"({total_bits:,} bits, {img_width * img_height - total_bits} padded)")
+
+                        padded = np.zeros(img_width * img_height, dtype=int)
+                        padded[:total_bits] = bits_matrix[:total_bits]
+                        img_data = padded.reshape((img_height, img_width))
+
+                        img_render = ((1 - img_data) * 255).astype(np.uint8)
+                        pil_img = Image.fromarray(img_render, mode="L")
+
+                        st.markdown("### 🖼️ Rendered Image")
+                        display_scale = max(1, 256 // img_width)
+                        display_w = img_width * display_scale
+                        display_h = img_height * display_scale
+                        pil_display = pil_img.resize((display_w, display_h), Image.NEAREST)
+                        st.image(pil_display, caption=f"Binary image — {img_width}×{img_height} (1=black, 0=white)")
+
+                        ones = int(bits_matrix.sum())
+                        st.markdown(
+                            f"- **Black pixels (1):** {ones:,} ({100*ones/total_bits:.1f}%)  \n"
+                            f"- **White pixels (0):** {total_bits - ones:,} ({100*(total_bits-ones)/total_bits:.1f}%)"
+                        )
+
+                        buf = io.BytesIO()
+                        pil_img.save(buf, format="PNG")
+                        st.download_button(
+                            "⬇️ Download as PNG",
+                            data=buf.getvalue(),
+                            file_name=f"binary_image_{img_width}x{img_height}.png",
+                            mime="image/png",
+                            key="download_preview_png"
+                        )
+
+                        buf_hr = io.BytesIO()
+                        pil_display.save(buf_hr, format="PNG")
+                        st.download_button(
+                            "⬇️ Download Scaled PNG (for viewing)",
+                            data=buf_hr.getvalue(),
+                            file_name=f"binary_image_{display_w}x{display_h}_scaled.png",
+                            mime="image/png",
+                            key="download_preview_png_scaled"
+                        )
 
-                    img_width = st.number_input(
-                        "Image width (pixels / positions per row):",
-                        min_value=1, max_value=total_bits, value=default_w, step=1,
-                        key="img_preview_width"
+                except Exception as e:
+                    st.error(f"❌ Error processing file: {e}")
+                    import traceback
+                    st.code(traceback.format_exc())
+            else:
+                st.info("👆 Upload a binary data file (CSV or TXT) to render as an image.")
+
+        # ===========================================================
+        # DECODE: GRAYSCALE (4-bit)
+        # ===========================================================
+        else:
+            g4_input_format = st.selectbox(
+                "Input data format:",
+                ["Value matrix (0–15)", "Binary (4 bits per pixel)", "Packed .g4 file"],
+                key="g4_input_format",
+                help=(
+                    "**Value matrix** — CSV/XLSX where each cell is a pixel value 0–15. "
+                    "Rows = pixel rows, columns = pixel columns.\n\n"
+                    "**Binary** — 0/1 data where every 4 consecutive bits encode one pixel (0–15).\n\n"
+                    "**Packed .g4 file** — Binary file with G4 header + packed 4bpp payload "
+                    "(two pixels per byte, high-nibble first)."
+                )
+            )
+
+            st.markdown("Render 4-bit grayscale data as an image (16 levels, 0=black, 15=white).")
+
+            # Accept .g4 files in addition to csv/xlsx/txt
+            accept_types = ["csv", "xlsx", "txt"]
+            if g4_input_format == "Packed .g4 file":
+                accept_types = ["g4"]
+
+            g4_file = st.file_uploader(
+                f"📤 Upload data file ({', '.join('.' + t for t in accept_types)}):",
+                type=accept_types,
+                key="g4_decode_uploader"
+            )
+
+            if g4_file is not None:
+                try:
+                    gray4_matrix = None
+                    img_width = None
+                    img_height = None
+
+                    # ---- Packed .g4 file ----
+                    if g4_input_format == "Packed .g4 file":
+                        raw_data = g4_file.read()
+                        gray4_matrix, img_width, img_height = load_g4_bytes(raw_data)
+
+                    # ---- Value matrix (0-15) ----
+                    elif g4_input_format == "Value matrix (0–15)":
+                        if g4_file.name.endswith(".csv"):
+                            gdf = pd.read_csv(g4_file)
+                        elif g4_file.name.endswith(".xlsx"):
+                            gdf = pd.read_excel(g4_file)
+                        else:
+                            content = g4_file.read().decode().strip()
+                            rows = [list(map(int, line.split())) for line in content.splitlines() if line.strip()]
+                            gdf = pd.DataFrame(rows)
+
+                        if "Sample" in gdf.columns or "sample" in gdf.columns:
+                            gdf = gdf.drop(columns=[c for c in gdf.columns if c.lower() == "sample"])
+
+                        gray4_matrix = gdf.values.astype(int)
+                        gray4_matrix = np.clip(gray4_matrix, 0, 15).astype(np.uint8)
+                        img_height, img_width = gray4_matrix.shape
+
+                    # ---- Binary (4 bits per pixel) ----
+                    else:
+                        if g4_file.name.endswith(".csv"):
+                            bdf = pd.read_csv(g4_file)
+                            if "Sample" in bdf.columns or "sample" in bdf.columns:
+                                bdf = bdf.drop(columns=[c for c in bdf.columns if c.lower() == "sample"])
+                            flat_bits = bdf.values.flatten().astype(int).tolist()
+                            detected_cols = len(bdf.columns)
+                            img_width = detected_cols // 4 if detected_cols >= 4 else max(1, int(np.sqrt(len(flat_bits) // 4)))
+                        elif g4_file.name.endswith(".xlsx"):
+                            bdf = pd.read_excel(g4_file)
+                            if "Sample" in bdf.columns or "sample" in bdf.columns:
+                                bdf = bdf.drop(columns=[c for c in bdf.columns if c.lower() == "sample"])
+                            flat_bits = bdf.values.flatten().astype(int).tolist()
+                            detected_cols = len(bdf.columns)
+                            img_width = detected_cols // 4 if detected_cols >= 4 else max(1, int(np.sqrt(len(flat_bits) // 4)))
+                        elif g4_file.name.endswith(".txt"):
+                            content = g4_file.read().decode().strip()
+                            flat_bits = [int(b) for b in content if b in ['0', '1']]
+                            img_width = max(1, int(np.sqrt(len(flat_bits) // 4)))
+                        else:
+                            flat_bits = []
+                            img_width = 1
+
+                        gray4_matrix = binary_flat_to_gray4(flat_bits, img_width)
+                        img_height = gray4_matrix.shape[0]
+
+                    n_pixels = img_width * img_height
+                    st.success(f"✅ Loaded **{n_pixels:,}** pixels ({img_width} × {img_height}).")
+
+                    # Width override
+                    st.markdown("#### ⚙️ Image Dimensions")
+                    img_width_adj = st.number_input(
+                        "Image width (pixels per row):",
+                        min_value=1, max_value=n_pixels, value=img_width, step=1,
+                        key="g4_preview_width"
                     )
-                    img_height = int(np.ceil(total_bits / img_width))
-                    st.caption(f"Image size: **{img_width} × {img_height}** = **{img_width * img_height:,}** pixels "
-                               f"({total_bits:,} bits, {img_width * img_height - total_bits} padded)")
 
-                    # Pad to fill the last row
-                    padded = np.zeros(img_width * img_height, dtype=int)
-                    padded[:total_bits] = bits_matrix[:total_bits]
-                    img_data = padded.reshape((img_height, img_width))
+                    if img_width_adj != img_width:
+                        flat_vals = gray4_matrix.flatten()
+                        new_h = max(1, int(np.ceil(len(flat_vals) / img_width_adj)))
+                        padded = np.zeros(img_width_adj * new_h, dtype=np.uint8)
+                        padded[:len(flat_vals)] = flat_vals
+                        gray4_matrix = padded.reshape((new_h, img_width_adj))
+                        img_width = img_width_adj
+                        img_height = new_h
+
+                    st.caption(f"Image size: **{img_width} × {img_height}**")
 
-                    # Render: 1 = black (0), 0 = white (255)
-                    img_render = ((1 - img_data) * 255).astype(np.uint8)
-                    pil_img = Image.fromarray(img_render, mode="L")
+                    # Render
+                    gray8_render = gray4_to_gray8(gray4_matrix)
+                    pil_img = Image.fromarray(gray8_render, mode="L")
 
-                    st.markdown("### 🖼️ Rendered Image")
+                    st.markdown("### 🖼️ Rendered Image (4-bit Grayscale)")
                     display_scale = max(1, 256 // img_width)
                     display_w = img_width * display_scale
                     display_h = img_height * display_scale
                     pil_display = pil_img.resize((display_w, display_h), Image.NEAREST)
-                    st.image(pil_display, caption=f"Binary image — {img_width}×{img_height} (1=black, 0=white)")
+                    st.image(pil_display, caption=f"4-bit grayscale — {img_width}×{img_height} (0=black, 15=white)")
 
                     # Stats
-                    ones = int(bits_matrix.sum())
+                    unique_vals, counts = np.unique(gray4_matrix, return_counts=True)
                     st.markdown(
-                        f"- **Black pixels (1):** {ones:,} ({100*ones/total_bits:.1f}%)  \n"
-                        f"- **White pixels (0):** {total_bits - ones:,} ({100*(total_bits-ones)/total_bits:.1f}%)"
+                        f"- **Dimensions:** {img_width} × {img_height}  \n"
+                        f"- **Unique levels:** {len(unique_vals)} of 16  \n"
+                        f"- **Min / Max value:** {gray4_matrix.min()} / {gray4_matrix.max()}"
                     )
 
-                    # Download rendered image as PNG
+                    # Downloads
                     buf = io.BytesIO()
                     pil_img.save(buf, format="PNG")
                     st.download_button(
                         "⬇️ Download as PNG",
                         data=buf.getvalue(),
-                        file_name=f"binary_image_{img_width}x{img_height}.png",
+                        file_name=f"gray4_image_{img_width}x{img_height}.png",
                         mime="image/png",
-                        key="download_preview_png"
+                        key="download_g4_png"
                     )
 
                     buf_hr = io.BytesIO()
@@ -571,17 +995,17 @@ with tab2:
                     st.download_button(
                         "⬇️ Download Scaled PNG (for viewing)",
                         data=buf_hr.getvalue(),
-                        file_name=f"binary_image_{display_w}x{display_h}_scaled.png",
+                        file_name=f"gray4_image_{display_w}x{display_h}_scaled.png",
                         mime="image/png",
-                        key="download_preview_png_scaled"
+                        key="download_g4_png_scaled"
                     )
 
-            except Exception as e:
-                st.error(f"❌ Error processing file: {e}")
-                import traceback
-                st.code(traceback.format_exc())
-        else:
-            st.info("👆 Upload a binary data file (CSV or TXT) to render as an image.")
+                except Exception as e:
+                    st.error(f"❌ Error processing file: {e}")
+                    import traceback
+                    st.code(traceback.format_exc())
+            else:
+                st.info("👆 Upload a 4-bit grayscale data file to render as an image.")
 
 # --------------------------------------------------
 # TAB 3: Data Analytics
@@ -602,7 +1026,6 @@ with tab3:
 
     if analytics_uploaded is not None:
         try:
-            # --- Load ---
             if analytics_uploaded.name.endswith(".xlsx"):
                 adf = pd.read_excel(analytics_uploaded)
             else:
@@ -611,7 +1034,6 @@ with tab3:
             st.success(f"✅ Loaded file with {len(adf)} rows and {len(adf.columns)} columns")
             adf.columns = [str(c).strip() for c in adf.columns]
 
-            # --- Detect position columns ---
             non_pos_keywords = {"sample", "description", "descritpion", "total edited",
                                 'volume per "1"', "volume per 1", "id", "name"}
             position_cols = [c for c in adf.columns
@@ -629,18 +1051,13 @@ with tab3:
 
             st.info(f"Detected **{len(position_cols)}** position columns and **{len(adf)}** samples.")
 
-            # Convert position data to numeric
             pos_data = adf[position_cols].apply(pd.to_numeric, errors="coerce").fillna(0.0)
 
-            # Compute Total edited (sum across positions per sample)
             if "Total edited" in adf.columns:
                 total_edited = pd.to_numeric(adf["Total edited"], errors="coerce").fillna(0.0)
             else:
                 total_edited = pos_data.sum(axis=1)
 
-            # =====================================================
-            # Shared controls for raw data plots
-            # =====================================================
             st.markdown("### 1️⃣ Raw Data Distribution")
             st.caption("Visualize editing values across all positions and samples — before any binary labelling.")
 
@@ -658,9 +1075,7 @@ with tab3:
                 )
             )
 
-            # --- Apply transforms ---
             def robust_pos_normalize_log1p(data: pd.DataFrame) -> pd.DataFrame:
-                """log1p then robust per-position normalization (median + IQR)."""
                 logged = np.log1p(data)
                 result = logged.copy()
                 for col in result.columns:
@@ -690,15 +1105,11 @@ with tab3:
                 value_label = "Editing Value"
                 transform_tag = "raw"
 
-            # Melt data to long format: (sample, position_index, value)
             melted = transformed.melt(var_name="Position", value_name="Value")
             melted["Position_idx"] = melted["Position"].apply(
                 lambda x: int(re.search(r"(\d+)", str(x)).group(1)) if re.search(r"(\d+)", str(x)) else 0
             )
 
-            # =====================================================
-            # PLOT 2: Histogram — all values
-            # =====================================================
             st.markdown("#### 📊 Histogram — All Values")
 
             n_bins = st.number_input("Number of bins:", min_value=10, max_value=300, value=80, step=10, key="hist_bins")
@@ -708,7 +1119,6 @@ with tab3:
             ax2.set_xlabel(value_label)
             ax2.set_ylabel("Count")
             ax2.set_title(f"Raw Values Distribution ({transform_tag})")
-            # Fine x-axis ticks adapted to transform range
             val_min = melted["Value"].min()
             val_max = melted["Value"].max()
             val_range = val_max - val_min
@@ -727,19 +1137,14 @@ with tab3:
             fig2.tight_layout()
             st.pyplot(fig2)
 
-            # =====================================================
-            # PLOT 3: FACS-style density scatter
-            # =====================================================
             st.markdown("#### 2️⃣ Density Scatter Plot (FACS-style)")
             st.caption("Each dot = one measurement (sample × position). Color = local point density.")
 
             x_vals = melted["Position_idx"].values.astype(float)
             y_vals = melted["Value"].values.astype(float)
 
-            # Add small jitter to x for visual separation
             x_jittered = x_vals + np.random.default_rng(42).uniform(-0.3, 0.3, size=len(x_vals))
 
-            # Compute density
             with st.spinner("Computing point density..."):
                 try:
                     xy = np.vstack([x_jittered, y_vals])
@@ -747,7 +1152,6 @@ with tab3:
                 except np.linalg.LinAlgError:
                     density = np.ones(len(x_vals))
 
-            # Sort by density so dense points render on top
             sort_idx = density.argsort()
             x_plot = x_jittered[sort_idx]
             y_plot = y_vals[sort_idx]
@@ -764,9 +1168,6 @@ with tab3:
             fig3.tight_layout()
             st.pyplot(fig3)
 
-            # =====================================================
-            # PLOT 4: 2D Density Heatmap
-            # =====================================================
             st.markdown("#### 3️⃣ 2D Density Heatmap")
             st.caption("Binned heatmap of editing values by position — similar to a FACS density plot.")
 
@@ -825,7 +1226,6 @@ with tab4:
         min_value=10.0, max_value=2000.0, value=160.0, step=10.0
     )
 
-    # ---------- Helpers (plate geometry, parsing, viz) ----------
     ROWS_96 = ["A", "B", "C", "D", "E", "F", "G", "H"]
     COLS_96 = list(range(1, 13))
 
@@ -916,7 +1316,6 @@ with tab4:
             body.append("</div></div>")
         return "".join(body)
 
-    # ---------- Main flow ----------
     if uploaded_writing is not None:
         try:
             if uploaded_writing.name.endswith(".xlsx"):