Improve mask help text

CHANGES.md

@@ -1,6 +1,7 @@
 # ChangeLog
 
 ## vx.x.x
+* Edit mask help text and documentation #257
 * Scales the displacement vectors keeping the color bar with the displacement values. Adds title to color bar #270
 * Allow inp format in point-cloud file #269 
 * Edit documentation on registration in dvc steps #268

docs/source/dvc_steps.rst

@@ -59,31 +59,66 @@ Move to the **Mask** tab only when the registration has been confirmed at least
 
 Mask Creation
 =============
+The point cloud will be created inside a mask defined by the user. A mask is a binary image where ones represent where the points will lie. iDVC allows you to create or import a mask via file. 
+Once satisfied with the mask, move on to the **Point Cloud** panel.
 
 Creating a mask
 ~~~~~~~~~~~~~~~
+A mask is created by tracing the cross section of the mask and extending it above and below the current slice by **Slices Above** and **Slices Below** values. 
+More complex masks can be created by extending the mask by multiple tracing.
 
-A mask needs to be created to dictate where the point cloud will lie.
-To draw a mask, click on the **Start Tracing** button.
-This will allow you to trace a region freehand by left button clicking and dragging the mouse.
+The user can trace in 2 modalities: free hand and or by inserting multiple segments separated by point handles.
 
-To extend the mask in 3D, above and below the current slice, you may adjust the **Slices Above** and **Slices Below** settings,
-before clicking **create mask**.
-The **Slices Above** and **Slices Below** are in the coordinate system of the down-sampled image (if your image has been down-sampled).
+Click on the **Start Tracing** button to draw a mask and enable tracing on the viewer. 
 
-If you would like your mask to cover more than one area, or you would like to increase the area of the mask, tick the **Extend Mask** checkbox.
-Then you can draw another region and press **Extend Mask** to extend the mask to this region as well.
+Freehand tracing:
 
-Saving and Loading a mask
-~~~~~~~~~~~~~~~~~~~~~~~~~
+- Draw a free hand line: left button click over the image, hold and drag.
 
-The most recent mask you have created will automatically be saved, but if you would like to create a new mask, you will be prompted to then save the previous one, otherwise it will be discarded.
+- Erase the line: left button click and release.
 
-The names of all of the masks you have saved will appear in a dropdown list. You can select one from here and reload it.
+Multisegment tracing:
 
-Note that the mask is created in the coordinate system of the down-sampled image, so if you change the down-sampling level, you may not be able to reload a mask you have previously generated.
-Alternatively, you may load a mask from a file you have saved. This must be an uncompressed metaimage file, with the extension .mha.
-Once you are satisfied with the mask, move on to the **Point Cloud** panel.
+- Start a snap drawn line: middle button click. Terminate the line by clicking the middle button while depressing the ctrl key. 
+
+- Form a closed loop with the line: trace a continuous or snap drawn line and place the last cursor position close to the first handle. 
+
+- Point handle dragging: right button click and hold on any handle that is part of a snap drawn line. The path can be closed by overlappingg the first and last points. 
+
+- Erase any point handle: ctrl key + right button down on the handle.
+
+- Split a segment at the cursor position: shift key + right button down on any snap drawn line segment.
+
+The 2D mask drawn in the viewer is used across multiple slices in 3D, above and below the current slice; the volume can be adjusted by editing the **Slices Above** and **Slices Below** values.
+Click on **Create mask** when the tracing is finalised.
+
+Note: the **Slices Above** and **Slices Below** are in the coordinate system of the downsampled image (if the images have been downsampled).
+
+Extending a mask
+~~~~~~~~~~~~~~~~
+
+Tick the **Extend Mask** checkbox if the mask needs to cover more than one area, or the area of the mask needs to be enlarged. 
+Then, draw another region and press the button **Extend Mask**.
+
+If **Extend Mask** is not checked the mask will be reset when tracing.
+
+Saving a mask
+~~~~~~~~~~~~~
+
+The most recent mask that has been created will automatically be applied. 
+If it is intended to draw more than one mask click on the **Save Mask** button. Else, the older mask will be discarded if a new mask is created without saving the previous one.
+
+The names of all of the saved masks will appear in a dropdown list. 
+Each mask can be selected and reloaded by clicking on **Load Saved Mask**.
+
+Note: the mask is created in the coordinate system of the down-sampled image.
+If the down-sampling level is changed, you may not be able to reload a mask you have previously generated.
+
+Loading a mask from file
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an alternative to creating a mask, this may be loaded from a file by clicking **Load Mask from File**. 
+The file format should be an uncompressed metaimage file, with extension '.mha'.
 
 Point Cloud
 ===========

src/idvc/dvc_interface.py

@@ -436,8 +436,24 @@ def CreateHelpPanel(self):
             "9. Once satisfied with the registration, move to the next tab. Be aware that point 0 is the point from which DVC will start."
             )
 
-        self.help_text.append("To create a mask you need to create a selection. Start tracing a freehand region for the selection by clicking 'Start Tracing' button.\n"
-            "When you are happy with your region click 'Create Mask'.")
+        self.help_text.append(
+            "The mask dictates where the point cloud lies.\n\n"
+            "1. Click on 'Load Mask from File' to upload a mask file (format '.mha').\n"
+            "2. To create a new mask click 'Start tracing'. This enables freehand tracing on the viewer. The mask design consists of either the tracing of a single curve or the insertion of multiple spline segments separated by point handles.\n\n"
+            "- Draw a free hand line: left button click over the image, hold and drag.\n"
+            "- Erase the line: left button click and release.\n"
+            "- Start a snap drawn line: middle button click. Terminate the line by clicking the middle button while depressing the ctrl key.\n"
+            "- Form a closed loop with the line: trace a continuous or snap drawn line and place the last cursor position close to the first handle.\n" 
+            "- Point handle dragging: right button click and hold on any handle that is part of a snap drawn line. The path can be closed by overlappingg the first and last points.\n" 
+            "- Erase any point handle: ctrl key + right button down on the handle.\n"
+            "- Split a segment at the cursor position: shift key + right button down on any snap drawn line segment.\n\n"
+            "3. If you are not happy with the tracing, click on 'Stop tracing'.\n"
+            "4. The mask is used across multiple slices in 3D. The volume can be adjusted by editing the 'Slices Above' and 'Slices Below' values.\n"
+            "5. Click on 'Create mask' when the tracing is finalised.\n"
+            "6. Tick the 'Extend Mask' checkbox if the mask needs to cover more than one area, or the area of the mask needs to be enlarged. Then, draw another region and press the button 'Extend Mask'.\n"
+            "7. The most recent mask will automatically be applied. If it is intended to draw more than one mask click on 'Save Mask' and name it in the pop-up dialog.\n"
+            "8. To restart the mask creation, click on 'Clear mask'.\n"
+            "9. Each mask can be selected and reloaded by clicking on 'Load Saved Mask'.")
 
         self.help_text.append("Dense point clouds that accurately reflect sample geometry and reflect measurement objectives yield the best results.\n"
             "The first point in the cloud is significant, as it is used as a global starting point and reference for the rigid translation between the two images.\n"