Operation doc updates

Updates from feeback from Winfried

mantidimaging/core/operations/arithmetic/arithmetic.py

@@ -29,7 +29,7 @@ def _arithmetic_func(data: np.ndarray, div_val: float, mult_val: float, add_val:
 
 
 class ArithmeticFilter(BaseFilter):
-    """Add, subtract, multiply, or divide an image with given values.
+    """Add, subtract, multiply, or divide all gray values of an image with the given values.
 
     Intended to be used on: Any
 

mantidimaging/core/operations/circular_mask/circular_mask.py

@@ -16,7 +16,7 @@ class CircularMaskFilter(BaseFilter):
 
     Intended to be used on: Reconstructed slices
 
-    When: To remove reconstruction artifacts near the outside of the image.
+    When: To remove reconstruction artifacts on the outside of the image.
 
     Caution: Ensure that the radius does not mask data from the sample.
     """

mantidimaging/core/operations/clip_values/clip_values.py

@@ -9,10 +9,10 @@
 
 
 class ClipValuesFilter(BaseFilter):
-    """Clips pixel values of the image based on the parameters. Can be used as
-    a way to mask a.
+    """Clips grey values of the image based on the parameters. Can be used to remove outliers
+    and noise (e.g. negative values) from reconstructed images.
 
-    Intended to be used on: Projections
+    Intended to be used on: Projections and reconstructed slices
 
     When: To remove a range of pixel values from the data.
 

mantidimaging/core/operations/crop_coords/crop_coords.py

@@ -18,9 +18,9 @@
 class CropCoordinatesFilter(BaseFilter):
     """Crop a region of interest from the image.
 
-    Intended to be used on: Projections, or reconstructed slices
+    Intended to be used on: A stack of projections, or reconstructed slices
 
-    When: To remove part of the image that contains only noise, this reduces
+    When: To select part of the image that is to be processed further; this reduces
     memory usage and can greatly improve the speed of reconstruction.
 
     Caution: Make sure the region of cropping does not crop parts of the sample

mantidimaging/core/operations/divide/divide.py

@@ -14,11 +14,12 @@
 
 
 class DivideFilter(BaseFilter):
-    """Divides the images by a value. That value is usually the pixel value,
-    and can be specified in either microns or cms.
+    """Divides a stack of images by a value. That value can be the pixel size,
+    and can be specified in either microns or cms, to obtain attenuation values.
+
     Intended to be used on: Reconstructed slices
 
-    When: To calculate attenuation values by dividing by the pixel size in Microns
+    When: To calculate attenuation values by dividing by the pixel size in microns
 
     Caution: Check preview values before applying divide
     """

mantidimaging/core/operations/flat_fielding/flat_fielding.py

@@ -46,17 +46,20 @@ def enable_correct_fields_only(selected_flat_fielding_widget, flat_before_widget
 
 
 class FlatFieldFilter(BaseFilter):
-    """Uses the flat (open beam) and dark images to reduce the noise in the
-    projection images.
+    """Uses the flat (open beam) and dark images to normalise a stack of images (radiograms, projections),
+    and to correct for a beam profile, scintillator imperfections and/or  detector inhomogeneities. This
+    operation produces images of transmission values.
+
+    In practice, several open beam and dark images are averaged in the flat-fielding process.
 
     Intended to be used on: Projections
 
-    When: As one of the first pre-processing steps to greatly reduce noise in the data
+    When: As one of the first pre-processing steps
 
     Caution: Make sure the correct stacks are selected for flat and dark.
 
     Caution: Check that the flat and dark images don't have any very bright pixels,
-    or this will introduce additional noise in the sample.
+    or this will introduce additional noise in the sample. Remove outliers before flat-fielding.
     """
     filter_name = 'Flat-fielding'
 
@@ -74,10 +77,10 @@ def filter_func(images: Images,
         """Do background correction with flat and dark images.
 
         :param images: Sample data which is to be processed. Expected in radiograms
-        :param flat_before: Flat (open beam) image to use in normalization, for before the sample is imaged
-        :param flat_after: Flat (open beam) image to use in normalization, for after the sample is imaged
-        :param dark_before: Dark image to use in normalization, for before the sample is imaged
-        :param dark_after: Dark image to use in normalization, for before the sample is imaged
+        :param flat_before: Flat (open beam) image to use in normalization, collected before the sample was imaged
+        :param flat_after: Flat (open beam) image to use in normalization, collected after the sample was imaged
+        :param dark_before: Dark image to use in normalization, collected before the sample was imaged
+        :param dark_after: Dark image to use in normalization, collected before the sample was imaged
         :param selected_flat_fielding: Select which of the flat fielding methods to use, just Before stacks, just After
                                        stacks or combined.
         :param use_dark: Whether to use dark frame subtraction

mantidimaging/core/operations/gaussian/gaussian.py

@@ -19,9 +19,9 @@
 class GaussianFilter(BaseFilter):
     """Applies Gaussian filter to the data.
 
-    Intended to be used on: Projections
+    Intended to be used on: Projections or reconstructed slices
 
-    When: As a pre-processing step to reduce noise.
+    When: As a pre-processing or post-reconstruction step to reduce noise.
     """
     filter_name = "Gaussian"
     link_histograms = True

mantidimaging/core/operations/median_filter/median_filter.py

@@ -55,9 +55,9 @@ def validate(self, input: str, pos: int) -> Tuple[QValidator.State, str, int]:
 class MedianFilter(BaseFilter):
     """Applies Median filter to the data.
 
-    Intended to be used on: Projections
+    Intended to be used on: Projections or reconstructed slices
 
-    When: As a pre-processing step to reduce noise.
+    When: As a pre-processing or post-reconstruction step to reduce noise.
     """
     filter_name = "Median"
     link_histograms = True

mantidimaging/core/operations/monitor_normalisation/monitor_normalisation.py

@@ -17,11 +17,13 @@ def _divide_by_counts(data=None, counts=None):
 
 
 class MonitorNormalisation(BaseFilter):
-    """Normalises the values of the data by the monitor counts read from the Sample log file.
+    """Normalises the image data using the average count of a beam monitor from the
+    experiment log file. This scaling operation is an alternative to ROI normalisation
+    and allows to account for beam fluctuations and different exposure times of projections.
 
     Intended to be used on: Projections
 
-    When: As a pre-processing step to normalise the value ranges of the data.
+    When: As a pre-processing step to normalise the grey value ranges of the data.
     """
     filter_name = "Monitor Normalisation"
     link_histograms = True

mantidimaging/core/operations/outliers/outliers.py

@@ -22,14 +22,14 @@
 
 
 class OutliersFilter(BaseFilter):
-    """Removes pixel values that are found to be outliers by the parameters.
+    """Removes pixel values that are found to be outliers as defined by the given parameters.
 
     Intended to be used on: Projections
 
     When: As a pre-processing step to reduce very bright or dead pixels in the data.
 
-    Caution: This should usually be the first step applied to the data, flat and dark
-    images, to remove pixels with very large values that will cause issues in the flat-fielding.
+    Caution: This should usually be one of the first steps applied to the data, flat and dark
+    images, to remove pixels with very large values that will cause issues for flat-fielding.
     """
     filter_name = "Remove Outliers"
     link_histograms = True

mantidimaging/core/operations/rebin/rebin.py

@@ -14,14 +14,14 @@
 
 
 class RebinFilter(BaseFilter):
-    """Rebins the image to the given parameter.
+    """Rebin the image to reduce the resolution.
 
     This filter temporarily increases memory usage, while the image is being rebinned.
     The memory usage will be lowered after the filter has finished executing.
 
     Intended to be used on: Any data
 
-    When: If you want to reduce the data size by losing information.
+    When: If you want to reduce the data size and to smoothen the image.
     """
     filter_name = "Rebin"
     link_histograms = True

mantidimaging/core/operations/remove_all_stripe/remove_all_stripe.py

@@ -13,7 +13,8 @@
 
 
 class RemoveAllStripesFilter(BaseFilter):
-    """Remove all types of stripe artifacts by combining algorithm 6, 5, and 3.
+    """Stripe and ring artifact removal. Remove all types of stripe artifacts by
+    combining algorithm 6, 5, and 3  in Vo et al., Optics Express 28396 (2018).
     Angular direction is along the axis 0.
 
     Source: https://github.com/nghia-vo/sarepy
@@ -23,8 +24,8 @@ class RemoveAllStripesFilter(BaseFilter):
     When: If stripes artifacts are present that have not been
     removed with outliers + flat-fielding the projections
 
-    Caution: Horizontal stripes are caused by changes in image intensity (pixel values),
-    and should be fixed by ROI Normalisation instead!
+    Caution: Horizontal stripes caused by changes in image intensity (pixel values)
+    should be fixed by ROI Normalisation instead!
     """
     filter_name = "Remove all stripes"
     link_histograms = True

mantidimaging/core/operations/remove_dead_stripe/remove_dead_stripe.py

@@ -13,18 +13,19 @@
 
 
 class RemoveDeadStripesFilter(BaseFilter):
-    """Algorithm 6 in the paper. Remove unresponsive or fluctuating stripes by:
-    locating stripes, correcting by interpolation. Angular direction is along
-    the axis 0.
+    """Stripe and ring artifact removal. Algorithm 6 in Vo et al., Optics Express 28396 (2018).
+    Remove unresponsive or fluctuating stripes by: locating stripes, correction by interpolation.
+    Angular direction is along the axis 0.
 
     Source: https://github.com/nghia-vo/sarepy
 
     Intended to be used on: Sinograms
+
     When: If stripes artifacts are present that have not been
     removed with outliers + flat-fielding the projections
 
-    Caution: Horizontal stripes are caused by changes in image intensity (pixel values),
-    and should be fixed by ROI Normalisation instead!
+    Caution: Horizontal stripes caused by changes in image intensity (pixel values)
+    should be fixed by ROI Normalisation instead!
     """
     filter_name = "Remove dead stripes"
     link_histograms = True

mantidimaging/core/operations/remove_large_stripe/remove_large_stripe.py

@@ -12,18 +12,18 @@
 
 
 class RemoveLargeStripesFilter(BaseFilter):
-    """Algorithm 5 in the paper. Remove large stripes by: locating stripes,
-    normalizing to remove full stripes, using the sorting technique to remove
-    partial stripes. Angular direction is along the axis 0.
+    """Stripe and ring artifact removal: Algorithm 5 in Vo et al., Optics Express 28396 (2018).
+    Remove large stripes by: locating stripes, normalizing them to remove full stripes, using
+    the sorting technique to remove partial stripes. Angular direction is along the axis 0.
 
     Source: https://github.com/nghia-vo/sarepy
 
     Intended to be used on: Sinograms
     When: If stripes artifacts are present that have not been
     removed with outliers + flat-fielding the projections
 
-    Caution: Horizontal stripes are caused by changes in image intensity (pixel values),
-    and should be fixed by ROI Normalisation instead!
+    Caution: Horizontal stripes caused by changes in image intensity (pixel values)
+    should be fixed by ROI Normalisation instead!
     """
     filter_name = "Remove large stripes"
     link_histograms = True

mantidimaging/core/operations/remove_stripe/stripe_removal.py

@@ -10,7 +10,7 @@
 
 
 class StripeRemovalFilter(BaseFilter):
-    """Stripe removal operations wrapped from TomoPy.
+    """Stripe and ring artifact removal operations wrapped from TomoPy.
 
     Source: https://tomopy.readthedocs.io/en/latest/api/tomopy.prep.stripe.html
 
@@ -19,8 +19,8 @@ class StripeRemovalFilter(BaseFilter):
     When: If stripes artifacts are present that have not been
     removed with outliers + flat-fielding the projections
 
-    Caution: Horizontal stripes are caused by changes in image intensity (pixel values),
-    and should be fixed by ROI Normalisation instead!
+    Caution: Horizontal stripes caused by changes in image intensity (pixel values)
+    should be fixed by ROI Normalisation instead!
     """
     filter_name = "Stripe Removal"
     link_histograms = True
@@ -33,12 +33,12 @@ def filter_func(images, wf=None, ti=None, sf=None, cores=None, chunksize=None, p
         Multiple operations can be executed, if they are specified on the command
         line.
 
-        The order for that execution will always be: wavelett-fourier, titarenko,
+        The order for that execution will always be: wavelet-fourier, Titarenko,
         smoothing-filter.
 
         :param images: Sample data which is to be processed. Expected in radiograms
 
-        :param wf: Specify parameters for the wavelett-fourier filter.
+        :param wf: Specify parameters for the wavelet-fourier filter.
                    Acceptable keywords are:
 
                         level (default None, type int, optional parameter)
@@ -54,7 +54,7 @@ def filter_func(images, wf=None, ti=None, sf=None, cores=None, chunksize=None, p
                                 If True, extend the size of the sinogram by
                                 padding with zeros.
 
-        :param ti: Specify parameters for the titarenko filter.
+        :param ti: Specify parameters for the Titarenko filter.
                    Acceptable keywords are:
 
                         nblock (default:0, int, optional) Number of blocks.

mantidimaging/core/operations/remove_stripe_filtering/remove_stripe_filtering.py

@@ -14,9 +14,9 @@
 
 
 class RemoveStripeFilteringFilter(BaseFilter):
-    """Combination of algorithm 2 and algorithm 3 in [1]. Removing stripes
-    using the filtering and sorting technique. Angular direction is along the
-    axis 0.
+    """Stripe and ring artifact removal. Combination of algorithm 2 and algorithm 3 in Vo et al.,
+    Optics Express 28396 (2018). Removing stripes using the filtering and sorting technique.
+    Angular direction is along the axis 0.
 
     Source: https://github.com/nghia-vo/sarepy
 
@@ -25,8 +25,8 @@ class RemoveStripeFilteringFilter(BaseFilter):
     When: If stripes artifacts are present that have not been
     removed with outliers + flat-fielding the projections
 
-    Caution: Horizontal stripes are caused by changes in image intensity (pixel values),
-    and should be fixed by ROI Normalisation instead!
+    Caution: Horizontal stripes caused by changes in image intensity (pixel values)
+    should be fixed by ROI Normalisation instead!
     """
     filter_name = "Remove stripes with filtering"
     link_histograms = True

mantidimaging/core/operations/remove_stripe_sorting_fitting/remove_stripe_sorting_fitting.py

@@ -13,8 +13,9 @@
 
 
 class RemoveStripeSortingFittingFilter(BaseFilter):
-    """Combination of algorithm 3 and 1 in [1]. Remove stripes using the
-    sorting and fitting technique. Angular direction is along the axis 0.
+    """Stripe and ring artifact removal. Combination of algorithm 3 and 1 in Vo et al.,
+    Optics Express 28396 (2018). Remove stripes using the sorting and fitting technique.
+    Angular direction is along the axis 0.
 
     Source: https://github.com/nghia-vo/sarepy
 
@@ -23,8 +24,8 @@ class RemoveStripeSortingFittingFilter(BaseFilter):
     When: If stripes artifacts are present that have not been
     removed with outliers + flat-fielding the projections
 
-    Caution: Horizontal stripes are caused by changes in image intensity (pixel values),
-    and should be fixed by ROI Normalisation instead!
+    Caution: Horizontal stripes caused by changes in image intensity (pixel values)
+    should be fixed by ROI Normalisation instead!
     """
     filter_name = "Remove stripes with sorting and fitting"
     link_histograms = True

mantidimaging/core/operations/rescale/rescale.py

@@ -19,9 +19,7 @@ class RescaleFilter(BaseFilter):
 
     Intended to be used on: Any
 
-    When: Can be used to crop-out value regions of interest
-
-    When: Automatically used when saving images to uint16
+    When: Automatically used when saving images to unsigned int
     """
     filter_name = 'Rescale'
 

mantidimaging/core/operations/ring_removal/ring_removal.py

@@ -18,7 +18,8 @@ class RingRemovalFilter(BaseFilter):
 
     Intended to be used on: Reconstructed slices
 
-    When: To remove ring-filters that have not been removed by the pre-processing
+    When: To remove ring-artifacts that have not been removed, or have been introduced
+    by pre-processing
     """
     filter_name = "Ring Removal"
     link_histograms = True