Camera: Add tangential distortion coefficients

Also improve the documentation for the radialDistortion tag in
general.

Bug: 20123879
Change-Id: I2266ed4f643e9324ac621257523fb45bcc349e3d

2 files changed, 89 insertions, 41 deletions

diff --git a/camera/docs/docs.html b/camera/docs/docs.html
index 60663e20..406e20ef 100644
--- a/camera/docs/docs.html
+++ b/camera/docs/docs.html
@@ -12208,7 +12208,7 @@ point,<wbr/> <code>z_<wbr/>s = 1</code>,<wbr/> and <code>w_<wbr/>s</code> is a m
                 <span class="entry_type_container">x</span>
 
                 <span class="entry_type_array">
-                  3
+                  5
                 </span>
               <span class="entry_type_visibility"> [public]</span>
 
@@ -12221,12 +12221,12 @@ point,<wbr/> <code>z_<wbr/>s = 1</code>,<wbr/> and <code>w_<wbr/>s</code> is a m
 
             <td class="entry_description">
               <p>The correction coefficients to correct for this camera device's
-radial lens distortion.<wbr/></p>
+radial and tangential lens distortion.<wbr/></p>
             </td>
 
             <td class="entry_units">
               
-            Coefficients for a 6th-degree even radial polynomial.<wbr/>
+            Unitless coefficients.<wbr/>
           
             </td>
 
@@ -12245,17 +12245,32 @@ radial lens distortion.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Three cofficients <code>[kappa_<wbr/>1,<wbr/> kappa_<wbr/>2,<wbr/> kappa_<wbr/>3]</code> that
-can be used to correct the lens's radial geometric
-distortion with the mapping equations:</p>
-<pre><code> x_<wbr/>c = x_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 )
-y_<wbr/>c = y_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 )
+              <p>Three radial distortion coefficients <code>[kappa_<wbr/>1,<wbr/> kappa_<wbr/>2,<wbr/>
+kappa_<wbr/>3]</code> and two tangential distortion coefficients
+<code>[kappa_<wbr/>4,<wbr/> kappa_<wbr/>5]</code> that can be used to correct the
+lens's geometric distortion with the mapping equations:</p>
+<pre><code> x_<wbr/>c = x_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>4 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>5 * ( r^2 + 2 * x_<wbr/>i^2 )
+ y_<wbr/>c = y_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>5 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>4 * ( r^2 + 2 * y_<wbr/>i^2 )
+</code></pre>
+<p>Here,<wbr/> <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> are the coordinates to sample in the
+input image that correspond to the pixel values in the
+corrected image at the coordinate <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code>:</p>
+<pre><code> correctedImage(x_<wbr/>i,<wbr/> y_<wbr/>i) = sample_<wbr/>at(x_<wbr/>c,<wbr/> y_<wbr/>c,<wbr/> inputImage)
 </code></pre>
-<p>where <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code> are normalized coordinates with <code>(0,<wbr/>0)</code>
-at the lens optical center,<wbr/> and <code>[-1,<wbr/> 1]</code> are the edges of
-the active pixel array; and where <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> are the
-corrected normalized coordinates with radial distortion
-removed; and <code>r^2 = x_<wbr/>i^2 + y_<wbr/>i^2</code>.<wbr/></p>
+<p>The pixel coordinates are defined in a normalized
+coordinate system related to the
+<a href="#dynamic_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a> calibration fields.<wbr/>
+Both <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code> and <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> have <code>(0,<wbr/>0)</code> at the
+lens optical center <code>[c_<wbr/>x,<wbr/> c_<wbr/>y]</code>.<wbr/> The maximum magnitudes
+of both x and y coordinates are normalized to be 1 at the
+edge further from the optical center,<wbr/> so the range
+for both dimensions is <code>-1 &lt;= x &lt;= 1</code>.<wbr/></p>
+<p>Finally,<wbr/> <code>r</code> represents the radial distance from the
+optical center,<wbr/> <code>r^2 = x_<wbr/>i^2 + y_<wbr/>i^2</code>,<wbr/> and its magnitude
+is therefore no larger than <code>|<wbr/>r|<wbr/> &lt;= sqrt(2)</code>.<wbr/></p>
+<p>The distortion model used is the Brown-Conrady model.<wbr/></p>
             </td>
           </tr>
 
@@ -12984,7 +12999,7 @@ point,<wbr/> <code>z_<wbr/>s = 1</code>,<wbr/> and <code>w_<wbr/>s</code> is a m
                 <span class="entry_type_container">x</span>
 
                 <span class="entry_type_array">
-                  3
+                  5
                 </span>
               <span class="entry_type_visibility"> [public]</span>
 
@@ -12997,12 +13012,12 @@ point,<wbr/> <code>z_<wbr/>s = 1</code>,<wbr/> and <code>w_<wbr/>s</code> is a m
 
             <td class="entry_description">
               <p>The correction coefficients to correct for this camera device's
-radial lens distortion.<wbr/></p>
+radial and tangential lens distortion.<wbr/></p>
             </td>
 
             <td class="entry_units">
               
-            Coefficients for a 6th-degree even radial polynomial.<wbr/>
+            Unitless coefficients.<wbr/>
           
             </td>
 
@@ -13021,17 +13036,32 @@ radial lens distortion.<wbr/></p>
           </tr>
           <tr class="entry_cont">
             <td class="entry_details" colspan="5">
-              <p>Three cofficients <code>[kappa_<wbr/>1,<wbr/> kappa_<wbr/>2,<wbr/> kappa_<wbr/>3]</code> that
-can be used to correct the lens's radial geometric
-distortion with the mapping equations:</p>
-<pre><code> x_<wbr/>c = x_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 )
-y_<wbr/>c = y_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 )
+              <p>Three radial distortion coefficients <code>[kappa_<wbr/>1,<wbr/> kappa_<wbr/>2,<wbr/>
+kappa_<wbr/>3]</code> and two tangential distortion coefficients
+<code>[kappa_<wbr/>4,<wbr/> kappa_<wbr/>5]</code> that can be used to correct the
+lens's geometric distortion with the mapping equations:</p>
+<pre><code> x_<wbr/>c = x_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>4 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>5 * ( r^2 + 2 * x_<wbr/>i^2 )
+ y_<wbr/>c = y_<wbr/>i * ( 1 + kappa_<wbr/>1 * r^2 + kappa_<wbr/>2 * r^4 + kappa_<wbr/>3 * r^6 ) +
+       kappa_<wbr/>5 * (2 * x_<wbr/>i * y_<wbr/>i) + kappa_<wbr/>4 * ( r^2 + 2 * y_<wbr/>i^2 )
+</code></pre>
+<p>Here,<wbr/> <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> are the coordinates to sample in the
+input image that correspond to the pixel values in the
+corrected image at the coordinate <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code>:</p>
+<pre><code> correctedImage(x_<wbr/>i,<wbr/> y_<wbr/>i) = sample_<wbr/>at(x_<wbr/>c,<wbr/> y_<wbr/>c,<wbr/> inputImage)
 </code></pre>
-<p>where <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code> are normalized coordinates with <code>(0,<wbr/>0)</code>
-at the lens optical center,<wbr/> and <code>[-1,<wbr/> 1]</code> are the edges of
-the active pixel array; and where <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> are the
-corrected normalized coordinates with radial distortion
-removed; and <code>r^2 = x_<wbr/>i^2 + y_<wbr/>i^2</code>.<wbr/></p>
+<p>The pixel coordinates are defined in a normalized
+coordinate system related to the
+<a href="#dynamic_android.lens.intrinsicCalibration">android.<wbr/>lens.<wbr/>intrinsic<wbr/>Calibration</a> calibration fields.<wbr/>
+Both <code>[x_<wbr/>i,<wbr/> y_<wbr/>i]</code> and <code>[x_<wbr/>c,<wbr/> y_<wbr/>c]</code> have <code>(0,<wbr/>0)</code> at the
+lens optical center <code>[c_<wbr/>x,<wbr/> c_<wbr/>y]</code>.<wbr/> The maximum magnitudes
+of both x and y coordinates are normalized to be 1 at the
+edge further from the optical center,<wbr/> so the range
+for both dimensions is <code>-1 &lt;= x &lt;= 1</code>.<wbr/></p>
+<p>Finally,<wbr/> <code>r</code> represents the radial distance from the
+optical center,<wbr/> <code>r^2 = x_<wbr/>i^2 + y_<wbr/>i^2</code>,<wbr/> and its magnitude
+is therefore no larger than <code>|<wbr/>r|<wbr/> &lt;= sqrt(2)</code>.<wbr/></p>
+<p>The distortion model used is the Brown-Conrady model.<wbr/></p>
             </td>
           </tr>
 
diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml
index b68c1bab..fa823700 100644
--- a/camera/docs/metadata_properties.xml
+++ b/camera/docs/metadata_properties.xml
@@ -3653,28 +3653,46 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
         <entry name="radialDistortion" type="float" visibility="public"
                container="array">
           <array>
-            <size>3</size>
+            <size>5</size>
           </array>
           <description>
             The correction coefficients to correct for this camera device's
-            radial lens distortion.
+            radial and tangential lens distortion.
           </description>
           <units>
-            Coefficients for a 6th-degree even radial polynomial.
+            Unitless coefficients.
           </units>
           <details>
-            Three cofficients `[kappa_1, kappa_2, kappa_3]` that
-            can be used to correct the lens's radial geometric
-            distortion with the mapping equations:
-
-                 x_c = x_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 )
-                y_c = y_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 )
-
-            where `[x_i, y_i]` are normalized coordinates with `(0,0)`
-            at the lens optical center, and `[-1, 1]` are the edges of
-            the active pixel array; and where `[x_c, y_c]` are the
-            corrected normalized coordinates with radial distortion
-            removed; and `r^2 = x_i^2 + y_i^2`.
+            Three radial distortion coefficients `[kappa_1, kappa_2,
+            kappa_3]` and two tangential distortion coefficients
+            `[kappa_4, kappa_5]` that can be used to correct the
+            lens's geometric distortion with the mapping equations:
+
+                 x_c = x_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) +
+                       kappa_4 * (2 * x_i * y_i) + kappa_5 * ( r^2 + 2 * x_i^2 )
+                 y_c = y_i * ( 1 + kappa_1 * r^2 + kappa_2 * r^4 + kappa_3 * r^6 ) +
+                       kappa_5 * (2 * x_i * y_i) + kappa_4 * ( r^2 + 2 * y_i^2 )
+
+            Here, `[x_c, y_c]` are the coordinates to sample in the
+            input image that correspond to the pixel values in the
+            corrected image at the coordinate `[x_i, y_i]`:
+
+                 correctedImage(x_i, y_i) = sample_at(x_c, y_c, inputImage)
+
+            The pixel coordinates are defined in a normalized
+            coordinate system related to the
+            android.lens.intrinsicCalibration calibration fields.
+            Both `[x_i, y_i]` and `[x_c, y_c]` have `(0,0)` at the
+            lens optical center `[c_x, c_y]`. The maximum magnitudes
+            of both x and y coordinates are normalized to be 1 at the
+            edge further from the optical center, so the range
+            for both dimensions is `-1 &lt;= x &lt;= 1`.
+
+            Finally, `r` represents the radial distance from the
+            optical center, `r^2 = x_i^2 + y_i^2`, and its magnitude
+            is therefore no larger than `|r| &lt;= sqrt(2)`.
+
+            The distortion model used is the Brown-Conrady model.
           </details>
           <tag id="DEPTH" />
         </entry>