CameraControls Class
The advanced, manual camera controls for MapView. You probably don't need to use this at all, instead relying on the MapView's focusOn, resetCamera and built in touch/mouse controls. This class will let you do things like change the min/max zoom, tilt, and pan, attach to camera events, and move/animate the camera to specifc points.
The camera works by setting an anchor point on the scene at ground level and pointing the camera at it. zoom controls how far the camera is from the anchor, and tilt/rotate controls the angle the camera is rotated about it. The camera will always be pointed directly at the anchor point. pan or setPosition will move that anchor around on the 2D ground plane.
Created for you automatically with a MapView, don't re-create yourself.
Methods
-
target
-
duration
-
curve
-
callback
-
options
Animates the camera from it's current position to the state specified in target. You only need to specify the properties you actually want to change.
You can also specify a duration, animation curve, and a callback for when it's done.
Parameters:
-
target
ObjectA list of optional parameters you can set that represent the camera state.
-
[position]
Object optionalAn {x, y, z} object representing the position to move to.
-
[zoom]
Number optionalThe zoom level to end at.
-
[tilt]
Number optionalThe tilt to end at, in radians.
-
[rotation]
Number optionalThe rotation to end at, in radians.
-
[doNotAutoStart=false]
Boolean optionalSet this to true if you want to start the tween yourself.
-
-
[duration]
Number optionalThe duration to animate the camera for, in ms.
-
[curve]
Mappedin.Easing optionalThe animation curve to use for the animation.
-
[callback]
Function optionalA callback that will be executed when the animation is done.
-
[options]
Object optionalAn Options object
-
[mode=cancel]
Object optionalMode determines what happens when multiple animateCamera calls happen at once. By Default, it will cancel and omit any previous animations. Set to "chain" to chain instead
-
Returns:
The tween being used, if you want to do anything to control it manually. Do not overide it's events.
-
zoom
-
buffer
Expands the zoom limits to allow zooming to the specified distance.
Returns the current camera position.
Returns:
An {x, y} object of the current camera postion.
Returns the current camera rotation.
Returns:
The current rotation of the camera, in radians.
Returns the current camera tilt
Returns:
The current tilt of the camera, in radians.
Returns the current camera zoom
Returns:
The distance of the camera from the anchor.
Returns the actual zoom maximum based on visible map size.
Returns:
The actual zoom maximum in map units.
Returns the actual zoom minimum based on real-world distance.
Returns:
The actual zoom minimum in map units.
Returns true if the camera is currently moving (it's animating, the user is manipulating it).
Returns:
True if the camera is moving, false otherwise.
Anything we need to do after we render the camera, like update anchors for the mouse/touch controls.
-
zoom
-
buffer
Restricts the zoom limits, but will not restrict beyond the current zoom level.
-
radians
Rotates the camera a set number of radians relative to the current rotation. Useful for an idle rotation animation.
Parameters:
-
radians
NumberNumber of radians to rotate the camera.
-
position
-
zoom
-
rotation
-
tilt
Allows you to set any of the Camera's position, zoom, rotation and tilt at once, with one function.
-
x
-
y
Sets the camera anchor to a specifc x/y positon, in the global reference frame. 0,0 will be roughly the middle of the map, and panBounds holds the min/max points.
-
radians
Sets the rotation to a specific orientation, in radians. Mostly useful to orient the map a certain way for a physical directory.
Parameters:
-
radians
NumberAbsolute rotation to set the camera to, in radians. 0 in the starting point.
-
radians
Sets the tilt to a specific level, in radians. 0 is top down. Bounded by minTilt and maxTilt.
Parameters:
-
radians
NumberTilt to set the camera to, in radians.
-
zoom
Sets the camera to be a certain distance from the anchor point, along it's tilt and rotation. Keeps it inside minZoom and maxZoom.
Parameters:
-
zoom
NumberThe distance to set the camera to.
-
radians
Tilts the camera up or down by some number of radians. Bounded by minTilt and maxTilt.
Parameters:
-
radians
NumberNumber of radians to increase or decrease the current tilt by.
Should probably be "pre-render". Anything we need to do before rendering the scene.
-
zoom
Moves the camera towards or away from the camera by a set amount. Positive will zoom in (bringing the distance closer to 0).
Parameters:
-
zoom
NumberThe distance to increase or decrease the zoom.
CAMERA_EVENTS
Object constCamera events you can attach a listener to (with controls.addListener(event, function)
), if you want to do certain things. They'll be fired both by touch events and by functions you can call yourself like pan() and tilt()/
Sub-properties:
-
CHANGE_EVENT
ObjectFired whenever the camera changes.
-
PAN_START_EVENT
ObjectFired when the camera starts panning.
-
PAN_END_EVENT
ObjectFired when the camera finishes panning.
-
ROTATE_START_EVENT
ObjectFired when the camera starts rotating.
-
ROTATE_END_EVENT
ObjectFired when the camera stops rotating.
-
ZOOM_START_EVENT
ObjectFired when the camera starts zooming.
-
ZOOM_END_EVENT
ObjectFired when the camera finishes zooming.
-
MULTI_START_EVENT
ObjectFired when the camera starts animating or you called setMulti. It means any one or more of pan, tilt, rotate and zoom could be changing. The individual pan/tilt/rotate/zoom events will NOT be fired.
-
MULTI_END_EVNT
ObjectFired when the camera stops animating, or has finished the setMulti call.
maxPedestal
NumberMax amount to allow scrolling maps down (In Z-axis units, at the origin, down is positive)
Default: Infinity
maxTilt
NumberMinium camera tilt, in radians. If you set it too high, the camera will be able to tilt down through the geometery of the scene, which will produce clipping issues.
Default: 1.2
maxZoom
NumberMaximum distance the camera can get from it's anchor on the ground. Setting this too high will result in parts of the map falling out of the camera's clipping plane and disappearing.
Default: 10000
minPedestal
NumberMax amount to allow scrolling maps up (In Z-axis units, at the origin, up is negative)
Default: -Infinity
minTilt
NumberMinium camera tilt, in radians. If it's anything other than 0, you won't be able to look at the venue from the top down perspective.
Default: 0.0
minZoom
NumberThis is actually the minium distance the camera can get from it's anchor on the ground. May be worth changing if your map has very tall buildings to avoid the camera clipping through them.
Default: 375
mouseButtons
ObjectIf you would really prefer to pan with the right mouse button and tilt/rotate with the left, you can swap the values here to achieve that.
Sub-properties:
-
ORBIT=MOUSE.RIGHT
MOUSEThe button to use for tilt/rotation. Defaults to
MOUSE.RIGHT
. -
ZOOM=MOUSE.MIDDLE
MOUSEThe button to use for zoom behaviour. Don't change this.
-
PAN=MOUSE.LEFT
MOUSEThe button to use for panning the camera. Defaults to
MOUSE.LEFT
.
panBounds
ObjectConstrains the camera from panning to far away from the scene. It's set automatically based on the size of the map. If you want to change anything, you probably want to change the margin property, which is the factor the min and max in each dimension are multiplied by to give the true bounds. For example, on a truely huge venue a 1.25 margin could get you way out into space when zoomed in.