initial commit

README.md

@@ -1,13 +1,104 @@
 ---
-title: Pystackreg App
-emoji: 👁
-colorFrom: green
-colorTo: indigo
+title: Pystackreg Web App
+emoji: 🧠
+colorFrom: indigo
+colorTo: cyan
 sdk: gradio
-sdk_version: 5.29.0
+sdk_version: 5.25.1
 app_file: app.py
 pinned: false
-short_description: Web app for image stack registration using pystackreg
+tags:
+  - image-processing
+  - registration
+  - pystackreg
 ---
+# 🧠 Stack Image Registration Web App  
+A web-based application for image stack registration powered by **Gradio** and **pystackreg**.  
+This tool allows users to align and stabilize multi-frame TIFF images using a variety of transformation models.
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+    <img src="https://raw.githubusercontent.com/qchapp/pystackreg-app/refs/heads/master/images/app.png" height="500">
+</p>
+
+---
+
+## 🚀 Try the App  
+The application is running on [Hugging Face](https://huggingface.co/), try it using this [link](https://huggingface.co/spaces/qchapp/pystackreg-app)!
+
+---
+
+## 🛠️ Installation  
+We recommend performing the installation in a clean Python environment.
+
+This app requires `python>=3.10`. To install dependencies, run:
+
+```sh
+pip install -r requirements.txt
+```
+
+---
+
+## ▶️ Usage  
+To run the app locally:
+
+```sh
+python app.py
+```
+
+Then open your browser and go to: [http://localhost:7860](http://localhost:7860)
+
+---
+
+## 🔍 About Stack Registration  
+This app uses the [pystackreg](https://github.com/glichtner/pystackreg) library, a Python port of the TurboReg/StackReg algorithms.  
+It supports several transformation models for alignment:
+- Translation
+- Rigid Body
+- Scaled Rotation
+- Affine
+- Bilinear
+
+---
+
+## 📂 Features  
+This application provides three core registration modes:
+
+1. **📚 Reference-Based Alignment**  
+   Align all frames within a stack to a selected reference frame — either from the same stack or an external 3D image.
+
+2. **🎯 Stack-Based Alignment**  
+   Align every frame in one stack to the first frame of another reference stack.
+
+3. **🧩 Frame-to-Frame Alignment**  
+   Align a single frame to another frame within the same stack.
+
+By default, the app uses the **Rigid Body** transformation mode for all alignment tasks.  
+If needed, users can enable **Advanced Settings** in each tab to select from other transformation models, such as Translation, Affine, or Bilinear.
+
+Each mode offers:
+- 🔍 Interactive image preview
+- 🧭 Frame-by-frame navigation
+- 💾 Downloadable aligned results
+- ⚙️ Customizable transformation models via advanced options
+
+---
+
+### 📚 Credits
+
+- **App Author**: [Quentin Chappuis](https://github.com/qchapp)  
+  Developed the Gradio-based web interface and integrated `pystackreg` for image stack registration.
+
+- **Core Registration Library**: [pystackreg](https://github.com/glichtner/pystackreg)  
+  A Python port of the StackReg plugin, written by [Gregor Lichtenberg](https://github.com/glichtner).
+
+- **Original Algorithm Author**: Philippe Thévenaz (EPFL)  
+  The core algorithm was originally developed by Philippe Thévenaz and is described in the following publication:
+
+  > P. Thévenaz, U.E. Ruttimann, M. Unser.  
+  > *A Pyramid Approach to Subpixel Registration Based on Intensity*.  
+  > IEEE Transactions on Image Processing, vol. 7, no. 1, pp. 27–41, January 1998.  
+  > [View paper](http://bigwww.epfl.ch/publications/thevenaz9801.html)
+
+  For more information, visit the [Biomedical Imaging Group at EPFL](http://bigwww.epfl.ch/).
+
+---

app.py

@@ -0,0 +1,230 @@
+import gradio as gr
+import numpy as np
+from PIL import Image
+from pystackreg import StackReg
+import imageio.v2 as iio
+import tifffile
+import tempfile
+
+from core.utils import *
+
+# Globals
+original_frames, aligned_frames = [], []
+ref_frames, mov_frames, reg_frames = [], [], []
+custom_stack, reg_result = [], None
+full_stack, full_aligned = [], []
+
+# reset
+def reset_intra_stack():
+    global original_frames, aligned_frames
+    original_frames, aligned_frames = [], []
+    return [None, gr.update(value=0, minimum=0, maximum=0), None, gr.update(value=0, minimum=0, maximum=0), None, gr.update(value=0, minimum=0, maximum=0), None, gr.update(value=0, minimum=0, maximum=0), None]
+
+def reset_reference_based():
+    global ref_frames, mov_frames, reg_frames
+    ref_frames, mov_frames, reg_frames = [], [], []
+    return [None, None, None, gr.update(value=0, minimum=0, maximum=0), None, gr.update(value=0, minimum=0, maximum=0), None]
+
+def reset_frame_to_frame():
+    global custom_stack, reg_result
+    custom_stack, reg_result = [], None
+    return [None, gr.update(value=0, minimum=0, maximum=0), gr.update(value=0, minimum=0, maximum=0), None, None]
+
+
+# Registration Logic
+def intra_stack_align(f, ref_idx, ext_file, ext_idx, mode):
+    global original_frames, aligned_frames
+    stack = load_stack(f)
+    original_frames = [Image.fromarray(fr) for fr in stack]
+    sr = StackReg(get_sr_mode(mode))
+
+    if ext_file:
+        ext_stack = load_stack(ext_file)
+        ref = ext_stack[ext_idx]
+    else:
+        ref = stack[ref_idx]
+
+    aligned = [sr.register_transform(ref, fr) for fr in stack]
+    aligned = normalize_stack(np.stack(aligned))
+    aligned_frames = [upscale(Image.fromarray(fr)) for fr in aligned]
+
+    path = tempfile.NamedTemporaryFile(suffix=".tif", delete=False).name
+    tifffile.imwrite(path, aligned, photometric='minisblack')
+
+    return (
+        original_frames[0],
+        gr.update(value=0, maximum=len(original_frames) - 1),
+        aligned_frames[0],
+        gr.update(value=0, maximum=len(aligned_frames) - 1),
+        path
+    )
+
+def reference_align(ref_file, mov_file, mode):
+    global ref_frames, mov_frames, reg_frames
+    ref_stack = load_stack(ref_file)
+    mov_stack = load_stack(mov_file)
+    ref_frames = [Image.fromarray(f) for f in ref_stack]
+    mov_frames = [Image.fromarray(f) for f in mov_stack]
+    sr = StackReg(get_sr_mode(mode))
+    aligned = [sr.register_transform(ref_stack[0], f) for f in mov_stack]
+    aligned = normalize_stack(np.stack(aligned))
+    reg_frames = [upscale(Image.fromarray(f)) for f in aligned]
+    path = tempfile.NamedTemporaryFile(suffix=".tif", delete=False).name
+    tifffile.imwrite(path, aligned, photometric='minisblack')
+    return ref_frames[0], gr.update(value=0, maximum=len(ref_frames)-1), \
+           reg_frames[0], gr.update(value=0, maximum=len(reg_frames)-1), path
+
+def frame_to_frame_align(file, ref_idx, mov_idx, mode):
+    global custom_stack, reg_result
+    stack = load_stack(file)
+    custom_stack = [Image.fromarray(f) for f in stack]
+    sr = StackReg(get_sr_mode(mode))
+    aligned = sr.register_transform(stack[ref_idx], stack[mov_idx])
+    aligned = normalize_stack(np.stack([aligned]))[0]
+    reg_result = Image.fromarray(aligned)
+    path = tempfile.NamedTemporaryFile(suffix=".tif", delete=False).name
+    tifffile.imwrite(path, aligned[np.newaxis, ...], photometric='minisblack')
+    return reg_result, path
+
+
+# Interface
+with gr.Blocks() as demo:
+    gr.Markdown("# 🧠 Pystackreg Web Application")
+    gr.Markdown(citation_markdown)
+
+    with gr.Accordion("📘 How to Use This App (Click to Expand)", open=False):
+        gr.Markdown(documentation_markdown)
+
+    with gr.Tab("📚 Reference-Based Alignment"):
+        with gr.Row():
+            file_input = gr.File(label="Upload Stack to Register")
+            use_ext_ref = gr.Checkbox(label="Use external reference stack")
+
+        with gr.Row():
+            ref_slider = gr.Slider(label="Reference Frame (from uploaded stack)", minimum=0, maximum=0, value=0, step=1, visible=True)
+            ext_ref_file = gr.File(label="Upload External Reference Stack (.tif)", visible=False)
+            ext_ref_slider = gr.Slider(label="Reference Frame (from external stack)", minimum=0, maximum=0, value=0, step=1, visible=False)
+
+        use_ext_ref.change(
+            lambda use_ext: (
+                gr.update(visible=not use_ext),
+                gr.update(visible=use_ext),
+                gr.update(visible=use_ext)
+            ),
+            use_ext_ref,
+            [ref_slider, ext_ref_file, ext_ref_slider]
+        )
+
+        ext_ref_file.change(
+            lambda f: gr.update(value=0, maximum=len(iio.mimread(f)) - 1) if f else gr.update(value=0, maximum=0),
+            ext_ref_file,
+            ext_ref_slider
+        )
+
+        with gr.Row():
+            show_advanced = gr.Checkbox(label="Show Advanced Settings", value=False)
+            mode_dropdown = gr.Dropdown(["TRANSLATION", "RIGID_BODY", "SCALED_ROTATION", "AFFINE", "BILINEAR"],
+                                        value="RIGID_BODY", label="Transformation Mode", visible=False)
+
+        show_advanced.change(lambda v: gr.update(visible=v), show_advanced, mode_dropdown)
+        run_btn = gr.Button("▶️ Align Stack")
+
+        with gr.Row():
+            original_image = gr.Image(label="Original Frame")
+            aligned_image = gr.Image(label="Aligned Frame")
+
+        with gr.Row():
+            original_slider = gr.Slider(label="Browse Original Stack", minimum=0, maximum=0, value=0, step=1)
+            aligned_slider = gr.Slider(label="Browse Aligned Stack", minimum=0, maximum=0, value=0, step=1)
+
+        download = gr.File(label="Download")
+
+        file_input.change(
+            lambda f: gr.update(value=0, maximum=len(iio.mimread(f)) - 1) if f else gr.update(value=0, maximum=0),
+            file_input,
+            ref_slider
+        )
+
+        run_btn.click(
+            intra_stack_align,
+            [file_input, ref_slider, ext_ref_file, ext_ref_slider, mode_dropdown],
+            [original_image, original_slider, aligned_image, aligned_slider, download]
+        )
+
+        original_slider.change(lambda i: original_frames[i] if 0 <= i < len(original_frames) else None, original_slider, original_image)
+        aligned_slider.change(lambda i: aligned_frames[i] if 0 <= i < len(aligned_frames) else None, aligned_slider, aligned_image)
+
+        reset_btn = gr.Button("🔄 Reset Tab")
+        reset_btn.click(
+            reset_intra_stack,
+            outputs=[
+                file_input, ref_slider, ext_ref_file, ext_ref_slider,
+                original_image, original_slider, aligned_image, aligned_slider, download
+            ]
+        )
+
+    with gr.Tab("🎯 Stack-Based Alignment"):
+        with gr.Row():
+            ref_input = gr.File(label="Reference Stack")
+            mov_input = gr.File(label="Moving Stack")
+
+        with gr.Row():
+            show_adv_ref = gr.Checkbox(label="Show Advanced Settings", value=False)
+            mode_dropdown_ref = gr.Dropdown(["TRANSLATION", "RIGID_BODY", "SCALED_ROTATION", "AFFINE", "BILINEAR"],
+                                            value="RIGID_BODY", label="Transformation Mode", visible=False)
+
+        show_adv_ref.change(lambda v: gr.update(visible=v), show_adv_ref, mode_dropdown_ref)
+        ref_btn = gr.Button("▶️ Register")
+
+        with gr.Row():
+            ref_image = gr.Image(label="Reference Frame")
+            reg_image = gr.Image(label="Registered Frame")
+
+        with gr.Row():
+            ref_slider = gr.Slider(label="Browse Ref", minimum=0, maximum=0, value=0, step=1)
+            reg_slider = gr.Slider(label="Browse Reg", minimum=0, maximum=0, value=0, step=1)
+
+        download_ref = gr.File(label="Download")
+
+        ref_btn.click(reference_align, [ref_input, mov_input, mode_dropdown_ref],
+                      [ref_image, ref_slider, reg_image, reg_slider, download_ref])
+        ref_slider.change(lambda i: ref_frames[i] if 0 <= i < len(ref_frames) else None, ref_slider, ref_image)
+        reg_slider.change(lambda i: reg_frames[i] if 0 <= i < len(reg_frames) else None, reg_slider, reg_image)
+
+        reset_ref_btn = gr.Button("🔄 Reset Tab")
+        reset_ref_btn.click(
+            reset_reference_based,
+            outputs=[ref_input, mov_input, ref_image, ref_slider, reg_image, reg_slider, download_ref]
+        )
+
+
+    with gr.Tab("🧩 Frame-to-Frame Alignment"):
+        with gr.Row():
+            frame_file = gr.File(label="Upload Stack")
+            ref_idx = gr.Slider(label="Reference Frame", minimum=0, maximum=0, value=0, step=1)
+            mov_idx = gr.Slider(label="Moving Frame", minimum=0, maximum=0, value=0, step=1)
+
+        with gr.Row():
+            show_adv_ftf = gr.Checkbox(label="Show Advanced Settings", value=False)
+            mode_dropdown_ftf = gr.Dropdown(["TRANSLATION", "RIGID_BODY", "SCALED_ROTATION", "AFFINE", "BILINEAR"],
+                                            value="RIGID_BODY", label="Transformation Mode", visible=False)
+
+        show_adv_ftf.change(lambda v: gr.update(visible=v), show_adv_ftf, mode_dropdown_ftf)
+        frame_btn = gr.Button("▶️ Register Frame")
+        frame_output = gr.Image(label="Registered Output")
+        download_ftf = gr.File(label="Download")
+
+        frame_file.change(
+            lambda f: [gr.update(value=0, maximum=len(iio.mimread(f)) - 1)]*2 if f else [gr.update(value=0, maximum=0)]*2,
+            frame_file, [ref_idx, mov_idx]
+        )
+        frame_btn.click(frame_to_frame_align, [frame_file, ref_idx, mov_idx, mode_dropdown_ftf], [frame_output, download_ftf])
+
+        reset_ftf_btn = gr.Button("🔄 Reset Tab")
+        reset_ftf_btn.click(
+            reset_frame_to_frame,
+            outputs=[frame_file, ref_idx, mov_idx, frame_output, download_ftf]
+        )
+
+if __name__ == "__main__":
+    demo.launch()

core/utils.py

@@ -0,0 +1,110 @@
+from pystackreg import StackReg
+import numpy as np
+import imageio.v2 as iio
+from PIL import Image
+
+def get_sr_mode(mode_str): return {
+    "TRANSLATION": StackReg.TRANSLATION,
+    "RIGID_BODY": StackReg.RIGID_BODY,
+    "SCALED_ROTATION": StackReg.SCALED_ROTATION,
+    "AFFINE": StackReg.AFFINE,
+    "BILINEAR": StackReg.BILINEAR,
+}.get(mode_str, StackReg.RIGID_BODY)
+
+def normalize_stack(stack):
+    norm_stack = []
+    for frame in stack:
+        f = frame.astype(np.float32)
+        low, high = np.percentile(f, (1, 99))
+        f = np.clip(f, low, high)
+        f = (f - f.min()) / (np.ptp(f) + 1e-8) * 255 if np.ptp(f) > 0 else np.zeros_like(f)
+        norm_stack.append(f.astype(np.uint8))
+    return np.stack(norm_stack)
+
+def upscale(image, factor=3):
+    return image.resize((image.width * factor, image.height * factor), Image.NEAREST)
+
+def load_stack(file):
+    stack = np.array(iio.mimread(file))
+    if stack.ndim == 4 and stack.shape[-1] == 3:
+        stack = np.mean(stack, axis=-1)
+    return normalize_stack(stack)
+
+
+##### Markdowns #####
+
+citation_markdown = """
+        ### 📘 Credits & Acknowledgments
+
+        Register TIFF stacks using multiple alignment strategies.
+
+        **App Author**: [Quentin Chappuis](https://github.com/qchapp)  
+        **Pystackreg Author**: [Gregor Lichtenberg](https://github.com/glichtner)  
+        🔗 [Pystackreg on GitHub](https://github.com/glichtner/pystackreg)  
+
+        **Original Algorithm Author**: Philippe Thévenaz (EPFL)  
+        The core algorithm was originally developed by Philippe Thévenaz and is described in the following publication:
+
+        > P. Thévenaz, U.E. Ruttimann, M. Unser  
+        > *A Pyramid Approach to Subpixel Registration Based on Intensity*  
+        > *IEEE Transactions on Image Processing*, vol. 7, no. 1, pp. 27–41, January 1998.  
+        > 🔗 [View paper](http://bigwww.epfl.ch/publications/thevenaz9801.html)
+        """
+
+
+documentation_markdown = """
+        ### Overview
+
+        This app provides three registration modes for 2D TIFF image stacks using the `pystackreg` library.
+
+        ---
+
+        ### 📚 Tab 1: Reference-Based Alignment
+
+        Register a stack using a reference frame. You can:
+        - Use a frame from the **same stack** as reference
+        - Or upload an **external reference stack**
+
+        1. Upload the stack you want to align.
+        2. (Optional) Check "Use external reference stack" to align to a frame from another file.
+        3. Choose the reference frame using the slider.
+        4. (Optional) Choose transformation mode.
+        5. Click **▶️ Align Stack**.
+        6. Use sliders to browse original/aligned results and download the output.
+
+        ---
+
+        ### 🎯 Tab 2: Stack-Based Alignment
+
+        Align one stack (moving) to another (reference).
+
+        1. Upload both **reference** and **moving** stacks.
+        2. (Optional) Choose transformation mode.
+        3. Click **▶️ Register** to align.
+        4. Browse and download registered stack.
+
+        ---
+
+        ### 🧩 Tab 3: Frame-to-Frame Alignment
+
+        Align a **single frame to another** from the same stack.
+
+        1. Upload a stack.
+        2. Select **reference** and **moving** frames using sliders.
+        3. Choose transformation mode.
+        4. Click **▶️ Register Frame**.
+        5. View/download the result.
+
+        ---
+
+        ### 🔄 Reset Buttons
+
+        Each tab includes a **Reset Tab** button that clears inputs, outputs, and internal state.
+
+        ---
+
+        ### 🧠 Credits
+
+        App developed by **Quentin Chapuis**  
+        Library: [`pystackreg`](https://github.com/glichtner/pystackreg) by **Georg Lichtenberg**
+        """

requirements.txt

@@ -0,0 +1,4 @@
+gradio==5.25.1
+pystackreg
+tifffile
+imageio