Version 9.1 by puchades on 2023/06/21 10:19
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. Give users Admin, Editor or Viewer rights by clicking** Team** in the navigation panel.
6 1. Install WebAlign, LocaliZoom, and Meshview from the EBRAINS Collaboratory App Store (see instructions below)
7
8 == How to install Collaboratory Apps ==
9
10 1. To install Collaboratory Apps, click on the + Create button (top right corner).
11 1. Give the page a Title (for example, WebAlign), select the Community App option, and click Create.
12 1. Select the App to install (for example, WebAlign), and click Save and View.
13 1. Repeat this for all the relevant Community Apps.
14 1. Navigate between the Apps in the navigation panel. File transfer between the Apps is through the Bucket.
15
16 == How to prepare your images? ==
17
18 **~1. Prepare your images before upload by naming them according this naming convention:**
19
20 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).
21
22 Example: tg2345_MMSH_s001.tif
23
24 - Upload the images you want to work with into the bucket of your collab using the Data proxy (press on //"Bucket"//)
25
26 **2. Image ingestion**
27
28 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:
29
30 (% class="wikigeneratedid" %)
31 === ===
32
33 === Use the "QUINT image creator" app ===
34
35 **~1. Select images to ingest**
36
37 Shift-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
46
47
48 == ==
49
50 === Use Image service app ===
51
52 **~1. Start the Image service UI from your webapp**
53
54 **2. 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"]]
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||height="427" width="900"]]
73
74 - Customize your ingestion:
75
76 - give a name to your ingestion in the "description of ingestion" field.
77
78 **3. For obtaining chunks in DZI format  (compatible with WebAlign),** choose "2D" and "not stack of Images".
79
80 **4. Click //"preview"// in order to preview your task**
81
82 **5. Click //"create task"//  to launch your ingestion**
83
84 **6. Checking results in the Main UI page**
85
86 Press "Task" in the higher right corner of the window.
87
88 When creating the task, a red banner is displayed in the "Create Task" view if something goes wrong for instance.
89
90 Otherwise, you will be redirected to the tasks list where the created task is selected.
91
92 //Note! //A task will be first "Queued" then "Running"; "Stagingout"and ultimately "Successful" or "Failed"
93
94 Refresh your browser in order to check the status of your task.
95
96 When "successful", your chunks have been created.
97
98 == ==
99
100 === Use Image service app ===
101
102 **~1. Start the Image service UI from your webapp**
103
104 **2. Fill in the requested information:**
105
106 - type or paste the URL of the dataset folder containing the images. //Note!// the name of the collab supports only hyphens.
107
108 E.g. https:~/~/data-proxy.ebrains.eu/api/v1/buckets/name-of-my-collab
109
110 - 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.
111
112 - 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"
113
114 - Or use a prefix: E.g. https:~/~/data-proxy.ebrains.eu/api/v1/buckets/name-of-my-collab?prefix=name_of_the_data_folder
115
116 - allow the image service to access your bucket
117
118 [[image:Skjermbilde 2022-02-08 103443.png||height="199" width="500"]]
119
120 - 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)
121
122 [[image:create collab.png||height="427" width="900"]]
123
124 - Customize your ingestion:
125
126 - give a name to your ingestion in the "description of ingestion" field.
127
128 **3. For obtaining chunks in DZI format  (compatible with WebAlign),** choose "2D" and "not stack of Images".
129
130 **4. Click //"preview"// in order to preview your task**
131
132 **5. Click //"create task"//  to launch your ingestion**
133
134 **6. Checking results in the Main UI page**
135
136 Press "Task" in the higher right corner of the window.
137
138 When creating the task, a red banner is displayed in the "Create Task" view if something goes wrong for instance.
139
140 Otherwise, you will be redirected to the tasks list where the created task is selected.
141
142 //Note! //A task will be first "Queued" then "Running"; "Stagingout"and ultimately "Successful" or "Failed"
143
144 Refresh your browser in order to check the status of your task.
145
146 When "successful", your chunks have been created.
147
148 == ==
149
150 === Use Image service app ===
151
152 **~1. Prepare your images before upload by naming them according this naming convention:**
153
154 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).
155
156 Example: tg2345_MMSH_s001_segmentation.png
157
158 - Upload the images you want to work with into the bucket of your collab using the Data proxy (press on //"Bucket"//)
159
160 **2. Start the Image service UI from your webapp**
161
162 **3. Fill in the requested information:**
163
164 - type or paste the URL of the dataset folder containing the images. //Note!// the name of the collab supports only hyphens.
165
166 E.g. https:~/~/data-proxy.ebrains.eu/api/v1/buckets/name-of-my-collab
167
168 - 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.
169
170 - 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"
171
172 - Or use a prefix: E.g. https:~/~/data-proxy.ebrains.eu/api/v1/buckets/name-of-my-collab?prefix=name_of_the_data_folder
173
174 - allow the image service to access your bucket
175
176 [[image:Skjermbilde 2022-02-08 103443.png||height="199" width="500"]]
177
178 - 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)
179
180 [[image:create collab.png||height="427" width="900"]]
181
182 - Customize your ingestion:
183
184 - give a name to your ingestion in the "description of ingestion" field.
185
186 **3. For obtaining chunks in DZI format  (compatible with WebAlign),** choose "2D" and "not stack of Images".
187
188 **4. Click //"preview"// in order to preview your task**
189
190 **5. Click //"create task"//  to launch your ingestion**
191
192 **6. Checking results in the Main UI page**
193
194 Press "Task" in the higher right corner of the window.
195
196 When creating the task, a red banner is displayed in the "Create Task" view if something goes wrong for instance.
197
198 Otherwise, you will be redirected to the tasks list where the created task is selected.
199
200 //Note! //A task will be first "Queued" then "Running"; "Stagingout"and ultimately "Successful" or "Failed"
201
202 Refresh your browser in order to check the status of your task.
203
204 When "successful", your chunks have been created.
205
206 == **How to use WebAlign** ==
207
208 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.
209
210 Online user manual: [[https:~~/~~/webalign.readthedocs.io/en/latest/>>https://webalign.readthedocs.io/en/latest/]]
211
212 The view can be magnified using the 4-arrow "X" symbol in the top-right corner.
213
214 === Opening a sample dataset ===
215
216 Demo dataset is loaded using the file: **demo_mouse_data_start**
217
218 You can see the result of a finished anchoring by choosing the file: **demo_mouse_data**
219
220 === Opening a private dataset ===
221
222 After you have uploaded your images to the bucket and ingested your images with the Image service, this has generated DZI chunks. These DZI files are used by WebAlign.
223
224 ~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
225
226 2. WebAlign will search for DZI files and list those found.
227
228 3. Enter a name for the descriptor json file which will be created and will contain your anchoring information.
229
230 4. Choose the target 3D reference atlas (WHSv3 for Rat and CCFv3_2017 for Mouse).
231
232 5. Press //"create"//. The main window will now display WebAlign. This step can take some time.
233
234 === Registration instructions ===
235
236 **Short keys**
237
238 |=To do this|=Press|=Description
239 |Place marker|Space bar|Markers are the anchor points of most transformations (stretch and rotate).
240 |Remove marker|Esc|Removes a previously placed marker.
241 |Horizontal stretch from marker |Left/Right arrow keys|Marker becomes a vertical line, and mouse drag horizontally resizes the cut.
242 |Vertical stretch from marker |Up/Down arrow keys|Marker becomes a horizontal line, and mouse drag vertically resizes the cut
243 |Rotate around marker|PgUp/PgDown|Marker becomes a cross with a surrounding arc, and mouse drag rotates the cut.
244 |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).
245
246 **Start the registration**
247
248 The main window shows the selected image with the atlas overlay.
249
250 -If necessary, change the atlas from coronal view to sagittal or horizontal view (see Navigation panel below)
251
252 ~1. Move the atlas to the approximate position of your section using the yellow dots in the three small windows from the navigation panel.
253
254 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.
255
256 3. The main window supports mouse drag in multiple modes in order to stretch the atlas and find the correct position.
257
258 -If there is no marker, or the marker is a cross, mouse drag slides the cut in its plane (translation).
259
260 -Keyboard controls to modify mouse drag (they also place the marker if it's not placed already):
261
262 -Left/Right arrow keys: marker becomes a vertical line, and mouse drag horizontally resizes the cut
263
264 -Up/Down arrow keys: marker becomes a horizontal line, and mouse drag vertically resizes the cut
265
266 -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.
267
268 After each transformation step, marker resets to a cross (translation mode).
269
270 //Note!// The panel can be resized towards the left (common border with Control Panel) and towards the bottom (common border with Filmstrip).
271
272 4. Save the position by pressing //"Store". //The registration is copied to the remaining slides to help with scaling (visible also in the filmstrip)
273
274 5. Go through all sections and refine position and cutting angles.
275
276 //Note!// When jumping from one section to the other, wait a few seconds for the image to load
277
278 //Note!// The "restore" button allows you to go back to the saved position if necessary
279
280 6. Save your results in the descriptor file (json) by pressing "Save to bucket".
281
282 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".//
283
284 **Control panel:**
285
286 |=Button|=Function
287 |Store |Store the current alignment and propagate to unaligned sections (**Note** this does not save the series to your bucket)
288 |Restore |Reset the current alignment to the last stored position
289 |Clear |Reset the current alignment to the default position
290 |Overlay Slider |Opacity of the atlas overlay, when fully opaque, it becomes an outline
291 |Overlay color |The outline color
292 |Filmstrip slider and color|The above settings, applied to the filmstrip
293 |Save to bucket|Save the series to your bucket (and overwrite the existing file)
294 |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)
295
296
297 The right border of the control panel can be dragged horizontally, allowing to resize the panel and the main view
298
299 **Filmstrip:**
300
301 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
302
303 **Navigation panel:**
304
305 Shows the three standard planes centered around the midpoint of the current alignment visible in the main view.
306
307 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.
308
309 Drag the midpoint around to move the cut.
310
311 Drag anywhere else to rotate the cut (inside the given standard plane, around the midpoint)