Smooth, momentum-based camera controls for That Open Components viewers.
- ❌ Dolly slowdown - Default camera controls become sluggish when zooming close to objects
- ❌ Wrong orbit center - Rotating around arbitrary points instead of what you're looking at
- 🎯 Smooth Wheel Zooming - Momentum-based scrolling with velocity accumulation
- 🔄 Smart Orbit Point - Automatically sets orbit center based on raycast
- 📱 Touch Support - Full mobile device support out of the box
- ⌨️ Keyboard Modifiers - Shift for speed boost, Ctrl/Alt for precision
- ⚙️ Highly Configurable - Tune all parameters to your needs
- 🎨 Auto Scene Calibration - Fixes dolly slowdown by adjusting zoom speed based on model size
Copy smoothWheelControl.ts and mouseOrbitControl.ts into your project.
Dependencies:
npm install @thatopen/components @thatopen/components-front threeFor React/TypeScript projects:
npm install -D @types/reactimport * as OBC from '@thatopen/components'
import { createSmoothWheelControl, calibrateDollyStepByScene } from './smoothWheelControl'
import { createMouseOrbitControl } from './mouseOrbitControl'
// Setup your That Open Components world
const world = /* your OBC.World */
const components = /* your OBC.Components */
const containerRef = /* React.RefObject or HTMLDivElement */
// Create controls
const smoothWheel = createSmoothWheelControl(world, components, containerRef)
const mouseOrbit = createMouseOrbitControl(world, components, containerRef)
// Add event listeners
containerRef.current.addEventListener('wheel', smoothWheel.wheelHandler, { passive: false })
containerRef.current.addEventListener('mousedown', mouseOrbit.mouseDownHandler, true)
containerRef.current.addEventListener('mousemove', mouseOrbit.mouseMoveHandler, true)
containerRef.current.addEventListener('touchstart', mouseOrbit.touchStartHandler, true)
// Calibrate zoom speed after loading model (optional)
calibrateDollyStepByScene(world)
// Cleanup on unmount
smoothWheel.cleanup()See TUTORIAL.md for detailed documentation, including:
- Step-by-step setup guide
- Parameter customization
- Complete React component example
- Performance optimization tips
- Advanced usage patterns
createSmoothWheelControl(world, components, containerRef, {
velocityDecay: 0.9, // Velocity reduction per scroll (0.9 = -10%)
velocityTimeout: 150, // Reset velocity after pause (ms)
velocityDivisor: 200, // Acceleration sensitivity
maxVelocityMultiplier: 5, // Max zoom speed (5x base speed)
smoothing: 0.15, // Animation responsiveness (0-1)
stepAccumulation: 0.3, // Motion blending between scrolls
shiftBoost: 3, // Shift key multiplier
fineModifier: 0.1, // Ctrl/Alt precision multiplier
fragmentUpdateDelay: 300 // Fragment update delay (ms)
})| Action | Effect |
|---|---|
| Mouse wheel | Smooth momentum zoom |
| Shift + Wheel | 3x faster zoom |
| Ctrl/Alt + Wheel | 10x slower (precision) |
| Click + Drag | Rotate around clicked point |
| Touch + Drag | Rotate around touched point |
- Momentum-based wheel zooming with velocity accumulation
- Configurable decay, smoothing, and acceleration
- Fragment update optimization
- Scene-based zoom calibration
- Raycast-based orbit point selection
- Drag detection with threshold
- Touch device support
- Manual orbit point utility function
- IFC/BIM model viewers
- Architectural visualization
- 3D product configurators
- CAD model viewers
- Any That Open Components application
This is a standalone utility package. Feel free to:
- Fork and modify for your needs
- Submit issues and suggestions
- Share improvements
MIT License - use freely in your projects!
Built for use with That Open Components by That Open Company.
Made with ❤️ for the That Open community