How to program an arcball (orbiting) camera in Unity using spherical coordinates

A while ago, I wrote this article about a simple implementation of an Arcball camera in C++. In it, I described how that could get done without using Quaternions, spherical coordinates, or a lookAt function. Anyway, just out of curiosity, I decided to create a minimal implementation of an orbiting arcball camera in C# using spherical coordinates.

Conversion from spherical to cartesian coordinates and vice versa

Before I give you the code, let’s take a look at how you can convert cartesian coordinates to spherical coordinates and vice versa. By default, Unity uses cartesian coordinates to describe where objects are located in a virtual 2D or 3D space.

However, when you want to move an object on the surface of an invisible sphere, like in this case, it makes sense to convert the cartesian coordinates to spherical coordinates, which use the radius and two angles to define the position of the object on the sphere’s surface:

Figure 1: A point P can be described using a radius and two angles

In figure 1, you can see how a point P gets mapped to the surface of a sphere. It can then get described using two angles (phi and theta) and the radius of the sphere. As a reference, you can also see the x, y, and z axes of the cartesian system.

Now, to transform a 3D point from the cartesian system to spherical coordinates, you can use the following formulas:

Figure 2: Formulas for calculating r, phi, and theta

In C# code, the conversion can get implemented like this:

Vector3 getSphericalCoordinates(Vector3 cartesian)
{
	float r = Mathf.Sqrt(
		Mathf.Pow(cartesian.x, 2) + 
		Mathf.Pow(cartesian.y, 2) + 
		Mathf.Pow(cartesian.z, 2)
	);

	// use atan2 for built-in checks
	float phi = Mathf.Atan2(cartesian.z / cartesian.x, cartesian.x);
	float theta = Mathf.Acos(cartesian.y / r);

	return new Vector3 (r, phi, theta);
}

As you can see, I used a vector to hold the three values that describe a point P in spherical coordinates. I, however, recommend that you write a custom class that holds the three values in suitably named fields.

Anyway, the conversion in the other direction is even simpler:

Figure 3: Convert spherical coordinates to carteisan coordinates with these formulas

And, again, a C# helper method could look like this:

Vector3 getCartesianCoordinates(Vector3 spherical)
{
	Vector3 ret = new Vector3 ();

	ret.x = spherical.x * Mathf.Cos (spherical.z) * Mathf.Cos (spherical.y);
	ret.y = spherical.x * Mathf.Sin (spherical.z);
	ret.z = spherical.x * Mathf.Cos (spherical.z) * Mathf.Sin (spherical.y);

	return ret;
}

Note that the axes’ names aren’t consistent between the formulas and the code because Unity uses a different reference compared to the mathematical formulas. Just keep this in mind when coding because it could save you some trouble and time!

A working barebones implementation

using System.Collections;
using System.Collections.Generic;
using UnityEngine;

[RequireComponent (typeof (Camera))]
public class ArcballScript : MonoBehaviour
{
	// Is true when the user wants to rotate the camera
	bool ballEnabled = false;

	float rotationSpeed = 1f;
	float radius = 5f;

	// The mouse cursor's position during the last frame
	Vector3 last = new Vector3();

	// The target that the camera looks at
	Vector3 target = new Vector3 (0, 0, 0);

	// The spherical coordinates
	Vector3 sc = new Vector3 ();

	void Start ()
	{
		this.transform.position = new Vector3 (radius, 0.0f, 0.0f);
		this.transform.LookAt (target);
		sc = getSphericalCoordinates (this.transform.position);
	}

	Vector3 getSphericalCoordinates(Vector3 cartesian)
	{
		float r = Mathf.Sqrt(
			Mathf.Pow(cartesian.x, 2) + 
			Mathf.Pow(cartesian.y, 2) + 
			Mathf.Pow(cartesian.z, 2)
		);

		float phi = Mathf.Atan2(cartesian.z / cartesian.x, cartesian.x);
		float theta = Mathf.Acos(cartesian.y / r);

		if (cartesian.x < 0)
			phi += Mathf.PI;

		return new Vector3 (r, phi, theta);
	}

	Vector3 getCartesianCoordinates(Vector3 spherical)
	{
		Vector3 ret = new Vector3 ();

		ret.x = spherical.x * Mathf.Cos (spherical.z) * Mathf.Cos (spherical.y);
		ret.y = spherical.x * Mathf.Sin (spherical.z);
		ret.z = spherical.x * Mathf.Cos (spherical.z) * Mathf.Sin (spherical.y);

		return ret;
	}
	
	// Update is called once per frame
	void Update ()
	{
		// Whenever the left mouse button is pressed, the
		// mouse cursor's position is stored for the arc-
		// ball camera as a reference.
		if (Input.GetMouseButtonDown(0))
		{
			// last is a global vec3 variable
			last = Input.mousePosition;

			// This is another global variable
			ballEnabled = true;
		}

		// When the user releases the left mouse button,
		// all we have to do is to reset the flag.
		if (Input.GetMouseButtonUp (0))
			ballEnabled = false;

		if (ballEnabled)
		{
			// Get the deltas that describe how much the mouse cursor got moved between frames
			float dx = (last.x - Input.mousePosition.x) * rotationSpeed;
			float dy = (last.y - Input.mousePosition.y) * rotationSpeed;

			// Only update the camera's position if the mouse got moved in either direction
			if (dx != 0f || dy != 0f)
			{
				// Rotate the camera left and right
				sc.y += dx * Time.deltaTime;

				// Rotate the camera up and down
				// Prevent the camera from turning upside down (1.5f = approx. Pi / 2)
				sc.z = Mathf.Clamp (sc.z + dy * Time.deltaTime, -1.5f, 1.5f);

				// Calculate the cartesian coordinates for unity
				transform.position = getCartesianCoordinates (sc) + target;

				// Make the camera look at the target
				transform.LookAt (target);
			}

			// Update the last mouse position
			last = Input.mousePosition;
		}
	}
}

As you can see in the update method, it’s now easy to update the position of the camera if the mouse got moved. For that, you update the phi and theta angles in the spherical coordinate system and then convert it into a cartesian system, that unity can work with.

Now you just need to attach the script to your camera object, and you’re good to go!

Summary

Spherical coordinates are useful for describing a point on the surface of a sphere. In that system, you use the radius and two angles to specify a point. If you want to move the point on the sphere’s surface, you need to update the angles. Note that you have to work in radians and not degrees.

Image sources

[Fig. 1] Kugelkoordinaten, Ag2gaeh / CC BY-SA
[Fig. 2, Fig. 3] Screenshots from wikipedia.org

2 thoughts on “How to program an arcball (orbiting) camera in Unity using spherical coordinates

Leave your two cents, comment here!

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.