Design Proposal: Projection

[HarelM]

Design Proposal: Projection

Motivation

Allow users to set a projection for the map

Proposed Change

Add projection to the root object of the style.

{
   version: 8,
   sources: { ... },
   layers: [],
   projection: {
      type: "mercator" // or "globe"
   }
}

I'm not sure if it should be type or name...

API Modifications

Besides the part of the spec that needs to be added APIs for setProjection and getProjection should be added to the map object.

Migration Plan and Compatibility

This is a new feature. The default would be Mercator.

Rejected Alternatives

N/A

[HarelM]

This is related to the following projection bounty:
maplibre/maplibre#272
Which is related to globe bounty:
maplibre/maplibre#190
As part of the globe implementation, we have found out that we need to properly define this.
See this globe initial PR:
maplibre/maplibre-gl-js#3783
Discussion about globe:
maplibre/maplibre#161

cc: @louwers @sjg-wdw @wipfli @Pheonor @kubapelc

[wipfli]

Could there be a plugin system for projections? Because there are many projections and we probably don't want to include all of them in the library. Might be wrong though...

[wipfli]

I would of course love to get support for https://en.m.wikipedia.org/wiki/Swiss_coordinate_system.

Talking of which, what is the difference between a projection and a coordinate system? And would the tiles always be assumed to use web mercator?

[wipfli]

Cc @pka since you are looking into Equal Earth...

[HarelM]

Could there be a plugin system for projections?

That's an interesting thought, I would assume that after we include more than just globe and mercator we can design an API that will allow adding more projections. Note that current code has the projection implementation in the shaders, so adding a custom shader might prove tricky, but generally speaking, we should aim to be able to add more projections.

[kubapelc]

In globe, anything that satisfies the Projection interface can supply its own shader code as a string. But not shader uniforms, those are currently hardcoded. I'm a bit more worried about how custom projections would interact with transform, panning the map, zooming, etc. There is a lot of complex logic in the transform class. I haven't even looked at that for globe yet.

[sjg-wdw]

Having implemented all of this in another toolkit here's some random thoughts.

Web Mercator is a deceptively simple projection. You can project back and forth with fairly simple functions and no iteration, no weird gridded offsets, that sort of thing. As such it can be unhelpful to design around. For example, doing the work in a shader is pretty easy, but much less so for something like UTM with a specialized ellipsoid and some strange offsets.

I'm not saying you need to implement all that madness, just design around it and drop in the pieces you already have.

A plugin system for projections is a good idea. It should be able to:

• project between coordinate systems
• project to model globe coordinates (kind of geocentric, but maybe not exactly)
• tell if two coordinate systems are the same. Harder than it sounds

Then you can drop in your existing implementation.

As for what needs a projection, I'd say the overall map and each data source. As to how you specify it, just do what Proj does. I'm fond of proj strings, but I think there's a JSON version of the WKT formatting that would work better in this case.

At least having those defined would let you implement three cases you can sort of do easily:

• Web Mercator with all Web Mercator sources
• A random projection with sources in that same projection. You need to convert out to lat/lon for utility functions here, which might be a bit of work.
• A globe with web mercator sources

Putting it all out there in proper form lets you expand as developers are interested in dealing with it. But for now you can just reject everything that's not implemented, like feeding UTM sources into a globe or some such.

Oh and the type is a good idea for the UI control system to figure out what to do. I'd suggest flat and globe, letting an explicit projection set what kind of flat map. Then ask the projection system if it's web mercator.

[Pheonor]

Very usefull feedback on previous experience, thanks !
For me, 'type' refers to 'globe' of 'flat' not the projection name.
Perhaps an explicit 'name' could be used.

[sjg-wdw]

Naming projections can get a little wonky on the implementation side. Sometimes it's best to just use the full projection definition so developers know to avoid shortcuts.

[vlarrieu]

Naming projections can get a little wonky on the implementation side. Sometimes it's best to just use the full projection definition so developers know to avoid shortcuts.

Ok, so you suggest to keep 'type' with 'globe' or 'flat' value. Its clear for me.
We could extend the projection system later.

[syonfox]

One comment is that it seems the sky and globe details are linked.

Of the top of my head the current plan is something lie

{
  projection: { 
    type: "globe", ... // type spicific settings
  }
  sky: {
    
  }
}

I need to do some more digging but are the atmosphere and globe effects not inherently linked.

it was mentioned that maybe having a module system to support different projections.

my question would then be how many projections are planed on being supported.

Would you want to offer a polar mode and a dymaxine mode etc. Or is this out of scope.

to throw out another perspective the globe mode could be the actual parameter with its own options.

{
  globe: { //falsy foe disabled or truthy for defaults or object with defined parameters such as
    background: "color/ starmap config??",
    skybox: {...}, // this maybe is independent from terrain atmosphere effect. but could inharent those settings as default or something. 
    
  },
  sky: { //terrain atmosphere rendering settings ... in globe mode it applies to both globe atmosphere effect when zoomed out and the terrain atmosphere

  }
}

// note I see that the sky spec is being used in both the terrain mode and globe mode. 

As this idea progresses and I look at more of the implementation maplibre/maplibre-gl-js#3783

maybe it makes sense to have this be a new issue for a feature skybox that is used by both the terrain mode and the globe projection simpler to the sky effect.

Some questions are? is it more or less complicated to have these be shared between the 2 modes.

{
...
projection: {
 type: "globe"
 ...globeSpecifiecOptions
}
terrain: {} // options specific to the zoomed in terrain mode

sky: { // shared between terrain and globe mode
 
  skybox: "image url in galactic cordanates or cubemap... depends on implmenetation"
}
}

https://maplibre.org/maplibre-style-spec/root#sky

I think That this is getting away from details specific to the projection feature but is probably useful context.

#163 Ill link this here but one question is

Is it best to have these options in one simple place fore each projection mode or to make a general version of them.

ps thanks for the cool project it looks promising.

[HarelM]

I've added the projection configuration to allow adding this to the globe branch. It is still marked as experimental and follows the initial suggestion I made in the beginning of this thread.
We might change it to facilitate WKT formats in the future when we have a better understanding on how to do it properly.