====== COLOR DECONVOLUTION: OPTIMIZING HANDLING OF 3D UNITARY OPTICAL DENSITY VECTORS WITH POLAR COORDINATES ======
===== INTRODUCTION =====

This software was designed to ease the determination of unitary optical density vectors used in the color decovolution plugin written by Gabriel Landini [[https://blog.bham.ac.uk/intellimic/g-landini-software/colour-deconvolution-2/]] and based on the original publication by Ruifrok and Johnston:[[http://www.ncbi.nlm.nih.gov/pubmed/11531144|Quantification of histochemical staining by color deconvolution.]]
The major idea of this imageJ plugin relies on the fact that 3D optical density unitary vectors (which are the core of the colour deconvolution algorithm) have constant radius = 1. Therefore, one can transform 3D vectors to 2D vectors by using polar coordinates and getting rid of the radius. 2D optical density vectors can then be mapped on a stereographic projection map. Please refers to: [[http://www.ncbi.nlm.nih.gov/pubmed/23016461|Color deconvolution. Optimizing handling of 3D unitary optical density vectors with polar coordinates.]]
===== AUTHOR =====
Gilbert Bigras, Cross Cancer Institute, University of Alberta, Edmonton Canada (gilbert_bigras@yahoo.com)
=====FEATURES=====
  *Creation of a 2D stereographic map
  *From individual pure stains images, drawing of associated 2D optical density cluster with pseudo 3D histogram (Max 3 stains identified as **V1**, **V2** and **V3**).
  *Creation of four pictures (one original RGB picture and the three associated deconvoluted pictures generated by **V1**,**V2** and **V3**)
  *For each stain, computation of  centroid values (**phi**,**theta**) which are stored in the stereographic map and available as descriptive statistics from the menu.
  *Computation of moment of inertia for clusters
  *User can interactively change **V1**, **V2** and **V3** by clicking new position directly on the stereographic map with instant update of deconvolution algorithm
  *If only two stains are used, the third vector **V3** should not interfere in the separation of the two colors **V1** and **V2** (see example at the bottom).
=====DESCRIPTION=====
The first window corresponds to the main menu. Two major actions are possible:
  *Creation of a stereographic map by selecting pure stains (samples are available in the installation section)
  *Launching the colour deconvolution itself by choosing a stereographic map (the one you just created) or one which is already saved. Different stereographic maps can be created and saved as each map keeps track of centroid (phi,theta) values.
  *By default, RGB pixels are sampled by using the 10% highest saturated pixels
  *More details are found in the help button
{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:menu1.jpg|}}

  *Below, the second and third windows correspond to the stereographic map (left) and deconvoluted images (right). Different actions are possible:
  *Interactively modify **V1**, **V2** and **V3** by clicking a new position in the stereographic map with instant deconvolution update
  ***V1**,**V2** and **V3** are selected in the green button.
  *More details are found in the help button (bottom right within stereographic map)
{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:menu2.jpg?1280|DAB}}<imgcaption image1|This example uses three stains>Adds an ImageCaption tag</imgcaption>



{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:menu3b.jpg?1280|DAB}}<imgcaption image2|This example uses two stains. The vector 3 (V3) is empirically determined using perpendicular planes: V3 is placed in between perpendicular planes (between V1 and V2) and as far as possible from the latter in order to let V1 and V2 capture virtually all the information. Thereafter the 'unit vector OD' values can be obtained by clicking the 'Get 3D OD' button. These values can thereafter be utilized with the color deconvolution plugin developed by Gabriel Landini>Adds an ImageCaption tag</imgcaption>
=====DIFFICULTY=====
The plugin works well with big screen. You can move and resize each window and especially the stereographic map by clicking '+' and '-' signs. By doing this the vector V1 will be accidentally modified. Just click on the button 'reset all'.

**If you click 'main menu' button and click 'LAUNCH vectors selector' button again all windows will be appropriately scaled**


=====INSTALLATION=====
Simply download {{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:unitvectorsselection_.jar|}} to the Plugins folder of ImageJ, restart ImageJ and use the “UnitVectorsSelection” command in the Plugins menu. For your convenience you can download the following five pictures to try this plugin. Three are three pure stains (DAB, Hematoxylin and Red) and two composite pictures to be deconvoluted. Click on small individual image and save the larger version.
====  ====

{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:small_composite.jpg?150|Composite}}
{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:small_composite2.jpg?150|Composite}}
{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:small_pure_dab.jpg?150|DAB}}
{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:small_pure_hematoxylin.jpg?150|Hematoxylin}}
{{:plugin:color:colour_deconvolution:optimizing_selection_of_unitary_optical_density_vectors:small_pure_red.jpg?150|Red}}
=====DISCLAIMER=====
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with the programs; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

=====LICENSE=====
Free software: you can redistribute it and or modify it under the terms of the GNU General Public license as published by the Free Software Foundation; either version 2 of the license, or (at your option) any later version.

=====CHANGELOG=====
First release: December 10, 2011

Additional precisions: March 24, 2016