basic perspective rendering

[ansis]

This merges current work on perspective rendering so that it doesn't get more stale.

Two transform properties are added:

pitch

The angle at which the camera is looking at the ground. 0 is straight down, 90 would be horizontal. The bigger the pitch, the more vertically squashed everything gets.

examples (with altitude 1.5):
pitch = 0
pitch = 30
pitch = 60

altitude

How high above the surface the camera is. The altitude units are "canvas heights". So an altitude of 3 should be 3x the vertical distance shown on the canvas. Decreasing the altitude makes everything more perspectivy.

examples (with pitch 55):
altitude = 0.75
altitude = 1.5
altitude = 100

Apple uses the names pitch and altitude in their sdk. Google calls pitch viewing angle and doesn't expose altitude.

A pitch argument was added to setView() and easeTo. setPitch() and getPitch() also added.

The implementation has three parts:

• the api for setting these properties
• calculating the projection matrix (and converting points back to coordinates)
• adapting antialiasing so that it works for everything. This is the hard part.

cc @jfirebaugh

Todo:

• Fix or update render tests. Most render tests are failing because everything is rendered a tiny bit more zoomed in. I still need to figure out if this wrong, and if it is how/whether it can be fixed.

[mourner]

what's up with 1px here?

[ansis]

See commit message here e5ee155 The tests were too sensitive.

[ansis]

@mourner:

Hmm, I'd rather fix the tests to check row equality within a margin when perspective is set.

The tests are affected by which tiles are in the view's covering tiles. I didn't see an easy way to allow a certain margin of error in the output, so I just changed the size of the test view so that it wouldn't test a case where multiple possible results would be ok.

[mourner]

This is so awesome, can't wait for this to get merged!

[karenzshea]

sweeeeeet

[jfirebaugh]

Should we change this to accept a single options argument?

[ansis]

I think so. Especially if we want to expose altitude too.

Or maybe separating the view from the ease options make sense: easeTo(view, options)?

[jfirebaugh]

Is this ready to merge?

[bsudekum]

@ansis Could we get an example and/or an update to api.md?

[ansis]

@bsudekum we're switching to internal jsdoc documentation that will be eventually processed into external docs. For now:

setView

mapbox-gl-js/js/ui/map.js

Line 123 in 7740a35

* @param {Number} pitch The angle at which the camera is looking at the ground

setPitch

mapbox-gl-js/js/ui/map.js

Line 184 in 7740a35

* Sets a map angle

getPitch

mapbox-gl-js/js/ui/map.js

Line 217 in 7740a35

getPitch: function() { return this.transform.pitch; },

easeTo

mapbox-gl-js/js/ui/easings.js

Line 291 in 7740a35

* @param {Number} pitch

example issue: #1062