What is the difference between map container coordinates and layer coordinates?

From what I gathered, the map container coordinates are always relative to the map viewport, and while layer coordinates always start out with the same values as the container coords, they change once the map is panned.

APIs that refer to coordinates/point:

2 Answers 2


Short answer

The containerPoint methods date from a feature request back in 2012, and today, they're a bit confusing.

The best answer is Leaflet maintainer Vladimir Agafonkin's description:

"layerPoint is actually a point relative to the map layer (the div which contains tiles and markers), not the outer map container. What you need is map.layerPointToContainerPoint. But I agree there's no convenient method to get it immediately, so scheduling this for the next version."

Long answer

In greater detail:

The core public conversion methods in Leaflet, although seldom used by application developers, are L.Map.project(latlng [, zoom]) and L.Map.unproject(point [, zoom]).

Web maps are split up into a grid of tiles, each with the same number of pixels. At higher zoom levels, the map is divided into a greater number of tiles, with a corresponding greater number of pixels. Thus the pixel size of the map is dependent on the zoom level.

This means that if you're messing around with a Leaflet demo window in your browser, the output of L.Map.project` for a given latlng will only change if you zoom in and out.

As of the latest version of Leaflet (0.7.3), the definition of L.Map.latLngToLayerPoint reads:

latLngToLayerPoint: function (latlng) {
    var projectedPoint = this.project(L.latLng(latlng))._round();
    return projectedPoint._subtract(this.getPixelOrigin());

By contrast, L.Map.latLngToContainerPoint reads:

latLngToContainerPoint: function (latlng) {
    return this.layerPointToContainerPoint(this.latLngToLayerPoint(L.latLng(latlng)));

with L.Map.layerPointToContainerPoint defined to be:

layerPointToContainerPoint: function (point) { 
    return L.point(point).add(this._getMapPanePos());

The private map method _getMapPanePos() returns the offset between the current map position and its position when it was first created. This only changes during a map pan (not during zoom), so the difference between the layerPoint and containerPoint corresponding to a given latlng is that the layerPoint is the position of the latlng in the map container <div> with the map at its initial position, while the containerPoint is the current position of the latlng in the map container <div>.

  • 1
    Man--if I could upvote, you'd get upvoted a 100 times.
    – Saad Malik
    Jul 16, 2014 at 2:00

EDIT: turns out I was wrong. Container coordinates seem to be for the visible frame while layer coordinates are for a bigger area than that visible. This question needs someone more knowledgeable than me to answer it.

  • 1
    Alex - I don't believe that is correct. The container coordinates and layer coordinates are both specified in pixels from the origin (top-left) of container. However, when I start panning the map, the layer coordinate/point of a marker remains the same while the map coordinate/point for a marker is updated respective to the top-left origin point.
    – Saad Malik
    Aug 21, 2013 at 16:34
  • Hi @SimFox3, you're right. And I should have tested it before saying anything! I now thing that the layer point is a coordinate that is defined relative to a sort of 'window' that is held, that is bigger than the screen. It's like a cached view that's biogger than the screen. That's why the layer point coordinates change, but not often, and only when the 'window' is moved. The container point coordinates seem always confined to coordinates relative to the visible view. Having said all that, it's clear I don't know any more than you, so it would be great if a Leaflet dev. could chip in!
    – Alex Leith
    Aug 21, 2013 at 23:51

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.