Skip to content

CameraControls ^3.2.0 โ€‹

CameraControls is a camera controller similar to OrbitControls yet supports smooth transitions and more features.

However, it is thirty party library for ThreeJS. So to use it you would need to install and import using npm.

Here is where the fancy part begins. โœจ The cientos package provides a component called <CameraControls /> that is a wrapper of the CameraControls from the camera-controls 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, CameraControls } from '@tresjs/cientos'
import { TresCanvas } from '@tresjs/core'
import { reactive } from 'vue'

const controlsState = reactive({
  minDistance: 0,
  maxDistance: 100,
})
</script>

<template>
  <TresCanvas clear-color="#82DBC5">
    <TresPerspectiveCamera :position="[5, 5, 5]" />
    <CameraControls
      v-bind="controlsState"
      make-default
    />
    <TresGridHelper :position="[0, -1, 0]" />
    <Box :scale="2">
      <TresMeshToonMaterial color="orange" />
    </Box>
    <TresAmbientLight />
    <TresDirectionalLight :position="[0, 2, 4]" />
  </TresCanvas>
</template>

WARNING

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

Props โ€‹

Certainly! Here's the properties of the object in raw markdown table format:

PropDescriptionDefault
makeDefaultWhether to make this the default controls.false
cameraThe camera to control.undefined
domElementThe DOM element to listen to.undefined
minPolarAngleMinimum vertical angle in radians.0
maxPolarAngleMaximum vertical angle in radians.Math.PI
minAzimuthAngleMinimum horizontal angle in radians.-Infinity
maxAzimuthAngleMaximum horizontal angle in radians.Infinity
distanceCurrent distance.camera.position.z
minDistanceMinimum distance for dolly. PerspectiveCamera only.Number.EPSILON
maxDistanceMaximum distance for dolly. PerspectiveCamera only.Infinity
infinityDollytrue to enable Infinity Dolly for wheel and pinch.false
minZoomMinimum camera zoom.0.01
maxZoomMaximum camera zoom.Infinity
smoothTimeApproximate time in seconds to reach the target. A smaller value will reach the target faster.0.25
draggingSmoothTimeThe smoothTime while dragging.0.125
maxSpeedMax transition speed in units per second.Infinity
azimuthRotateSpeedSpeed of azimuth (horizontal) rotation.1.0
polarRotateSpeedSpeed of polar (vertical) rotation.1.0
dollySpeedSpeed of mouse-wheel dollying.1.0
dollyDragInvertedtrue to invert direction when dollying or zooming via drag.false
truckSpeedSpeed of drag for truck and pedestal.2.0
dollyToCursortrue to enable Dolly-in to the mouse cursor coords.false
dragToOffsetWhether to drag to offset.false
verticalDragToForwardThe same as .screenSpacePanning in three.js's OrbitControls.false
boundaryFrictionFriction ratio of the boundary.0.0
restThresholdControls how soon the rest event fires as the camera slows.0.01
colliderMeshesAn array of Meshes to collide with the camera. Be aware colliderMeshes may decrease performance. The collision test uses 4 raycasters from the camera since the near plane has 4 corners.[]
mouseButtonsConfiguration of actions on mouse input.See User input config for details
touchesConfiguration of actions on touch.See User input config for details

User input config โ€‹

You can easily override the default user input config by defining mouseButtons and/or touches props that correspond to camera-controls settings. For ease of use, we're re-exporting the CameraControls class as BaseCameraControls which gives you access to the ACTION enum.

vue
<script lang="ts" setup>
import { BaseCameraControls, CameraControls } from '@tresjs/cientos'
</script>

<template>
  ...
  <CameraControls
    :mouse-buttons="{ left: BaseCameraControls.ACTION.DOLLY }"
    :touches="{ one: BaseCameraControls.ACTION.TOUCH_TRUCK }"
  />
  ...
</template>

Mouse buttons โ€‹

Button to assignOptionsDefault
mouseButtons.leftROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONEROTATE
mouseButtons.rightROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONETRUCK
mouseButtons.wheel ยนROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONEDOLLY for Perspective camera, ZOOM for Orthographic camera.
mouseButtons.middle ยฒROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONEDOLLY
  1. Mouse wheel event for scroll "up/down", on mac "up/down/left/right".
  2. Mouse wheel "button" click event.

Touches โ€‹

Fingers to assignOptionsDefault
touches.oneTOUCH_ROTATE | TOUCH_TRUCK | TOUCH_OFFSET | DOLLY | ZOOM | NONETOUCH_ROTATE
touches.twoTOUCH_DOLLY_TRUCK | TOUCH_DOLLY_OFFSET | TOUCH_DOLLY_ROTATE | TOUCH_ZOOM_TRUCK | TOUCH_ZOOM_OFFSET | TOUCH_ZOOM_ROTATE | TOUCH_DOLLY | TOUCH_ZOOM | TOUCH_ROTATE | TOUCH_TRUCK | TOUCH_OFFSET | NONETOUCH_DOLLY_TRUCK for Perspective camera, TOUCH_ZOOM_TRUCK for Othographic camera.
touches.threeTOUCH_DOLLY_TRUCK | TOUCH_DOLLY_OFFSET | TOUCH_DOLLY_ROTATE | TOUCH_ZOOM_TRUCK | TOUCH_ZOOM_OFFSET | TOUCH_ZOOM_ROTATE | TOUCH_ROTATE | TOUCH_TRUCK | TOUCH_OFFSET | NONETOUCH_TRUCK

Events โ€‹

vue
<CameraControls @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.