Skip to content, Skip to search

Changes

BigWarp

14,820 bytes added, 11:17, 7 November 2019
remove outdated command
{{Infobox| name = BigWarp | software = Fiji| author = {{Person|Bogovic}}| maintainer = {{Person|Bogovic}}| source = {{GitHub|org=saalfeldlab|repo=bigwarp}}| latest version = 1ComponentStats:sc.0.0| status = stable| category = [[:Category:Plugins|Plugins]], [[:Category:Visualization|Visualization]], [[:Categoryfiji:Transform|Transform]]bigwarp_fiji}} == Description ==Bigwarp is a tool for manual, interactive, landmark-based deformable image alignment.
It uses the [[BigDataViewer]] for visualization and navigation, and uses a
[[wikipedia:Thin_plate_spline|Thin Plate Spline]] implemented
== Installation ==
Bigwarp comes with Fiji.
You can access it via ''Plugins {{arrow}} BigDataViewer {{arrow}} Big Warp'', or by modifying {{GitHub|org=saalfeldlab|repo=bigwarp|path=src/main/resources/scripts/bigwarp_fiji_demo.bsh|label=this example script}}. If this is not visible in your installation, try updating Fiji with ''Help {{arrow}} Update Fiji.''
== Usage ==
Open two images in ImageJ, one ''moving'' and the other ''target'' and navigate to ''Plugins {{arrow}} BigDataViewer {{arrow}} Big Warp.'' A dialog will appear prompting selection of the moving and target images.
 
Once the two image windows and one table window open, press {{key press|Spacebar}} to enter "landmark mode". Next, click on a point in the moving image, then click on the corresponding point in the target image. After you have a few moving-target point pairs, press {{key press|T}} to transform the moving image (you may need to re-navigate if the two image are very far apart: see the {{key press|Q}} and {{key press|W}} hotkeys below).
=== Getting Help ===
Press {{key press|F1}} at any time to open a help page with a listing of navigation and editing commands. For detailed help, create a post on the [https://forum.image.sc/ image.sc forum] with a bigwarp tag. Report bugs [https://github.com/saalfeldlab/bigwarp/issues on github].
=== Landmark point placement and display in the viewer ===
Landmark placements is done in ''Landmark mode'' which can be toggled with you enter by pressing {{key press|Spacebar}}.Users place pairs of corresponding points on the moving and target images.
The following table shows the available landmark placement commands and keystrokesfor landmark placement, warping.
{| border="1" style="border-collapse:collapse;"
| style="padding: 5px;" | {{key press|T}}
| style="padding: 5px;" | Toggle between warped view and raw view or moving image.
|-
| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|O}}
| style="padding: 5px;" | Open landmarks from saved file.
|-
| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|S}}
| style="padding: 5px;" | Save current landmarks to a file.
|-
| style="padding: 5px;" | {{key press|Spacebar}}
| style="padding: 5px;" | Toggle ''Landmark mode''
|-
| style="padding: 5px;" | <''Landmark mode on''>+{{key press|left-click}}| style="padding: 5px;" | Clicking while in landmark mode adds a landmark pointor selects and existing landmark.
|-
| style="padding: 5px;" | <''Landmark mode on''>+{{key press|left-click}}+{{key press|drag}}
| style="padding: 5px;" | Clicking an existing point and dragging changes it's position.
|-
| style="padding: 5px;" | <''Landmark mode on''>+{{key press|Shift}}+{{key press|left-click}}+{{key press|drag}}
| style="padding: 5px;" | "Move" a point. The initial click places a
landmark point for the moving image. The release places a landmark
point for the target image.
|-
| style="padding: 5px;" | <''Landmark mode''>+{{key press|Ctrl}}+{{key press|left-click}}
| style="padding: 5px;" | "Pin" a point. Add a landmark at the same location for both moving and target images.
|-
 
| style="padding: 5px;" | <''Landmark mode''>+{{key press|Ctrl}}+{{key press|Shift}}+{{key press|left-click}}
| style="padding: 5px;" | Place a point in the "other" space. Place a moving landmark from the fixed window, and vice versa.
|-
| style="padding: 5px;" | {{key press|Ctrl}} + {{key press|Z}}
| style="padding: 5px;" | Undo the last landmark point change.
|-
| style="padding: 5px;" | {{key press|Ctrl}} + {{key press|Y}}
| style="padding: 5px;" | Redo the last landmark point change.
|-
| style="padding: 5px;" | {{key press|V}}
| style="padding: 5px;" | Toggle point visibility in the viewer.
|-
| style="padding: 5px;" | {{key press|N}}
| style="padding: 5px;" | Toggle point name visibility in the viewer.
|}
=== Navigation Landmark selection and editing in the table ===
Some changes to landmarks can be done by interacting with the landmark table. {| border="1" style="border-collapse:collapse;"| style="padding: 5px;" | {{key press|left-click}}| style="padding: 5px;" | Select row.|-| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|left-click}}| style="padding: 5px;" | Add row to selection.|-| style="padding: 5px;" | {{key press|Shift}}+{{key press|left-click}}| style="padding: 5px;" | Select range of rows.|-| style="padding: 5px;" | {{key press|Esc}}| style="padding: 5px;" | Deselect all rows.|-| style="padding: 5px;" | {{key press|right-click}} {{arrow}} Delete| style="padding: 5px;" | Deletes a landmark pair (row in the table).|-| style="padding: 5px;" | {{key press|right-click}} {{arrow}} Delete all selected| style="padding: 5px;" | Deletes all selected landmark pairs (row in the table).|} === Notes on point addition and landmark pair selection === * Adding a new landmark pair selects that pair (row) in the table.* If a row is "missing" a moving (target) landmark point, then it must be selected in order to add that missing point by clicking in the moving (target) viewer. Then BigWarp will find the "next" row that is missing a moving (target) landmark, and select that row automatically.* If the selected row is not missing a landmark, the next click will add a new landmark pair.* If multiple rows are selected when a viewer is clicked, the result will be as though only the first row was selected. === Selecting transformation types === Press {{key press|F8}} to bring up a transformation type selection window (version 4.0.0 of BigWarp supports multiple options for transformations) {|| [[Image:Bigwarp_selectTps.png|400px]]| [[Image:Bigwarp_selectAffine.png|400px]]|-| Example of a thin plate spline transformation| Example of an affine transformation|} ==== Table of transformation types ===={| border="1" style="border-collapse:collapse;"| style="padding: 5px;" | Thin Plate Spline| style="padding: 5px;" | The smoothest deformable transformation that maps moving landmarks exactly to the corresponding target landmarks.|-| style="padding: 5px;" | Affine| style="padding: 5px;" | Linear transform with translation, rotation, independent scales and shear (12 degrees of freedom)|-| style="padding: 5px;" | Similarity| style="padding: 5px;" | Linear transform with translation, rotation, and one scale parameter (7 degrees of freedom)|-| style="padding: 5px;" | Rotation| style="padding: 5px;" | Linear transform with translation, and rotation (6 degrees of freedom)|-| style="padding: 5px;" | Translation| style="padding: 5px;" | Translation only (3 degrees of freedom)|} === Navigation and Visualization === Bigwarp shares inherits many image [[BigDataViewer#Basic_Navigation|navigation ]], [[BigDataViewer#Adjusting_Brightness_and_Color|visualization]], and [[BigDataViewer#Grouping_Sources|grouping]] features with BigDataViewer, the details of which can befound on the [[BigDataViewer#Basic_Navigation|BigDataViewer Navigation Page]], pageor on thehelp page. BigWarp specific features are documented below.
The following table shows the available navigation commands using the mouse:
| style="padding: 5px;" | {{key press|W}}
| style="padding: 5px;" | Align the active viewer with the non-active viewer.
|-
| style="padding: 5px;" | {{key press|E}}
| style="padding: 5px;" | Centers the active viewer to the nearest landmark (considers 3D when applicable).
|-
| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|D}}
| style="padding: 5px;" | Centers the active viewer to the next landmark.
|-
| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|Shift}}+{{key press|D}}
| style="padding: 5px;" | Centers the active viewer to the previous landmark.
|-
| style="padding: 5px;" | {{key press|R}}
| style="padding: 5px;" | Resets the active viewer.|-| style="padding: 5px;" | {{key press|U}}| style="padding: 5px;" | Show warp visualization / grid dialog.|-| style="padding: 5px;" | {{key press|F6}}| style="padding: 5px;" | Show moving image panel Visibility & and Grouping dialog.|-| style="padding: 5px;" | {{key press|F7}}| style="padding: 5px;" | Show target image panel Visibility & and Grouping dialog.|-| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|E}}| style="padding: 5px;" | Export moving image as an ImagePlus.|-| style="padding: 5px;" | {{key press|Ctrl}}+{{key press|Shift}}+{{key press|E}}| style="padding: 5px;" | Export moving image as a Virtual ImagePlus.
|}
 
=== Commands shared with BigDataViewer ===
* [[BigDataViewer#Displaying_Multiple_Sources|Displaying multiple stacks ("sources")]]
* [[BigDataViewer#Grouping_Sources|Grouping sources]]
* [[BigDataViewer#Adjusting_Brightness_and_Color|Adjusting brightness and color]]
* [[BigDataViewer#Bookmarking_Locations_and_Orientations|Bookmarking views (locations and orientations)]]
====Mouse navigation====
{| border="1" style="border-collapse:collapse;"
| style="padding: 5px;" | {{key press|left-click|drag}}
| style="padding: 5px;" | Rotate (pan and tilt) around the point where the mouse was clicked.
|-
| style="padding: 5px;" | {{key press|right-click|drag}} or {{key press|middle-click|drag}}
| style="padding: 5px;" | Translate in the XY-plane.
|-
| style="padding: 5px;" | {{key press|mouse-wheel}}
| style="padding: 5px;" | Move along the z-axis.
|-
| style="padding: 5px;" | {{key press|Cmd|mouse-wheel}} or {{key press|Shift|Ctrl|mouse-wheel}}
| style="padding: 5px;" | Zoom in and out.
|}
====Keyboard navigation====
{| border="1" style="border-collapse:collapse;"
| style="padding: 5px;" | {{key press|X}}, {{key press|Y}}, {{key press|Z}}
| style="padding: 5px;" | Select keyboard rotation axis.
|-
| style="padding: 5px;" | {{key press|Left}}, {{key press|Right}}
| style="padding: 5px;" | Rotate clockwise or counter-clockwise around the choosen rotation axis.
|-
| style="padding: 5px;" | {{key press|Up}}, {{key press|Down}}
| style="padding: 5px;" | Zoom in or out.
|-
| style="padding: 5px;" | {{key press|,}}, {{key press|.}}
| style="padding: 5px;" | Move forward or backward along the Z-axis.
|-
| style="padding: 5px;" | {{key press|Shift|X}}
| style="padding: 5px;" | Rotate to the ZY-plane of the current source. (Look along the X-axis of the current source.)
|-
| style="padding: 5px;" | {{key press|Shift|Y}} or {{key press|Shift|A}}
| style="padding: 5px;" | Rotate to the XZ-plane of the current source. (Look along the Y-axis of the current source.)
|-
| style="padding: 5px;" | {{key press|Shift|Z}}
| style="padding: 5px;" | Rotate to the XY-plane of the current source. (Look along the Z-axis of the current source.)
|-
| style="padding: 5px;" | {{key press|[}} or {{key press|N}}
| style="padding: 5px;" | Move to previous timepoint.
|-
| style="padding: 5px;" | {{key press|]}} or {{key press|M}}
| style="padding: 5px;" | Move to next timepoint.
|}
 
 
For all navigation commands you can hold {{key press|Shift}} to rotate and browse
10x faster, or hold {{key press|Ctrl}} to rotate and browse
10x slower.
For example, {{key press|Left}} rotates by
1° clockwise, while {{key press|Shift|Left}} rotates by
10°, and {{key press|Ctrl|Left}} rotates by
0.1°.
 
=== Save and load landmarks ===
 
Landmarks can be exported and imported from plain text files using the drop down menu in the landmark table panel ( ''File {{arrow}} Export (Import) landmarks.'' )
 
=== Export warped images ===
 
Export the warped moving image by clicking ''File {{arrow}} > Export as ImagePlus'' or using the {{key press|Ctrl}}+{{key press|E}} keyboard shortcut.
 
[[Image:Bigwarp_export.png]]
 
The default parameters will result in the exported image having the same dimensions as the target image. ''Note: Take care when exporting very large data sets as they can cause out-of-memory exceptions.''
 
* Resolution
** Target: ''The output will have the same resolution as the target image''
** Moving: ''The output will have the same resolution as the moving image''
** Specified: ''The output will have the resolution given in the fields below (in the same units as the moving and target images).''
 
* Field of view
** Target: ''The output will have the same field of view as the target image''
** Moving: ''The output field of view will be the smallest bounding box that contains the warped moving images (approximated)''
** Specified (pixel): '' The output field of view will be that given by the Offset and Field of View parameter fields where both are in units of pixels''** ** Specified (physical): '' The output field of view will be that given by the Offset and Field of View parameter fields where both are in the physical units of the moving and target images''
 
 
The warped moving image can be exported as an in-memory or [http://imagej.net/docs/guide/146-8.html virtual] ImagePlus. A virtual ImagePlus is generally faster to generate but slower to browse, whereas an in-memory ImagePlus will be slower to generate but faster to browse.
 
 
[[Image:BigwarpLandmarkCenteredExport.png|600px]]
 
 
=== Apply transforms ===
 
Often, it is important to apply transforms estimated with one image to other images in the same space.
 
If you have moving and target images open in Fiji [https://github.com/saalfeldlab/bigwarp/blob/master/scripts/Apply_Bigwarp_Xfm.groovy this script] to transform the moving image into the space of the target image. You will need to provide a file containing the saved landmark point pairs.
 
To manually specify the field-of-view (FOV) of the target space, use [https://github.com/saalfeldlab/bigwarp/blob/master/scripts/Apply_Bigwarp_Xfm_FOV.groovy this script]
 
To make the scripts above appear in your Fiji Plugins menu, simply copy them into the <code>/plugins/Scripts folder</code> in your Fiji installation.
 
==== Warp 2d ImageJ ROIs ====
 
Download and install [https://raw.githubusercontent.com/saalfeldlab/bigwarp/master/scripts/Apply_Bigwarp_Xfm_IjRoi2d.groovy this script].
 
Usage:
# Run the script downloadable above.
# Indicate which open images correspond to the moving and fixed images in bigwarp.
# Select the csv file that stores bigwarp landmarks.
# Indicate whether you want to transform an ROI from moving to target space or vice versa.
# Click OK.
 
Note that the resulting ROI will be densely sampled. This is because an ROI with a particular shape may not have the same shape after being warped (i.e., a circle may not still be circular after being warped).
 
Example:
In this example, we've chosen the boats sample as the moving image, the bridge sample as the target image, and have added some landmarks that transform the boats image.
 
To warp an ROI from the moving boats image to the fixed bridge image, we run the script with the options:
<blockquote>
* Fixed image: boats
* Moving image: bridge
* Landmark file: <our landmarks file>
* Moving to target
</blockquote>
 
The results are shown in the "Forward example" below.
 
To warp an ROI from the moving boats image to the fixed bridge image, we run the script with the options:
<blockquote>
* Fixed image: boats
* Moving image: bridge
* Landmark file: <our landmarks file>
* Target to moving
</blockquote>
 
The results are shown in the "Inverse example" below.
 
{|
| [[Image:bigwarp_warp_roi_fwd.png|600px]]
| [[Image:bigwarp_warp_roi_inv.png|600px]]
|-
| Forward example (click to expand)
| Inverse example (click to expand)
|}
 
Note, at this time ImageJ ROIs are 2D objects. We recommend using another approach for 3D regions of interest.
 
==== Warp points in a csv file ====
 
Download and install [https://raw.githubusercontent.com/saalfeldlab/bigwarp/master/scripts/Apply_Bigwarp_Xfm_csvPts.groovy this script].
 
Usage:
# Run the script download-able above.
# Select the csv file that stores bigwarp landmarks.
# Select the csv file storing the points you want to transform.
# Select the location for csv file you want the results to be stored in.
# Indicate whether you want to transform the points from moving to target space or vice versa.
# Click OK.
 
Note the input csv must be formatted:
 
x1,y1,z1
x2,y2,z2
...
xN,yN,zN
 
 
without quotation marks, spaces, or any other characters. Csv files storing bigwarp landmarks will not work as input to this script.
 
= Tutorials =
* An example of a 2d warping by [http://kiaru.eu/cv-rapide/ Nicolas Chiaruttini] in response to [https://forum.image.sc/t/superimpose-atlas-image-onto-microscope-picture/20593 this forum post]
{{#widget:YouTube|id=zNur6mk9VXg|width=420}}
 
= Publication =
* {{Publication | BigWarp}}
 
= Publications using BigWarp =
# Russell et al. [https://www.ncbi.nlm.nih.gov/pubmed/27445312 "3D correlative light and electron microscopy of cultured cells using serial blockface scanning electron microscopy"] J Cell Sci 130: 278-291 2017.
# Collinson et al. [https://www.sciencedirect.com/science/article/pii/S2468451117300685 "Correlating 3D light to 3D electron microscopy for systems biology"] Current Opinion in Biomedical Engineering 2017 3:49-55
# Lerner et al. [http://jcb.rupress.org/content/216/3/583 "Mycobacterium tuberculosis replicates within necrotic human macrophages"] J Cell Biol 2017
# Hildebrand et al. [https://www.nature.com/articles/nature22356 "Whole-brain serial-section electron microscopy in larval zebrafish"] Nature 545:345–349 2017.
# Zhang et al. [https://www.cell.com/cell/fulltext/S0092-8674(18)30787-6 "A Complete Electron Microscopy Volume Of The Brain Of Adult Drosophila melanogaster"] Cell 174:3 P730-743.e22, 2018.
# Gao et al. [http://science.sciencemag.org/content/363/6424/eaau8302.abstract Cortical column and whole-brain imaging with molecular contrast and nanoscale resolution] Science 363 (6424) 2019.
 
 
[[Category:Plugins]]
[[Category:Visualization]]
[[Category:Transform]]
[[Category:Registration]]
[[Category:Citable]]
Uploaders
83
edits