Merge pull request #101 from SgStapleton/spatialplot

  </brief>

  <description>

    This program will display cubes and allow for interactive analysis.

    <p>

      This program will display cubes and allow for interactive analysis. Although the program 

      comprises a number of individual tools to perform analysis on your data, only the Spatial 

      Plot Tool is discussed here until further notice.  

    </p>

    <h3>Spatial Plot Tool</h3>

    <p>

      This tool is used for analyzing manually selected pixel DN values. It works with two 

      different modes: linear and rotated rectangle. It is also capable of handling three different 

      modes of interpolation: Nearest Neighbor, BiLinear and Cubic Convolution. 

    </p>

    <h4>Linear</h4>

    <p>

      This mode involves drawing a 

      line across an open cube. The selection is started by clicking and holding the mouse where 

      you would like to start your calculations, at which point you may drag the mouse in any 

      direction and release the click to establish the end of your selection.

    </p>

    <p>

      The tool calculates the length of the line in pixels, rounding to the nearest full pixel 

      value. It then divides the actual length of the line by this rounded length to achieve a 

      step-size. <strong>Please note:</strong> This step size may be slightly bigger or smaller 

      than a pixel length, but this difference becomes negligible for larger selections. For 

      example, if the length of the drawn line was 2.91 pixels, the tool would round the length to 

      3 and the step-size would be 2.91/3 (or 0.97).

    </p>

    <p>

      A plot window will be generated with the calculated DN values of the pixels. The first value 

      to be calculated is the value where the original mouse click was made. At each increment, 

      according to step size, the tool calculates the value along the line until it reaches where the 

      mouse-click was released. This means that for a line with a rounded length of 3, the plot would show a 

      total of 4 plotted DN values. <strong>Please note:</strong> For a line with a rounded length of 

      <i>n</i>, the tool will calculate <i>n</i> + 1 values.

    </p>

    <image src="assets/image/LinearSelection.png" height="400" />

    <image src="assets/image/LinearPlot.png" height="400" />

    <p>

      The images above include an example of the line as drawn in the cube view and the 

      associated plot window. Marking has been added to delineate where mouse clicks were made and 

      the DN values were calculated. The mouse was first clicked at dileneation marked "1" on the 

      cube, and was released at "4". The number from the cube view correlates with the "Pixel 

      Number" on the plot.

    </p>

    <h4>Rotated Rectangle</h4>

    <p>

      This mode of the Spatial Plot Tool involves drawing a 

      rectangle across an open cube. The selection starts by clicking and holding the mouse 

      where you would like to start your calculations, at which point you may drag the mouse in any 

      direction and release the click to establish one edge of your selection. You may then 

      drag the mouse away from this original line to expand in the other direction. A single mouse 

      click establishes your final selection. <strong>Please note:</strong> The tool will lock 

      angles to be perpendicular and so your selections will always be a perfect rectangle.

    </p>

    <p>

      Similar to the linear mode of this tool, the lengths of the lines in pixels are rounded to the 

      nearest full pixel value, and then the lengths are divided by their rounded lengths to establish 

      a step-size. <strong>Please note:</strong>

      The step-size along one edge of the selection may differ from the step-size of the 

      perpendicular edge, this becomes negligible for larger selections. For 

      example, if the length of the line in one direction was 2.91 pixels, the step-size would be 2.91/3 

      (or 0.97), whereas if the length of the line in the perpendicular direction was 4.92, the step 

      size would be 4.92/5 (0.98).

    </p>

    <p>

      A plot window will be generated with the calculated DN values. This is done by calculating the 

      value where the original mouse click was made, then continuing in the direction of that 

      first-drawn line, calculating the DN value at each step-sized increment until it reaches where 

      the original mouse-click was released. The tool will then calculate the average of these 

      values. This average becomes the first value in the plot.

    </p>

    <p>

      The tool will then shift a step-size along the perpendicular edge, and calculate the average DN 

      value along a line running parallel to the first-drawn line. This average becomes the second 

      value in the plot. The tool continues this pattern until it has reached the opposite edge of 

      the rectangle as the first-drawn line.

    </p>

    <image src="assets/image/RRSelection.png" height="400" />

    <image src="assets/image/RRSelectionMarked.png" height="400" />

    <image src="assets/image/RRPlot.png" height="400" />

    <p>

      The first image is the original selection. The second image 

      is the same view that has been marked for reference purposes. Finally, the last image 

      is the associated plot window. The original mouse click was made at delineation 

      "1" within the cube view, the original mouse release was made at "5", and the final 

      mouse click was made at "15". The Spatial Plot Tool calculates the average of the DN values at 

      delineations 1-5, and this value is stored as "Pixel Value" 1 in the plot window, while the 

      averages of 6-10 are stored in 2, and 7-15 are stored in 3. 

    </p>

    <h4>Interpolations</h4>

    <p>

      Spatial Plot Tool makes use of Nearest Nieghbor, BiLinear and Cubic Convolution interpolations 

      when calculating the DN values at particular points. <strong>Do be aware that when the tool is 

      calculating a DN value at a particular point, it is calculating the interpolated DN value at 

      that point.</strong>

    </p>

  </description>

  <category>

      Readded help menu for the 2D and 3D plot tools. Now properly display in both tools.

      Fixes #2126.

    </change>

    <change name="Summer Stapleton" date="2018-03-14">

      Included documentation for Spatial Plot Tool in this .xml. References #5281.

    </change>

  </history>

</application>