Add direction parameters to fitTo method

[juliendargelos]

This feature allows to specify which side of the bounding box to fit when using fitTo.
The corresponding example has also been updated so the grid always shows the right unit size regarding the camera position.

Usage

controls.fitTo(mesh, true, {
  side: 'back'
})

These are the available side values:

export enum SIDE {
  UP    = 'up',
  DOWN  = 'down',
  RIGHT = 'right',
  LEFT  = 'left',
  FRONT = 'front',
  BACK  = 'back'
}

The default value is 'front' so the feature isn't a breaking change. I haven't written the doc yet, let me know if you would merge this and I'll do it.

[yomotsu]

Thanks for your contribution.
How about just using the camera direction rather than the side option?

Here is my idea

1. get the closest corner of the bounding box
2. make a plane with the closest corner and camera direction
3. project all corners to the plane
4. make a rectangle that contains all corners on the plane
5. get the distance to contain the rect
6. move the camera to the distance

[juliendargelos]

The current direction ?

[yomotsu]

yesyes

[juliendargelos]

but the point is to choose a side to look at, whatever the current camera state is

[juliendargelos]

Thanks for your contribution.
How about just using the camera direction rather than the side option?

Here is my idea

1. get the closest corner of the bounding box
2. make a plane with the closest corner and camera direction
3. project all corners to the plane
4. make a rectangle that contains all corners on the plane
5. get the distance to contain the rect
6. move the camera to the distance

Yes this would be more flexible since it allows any point of view. But it still requires extra parameters for direction.

[yomotsu]

I guess choosing a side can be done in userland if the library provides free direction fit

[juliendargelos]

Yes, I'll work on that

[yomotsu]

oh btw, don't add generated files (such as .js) for pull requests please. this causes too many changes

[juliendargelos]

The last changes introduce two new polarAngle and azimuthAngle parameters.

controls.fitTo(mesh, true, {
  polarAngle: Math.PI / 2,
  azimuthAngle: Math.PI
})

If you specify a side, polarAngle and azimuthAngle will have the side angles as default value.

controls.fitTo(mesh, true, {
  side: 'up'
})

This behaviour depends on parameters destructuring and default values:

fitTo( box3OrObject: _THREE.Box3 | _THREE.Object3D, enableTransition: boolean, {
  side = SIDE.FRONT,
  azimuthAngle = SIDES[ side ].azimuthAngle,
  polarAngle = SIDES[ side ].polarAngle,
  paddingLeft = 0,
  paddingRight = 0,
  paddingBottom = 0,
  paddingTop = 0
}: Partial<FitToOptions> = {} ): void

And the available side angles are defined in a constant:

export const SIDES: { [side in SIDE]: Direction } = {
  [ SIDE.FRONT ]: { polarAngle:   PI_HALF, azimuthAngle:         0 },
  [ SIDE.BACK  ]: { polarAngle:   PI_HALF, azimuthAngle:   Math.PI },
  [ SIDE.UP    ]: { polarAngle: - PI_HALF, azimuthAngle:         0 },
  [ SIDE.DOWN  ]: { polarAngle:   Math.PI, azimuthAngle:         0 },
  [ SIDE.RIGHT ]: { polarAngle:   PI_HALF, azimuthAngle:   PI_HALF },
  [ SIDE.LEFT  ]: { polarAngle:   PI_HALF, azimuthAngle: - PI_HALF }
};

As you proposed, each corner of the bounding box is projected on a plane, then the camera distance is computed from the bounding rect containing all projected points.

[yomotsu]

Thanks i will take a look

[dguay]

Thank you for this PR I'd need this to fit the object from a top-down view. Any chance this gets merged/released soon?

[yomotsu]

sorry for the delay.
I will merge this for now but let me change a little bit.

Thanks for the PR!

[dguay]

@yomotsu Any idea when the next release will be so I can update to be able to use this feature? Thank you !

[yomotsu]

I'll work on that this weekend. maybe early next week!

[dguay]

@yomotsu You have done some releases since but this is still not release. Any chance we can get a release for this soon?

[yomotsu]

This feature is already available.
see https://yomotsu.github.io/camera-controls/examples/fit-and-padding.html

[dguay]

I updated to 1.21.0 and I can't use the new side option. Also I don't see the new code in this repo (master or dev branches)

[yomotsu]

Please see
https://yomotsu.github.io/camera-controls/examples/fit-and-padding.html
and
https://github.com/yomotsu/camera-controls#fitto-box3ormesh-enabletransition--paddingtop-paddingleft-paddingbottom-paddingright--

fitTo uses the current angle.

[dguay]

@yomotsu This is working well when you want a perpendicular view on the object but this is not working if I want to do an isometric view for example. rotateTo then fitTo --> works for perpendicular views. If you want isometric style view you need to do fitTo then rotateTo but this doesn't work well for perpendicular views. Am I missing something?