Version 61.1 by puchades on 2025/02/13 10:33
Hide last authors
puchades 6.1 1 == To set up your working environment: ==
puchades 1.1 2
3 1. [[Register>>url:https://ebrains.eu/register/]] for an EBRAINS account, login, and set up a [[private collab>>url:https://wiki.ebrains.eu/bin/view/Collabs/]].
4 1. Initialise the Bucket by clicking on Bucket in the navigation panel -> Create Bucket.
puchades 53.1 5 1. Remember to set your data proxy bucket to "public". Your collab can still be private.
puchades 1.1 6 1. Give users Admin, Editor or Viewer rights by clicking** Team** in the navigation panel.
puchades 55.1 7 1. Install DeepZoom, WebAlign, WebWarp, LocaliZoom, and Meshview from the EBRAINS Collaboratory App Store (see instructions below)[[image:public_data_proxy_bucket.png]]
puchades 1.1 8
9 == How to install Collaboratory Apps ==
10
11 1. To install Collaboratory Apps, click on the + Create button (top right corner).
12 1. Give the page a Title (for example, WebAlign), select the Community App option, and click Create.
puchades 58.1 13 1. Select the App to install (for example, DeepZoom), and click Save and View.
puchades 56.1 14 1. Repeat this for all the relevant Community Apps. You will need, "DeepZoom"; "WebAlign"; "WebWarp"; "LocaliZoom" and "MeshView".
puchades 1.1 15 1. Navigate between the Apps in the navigation panel. File transfer between the Apps is through the Bucket.
16
puchades 60.1 17 [[image:1739438141762-762.png||height="414" width="300"]]
puchades 58.1 18
puchades 8.2 19 == How to prepare your images? ==
puchades 2.1 20
21 **~1. Prepare your images before upload by naming them according this naming convention:**
22
23 The ID should be unique to the particular brain section and in the format sXXX, with XXX representing the section number. The section number should reflect the serial order and spacing of the sections (e.g., s002, s006, s010 for every 4^^th^^ section starting with section 2).
24
puchades 8.2 25 Example: tg2345_MMSH_s001.tif
26
puchades 8.3 27 - Upload the images you want to work with into the bucket of your collab using the Data proxy (press on //"Bucket"//)
28
puchades 8.2 29 **2. Image ingestion**
30
puchades 61.1 31 Open the DeepZoom app and login with your EBRAINS credentials.
puchades 8.2 32
33
puchades 61.1 34 [[image:1739438392064-892.png]]
puchades 8.2 35
puchades 61.1 36 Select your bucket, the one where your images are stored.
puchades 8.2 37
puchades 61.1 38 Select the appropriate folder and click "Browse source" in order to visualise the images to ingest.
puchades 8.2 39
puchades 61.1 40 Enter the URL of the bucket by typing "/bucket_name/output_folder_name"
puchades 24.1 41
puchades 61.1 42 Press "Start process".
puchades 18.1 43
puchades 61.1 44 By refreshing the status, you will see when the ingestion is completed.
puchades 18.1 45
puchades 61.1 46 You now will have pyramid files in DZI format in your output folder. These can be opened by the WebAlign app.
puchades 8.2 47
puchades 8.3 48
puchades 61.1 49 [[image:1739439061155-890.png]]
50
puchades 3.1 51 == **How to use WebAlign** ==
52
puchades 5.1 53 WebAlign is an online tool for spatial registration of histological section images from rodent brains to reference 3D atlases.  Different experimental datasets registered to the same reference atlas allows you to spatially integrate, analyse and navigate these datasets within a standardised coordinate system. The output of WebAlign can be used for analysis in the online QUINT workflow.
54
puchades 8.1 55 Online user manual: [[https:~~/~~/webalign.readthedocs.io/en/latest/>>https://webalign.readthedocs.io/en/latest/]]
56
puchades 3.1 57 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
58
59 === Opening a sample dataset ===
60
puchades 25.1 61 Demo dataset is loaded using the file: **demo_mouse_data_start.waln**
puchades 3.1 62
puchades 25.1 63 You can see the result of a finished anchoring by choosing the file: **demo_mouse_data.waln**
puchades 3.1 64
65 === Opening a private dataset ===
66
puchades 25.1 67 After you have uploaded your images to the bucket and ingested your images with the QUINT Image creator app, this has generated DZIP chunks. These DZIP files are used by WebAlign.
puchades 3.1 68
69 ~1. Start a new registration by pressing "create new series", the UI will ask you for the name of the collab where DZI chunks are stored. E.g. my-collab-name
70
puchades 27.1 71 2. WebAlign will search for DZIP files and list those found.
puchades 3.1 72
73 3. Enter a name for the descriptor json file which will be created and will contain your anchoring information.
74
75 4. Choose the target 3D reference atlas (WHSv3 for Rat and CCFv3_2017 for Mouse).
76
77 5. Press //"create"//. The main window will now display WebAlign. This step can take some time.
78
puchades 27.1 79 [[image:create series webAlign.png]]
80
puchades 33.1 81 === Opening an EBRAINS dataset ===
puchades 27.1 82
puchades 28.1 83 (% class="wikigeneratedid" %)
puchades 33.1 84 If you would like to work with an EBRAINS dataset, fetch the LocaliZoom link from the KG dataset card ( [[https:~~/~~/search.kg.ebrains.eu>>https://search.kg.ebrains.eu]] )and paste it in the "Import LocaliZoom link" tab.
puchades 28.1 85
86 (% class="wikigeneratedid" %)
87 These series already have been registered to a reference atlas, so this gives you a starting point. The linear registrations obtained with WebAlign can be refined using WebWarp.
88
puchades 3.1 89 === Registration instructions ===
90
91 **Short keys**
92
93 |=To do this|=Press|=Description
94 |Place marker|Space bar|Markers are the anchor points of most transformations (stretch and rotate).
95 |Remove marker|Esc|Removes a previously placed marker.
96 |Horizontal stretch from marker |Left/Right arrow keys|Marker becomes a vertical line, and mouse drag horizontally resizes the cut.
97 |Vertical stretch from marker |Up/Down arrow keys|Marker becomes a horizontal line, and mouse drag vertically resizes the cut
98 |Rotate around marker|PgUp/PgDown|Marker becomes a cross with a surrounding arc, and mouse drag rotates the cut.
99 |In plane adjust |Click + drag|If there is no marker, or the marker is a cross, mouse drag slides the cut in its plane (translation).
100
101 **Start the registration**
102
103 The main window shows the selected image with the atlas overlay.
104
105 -If necessary, change the atlas from coronal view to sagittal or horizontal view (see Navigation panel below)
106
107 ~1. Move the atlas to the approximate position of your section using the yellow dots in the three small windows from the navigation panel.
108
109 2. Start anchoring by placing a marker with the //"Space bar//" , it is initially a cross, and it is the fix point of (most) transformations. The "//Escape key//" can be used to remove the marker.
110
111 3. The main window supports mouse drag in multiple modes in order to stretch the atlas and find the correct position.
112
113 -If there is no marker, or the marker is a cross, mouse drag slides the cut in its plane (translation).
114
115 -Keyboard controls to modify mouse drag (they also place the marker if it's not placed already):
116
117 -Left/Right arrow keys: marker becomes a vertical line, and mouse drag horizontally resizes the cut
118
119 -Up/Down arrow keys: marker becomes a horizontal line, and mouse drag vertically resizes the cut
120
121 -PgUp/PgDown keys: marker becomes a cross with a surrounding arc, and mouse drag rotates the cut. This may look weird because the cut remains being a rectangle, and when  the horizontal and vertical physical resolutions (like pixels/mm) of the image do not match, atlas cut will appear stretching/shrinking with the rotation.
122
123 After each transformation step, marker resets to a cross (translation mode).
124
125 //Note!// The panel can be resized towards the left (common border with Control Panel) and towards the bottom (common border with Filmstrip).
126
127 4. Save the position by pressing //"Store". //The registration is copied to the remaining slides to help with scaling (visible also in the filmstrip)
128
129 5. Go through all sections and refine position and cutting angles.
130
131 //Note!// When jumping from one section to the other, wait a few seconds for the image to load
132
133 //Note!// The "restore" button allows you to go back to the saved position if necessary
134
135 6. Save your results in the descriptor file (json) by pressing "Save to bucket".
136
137 7. When the registration is finished, you can export your descriptor files ( .flat files used for analysis in the QUINT workflow) by pressing //"export overlays".//
138
139 **Control panel:**
140
141 |=Button|=Function
142 |Store |Store the current alignment and propagate to unaligned sections (**Note** this does not save the series to your bucket)
143 |Restore |Reset the current alignment to the last stored position
144 |Clear |Reset the current alignment to the default position
145 |Overlay Slider |Opacity of the atlas overlay, when fully opaque, it becomes an outline
146 |Overlay color |The outline color
147 |Filmstrip slider and color|The above settings, applied to the filmstrip
148 |Save to bucket|Save the series to your bucket (and overwrite the existing file)
149 |Export overlays|Generates a series of .flat files (for Nutil or similar utility), and stores them into a .zip file in the bucket (re-using the name of the series descriptor, e.g. series13.json will export series13.zip)
150
151
152 The right border of the control panel can be dragged horizontally, allowing to resize the panel and the main view
153
154 **Filmstrip:**
155
156 Drag horizontally to see series, click on a section in order to load it into the main view The top border of the filmstrip can be dragged vertically, allowing to resize the panel and the main view
157
158 **Navigation panel:**
159
160 Shows the three standard planes centered around the midpoint of the current alignment visible in the main view.
161
162 The rectangle of the current cut is projected on each standard plane as a yellow line/rectangle/parallelogram. A small yellow circle represents the midpoint of the projection.
163
164 Drag the midpoint around to move the cut.
165
puchades 31.1 166 Drag anywhere else to rotate the cut (inside the given standard plane, around the midpoint).
167
puchades 32.1 168 == **How to use WebWarp** ==
puchades 33.2 169
170 WebWarp is an online tool for nonlinear refinement of spatial registration of histological section images from rodent brains to reference 3D atlases. Webwarp is compatible with registration performed with the WebAlign tool. Different experimental datasets registered to the same reference atlas allows you to spatially integrate, analyse and navigate these datasets within a standardised coordinate system.
171
172 Online user manual: [[https:~~/~~/webwarp.readthedocs.io/en/latest/>>https://webwarp.readthedocs.io/en/latest/]]
173
174 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
175
176 === Opening a sample dataset ===
177
178 Demo dataset is loaded using the file: **demo_mouse_data.waln**
179
180 You can see the result of a finished anchoring by choosing the file: **demo_mouse_data.wwrp**
181
puchades 34.1 182 === Opening a private dataset ===
183
puchades 39.2 184 (% class="wikigeneratedid" %)
185 All the .waln files located in the Bucket are displayed on the WebWarp main page. Your progress in WebWarp is saved as a .wwrp file.
186
187 === Opening an EBRAINS dataset ===
188
189 If you would like to work with an EBRAINS dataset, open the LocaliZoom link from the KG dataset card ( [[https:~~/~~/search.kg.ebrains.eu>>url:https://search.kg.ebrains.eu]]) and paste it in the "Import LocaliZoom link" tab in WebAlign. Save this series as a .waln file you then can open in WebWarp.
190
191 === Non-linear registration ===
192
puchades 34.1 193 1. Navigate to the WebWarp app in the left-hand panel: all the .waln files located in the Bucket are displayed on the WebWarp main page.
194 1. Select the waln file corresponding to your result from the WebAlign image registration.
195 1. Wait for the images to load: this may take some time.
196
puchades 54.1 197 [[~[~[image:image1.png~|~|alt="_images/image1.png"~]~]>>url:https://webwarp.readthedocs.io/en/latest/_images/image1.png]]
puchades 34.1 198
puchades 39.2 199 Your registered images are visible in the main window. The atlas regions with transparency sliders can be toggled using the “Atlas opacity” button. The color of the atlas outline can be modified by clicking on the colored rectangle.
puchades 34.2 200
puchades 40.1 201 4. When going to “Settings”, the button for selecting the marker color will appear as well as “show triangles” which correspond to areas affected by the same    transformation.
puchades 34.2 202
puchades 39.2 203 5. Place a marker on an area you want to stretch using the space bar. Nonlinear distortions are applied by dragging a marker using the mouse.
204
205 6. Press Delete or Backspace to remove a marker under the mouse cursor.
206
puchades 40.1 207 7. Save your results pression the “save” button. “Save as” will allow you to save the adjustments as a new file with a different name.
puchades 39.2 208
puchades 40.1 209 8. When the registration is finished, you can export your descriptor files ( .seg files used for analysis in the QUINT workflow) by pressing “export overlays”. All results are zipped and stored in the bucket. The result file name will be the same as the one chosen to create the registration, e.g. “my-registration.zip”.
puchades 39.2 210
puchades 40.1 211
puchades 39.2 212
213
puchades 34.2 214 == **How to use LocaliZoom** ==
215
puchades 36.1 216 LocaliZoom is a web application for viewing of series of high-resolution 2D images that have been anchored to reference atlases. LocaliZoom allows the viewing and exploring of high-resolution images with superimposed atlas overlays, and the extraction of coordinates of annotated points within those images for viewing in 3D brain atlas space.
puchades 34.2 217
puchades 36.1 218 Online Manual: [[https:~~/~~/localizoom.readthedocs.io/en/latest/>>https://localizoom.readthedocs.io/en/latest/]]
219
220 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
221
222 === Opening a sample dataset ===
223
224 A demo dataset is loaded using the file: demo_mouse_data_lz
225
puchades 41.2 226 === Opening a private or EBRAINS dataset ===
puchades 36.1 227
puchades 41.2 228 LocaliZoom will open all WebAlign (.waln) or WebWarp (.wwrp) files.
puchades 36.1 229
puchades 41.2 230 === Create annotation points ===
puchades 35.1 231
puchades 42.1 232 To extract a coordinate, the mouse marker must be positioned at the desired location, and press the space bar. A cross will appear in the selected colour (under Settings), representing the location of the extracted coordinate. After all desired points have been marked, the coordinates can be exported either to Excel.
puchades 41.2 233
puchades 42.1 234 Press "delete" in order to remove an annotation.
puchades 41.2 235
puchades 42.1 236 Save your annotations with the "save" or "save as" buttons. The file format is .lz
237
puchades 41.2 238 === Export of coordinate points ===
239
puchades 42.1 240 The created points can be exported to an Excel book by pressing "XLSX export".
puchades 41.2 241
puchades 42.2 242 The saved .lz file can also be visualised in the 3D viewer, MeshView.
puchades 42.1 243
puchades 37.1 244 == **How to use MeshView** ==
puchades 35.1 245
puchades 44.1 246 MeshView is a web application for real-time 3D display of surface mesh data representing structural parcellations from volumetric atlases, and point clouds extracted from datasets.
puchades 35.1 247
puchades 44.1 248 Online manual: [[https:~~/~~/meshview-for-brain-atlases.readthedocs.io/en/latest>>https://meshview-for-brain-atlases.readthedocs.io/en/latest]]
249
250 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
251
252 === Open point cloud files ===
253
puchades 49.1 254 MeshView can open annotations from LocaliZoom (.lz files). Possibility of a global control of all structures, using the slider will render the meshes transparent or disappear.
puchades 44.1 255
puchades 50.1 256 The individual control allow each structure to be made transparent or disappear. The color for each structure can be changed when clicking on the colored square.
puchades 49.1 257
258 Navigation in the hierarchy is possible by clicking on the region names (grey boxes), this will collapse parts of the region tree.
259
puchades 48.1 260 === Export images ===
261
puchades 47.1 262 The "screenshot" button allows to capture the main window view as a png file.
263
puchades 46.1 264 [[image:image19.png]]
puchades 47.1 265
266