derive scale in 3d model example

[andrewharvey]

Launch Checklist

• briefly describe the changes in this PR

closes #8508. the custom layers with three.js example uses a magic number for the model scale, in this PR we try to show for a model with units in meters, how to determine the scale.

This PR is one option. another option is move most of this code to src/geo/mercator_coordinates.js, so the user can just ask for MercatorScale(lat), I'd probably prefer the latter, thoughts?

[ryanhamley]

@ansis I think you implemented Mercator coordinates. What do you think about Andrew's proposal for implementing a way to get a scale factor?

If we stick with this PR, I'd suggest adding a comment explaining what the math is doing.

[andrewharvey]

I've explained below, but I think ideally we'd wrap this up in a method that we expose to the user. I'll try to do that shortly...

var scaleFactor = 1 / Math.cos(modelOrigin[1] * Math.PI / 180);

From https://en.wikipedia.org/wiki/Mercator_projection#Scale_factor, the Mercator projection's scale factor is secant(latitude in radians) which is 1 / cos(latitude in radians).

This is since at higher latitudes, a meter is more pixels than at the lower latitudes, and this scale factor accounts for this.

var mercatorExtent = 2 * Math.PI * 6378137;

This is the extent of the map in meters, -180 longitude to 180 longitude. We need this because the Mapbox GL Custom Layers expects all units to be unit values, 0 to 1, so we need to know the extent in meters so we can scale our model units (in meters) to a 0 to 1 value that Mapbox expects.

var modelScale = 1 / mercatorExtent * scaleFactor;

1 meter in the model units / the total extent of the map in meters gives our 0 to 1 unit value from above, then simply multiply by the mercator scale factor to get our transform scale.

[andrewharvey]

I put together #8524 which would make these scale calculations internal to the MercatorCoordinate class, so developers don't need to do any calculations.

However since that, if approved, would only go into the next release, I think this change to the documentation could still go in independently so that the example is updated straight away.

[andrewharvey]

We can skip this and just wait for #8524 together with https://github.com/mapbox/mapbox-gl-js-docs/pull/23 in the next release.