Geographic Coordinates and Projections
This document covers Leaflet's coordinate system architecture, including geographic coordinate representations, pixel coordinate systems, coordinate reference systems (CRS), and the projection pipeline that transforms between geographic and screen coordinates. For information about map view management and zoom levels, see Map Component. For details about geometry utilities and mathematical operations, see Utilities and Class System.
Geographic and Pixel Coordinate Systems
Leaflet operates with two fundamental coordinate spaces: geographic coordinates representing positions on Earth, and pixel coordinates representing positions on screen. The library provides dedicated classes for each space and their bounding rectangles.
LatLng and Geographic Coordinates
The LatLng class represents geographical points with latitude, longitude, and optional altitude values. It supports flexible construction patterns and provides geographic calculations.
| Constructor Pattern | Example | Description |
|---|---|---|
| Individual coordinates | new LatLng(50.5, 30.5) | Latitude, longitude, optional altitude |
| Array format | new LatLng([50.5, 30.5]) | [lat, lng] or [lat, lng, alt] |
| Object format | new LatLng({lat: 50.5, lng: 30.5}) | Object with lat/lng or lat/lon |
The class provides essential geographic operations including distance calculations using the Haversine formula, coordinate wrapping for longitude boundaries, and bounds generation for spatial queries.
LatLngBounds for Geographic Areas
LatLngBounds represents rectangular geographical areas defined by southwest and northeast corner points. It provides spatial relationship methods and boundary calculations.
Point and Pixel Coordinates
The Point class handles pixel coordinates with comprehensive mathematical operations. Unlike geographic coordinates, points represent screen positions and support vector mathematics.
Coordinate Reference Systems Architecture
The CRS (Coordinate Reference System) classes form the core of Leaflet's projection system, transforming between geographic coordinates and pixel coordinates through a two-stage process involving projection and transformation.
CRS Base Class and Projection Pipeline
The base CRS class defines the standard interface for coordinate transformations. The projection pipeline involves two key stages: geographic projection to an intermediate coordinate system, then affine transformation to pixel coordinates.
The CRS class provides these core transformation methods:
| Method | Purpose | Pipeline Stage |
|---|---|---|
latLngToPoint(latlng, zoom) | Geographic to pixel coordinates | Full pipeline |
pointToLatLng(point, zoom) | Pixel to geographic coordinates | Reverse pipeline |
project(latlng) | Geographic to projected coordinates | Projection only |
unproject(point) | Projected to geographic coordinates | Reverse projection |
Transformation Class for Affine Operations
The Transformation class handles affine transformations using coefficients a, b, c, d to convert points from (x, y) to (a*x + b, c*y + d). This is used by CRS implementations to transform projected coordinates to pixel coordinates at specific zoom levels.
CRS Implementations
Leaflet includes several CRS implementations for different mapping scenarios, each with specific projection characteristics and use cases.
Earth-Based CRS Systems
The Earth class serves as the base for global CRS implementations, providing longitude wrapping and Haversine distance calculations.
Web Mercator (EPSG:3857)
The most common CRS for web mapping, EPSG3857 uses Spherical Mercator projection and is the default for most tile providers.
Simple CRS for Non-Geographic Maps
CRS.Simple provides a direct 1:1 mapping between longitude/latitude and x/y coordinates, suitable for game maps or non-geographic imagery.
Coordinate System Integration
The coordinate system components work together to provide seamless transformation between geographic positions and screen rendering. The system handles coordinate wrapping, bounds checking, and zoom-level scaling automatically.
This architecture enables Leaflet to support diverse mapping scenarios from standard web maps using Web Mercator projection to specialized applications requiring custom coordinate systems or non-geographic imagery.