add schematics and impoves how docs

docs/How.md

@@ -1,65 +1,89 @@
 ## How does it work?
 
-The underlying mathematical principal used is trigonometry. It assumes, that a reference height is known. This could be a stick of a known length leaned against the tree as optical marker, or an actual marker on the tree at a known height. Given that known height, the height of the entire tree can be calculated without actually knowing the distance to the tree. 
+The underlying mathematical principal used is trigonometry. The used formulas assume, that a reference height is known. This could be a stick of a known length leaned against the tree as optical marker, or an actual marker on the tree at a known height. Given that known height, the height of the entire tree can be calculated without actually knowing the distance to the tree. 
 
-The implementation was inspired by the formulas and explanations given at the [AWF-Wiki of University of Göttingen](http://wiki.awf.forst.uni-goettingen.de/wiki/index.php/The_trigonometric_principle). They present the following formulas in more detail and with nice pictures, so go there to learn more!
+The implementation was inspired by the formulas and explanations given at the [AWF-Wiki of University of Göttingen](http://wiki.awf.forst.uni-goettingen.de/wiki/index.php/The_trigonometric_principle). They present the formulas used in much more detail and with nice pictures. I recommend visiting their website if you want to learn more.
+
+### Schematic overview
+
+![Schema.png](Schema.png)
 
 ### Definitions for the calculation
 
-- $l$: the reference height in meters, 
-- $e$: the distance to the tree in meters
-- $\alpha1$: the angle between horizontal line and top of tree, 
-- $\alpha2$: the angle between horizontal line and bottom of tree, 
-- $\alpha3$: the angle between horizontal line and top of reference height
+First, let's define some variables for the calculations.
+
+- $l$: reference height in meters
+- $e$: distance to the tree in meters
+- $\alpha1$: angle between horizontal line and top of tree, 
+- $\alpha2$: angle between horizontal line and bottom of tree, 
+- $\alpha3$: angle between horizontal line and top of reference height
 
 ### Formulas and Calculations
 The reference height $l$ can be calulated like this:
 
-$l = e * (tan (\alpha 1) - tan(\alpha 2))$
+$l = e * (tan (\alpha 3) - tan(\alpha 2))$
 
-By transforming the formula (with given $l$), the distance to the tree can be caculated like so:
+By transforming the formula, the distance to the tree can be caculated like so:
 
-$e = \frac{l}{tan (\alpha 1) - tan(\alpha 2)}$
+$e = \frac{l}{tan (\alpha 3) - tan(\alpha 2)}$
 
-The actual tree height $h$ is constructed of
+Next, we can calculate the tree height. The tree height $h$ is constructed of
 
--  $h1$: the distance between horizontal and top of tree,  and
-- $h2$: the distance between horizontal and the bottom of the tree
+- $h1$: distance between horizontal line and the top of the tree
+- $h2$: distance between horizontal line and the bottom of the tree
 
 and can be calculated as such:
 
 $h = h1 - h2$
 
+where $h2$ has to be multiplied by `-1` if the bottom of the tree is below the horizontal line. Where this is done exactly is desribed further down in the additional considerations.
+
+Next, we can use these formulas to get $h1$ and $h2$:
+
 $h1 = e * tan(\alpha1)$
 
 $h2 = e * tan(\alpha2)$
 
-Thus, with the formula for $e$, we get the following final formula.
+which leads to
 
-$h = h1 - h2 = (e * tan(\alpha1)) - (e * tan(\alpha2))$
+$h = e * tan(\alpha1) - (e * tan(\alpha2)) = e * (tan(\alpha1) - tan(\alpha2))$
 
-$= \frac{l}{tan (\alpha 1) - tan(\alpha 2)} * tan(\alpha1) - \frac{l}{tan (\alpha 1) - tan(\alpha 2)} * tan(\alpha2)$
+Thus, with the formula for $e$, we get the following final formula for calculating the tree height with a given reference height.
 
-### Considerations in implementation
+$h =  \frac{l}{tan (\alpha 3) - tan(\alpha 2)} * (tan(\alpha1) - tan(\alpha2))$
+
+
+### Additional considerations
 To get correct results, the following things have additonally been implemented.
 
-#### Corrections for display in degrees
-When using the integrated motion sensors, the iPhone measures angles in radians. When converting those to degrees, they will repeat when looking down or up (as they are the "difference" to the horizontal line). So we must determine if we are actually looking "up" or "down" (using the gravity "z" angle of the motion sensor) and apply a transformation. 
+#### Corrections for displaying angles in degrees
+When using the integrated motion sensors, the iPhone measures angles in radians. For display, degrees are more usual and easier to grasp. The horizontal line is displayed as 90° in this app, as this is the orientation of the phone in relation to the horizontal line.
+
+When converting radians to degrees for display, they will "repeat" when looking down or up (as they are the "difference" to the horizontal line and do not reflect the actual position of the angle within a circle). 
+
+This is why we must determine, if we are actually looking "up" or "down" (using the gravity "z" angle of the motion sensor) and apply a transformation. 
 
 This was done like this:
 
-a) First, convert to degrees: 
+a) First, convert radians to degrees: 
 
 $\alpha1(deg)=alpha1(rad) * \frac{180}{\pi}$
     
-b) next, if we are looking "up", tranform it to be the correct angle: 
+b) next, if we are looking "up", transform it to be the correct angle: 
 
 $\alpha1(deg) = 180 - alpha1(deg)$
 
-#### Angle corrections to allow all possibilities of tree location
-Depending on whether the different angles are located  - above or below the horizontal line - (when the iPhone is hold in portrait orientation, these are - in degrees - 90°) the angles have to be multiplied by `-1` as needed
-    - if looking "up", multiply by `-1`, if looking down, keep the original radian value.
+#### Angle corrections to correct observer standpoint
+Depending on whether the measured angles are "positive" or "negative" - are looking "up" or "down" below the horizontal line - the angles have to be multiplied with `-1`. In the real world, this is the correction needed if the tree is located "uphill" or "downhill" from the observers standpoint. 
 
-#### Corrections for negative values
-Depending on whether certain angles are above or below the horizontal line one would get negative values in some cases. This is why at many places I used `abs` to only get the numbers in a positive range.
+By doing this transformation, the formula $h = h1 - h2$ always delivers correct results if the tree is completely above or below the observers standpoint.
+
+When the iPhone is hold in portrait orientation, the horizontal line, in degrees, is 90°. In radian measurements from the motion sensor, all values above 90° are to be interpreted as "negative" and below 90° as "positive", so the formula for $h$ keeps delivering the correct results.
+
+So if looking "up", we multiply the angle with `-1`, if looking down, we keep the original radian value. This way we can keep the original height formula unchanged, as we already applied the necessary transformation at the angle part of the formulas.
+
+#### Angle corrections for other cases
+Depending on whether certain angles are above or below the horizontal line, there can be negative values for $h$. The case left after our previous transformations is when one measurement is above the horizontal line and one measurement is below it. This case would still lead to negative results for $h$, while the absolute value is correct. That is why `abs` is used to get the absolute value. 
+
+This way the same formula from above can be used, even if the tree is partly above and partly below the observers standpoint.
 

docs/UserGuide.md

@@ -1,25 +1,37 @@
-## User Guide
+# User Guide
 
-### Before starting - prepare reference height
-When you selected a tree for measurement you first need to optically mark a reference height on it. You could do this by using a stick of a known length and leaning it at the tree. Or you could mark the height with any kind of marker. Make sure that you can see the marker from an comfortable distance - you should be able to see both easily: the marker and the top of the tree. It is recommended to get as close as possible to the tree to get the most accurate measurements.
+## Taking measurements
+### 1. Preparation
+When you selected a tree for measurement you first need to optically mark a reference height on it. You could do this by using a stick of a known length and leaning it at the tree. The top of the stick would then be the reference height. Alternatively you could mark the height with any kind of optical marker (for example tick a piece of paper at the reference height) while using a measurement tape or stick to place it at a known height. 
 
-### Taking measurements
-The calculation needs 3 measurements taken using the marker at the center of your screen.
+For best results, make sure that you can see the marker from an comfortable distance. You should be able to see these easily: 
+- the marker for the reference height
+- and the top of the tree
 
-#### Marker 1: Top of reference height
-First, mark the top of the reference height. To do so, place the top of the reference height as accurately as possible at the marker at the center of your screen. Try not to shake too much as to not disturb the motion sensor of your phone too much. 
+It is recommended to get as close as possible to the tree, while still beeing able to comfortably take measurements, to get the most accurate measurements. This way small movements of your hand do not affect the results of the motion measurements as much, as the angles will be bigger.
+
+Finally make sure to set the reference height to be your actual marker height at the top of your screen.
+
+### 2. Measurements
+The calculation needs 3 angle measurements.
+
+#### 1st Measurement -  Top of reference height
+First, mark the the reference height. 
+
+To do so, place the top of the stick or any other optical marker as accurately as possible at the marker at the center of your screen. Try not to shake your hands too much as to not disturb the motion sensor of your phone. 
 
 When you are ready, take the mark using the "shutter" button at the bottom of your screen.
 
-#### Marker 2: Bottom of tree
+#### 2nd Measurement: Bottom of tree
 For the second measurement, mark the bottom of the tree the same way as you took the first measurement.
 
-You should now see the calculated distance to the tree. If you notice a unplausible result already, start over by clicking the "reset" button.
+You should now see the calculated distance to the tree for reference. If you notice an unplausible result for this value already, it is best to start over by clicking the "reset" button and take the first two measurements again.
 
-#### Marker 3: Top of tree
-Finally, take a measurement of the top of the tree the same way you took the other measurements.
+#### 3rd Measurement: Top of tree
+Finally, point your phone to the top of the tree and take a measurement the same way you took the other measurements.
 
-The result is now presented at the top of the screen.
+The calculated tree height is now presented to you at the top of the screen.
 
-### Restart measuring
-You can at any time start over using the "reset" icon.
+## Other Actions
+### Restart measurement
+You can, at any time, start over by using the "reset" button. You will then need to begin again with the 1st measurement.