Difference between revisions of "Filament model"

From Dynamo
Jump to navigation Jump to search
 
(25 intermediate revisions by the same user not shown)
Line 1: Line 1:
Filament models are used for geometries where location and orientation of particles can be defined with relation to tubular estructures.
+
Filament models are used for geometries where location and orientation of particles to be cropped (called ''subunits''in this context) can be defined with relation to tubular estructures.  
 
 
The usual way of handling them is by opening a small fraction of a  tomogram inside <tt>dtmslice</tt> and mark manually positions that will be used to define a "backbone". Loosely speaking, we call the " ''backbone'' of the filament" to the series of ordered points that arise from defining successive orthogonal sections along the path of the filament and picking the central point. Different models are available for the different relationships between the "backbone" of the filament and the locations and positions of the particles to be cropped. 
 
  
 +
The usual way of handling them is by opening a small fraction of a  tomogram inside <tt>dtmslice</tt> and mark manually positions that will be used to define a "backbone". Loosely speaking, we call the "''backbone'' of the filament" to the series of ordered points that arise from defining successive orthogonal sections along the path of the filament and picking the central point. Different models are available for the different relationships between the "backbone" of the filament and the locations and positions of the particles to be cropped.
  
 
==Input stage==
 
==Input stage==
Line 8: Line 7:
  
 
===Clicking input points in <tt>dtmslice</tt>===
 
===Clicking input points in <tt>dtmslice</tt>===
 +
A [[https://www.youtube.com/watch?v=hsZ-9xAYufI video tutorial]] explains with detail the process of picking points and  converting them into subunit locations.
 +
 +
The basic tool for tracking filaments is <tt>dtmslice</tt>. In this tools, creating the points of a filament can be done manually in three steps:
 +
# Select extremal points,
 +
# Create orthogonal sections
 +
# Click on the center of each section.
 +
 +
==== Select extremal points (anchors) ====
 +
 +
Click on <tt>[1]</tt> and <tt>[2]</tt> to select two extremal points in the filament, typically in two different sections. <tt>[1]</tt> will appear as a red diamond, <tt>[2]</tt> appears as a blue diamond.
 +
 +
{|style="margin: 0 auto;"
 +
| [[File:filamentAnchor1.png|thumb|upright|400px| Click on anchor 1]]
 +
| [[File:filamentAnchor2.png|thumb|upright|400px| Click on anchor 2]]
 +
|}
 +
 +
==== Create orthogonal sections ====
 +
 +
In the <tt>Filament Tools</tt> panel, you can select a partition of the space between the anchor points. The default value is <tt>1:10:100</tt>, meaning: "divide the distance between the anchor points in 100 parts, and create an orthogonal section every 10 points".
 +
 +
You can also select a sidelength different to the default value of 32. Here, the units are pixels.
 +
[[File:filamentControls.png|thumb|center|300px| Control for creating filament sections in <tt>dtmslice</tt>]]
 +
 +
After clicking the [extract] button, two things will happen:
 +
# An animation on the <tt>dtmslice</tt> scene will show the sections that will be extracted (using a small cyan rectangle).
 +
# The sections will appear as a montage in a new window.
 +
[[File:filamentSliceClickReady.png|thumb|center|300px|Popup window with the created sections.]]
 +
 +
==== Define section centers ====
 +
 +
In the currently released version, the user is asked to click on the the center of each shown section.
 +
 +
 +
[[File:filamentUpdatePointsThroughSliceClick.png|thumb|center|300px|Each click on a section in the montage determines a 3d point added to the model.]]
 +
 +
==Geometric computation stage==
 +
 +
The manually introduced points need to be converted into particle points.
 +
 +
=== Types of filaments ===
 +
Different models are provided to account for different ways of relating particles to the points provided by the user during the input stage:
 +
 +
# along the path
 +
# helically distributed pointing outwards
 +
# in rings orthogonal to the path, pointing outwards.
 +
# randomlly distributed in the tube of the filament.
 +
 +
[[File:filamentTypes.png|thumb|center|upright|800px|Crop positions generated by the different filament types. The central points are common in all types. Matlab syntax can be consulted [[Filament types code example here]] ]]
 +
 +
====<tt>filamentWithTorsion</tt>====
 +
The subunits will be defined along the backbone. The center of each subunit will be defined in the backbone. The ''z''direction of the subunit is defined to be colineal with the orientation of backbone at that point, and the distance between two subsequent subunits is defined by the model parameter <tt>dz</tt>. The ''torsion'' effect referred to by the name of the model refers to the fact that the x direction of two subsequent subunits can be chosen to vary a fixed amount (with parameter <tt>dphi</tt>) 
 +
 +
Parameters:
 +
* <tt>subunits_dz</tt>  distance of the subunits along the backbone (in pixels).
 +
*<tt> subunits_dphi</tt> torsion between subunits (in degrees).
 +
 +
====<tt>filamentSubunitsOnHelix</tt>====
 +
 +
In this case, the subunits to be cropped are supposed to be located on a helix that turns along the backbone of the filament. The center of the subunits is on a fixed distance from the backbone of the filament (defined by parameter <tt>radius</tt>), and the ''z'' direction points radially from the backbone, while ''x'' points along the way of the filament.
 +
 +
Parameters:
 +
* <tt> subunits_dz </tt>  distance of the subunits along the backbone (in pixels).
 +
* <tt> subunits_dphi </tt> angular distance between the subunits (in degrees) .
 +
* <tt>radius</tt> distance of the subunits to the backbone (in pixels).
 +
 +
====<tt>filamentSubunitsOnRings</tt>====
 +
 +
Several equally spaced rings of subunits are distributed along the path of the filament.
 +
 +
Parameters:
 +
* <tt> ringSeparation </tt>  in pixels.
 +
* <tt> subunitsPerRing </tt>
 +
* <tt>radius</tt> distance of the subunits to the backbone (in pixels).
 +
 +
=== Computation of the particles ===
 +
  
  
==Computation stage==
+
==== Using a workflow tool  ====
  
Different models are provided to account for different ways of relating particles to the backbone.
+
The <tt>Active model</tt> option in <tt>dtmslice</tt> includes the option ''Step-by-step workflow for model''.
  
===<tt>filamentWithTorsion</tt>===
+
{|style="margin: 0 auto;"
Parameters
+
| [[File:filamentSelectWorkflow.png|thumb|upright|400px| Opening the model workflow from <tt>dtmslice</tt>]]
* <tt>dz</tt>   distance of the subunits along the backbone (in pixels)
+
| [[File:FilamentWorkflowStart.png|thumb|upright|400px| Workflow steps on a workflow GUI opened onto an unprocessed filament model]]
*<tt> dphi</tt> angular distance between the subunits (in degrees)
+
|}
===<tt>filamentSubunitsObHelix</tt>===
+
==== Programmatically ====
 +
The methods used for the processing of a filament objects are typically:
 +
* <tt>createBackbone</tt>
 +
: derives a smooth backbone that interpolates the <tt>points</tt> introduced by the user.
 +
: normally does not require to change any parameter.
 +
* <tt>updateCrop</tt>
 +
: creates the <tt>crop_points</tt> and <tt>crop_angles</tt> corresponding to the particular model.
 +
: uses the geometrical parameters of the model: <tt>dz</tt>, <tt>dphi</tt>, etc....
 +
* <tt>saveIntoCatalogue</tt>
  
Parameters
+
The syntax for invoking these models can be consulted in this [[Filament types code example | matlab code example]] .
* <tt>dz</tt>  distance of the subunits along the backbone (in pixels)
 
*<tt> dphi</tt> angular distance between the subunits (in degrees)
 
* <tt>radius</tt> distance of the subunits to the backbone (in pixels)
 

Latest revision as of 15:29, 15 August 2016

Filament models are used for geometries where location and orientation of particles to be cropped (called subunitsin this context) can be defined with relation to tubular estructures.

The usual way of handling them is by opening a small fraction of a tomogram inside dtmslice and mark manually positions that will be used to define a "backbone". Loosely speaking, we call the "backbone of the filament" to the series of ordered points that arise from defining successive orthogonal sections along the path of the filament and picking the central point. Different models are available for the different relationships between the "backbone" of the filament and the locations and positions of the particles to be cropped.

Input stage

The input points in a filament model are used to define a smooth interpolant called backbone.

Clicking input points in dtmslice

A [video tutorial] explains with detail the process of picking points and converting them into subunit locations.

The basic tool for tracking filaments is dtmslice. In this tools, creating the points of a filament can be done manually in three steps:

  1. Select extremal points,
  2. Create orthogonal sections
  3. Click on the center of each section.

Select extremal points (anchors)

Click on [1] and [2] to select two extremal points in the filament, typically in two different sections. [1] will appear as a red diamond, [2] appears as a blue diamond.

Click on anchor 1
Click on anchor 2

Create orthogonal sections

In the Filament Tools panel, you can select a partition of the space between the anchor points. The default value is 1:10:100, meaning: "divide the distance between the anchor points in 100 parts, and create an orthogonal section every 10 points".

You can also select a sidelength different to the default value of 32. Here, the units are pixels.

Control for creating filament sections in dtmslice

After clicking the [extract] button, two things will happen:

  1. An animation on the dtmslice scene will show the sections that will be extracted (using a small cyan rectangle).
  2. The sections will appear as a montage in a new window.
Popup window with the created sections.

Define section centers

In the currently released version, the user is asked to click on the the center of each shown section.


Each click on a section in the montage determines a 3d point added to the model.

Geometric computation stage

The manually introduced points need to be converted into particle points.

Types of filaments

Different models are provided to account for different ways of relating particles to the points provided by the user during the input stage:

  1. along the path
  2. helically distributed pointing outwards
  3. in rings orthogonal to the path, pointing outwards.
  4. randomlly distributed in the tube of the filament.
Crop positions generated by the different filament types. The central points are common in all types. Matlab syntax can be consulted Filament types code example here

filamentWithTorsion

The subunits will be defined along the backbone. The center of each subunit will be defined in the backbone. The zdirection of the subunit is defined to be colineal with the orientation of backbone at that point, and the distance between two subsequent subunits is defined by the model parameter dz. The torsion effect referred to by the name of the model refers to the fact that the x direction of two subsequent subunits can be chosen to vary a fixed amount (with parameter dphi)

Parameters:

  • subunits_dz distance of the subunits along the backbone (in pixels).
  • subunits_dphi torsion between subunits (in degrees).

filamentSubunitsOnHelix

In this case, the subunits to be cropped are supposed to be located on a helix that turns along the backbone of the filament. The center of the subunits is on a fixed distance from the backbone of the filament (defined by parameter radius), and the z direction points radially from the backbone, while x points along the way of the filament.

Parameters:

  • subunits_dz distance of the subunits along the backbone (in pixels).
  • subunits_dphi angular distance between the subunits (in degrees) .
  • radius distance of the subunits to the backbone (in pixels).

filamentSubunitsOnRings

Several equally spaced rings of subunits are distributed along the path of the filament.

Parameters:

  • ringSeparation in pixels.
  • subunitsPerRing
  • radius distance of the subunits to the backbone (in pixels).

Computation of the particles

Using a workflow tool

The Active model option in dtmslice includes the option Step-by-step workflow for model.

Opening the model workflow from dtmslice
Workflow steps on a workflow GUI opened onto an unprocessed filament model

Programmatically

The methods used for the processing of a filament objects are typically:

  • createBackbone
derives a smooth backbone that interpolates the points introduced by the user.
normally does not require to change any parameter.
  • updateCrop
creates the crop_points and crop_angles corresponding to the particular model.
uses the geometrical parameters of the model: dz, dphi, etc....
  • saveIntoCatalogue

The syntax for invoking these models can be consulted in this matlab code example .