Merge pull request #126 from kartena/leaflet-proj-refactor

Leaflet 1.0.3 support.

.gitignore

@@ -1,2 +1,2 @@
 node_modules
-
+.lvimrc

README.md

@@ -1,18 +1,162 @@
-Proj4Leaflet [![NPM version](https://badge.fury.io/js/proj4leaflet.png)](http://badge.fury.io/js/proj4leaflet)
-============
+# Proj4Leaflet [![NPM version](https://badge.fury.io/js/proj4leaflet.png)](http://badge.fury.io/js/proj4leaflet)
 
 This [Leaflet](http://leafletjs.com) plugin adds support for using projections supported by
 [Proj4js](https://github.com/proj4js/proj4js).
 
-*For compatibility with Leaflet 1.0-beta1 use the leaflet-proj-refactor branch.*
+_Proj4Leaflet uses Leaflet 1.0.3, for compatibility with Leaflet 0.7.x use the [0.7.2](https://github.com/kartena/Proj4Leaflet/releases/tag/0.7.2) release._
 
-## Features
+Leaflet comes with built in support for tiles in [Spherical Mercator](http://wiki.openstreetmap.org/wiki/EPSG:3857) and [a few other projections](http://leafletjs.com/reference-1.0.0.html#crs-l-crs-epsg3395). 
+If you need support for tile layers in other projections, the Proj4Leaflet plugin lets you use tiles in any projection 
+supported by Proj4js, which means support for just about any projection commonly used.
 
-* Supports all commonly used projections
-* Extends Leaflet with full TMS support even for local projections
-* Makes it easy to use GeoJSON data with other projections than WGS84
-* Image overlays with bounds set from projected coordinates rather than `LatLngs`
+Proj4Leaflet also adds support for GeoJSON in any projection, while Leaflet by itself assumes GeoJSON to always 
+use WGS84 as its projection.
 
-Leaflet comes with built in support for tiles in [Spherical Mercator](http://wiki.openstreetmap.org/wiki/EPSG:3857). If you need support for tile layers in other projections, the Proj4Leaflet plugin lets you use tiles in any projection supported by Proj4js, which means support for just about any projection commonly used.
+Image overlays with bounds set from projected coordinates rather than `LatLng`s are also supported by Proj4Leaflet plugin.
 
-For more details and API docs, see the [Proj4Leaflet site](http://kartena.github.io/Proj4Leaflet/).
+For more details, see this blog post on [tiling and projections](http://blog.kartena.se/local-projections-in-a-world-of-spherical-mercator/).
+
+## Usage
+
+Common use means making a new CRS instance for the projection you want to use.
+
+```javascript
+// RT90 with map's pixel origin at RT90 coordinate (0, 0)
+var crs = new L.Proj.CRS('EPSG:2400',
+  '+lon_0=15.808277777799999 +lat_0=0.0 +k=1.0 +x_0=1500000.0 ' +
+  '+y_0=0.0 +proj=tmerc +ellps=bessel +units=m ' +
+  '+towgs84=414.1,41.3,603.1,-0.855,2.141,-7.023,0 +no_defs',
+  {
+    resolutions: [8192, 4096, 2048] // 3 example zoom level resolutions
+  }
+);
+
+var map = L.map('map', {
+  crs: crs,
+  continuousWorld: true,
+  worldCopyJump: false
+});
+
+L.tileLayer('http://tile.example.com/example/{z}/{x}/{y}.png').addTo(map);
+```
+
+Using options when constructing the CRS, you can set the tile set's origin.
+
+```javascript
+// SWEREF 99 TM with map's pixel origin at (218128.7031, 6126002.9379)
+var crs = new L.Proj.CRS('EPSG:3006',
+  '+proj=utm +zone=33 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs',
+  {
+    origin: [218128.7031, 6126002.9379],
+    resolutions: [8192, 4096, 2048] // 3 example zoom level resolutions
+  }
+);
+```
+
+## Proj4js compatibility notice
+Proj4js has breaking changes introduced after version 1.1.0. The current version of Proj4Leaflet
+uses Proj4js 2.3.14 or later. If you for some reason need Proj4js version 1.1.0 compatibility, you can
+still use Proj4Leaflet [version 0.5](https://github.com/kartena/Proj4Leaflet/tree/0.5).
+
+## API
+The plugin extends Leaflet with a few classes that helps integrating Proj4's projections into
+Leaflet's [CRS](http://leafletjs.com/reference-1.0.0.html#crs) abstract class.
+
+### L.Proj.CRS
+A CRS implementation that uses a Proj4 definition for the projection. 
+This is likely to be the only class you need to work with in Proj4Leaflet.
+
+#### Usage example
+
+```javascript
+var map = L.map('map', {
+    center: [57.74, 11.94],
+    zoom: 13,
+    crs: L.Proj.CRS('EPSG:2400',
+      '+lon_0=15.808277777799999 +lat_0=0.0 +k=1.0 +x_0=1500000.0 ' +
+      '+y_0=0.0 +proj=tmerc +ellps=bessel +units=m ' +
+      '+towgs84=414.1,41.3,603.1,-0.855,2.141,-7.023,0 +no_defs',
+      {
+        resolutions: [8192, 4096, 2048] // 3 example zoom level resolutions
+      }
+    ),
+    continuousWorld: true,
+    worldCopyJump: false
+});
+```
+
+#### Constructor
+
+```javascript
+L.Proj.CRS(code, proj4def, options)
+```
+
+* `code` is the projection's SRS code (only used internally by the Proj4js library)
+* `proj4def` is the Proj4 definition string for the projection to use
+* `options` is an options object with these possible parameters:
+  * `origin` - the projected coordinate to use as the map's pixel origin; overrides the `transformation` option if set
+  * `transformation` - an [L.Transformation](http://leafletjs.com/reference-1.0.0.html#transformation) that is used 
+  to transform the projected coordinates to pixel coordinates; default is `L.Transformation(1, 0, -1, 0)`
+  * `scales` - an array of scales (pixels per projected coordinate unit) for each corresponding zoom level; 
+  default is to use Leaflet's native scales. You should use `scales` _or_ `resolutions`, not both.
+  * `resolutions` - an array of resolutions (projected coordinate units per pixel) for each corresponding zoom level; 
+  default is to use Leaflet's native resolutions. You should use `scales` _or_ `resolutions`, not both.
+  * `bounds` - an [L.Bounds](http://leafletjs.com/reference-1.0.0.html#bounds) providing the bounds of CRS in projected 
+  coordinates. If defined, Proj4Leaflet will use this in the `getSize` method, otherwise reverting to Leaflet's 
+  default size for Spherical Mercator.
+
+### L.Proj.GeoJSON
+
+Extends [L.GeoJSON](http://leafletjs.com/reference-1.0.0.html#geojson) to add CRS support. Unlike the TileLayer extension, the 
+CRS is derived from the `name` property of a `crs` defined directly on the GeoJSON object per [the spec](http://www.geojson.org/geojson-spec.html#named-crs). 
+Linked CRSs are not supported.
+
+**Note:** The relevant Proj4 definition should be defined directly via `proj4.defs` before loading the GeoJSON object. 
+If it is not, Proj4leaflet will throw an error.
+
+Also, note that future versions of the GeoJSON spec may not include explicit CRS support. See https://github.com/GeoJSONWG/draft-geojson/pull/6 for more information.
+
+#### Usage Example
+
+```javascript
+proj4.defs("urn:ogc:def:crs:EPSG::26915", "+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs");
+
+var geojson = {
+  type: "Feature",
+  geometry: {
+    type: "Point",
+    coordinates: [481650, 4980105]
+  },
+  crs: {
+    type: "name",
+    properties: {
+      name: "urn:ogc:def:crs:EPSG::26915"
+    }
+  }
+};
+
+var map = L.map('map');
+
+L.Proj.geoJson(geojson).addTo(map);
+```
+
+### L.Proj.ImageOverlay
+
+Works like [L.ImageOverlay](http://leafletjs.com/reference-1.0.0.html#imageoverlay), but accepts bounds in the map's
+projected coordinate system instead of latitudes and longitudes. This is useful when the projected coordinate systems
+axis do not align with the latitudes and longitudes, which results in distortion with the default image overlay in Leaflet.
+
+#### Usage Example
+
+```javascript
+// Coordinate system is EPSG:28992 / Amersfoort / RD New
+var imageBounds = L.bounds(
+  [145323.20011251318, 475418.56045463786],
+  [175428.80013969325, 499072.9604685671]
+);
+
+L.Proj.imageOverlay('http://geo.flevoland.nl/arcgis/rest/services/Groen_Natuur/Agrarische_Natuur/MapServer/export?' +
+  'format=png24&transparent=true&f=image&bboxSR=28992&imageSR=28992&layers=show%3A0' +
+  '&bbox=145323.20011251318%2C475418.56045463786%2C175428.80013969325%2C499072.9604685671&size=560%2C440',
+  imageBounds);
+```

examples/geojson-crs/index.html

@@ -3,11 +3,11 @@
   <head>
     <meta charset="utf-8" />
     <link rel="stylesheet" href="style.css" />
-    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.css" />
+    <link rel="stylesheet" href="../../lib/leaflet/leaflet.css" />
   </head>
   <body>
     <div id="map"></div>
-    <script src="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.js"></script>
+    <script src="../../lib/leaflet/leaflet.js"></script>
     <script src="../../lib/proj4-compressed.js"></script>
     <script src="../../src/proj4leaflet.js"></script>
     <script src="script.js"></script>

examples/geojson-crs/script.js

@@ -1,18 +1,14 @@
 var map = L.map('map').setView([44.97,-93.24], 11);
 
-// MapQuest OSM Tiles
-
-// Attribution (https://gist.github.com/mourner/1804938)
-var osmAttr = 'Map data &copy; <a href="http://openstreetmap.org">OpenStreetMap</a> contributors, <a href="http://creativecommons.org/licenses/by-sa/2.0/">CC-BY-SA</a>',
-    mqTilesAttr = 'Tiles &copy; <a href="http://www.mapquest.com/"" target="_blank">MapQuest</a> <img src="http://developer.mapquest.com/content/osm/mq_logo.png" />';
+// OSM Tiles
 
 L.tileLayer(
-  'http://otile{s}.mqcdn.com/tiles/1.0.0/map/{z}/{x}/{y}.png',
+  'http://tile.openstreetmap.org/{z}/{x}/{y}.png', 
   {
-    subdomains: '1234',
-    attribution: osmAttr + ', ' + mqTilesAttr
+      attribution: 'Data by <a href="http://openstreetmap.org">OpenStreetMap contributors</a>'
   }
-).addTo(map);
+)
+.addTo(map);
 
 // GeoJSON layer (UTM15)
 proj4.defs('EPSG:26915', '+proj=utm +zone=15 +ellps=GRS80 +datum=NAD83 +units=m +no_defs');

examples/image-overlay/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <link rel="stylesheet" href="style.css" />
+    <link rel="stylesheet" href="../../lib/leaflet/leaflet.css" />
+  </head>
+  <body>
+    <div id="map"></div>
+    <script src="../../lib/leaflet/leaflet.js"></script>
+    <script src="../../lib/proj4-compressed.js"></script>
+    <script src="../../src/proj4leaflet.js"></script>
+    <script src="script.js"></script>
+  </body>
+</html>

examples/image-overlay/script.js

@@ -0,0 +1,20 @@
+var crs = new L.Proj.CRS('EPSG:25833', '+proj=utm +zone=33 +ellps=GRS80 +units=m +no_defs', {
+        resolutions: [21674.7100160867, 10837.35500804335, 5418.677504021675, 2709.3387520108377, 1354.6693760054188, 677.3346880027094,
+            338.6673440013547, 169.33367200067735, 84.66683600033868, 42.33341800016934, 21.16670900008467, 10.583354500042335,
+            5.291677250021167, 2.6458386250105836, 1.3229193125052918, 0.6614596562526459, 0.33072982812632296, 0.16536491406316148],
+        origin: [-2500000, 9045984]
+    }
+);
+
+var map = L.map('map', {
+    crs: crs,
+    center: [60, 10],
+    zoom: 14
+});
+
+L.tileLayer('https://services.geodataonline.no/arcgis/rest/services/Geocache_UTM33_EUREF89/GeocacheBasis/MapServer/tile/{z}/{y}/{x}').addTo(map);
+
+L.Proj.imageOverlay('https://services.geodataonline.no/arcgis/rest/services/Geocache_UTM33_EUREF89/GeocacheGraatone/MapServer/export' +
+    '?bbox=220461.84450009145,6661489.40861154,222115.49415195954,6662415.4521056535' +
+    '&size=1250,700&dpi=96&format=png24&transparent=true&bboxSR=25833&imageSR=25833&f=image',
+    L.bounds([220461.84450009145, 6661489.40861154], [222115.49415195954, 6662415.4521056535])).addTo(map);

examples/local-projections/europe/index_austria.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <link rel="stylesheet" href="../style.css" />
+    <link rel="stylesheet" href="../../../lib/leaflet/leaflet.css" />
+  </head>
+  <body>
+    <div id="map"></div>
+    <script src="../../../lib/leaflet/leaflet.js"></script>
+    <script src="../../../lib/proj4-compressed.js"></script>
+    <script src="../../../src/proj4leaflet.js"></script>
+    <script src="script_austria.js"></script>
+  </body>
+</html>

examples/local-projections/europe/script_austria.js

@@ -0,0 +1,36 @@
+var crs31258 = new L.Proj.CRS('EPSG::31258',
+              "+proj=tmerc +lat_0=0 +lon_0=13.33333333333333 +k=1 +x_0=450000 +y_0=-5000000 +ellps=bessel +towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232 +units=m +no_defs",
+              {
+                origin: [-5172500.0, 5001000.0],
+                resolutions: [
+					400.00079375158754,
+				   	200.000529167725,
+				   	100.0002645838625,
+				   	50,
+				   	25,
+				   	15.000052916772502,
+				   	9.9999470832275,
+				   	5.000105833545001,
+				   	3.0001164168995005,
+				   	2.5000529167725003,
+				   	1.9999894166455001,
+				   	1.4999259165184997,
+				   	1.0001270002540006,
+				   	0.5000635001270003,
+				   	0.25003175006350015],
+              });
+
+var map = L.map('map', {
+	crs: crs31258,
+});
+var attrib = "&copy KAGIS http://www.kagis.ktn.gv.at";
+var basemap = new L.TileLayer("http://gis.ktn.gv.at/arcgis/rest/services/tilecache/Ortho_2010_2012/MapServer/tile/{z}/{y}/{x}", {
+	tileSize: 512,
+	maxZoom: 14,
+	minZoom: 0,
+	attribution: attrib
+});
+
+map.addLayer(basemap);
+map.setView([46.66411, 14.63602], 12);
+

examples/local-projections/nz/index_auckland.html

@@ -2,12 +2,12 @@
 <html>
   <head>
     <meta charset="utf-8" />
-    <link rel="stylesheet" href="style.css" />
-    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.css" />
+    <link rel="stylesheet" href="../style.css" />
+    <link rel="stylesheet" href="../../../lib/leaflet/leaflet.css" />
   </head>
   <body>
     <div id="map"></div>
-    <script src="http://cdn.leafletjs.com/leaflet/v0.7.7/leaflet.js"></script>
+    <script src="../../../lib/leaflet/leaflet.js"></script>
     <script src="../../../lib/proj4-compressed.js"></script>
     <script src="../../../src/proj4leaflet.js"></script>
     <script src="script_auckland.js"></script>

examples/local-projections/nz/script_auckland.js

@@ -21,16 +21,13 @@ var crs = new L.Proj.CRS('EPSG:2193',
 
 var	map = new L.Map('map', {
 	crs: crs,
-	continuousWorld: true,
-	worldCopyJump: false
 });
 
 var tileUrl = 'http://maps.aucklandcouncil.govt.nz/ArcGIS/rest/services/Aerials/MapServer/tile/{z}/{y}/{x}',
 	attrib = 'Auckland City Council © 2012',
 	tilelayer = new L.TileLayer(tileUrl, {
 		maxZoom: 12,
 		minZoom: 0,
-		continuousWorld: true,
 		attribution: attrib,
 	});
 

examples/local-projections/style.css

@@ -0,0 +1,10 @@
+html, body {
+  height: 100%;
+  padding: 0;
+  margin: 0;
+}
+
+#map {
+  width: 100%;
+  height: 100%;
+}