Corrected sphere UV coordinates

Fixed in text and code. This addresses the following problems:

- Confusion between UV space and texture image space. There were places
  that assumed Y/V grows, down, others where Y/V grow upwards. Correct
  UV coordinates have Y/V growing upwards, as in regular 2D Cartesian
  coordinates. The V coordinate is flipped for texture-map lookup, left
  alone for all other coordinate uses.

- The Y and Z coordinates were confused in several equations.

- The text had Y = sin(theta), where it should have been
  Y = -cos(theta).

- There was nothing in the text to explain the rearrangment of atan2()
  arguments in order to get a continuous 0->2pi return value. I
  introduced the equivalence formula to get continuous return values.

- get_sphere_uv() was in sphere.h for book 2, but hittable.h for book 3.
  This change also moves the function to sphere.h for book 3.

- get_sphere_uv() moved to be a private static method on class sphere.

- I am used to (and therefore prefer) phi corresponding to latitude, and
  theta corresponding to longitude, where the text and code flip these
  two angles. In a quick search of definitions, it looks like this is
  yet another case of competing conventions with both sides roughly
  equal in size. Thus, no clear winner, so I'm leaving this as is.

Resolves #533

Author: hollasch

CHANGELOG.md

@@ -9,6 +9,8 @@ Change Log -- Ray Tracing in One Weekend
   - Fix: `random_unit_vector()` was incorrect (#697)
   - Fix: Synchronize text and copies of `hittable.h`
   - Fix: Synchronize copies of `hittable_list.h`, `material.h`, `sphere.h`
+  - Change: refactor `sphere::hit()` method to reuse common blocks of code.
+  - Change: Improved the explanation and calculation of sphere UV coordinates (#533)
 
 ### In One Weekend
   - Change: Wrote brief explanation waving away negative t values in initial normal sphere

books/RayTracingTheNextWeek.html

@@ -1148,52 +1148,81 @@
 Texture Coordinates for Spheres
 --------------------------------
 <div class='together'>
-For spheres, this is usually based on some form of longitude and latitude, _i.e._, spherical
-coordinates. So if we have a $(\theta,\phi)$ in spherical coordinates, we just need to scale
-$\theta$ and $\phi$ to fractions. If $\theta$ is the angle down from the pole, and $\phi$ is the
-angle around the axis through the poles, the normalization to $[0,1]$ would be:
+For spheres, texture coordinates are usually based on some form of longitude and latitude, _i.e._,
+spherical coordinates. So we compute $(\theta,\phi)$ in spherical coordinates, where $\theta$ is the
+angle up from the bottom pole (that is, up from -Y), and $\phi$ is the angle around the Y-axis (from
+-X to +Z to +X to -Z back to -X).
+
+We want to map $\theta$ and $\phi$ to texture coordinates $u$ and $v$ each in $[0,1]$, where
+$(u=0,v=0)$ maps to the bottom-left corner of the texture. Thus the normalization from
+$(\theta,\phi)$ to $(u,v)$ would be:
 
   $$ u = \frac{\phi}{2\pi} $$
   $$ v = \frac{\theta}{\pi} $$
 </div>
 
 <div class='together'>
-To compute $\theta$ and $\phi$, for a given hitpoint, the formula for spherical coordinates of a
-unit radius sphere on the origin is:
+To compute $\theta$ and $\phi$ for a given point on the unit sphere centered at the origin, we start
+with the equations for the corresponding Cartesian coordinates:
 
-  $$ x = \cos(\phi) \cos(\theta) $$
-  $$ y = \sin(\phi) \cos(\theta) $$
-  $$ z = \sin(\theta) $$
+  $$ \begin{align*}
+      x &= -\cos(\phi) \sin(\theta) \\
+      y &= -\cos(\theta)            \\
+      z &= \sin(\phi) \sin(\theta)
+     \end{align*}
+  $$
 </div>
 
 <div class='together'>
-We need to invert that. Because of the lovely `<cmath>` function `atan2()` which takes any number
-proportional to sine and cosine and returns the angle, we can pass in $x$ and $y$ (the
-$\cos(\theta)$ cancel):
+We need to invert these equations to solve for $\theta$ and $\phi$. Because of the lovely `<cmath>`
+function `atan2()`, which takes any pair of numbers proportional to sine and cosine and returns the
+angle, we can pass in $x$ and $z$ (the $\sin(\theta)$ cancel) to solve for $\phi$:
 
-  $$ \phi = \text{atan2}(y, x) $$
+  $$ \phi = \text{atan2}(z, -x) $$
 </div>
 
 <div class='together'>
-The $atan2$ returns values in the range $-\pi$ to $\pi$, so we need to take a little care there.
-The $\theta$ is more straightforward:
+`atan2()` returns values in the range $-\pi$ to $\pi$, but they go from 0 to $\pi$, then flip to
+$-\pi$ and proceed back to zero. While this is mathematically correct, we want $u$ to range from $0$
+to $1$, not from $0$ to $1/2$ and then from $-1/2$ to $0$. Fortunately,
+
+  $$ \text{atan2}(a,b) = \text{atan2}(-a,-b) + \pi, $$
+
+and the second formulation yields values from $0$ continuously to $2\pi$. Thus, we can compute
+$\phi$ as
+
+  $$ \phi = \text{atan2}(-z, x) + \pi $$
+</div>
 
-  $$ \theta = \text{asin}(z) $$
+<div>
+The derivation for $\theta$ is more straightforward:
 
-which returns numbers in the range $-\pi/2$ to $\pi/2$.
+  $$ \theta = \text{acos}(-y) $$
 </div>
 
 <div class='together'>
-So for a sphere, the $(u,v)$ coord computation is accomplished by a utility function that expects
-things on the unit sphere centered at the origin:
+So for a sphere, the $(u,v)$ coord computation is accomplished by a utility function that takes
+points on the unit sphere centered at the origin, and computes $u$ and $v$:
 
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++
-    void get_sphere_uv(const vec3& p, double& u, double& v) {
-        auto phi = atan2(p.z(), p.x());
-        auto theta = asin(p.y());
-        u = 1-(phi + pi) / (2*pi);
-        v = (theta + pi/2) / pi;
-    }
+    class sphere : public hittable {
+        ...
+        private:
+            static void get_sphere_uv(const point3& p, double& u, double& v) {
+                // p: a given point on the sphere of radius one, centered at the origin.
+                // u: returned value [0,1] of angle around the Y axis from X=-1.
+                // v: returned value [0,1] of angle from Y=-1 to Y=+1.
+                //     <1 0 0> yields <0.50 0.50>       <-1  0  0> yields <0.00 0.50>
+                //     <0 1 0> yields <0.50 1.00>       < 0 -1  0> yields <0.50 0.00>
+                //     <0 0 1> yields <0.25 0.50>       < 0  0 -1> yields <0.75 0.50>
+
+                auto theta = acos(-p.y());
+                auto phi = atan2(-p.z(), p.x()) + pi;
+
+                u = phi / (2*pi);
+                v = theta / pi;
+            }
+    };
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     [Listing [get-sphere-uv]: <kbd>[sphere.h]</kbd> get_sphere_uv function]
 </div>

src/TheNextWeek/sphere.h

@@ -32,6 +32,22 @@ class sphere : public hittable {
         point3 center;
         double radius;
         shared_ptr<material> mat_ptr;
+
+    private:
+        static void get_sphere_uv(const point3& p, double& u, double& v) {
+            // p: a given point on the sphere of radius one, centered at the origin.
+            // u: returned value [0,1] of angle around the Y axis from X=-1.
+            // v: returned value [0,1] of angle from Y=-1 to Y=+1.
+            //     <1 0 0> yields <0.50 0.50>       <-1  0  0> yields <0.00 0.50>
+            //     <0 1 0> yields <0.50 1.00>       < 0 -1  0> yields <0.50 0.00>
+            //     <0 0 1> yields <0.25 0.50>       < 0  0 -1> yields <0.75 0.50>
+
+            auto theta = acos(-p.y());
+            auto phi = atan2(-p.z(), p.x()) + pi;
+
+            u = phi / (2*pi);
+            v = theta / pi;
+        }
 };
 
 
@@ -43,14 +59,6 @@ bool sphere::bounding_box(double time0, double time1, aabb& output_box) const {
 }
 
 
-void get_sphere_uv(const point3& p, double& u, double& v) {
-    auto phi = atan2(p.z(), p.x());
-    auto theta = asin(p.y());
-    u = 1-(phi + pi) / (2*pi);
-    v = (theta + pi/2) / pi;
-}
-
-
 bool sphere::hit(const ray& r, double t_min, double t_max, hit_record& rec) const {
     vec3 oc = r.origin() - center;
     auto a = r.direction().length_squared();

src/TheRestOfYourLife/hittable.h

@@ -18,13 +18,6 @@
 
 class material;
 
-void get_sphere_uv(const point3& p, double& u, double& v) {
-    auto phi = atan2(p.z(), p.x());
-    auto theta = asin(p.y());
-    u = 1-(phi + pi) / (2*pi);
-    v = (theta + pi/2) / pi;
-}
-
 
 struct hit_record {
     point3 p;

src/TheRestOfYourLife/sphere.h

@@ -35,6 +35,22 @@ class sphere : public hittable {
         point3 center;
         double radius;
         shared_ptr<material> mat_ptr;
+
+    private:
+        static void get_sphere_uv(const point3& p, double& u, double& v) {
+            // p: a given point on the sphere of radius one, centered at the origin.
+            // u: returned value [0,1] of angle around the Y axis from X=-1.
+            // v: returned value [0,1] of angle from Y=-1 to Y=+1.
+            //     <1 0 0> yields <0.50 0.50>       <-1  0  0> yields <0.00 0.50>
+            //     <0 1 0> yields <0.50 1.00>       < 0 -1  0> yields <0.50 0.00>
+            //     <0 0 1> yields <0.25 0.50>       < 0  0 -1> yields <0.75 0.50>
+
+            auto theta = acos(-p.y());
+            auto phi = atan2(-p.z(), p.x()) + pi;
+
+            u = phi / (2*pi);
+            v = theta / pi;
+        }
 };
 
 double sphere::pdf_value(const point3& o, const vec3& v) const {
@@ -64,6 +80,7 @@ bool sphere::bounding_box(double time0, double time1, aabb& output_box) const {
     return true;
 }
 
+
 bool sphere::hit(const ray& r, double t_min, double t_max, hit_record& rec) const {
     vec3 oc = r.origin() - center;
     auto a = r.direction().length_squared();