Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feature: documentation update #223

Merged
merged 7 commits into from
Sep 29, 2021
+306 −15
Merged

feature: documentation update #223

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1b03026
feature: documentation update
klich3 Sep 27, 2021
9b2e374
feature: documentation
klich3 Sep 27, 2021
34dbdad
feature: docs corrections
klich3 Sep 27, 2021
c96747d
feature: edited
klich3 Sep 27, 2021
2b856bc
feature: orthographic corrections
klich3 Sep 27, 2021
f27ec46
bugfix: omitting sample
klich3 Sep 28, 2021
b6dd8c8
feature: corrections & added new list of samples / tips on readme doc.
klich3 Sep 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 70 additions & 7 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ See [the demo](https://github.com/yomotsu/camera-movement-comparison#dolly-vs-zo
| `.polarAngle` | `number` | N/A | current polarAngle in radians. |
| `.minPolarAngle` | `number` | `0` | In radians. |
| `.maxPolarAngle` | `number` | `Math.PI` | In radians. |
| `.azimuthAngle` | `number` | N/A | current azimuthAngle in radians. |
| `.azimuthAngle` | `number` | N/A | current azimuthAngle in radians ³. |
| `.minAzimuthAngle` | `number` | `-Infinity` | In radians. |
| `.maxAzimuthAngle` | `number` | `Infinity` | In radians. |
| `.boundaryFriction` | `number` | `0.0` | Friction ratio of the boundary. |
Expand All @@ -170,9 +170,14 @@ See [the demo](https://github.com/yomotsu/camera-movement-comparison#dolly-vs-zo
| `.colliderMeshes` | `array` | `[]` | An array of Meshes to collide with camera ¹. |
| `.infinityDolly` | `boolean` | `false` | `true` to enable Infinity Dolly ². |
| `.restThreshold` | `number` | `0.0025` | Controls how soon the `rest` event fires as the camera slows |
| `.minZoom` | `number` | `int` | Limit for camera zoom pos/neg |
| `.maxZoom` | `number` | `int` | Limit for camera zoom pos/neg |

1. Be aware colliderMeshes may decrease performance. Collision test uses 4 raycasters from camera, since near plane has 4 corners.
2. When the Dolly distance less than the minDistance, the sphere of radius will set minDistance.
3. Every 360 degrees turn are added to `.azimuthAngle` value, is acaccumulative.
`360º = 360 * THREE.MathUtils.DEG2RAD = 6.283185307179586`, `720º = 12.566370614359172`.<br/>
**Tip**: [How to normalize azimuthAngle?](#tips)

## Events

Expand Down Expand Up @@ -201,8 +206,12 @@ Working example: [user input config](https://yomotsu.github.io/camera-controls/e
| --------------------- | -------- |
| `mouseButtons.left` | `CameraControls.ACTION.ROTATE`* \| `CameraControls.ACTION.TRUCK` \| `CameraControls.ACTION.OFFSET` \| `CameraControls.ACTION.DOLLY` \| `CameraControls.ACTION.ZOOM` \| `CameraControls.ACTION.NONE` |
| `mouseButtons.right` | `CameraControls.ACTION.ROTATE` \| `CameraControls.ACTION.TRUCK`* \| `CameraControls.ACTION.OFFSET` \| `CameraControls.ACTION.DOLLY` \| `CameraControls.ACTION.ZOOM` \| `CameraControls.ACTION.NONE` |
| `mouseButtons.wheel` | `CameraControls.ACTION.ROTATE` \| `CameraControls.ACTION.TRUCK` \| `CameraControls.ACTION.OFFSET` \| `CameraControls.ACTION.DOLLY` \| `CameraControls.ACTION.ZOOM` \| `CameraControls.ACTION.NONE` |
| `mouseButtons.shiftLeft` | `CameraControls.ACTION.ROTATE` \| `CameraControls.ACTION.TRUCK` \| `CameraControls.ACTION.OFFSET` \| `CameraControls.ACTION.DOLLY` \| `CameraControls.ACTION.ZOOM` \| `CameraControls.ACTION.NONE`* |
| `mouseButtons.wheel` ¹ | `CameraControls.ACTION.ROTATE` \| `CameraControls.ACTION.TRUCK` \| `CameraControls.ACTION.OFFSET` \| `CameraControls.ACTION.DOLLY` \| `CameraControls.ACTION.ZOOM` \| `CameraControls.ACTION.NONE` |
| `mouseButtons.middle` ² | `CameraControls.ACTION.ROTATE` \| `CameraControls.ACTION.TRUCK` \| `CameraControls.ACTION.OFFSET` \| `CameraControls.ACTION.DOLLY`* \| `CameraControls.ACTION.ZOOM` \| `CameraControls.ACTION.NONE` |

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

- \* is the default.
- The default of `mouseButtons.wheel` is:
Expand All @@ -225,18 +234,26 @@ Working example: [user input config](https://yomotsu.github.io/camera-controls/e
#### `rotate( azimuthAngle, polarAngle, enableTransition )`

Rotate azimuthal angle(horizontal) and polar angle(vertical).
Every value is adding to current.

| Name | Type | Description |
| ------------------ | --------- | ----------- |
| `azimuthAngle` | `number` | Azimuth rotate angle. In radian. |
| `polarAngle` | `number` | Polar rotate angle. In radian. |
| `enableTransition` | `boolean` | Whether to move smoothly or immediately |

When you need rotate only one axie put value to move, and zero value for doing nothing.
``` js
rotate(20 * THREE.MathUtils.DEG2RAD, 0, true)
```

---

#### `rotateAzimuthTo( azimuthAngle, enableTransition )`

Rotate azimuthal angle(horizontal) and keep the same polar angle(vertical) target.
Rotate azimuthal angle(horizontal) and keep the same polar angle(vertical) target.
Same as `rotate()` affect only one axie.
Every value is adding to current.

| Name | Type | Description |
| ------------------ | --------- | ----------- |
Expand All @@ -248,6 +265,8 @@ Rotate azimuthal angle(horizontal) and keep the same polar angle(vertical) targe
#### `rotatePolarTo( polarAngle, enableTransition )`

Rotate polar angle(vertical) and keep the same azimuthal angle(horizontal) target.
Same as `rotate()` affect only one axie.
Every value is adding to current.

| Name | Type | Description |
| ------------------ | --------- | ----------- |
Expand All @@ -259,6 +278,30 @@ Rotate polar angle(vertical) and keep the same azimuthal angle(horizontal) targe
#### `rotateTo( azimuthAngle, polarAngle, enableTransition )`

Rotate azimuthal angle(horizontal) and polar angle(vertical) to a given point.
Rotate absolutly camera view over camera pivot:

azimuth
<pre>
0
|
90 -- -- -90
|
180
</pre>
0 front, 90 left, -90 right, 180 back

-----

polar
<pre>
180
|
90
|
0
</pre>

180 top/sky, 90 horizontal from view, 0 bottom/floor

| Name | Type | Description |
| ------------------ | --------- | ----------- |
Expand Down Expand Up @@ -292,7 +335,10 @@ Dolly in/out camera position to given distance.

#### `zoom( zoomStep, enableTransition )`

Zoom in/out of camera.
Zoom in/out is added or reduced to camera given scale.
Current value +/- input `zoomStep`

Limits set with `.minZoom` and `.maxZoom`

| Name | Type | Description |
| ------------------ | --------- | ----------- |
Expand All @@ -301,7 +347,7 @@ Zoom in/out of camera.

You can also make zoomIn function using `camera.zoom` property.
e.g.
```js
``` js
const zoomIn = () => cameraControls.zoom( camera.zoom / 2, true );
const zoomOut = () => cameraControls.zoom( - camera.zoom / 2, true );
```
Expand All @@ -310,13 +356,16 @@ const zoomOut = () => cameraControls.zoom( - camera.zoom / 2, true );

#### `zoomTo( zoom, enableTransition )`

Zoom in/out camera to given scale.
Rewrite current Zoom value to input value `zoom`.

Limits set with `.minZoom` and `.maxZoom`

| Name | Type | Description |
| ------------------ | --------- | ----------- |
| `zoom` | `number` | zoom scale |
| `enableTransition` | `boolean` | Whether to move smoothly or immediately |


---

#### `truck( x, y, enableTransition )`
Expand Down Expand Up @@ -442,7 +491,7 @@ Similar to `setLookAt`, but it interpolates between two states.
| `targetBX` | `number` | look at position x to interpolate towards. |
| `targetBY` | `number` | look at position y to interpolate towards. |
| `targetBZ` | `number` | look at position z to interpolate towards. |
| `t` | `number` | Interpolation factor in the closed interval [0, 1]. |
| `t` | `number` | Interpolation factor in the closed interval [0, 1 = 100%]. |
| `enableTransition` | `boolean` | Whether to move smoothly or immediately |

---
Expand Down Expand Up @@ -637,6 +686,20 @@ If `enableTransition` is `false`, the promise will resolve immediately:
await cameraControls.dollyTo( 3, false );
```

---

## Tips

* **Normalize azimuth angle**:
If you need a normalized accumulated azimuth angle (between 0 and 360 deg), compute with [THREE.MathUtils.euclideanModulo](https://threejs.org/docs/#api/en/math/MathUtils)
e.g.:
``` js
const normalizedAzimuthAngle = THREE.MathUtils.euclideanModulo( cameraControls.azimuthAngle, 360 * THREE.MathUtils.DEG2RAD );
```


---

## Breaking changes

@1.16.0 `dolly()` will take opposite value. e.g. dolly-in to `dolly( 1 )` (used be dolly-in to `dolly( -1 )`)
Expand Down
Loading