Facilitate for globe transition expression refactoring

[HarelM]

Launch Checklist

• Fixes Cannot go from vertical-perspective to globe projection #5114
• Fixes Incorrect custom layer render methods argument args.defaultProjectionData.mainMatrix value using globe projection with high zoom level #5117

This is a draft PR at this point to see what still need to be fixed and for others to see.
CC: @birkskyum @ibesora @kubapelc

The idea behind this refactoring:

1. Move all logic that is common for vertical-perspective and mercator to the transform helper.
2. Create a new class to hold all the logic of transitioning while relaying on the two transforms to do their part when called.
3. Remove the events and define the default expression for globe

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!

[codecov]

Codecov Report

Attention: Patch coverage is 85.88020% with 231 lines in your changes missing coverage. Please review.

Project coverage is 91.82%. Comparing base (9ca3f20) to head (1703870).
Report is 4 commits behind head on main.

✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
...c/geo/projection/vertical_perspective_transform.ts	85.41%	104 Missing ⚠️
...o/projection/vertical_perspective_camera_helper.ts	73.63%	82 Missing ⚠️
src/geo/projection/globe_projection.ts	89.38%	12 Missing ⚠️
src/geo/projection/projection_factory.ts	71.87%	9 Missing ⚠️
src/geo/projection/globe_transform.ts	93.69%	7 Missing ⚠️
src/geo/transform_helper.ts	94.54%	6 Missing ⚠️
src/geo/projection/camera_helper.ts	94.00%	3 Missing ⚠️
src/geo/projection/globe_camera_helper.ts	86.36%	3 Missing ⚠️
.../geo/projection/vertical_perspective_projection.ts	88.46%	3 Missing ⚠️
src/geo/projection/mercator_transform.ts	97.56%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5139      +/-   ##
==========================================
- Coverage   91.84%   91.82%   -0.03%     
==========================================
  Files         278      281       +3     
  Lines       38336    38776     +440     
  Branches     6714     6756      +42     
==========================================
+ Hits        35211    35605     +394     
- Misses       2996     3043      +47     
+ Partials      129      128       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[birkskyum]

I think this looks like the right direction, with the globe transform (being a mercator<->verticalPerspective lerp) to contain a mercatorTransform and now also a verticalPerspectiveTransform, and call into those, instead of having too much logic of it's own.

[HarelM]

Surprisingly I think I managed to find what created the issues in the branch after trying to recreate it in another branch...
I'll see if I can fix the remaining failing unit test, but otherwise this might be ready for review.
@kubapelc I found strange behavior in the getProjectionData and getProjectionDataForCustomLayer - both methods don't really follow the "if globe do that otherwise do what we did in mercator".
Last two commits are basically reverting the logic there, but I still find it odd.
Any chance you can take a look and let me know if there are improvements that can be done?

[kubapelc]

The new getProjectionData on globe transform look good to me! As for getProjectionDataForCustomLayer it is somewhat broken in main right now, I'm fixing it to resolve #5117. But I have some render tests failing after the fix, and I haven't figured it out yet.

[HarelM]

I think you can simply fix it by opening a PR to this branch, it would be better to avoid the need for me to resolve conflicts.
Is it possible to get a fallbackMatrix without the code from mercator transform? Or should I move part of the code from mercator transfrom to the helper to calculate the fallbackMatrix in case of globe/vertical-perspective?
There is also the same question for prefetchTiles and a few more other places where I couldn't find a proper solution.
If you could take a look at those it would be great.
I'm also thinking about splitting the camera helper the same way I did for the globe transform, it creates a clear separation of code and is very easy to see where issues exists this way.

[kubapelc]

Is it possible to get a fallbackMatrix without the code from mercator transform?

I think it makes sense to query mercator transfrom to get the fallback matrix. since it is the exact matrix which is used when mercator is active. Globe mostly needs it to do the projection transition.

There is also the same question for prefetchTiles and a few more other places where I couldn't find a proper solution.

I think precacheTiles is ok in its current state, since there is no equivalent for globe transform. Mercator needs to compute a separate matrix for each tile, globe does not. (But I'm honestly not sure this precaching step even helps performance, I think maplibre did do it originally, but it was a side effect of some other function which was obsoleted and removed by the globe changes, iirc., and so I left it in.)

I'll go over all the mercator transform usages.

I'm also thinking about splitting the camera helper the same way I did for the globe transform

Sounds good!

[kubapelc]

I went over all mercator transform usages in the current globe_transform.ts, everything looks good, I only added a comment about the removed double interpolation.

[ibesora]

I like where this is going, nice work!
Added some comments but feel free to ignore them (except for the typo ones!)

[HarelM]

@kubapelc I'm looking into leveraging the following code to calculate the current globeness:

type ProjectionProps = {
    type: DataConstantProperty<ProjectionDefinition>;
}

type ProjectionPossiblyEvaluated = {
    type: ProjectionDefinitionSpecification;
}

const properties: Properties<ProjectionProps> = new Properties({
    'type': new DataConstantProperty(styleSpec.projection.type as StylePropertySpecification)
});

export class ProjectionTransition extends Evented {
    properties: PossiblyEvaluated<ProjectionProps, ProjectionPossiblyEvaluated>;

    _transitionable: Transitionable<ProjectionProps>;
    _transitioning: Transitioning<ProjectionProps>;

    constructor(projection?: ProjectionSpecification) {
        super();
        this._transitionable = new Transitionable(properties);
        this.setProjection(projection);
        this._transitioning = this._transitionable.untransitioned();
        this.recalculate(new EvaluationParameters(0));
    }

    setProjection(projection?: ProjectionSpecification) {
        this._transitionable.setValue('type', projection.type);
    }

    updateTransitions(parameters: TransitionParameters) {
        this._transitioning = this._transitionable.transitioned(parameters, this._transitioning);
    }

    hasTransition() {
        return this._transitioning.hasTransition();
    }

    recalculate(parameters: EvaluationParameters) {
        this.properties = this._transitioning.possiblyEvaluate(parameters);
    }
}

//... usage:
new ProjectionTransition({
    type: ["interpolate", ["linear"], ["zoom"],
    10, "vertical-perspective", 12, "mercator"]
});

This leverages maplibre's expression evaluation capabilities and it looks like it is working as expected, and also removes the code related to animation and time tracking. I do see code related to updating the zoom and center when the globeness is not equal, can you elaborate on what it does?

[kubapelc]

I do see code related to updating the zoom and center when the globeness is not equal, can you elaborate on what it does?

See #5139 (comment)

We need to somehow smoothly move globe's map center to match mercator, it is not clear how now that the transition is controlled by an arbitrary expression.

Maybe we can interpolate the center towards mercator every time that globeness decresases compared to the last update, and do nothing if it increases? This would make zooming in smoothly interpolate the center, and zooming out would not affect it.

[HarelM]

I'll create a PR against this branch with the changes related to the globeness calculations outside the transform class so we can discuss the changes.
@ibesora @kubapelc I've left the comments above unresolved, let me know if you want me to close them as resolved or if you prefer to do it so I'd know which comments I still need to address.

[HarelM]

This is now ready for review and afterwards merged to main branch.
This is almost the last change related to version 5, so after this is merged we can release version 5 (there will be other bug fixes afterwards, but no breaking changes).

[HarelM]

@Pessimistress I was about to completely remove the event of projection change here as the only place after these code change that this event is fired is when setting the projection, which is a programmatic operation, and raising an event for something you called seems weird to me...
Please let me know what event would help and when to raise it.
I'll be merging this branch shortly.