Difference between revisions of "Grid hole picker"

From Dynamo
Jump to navigation Jump to search
 
(10 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
The main input expected by the Hole Picker is a set of .mrc files, each one being a polygon, typically from the same grid. For each one of them, it will create a corresponding .xy file, a text file containing the x,y coordinates of the holes detected/clicked on the corresponding polygon.
 
The main input expected by the Hole Picker is a set of .mrc files, each one being a polygon, typically from the same grid. For each one of them, it will create a corresponding .xy file, a text file containing the x,y coordinates of the holes detected/clicked on the corresponding polygon.
  
== Calling the Hole Picker ==
+
== Calling the Hole Picker GUI ==
  
The function that launches the Hole Picker GUI is <tt>dpacq.polygons.detectHoles</tt>  
+
The function that launches the Hole Picker GUI is <tt>dpacq.polygons.detectHoles</tt>.
 +
 
 +
[[File:HoleClickerGUIWithPoints.png|thumb|center|500px|The Hole Picker GUI]]
  
 
=== From a running ''Dynamo'' instance ===
 
=== From a running ''Dynamo'' instance ===
Line 56: Line 58:
 
* <tt>d</tt> deletes the point closest to the cursor.
 
* <tt>d</tt> deletes the point closest to the cursor.
 
* <tt>m</tt> moves the cursor the closest point.
 
* <tt>m</tt> moves the cursor the closest point.
 +
 +
 +
{|style="margin: 0 auto;"
 +
| [[File:holeClickerClickingSwitchDetail.png|thumb|upright|200px| ''manual click switcher'']]
 +
| [[File:HoleClickerClickingZoomOutDetail.png|thumb|upright|200px| Resets view to original zoom]]
 +
| [[File:HoleClickerClickingHoverDetail.png|thumb|upright|200px| Locates the zoomed fraction in a auxiliary viewer]]
 +
| [[File:HoleClickerClickingGalleryDetail.png|thumb|upright|200px| Gallery view of clicked holes]]
 +
|}
  
 
=== Selecting a detection workflow ===
 
=== Selecting a detection workflow ===
In the current version of ''Dynamo'', the Hole Clicker provides a single type of workflows, appropriate for Lacey grids.   
+
In the current version of ''Dynamo'', the Hole Clicker provides a single type of workflows, appropriate for [[Basic detector workflow for Lacey grids | Lacey grids]].   
  
 
=== Running a detection workflow ===
 
=== Running a detection workflow ===
Line 67: Line 77:
  
 
=== Editing a detection workflow ===
 
=== Editing a detection workflow ===
Edition of the current workflow will open a GUI that allows the execution of each step in the current detection workflow separately. This allows the user to gauge the effect of each parameter and the design of a workflow more suitable to the image properties of the current polygons.
+
Edition of the current workflow will open a GUI that allows the execution of each step in the current detection workflow separately. This allows the user to gauge the effect of each parameter and the design of a workflow more suitable to the image properties of the current polygons.
 +
 
 +
==Interfacing with SerialEM==
 +
The Hole Picker tools is delivered as an independent tool. We suggest the following protocol to interface it with tools in contact with the microscope hardware. Here, we call ''DAS''  (Data Acquisition Software) the package you use to operate the data acquisition. It can be SerialEM, a device on top of serialEM, or anything else.
 +
# ''DAS'' collects a series of polygon images and stores them in a single folder (the ''polygon folder'').
 +
# ''DAS'' launches a ''Dynamo'' Hole Picker instance with the polygon folder as input.
 +
# ''DAS'' stops execution and periodically checks the existence of a semaphore file in the polygon folder (<tt><polygonFolder>\unlock</tt>)
 +
# The user interacts with ''Dynamo'' and creates the coordinate files for each polygon file.
 +
# When the user terminates the work with ''Dynamo'', it creates the semaphore file in the polygon folder.
 +
# ''DAS'' detects the existence of the semaphore file and resumes execution.
 +
 
 +
Note that ''Dynamo'' only provides the hole picking system. All necessary coordinate conversions to produce a navigation file must be carried by ''DAS''.

Latest revision as of 18:07, 13 February 2017

Dynamo includes an utility for semi-automated picking of holes on a grid. This utility can be called from SerialEM or any other data acquisition software.

An instance of the Dynamo hole picker can be invoked along with a set of .mrc files, each one containing the image a single polygon. The hole picker allows the application of a predetermined detection workflow on all the polygons, and the manual correction afterwards. It also offers the possibility of tuning the parameters in the hole detection workflow for each of the polygons separately.

Input and output

The main input expected by the Hole Picker is a set of .mrc files, each one being a polygon, typically from the same grid. For each one of them, it will create a corresponding .xy file, a text file containing the x,y coordinates of the holes detected/clicked on the corresponding polygon.

Calling the Hole Picker GUI

The function that launches the Hole Picker GUI is dpacq.polygons.detectHoles.

The Hole Picker GUI

From a running Dynamo instance

If you have already an opened Matlab process or a Dynamo standalone process, you invoke directly dpacq.polygons.detectHoles from the command line with the corresponding arguments.

From the operative system

The Hole Clicker can be launched directly from the command line of the operative System:

in Mac or Linux:

 dynamo dpacq.polygons.detectHoles( arguments ) 

in Windows:

 dynamo.exe dpacq.polygons.detectHoles( arguments ) 

Full syntax

The syntax of the invoking function is:

dpacq.polygons.detectHoles(<location of polygons>,'flag1',parameter1,....)

where the input location of the polygons is a string that locates a set of .mrc files. This input can be the name of a single text file containing the absolute path to each on of the polygon files. However, the recommended input is an absolute path to a folder that contains each polygon as an .mrc file. We call this location polygon folder or input folder. In this case, Dynamo will treat each .mrc file found in the indicated location as a polygon to analyse.

Admissible flags:

  • 'runWorkflow', with values 0/1. Applies a detection workflow on the polygons.
  • 'type' allows selecting a type of detection workflow. Currently the only valid input is 'lacey', further workflows will be added.
  • 'gui' , with values 0/1. If switched to 0, runs the detection workflow on the polygons without opening the Hole Clicker GUI.

The hole picker GUI

The hole picker GUI allows surfing from polygon to polygon, using the cursor keys or the << and >> pushbuttons in the GUIs. Each time you transition the view from a polygon to another one, Dynamo will:

  • the coordinates shown in screen will be saved in the .xy file corresponding to the polygon you just left.
  • read the .xy coordinates of the polygon you just opened and show them on screen.

Key strokes

The pushbutton depicting a black point inside a red circle is the manual click switcher. When it is activated, you can use several keys to interact with the polygon shown in the main view of the Hole Picker.

  • Main click: adds a point (i.e., a hole)/
  • Secondary click: to selects a point.
  • Mouse movement keeping secondary click pressed: shifts the view (hand tool).
  • Mouse wheel: zooms in and out.
  • d deletes the point closest to the cursor.
  • m moves the cursor the closest point.


manual click switcher
Resets view to original zoom
Locates the zoomed fraction in a auxiliary viewer
Gallery view of clicked holes

Selecting a detection workflow

In the current version of Dynamo, the Hole Clicker provides a single type of workflows, appropriate for Lacey grids.

Running a detection workflow

Detection workflows can be already executed an all the polygons when the Hole Picker gets invoked. In such a case you will find a set of marked points each time you enter a new polygon. If the detection workflow was not ran at invoking time, you can use the Current workflow menu to ran the workflow on the selected polygon. This will generate a new set of points in the currently shown polygon. Holes that where detected or manually clicked before running the detection workflow will be discarded.

You will need to evaluate the hole centers suggested by Dynamo. If you are happy with most of them, you can just activate the manual click tool (the red circle in the toolbar) to manually remove or add holes. If the results are too bad and cannot be fixed by a manual curation of the detected points, you might want to try to edit the workflow and change its parameters.

Editing a detection workflow

Edition of the current workflow will open a GUI that allows the execution of each step in the current detection workflow separately. This allows the user to gauge the effect of each parameter and the design of a workflow more suitable to the image properties of the current polygons.

Interfacing with SerialEM

The Hole Picker tools is delivered as an independent tool. We suggest the following protocol to interface it with tools in contact with the microscope hardware. Here, we call DAS (Data Acquisition Software) the package you use to operate the data acquisition. It can be SerialEM, a device on top of serialEM, or anything else.

  1. DAS collects a series of polygon images and stores them in a single folder (the polygon folder).
  2. DAS launches a Dynamo Hole Picker instance with the polygon folder as input.
  3. DAS stops execution and periodically checks the existence of a semaphore file in the polygon folder (<polygonFolder>\unlock)
  4. The user interacts with Dynamo and creates the coordinate files for each polygon file.
  5. When the user terminates the work with Dynamo, it creates the semaphore file in the polygon folder.
  6. DAS detects the existence of the semaphore file and resumes execution.

Note that Dynamo only provides the hole picking system. All necessary coordinate conversions to produce a navigation file must be carried by DAS.