Merge pull request #1940 from abuts/1939_draw_mask_doc

`draw_mask` algorithm documentation

Author: abuts

documentation/release_notes/v4.2.0.md

@@ -2,14 +2,24 @@
 
 # Highlights
 
+ - #1925 Horace images now contain references to the Horace objects, plotted from them.
+   `src(figure)` command allows one to retrieve the object from the figure and continue
+   analysing this object.
+   
+ - #1937 new algorithm `draw_mask` allows generation of requested mask providing sequence of points 
+    surrounding masked area.
+    If image processing toolbox (IPT) is available, the mask may be drawn on a Horace image directly. 
+    If IPT does not available, user needs to read coordinates of the points surrounding area
+    he wants to mask manually and provide their coordinates as 2-dimensional array of points.
+
  - #1668, #1908, #1918 Symmetry operations interface (for `SymopReflection` and `SymopRotation`)
-   have been modified to define rotation or reflection plane using either normal vector to the
-   plane or two vectors within this plane, whatever user prefers.
-   Both options produce the same results for orthogonal crystal lattice but for a non-orthogonal lattice
-   the definition which uses normal vector needs
-   additional information about the coordinate system this vector is expressed in.
-   User documentation have been modified to reflect the changes and describe
-   what is necessary for different lattices.
+    have been modified to define rotation or reflection plane using either normal vector to the
+    plane or two vectors within this plane, whatever user prefers.
+    Both options produce the same results for orthogonal crystal lattice but for a non-orthogonal lattice
+    the definition which uses normal vector needs
+    additional information about the coordinate system this vector is expressed in.
+    User documentation have been modified to reflect the changes and describe
+    what is necessary for different lattices.
 
  - #1822 fixed issues with pixels missing in cuts build using symmetry operations. The cuts now contain pixels modified 
     correctly so that the follow-up cuts from cut objects can be performed properly. Also fixed issues with 
@@ -31,7 +41,7 @@
     in the original file is described by projection axis. Resulting cut ranges were
     incorrectly reduced by half of original binning step in each direction.
  - #1848 `symmetrize_sqw` now can work with rotational symmetry operations.
-    To achieve that, algorithm which calculates transformation ranges when 
+    To achieve that, algorithm which calculates transformation ranges when
     `sqw` transformation during `sqw` generation is provided was modified. In addition to that, 
     the algorithm to generate `sqw` objects when transformation is present 
     has to be modified too. This fixed bugs and improve the efficiency of this

documentation/user_docs/docs/images/Draw_mask_and_apply_it_to_object.png

@@ -37,6 +37,9 @@ All configurations have the following settings:
 - ``config_folder``: Folder where configurations are stored for reloading for
   new Matlab sessions.
 
+
+.. _hor_config_settings:
+
 Horace Config
 =============
 
@@ -58,6 +61,7 @@ functionality and ``parallel_config`` to control the parameters of parallel jobs
                   use_mex: 1
                delete_tmp: 1
         working_directory: '/temp/Horace_4.0.0.f2f508726'
+       store_src_in_plots: 1
      force_mex_if_use_mex: 0
                hpc_config: [1×1 hpc_config]
           parallel_config: [1×1 parallel_config]
@@ -95,6 +99,9 @@ functionality and ``parallel_config`` to control the parameters of parallel jobs
 - ``delete_tmp`` : Whether to automatically delete temporary files after
   generating SQW files.
 - ``working_directory`` : The directory to which temporary files are written
+- ``store_src_in_plots`` : if true (default) all Horace objects are attached to the figures displaying these objects. 
+  ``src`` command then may be applied to an image to provide this object back to user. If you set this property to false,
+  objects become not available any more. (Advanced) : Reference to the plotted object is stored in MATLAB's  ``fig.UserData`` property.
 - ``hpc_config`` : Reference to the HPC configuration (:ref:`see below <HPC config>`:)
 - ``parallel_config`` : Reference to the settings to run parallel jobs (:ref:`see below <Parallel Config>`:)
 

documentation/user_docs/docs/manual/Changing_Horace_settings.rst

@@ -494,7 +494,9 @@ Simplest form of the function, which allows combining multiple cuts into single
         proj_array(i).alatt = targ_proj.alatt;
         proj_array(i).angdeg = targ_proj.angdeg;
         % transform momentum transfer values from current page of data into
-        % image associated with proj_array(i) projection
+        % image associated with proj_array(i) projection. x-axis (data.p{1})
+        % of image, produced by this projection have to coincide for all
+        % combined images.
         coord_tr = proj_array(i).transform_pix_to_img(q_coord);
         % find the data falling outside of the target image range
         % forcing target image and the image produced by current projection to

documentation/user_docs/docs/manual/Generic_Transformation.rst

@@ -615,12 +615,31 @@ e.g. following a spin wave dispersion ring/cone as a function of energy.
 Miscellaneous functions
 =======================
 
-``meta(fig)`` allows you to copy the figure into a metafile. On Windows, this
-function puts the file in the clipboard so that it can be pasted directly into
-Word, Powerpoint etc.
+* ``meta(fig)`` allows you to copy the figure into a metafile.
+  On Windows, this function puts the file in the clipboard so that it can be pasted directly into
+  Word, Powerpoint etc.
 
-``genieplot``  is a singleton, which describes common settings (configuration) used in Horace plots.
+* ``genieplot``  is a singleton, which describes common settings (configuration) used in Horace plots.
 
-``genieplot.instance()`` gives one access to the settings, similar to one, used for changing properties of MATLAB ``figure`` classes.
+* ``genieplot.instance()`` gives access to the settings common to all Horace figures.
+  The result behaves similarly to the properties of MATLAB ``figure`` classes, but is applied for all
+  figures plotted after the change.
 
-See :ref:`geneplot_settings` to get more details about Horace graphics configurations. 
+  See :ref:`geneplot_settings` to get more details about Horace graphics configurations. 
+
+* ``src(fig)``. If you plotted an object and want to return the object, used as the source of the figure,
+  you may use ``src`` command:
+
+:: 
+
+    >>source = src(fig);
+    or
+    >>source = src(figure_number);
+    
+This command returns you the Horace object (``sqw``, ``dnd`` or ``IX_dataset_nD``) used as the source of the plot. The option to store references to plotted objects in figure
+handles is configured by :ref:`Horace Configuration Settings <hor_config_settings>` property 
+``store_src_in_plots``.  If your machine has very limited memory, you may want set this property to ``false`` so this option becomes unavailable and you may delete your resulting
+objects immediately after they were plotted. By default, reference to plotted Horace object is stored in figure handle's ``UserData`` property, so the source object exist until its figure exists. ``src`` command finds appropriate figure handle and returns contents of ``UserData`` property.
+
+* ``draw_mask``. The algorithm allows you to define mask by drawing it on plotted image if image processing toolbox is installed.
+  See :ref:`draw_mask_algorithm` for more details about this routine.

documentation/user_docs/docs/manual/Plotting.rst

@@ -234,6 +234,8 @@ are convoluted.
 ``function`` may be either either ``'hat'`` or ``'gaussian'`` to apply the
 respective windowing function.
 
+.. _mask_algorithm:
+
 ``mask``
 ========
 
@@ -385,3 +387,68 @@ The inputs are:
 The output is:
 
 - ``wout``, the output sqw object with mask applied
+
+.. _draw_mask_algorithm:
+
+``draw_mask``
+=============
+
+Take 2-dimensional image or 2-dimensional Horace object and construct mask for this object for future use with 
+``mask`` algorithm :ref:`above <mask_algorithm>`. 
+Mask may be drawn on a Matlab image or defined by 2-dimensional array of image points. Drawing mask requests image processing toolbox being 
+installed but option to provide mask vertices in array works for any MATLAB version. 
+
+.. code-block:: matlab
+
+    msk  = draw_mask(win);
+    msk  = draw_mask(fig_num);
+    msk = draw_mask(fig_ax_handle);
+    
+    msk = draw_mask(__,'mask_vertices',[x1,x2,x3...;y1,y2,y3]);
+    [msk,ax,mask_vertices] = draw_mask(__);
+    
+    
+The possible inputs are:
+
+* ``win`` -- ``sqw`` object to be masked  **or**
+* ``fig_num`` -- number of existing figure to draw mask on **or**
+* ``fig_ax_handle`` -- handle to the image(``gcf`` for current) or the axis (``gca`` for current) to draw mask on.
+
+Optional:
+
+* ``'mask_vertices'`` -- key followed by 2-dimensional array of coordinates, defining points surrounding area to mask.
+  **Mandatory** if you do not have image processing toolbox installed.
+* ``'-keep_area'``   -- If option provided, area surrounded by input points is kept and external area is masked. By default,
+  mask excludes selected part of the image.   
+* ``'-freehand_draw'``   -- use MATLAB "drawfreehand" routine to draw mask on the image provided. If this key is not provided,
+  routine uses MATLAB's "drawpolygon" routine to draw the mask. Option is ignored if ``fig_info`` is Horace
+  dataset and ``mask_vertices`` are provided. Drawing options are available only if image processing toolbox is installed. 
+
+Returns:
+
+* ``msk`` logical array with dimensions of masked image i.e. ``size(win.data.npix)`` or ``win.data.img_size`` if input ``win`` object
+  is an ``sqw`` object. Object contains ``true`` for cells to keep and ``false`` for masked areas. 
+
+Additional returns:
+
+* ``ax``  -- the axes handle for the image to mask.
+* ``mask_vertices`` -- the vertices which define mask. Output ``mask_vertices`` coincide with input mask vertices
+  if you provided them, or are the coordinates of the points drawn on the image in image coordinate system if they were drawn. (needs image processing toolbox).
+
+
+The figure below shows the result of executing the following code:
+
+.. code-block:: matlab
+
+   msk  = draw_mask(6);
+   wout = mask(src(6),msk);
+   plot(wout); lz 0 0.5;
+   
+where image number 6 was present in Matlab workspace. If image processing toolbox is available, one can draw the points
+highlighted by red arrow on the left part of the image using mouse, but if toolbox is not available one needs to
+read the coordinates of these points from the image and provide them as 2x6 array of image coordinates values 
+for 'mask_vertices' key.
+
+.. figure:: ../images/Draw_mask_and_apply_it_to_object.png
+   :align: center
+   :width: 800

documentation/user_docs/docs/manual/Reshaping_etc.rst

@@ -253,7 +253,7 @@ i.e. applied in the reverse order of the list).
 .. code-block:: matlab
 
    % Rotate 90 deg about X, Reflect across X, Rotate back 90 deg about X
-   >> big_sym = [SymopRotation([1 0 0], 90), SymopReflection([0 1 0], [0 0 1]), SymopRotation([1 0 0], -90)];
+   big_sym = [SymopRotation([1 0 0], 90), SymopReflection([0 1 0], [0 0 1]), SymopRotation([1 0 0], -90)];
    
 .. note::
 

documentation/user_docs/docs/manual/Symmetrising_etc.rst

@@ -42,7 +42,9 @@
     proj_array(i).alatt = targ_proj.alatt;
     proj_array(i).angdeg = targ_proj.angdeg;
     % transform momentum transfer values from current page of data into
-    % image associated with proj_array(i) projection.
+    % image associated with proj_array(i) projection. x-axis (data.p{1})
+    % of image, produced by this projection have to coincide for all
+    % combined images.
     coord_tr = proj_array(i).transform_pix_to_img(q_coord);
     % Assume these coordinates are in the target coordinate system instead
     % of the actual coordinate system defined initially by proj_array(i).