View source for Walkthrough on filament models

This walkthrough is a step-by-step guide that teaches how to extract subtomograms from filament-like structures using the ''Dynamo'' filament models.

= Data =
We are going to demonstrate the basic ideas and tools on a synthetic dataset. This data is already available in the catalogue manager. It can be accessed by first opening the catalogue manager using the command:
 <tt>dcm</tt>
After the catalogue manager opens, we create the synthetic tomogram that includes tubular looking objects (filaments) in the following way:

[[ File:filament_step_1.png |thumb|center| 700px|]]

A new tomogram entry appears in the catalogue manager. Any further annotations (models) to the tomogram will be linked to this entry. Select the entry and open it:

[[ File:filament_step_2.png |thumb|center| 700px|]]

A tomogram viewer opens. You might need to adjust the contrast (blue arrow). To move through the tomogram slices, you can either use the mouse wheel, click and drag the tomogram slice up and down (orange arrows), or move the ''position'' control left and right (orange box).

[[ File:filament_step_3.png |thumb|center| 700px|]]

= Manual annotation =

To be able to later annotate a filament of interest, we first create an alternative view by using the ''anchor points''. We start by marking the beginning of a filament. Move the slice up to a high z height. Place the mouse in the center of a filament and press the key [1] on the keyboard to place an anchor in the beginning of the filament. Note: to correct the anchor point just click the [1] key again.

[[ File:filament_step_4.png |thumb|center| 700px|]]

To mark the end of the filament, move to a low z-height. Place the mouse in the center of the same filament and press the key [2] on the keyboard to place the anchor in the end of the filament.

[[ File:filament_step_5.png |thumb|center| 700px|]]

Finally, a third anchor point (key [3]) is placed to define the width of the alternative view that we are creating:

[[ File:filament_step_6.png |thumb|center| 700px|]]

Click on ''set plane'' (orange box) to define a plane along the anchor points:

[[ File:filament_step_7.png |thumb|center| 700px|]]

Use the ''anchor for plane selection'' control (orange box) to activate and rotate the viewing plane around the filament:

[[ File:filament_step_8.png |thumb|center| 700px|]]

Annotations are done within a so called ''model''. We open a new model of type ''filament'' as follows:

[[ File:filament_step_9.png |thumb|center| 700px|]]

If necessary, click and drag while holding the control key to rotate the view of the tomogram to get a good view of the filament:

[[ File:filament_step_10.png |thumb|center| 700px|]]

To add annotation points to the model, place the mouse on the filament and press the key [c]. Use the right-click to delete points if needed. Note: A known bug may cause the clicked points to be generated slightly displaced from the mouse cursor. Maximize the window of the tomogram viewer to get rid of this effect. Generate about 10 points:

[[ File:filament_step_11.png |thumb|center| 700px|]]

We show you an alternative way to click the points on the filament. To demonstrate this, we first delete the current points as shown below:

[[ File:filament_step_12.png |thumb|center| 700px|]]

We create a new model in the same way as before:

[[ File:filament_step_9.png |thumb|center| 700px|]]

For this alternative method, we first create a view of orthogonal slices through the filament. In ''tools for filaments'' set sidelength to 64 and thickness to 10 (see orange box). Then click on ''extract'' (see orange box): 

[[ File:filament_step_13.png |thumb|center| 700px|]]

You get a new window with the view of the orthogonal slices through the filament:

[[ File:filament_step_14.png |thumb|center| 500px|]]

Same as before, using the [c] key, add model points at the center of the tube filament:

[[ File:filament_step_15.png |thumb|center| 500px|]]

When done, close the window and you should see your clicked points in the main view:

[[ File:filament_step_16.png |thumb|center| 700px|]]

= Generate subtomogram coordinates =

Using the clicked model we can now define the coordinates where the subvolumes will be extracted. To do that, we first processes the clicked model points using the ''model workflow'' to generate a user specific cropping geometry. Open the workflow:

[[ File:filament_step_17.png |thumb|center| 700px|]]

You get a new window with the model workflow. It has three large buttons (and corresponding input parameters below) that are executed sequentially starting from top. Click on ''create a smooth backbone'':

[[ File:filament_step_18.png |thumb|center| 500px|]]

This creates an interpolation through the points in the model. Visualize it by left-clicking on ''view'':

[[ File:filament_step_19.png |thumb|center| 700px|]]

Add the clicked model points to the graph:

[[ File:filament_step_20.png |thumb|center| 700px|]]

This looks good. We now create coordinates along this interpolation (backbone) which will be used as centers for the subtomogram extraction (cropping). Click on ''create final positions and angles for particle cropping''. Ignore the angles, as they are not part of this model. Visualize the crop positions: 

[[ File:filament_step_21.png |thumb|center| 700px|]]

You can see that these are too many crop points. Adjust the spacing between the cropping points by changing the parameter ''subunits dz'' from 2 to 20 (see orange box). Click again ''create final positions and angles for particle cropping'' to update the information and visualize the new crop points:

[[ File:filament_step_22.png |thumb|center| 700px|]]

This looks much better. Save the model by clicking on '' save resulting model into catalogue'' and we can move to the subtomogram extraction.

= Extract subtomograms = 

In this final step we extract subvolumes at the coordinates defined before. First, open the partcile extraction GUI:

[[ File:filament_step_23.png |thumb|center| 700px|]]

Set the sidelength to 64 and click on ''start cropping'' (orange box):

[[ File:filament_step_24.png |thumb|center| 500px|]]

To see the results, click on ''ddbrowse'' (orange box):


[[ File:filament_step_245.png |thumb|center| 500px|]]


In the new window activate the table, select the axis and click on show (orange boxes):

[[ File:filament_step_25.png |thumb|center| 500px|]]

For the z and x axis you should see results similar to the following. These are 2D representations (projections) of the actually cropped 3D subtomograms:

[[ File:filament_step_26.png |thumb|center| 700px|]]