acatalepsie/content/posts/wireframe-sphere-with-ellipses.md

---
title: Drawing a wireframe sphere with Canvas2D using ellipses
date: 2022-10-20
draft: true
math: true
---

```{=html}
<script src="/assets/sphere-main.js" defer></script>
```

In order to *visualize* a raycasting algorithm, I recently started writing some
javascript code to render [3D gizmos] using [Canvas2D].
I reached a point where I needed to draw a (unit) **sphere**. A simple mind would
think displaying a *circle* for the circumference of the sphere is enough.
But if we want to make the *rotation* of the sphere *visible* and *obvious*,
it's also important to to display its *wireframe*. 

[3D gizmos]: https://twitter.com/sbbls/status/1582473846140960769?s=20&t=K1rByQRkOudayyoWZq5yCQ
[Canvas2D]: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D

If you click and drag your mouse over the next canvas to rotate the camera
'round the spheres, it should become clear that we can only really grasp the
orientation on the right.

```{=html}
<figure id="split-fig" class="leftbottom">
  <input id="split_phi" orient="vertical" type="range" min="-1" step="any" max="1" value=".42">
  <canvas id="split" class="r2" tabindex="-1"></canvas>
  <input id="split_theta" type="range" min="0" step="any" max="1" value=".125" style="direction: rtl">
</figure>
<style>
  .leftbottom {
    display: grid;
    grid-template: "p c" 1fr
                   "_ t" auto / auto 1fr;
  }
  .leftbottom input:not([orient="vertical"]) { grid-area: t}
</style>
<script type="module">
let camera = { theta: 0, phi: 0 }
new Canvas('split', {
  inputs: [split_theta, split_phi],
  init() { setup_orbiter(this, split_theta, split_phi) },
  render(ctx) {
    ctx.clearRect(0, 0, this.width, this.height)
    ctx.translate(this.width / 2, this.height / 2)
    ctx.scale(1, -1)

    camera.theta = split_theta.value * 2 * PI
    camera.phi   = split_phi.value * PI / 2

    let x = this.width / 4
    let r = min(this.width / 2, this.height) / 2 - 20
    let c = color('dark')

    ctx.lineCap = 'round'

    // left
    ctx.translate(- x, 0)
    this.drawBasis(camera, r)
    this.drawCircle(0, 0, r, c, 4)

    // right
    ctx.translate(2 * x, 0)
    this.drawBasis(camera, r)
    this.drawCircle(0, 0, r, c, 4)
    ctx.lineCap = 'butt'
    this.drawWireframe(camera, r)
  }
})
</script>
```

But how de we render such a wireframe of the sphere using only 2D primitives?
The usual technique is to compute the position of all the vertices that compose
the wireframe. Then you compute all the edges. To render the wireframe, project
every vertex to the screen, then stroke a line segment for every edge.

```{=html}
<figure class="leftbottom">
  <input id="bad_phi" orient="vertical" type="range" min="-1" step="any" max="1" value=".42">
  <canvas id="wire" class="r1 hw" tabindex="-1"></canvas>
  <input id="bad_theta" type="range" min="0" step="any" max="1" value=".125" style="direction: rtl">
</figure>
<script type="module">
let camera = { theta: PI / 4, phi: .7 }
let points = [], edges  = []

// yes, there are duplicates at poles, no, i do not care
for (let i = 0, c = 6; i <= c; i++) {
  let b = i * Math.PI / c
  for (let j = 0, d = 8; j < d; j++) {
    let a = j / d * Math.PI * 2
    points.push(vec(cos(a) * sin(b), sin(a) * sin(b), cos(b)))
    edges.push([i * d + j, i * d + ((j + 1) % d)])
    if (i > 0) edges.push([i * d + j, (i - 1) * d + j])
  }
}

let _points = points.map(_ => vec())

new Canvas('wire', {
  inputs: [bad_theta, bad_phi],
  init() { setup_orbiter(this, bad_theta, bad_phi) },
  render(ctx) {
    ctx.clearRect(0, 0, this.width, this.height)
    ctx.translate(this.width / 2, this.height / 2)
    ctx.scale(1, -1)
    ctx.lineCap = 'round'
    camera.theta = bad_theta.value * 2 * PI
    camera.phi   = bad_phi.value * PI / 2
    points.forEach((v, i) => project(_points[i], camera, v))
    let r = min(this.width, this.height) / 2 - 20
    this.drawBasis(camera, r)
    ctx.strokeStyle = ctx.fillStyle = color('dark')
    ctx.beginPath()
    edges.forEach(([a, b]) => {
      let u = _points[a]
      let v = _points[b]
      ctx.moveTo(u.x* r, u.y * r)
      ctx.lineTo(v.x* r, v.y * r)
    })
    ctx.stroke()
}})
</script>
```

Yes, but.
A first drawback is that computing vertices and edges is quite annoying.
Projecting every vertex on the screen for every redraw is also computationally
intensive. But most importantly, **it's ugly**. Indeed, edges are straight, and
you need a lot of them to convince yourself that you are looking at a sphere.
So much so that it clutters the canvas, and makes it very hard to legibly see
what is behind the sphere. Which I want to do, because it's supposed to be a
semi-transparent gizmo.

I am the bearer of *great news*: it is actually possible to draw a wireframe sphere
(really, any 3d-rotated circle) in Canvas2D, with:

- sexy **smooth** edges, like in the first example, thanks to the `ellipse()` function.
- no need to compute individual vertices and edges.
- a short implementation (I'd argue it's simpler than manually computing vertices)

## Sphere sections

The first thing to notice is that the wireframe above is only composed of
*circles*. And not just any circles, but circles that *lay on the surface of the
sphere*. They can therefore each be characterized as the intersection of a plane
and the sphere, i.e be described by a normal vector `n` (orthogonal to the plane)
and an offset `o` (`-1 < o < 1`) for the displacement of the plane along this
normal vector.

```{=html}
<figure>
  <canvas id="circ" class="r1 hw"></canvas>
  <input id="circ_offset" type="range" min="-1" step="any" max="1" value=".5">
</figure>
<script type="module">
let _V = vec()
let p1 = vec(), p2 = vec()
let normal = vec(0, 1 / sqrt(2), 1 / sqrt(2))
let camera = { theta: PI / 4, phi: .5 }
let _normal = project(vec(), camera, normal)
new Canvas('circ', {
  inputs: [circ_offset],
  render(ctx) {
    ctx.clearRect(0, 0, this.width, this.height)
    ctx.translate(this.width / 2, this.height / 2)
    ctx.scale(1, -1)
    ctx.lineCap = 'round'

    let x = this.width / 4
    let radius = min(this.width, this.height) / 2 / sqrt(2) - 20

    this.drawBasis(camera, radius)
    this.drawVec(camera, Z, radius, color('cyan'), 3)

    project(_normal, camera, Z)
    project(p1, camera, X)
    project(p2, camera, Y)

    this.drawCircle(0, 0, radius, color('dark'), 4)
    this.drawWireframe(camera, radius)

    ctx.save()
    ctx.globalAlpha =  .5
    ctx.fillStyle = color('yellow')
    ctx.scale(radius, radius)
    ctx.translate(_normal.x * circ_offset.value, _normal.y * circ_offset.value)
    ctx.beginPath()
    ctx.moveTo(p1.x + p2.x, p1.y + p2.y)
    ctx.lineTo(p1.x - p2.x, p1.y - p2.y)
    ctx.lineTo(- p1.x - p2.x, - p1.y - p2.y)
    ctx.lineTo(- p1.x + p2.x, - p1.y + p2.y)
    ctx.fill()
    ctx.restore()

    this.pathSection(camera, Z, radius, circ_offset.value)

    ctx.strokeStyle = color('yellow')
    this.drawSectionFront(camera, Z, radius, circ_offset.value, color('yellow'), 3)

    // ctx.save()
    //   ctx.beginPath()
    //   this.pathSection(camera, Z, radius, circ_offset.value)
    //   ctx.clip()
    //   ctx.strokeStyle = color('dark')
    //   ctx.lineWidth = 4
    //   this.drawWireframe(camera, radius)
    // ctx.restore()

    // ctx.lineWidth = 6
    // ctx.strokeStyle = color('yellow')
    // this.drawSection(this.camera, this.n, r, circ_o.value)
  }
})
</script>
```

And indeed, to obtain the wireframe from earlier, we just have to cut the
sphere with:

- a plane rotating around the z axis ;
- a plane orthogonal to z, shifting along the z axis.

## Projected circles are ellipses

Now that we know what the wireframe is made of, and how to characterize these
intersections, how do we render them?

The key is to realize that the projection of a circle on the screen will *always*
be an ellipse. Conveniently, Canvas2D provides us with a way to draw ellipses,
defined as such:

> `ellipse(x, y, radiusX, radiusY, rotation, startAngle, endAngle)`
>
> The `ellipse()` method creates an elliptical arc centered at `(x, y)` with the
> radii `radiusX` and `radiusY`. The path starts at `startAngle` and ends at
> `endAngle`.


We just need to find what the parameters should be for any given section.
Because we're only doing orthographic projection here, it turns out it's really
not difficult:

- the angle of the ellipse is the angle of the (projected) normal vector on screen.
- the radius of the circle is `(1 - o * o)`, which becomes the `radiusY` of the ellipse.
- the `radiusX` of the ellipse is the radius of the circle times how much of the (projected)
  normal vector is facing us.

### Occlusion culling

We're already able to generate pretty, smooth wireframes. Now let's 
take care of *occlusion culling*. That is, only draw the arc of the ellipse
that is directly facing us.

(Actually the MDN docs are wrong here, startAngle and endAngle are the
eccentric angles of the start and end points, not an actual measurable
geometric angle).

## Putting things in perspective

So far so good. However to actually convince anyone of the versatility of this
method, we really ought to also support perspective projection. Good news:
perspective-projected circles are *still* ellipses. Bad news: computing the
parameters of the ellipse is a tad more involved, as:

- the angle of the projected normal on the screen is no longer the angle of the
  ellipse ;
- the perspective-projection of the center of the circle is no longer the
  center of the ellipse.

I'm gonna show you my method --- but I really would like a simpler one, so if
you know better, please tell me!

Until them I purposefully getting specific about the coordinate system we're
using and camera projection. But to delve into perspective projection, we cannot
cut it.

---

### Equations

You can skip this if you just want to get to the final implementation.

Without loss of generality, we can just assume we have everything expressed in
the camera coordinate system (the projection used before gets you there).
Let's consider the points on screen (at depth `z=1`) that belong to the ellipse.

They must be at coordinate `\overrightarrow{p} = (s \cdot x, s \cdot y, s)` for some $s$ because that's how
projection scaling works. The coordinates of its projection is `\overrightarrow{q} = \overrightarrow{p} / s = (x, y, 1)`
Now, this point belongs to the original circle,
therefore it satisfies the following equations:

- they are on the plane orthogonal to normal `\overrightarrow{n}` and going through `\overrightarrow{c}`,
  the center of the circle:

  `(\overrightarrow{p} - \overrightarrow{c}) \cdot \overrightarrow{n} = 0`

- they are at distance `r` from the line directed by `\overrightarrow{n}` going through `\overrightarrow{c}`:

  `\|(\overrightarrow{p} - \overrightarrow{c}) \times \overrightarrow{n}\| = r`

The first equation allows us to express $s$ in terms of $x$ and $y$:

`s = \frac{\overrightarrow{c} \cdot \overrightarrow{n}}{\overrightarrow{q} \cdot \overrightarrow{n}}`

Replacing $s$ in the second equations yields:

```
\begin{align*}&\|(\frac{\overrightarrow{c} \cdot \overrightarrow{n}}{\overrightarrow{q} \cdot
\overrightarrow{n}} \cdot \overrightarrow{q} - \overrightarrow{c}) \times
\overrightarrow{n}\| \\
=\ &\|\frac{\overrightarrow{c} \cdot \overrightarrow{n}}{\overrightarrow{q} \cdot
\overrightarrow{n}} \cdot \overrightarrow{q} \times \overrightarrow{n} - \overrightarrow{c} \times
\overrightarrow{n}\| \\
=\ &r^2\end{align*}
```

Squaring and expanding the second equation gives us:

```
$$\begin{align*}
    &((x \cdot s - c_x) \cdot n_y - (y \cdot s - c_y) \cdot n_x)^2 \\
  +\ &((s - c_z) \cdot n_x - (x \cdot s - c_x) \cdot n_z)^2 \\
  +\ &((y \cdot s - c_y) \cdot n_z - (s - c_z) \cdot n_y)^2 = r^2
\end{align*}
$$
```


----

## In conclusion

I hope this little interactive article will be useful for someone, anyone. Did
I spend way too much time thinking about ellipses for such an insignificant
result? Yes. But it's such neat technique I couldn't keep it for myself.


```{=html}
<!-- TODO: pre-compile katex to MathML only -->
<!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.css" integrity="sha384-Juol1FqnotbkyZUT5Z7gUPjQ9gzlwCENvUZTpQBAPxtusdwFLRy382PSDx5UUJ4/" crossorigin="anonymous"> -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.js" integrity="sha384-97gW6UIJxnlKemYavrqDHSX3SiygeOwIZhwyOKRfSaf0JWKRVj9hLASHgFTzT+0O" crossorigin="anonymous"></script>
<script type="module">
  const macros = {}
  document.querySelectorAll('.math').forEach(elem => {
    katex.render(elem.innerText, elem, {throwOnError: false, macros,
    displayMode: !(elem.classList.contains('inline')), output:'mathml'})
  })
</script>
```