Updated Documentation

Updated the documentation to include details on using manual segmentation and pre-segmented masks.

Author: TomSlater

ParticleSpy/Parameters/manual_mask.npy

@@ -17,28 +17,69 @@ Once you have chosen your segmentation parameters and successfully prepared a pr
 Particle Analysis will run the segmentation on your data and calculate a number of parameters for each particle.
 
 The calculated parameters include:
-- Area
-- Equivalent circular diameter
-- Major and minor axes lengths
-- Circularity
-- Eccentricity
-- Total particle intensity
-- Zone axis (if atomic resolution images of fcc structure, looking to expand this!)
+
+* Area
+
+* Equivalent circular diameter
+
+* Major and minor axes lengths
+
+* Circularity
+
+* Eccentricity
+
+* Total particle intensity
+
+* Zone axis (if atomic resolution images of fcc structure, looking to expand this!)
 
 .. code-block:: python
 
     >>> #Syntax for accessing particle properties.
     >>> particles.list[0].properties['area']
 
+Combining Particles from Multiple Images
+----------------------------------------
+
+It is possible to analyse particles from multiple images by passing a previously populated Particle_list object to :py:meth:`~.ParticleAnalysis` instead of returning a new Particle_list.
+For example:
+
+.. code-block:: python
+
+    >>> ps.ParticleAnalysis(data, params, particles=particles)
+
+EDS Analysis
+------------
+
 In addition, Particle Analysis will also segment and process EDS data if given as an additional dataset in the data list.
 
 Particle Analysis can do the following processing on EDS data:
-- Obtain the EDS spectrum of each particle.
-- Obtain elemental maps of each particle.
-- Get the composition of each particle if k-factors or zeta-factors are supplied in the parameters object.
+
+* Obtain the EDS spectrum of each particle.
+
+* Obtain elemental maps of each particle.
+
+* Get the composition of each particle if k-factors or zeta-factors are supplied in the parameters object.
 
 .. code-block:: python
 
     >>> params = ps.parameters.load()
     >>> params.generate_eds(eds_method='CL',elements=['Pt','Au'],factors=[1.7,1.9],store_maps=False)
-    >>> particles = ps.ParticleAnalysis(data, params)
+    >>> particles = ps.ParticleAnalysis(data, params)
+    
+Particle Segmentation with a Pre-Generated Mask
+-----------------------------------------------
+
+:py:meth:`~.ParticleAnalysis` will also accept pre-generated masks, either generated externally or through the manual option of :py:meth:`~.SegUI`.
+In order to use a pre-generated mask it is possible to pass a mask argument to :py:meth:`~.ParticleAnalysis`.
+
+.. code-block:: python
+
+    >>> generated_mask = hs.load('maskfile')
+    >>> params = ps.parameters.load() # This isn't used if you load a pre-generated mask but you still have to pass it.
+    >>> particles = ps.ParticleAnalysis(data, params, mask=generated_mask)
+
+If you have used the manual segmentation editor in :py:meth:`~.SegUI` you can simply pass 'UI' as the mask argument.
+
+.. code-block:: python
+    
+    >>> particles = ps.ParticleAnalysis(data, params, mask='UI')

docs/_static/manual_segui.png

@@ -7,7 +7,7 @@ Segmentation
 ParticleSpy provides different options for the segmentation of particles from images.
 
 Using a Pre-Segmented Mask
-==========================
+--------------------------
 
 The most straightforward method is to supply ParticleSpy with a pre-segmented mask (boolean image).
 
@@ -18,19 +18,29 @@ The most straightforward method is to supply ParticleSpy with a pre-segmented ma
 In this way other software (e.g. ImageJ) could be used to perform segmentation which is then used by ParticleSpy to segment particles.
 
 Using the Segmentation User Interface
-=====================================
+-------------------------------------
 
-ParticleSpy can also perform its own segmentation using functions from scikit-image. A number of methods and options for segmentation are included and therefore ParticleSpy parameterizes the segmentation process. In order to choose the correct parameters for your segmentation ParticleSpy provides a Segmentation User Interface, that can be launched from a python kernel using the :py:meth:`~.SegUI` function.
+ParticleSpy can also perform its own segmentation either using automated functions from scikit-image or using a fully manual approach.
+In order to assist with both methods, ParticleSpy provides a Segmentation User Interface.
+This can be launched from a python kernel using the :py:meth:`~.SegUI` function.
 
 .. code-block:: python
 
     >>> SegUI(image)
 
-Once the Segmentation User Interface is launched the image is displayed and a number of options are available on the right hand side.
+Parameter Picking for Automated Segmentation
+============================================
+
+Once the Segmentation User Interface is launched the 'Auto' panel is displayed.
+This panel provides a number of options that can be tuned to provide an optimal automated segmentation.
+Once you have chosen your parameters, pressing 'Update' will display a segmented image.
+'Update' will also save the current parameters to use later.
 
 .. image:: _static/segui.png
     :align: center
 
+The parameters for the automated segmentation are described here:
+
 (1) Rolling ball size
 
    The rolling ball algorithm is equivalent to a top hat filter. It acts to remove slowly varying background intensity at a size larger than the particle diameter. The default is to not apply a rolling ball (value = 0). To apply a rolling ball enter a value (in pixels) that is significantly larger than your particle diameter.
@@ -73,3 +83,25 @@ Prints the current parameters as output for reference.
 (10) Display
 
 Option to display either the image with label boundaries displayed, or the solid labels coloured by label number.
+
+Manual Segmentation
+===================
+
+The second tab in the Segmentation User Interface provides an option to manually segment an individual image.
+You can get to this tab by clicking 'Manual' in the top bar.
+
+Here, segmentation works by holding the left mouse button and drawing around the outside of a particle.
+Once you have completely enclosed the particle, release the left mouse button.
+If you are happy with your particle boundary, click on the particle centre with the right mouse button.
+You may notice the middle of the particle turn slightly blue (can be difficult to see).
+Continue to segment all of the particles in the image in this way until all are segmented.
+
+Once you have segmented all of the particles, click 'Save Segmentation'.
+This will save the generated segmentation as an internal npy file that can be read when using :py:meth:`~.ParticleAnalysis`.
+
+.. image:: _static/manual_segui.png
+    :align: center
+
+.. warning::
+   Do NOT right-click on any part of the image that is not fully enclosed by a red circle.
+   Doing so will ruin the segmentation and you will have to reload SegUI.