Version 53.1 by puchades on 2023/07/05 09:25
Show last authors
1 == To set up your working environment: ==
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.
5 1. Remember to set your data proxy bucket to "public". Your collab can still be private.
6 1. Give users Admin, Editor or Viewer rights by clicking** Team** in the navigation panel.
7 1. Install WebAlign, WebWarp, LocaliZoom, and Meshview from the EBRAINS Collaboratory App Store (see instructions below)[[image:public_data_proxy_bucket.png]]
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.
13 1. Select the App to install (for example, WebAlign), and click Save and View.
14 1. Repeat this for all the relevant Community Apps. You will need, "QUINT Image creator app"; "WebAlign"; "WebWarp"; "LocaliZoom" and "MeshView".
15 1. Navigate between the Apps in the navigation panel. File transfer between the Apps is through the Bucket.
16
17 == How to prepare your images? ==
18
19 **~1. Prepare your images before upload by naming them according this naming convention:**
20
21 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).
22
23 Example: tg2345_MMSH_s001.tif
24
25 - Upload the images you want to work with into the bucket of your collab using the Data proxy (press on //"Bucket"//)
26
27 **2. Image ingestion**
28
29 Two alternatives are available, the QUINT image creator app, which is automatically creating the necessary files for downstream analyses in your collab. Or, you can use the image service app which is able to create image tiles in different formats. The steps for preparing your files are described bellow:
30
31 === Use the "QUINT image creator" app ===
32
33 (% style="color:#e67e22" %)NB! we are still working on this app for the moment. For the enabling viewer links,  make your bucket "public". The collab can still be "private".
34
35 **2a. Select images to ingest**
36
37 Click on your images in order to select them and press the "create brain from selection" button. Choose a name for your serie.
38
39 The App will automatically generate the files for you. Monitor the progress under the "processing" tab and on the two dashboards on the left.
40
41 When the ingestion is finished, your serie will appear under the "Prepared Brains" tab.
42
43 Click on the "View Brain" button in order to preview your images.
44
45 Now go to the WebAlign app in order to start the registration to atlas.
46
47 [[image:Screenshot create_brain app.png]]
48
49
50 === Use Image service app (alt.) ===
51
52 **2b. Start the Image service UI from your webapp**
53
54 * ** Fill in the requested information:**
55
56 - type or paste the URL of the dataset folder containing the images. //Note!// the name of the collab supports only hyphens.
57
58 E.g. https:~/~/data-proxy.ebrains.eu/api/v1/buckets/name-of-my-collab
59
60 - you can filter the data using RegEx expressions. E.g. name_of_the_data_file.*\.jpg$ (for filtering jpeg files only). Or e.g hbp-00173_262_1366_1827.*\.tif$ for tiff files.
61
62 - If your URL is valid, you will see the list of files by pressing "yes". Paste the name of the file you want to select. You can go back to the previous step  by pressing "back"
63
64 - Or use a prefix: E.g. https:~/~/data-proxy.ebrains.eu/api/v1/buckets/name-of-my-collab?prefix=name_of_the_data_folder
65
66 - allow the image service to access your bucket
67
68 [[[[image:Skjermbilde 2022-02-08 103443.png||height="199" width="500"]]>>attach:Skjermbilde 2022-02-08 103443.png]]
69
70 - Store your results: Choose "create a new collab" where your ingested chunks will be stored in the bucket. This option is preferred in order not to overload the Bucket of your current  collab. Give a name to your Bucket as well as a name for the  collab (bucket slug) (see this illustration for more info)
71
72 [[image:create collab.png]]
73
74 - Customize your ingestion:
75
76 - give a name to your ingestion in the "description of ingestion" field.
77
78 * ** For obtaining chunks in DZI format  (compatible with WebAlign),** choose "2D" and "not stack of Images".
79 * ** Click //"preview"// in order to preview your task**
80 * ** Click //"create task"//  to launch your ingestion**
81 * ** Checking results in the Main UI page**
82
83 Press "Task" in the higher right corner of the window.
84
85 When creating the task, a red banner is displayed in the "Create Task" view if something goes wrong for instance.
86
87 Otherwise, you will be redirected to the tasks list where the created task is selected.
88
89 //Note! //A task will be first "Queued" then "Running"; "Stagingout"and ultimately "Successful" or "Failed"
90
91 Refresh your browser in order to check the status of your task.
92
93 When "successful", your chunks have been created.
94
95 == **How to use WebAlign** ==
96
97 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.
98
99 Online user manual: [[https:~~/~~/webalign.readthedocs.io/en/latest/>>https://webalign.readthedocs.io/en/latest/]]
100
101 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
102
103 === Opening a sample dataset ===
104
105 Demo dataset is loaded using the file: **demo_mouse_data_start.waln**
106
107 You can see the result of a finished anchoring by choosing the file: **demo_mouse_data.waln**
108
109 === Opening a private dataset ===
110
111 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.
112
113 ~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
114
115 2. WebAlign will search for DZIP files and list those found.
116
117 3. Enter a name for the descriptor json file which will be created and will contain your anchoring information.
118
119 4. Choose the target 3D reference atlas (WHSv3 for Rat and CCFv3_2017 for Mouse).
120
121 5. Press //"create"//. The main window will now display WebAlign. This step can take some time.
122
123 [[image:create series webAlign.png]]
124
125 === Opening an EBRAINS dataset ===
126
127 (% class="wikigeneratedid" %)
128 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.
129
130 (% class="wikigeneratedid" %)
131 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.
132
133 === Registration instructions ===
134
135 **Short keys**
136
137 |=To do this|=Press|=Description
138 |Place marker|Space bar|Markers are the anchor points of most transformations (stretch and rotate).
139 |Remove marker|Esc|Removes a previously placed marker.
140 |Horizontal stretch from marker |Left/Right arrow keys|Marker becomes a vertical line, and mouse drag horizontally resizes the cut.
141 |Vertical stretch from marker |Up/Down arrow keys|Marker becomes a horizontal line, and mouse drag vertically resizes the cut
142 |Rotate around marker|PgUp/PgDown|Marker becomes a cross with a surrounding arc, and mouse drag rotates the cut.
143 |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).
144
145 **Start the registration**
146
147 The main window shows the selected image with the atlas overlay.
148
149 -If necessary, change the atlas from coronal view to sagittal or horizontal view (see Navigation panel below)
150
151 ~1. Move the atlas to the approximate position of your section using the yellow dots in the three small windows from the navigation panel.
152
153 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.
154
155 3. The main window supports mouse drag in multiple modes in order to stretch the atlas and find the correct position.
156
157 -If there is no marker, or the marker is a cross, mouse drag slides the cut in its plane (translation).
158
159 -Keyboard controls to modify mouse drag (they also place the marker if it's not placed already):
160
161 -Left/Right arrow keys: marker becomes a vertical line, and mouse drag horizontally resizes the cut
162
163 -Up/Down arrow keys: marker becomes a horizontal line, and mouse drag vertically resizes the cut
164
165 -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.
166
167 After each transformation step, marker resets to a cross (translation mode).
168
169 //Note!// The panel can be resized towards the left (common border with Control Panel) and towards the bottom (common border with Filmstrip).
170
171 4. Save the position by pressing //"Store". //The registration is copied to the remaining slides to help with scaling (visible also in the filmstrip)
172
173 5. Go through all sections and refine position and cutting angles.
174
175 //Note!// When jumping from one section to the other, wait a few seconds for the image to load
176
177 //Note!// The "restore" button allows you to go back to the saved position if necessary
178
179 6. Save your results in the descriptor file (json) by pressing "Save to bucket".
180
181 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".//
182
183 **Control panel:**
184
185 |=Button|=Function
186 |Store |Store the current alignment and propagate to unaligned sections (**Note** this does not save the series to your bucket)
187 |Restore |Reset the current alignment to the last stored position
188 |Clear |Reset the current alignment to the default position
189 |Overlay Slider |Opacity of the atlas overlay, when fully opaque, it becomes an outline
190 |Overlay color |The outline color
191 |Filmstrip slider and color|The above settings, applied to the filmstrip
192 |Save to bucket|Save the series to your bucket (and overwrite the existing file)
193 |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)
194
195
196 The right border of the control panel can be dragged horizontally, allowing to resize the panel and the main view
197
198 **Filmstrip:**
199
200 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
201
202 **Navigation panel:**
203
204 Shows the three standard planes centered around the midpoint of the current alignment visible in the main view.
205
206 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.
207
208 Drag the midpoint around to move the cut.
209
210 Drag anywhere else to rotate the cut (inside the given standard plane, around the midpoint).
211
212 == **How to use WebWarp** ==
213
214 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.
215
216 Online user manual: [[https:~~/~~/webwarp.readthedocs.io/en/latest/>>https://webwarp.readthedocs.io/en/latest/]]
217
218 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
219
220 === Opening a sample dataset ===
221
222 Demo dataset is loaded using the file: **demo_mouse_data.waln**
223
224 You can see the result of a finished anchoring by choosing the file: **demo_mouse_data.wwrp**
225
226 === Opening a private dataset ===
227
228 (% class="wikigeneratedid" %)
229 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.
230
231 === Opening an EBRAINS dataset ===
232
233 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.
234
235 === Non-linear registration ===
236
237 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.
238 1. Select the waln file corresponding to your result from the WebAlign image registration.
239 1. Wait for the images to load: this may take some time.
240
241 [[[[image:image1.png||alt="_images/image1.png"]]>>url:https://webwarp.readthedocs.io/en/latest/_images/image1.png]]
242
243 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.
244
245 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.
246
247 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.
248
249 6. Press Delete or Backspace to remove a marker under the mouse cursor.
250
251 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.
252
253 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”.
254
255
256
257
258 == **How to use LocaliZoom** ==
259
260 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.
261
262 Online Manual: [[https:~~/~~/localizoom.readthedocs.io/en/latest/>>https://localizoom.readthedocs.io/en/latest/]]
263
264 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
265
266 === Opening a sample dataset ===
267
268 A demo dataset is loaded using the file: demo_mouse_data_lz
269
270 === Opening a private or EBRAINS dataset ===
271
272 LocaliZoom will open all WebAlign (.waln) or WebWarp (.wwrp) files.
273
274 === Create annotation points ===
275
276 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.
277
278 Press "delete" in order to remove an annotation.
279
280 Save your annotations with the "save" or "save as" buttons. The file format is .lz
281
282 === Export of coordinate points ===
283
284 The created points can be exported to an Excel book by pressing "XLSX export".
285
286 The saved .lz file can also be visualised in the 3D viewer, MeshView.
287
288 == **How to use MeshView** ==
289
290 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.
291
292 Online manual: [[https:~~/~~/meshview-for-brain-atlases.readthedocs.io/en/latest>>https://meshview-for-brain-atlases.readthedocs.io/en/latest]]
293
294 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
295
296 === Open point cloud files ===
297
298 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.
299
300 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.
301
302 Navigation in the hierarchy is possible by clicking on the region names (grey boxes), this will collapse parts of the region tree.
303
304 === Export images ===
305
306 The "screenshot" button allows to capture the main window view as a png file.
307
308 [[image:image19.png]]
309
310