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

Changes from 2 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
59 changes: 53 additions & 6 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,18 @@ 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 are added to the value. `360º = 360 * THREE.MathUtils.DEG2RAD = 6.283185307179586`, `720 = 12.566370614359172`. To restart use this function normalizeRotations() or this code
```js
const azi = 0;
cameraController.addEventListener("control", (_event) => {
azi = _event.target.azimuthAngle % (360 * THREE.MathUtils.DEG2RAD);
}, false);
```
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this code example for?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when you rotate to the side .azimuthAngle is summing
0 -> 360º -> 720º -> 1080º + 45º = 1125º
now if you use rotateTo() camera spinning back all 4x right? okey if you use this code
.azimuthAngle = .azimuthAngle % (360 * THREE.MathUtils.DEG2RAD) you are reset 4x turns to 0 + 45º
now if you execute rotateTo() camera rotate only -45º to 0

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's right.
However, I think, the code example doesn't solve the situation, because azi is just a variable (also it should not be a const?).
Maybe the example could be omitted at this time?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm yes you right, ok no problem I change it, omitting this sample

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe can add new parameter with this function .azimuthAbsoluteAngle what you thing about it?

Copy link
Owner

@yomotsu yomotsu Sep 29, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for understanding.

maybe can add new parameter

Thanks for your suggestion.
I think It can be done easily with THREE.MathUtils.euclideanModulo.
Maybe it should be in user-land rather than a part of camera-controls?

e.g.

THREE.MathUtils.euclideanModulo( -2890, 360 ); // 350

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think people do not know the existence of many of the functions, which integrates in Three for that reason to be confused when using the plugin. Or they just do not understand the hierarchy of elements. You should put plugin for user Mid / Pro Level XD

Copy link
Owner

@yomotsu yomotsu Sep 29, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for considering the users😊

Although we already have cameraControls.normalizeRotations() method to fix, We could add an explanation of how to normalize the accumulated angle on the user's side with THREE.MathUtils.euclideanModulo.
Maybe like the below:

If you need a normalized accumulated azimuth angle (between 0 and 360 deg), compute with THREE.MathUtils.euclideanModulo.
e.g.

const normalizedAzimuthAngle = THREE.MathUtils.euclideanModulo( cameraControls.azimuthAngle, 360 * THREE.MathUtils.DEG2RAD );

However, regarding adding the helper on the library side, That must be done with another github issue or PR.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are welcome :)


## Events

Expand Down Expand Up @@ -201,8 +210,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 +238,25 @@ 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 +268,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 +281,25 @@ 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
0
|
90 -- -- -90
|
180

0 front, 90 left, -90 right, 180 back

polar
180
|
90
|
0

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

| Name | Type | Description |
| ------------------ | --------- | ----------- |
Expand Down Expand Up @@ -292,7 +333,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 @@ -310,13 +354,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 +489,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