Hugging Face's logo

Spaces:
qchapp
/
pystackreg-app
Sleeping

App Files Community
pystackreg-app
File size: 4,554 Bytes 
b120daa
 
 
 
 
 
 
 
 
 
 
 
 
 
8e6b3e7
 
 
f6da738
8e6b3e7
2530008
8e6b3e7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2530008
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
8e6b3e7
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
---
title: Pystackreg Web App
emoji: 🧠
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.25.1
app_file: app.py
pinned: false
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.

<p align="center">
    <img src="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

---

### 📂 Examples in the App

You can try the application directly using preloaded examples from the [`pystackreg`](https://github.com/glichtner/pystackreg) repository.  
Each mode includes interactive buttons that load demo TIFF stacks automatically:

- 📚 **Reference-Based Alignment**:  
  Loads a stack of PC12 microscopy frames.

- 🎯 **Stack-Based Alignment**:  
  Loads both an unregistered and a translation-aligned stack.

- 🧩 **Frame-to-Frame Alignment**:  
  Uses the same unregistered stack for aligning specific frames.

No need to upload your own files — just click and experiment!

---

### 🌐 URL Parameter Support

The app supports loading image stacks from external URLs using query parameters.

**▶️ Load a single stack (for Reference-Based or Frame-to-Frame):**

```
https://huggingface.co/spaces/qchapp/pystackreg-app?file_url=https://github.com/glichtner/pystackreg/raw/master/examples/data/pc12-unreg.tif
```


**▶️ Load two stacks (for Stack-Based Alignment):**

```
https://huggingface.co/spaces/qchapp/pystackreg-app?file_url_1=https://github.com/glichtner/pystackreg/raw/master/examples/data/pc12-unreg.tif&file_url_2=https://github.com/glichtner/pystackreg/raw/master/examples/data/pc12-reg-translation.tif
```

> 💡 The app will automatically load and preview the provided stack(s) in the appropriate tabs.

---

### 📚 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/).

---