Skip to content

OrbitControls

OrbitControls is a camera controller that allows you to orbit around a target. It's a great way to explore your scene.

However, it is not part of the core of ThreeJS. So to use it you would need to import it from the three/examples/jsm/controls/OrbitControls module.

Here is where the fancy part begins. ✨ The cientos package provides a component called <OrbitControls /> that is a wrapper of the OrbitControls from the three-stdlib module.

The nicest part? You don't need to extend the catalog or pass any arguments. It just works. 💯

Usage

vue
<script setup lang="ts">
import { Box, OrbitControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[3, 3, 3]" />
    <OrbitControls />
    <Box :scale="2">
      <TresMeshToonMaterial color="orange" />
    </Box>
    <TresAmbientLight />
    <TresDirectionalLight
      :position="[0, 2, 4]"
    />
    <TresGridHelper />
  </TresCanvas>
</template>

WARNING

Is really important that the Perspective camera is set first in the canvas. Otherwise might break.

Props

PropDescriptionDefault
makeDefaultIf true, the controls will be set as the default controls for the scene.false
cameraThe camera to control.undefined
domElementThe dom element to listen to.undefined
targetThe target to orbit around.undefined
enableDampingIf true, the controls will use damping (inertia), which can be used to give a sense of weight to the controls.true
dampingFactorThe damping inertia used if .enableDamping is set to true.0.05
autoRotateSet to true to automatically rotate around the target.false
autoRotateSpeedHow fast to rotate around the target if .autoRotate is true.2
enablePanWhether to enable panning.true
keyPanSpeedHow fast to pan the camera when the keyboard is used. Default is 7.0 pixels per keypress.7.0
keysThis object contains references to the keycodes for controlling camera panning. Default is the 4 arrow keys.{ LEFT: 'ArrowLeft', UP: 'ArrowUp', RIGHT: 'ArrowRight', BOTTOM: 'ArrowDown' }
maxAzimuthAngleHow far you can orbit horizontally, upper limit. If set, the interval [ min, max ] must be a sub-interval of [ - 2 PI, 2 PI ], with ( max - min < 2 PI ). Default is Infinity.Infinity
minAzimuthAngleHow far you can orbit horizontally, lower limit. If set, the interval [ min, max ] must be a sub-interval of [ - 2 PI, 2 PI ], with ( max - min < 2 PI ). Default is - Infinity.-Infinity
maxPolarAngleHow far you can orbit vertically, upper limit. Range is 0 to Math.PI radians, and default is Math.PI.Math.PI
minPolarAngleHow far you can orbit vertically, lower limit. Range is 0 to Math.PI radians, and default is 0.0
minDistanceThe minimum distance of the camera to the target. Default is 0.0
maxDistanceThe maximum distance of the camera to the target. Default is Infinity.Infinity
minZoomThe minimum field of view angle, in radians. Default is 0.0
maxZoomThe maximum field of view angle, in radians. ( OrthographicCamera only ). Default is Infinity.Infinity
touchesThis object contains references to the touch actions used by the controls.{ ONE: TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN }
--
enableZoomWhether to enable zooming.true
zoomSpeedHow fast to zoom in and out. Default is 1.1
enableRotateWhether to enable rotating.true
rotateSpeedHow fast to rotate around the target. Default is 1.1

Events

vue
<OrbitControls @change="onChange" @start="onStart" @end="onEnd" />
EventDescription
startDispatched when the control starts to change.
changeDispatched when the control changes.
endDispatched when the control ends to change.