Three.js TransformControls for 3D Editors

This article explains the purpose and utility of TransformControls in Three.js when developing interactive, in-browser 3D editors. You will learn how this essential class enables users to manipulate 3D objects directly in the viewport through intuitive visual gizmos for translation, rotation, and scaling.

In Three.js, building a 3D editor requires a way for users to interact with objects in the 3D space. While controls like OrbitControls allow users to navigate the camera around the scene, TransformControls is specifically designed to manipulate the 3D objects themselves. It acts as the bridge between user input (mouse clicks and drags) and the underlying mathematical transformations of 3D meshes.

Core Functionalities

TransformControls provides three primary modes of manipulation, which are standard in almost all professional 3D modeling software: * Translate (Position): Displays directional arrows along the X, Y, and Z axes. Dragging these arrows moves the object along the corresponding axis. * Rotate: Displays circular rings around the object. Dragging these rings rotates the object around the selected axis. * Scale: Displays boxes at the ends of the axes. Dragging these boxes resizes the object either uniformly or along a specific axis.

The Role of Visual Gizmos

Without a visual aid, users would have to input numerical coordinates into a sidebar UI to move objects. TransformControls solves this by rendering 3D gizmos (the colorful red, green, and blue handle graphics) directly on top of the active object. The colors represent the standard 3D coordinate system (Red for X, Green for Y, and Blue for Z), making the interface instantly recognizable and user-friendly.

Preventing Conflict with Camera Controls

In a typical 3D editor, both camera navigation and object manipulation rely on mouse drag events. If a user tries to drag a transform gizmo, the camera might orbit at the same time, causing a chaotic user experience. TransformControls provides built-in event listeners to resolve this. Developers can temporarily disable camera controls (like OrbitControls) the moment a user starts dragging a transform handle, and re-enable them once the drag event ends.

Advanced Editor Features

Beyond basic movement, TransformControls supports several advanced features necessary for a production-ready 3D editor: * Coordinate Spaces: Users can toggle between “world” space (aligning gizmos with the global grid) and “local” space (aligning gizmos with the object’s own rotated axes). * Snapping: It supports grid and angle snapping, allowing users to move or rotate objects by precise increments (e.g., snapping every 1 unit or every 15 degrees). * Keyboard Shortcuts: It can easily be bound to keyboard listeners so users can quickly switch modes (e.g., pressing “W” for translate, “E” for rotate, and “R” for scale).