How to Use Three.js CameraHelper to Debug Frustum

In Three.js, visualizing the viewing frustum of a perspective camera is essential for debugging clipping issues, positioning cameras accurately, and optimizing culling. This article provides a quick guide on how to implement the CameraHelper class to render a wireframe representation of your camera’s field of view, near/far planes, and aspect ratio directly within your 3D scene.

Setting Up the CameraHelper

To visualize a camera’s frustum, you must pass the target camera instance into the CameraHelper constructor and then add that helper to your scene.

Here is a basic implementation:

import * as THREE from 'three';

// 1. Create the main scene and renderer
const scene = new THREE.Scene();
const renderer = new THREE.WebGLRenderer();

// 2. Create the Perspective Camera you want to debug
const debugCamera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 1, 100);
debugCamera.position.set(0, 5, 10);

// 3. Create the CameraHelper for the debug camera
const cameraHelper = new THREE.CameraHelper(debugCamera);

// 4. Add the helper to the scene
scene.add(cameraHelper);

Viewing the Helper

To actually see the frustum helper, you must view the scene through a different camera (often called an active or rendering camera). If you render the scene using the camera being debugged, the helper lines will lie exactly on the edges of the viewport and will be invisible.

// Create an active camera to view the scene and the helper
const activeCamera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
activeCamera.position.set(20, 20, 20);
activeCamera.lookAt(0, 0, 0);

// In your render loop, render using the active camera
function animate() {
    requestAnimationFrame(animate);
    renderer.render(scene, activeCamera);
}
animate();

Updating the Helper

If you modify any of the target camera’s properties—such as fov, aspect, near, far, or if you manually update its projection matrix—you must call the .update() method on the helper to keep the visualization synchronized.

// Example: Modifying the camera's field of view dynamically
debugCamera.fov = 60;
debugCamera.updateProjectionMatrix();

// Update the helper to reflect the new FOV
cameraHelper.update();

Controlling Visibility

You can easily toggle the visibility of the helper in your debugging UI (like lil-gui or dat.GUI) by changing its visible property:

// Hide the frustum helper
cameraHelper.visible = false;

// Show the frustum helper
cameraHelper.visible = true;