Locate3D Overview: Difference between revisions

From Software Product Documentation
Jump to navigation Jump to search
 
(44 intermediate revisions by the same user not shown)
Line 7: Line 7:
Locate3D tracks radiopaque beads in X-ray trials. It is most often used to track objects (e.g., bones and implants) with implanted beads. If the object contains three or more beads in fixed locations, and these 3D locations are known relative to the [[DSX_Definitions#Coordinate systems|object's CT coordinate system]], then the beads' 2D locations in the X-ray images can be used to calculate the object's 3D pose in the [[DSX_Definitions#Coordinate systems|X-ray lab frame]]. Locate3D is thus similar to X4D, except that it uses multiple beads to determine the pose of an object, instead of the contours of the object itself. Locate3D requires that the configuration of the X-ray equipment has been calculated (with [[CalibrateDSX_Overview|CalibrateDSX]]), and that the locations of the beads in the object's local frame have been determined (with [[Surface3D_Overview|Surface3D]]).
Locate3D tracks radiopaque beads in X-ray trials. It is most often used to track objects (e.g., bones and implants) with implanted beads. If the object contains three or more beads in fixed locations, and these 3D locations are known relative to the [[DSX_Definitions#Coordinate systems|object's CT coordinate system]], then the beads' 2D locations in the X-ray images can be used to calculate the object's 3D pose in the [[DSX_Definitions#Coordinate systems|X-ray lab frame]]. Locate3D is thus similar to X4D, except that it uses multiple beads to determine the pose of an object, instead of the contours of the object itself. Locate3D requires that the configuration of the X-ray equipment has been calculated (with [[CalibrateDSX_Overview|CalibrateDSX]]), and that the locations of the beads in the object's local frame have been determined (with [[Surface3D_Overview|Surface3D]]).


[[Image:L3D_Full.png|600px]]
[[Image:L3D_Full.png|800px]]


{| class="mw-collapsible mw-collapsed wikitable" id="Digitizing_POIs" width="80%"
==Tutorials==
! style="text-align:left;" |      Digitizing POIs
<!-- Note: '====' gives '[edit] link; '<h4> doesn't -->
|-
 
|
<h4><span id="L3DTutorials01"></span>[[Locate3D:_How_to_Digitize_Points_of_Interest|How To: Digitize Points of Interest]]</h4>
To digitize a POI for the current reporting time, select the POI by clicking on its name in the table in the [[Locate3D_Overview#Points of Interest|''Points of Interest'']] widget. The table row will be highlighted in blue, and when you move the cursor into one of the X-ray windows, the cursor will change to a circle inside a square, with the POI name to the right. The circle represents the expected size of the POI on the X-ray image, which is dependent on the pixel size of the image and the radius of the POI, which is specified in the subject file. The square represents the region of the image that will be searched for the center of the POI (some of the outer pixels of the POI can be outside the square). The size of the square is controlled by the [[Locate3D Parameters#Click Search Factor|''Click Search Factor'']] parameter. A larger number makes it quicker and easier to digitize POIs, but you don't want the square to contain more than one POI. When you click the left mouse button, Locate3D will search the X-ray pixels within the square to determine which one is the best candidate for the center of the POI. This is done by using the [[Locate3D Parameters#Centroid Threshold|''Centroid Threshold'']] parameter to separate the POI pixels from the background, and the [[Locate3D Parameters#Edge Threshold|''Edge Threshold'']] parameter to determine if these pixels represent a circular POI. The POI is assumed to be a bright circle on a dark background, with the center of the POI being the brightest. The 2D coordinates of the POI center in each view are calculated as the weighted center of the pixels above the ''Centroid Threshold''.
<h4><span id="L3DTutorials02"></span>[[Locate3D:_How_to_Track_Objects_Using_Points_of_Interest|How To: Track Objects Using Points of Interest]]</h4>


Once you digitize the POI in one view (you can start with either one), a yellow line is drawn in the other view. This line is the projection of the point in the first view through the field of view of the second view, and its purpose is to help you identify the POI in the other view. You can then digitize the POI in the second view by clicking on a point near the line. If you make a mistake identifying the proper POI in the first view, you can press the ''Esc'' key to cancel the process. If you make a mistake after identifying the POI in the second view, you can remove the POI pose by unchecking the ''pose'' box in the POI table. Once you have digitized a POI, Locate3D automatically advances the current POI to the next one in the table that does not already have a pose.
==Menus==
<!-- Note: '====' gives '[edit] link; '<h4> doesn't -->


Once you have identified the POIs for one or more reporting times, you can have Locate3D attempt to automatically identify them for other reporting times using the ''Propagate POIs'' command in the ''Tools'' menu. See the wiki entry for this command for more details.
<h4><span class="mw-customtoggle-File"><span class="mw-customtoggletext" style="color:rgb(6,69,173);">File Menu</span></span></h4>
|}
<div id="mw-customcollapsible-File" class="toccolours mw-collapsible mw-collapsed" style="margin-left:1em; width:80%;">


==Tutorials==
[[File:L3D_FileMenu.png|right]]


[[Locate3D_How_To_Track_Objects_Using_POIs|How To: Track Objects Using Points of Interest]]
;Open Subject... (Ctrl + O)
: This command loads a subject file.


==Menus==
;Save Subject (Ctrl + S)
{| class="mw-collapsible mw-collapsed wikitable" width="80%"
: This command saves the currently loaded subject to its existing subject file.
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;File Menu
|-
|


<ul>
;Save Subject As...
<li>
: This command saves the currently loaded subject to a new subject file.
'''Open Subject...''' (Ctrl + O): loads a subject file.
</li>
<li>
'''Save Subject''' (Ctrl + S): saves the currently loaded subject to its existing subject file.
</li>
<li>
'''Save Subject As...''': saves the currently loaded subject to a new subject file.
</li>


<li>
;Save POI Locations...
'''Save POI Locations...''': saves three text files containing the coordinates of the current object’s POIs. The files are as follows:  
: This command saves three text files containing the coordinates of the current object’s POIs. The files are as follows:  
#one with the 3D coordinates in the X-ray reference frame of all POIs for all frames,  
#one with the 3D coordinates in the X-ray reference frame of all POIs for all frames,  
#one for the first view with the 2D POI coordinates in the image frame of the view, and  
#one for the first view with the 2D POI coordinates in the image frame of the view, and  
#one for the second view with the 2D POI coordinates in the image frame of the view.  
#one for the second view with the 2D POI coordinates in the image frame of the view.  


If a name for any of these files is already specified in the subject file, it is used to write the data to. If the file already exists, it is overwritten without notification. For any that is not specified, a file browser is displayed, allowing you to select the file and folder.
:If a name for any of these files is already specified in the subject file, it is used to write the data to. If the file already exists, it is overwritten without notification. For any that is not specified, a file browser is displayed, allowing you to select the file and folder.
</li>
<li>
'''Save Pose Maps''': saves the pose map of each selected object in the current trial to a .csv file. This file contains 6 values for each pose: the XYZ translation and the XYZ Euler angles representing the transform from the X-ray lab frame to the object's local coordinate system (i.e., as if you were traveling from the lab frame to the object frame). If a name for the pose map file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file. Before the poses can be saved, they must be calculated using the ''Compute Object Poses from POIs'' command.
</li>
<li>
'''Save Pose Maps As...''': saves the pose map for each selected object in the current trial to a new .csv file. You will be prompted to browse for a new file for each object. A link to this new file will then be added to the Subject file.
</li>
<li>
'''Save Object Transforms...''': saves the pose map of each selected object in the current trial to a .txt file. This file contains a 4x4 transform for each pose, expressing the transform from the X-ray lab frame to the object's local coordinate system (i.e., as if you were traveling from the lab frame to the object frame). If a name for the transforms file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file. Because these transforms are calculated from the object poses, the ''Compute Object Poses from POIs'' command must be used before the transforms can be saved.
</li>
<li>
'''Save Landmark Locations...''': saves a text file with the 3D coordinates of all landmarks on the current object for all frames that have poses. These locations are calculated using the object poses, so the ''Compute Object Poses from POIs'' command must be used before the landmarks can be saved. If a name for the landmarks file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file.
</li>
<li>
'''Exit''': exits the program. The program can also be closed using the X in the top right corner of the program window.
</li>
</ul>


|}
;Save Pose Maps
: This command saves the pose map of each selected object in the current trial to a .csv file. This file contains 6 values for each pose: the XYZ translation and the XYZ Euler angles representing the transform from the X-ray lab frame to the object's local coordinate system (i.e., as if you were traveling from the lab frame to the object frame). If a name for the pose map file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file. Before the poses can be saved, they must be calculated using the ''Compute Object Poses from POIs'' command.


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;Save Pose Maps As...
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;View Menu
: This command saves the pose map for each selected object in the current trial to a new .csv file. You will be prompted to browse for a new file for each object. A link to this new file will then be added to the Subject file.
|-
|
[[File:Locate3D_ViewMenu.jpg|right|250px]]


<ul>
;Save Object Transforms...
<li>
: This command saves the pose map of each selected object in the current trial to a .txt file. This file contains a 4x4 transform for each pose, expressing the transform from the X-ray lab frame to the object's local coordinate system (i.e., as if you were traveling from the lab frame to the object frame). If a name for the transforms file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file. Because these transforms are calculated from the object poses, the ''Compute Object Poses from POIs'' command must be used before the transforms can be saved.  
'''Show All POIs''' (Ctrl + A): toggles the display of all of the POIs for all objects in the current trial.  
</li>
<li>
'''Show Body Reference Frame''' (Alt+ R): toggles the display of the reference frame for the current object, as long as a local frame is defined in the subject file and the pose for the current frame has been calculated.
</li>
<li>
'''Show Landmarks''' (Alt+ L): toggles the display of all of the landmarks for the current object.
</li>


<li>
;Save Landmark Locations...
'''DSX Configuration''' (Ctrl + Shift + D): toggles the display of the dockable widget that shows the current session’s objects.
: This command saves a text file with the 3D coordinates of all landmarks on the current object for all frames that have poses. These locations are calculated using the object poses, so the ''Compute Object Poses from POIs'' command must be used before the landmarks can be saved. If a name for the landmarks file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file.  
</li>
<li>
'''Points of Interest''' (Ctrl + Shift + I): toggles the display of the dockable widget that shows the details of the points of interest.
</li>
<li>
'''POI Parameters''' (Ctrl + Shift + P): toggles the display of the dockable ''POI Parameters'' widget.
</li>
<li>
'''POI Graphs''' (Ctrl + Shift + G): toggles the display of the dockable widget that shows the XYZ coordinate graphs of the currently selected POIs.
</li>
</ul>


|}
;Export Poses to CMZ
: This command exports the pose map of the selected object in the current trial to the session's CMZ file. If the CMZ already contains poses for this object for this trial, those poses will be removed before the current ones are exported. This command does not affect the poses of unselected objects, nor of other trials in the CMZ file. If a CMZ file is not already specified in the subject file, you will be prompted to enter the name of a new one.


{| class="mw-collapsible mw-collapsed wikitable" id="Tools_Menu" width="80%"
;Exit
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Tools Menu
: This command exits the program. The program can also be closed using the X in the top right corner of the program window.
|-
|


<ul>
</div>
<li>
'''Propagate POIs''' (Ctrl + P): propagates all POIs in the current object through all of the frames selected in the ''Propagate Range'' slider. For each POI, Locate3D fits a GCV spline to the poses in that POI's pose map (as shown in the ''POI Graphs'' widget). For each reporting time in the range, if the POI does not already have a pose at that time, Locate3D interpolates the X, Y, and Z splines to calculate the expected location of the POI in each X-ray view. A region of the X-ray image around this point is then searched for a suitable location of the POI center. The size of this region is determined by the ''Propagation Search Factor'' parameter. If the POI moves a lot from frame to frame and this movement is not adequately predicted by the splines, you make need to increase the ''Propagation Search Factor''. However, if this parameter is too large, or if several POIs are close to each other, Locate3D may misidentify POIs during propagation.
</li>
<li>
'''Compute Object Poses from POIs''' (Ctrl + C): calculates the poses of the current object in all frames, using the POI locations. For each frame, if three or more POIs have poses, Locate3D will calculate the object pose using a least-squares optimization (fitting the POIs defined in the 3D voxel data to the POIs defined in the X-ray coordinate system).
</li>
<li>
'''Recalculate 3D POIs''' (Ctrl + R): meant for asynchronous trials. When the first pose for a POI is digitized, there is no valid pose map yet to extrapolate from the two frame times to the reporting time (the pose map splines are straight lines with slope=0, passing through the point being digitized). Thus, the 3D coordinates of the POI at the reporting time could have large errors. There is no way to account for this while digitizing the first POI because the shape of the pose map is not known yet. The work-around is to provide a function so the user can recalculate the 3D coordinates after the pose map contains more poses.
</li>
</ul>


|}
<h4><span class="mw-customtoggle-View"><span class="mw-customtoggletext" style="color:rgb(6,69,173);">View Menu</span></span></h4>
<div id="mw-customcollapsible-View" class="toccolours mw-collapsible mw-collapsed" style="margin-left:1em; width:80%;">


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
[[File:L3D_ViewMenu.png|right]]
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Options Menu
|-
|


<ul>
;Show All POIs (Ctrl + A)
<li>
: toggles the display of all of the POIs for all objects in the current trial.
'''Settings''': opens the Settings dialog
</li>
</ul>


|}
;Show Body Reference Frame (Alt+ R)
: toggles the display of the reference frame for the current object, as long as a local frame is defined in the subject file and the pose for the current frame has been calculated.


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;Show Landmarks (Alt+ L)
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Help Menu
: toggles the display of all of the landmarks for the current object.
|-
|


<ul>
;DSX Configuration (Ctrl + Shift + D)
<li>
: toggles the display of the dockable widget that shows the current session’s objects.
'''Help''' (F1): opens the Locate3D wiki page in the default browser.
</li>
<li>
'''About...''': displays a dialog with information about Locate3D, including the installed version number. It also contains the ''Deactivate'' button, for deactivating your DSX suite license.
</li>
</ul>


|}
;Points of Interest (Ctrl + Shift + I)
: toggles the display of the dockable widget that shows the details of the points of interest.


==Widgets==
;POI Parameters (Ctrl + Shift + P)
: toggles the display of the dockable ''POI Parameters'' widget.


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;POI Graphs (Ctrl + Shift + G)
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DSX Configuration
: toggles the display of the dockable widget that shows the XYZ coordinate graphs of the currently selected POIs.
|-
|
[[Image:L3D_DSXConfigurationWidget2.png|right]]


<ul>
</div>
<li>
'''Subject''': This field is automatically populated with the ID of the subject when you load a subject file.
</li>
<li>
'''Session''': This drop down menu is automatically populated with all of the sessions available for the current subject.
</li>
<li>
'''Configuration''': This drop down menu is automatically populated with all of the configurations available for the current session.
</li>
<li>
'''Trial''': This drop down menu is automatically populated with all of the trials available for the current configuration.
</li>
<li>
'''Object''': This list is automatically populated with all of the objects in the current trial. When an object is selected, its POIs are displayed in the ''Points of Interest'' widget.
</li>
</ul>


|}
<h4><span class="mw-customtoggle-Tools"><span class="mw-customtoggletext" style="color:rgb(6,69,173);">Tools Menu</span></span></h4>
<div id="mw-customcollapsible-Tools" class="toccolours mw-collapsible mw-collapsed" style="margin-left:1em; width:80%;">


{| class="mw-collapsible mw-collapsed wikitable" id="Points_of_Interest_Widget" width="80%"
[[File:L3D_ToolsMenu.png|right]]
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Points of Interest
|-
|
[[Image:L3D_PointsOfInterestWidget.png]]


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;Propagate POIs (Ctrl + P)
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Propagate Range
: This command propagates all POIs in the current object through all of the frames selected in the ''Propagate Range'' slider. For each POI, Locate3D fits a GCV spline to the poses in that POI's pose map (as shown in the ''POI Graphs'' widget). For each reporting time in the range, if the POI does not already have a pose at that time, Locate3D interpolates the X, Y, and Z splines to calculate the expected location of the POI in each X-ray view. A region of the X-ray image around this point is then searched for a suitable location of the POI center. The size of this region is determined by the ''Propagation Search Factor'' parameter. If the POI moves a lot from frame to frame and this movement is not adequately predicted by the splines, you make need to increase the ''Propagation Search Factor''. However, if this parameter is too large, or if several POIs are close to each other, Locate3D may misidentify POIs during propagation.
|-
|
The ''Propagate Range'' slider lets you specify the range of frames over which the ''Propagate POIs'' command (in the ''Tools'' menu) operates. Once you have digitized a POI in one or more frames of a trial, the ''Propagate POIs'' command uses the spline through the poses (shown in the graphs) to attempt to digitize the POI in all frames in this range that do not already have a pose.
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;Compute Object Poses from POIs (Ctrl + C)
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;POIs
: This command clears the pose map of the current object, then calculates poses for all frames using the POI locations. For each frame, if three or more POIs have defined locations, Locate3D will calculate the object pose using a least-squares optimization that fits the POIs defined in the 3D voxel data to the POIs defined in the X-ray coordinate system. The 6-DOF pose for that frame is then added to the object's pose map.
|-
|
There are six columns in the POI table:
:'''Name''' is the name of the POI, which is used to identify the POI in the X-ray windows and in all 2D and 3D coordinate files. It can be changed by double clicking on the cell and typing in a new name.
:'''Pose''' is a checkbox which is checked when the POI's 3D location is defined for the current frame. Deselecting it deletes its location for the current frame.
:'''Visibility''' toggles the visibility of the POI in the X-ray windows. It does not affect the presence or absence of locations in the pose map.
:'''Graph''' toggles the visibility of the POI in the ''POI Graphs'' Widget.
:'''Trail''' toggles the visibility of the POI's entire pose map in the X-ray windows.
:'''Color''' controls the color of the POI in both the X-ray windows and the POI Graphs Widget. Double clicking on the color cell opens a ''Select Color'' dialogue which allows you to change the color.
|}
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;Recalculate 3D POIs (Ctrl + R)
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;POI Parameters
: This command is enabled only for asynchronous trials. When the first pose for a POI is digitized, there is no valid pose map yet to extrapolate from the two frame times to the reporting time (the pose map splines are straight lines with slope=0, passing through the point being digitized). Thus, the 3D coordinates of the POI at the reporting time could have large errors. There is no way to account for this while digitizing the first POI because the shape of the pose map is not yet known. This function lets you recalculate the 3D coordinates with higher accuracy after the pose map contains more poses.
|-
|
[[Image:L3D_POIParametersWidget.png]]


The POI Parameters widget displays the parameters that govern the digitization of POIs in the X-ray images.
</div>


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
<h4><span class="mw-customtoggle-Options"><span class="mw-customtoggletext" style="color:rgb(6,69,173);">Options Menu</span></span></h4>
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;POI Scale
<div id="mw-customcollapsible-Options" class="toccolours mw-collapsible mw-collapsed" style="margin-left:1em; width:80%;">
|-
|
:''POI Scale'' is used to calculate the expected radius, in pixels, of the POI in the X-ray images. The expected radius is the physical size of the POI multiplied by the scale factor, divided by the pixel size. The scale factor should increase with the distance between the POI and the image plane. The default value is 1.0.
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
[[File:L3D_OptionsMenu.png|right]]
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Click Search Factor
|-
|
''Click Search Factor'' is used when manually digitizing POIs in the X-ray images. If you click at point X,Y in an image, a region of the image around this point is searched for the best location of a grayscale centroid. This region is a square centered at X,Y with sides equal to two times the expected radius of the POI times the ''Click Search Factor''. This factor should be set small enough so that the search region includes only the POI you're currently digitizing. The default value is 1.25.  
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
;Settings: opens the Settings dialog
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Propagation Search Factor
|-
|
''Propagation Search Factor'' is used when propagating POIs in the X-ray images. In order to propagate a POI with coordinates X,Y in one frame to the next frame, a region of the next frame is searched for the best location of a grayscale centroid. This region is a square centered at X,Y with sides equal to two times the expected radius of the POI times the propagation search factor. This factor should be set large enough so that the search region captures the movement of the POI from one frame to the next, but small enough so that it does not include other POIs. The default value is 2.0.
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
</div>
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Centroid Threshold
|-
|
''Centroid Threshold'' is the relative threshold for identifying pixels that belong to the POI. Once a grayscale region of an X-ray image has been identified as a POI, its centroid is calculated by a weighted average of all the pixels that have an intensity value greater than this percentage (0.0 to 1.0) of the maximum intensity. The default value is 0.25.
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
<h4><span class="mw-customtoggle-Help"><span class="mw-customtoggletext" style="color:rgb(6,69,173);">Help Menu</span></span></h4>
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Edge Threshold
<div id="mw-customcollapsible-Help" class="toccolours mw-collapsible mw-collapsed" style="margin-left:1em; width:80%;">
|-
|
''Edge Threshold'' is the relative threshold for identifying suitable POIs. For a grayscale region in an X-ray image to be considered a POI, the average edge value within the region must be at least this percentage (0.0 to 1.0) of the maximum edge value. The default value is 0.10.
|}


{| class="mw-collapsible mw-collapsed wikitable" width="80%"
[[File:L3D_HelpMenu.png|right]]
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Pose Map Cutoff Frequency
|-
|
''Pose Map Cutoff Frequency'' is the low-pass cut-off frequency for smoothing the cubic splines in the POI pose maps. The default value is 20.0. Smoothing can be turned off by using a value of 0.0 or less.
|}


|}
;Help (F1)
: opens the Locate3D wiki page in the default browser.


{| class="mw-collapsible mw-collapsed wikitable" id="POI_Graphs" width="80%"
;About...
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;POI Graphs
: displays a dialog with information about Locate3D, including the installed version number. It also contains the ''Deactivate'' button, for deactivating your DSX suite license.
|-
|
[[Image:L3D_GraphsFull.png]]


The ''POI Graphs'' widget displays graphs of the X, Y, and Z coordinates of the selected POIs for the current trial.
</div>


As the cursor is moved around the graph a crosshair shows the current coordinates. If the cursor is close enough to one of the data points for a POI it will snap to it and display that point's coordinates in the POI's color. To move the view of a graph in the Y direction, press the left mouse button and drag the cursor up or down. The mouse wheel can also be used to zoom the graph in the Y direction. Press the ''R'' key to reset the graph to the default view. The X axis of the graphs cannot be changed.
==Widgets==
 
Data points cannot be added or moved via the graphs, but they can be deleted. To select one or more points, press the ''Ctrl'' key and then box-select them (hold the left mouse button down while sweeping the diagonal of a box with the cursor). Press the ''Delete'' key to delete the points. Press the ''Esc'' key to deselect them.
|}
 
{| class="mw-collapsible mw-collapsed wikitable" width="80%"
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;X-ray Windows
|-
|
[[Image:L3D_2DViewer.png|600px]]
 
The X-ray windows display the X-rays of each view, as well as POIs, POI trails, reference frames, and landmarks. The ''Points of Interest'' widget lets you choose which POIs and POI trails to display on the X-rays. The ''View'' menu has commands for toggling the display of the reference frame and landmarks of the current object, and the POIs of all of the other objects.
 
The following mouse and keyboard commands can be used in the X-ray windows:
:Page Up/Down: moves to the previous/next reporting time.
:The mouse wheel zooms the X-ray image in and out.
:Press and hold the left mouse button to change the X-ray image contrast (move cursor left/right) and brightness (move cursor up/down).
:Press and hold the middle mouse button to pan the X-ray image within the window.
:'R' resets the position of the X-ray image in the window.
:'Shift-R' resets the image brightness and contrast.
 
|}
 
{| class="mw-collapsible mw-collapsed wikitable" width="80%"
! style="text-align:left;" | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Settings
|-
|
[[Image:L3D_Settings.png|300px|right]]
 
<ul>
<li>
'''Euler''': order of Euler rotations in body pose maps.
</li>
<li>
'''Color Theme''': the user can choose between a light or a dark color theme.
</li>
</ul>


|}
<!-- Note: '====' gives '[edit] link; '<h4> doesn't -->
<h4><span id="Locate3DWidget01"></span>[[Locate3D: DSX Configuration|DSX Configuration]]</h4>
<h4><span id="Locate3DWidget01"></span>[[Locate3D: Points of Interest|Points of Interest]]</h4>
<h4><span id="Locate3DWidget01"></span>[[Locate3D: POI Parameters|POI Parameters]]</h4>
<h4><span id="Locate3DWidget01"></span>[[Locate3D: POI Graphs|POI Graphs]]</h4>
<h4><span id="Locate3DWidget01"></span>[[Locate3D: X-ray Windows|X-ray Windows]]</h4>
<h4><span id="Locate3DWidget01"></span>[[Locate3D: Settings|Settings]]</h4>

Latest revision as of 21:32, 18 January 2021

Language:  English  • français • italiano • português • español 

Locate3D tracks radiopaque beads in X-ray trials. It is most often used to track objects (e.g., bones and implants) with implanted beads. If the object contains three or more beads in fixed locations, and these 3D locations are known relative to the object's CT coordinate system, then the beads' 2D locations in the X-ray images can be used to calculate the object's 3D pose in the X-ray lab frame. Locate3D is thus similar to X4D, except that it uses multiple beads to determine the pose of an object, instead of the contours of the object itself. Locate3D requires that the configuration of the X-ray equipment has been calculated (with CalibrateDSX), and that the locations of the beads in the object's local frame have been determined (with Surface3D).

Tutorials

How To: Digitize Points of Interest

How To: Track Objects Using Points of Interest

Menus

File Menu

Open Subject... (Ctrl + O)
This command loads a subject file.
Save Subject (Ctrl + S)
This command saves the currently loaded subject to its existing subject file.
Save Subject As...
This command saves the currently loaded subject to a new subject file.
Save POI Locations...
This command saves three text files containing the coordinates of the current object’s POIs. The files are as follows:
  1. one with the 3D coordinates in the X-ray reference frame of all POIs for all frames,
  2. one for the first view with the 2D POI coordinates in the image frame of the view, and
  3. one for the second view with the 2D POI coordinates in the image frame of the view.
If a name for any of these files is already specified in the subject file, it is used to write the data to. If the file already exists, it is overwritten without notification. For any that is not specified, a file browser is displayed, allowing you to select the file and folder.
Save Pose Maps
This command saves the pose map of each selected object in the current trial to a .csv file. This file contains 6 values for each pose: the XYZ translation and the XYZ Euler angles representing the transform from the X-ray lab frame to the object's local coordinate system (i.e., as if you were traveling from the lab frame to the object frame). If a name for the pose map file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file. Before the poses can be saved, they must be calculated using the Compute Object Poses from POIs command.
Save Pose Maps As...
This command saves the pose map for each selected object in the current trial to a new .csv file. You will be prompted to browse for a new file for each object. A link to this new file will then be added to the Subject file.
Save Object Transforms...
This command saves the pose map of each selected object in the current trial to a .txt file. This file contains a 4x4 transform for each pose, expressing the transform from the X-ray lab frame to the object's local coordinate system (i.e., as if you were traveling from the lab frame to the object frame). If a name for the transforms file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file. Because these transforms are calculated from the object poses, the Compute Object Poses from POIs command must be used before the transforms can be saved.
Save Landmark Locations...
This command saves a text file with the 3D coordinates of all landmarks on the current object for all frames that have poses. These locations are calculated using the object poses, so the Compute Object Poses from POIs command must be used before the landmarks can be saved. If a name for the landmarks file is not already specified in the subject file, you will be prompted to browse for the file to create. A link to this file will then be added to the subject file.
Export Poses to CMZ
This command exports the pose map of the selected object in the current trial to the session's CMZ file. If the CMZ already contains poses for this object for this trial, those poses will be removed before the current ones are exported. This command does not affect the poses of unselected objects, nor of other trials in the CMZ file. If a CMZ file is not already specified in the subject file, you will be prompted to enter the name of a new one.
Exit
This command exits the program. The program can also be closed using the X in the top right corner of the program window.

View Menu

Show All POIs (Ctrl + A)
toggles the display of all of the POIs for all objects in the current trial.
Show Body Reference Frame (Alt+ R)
toggles the display of the reference frame for the current object, as long as a local frame is defined in the subject file and the pose for the current frame has been calculated.
Show Landmarks (Alt+ L)
toggles the display of all of the landmarks for the current object.
DSX Configuration (Ctrl + Shift + D)
toggles the display of the dockable widget that shows the current session’s objects.
Points of Interest (Ctrl + Shift + I)
toggles the display of the dockable widget that shows the details of the points of interest.
POI Parameters (Ctrl + Shift + P)
toggles the display of the dockable POI Parameters widget.
POI Graphs (Ctrl + Shift + G)
toggles the display of the dockable widget that shows the XYZ coordinate graphs of the currently selected POIs.

Tools Menu

Propagate POIs (Ctrl + P)
This command propagates all POIs in the current object through all of the frames selected in the Propagate Range slider. For each POI, Locate3D fits a GCV spline to the poses in that POI's pose map (as shown in the POI Graphs widget). For each reporting time in the range, if the POI does not already have a pose at that time, Locate3D interpolates the X, Y, and Z splines to calculate the expected location of the POI in each X-ray view. A region of the X-ray image around this point is then searched for a suitable location of the POI center. The size of this region is determined by the Propagation Search Factor parameter. If the POI moves a lot from frame to frame and this movement is not adequately predicted by the splines, you make need to increase the Propagation Search Factor. However, if this parameter is too large, or if several POIs are close to each other, Locate3D may misidentify POIs during propagation.
Compute Object Poses from POIs (Ctrl + C)
This command clears the pose map of the current object, then calculates poses for all frames using the POI locations. For each frame, if three or more POIs have defined locations, Locate3D will calculate the object pose using a least-squares optimization that fits the POIs defined in the 3D voxel data to the POIs defined in the X-ray coordinate system. The 6-DOF pose for that frame is then added to the object's pose map.
Recalculate 3D POIs (Ctrl + R)
This command is enabled only for asynchronous trials. When the first pose for a POI is digitized, there is no valid pose map yet to extrapolate from the two frame times to the reporting time (the pose map splines are straight lines with slope=0, passing through the point being digitized). Thus, the 3D coordinates of the POI at the reporting time could have large errors. There is no way to account for this while digitizing the first POI because the shape of the pose map is not yet known. This function lets you recalculate the 3D coordinates with higher accuracy after the pose map contains more poses.

Options Menu

Settings
opens the Settings dialog

Help Menu

Help (F1)
opens the Locate3D wiki page in the default browser.
About...
displays a dialog with information about Locate3D, including the installed version number. It also contains the Deactivate button, for deactivating your DSX suite license.

Widgets

DSX Configuration

Points of Interest

POI Parameters

POI Graphs

X-ray Windows

Settings

Retrieved from ""