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

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

<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.

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.

<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.

<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.

<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.

<!-- 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>