Arcball Camera with C++ and OpenGL

This is a little tutorial for making arcball camera with C++ and OpenGL. You can look into the GitHub repository for source code here or watch on YouTube.

Prerequistes

You have to know what arcball camera is. You also have to know C++ and OpenGL.

We used quaternions to build an arcball camera. There are also other ways to do it. OpenGL version is 3.30.

1 Quaternions

Quaternions are kind of number structure in mathematics and also used in physics and engineering. A quaternion consists of one real part and three imaginary-like parts which are called "basic quaternions." It seems in form of a + xi + yj + zk. The real part is a and i-j-k are basic quaternions. It can be thought that a quaternion is built by merging a real number and a three dimensional vector.

1.1 Properties of Quaternions

There is no need to focus all properties of quaternions. Just some of them which we use here will be given. \begin{equation*} i^2 = j^2 = k^ 2 = ijk = -1 \end{equation*} \begin{equation*} ij = k,\quad jk = i,\quad ki = j,\quad %\quad is for creating larger space between expressions. ik = -j,\quad kj = -i,\quad ji = -k \end{equation*} A quaternion can be represented in form of q = [s, v] where s is the real part and v is the vector part as v = xi + yj + zk. If \begin{align*} q_a = [s_a, v_a]\\ q_b = [s_b, v_b]\\ \end{align*} then \begin{align*} q_a + q_b = [s_a + s_b, v_a + v_b]\\ q_a - q_b = [s_a - s_b, v_a - v_b]\\ \end{align*} Assume that c is a constant; \begin{align*} cq_a = [cs_a, cv_a]. \end{align*} If you multiply two quaternions \begin{align*} q_a . q_b &= (s_a + x_ai + y_aj + z_ak)(s_b + x_bi + y_bj + z_bk)\\ &= [s_as_b - v_av_b, s_av_b + s_bv_a + v_a\times v_b] \end{align*} If θ is the rotation angle and $$u_xi + u_yj + u_zk$$ is the unit rotation axis which camera rotates about, then rotation quaternion is represented as \begin{align*} r = e^{\frac{\theta}{2}(u_xi + u_yj + u_zk)} \end{align*}

2 Arcball Camera

2.1 Getting Screen Coordinates

When we click the mouse on the application window, the position where mouse cursor on in that moment is our start position and the code gets that position. Then we move the mouse and the cursor moves on the screen (we are still pushing the mouse button), every position on the screen that our mouse stands on with pushed button is our current position and we have to calculate the rotation for every current position with start position until the mouse button is released.

The code below is for getting start position.

void mouse_button_callback(GLFWwindow* window, int button, int action, int mods){
	if(button == GLFW_MOUSE_BUTTON_LEFT && action == GLFW_PRESS){
        
		double startXPos, startYPos; //screen coordinates when mouse clicks.
		glfwGetCursorPos(window, &startXPos, &startYPos);
		//convert to NDC, then assign to startPos.
		arcCamera.startPos.x = ((startXPos - (SCR_WIDTH/2) ) / (SCR_WIDTH/2)) * RADIUS;
		// ..same for y coordinate. 
		arcCamera.startPos.y = (((SCR_HEIGHT/2) - startYPos) / (SCR_HEIGHT/2)) * RADIUS;
		arcCamera.startPos.z = arcCamera.z_axis(arcCamera.startPos.x, arcCamera.startPos.y);
		flag = true;
	}
     else if(action == GLFW_RELEASE){
        arcCamera.replace();
        flag = false;

        }
}						
					

And for getting current position

						
void mouse_pos_callback(GLFWwindow* window, double xpos, double ypos){
	if(flag == true){
	//Get the screen coordinates when mouse clicks.
	arcCamera.currentPos.x = ((xpos - (SCR_WIDTH/2) ) / (SCR_WIDTH/2)) * RADIUS;
	arcCamera.currentPos.y = (((SCR_HEIGHT/2) - ypos) / (SCR_HEIGHT/2)) * RADIUS;
	arcCamera.currentPos.z = arcCamera.z_axis(arcCamera.currentPos.x, arcCamera.currentPos.y);
	arcCamera.rotation();
    }
}
						
					

Let's explain them.

We have an "ArcballCamera" class and "arcCamera" is an object of this class (You'll see this class later). In the first piece above; when we click the button, the program gets cursor position on the application screen with "glfwGetCursorPos" and assign them to startXPos and startYPos. Then these start coordinates are converted to normalized device coordinates(NDC) and are assigned to startPos vector(it is a glm::vec3 variable). But we need z axis, because arcball camera assumes that there is a sphere which we rotates and a sphere is a 3D shape. So we have to get z axis for certain location on the sphere. The z axis is calculated with this formula: $$z=f\left(x,y\right)=\left\{\begin{array}{c}+\sqrt{1-x^2-y^2}\hfill \\ 0\hfill \end{array}\begin{array}{c},if\left(x^2+y^2\le 1\right)\hfill \\ ,if\left(x^2+y^2>1\right)\hfill \end{array}\right.$$
Now, we have normalized x, y and z coordinates for start position. Last thing we have to do in "mouse_button_callback" function is to assing "true" to the flag. This flag inform "mouse_pos_callback" function that the mouse button is pressed or released. When it is "true", "mouse_pos_callback" knows that the button is pressed and gets the current position of the cursor for every moment until the button is released. When the button is released, "false" is assigned to "flag" and the function finishes getting current position. "mouse_pos_callback" function, like we said before, gets the current position of the cursor on the window, converts them to NDCs, calculates z axis and starts the "rotation()" function of arcballCamera object. "rotation()" is the heart of this application. It's time to dive into it.

3 Rotation

Here is the algorithm:

1. Transform start and current positions to unit vectors.
2. Get rotational axis by taking cross product of start and current positions and transform it to unit vector.
3. Get cosine of the rotation angle by taking dot product of start and current unit vectors.
4. Get rotation angle θ.
5. Build currentQuaternion struct with θ and rotational axis by using required operations (assign the cosine of half the angle and rotational axis which is scaled by sine of half the angle).
6. Take $$q' = q_{current}.q_{last}$$ product.
7. Replace lastQuaternion variables with new variables after the mouse button is released.

		
struct Quaternion{
    float cosine; //cosine of half the rotation angle
    glm::vec3 axis; //unit vector scaled by sine of half the angle

};
		
	

These are structures in type of the struct "Quaternion". We created "Quaternion" structure for describing rotation with quaternions. A Quaternion structure has a "cosine" variable and an "axis" vector.
The next one is the class which we used in this study.

		
class ArcballCamera{
public:
    
    glm::vec3 position = glm::vec3(0.0f, 0.0f, -3.0f);
    glm::vec3 startPos;
    glm::vec3 currentPos = startPos;
    glm::vec3 startPosUnitVector;
    glm::vec3 currentPosUnitVector;

    Quaternion currentQuaternion;
    Quaternion lastQuaternion = {0.0f, glm::vec3(1.0f, 0.0f, 0.0f)};
    
    float cosValue, cosValue_2;
    float theta;
    float angle = 180.0f;
    glm::vec3 rotationalAxis = glm::vec3(1.0f, 0.0f, 0.0f);                       
    glm::vec3 rotationalAxis_2;
    ArcballCamera (){};
    float z_axis(float,float);
    glm::vec3 getUnitVector(glm::vec3);
    float dotProduct();
    void rotation();
    void replace();

    
};
		
	

Functions of Arcball class and what they do:

1. z_axis(float, float): Calculates z axis.
2. getUnitVector(glm::vec3): Transforms glm::vec3 parameter to unit vector.
3. dotProduct(): Calculates the dot product of start and current position's unit vector. It doesn't get any parameter.
4. rotation(): Makes all rotation calculation.
5. replace(): Replaces lastQuaternion variables with new ones.

		
startPosUnitVector = getUnitVector(startPos);
currentPosUnitVector = getUnitVector(currentPos);
currentQuaternion.axis = glm::cross(startPos, currentPos);
currentQuaternion.axis = getUnitVector(currentQuaternion.axis);
    
cosValue = dotProduct(); //q0 is cosine of the angle here.
if(cosValue > 1) cosValue = 1;
theta = (acos(cosValue) * 180 / 3.1416); //theta is the angle now.
		
	

These lines run the first four steps in the algorithm we mentioned above. Transforming start and current position vectors to unit vectors, getting rotation axis and rotation angle.In the bottom, we calculate rotation angle θ and completed the first four step of the algorithm. But maybe one line must be explained:

if(cosValue > 1) cosValue = 1;

When dotProduct() calculates the dot product of vectors and if the result is 1, it may not equal to 1 indeed. It may be 1.00000001 but when you display the result on the screen, it seems as 1. Because of this, I put this line there and it checks the result if it is 1 or not.(Maybe you may not encounter such a problem, but i did and found this solution)

Then we build currentQuaternion assigning cosine of half the rotation angle and rotation axis which is scaled by sine of half the rotation angle.

		
currentQuaternion.cosine = cos((theta / 2) * 3.1416 / 180);

currentQuaternion.axis.x = currentQuaternion.axis.x * sin((theta / 2) * 3.1416 / 180);
currentQuaternion.axis.y = currentQuaternion.axis.y * sin((theta / 2) * 3.1416 / 180);
currentQuaternion.axis.z = currentQuaternion.axis.z * sin((theta / 2) * 3.1416 / 180);
		
	

Remember, we represent rotation with quaternions.

Let's write currentQuaternion in mathematical notation: \begin{equation*} \begin{split} q_{current} &= e^{\frac{\theta}{2}(u_xi + u_yj + u_zk)}\\ &= \cos{\frac{\theta}{2}} + (u_xi + u_yj + u_zk)\sin{\frac{\theta}{2}}\\ &= [\cos{\frac{\theta}{2}} , (u_xi + u_yj + u_zk)\sin{\frac{\theta}{2}}] \end{split} \end{equation*} We have also another quaternion, called lastQuaternion, which keeps the last values of cosine and rotation axis. \begin{equation*} \begin{split} q_{last} &= e^{\frac{\theta'}{2}(u'_xi + u'_yj + u'_zk)}\\ &= \cos{\frac{\theta'}{2}} + (u'_xi + u'_yj + u'_zk)\sin{\frac{\theta'}{2}}\\ &= [\cos{\frac{\theta'}{2}} , (u'_xi + u'_yj + u'_zk)\sin{\frac{\theta'}{2}}] \end{split} \end{equation*} We have arrived the most important step. How do we calculate the rotation? We do it with this product: \begin{equation*} q' = q_{current}q_{last} \end{equation*} It was given how to product two quaternions before, so I will not mention about it again but tell how to code it. The real part of the quaternion q' is calculated by below lines:

		
glm::vec3 temporaryVector;

temporaryVector = glm::cross(currentQuaternion.axis, lastQuaternion.axis);
    

rotationalAxis_2.x = (currentQuaternion.cosine * lastQuaternion.axis.x) + 
                     (lastQuaternion.cosine * currentQuaternion.axis.x ) +
                      temporaryVector.x;

rotationalAxis_2.y = (currentQuaternion.cosine * lastQuaternion.axis.y) + 
                     (lastQuaternion.cosine * currentQuaternion.axis.y ) +
                      temporaryVector.y;

rotationalAxis_2.z = (currentQuaternion.cosine * lastQuaternion.axis.z) + 
                     (lastQuaternion.cosine * currentQuaternion.axis.z ) +
                      temporaryVector.z;
		
	

We need a temporary vector (glm::vec3 temporaryVector) to calculate the cross product of vector parts of current and last quaternions.

As a result, we have cosine value and vector part of q'. What we have to do is extracting the rotation angle from the cosine value and the rotation axis from the vector part.

		
angle = (acos(cosValue_2) * 180 / 3.1416) * 2;

rotationalAxis.x = rotationalAxis_2.x / sin((angle / 2) * 3.1416 / 180);
rotationalAxis.y = rotationalAxis_2.y / sin((angle / 2) * 3.1416 / 180);
rotationalAxis.z = rotationalAxis_2.z / sin((angle / 2) * 3.1416 / 180);
		
	

Remember that the vector part of the rotation quaternion is in scaled form done by sine of half the angle. To extract the rotation axis, we need to divide the vector part by sine.

Then "angle" and "rotationalAxis" is put into glm::rotate function.

Finally, we put cosine and vector part(rotationalAxis_2) of q' into lastQuaternion when mouse button is released. lastQuaternion variables must be updated after rotation because we calculate the rotation by multiplying last two rotations, $$q' = q_{current}q_{last}$$.

		
if(action == GLFW_RELEASE){
    arcCamera.replace();
    flag = false;

        }

void ArcballCamera::replace(){
    lastQuaternion.cosine = cosValue_2;
    lastQuaternion.axis = rotationalAxis_2;
}
		
	

Full source code is here.