Merge pull request #783 from luxonis/docs_math_fix

Fixed some ..math docs, as sphinx is quite strange with these

Author: Erol444

docs/source/samples/calibration/calibration_reader.rst

@@ -27,23 +27,23 @@ Here's theoretical calculation of the focal length in pixels:
 
 .. math::
 
-  focal_length_in_pixels = image_width_in_pixels * 0.5 / tan(HFOV * 0.5 * PI/180)
+  focalLength = width_px * 0.5 / tan(hfov * 0.5 * pi / 180)
 
-  // With 400P mono camera resolution where HFOV=71.9 degrees
-  focal_length_in_pixels = 640 * 0.5 / tan(71.9 * 0.5 * PI / 180) = 441.25
+To get the HFOV you can use `this script <https://gist.github.com/Erol444/4aff71f4576637624d56dce4a60ad62e>`__, which also works for wide-FOV cameras and allows you to
+specif alpha parameter.
 
-  // With 800P mono camera resolution where HFOV=71.9 degrees
-  focal_length_in_pixels = 1280 * 0.5 / tan(71.9 * 0.5 * PI / 180) = 882.5
+With 400P (640x400) camera resolution where HFOV=71.9 degrees:
 
-Examples for calculating the depth value, using the OAK-D (7.5cm baseline):
+.. math::
+
+  focalLength = 640 * 0.5 / tan(71.9 * 0.5 * PI / 180) = 441.25
+
+And for 800P (1280x800) camera resolution where HFOV=71.9 degrees:
 
 .. math::
 
-  # For OAK-D @ 400P resolution and disparity of eg. 50 pixels
-  depth = 441.25 * 7.5 / 50 = 66.19 # cm
+  focalLength = 1280 * 0.5 / tan(71.9 * 0.5 * PI / 180) = 882.5
 
-  # For OAK-D @ 800P resolution and disparity of eg. 10 pixels
-  depth = 882.5 * 7.5 / 10 = 661.88 # cm
 
 
 Setup

docs/source/tutorials/configuring-stereo-depth.rst

@@ -36,6 +36,11 @@ Let's first look at how the depth is calculated:
 
    depth [mm] = focalLength [pix] * baseline [mm] / disparity [pix]
 
+Examples for calculating the depth value, using the OAK-D (7.5cm baseline OV9282), for 400P resolution and disparity of 50 pixels:
+
+.. math::
+
+  depth = 441.25 * 7.5 / 50 = 66.19 cm
 
 `RVC2 <https://docs.luxonis.com/projects/hardware/en/latest/pages/rvc/rvc2.html>`__-based cameras have a **0..95 disparity search** range,
 which limits the minimal depth perception. Baseline is the distance between two cameras of the
@@ -280,22 +285,27 @@ Stereo subpixel effect on layering
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Default stereo depth output has 0..95 disparity pixels, which would produce 96 unique depth values. This can especially be seen when using pointcloud representation
- and seeing how there are discrete "layers" of points, instead of a smooth transition:
+and seeing how there are discrete "layers" of points, instead of a smooth transition:
 
 .. image:: /_static/images/components/layered-pointcloud.png
 
 This layering can especially be seen at longer distances, where these layers are exponentially further apart.
 
 But with Stereo Subpixel mode enabled, there are many more unique values possible, which produces more granular depth steps, and thus smoother a pointcloud.
 
+.. code-block:: python
+
+    # Number of unique values based on subpixel bits setting
+    unique_values = 94 * 2 ^ subpixel_bits + 2 [min/max value]
+
 .. math::
-    94 * 2^3 [subpixel bits] + 2 [min/max value] = 754 unique values
+    94 * 2^3 + 2 = 754
 
 .. math::
-    94 * 2^4 [subpixel bits] + 2 [min/max value] = 1506 unique values
+    94 * 2^4 + 2 = 1506
 
 .. math::
-    94 * 2^5 [subpixel bits] + 2 [min/max value] = 3010 unique values
+    94 * 2^5 + 2 = 3010
 
 One can change the number of subpixel bits by setting ``stereoDepth.setSubpixelFractionalBits(int)`` parameter to 3, 4 or 5 bits.
 
@@ -317,10 +327,10 @@ Going back to :ref:`Depth from disparity`, minimal depth perception (**MinZ**) i
 (maximum number of pixel for disparity search):
 
 .. math::
-    depth = focal_length * baseline / disparity
+    depth = focalLength * baseline / disparity
 
 .. math::
-    MinZ = focal_length * baseline / 95
+    MinZ = focalLength * baseline / 95
 
 How to get lower MinZ
 ---------------------
@@ -343,10 +353,10 @@ Above we have a formula for MinZ, and by lowering the resolution, we are lowerin
     MinZ = focalLength * baseline / 95
 
 .. math::
-    MinZ [800P OAK-D] = 882.5 * 7.5 / 95 = 70 cm
+    MinZ [800P] = 882.5 * 7.5 / 95 = 70 cm
 
 .. math::
-    MinZ [400P OAK-D] = 441 * 7.5 / 95 = 35 cm
+    MinZ [400P] = 441 * 7.5 / 95 = 35 cm
 
 As you can see, by lowering resolution by 2, we are also lowering MinZ by 2. Note that because you have fewer pixels, you will also have lower depth accuracy (in cm).
 
@@ -431,7 +441,7 @@ That gives the following formula:
   B = 2 * Dv * tan(HFOV/2) * W / (2 * D * tan(HFOV/2))
 
 .. math::
-  B = W * Dv / D  # pixels
+  B [pixels] = W * Dv / D
 
 Example: If we are using OAK-D, which has a HFOV of 72°, a baseline (:code:`BL`) of 7.5 cm and
 640x400 (400P) resolution is used, therefore :code:`W = 640` and an object is :code:`D = 100` cm away, we can
@@ -440,7 +450,7 @@ calculate :code:`B` in the following way:
 .. math::
 
   Dv = 7.5 / 2 * tan(90 - 72/2) = 3.75 * tan(54°) = 5.16 cm
-  B = 640 * 5.16 / 100 = 33 # pixels
+  B = 640 * 5.16 / 100 = 33
 
 Credit for calculations and images goes to our community member gregflurry, which he made on
 `this <https://discuss.luxonis.com/d/339-naive-question-regarding-stereodepth-disparity-and-depth-outputs/7>`__
@@ -468,6 +478,7 @@ For noisy pointcloud we suggest a few approaches:
 
 * (mentioned above) Start with the :ref:`Fixing noisy depth <2. Fixing noisy depth>` chapter, as otherwise, noise will produce points all over the pointcloud
 * (mentioned above) Continue with the :ref:`Improving depth accuracy <3. Improving depth accuracy>` chapter - depth inaccuracy will be easily visible in pointcloud
+
     * Enable Stereo subpixel mode, especially due to the :ref:`Stereo subpixel effect on layering`
 
 * :ref:`Decimation filter for pointcloud` for faster processing (FPS) and additional filtering