Added code files

src/app.py

@@ -0,0 +1,560 @@
+import streamlit as st
+import numpy as np
+from PIL import Image
+import io
+import sys
+import os
+
+# Bug 3 & 4 fixes - Top level imports, recursion limit
+sys.setrecursionlimit(10000)
+
+sys.path.insert(0, os.path.dirname(__file__))
+from quadtree_engine import (
+    read_ppm_bytes, process_image, arr_to_pil, compress_image, decompress_image, pad_to_square_pow2
+)
+
+st.set_page_config(
+    page_title="QuadTree Image Engine",
+    page_icon="🌲",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+# ── CSS ──────────────────────────────────────────────────────────────────────
+st.markdown("""
+<style>
+@import url('https://fonts.googleapis.com/css2?family=DM+Mono:wght@400;500;700&family=IBM+Plex+Sans:wght@400;500;600&display=swap');
+
+html, body, [data-testid="stAppViewContainer"], .stApp {
+    background: #0d0d0d !important;
+    color: #f0f0f0 !important;
+    font-family: 'IBM Plex Sans', sans-serif !important;
+}
+
+header[data-testid="stHeader"] {
+    display: none !important;
+}
+
+
+h1, h2, h3, h4, h5, h6, [data-testid="stMarkdownContainer"] h1, [data-testid="stMarkdownContainer"] h2, [data-testid="stMarkdownContainer"] h3 {
+    font-family: 'DM Mono', monospace !important;
+}
+
+[data-testid="stSidebar"] {
+    background: #141414 !important;
+    border-right: 1px solid #2a2a2a !important;
+}
+
+.stButton > button {
+    background-color: #00ff87 !important;
+    color: #0d0d0d !important;
+    border: none !important;
+    border-radius: 4px !important;
+    font-family: 'DM Mono', monospace !important;
+    font-weight: 700 !important;
+    width: 100%;
+    margin-top: 1rem;
+}
+
+.stButton > button:hover {
+    background-color: #00cc6a !important;
+    color: #000000 !important;
+}
+
+.stDownloadButton > button {
+    background-color: transparent !important;
+    color: #00ff87 !important;
+    border: 1px solid #00ff87 !important;
+    border-radius: 4px !important;
+    font-family: 'DM Mono', monospace !important;
+    font-weight: 700 !important;
+}
+
+.stDownloadButton > button:hover {
+    background-color: #00ff87 !important;
+    color: #0d0d0d !important;
+}
+
+.accent-text { color: #00ff87; }
+.warning-text { color: #ffb700; }
+.error-text { color: #ff4444; }
+
+.step-row {
+    display: flex;
+    align-items: center;
+    margin-bottom: 0.5rem;
+    background-color: #141414;
+    border: 1px solid #2a2a2a;
+    padding: 0.75rem;
+}
+.step-num {
+    color: #00ff87;
+    font-family: 'DM Mono', monospace;
+    font-weight: 700;
+    margin-right: 1rem;
+    min-width: 60px;
+}
+
+.code-block-custom {
+    background-color: #141414;
+    border: 1px solid #2a2a2a;
+    padding: 1rem;
+    font-family: 'DM Mono', monospace;
+    color: #f0f0f0;
+}
+</style>
+""", unsafe_allow_html=True)
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+PPM_DIR = os.path.join(os.path.dirname(__file__), "c_project_files")
+
+def list_ppms():
+    result = []
+    if not os.path.isdir(PPM_DIR):
+        return result
+    for f in sorted(os.listdir(PPM_DIR)):
+        if not f.endswith(".ppm"):
+            continue
+        fpath = os.path.join(PPM_DIR, f)
+        try:
+            with open(fpath, "rb") as fh:
+                header = fh.read(3)
+            if header.startswith(b'P6'):
+                result.append(f)
+        except Exception:
+            pass
+    return result
+
+def load_array(uploaded=None, ppm_name=None):
+    if uploaded is not None:
+        uploaded.seek(0)
+        raw = uploaded.read()
+    elif ppm_name:
+        path = os.path.join(PPM_DIR, ppm_name)
+        with open(path, "rb") as f:
+            raw = f.read()
+    else:
+        return None, None
+
+    try:
+        arr = np.array(Image.open(io.BytesIO(raw)).convert("RGB"), dtype=np.uint8)
+        return arr, raw
+    except Exception:
+        pass
+
+    try:
+        arr = read_ppm_bytes(raw)
+        return arr, raw
+    except Exception as e:
+        fname = uploaded.name if uploaded else ppm_name
+        raise ValueError(f"Cannot read '{fname}' as an image.\nDetail: {e}")
+
+def count_nodes_and_leaves(node, depth=0):
+    if node is None:
+        return 0, 0, 0 # total, leaves, max_d
+    if node.is_leaf():
+        return 1, 1, depth
+    counts = [count_nodes_and_leaves(c, depth+1) for c in [node.topLeft, node.topRight, node.bottomLeft, node.bottomRight]]
+    total = 1 + sum(c[0] for c in counts)
+    leaves = sum(c[1] for c in counts)
+    max_d = max(c[2] for c in counts)
+    return total, leaves, max_d
+
+# ── Sidebar ──────────────────────────────────────────────────────────────────
+
+with st.sidebar:
+    st.markdown("### ⬆ INPUT")
+    
+    input_options = ["Upload file"]
+    has_ppms = os.path.isdir(PPM_DIR) and len(list_ppms()) > 0
+    if has_ppms:
+        input_options.append("Use repo PPM")
+        
+    input_mode = st.radio("Source", input_options, label_visibility="collapsed")
+    
+    arr1 = None
+    file_id = None
+    
+    if input_mode == "Upload file":
+        up1 = st.file_uploader("Primary image", type=["ppm","png","jpg","jpeg"], key="u1")
+        if up1:
+            file_id = f"{up1.name}_{up1.size}"
+            try:
+                arr1, _ = load_array(uploaded=up1)
+            except ValueError as e:
+                st.error(str(e))
+    else:
+        sel = st.selectbox("Select PPM", list_ppms())
+        if sel:
+            file_id = f"repo_{sel}"
+            try:
+                arr1, _ = load_array(ppm_name=sel)
+            except ValueError as e:
+                st.error(str(e))
+                
+    # Bug 5: Image Size Guard
+    if arr1 is not None:
+        MAX_DIM = 2048
+        h, w = arr1.shape[:2]
+        if h > MAX_DIM or w > MAX_DIM:
+            st.markdown(f"<div style='color: #ffb700; font-size: 0.85rem; margin-bottom: 1rem; border: 1px solid #ffb700; padding: 0.5rem;'>⚠️ Image is {w}×{h}. Images over {MAX_DIM}px may be slow or crash. Consider resizing first.</div>", unsafe_allow_html=True)
+
+    # Bug 6: Stale Result Flash (immediately wipe on new file)
+    if file_id != st.session_state.get("last_file_id"):
+        st.session_state.pop("result", None)
+        st.session_state.pop("tree", None)
+        st.session_state.pop("op_done", None)
+        st.session_state["last_file_id"] = file_id
+        
+    st.markdown("---")
+    st.markdown("### ⚙ OPERATION")
+    
+    OP_MAP = {
+        "Compress Only": "compress_only",
+        "Grayscale": "grayscale",
+        "Negative": "negative",
+        "Sepia": "sepia",
+        "Brighten": "brighten",
+        "Mirror (Horizontal)": "mirror",
+        "Flip (Vertical)": "water",
+        "Rotate Left 90°": "rotate_left",
+        "Rotate Right 90°": "rotate_right",
+        "Blend / Union": "union",
+    }
+    
+    operation = st.selectbox("Operation", list(OP_MAP.keys()), label_visibility="collapsed")
+    op_key = OP_MAP[operation]
+    
+    arr2 = None
+    if op_key == "union":
+        st.markdown("<div style='font-family: \"DM Mono\", monospace; font-size: 0.85rem;'>Second image for blending:</div>", unsafe_allow_html=True)
+        if input_mode == "Upload file":
+            up2 = st.file_uploader("Second image", type=["ppm","png","jpg","jpeg"], key="u2")
+            if up2:
+                try:
+                    arr2, _ = load_array(uploaded=up2)
+                except ValueError as e:
+                    st.error(str(e))
+        else:
+            sel2 = st.selectbox("Second PPM", list_ppms(), key="sel2")
+            if sel2:
+                try:
+                    arr2, _ = load_array(ppm_name=sel2)
+                except ValueError as e:
+                    st.error(str(e))
+
+    st.markdown("---")
+    st.markdown("### ◎ THRESHOLD")
+    threshold = st.slider("Quality vs Compression", 1, 500, 30, label_visibility="collapsed")
+    
+    if threshold <= 30:
+        st.markdown("<div style='color: #00ff87; font-family: \"DM Mono\", monospace; font-weight: bold;'>● LOSSLESS</div>", unsafe_allow_html=True)
+    elif threshold <= 100:
+        st.markdown("<div style='color: #ffb700; font-family: \"DM Mono\", monospace; font-weight: bold;'>● BALANCED</div>", unsafe_allow_html=True)
+    else:
+        st.markdown("<div style='color: #ff4444; font-family: \"DM Mono\", monospace; font-weight: bold;'>● LOSSY</div>", unsafe_allow_html=True)
+        
+    run = st.button("▶ RUN", disabled=(arr1 is None))
+    
+    st.markdown("<br>", unsafe_allow_html=True)
+    download_placeholder = st.empty()
+
+
+# ── Main Area ────────────────────────────────────────────────────────────────
+
+tab1, tab2, tab3 = st.tabs(["IMAGE VIEW", "ALGORITHM EXPLORER", "C SOURCE"])
+
+with tab1:
+    if run and arr1 is not None:
+        st.session_state.pop("result", None)
+        st.session_state.pop("tree", None)
+        
+        with st.spinner("Processing..."):
+            try:
+                if op_key == "compress_only":
+                    padded, oh, ow = pad_to_square_pow2(arr1)
+                    size = padded.shape[0]
+                    tree = compress_image(padded, 0, 0, size, threshold)
+                    out = np.zeros((size, size, 3), dtype=np.uint8)
+                    decompress_image(tree, out, 0, 0, size)
+                    computed = out[:oh, :ow]
+                elif op_key == "union":
+                    if arr2 is None:
+                        st.error("Please provide a second image for union.")
+                        computed, tree = None, None
+                    else:
+                        computed, tree = process_image(arr1, "union", threshold, arr2, return_tree=True)
+                else:
+                    computed, tree = process_image(arr1, op_key, threshold, return_tree=True)
+
+                if computed is not None:
+                    # Bug 1 Fix: Store result and tree together, avoid rebuilding
+                    st.session_state["result"] = computed
+                    st.session_state["tree"] = tree
+                    st.session_state["op_done"] = operation
+                    st.session_state["thresh_done"] = threshold
+            except RecursionError:
+                st.error("RecursionError: image too large for this threshold. Try a higher threshold.")
+            except Exception as e:
+                st.error(f"Error: {e}")
+
+    result_arr = st.session_state.get("result")
+    tree = st.session_state.get("tree")
+    
+    if arr1 is not None:
+        with st.container():
+            c1, c2 = st.columns(2)
+            with c1:
+                st.markdown("<div style='font-family: \"DM Mono\", monospace; margin-bottom: 0.5rem; color: #555;'>BEFORE</div>", unsafe_allow_html=True)
+                st.image(arr_to_pil(arr1), use_container_width=True)
+                st.markdown(f"<div style='font-family: \"DM Mono\", monospace; color: #555; text-align: center;'>{arr1.shape[1]} × {arr1.shape[0]}</div>", unsafe_allow_html=True)
+            with c2:
+                st.markdown("<div style='font-family: \"DM Mono\", monospace; margin-bottom: 0.5rem; color: #555;'>AFTER</div>", unsafe_allow_html=True)
+                if result_arr is not None:
+                    st.image(arr_to_pil(result_arr), use_container_width=True)
+                    op_str = st.session_state.get("op_done", "")
+                    th_str = st.session_state.get("thresh_done", "")
+                    st.markdown(f"<div style='font-family: \"DM Mono\", monospace; color: #555; text-align: center;'>{op_str} · t={th_str}</div>", unsafe_allow_html=True)
+                else:
+                    st.markdown("<div style='border: 1px solid #2a2a2a; height: 300px; display: flex; align-items: center; justify-content: center; color: #555; font-family: \"DM Mono\", monospace; background-color: #141414;'>[ RESULT IMAGE ]</div>", unsafe_allow_html=True)
+        
+        if result_arr is not None and tree is not None:
+            total_nodes, leaves, max_d = count_nodes_and_leaves(tree)
+            total_pixels = arr1.shape[0] * arr1.shape[1]
+            ratio = total_pixels / total_nodes if total_nodes > 0 else 0
+            
+            st.markdown("<div style='font-family: \"DM Mono\", monospace; color: #555; margin-top: 2rem; margin-bottom: 0.5rem;'>QUADTREE STATS</div>", unsafe_allow_html=True)
+            
+            st.markdown(f"""
+            <div style='display: flex; border: 1px solid #2a2a2a; background-color: #141414;'>
+                <div style='flex: 1; border-right: 1px solid #2a2a2a; padding: 1rem; text-align: center;'>
+                    <div style='color: #555; font-family: "DM Mono", monospace; font-size: 0.8rem; margin-bottom: 0.5rem;'>TOTAL NODES</div>
+                    <div style='color: #00ff87; font-family: "DM Mono", monospace; font-size: 1.5rem; font-weight: 700;'>{total_nodes:,}</div>
+                    <div style='color: #00ff87; font-size: 0.75rem; font-family: "DM Mono", monospace; margin-top: 4px;'>{ratio:.1f}× fewer nodes</div>
+                </div>
+                <div style='flex: 1; border-right: 1px solid #2a2a2a; padding: 1rem; text-align: center;'>
+                    <div style='color: #555; font-family: "DM Mono", monospace; font-size: 0.8rem; margin-bottom: 0.5rem;'>LEAF NODES</div>
+                    <div style='color: #00ff87; font-family: "DM Mono", monospace; font-size: 1.5rem; font-weight: 700;'>{leaves:,}</div>
+                </div>
+                <div style='flex: 1; border-right: 1px solid #2a2a2a; padding: 1rem; text-align: center;'>
+                    <div style='color: #555; font-family: "DM Mono", monospace; font-size: 0.8rem; margin-bottom: 0.5rem;'>MAX DEPTH</div>
+                    <div style='color: #00ff87; font-family: "DM Mono", monospace; font-size: 1.5rem; font-weight: 700;'>{max_d}</div>
+                </div>
+                <div style='flex: 1; border-right: 1px solid #2a2a2a; padding: 1rem; text-align: center;'>
+                    <div style='color: #555; font-family: "DM Mono", monospace; font-size: 0.8rem; margin-bottom: 0.5rem;'>TOTAL PIXELS</div>
+                    <div style='color: #00ff87; font-family: "DM Mono", monospace; font-size: 1.5rem; font-weight: 700;'>{total_pixels:,}</div>
+                </div>
+                <div style='flex: 1; padding: 1rem; text-align: center;'>
+                    <div style='color: #555; font-family: "DM Mono", monospace; font-size: 0.8rem; margin-bottom: 0.5rem;'>THRESHOLD</div>
+                    <div style='color: #00ff87; font-family: "DM Mono", monospace; font-size: 1.5rem; font-weight: 700;'>{st.session_state.get('thresh_done')}</div>
+                </div>
+            </div>
+            """, unsafe_allow_html=True)
+            
+            with download_placeholder:
+                img_pil = arr_to_pil(result_arr)
+                buf = io.BytesIO()
+                img_pil.save(buf, format="PNG")
+                st.download_button("↓ DOWNLOAD RESULT", buf.getvalue(), "result.png", "image/png")
+                
+    else:
+        st.markdown("<div style='border: 1px solid #2a2a2a; padding: 6rem; text-align: center; color: #555; font-family: \"DM Mono\", monospace; background-color: #141414;'>[ AWAITING INPUT ]</div>", unsafe_allow_html=True)
+
+
+with tab2:
+    st.markdown("### 1. What is a Quadtree?")
+    c1, c2 = st.columns(2)
+    with c1:
+        st.code("""
+┌────────┬────────┐
+│        │        │
+│   TL   │   TR   │
+│        │        │
+├────────┼────────┤
+│        │        │
+│   BL   │   BR   │
+│        │        │
+└────────┴────────┘
+""", language="text")
+    with c2:
+        st.markdown("""
+- **`red`, `green`, `blue`**: The average color of this region.
+- **`area`**: The total pixels covered by this node.
+- **Children**: If variance > threshold, the region splits into 4 sub-regions (`topLeft`, `topRight`, `bottomLeft`, `bottomRight`).
+- **Leaf Node**: If variance <= threshold, children are null. The region is colored uniformly.
+""")
+
+    st.markdown("---")
+    st.markdown("### 2. How Compression Works")
+    st.markdown("<div style='color: #555; margin-bottom: 1rem;'>See how threshold controls quality vs. compression</div>", unsafe_allow_html=True)
+    
+    @st.cache_data
+    def get_synthetic_image():
+        y, x = np.mgrid[0:64, 0:64]
+        r = (x * 4) % 255
+        g = (y * 4) % 255
+        b = ((x + y) * 2) % 255
+        noise = np.random.randint(0, 50, (64, 64, 3))
+        img = np.stack([r, g, b], axis=-1) + noise
+        return np.clip(img, 0, 255).astype(np.uint8)
+
+    synth_img = get_synthetic_image()
+    sim_thresh = st.slider("Simulator Threshold", 1, 200, 50, key="sim_t")
+    
+    sc1, sc2 = st.columns(2)
+    with sc1:
+        st.image(arr_to_pil(synth_img), caption="Original (64x64)", use_container_width=True)
+    with sc2:
+        sim_tree = compress_image(synth_img, 0, 0, 64, sim_thresh)
+        sim_out = np.zeros((64, 64, 3), dtype=np.uint8)
+        decompress_image(sim_tree, sim_out, 0, 0, 64)
+        total_sim, leaves_sim, _ = count_nodes_and_leaves(sim_tree)
+        st.image(arr_to_pil(sim_out), caption=f"Compressed (Nodes: {total_sim})", use_container_width=True)
+
+    st.markdown("---")
+    st.markdown("### 3. Compression Algorithm Step-by-Step")
+    st.markdown("""
+<div class="step-row"><span class="step-num">STEP 1</span><span>Divide image into 4 quadrants</span></div>
+<div class="step-row"><span class="step-num">STEP 2</span><span>Compute mean RGB + variance for each quadrant</span></div>
+<div class="step-row"><span class="step-num">STEP 3</span><span>If variance ≤ threshold: <b>LEAF</b> → store avg color, stop subdividing</span></div>
+<div class="step-row"><span class="step-num">STEP 4</span><span>If variance > threshold: <b>RECURSE</b> into each quadrant with size/2</span></div>
+<div class="step-row"><span class="step-num">STEP 5</span><span>Continue until size=1 pixel or variance ≤ threshold</span></div>
+""", unsafe_allow_html=True)
+
+    st.markdown("---")
+    st.markdown("### 4. Color Filters — How They Work on the Tree")
+    fc1, fc2, fc3, fc4 = st.columns(4)
+    with fc1:
+        with st.container(border=True):
+            st.markdown("**Grayscale**")
+            st.code("L = 0.299R + 0.587G + 0.114B\nR'=L, G'=L, B'=L")
+            st.caption("Weights green channel most heavily (human eye is most sensitive to green)")
+    with fc2:
+        with st.container(border=True):
+            st.markdown("**Negative**")
+            st.code("R' = 255 - R\nG' = 255 - G\nB' = 255 - B")
+            st.caption("Inverts each channel — dark becomes light, colors become complementary")
+    with fc3:
+        with st.container(border=True):
+            st.markdown("**Sepia**")
+            st.code("R' = 0.393R + 0.769G + 0.189B\nG' = ...\nB' = ...")
+            st.caption("Warm brownish tones by mixing channels — mimics aged photographic paper")
+    with fc4:
+        with st.container(border=True):
+            st.markdown("**Brighten**")
+            st.code("R' = min(255, R*1.3)\nG' = min(255, G*1.3)\nB' = min(255, B*1.3)")
+            st.caption("Scales all channels up — clips at 255 to avoid overflow")
+
+    st.markdown("---")
+    st.markdown("### 5. Spatial Transforms — Pointer Swaps")
+    st.markdown("<div class='accent-text'><strong>No pixel data is ever copied. Only 4 pointer assignments per node.</strong></div><br>", unsafe_allow_html=True)
+    tc1, tc2 = st.columns(2)
+    with tc1:
+        st.code("""MIRROR (horizontal):
+Before:  TL | TR
+         -------
+         BL | BR
+
+After:   TR | TL
+         -------
+         BR | BL""", language="text")
+    with tc2:
+        st.code("""ROTATE LEFT 90°:
+Before:  TL | TR
+         -------
+         BL | BR
+
+After:   TR | BR
+         -------
+         TL | BL""", language="text")
+         
+    tc3, tc4 = st.columns(2)
+    with tc3:
+        st.code("""FLIP (vertical):
+Before:  TL | TR
+         -------
+         BL | BR
+
+After:   BL | BR
+         -------
+         TL | TR""", language="text")
+    with tc4:
+        st.code("""ROTATE RIGHT 90°:
+Before:  TL | TR
+         -------
+         BL | BR
+
+After:   BL | TL
+         -------
+         BR | TR""", language="text")
+
+    st.markdown("---")
+    st.markdown("### 6. Union / Blend — Three Cases")
+    st.markdown("""
+- **Case 1:** Both nodes are internal → recurse into all 4 child pairs.
+- **Case 2:** t1 is a leaf, t2 has children → blend t1's solid color with each of t2's children.
+- **Case 3:** t2 is a leaf, t1 has children → blend t2's solid color with each of t1's children.
+
+Averaging formula: `result.R = (t1.R + t2.R) / 2`
+*Note: This produces a pixel-perfect 50/50 blend without ever decompressing either image to a pixel buffer.*
+""")
+
+    st.markdown("---")
+    st.markdown("### 7. Complexity Analysis")
+    st.markdown("""
+| Operation | Time Complexity | Space Complexity | Notes |
+|---|---|---|---|
+| Compress | O(n log n) | O(n) | n = total pixels |
+| Decompress | O(n) | O(n) | Linear tree traversal |
+| Filter | O(k) | O(k) | k = tree nodes, k ≪ n |
+| Rotate/Mirror | O(k) | O(1) | Only pointer swaps |
+| Union | O(min(k1,k2)) | O(min(k1,k2)) | Bounded by smaller tree |
+
+<div style="border-left: 4px solid #00ff87; padding-left: 1rem; margin-top: 1rem; color: #f0f0f0;">
+<strong>Key Takeaway:</strong> Filters and transforms run on the compressed tree — they're O(nodes) not O(pixels). At threshold=100, a 512×512 image (262K pixels) may have fewer than 5,000 nodes.
+</div>
+""", unsafe_allow_html=True)
+
+
+with tab3:
+    st.markdown("### C Source vs Python")
+    st.markdown("""
+    <div style="background-color: #141414; border: 1px solid #2a2a2a; padding: 1rem; margin-bottom: 1rem;">
+    🔗 View the full C implementation on GitHub:<br>
+    <a href="https://github.com/Harshwardhan-Deshmukh03/Image-Manipulation-QuadTree.git" target="_blank"
+       style="color:#00ff87;font-weight:600;text-decoration:none;">
+       github.com/Harshwardhan-Deshmukh03/Image-Manipulation-QuadTree
+    </a>
+    </div>
+    """, unsafe_allow_html=True)
+    st.markdown("""
+| C File | Python Equivalent |
+|---|---|
+| `compress.c` | `compress_image()` |
+| `filters.c` | `apply_grayscale()`, `apply_negative()`, etc. |
+| `rotate.c` | `rotate_left()`, `get_mirror_image()`, etc. |
+| `union.c` | `union_of_images()` |
+| `decompress.c` | `decompress_image()` |
+""")
+    
+    c_files = {
+        "main.c": "CLI entry point — parses flags, orchestrates the full pipeline",
+        "compress.c": "Quadtree construction from pixel matrix using variance threshold",
+        "decompress.c": "Quadtree → pixel matrix reconstruction",
+        "filters.c": "Color filters: grayscale, negative, sepia, brighten",
+        "rotate.c": "Spatial transforms: mirror, flip, rotate L/R/180",
+        "union.c": "Pixel-level blending of two Quadtrees",
+        "suppl.c": "PPM I/O, getMean(), tree serialization helpers",
+        "suppl.h": "All struct definitions: pixels, qtNode, qtInfo",
+    }
+
+    st.markdown("<br>", unsafe_allow_html=True)
+    for fname, desc in c_files.items():
+        fpath = os.path.join(PPM_DIR, fname)
+        with st.expander(f"`{fname}` — {desc}"):
+            if os.path.isfile(fpath):
+                with open(fpath) as f:
+                    st.code(f.read(), language="c")
+            else:
+                st.info(f"File not found at: {fpath}")

src/quadtree_engine.py

@@ -0,0 +1,336 @@
+"""
+Quadtree Image Engine - Python implementation of the C quadtree image manipulation.
+Mirrors the logic from compress.c, decompress.c, filters.c, rotate.c, union.c
+"""
+import numpy as np
+from dataclasses import dataclass, field
+from typing import Optional
+from PIL import Image
+import io
+
+
+@dataclass
+class QtNode:
+    red: int = 0
+    green: int = 0
+    blue: int = 0
+    area: int = 0
+    topLeft: Optional['QtNode'] = field(default=None, repr=False)
+    topRight: Optional['QtNode'] = field(default=None, repr=False)
+    bottomLeft: Optional['QtNode'] = field(default=None, repr=False)
+    bottomRight: Optional['QtNode'] = field(default=None, repr=False)
+
+    def is_leaf(self):
+        return (self.topLeft is None and self.topRight is None and
+                self.bottomLeft is None and self.bottomRight is None)
+
+
+def get_mean(matrix: np.ndarray, x: int, y: int, size: int):
+    """Compute average color and variance score for a region. Mirrors getMean() in suppl.c"""
+    region = matrix[y:y+size, x:x+size]
+    red = int(np.mean(region[:, :, 0]))
+    green = int(np.mean(region[:, :, 1]))
+    blue = int(np.mean(region[:, :, 2]))
+    variance = (
+        np.mean((region[:, :, 0].astype(int) - red)**2) +
+        np.mean((region[:, :, 1].astype(int) - green)**2) +
+        np.mean((region[:, :, 2].astype(int) - blue)**2)
+    ) / 3
+    return red, green, blue, int(variance)
+
+
+def compress_image(matrix: np.ndarray, x: int, y: int, size: int, threshold: int) -> QtNode:
+    """Build quadtree. Mirrors compressImage() in compress.c"""
+    red, green, blue, score = get_mean(matrix, x, y, size)
+    node = QtNode(red=red, green=green, blue=blue, area=size * size)
+    if size > 1 and score > threshold:
+        half = size // 2
+        node.topLeft = compress_image(matrix, x, y, half, threshold)
+        node.topRight = compress_image(matrix, x + half, y, half, threshold)
+        node.bottomRight = compress_image(matrix, x + half, y + half, half, threshold)
+        node.bottomLeft = compress_image(matrix, x, y + half, half, threshold)
+    return node
+
+
+def decompress_image(node: QtNode, matrix: np.ndarray, x: int, y: int, size: int):
+    """Reconstruct pixel matrix from quadtree. Mirrors decompressImage() in decompress.c"""
+    if node.is_leaf():
+        matrix[y:y+size, x:x+size, 0] = node.red
+        matrix[y:y+size, x:x+size, 1] = node.green
+        matrix[y:y+size, x:x+size, 2] = node.blue
+    else:
+        half = size // 2
+        decompress_image(node.topLeft, matrix, x, y, half)
+        decompress_image(node.topRight, matrix, x + half, y, half)
+        decompress_image(node.bottomRight, matrix, x + half, y + half, half)
+        decompress_image(node.bottomLeft, matrix, x, y + half, half)
+
+
+# ── Filters (mirrors filters.c) ──────────────────────────────────────────────
+
+def apply_grayscale(node: QtNode) -> QtNode:
+    """True luminance-weighted grayscale.
+    Compute single luma value and assign to all 3 channels so the
+    output is actually grey (not green-tinted).
+    luma = 0.299R + 0.587G + 0.114B  (BT.601 standard)
+    """
+    res = QtNode(area=node.area)
+    if not node.is_leaf():
+        res.topLeft = apply_grayscale(node.topLeft)
+        res.topRight = apply_grayscale(node.topRight)
+        res.bottomLeft = apply_grayscale(node.bottomLeft)
+        res.bottomRight = apply_grayscale(node.bottomRight)
+    luma = int(0.299 * node.red + 0.587 * node.green + 0.114 * node.blue)
+    res.red = luma
+    res.green = luma
+    res.blue = luma
+    return res
+
+
+def apply_negative(node: QtNode) -> QtNode:
+    """Invert channels: 255 - value. Mirrors negativeImage() in filters.c"""
+    res = QtNode(area=node.area)
+    if not node.is_leaf():
+        res.topLeft = apply_negative(node.topLeft)
+        res.topRight = apply_negative(node.topRight)
+        res.bottomLeft = apply_negative(node.bottomLeft)
+        res.bottomRight = apply_negative(node.bottomRight)
+    res.red = 255 - node.red
+    res.green = 255 - node.green
+    res.blue = 255 - node.blue
+    return res
+
+
+def apply_sepia(node: QtNode) -> QtNode:
+    """Cinematic warm sepia tone. Mirrors sepia() in filters.c"""
+    res = QtNode(area=node.area)
+    if not node.is_leaf():
+        res.topLeft = apply_sepia(node.topLeft)
+        res.topRight = apply_sepia(node.topRight)
+        res.bottomLeft = apply_sepia(node.bottomLeft)
+        res.bottomRight = apply_sepia(node.bottomRight)
+    r, g, b = node.red, node.green, node.blue
+    res.red = min(255, int(0.393 * r + 0.769 * g + 0.189 * b))
+    res.green = min(255, int(0.272 * r + 0.534 * g + 0.131 * b))
+    res.blue = min(255, int(0.349 * r + 0.686 * g + 0.168 * b))
+    return res
+
+
+def apply_brighten(node: QtNode, factor: float = 1.3) -> QtNode:
+    """Brighten by scaling channels. Mirrors brighten() in filters.c"""
+    res = QtNode(area=node.area)
+    if not node.is_leaf():
+        res.topLeft = apply_brighten(node.topLeft, factor)
+        res.topRight = apply_brighten(node.topRight, factor)
+        res.bottomLeft = apply_brighten(node.bottomLeft, factor)
+        res.bottomRight = apply_brighten(node.bottomRight, factor)
+    res.red = min(255, int(node.red * factor))
+    res.green = min(255, int(node.green * factor))
+    res.blue = min(255, int(node.blue * factor))
+    return res
+
+
+# ── Spatial Transforms (mirrors rotate.c) ────────────────────────────────────
+
+def get_water_image(node: QtNode):
+    """Vertical flip (top-bottom). Mirrors getWaterImage() in rotate.c"""
+    if not node.is_leaf():
+        get_water_image(node.topLeft)
+        get_water_image(node.topRight)
+        get_water_image(node.bottomLeft)
+        get_water_image(node.bottomRight)
+        node.topLeft, node.bottomLeft = node.bottomLeft, node.topLeft
+        node.topRight, node.bottomRight = node.bottomRight, node.topRight
+
+
+def get_mirror_image(node: QtNode):
+    """Horizontal mirror (left-right). Mirrors getMirrorImage() in rotate.c"""
+    if not node.is_leaf():
+        get_mirror_image(node.topLeft)
+        get_mirror_image(node.topRight)
+        get_mirror_image(node.bottomLeft)
+        get_mirror_image(node.bottomRight)
+        node.topLeft, node.topRight = node.topRight, node.topLeft
+        node.bottomLeft, node.bottomRight = node.bottomRight, node.bottomLeft
+
+
+def rotate_left(node: QtNode):
+    """90° counter-clockwise. Mirrors rotateLeft() in rotate.c"""
+    if not node.is_leaf():
+        rotate_left(node.topLeft)
+        rotate_left(node.topRight)
+        rotate_left(node.bottomLeft)
+        rotate_left(node.bottomRight)
+        tl, tr, bl, br = node.topLeft, node.topRight, node.bottomLeft, node.bottomRight
+        node.topLeft = tr
+        node.topRight = br
+        node.bottomLeft = tl
+        node.bottomRight = bl
+
+
+def rotate_right(node: QtNode):
+    """90° clockwise. Mirrors rotateRight() in rotate.c"""
+    if not node.is_leaf():
+        rotate_right(node.topLeft)
+        rotate_right(node.topRight)
+        rotate_right(node.bottomLeft)
+        rotate_right(node.bottomRight)
+        tl, tr, bl, br = node.topLeft, node.topRight, node.bottomLeft, node.bottomRight
+        node.topLeft = bl
+        node.topRight = tl
+        node.bottomLeft = br
+        node.bottomRight = tr
+
+
+# ── Union / Blend (mirrors union.c) ──────────────────────────────────────────
+
+def union_of_images(t1: QtNode, t2: QtNode) -> QtNode:
+    """Average-blend two quadtrees. Mirrors unionOfImages() in union.c"""
+    res = QtNode(area=min(t1.area, t2.area))
+    res.red = (t1.red + t2.red) // 2
+    res.green = (t1.green + t2.green) // 2
+    res.blue = (t1.blue + t2.blue) // 2
+    if not t1.is_leaf() and not t2.is_leaf():
+        res.topLeft = union_of_images(t1.topLeft, t2.topLeft)
+        res.topRight = union_of_images(t1.topRight, t2.topRight)
+        res.bottomLeft = union_of_images(t1.bottomLeft, t2.bottomLeft)
+        res.bottomRight = union_of_images(t1.bottomRight, t2.bottomRight)
+    elif t1.is_leaf() and not t2.is_leaf():
+        res.topLeft = union_of_images(t1, t2.topLeft)
+        res.topRight = union_of_images(t1, t2.topRight)
+        res.bottomLeft = union_of_images(t1, t2.bottomLeft)
+        res.bottomRight = union_of_images(t1, t2.bottomRight)
+    elif not t1.is_leaf() and t2.is_leaf():
+        res.topLeft = union_of_images(t1.topLeft, t2)
+        res.topRight = union_of_images(t1.topRight, t2)
+        res.bottomLeft = union_of_images(t1.bottomLeft, t2)
+        res.bottomRight = union_of_images(t1.bottomRight, t2)
+    return res
+
+
+# ── I/O Helpers ───────────────────────────────────────────────────────────────
+
+def read_ppm_bytes(data: bytes):
+    """
+    Parse P6 binary PPM data robustly.
+    Returns numpy array (H, W, 3) uint8.
+    """
+    # First try Pillow (handles PNG/JPG/PPM automatically)
+    try:
+        img = Image.open(io.BytesIO(data)).convert("RGB")
+        return np.array(img, dtype=np.uint8)
+    except Exception:
+        pass
+
+    # Manual P6 binary PPM parser — reads header byte-by-byte
+    pos = 0
+    def read_token():
+        nonlocal pos
+        # Skip whitespace and comments
+        while pos < len(data):
+            c = data[pos:pos+1]
+            if c == b'#':
+                while pos < len(data) and data[pos:pos+1] != b'\n':
+                    pos += 1
+            elif c in (b' ', b'\t', b'\n', b'\r'):
+                pos += 1
+            else:
+                break
+        start = pos
+        while pos < len(data) and data[pos:pos+1] not in (b' ', b'\t', b'\n', b'\r'):
+            pos += 1
+        return data[start:pos].decode('ascii')
+
+    magic = read_token()
+    if magic != 'P6':
+        raise ValueError(f"Not a P6 PPM file (got: {magic!r})")
+    w = int(read_token())
+    h = int(read_token())
+    _maxval = int(read_token())
+    # skip exactly one whitespace byte after maxval
+    pos += 1
+    raw = data[pos:pos + h * w * 3]
+    arr = np.frombuffer(raw, dtype=np.uint8).reshape(h, w, 3)
+    return arr.copy()  # make writable
+
+
+def arr_to_pil(arr: np.ndarray) -> Image.Image:
+    return Image.fromarray(arr.astype(np.uint8), 'RGB')
+
+
+def next_power_of_two(n: int) -> int:
+    p = 1
+    while p < n:
+        p <<= 1
+    return p
+
+
+def pad_to_square_pow2(arr: np.ndarray):
+    """Pad image to square power-of-2 as required by the quadtree."""
+    h, w = arr.shape[:2]
+    size = next_power_of_two(max(h, w))
+    padded = np.zeros((size, size, 3), dtype=np.uint8)
+    padded[:h, :w] = arr
+    return padded, h, w
+
+
+def process_image(matrix: np.ndarray, operation: str, threshold: int,
+                  matrix2: Optional[np.ndarray] = None, return_tree: bool = False) -> np.ndarray:
+    """
+    Full pipeline: pad → compress → transform → decompress → crop.
+    Returns the result as a numpy RGB array, and optionally the tree.
+    """
+    padded, oh, ow = pad_to_square_pow2(matrix)
+    size = padded.shape[0]
+
+    tree = compress_image(padded, 0, 0, size, threshold)
+
+    if operation == "grayscale":
+        tree = apply_grayscale(tree)
+    elif operation == "negative":
+        tree = apply_negative(tree)
+    elif operation == "sepia":
+        tree = apply_sepia(tree)
+    elif operation == "brighten":
+        tree = apply_brighten(tree)
+    elif operation == "mirror":
+        get_mirror_image(tree)
+    elif operation == "water":
+        get_water_image(tree)
+    elif operation == "rotate_left":
+        rotate_left(tree)
+    elif operation == "rotate_right":
+        rotate_right(tree)
+    elif operation == "union" and matrix2 is not None:
+        padded2, oh2, ow2 = pad_to_square_pow2(matrix2)
+        s2 = padded2.shape[0]
+        s_common = max(size, s2)
+        p1 = np.zeros((s_common, s_common, 3), dtype=np.uint8)
+        p1[:padded.shape[0], :padded.shape[1]] = padded
+        p2 = np.zeros((s_common, s_common, 3), dtype=np.uint8)
+        p2[:padded2.shape[0], :padded2.shape[1]] = padded2
+        t1 = compress_image(p1, 0, 0, s_common, threshold)
+        t2 = compress_image(p2, 0, 0, s_common, threshold)
+        tree = union_of_images(t1, t2)
+        size = s_common
+        # For union, we want the bounding box that encompasses both original images
+        oh = max(oh, oh2)
+        ow = max(ow, ow2)
+
+    out = np.zeros((size, size, 3), dtype=np.uint8)
+    decompress_image(tree, out, 0, 0, size)
+    
+    if operation == "mirror":
+        res = out[:oh, size - ow : size]
+    elif operation == "water":
+        res = out[size - oh : size, :ow]
+    elif operation == "rotate_left":
+        res = out[size - ow : size, :oh]
+    elif operation == "rotate_right":
+        res = out[:ow, size - oh : size]
+    else:
+        res = out[:oh, :ow]
+    
+    if return_tree:
+        return res, tree
+    return res

src/test_engine.py

@@ -0,0 +1,27 @@
+import numpy as np
+from quadtree_engine import process_image
+
+# Create a mock "Mona Lisa" image: 1000x671
+arr = np.zeros((1000, 671, 3), dtype=np.uint8)
+# Draw a white rectangle to represent the face in the center
+arr[200:400, 200:471] = 255
+
+# Apply "water"
+res = process_image(arr, "water", 30)
+
+print(f"Original shape: {arr.shape}")
+print(f"Result shape: {res.shape}")
+
+# Check where the white pixels are in the result
+white_pixels = np.where(res[:, :, 0] == 255)
+if len(white_pixels[0]) > 0:
+    min_y, max_y = np.min(white_pixels[0]), np.max(white_pixels[0])
+    min_x, max_x = np.min(white_pixels[1]), np.max(white_pixels[1])
+    print(f"Face is at y: {min_y}-{max_y}, x: {min_x}-{max_x}")
+else:
+    print("No white pixels found!")
+    
+# Let's also check if there are non-zero pixels outside the expected region
+non_zero = np.where(res > 0)
+if len(non_zero[0]) > 0:
+    print(f"All Non-zero y: {np.min(non_zero[0])}-{np.max(non_zero[0])}, x: {np.min(non_zero[1])}-{np.max(non_zero[1])}")