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

<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:

Prop	Description	Default
makeDefault	Whether to make this the default controls.	false
camera	The camera to control.	undefined
domElement	The DOM element to listen to.	undefined
minPolarAngle	Minimum vertical angle in radians.	0
maxPolarAngle	Maximum vertical angle in radians.	Math.PI
minAzimuthAngle	Minimum horizontal angle in radians.	-Infinity
maxAzimuthAngle	Maximum horizontal angle in radians.	Infinity
distance	Current distance.	camera.position.z
minDistance	Minimum distance for dolly. PerspectiveCamera only.	Number.EPSILON
maxDistance	Maximum distance for dolly. PerspectiveCamera only.	Infinity
infinityDolly	true to enable Infinity Dolly for wheel and pinch.	false
minZoom	Minimum camera zoom.	0.01
maxZoom	Maximum camera zoom.	Infinity
smoothTime	Approximate time in seconds to reach the target. A smaller value will reach the target faster.	0.25
draggingSmoothTime	The smoothTime while dragging.	0.125
maxSpeed	Max transition speed in units per second.	Infinity
azimuthRotateSpeed	Speed of azimuth (horizontal) rotation.	1.0
polarRotateSpeed	Speed of polar (vertical) rotation.	1.0
dollySpeed	Speed of mouse-wheel dollying.	1.0
dollyDragInverted	true to invert direction when dollying or zooming via drag.	false
truckSpeed	Speed of drag for truck and pedestal.	2.0
dollyToCursor	true to enable Dolly-in to the mouse cursor coords.	false
dragToOffset	Whether to drag to offset.	false
verticalDragToForward	The same as .screenSpacePanning in three.js's OrbitControls.	false
boundaryFriction	Friction ratio of the boundary.	0.0
restThreshold	Controls how soon the rest event fires as the camera slows.	0.01
colliderMeshes	An 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.	[]
mouseButtons	Configuration of actions on mouse input.	See User input config for details
touches	Configuration 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.

<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 assign	Options	Default
mouseButtons.left	ROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONE	ROTATE
mouseButtons.right	ROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONE	TRUCK
mouseButtons.wheel ¹	ROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONE	DOLLY for Perspective camera, ZOOM for Orthographic camera.
mouseButtons.middle ²	ROTATE | TRUCK | OFFSET | DOLLY | ZOOM | NONE	DOLLY

1. Mouse wheel event for scroll "up/down", on mac "up/down/left/right".
2. Mouse wheel "button" click event.

Touches

Fingers to assign	Options	Default
touches.one	TOUCH_ROTATE | TOUCH_TRUCK | TOUCH_OFFSET | DOLLY | ZOOM | NONE	TOUCH_ROTATE
touches.two	TOUCH_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 | NONE	TOUCH_DOLLY_TRUCK for Perspective camera, TOUCH_ZOOM_TRUCK for Othographic camera.
touches.three	TOUCH_DOLLY_TRUCK | TOUCH_DOLLY_OFFSET | TOUCH_DOLLY_ROTATE | TOUCH_ZOOM_TRUCK | TOUCH_ZOOM_OFFSET | TOUCH_ZOOM_ROTATE | TOUCH_ROTATE | TOUCH_TRUCK | TOUCH_OFFSET | NONE	TOUCH_TRUCK

Events

<CameraControls @change="onChange" @start="onStart" @end="onEnd" />

Event	Description
start	Dispatched when the control starts to change.
change	Dispatched when the control changes.
end	Dispatched when the control ends to change.