Real-time earthquake trackers and 3D scientific visualizations cannot remain tethered to large desktop monitors if they are to function as genuine disaster prevention utilities. When tremors suddenly shake a room, people instinctively grab their smartphones from their pockets to understand what just happened and where the danger lies.
However, navigating a 3D digital globe on mobile web browsers has historically plagued users with frustration: fingers slipping across textures without direct traction, sudden camera inversion near polar latitudes, and abrupt, mechanical stopping the instant a touch ends. In QuakeViewer3D, our goal was to deliver a tactile, physical interaction model—making the digital Earth feel as responsive and tangible as spinning an authentic physical globe on your desk. Below, we examine the mathematics behind our custom arcball quaternion engine, exponential inertia modeling, and mobile-first PWA architecture.
1. Why Standard Three.js OrbitControls Degrades on Touchscreens
The ubiquitously used OrbitControls library in Three.js is fundamentally architected around desktop mouse paradigms (horizontal drag mapping to azimuthal angle $\theta$, vertical drag mapping to polar inclination angle $\phi$).
When directly mapped to touchscreens, this coordinate scheme breaks down into critical UX friction points:
- Surface Slipping (Slip Artifact): When a user places a thumb on the Japanese archipelago and drags right, spherical polar projection causes linear touch displacements to diverge from surface texture velocity, creating an uncomfortable cognitive feeling that the globe is slipping under their finger.
- Polar Gimbal Singularities: When the camera approaches the zenith (North Pole) or nadir (South Pole), azimuthal coordinate axes degenerate, causing the viewport to flip violently 180 degrees and disorienting the user.
2. Arcball Quaternion Projection for Singularity-Free Spherical Rotation
To deliver uncompromising tactile responsiveness, QuakeViewer3D implements a custom Arcball (Trackball) rotation model written from first principles in vanilla JavaScript.
The screen-space 2D coordinates $(x, y)$ of a finger touch are projected onto a virtual unit hemisphere $\vec{v} = (v_x, v_y, v_z)$ floating behind the display glass. As the touch transitions between successive frames from $\vec{v_1}$ to $\vec{v_2}$, the vector cross product determines the instantaneous rotation axis, while the dot product determines the angular displacement $\Delta \theta$:
// Project 2D viewport coordinates onto virtual 3D unit sphere
function projectToSphere(x, y, width, height) {
const r = Math.min(width, height) * 0.45;
const px = (x - width / 2) / r;
const py = (height / 2 - y) / r;
const d2 = px * px + py * py;
if (d2 <= 1.0) {
return new THREE.Vector3(px, py, Math.sqrt(1.0 - d2)).normalize();
} else {
// Hyperbolic falloff outside globe boundaries
return new THREE.Vector3(px, py, 1.0 / (2.0 * Math.sqrt(d2))).normalize();
}
}
// Synthesize orientation delta via quaternions on touch move
function onTouchMove(currPos, prevPos) {
const v1 = projectToSphere(prevPos.x, prevPos.y, viewWidth, viewHeight);
const v2 = projectToSphere(currPos.x, currPos.y, viewWidth, viewHeight);
const axis = new THREE.Vector3().crossVectors(v1, v2).normalize();
const angle = Math.acos(Math.min(1.0, v1.dot(v2))) * ROTATION_SENSITIVITY;
const deltaQuat = new THREE.Quaternion().setFromAxisAngle(axis, angle);
globeGroup.quaternion.premultiply(deltaQuat);
}Because all rotational states are accumulated directly as four-dimensional quaternions, singularities and gimbal lock are mathematically impossible. The globe follows the user's thumb with 1:1 kinematic fidelity across any angle or orientation.
3. Physics-Based Inertial Damping & Friction Modeling
True tactile immersion requires simulating the physical conservation of angular momentum. An abrupt halt the moment a finger lifts breaks immersion.
QuakeViewer3D records an exponential moving average of angular velocity vectors across the final three touch frames preceding a touchend event. Upon release, an inertial simulation loop engages, decelerating rotation via an exponential viscous drag model ($\gamma \approx 0.94$ per tick):
// Inertial simulation step inside requestAnimationFrame loop
function updateInertia(deltaTime) {
if (!isUserTouching && angularVelocity.lengthSq() > 0.000001) {
const angle = angularVelocity.length() * deltaTime;
const axis = angularVelocity.clone().normalize();
const deltaQuat = new THREE.Quaternion().setFromAxisAngle(axis, angle);
globeGroup.quaternion.premultiply(deltaQuat);
// Apply exponential viscous decay
angularVelocity.multiplyScalar(Math.pow(0.92, deltaTime * 60));
}
}This dynamic gives users the freedom to flick the Earth with enthusiasm to travel to the opposite hemisphere in an instant, or apply gentle nudges to examine fault lines with fine micro-precision.
4. Thumb-Zone Glassmorphism UI & PWA Offline Resilience
Screen real estate on mobile devices is strictly constrained. Bulky static sidebars or top headers obscure valuable map visibility.
- Thumb-Zone Glassmorphism Dock: Core analytical controls (magnitude threshold sliders, depth filters, plate boundary toggles) reside within a bottom collapsible sheet styled with translucent glassmorphism (
backdrop-filter: blur(16px)), easily reachable by one-handed thumb interaction. - PWA Native App Parity: Equipped with a Web App Manifest and Service Worker registration, users can tap "Add to Home Screen" on iOS Safari or Android Chrome to launch QuakeViewer3D in standalone fullscreen mode without browser URL bars.
- Offline Fault & Boundary Caching: Tectonic plate boundary GeoJSONs, seismic city centroids, and base bathymetry textures are pre-cached via Cache API, guaranteeing immediate visual operation even if local cellular towers suffer post-disaster outages.
5. Conclusion: Redefining Mobile Web 3D Interaction
Operating inside a browser environment does not require conceding ground to native iOS and Android apps in terms of fluidity and polish.
By uniting mathematical arcball quaternions, authentic inertial damping, and one-handed PWA ergonomics, QuakeViewer3D delivers an agile, dependable disaster visualization interface ready for the moment it is needed most.