added map docs (#1850)

_docs/map-node.md

@@ -6,10 +6,141 @@ prevPage: multiplex-image-node.html
 nextPage: video-node.html
 ---
 
-`ASMapNode` offers completely asynchronous preparation, automatic preloading, and efficient memory handling. Its standard mode is a fully asynchronous snapshot, with liveMap mode loading automatically triggered by any `ASTableView` or `ASCollectionView`; its `.liveMap` mode can be flipped on with ease (even on a background thread) to provide a cached, fully interactive map when necessary. 
+`ASMapNode` allows you to easily specify a geographic region to show to your users.  
+
+### Basic Usage
+
+Let's say you'd like to show a snapshot of San Francisco.  All you need are the coordinates.
+
+<div class = "highlight-group">
+<span class="language-toggle"><a data-lang="swift" class="swiftButton">Swift</a><a data-lang="objective-c" class = "active objcButton">Objective-C</a></span>
+
+<div class = "code">
+<pre lang="objc" class="objcCode">
+ASMapNode *mapNode = [[ASMapNode alloc] init];
+mapNode.preferredFrameSize = CGSizeMake(300.0, 300.0);
+
+// San Francisco
+CLLocationCoordinate2D coord = CLLocationCoordinate2DMake(37.7749, -122.4194);
+
+// show 20,000 square meters
+mapNode.region = MKCoordinateRegionMakeWithDistance(coord, 20000, 20000);
+</pre>
+
+<pre lang="swift" class = "swiftCode hidden">
+let mapNode = ASMapNode()
+mapNode.preferredFrameSize = CGSize(width: 300.0, height: 300.0)
+
+// San Francisco
+let coord = CLLocationCoordinate2DMake(37.7749, -122.4194)
+
+// show 20,000 square meters
+mapNode.region = MKCoordinateRegionMakeWithDistance(coord, 20000, 20000)
+</pre>
+</div>
+</div>
+
+<img width = "300" src = "/static/basicMap.png"/>
+
+The region value is actually just one piece of a property called `options` of type `MKMapSnapshotOptions`.
+
+
+### MKMapSnapshotOptions
+
+A map node's main components can be defined directly through its `options` property.  The snapshot options object contains the following:
+
+<ul>
+	<li>An <strong>MKMapCamera</strong>: used to configure altitude and pitch of the camera</li>
+	<li>An <strong>MKMapRect</strong>: basically a CGRect</li>
+	<li>An <strong>MKMapRegion</strong>: Controls the coordinate of focus, and the size around that focus to show</li>
+	<li>An <strong>MKMapType</strong>: Can be set to Standard, Satellite, etc.</li>
+</ul>
+
+To do something like changing your map to a satellite map, you just need to create an options object and set its properties accordingly.
+
+<div class = "highlight-group">
+<span class="language-toggle"><a data-lang="swift" class="swiftButton">Swift</a><a data-lang="objective-c" class = "active objcButton">Objective-C</a></span>
+
+<div class = "code">
+<pre lang="objc" class="objcCode">
+MKMapSnapshotOptions *options = [[MKMapSnapshotOptions alloc] init];
+options.mapType = MKMapTypeSatellite;
+options.region = MKCoordinateRegionMakeWithDistance(coord, 20000, 20000);
+
+mapNode.options = options;
+</pre>
+<pre lang="swift" class = "swiftCode hidden">
+let options = MKMapSnapshotOptions()
+options.mapType = .Satellite
+options.region = MKCoordinateRegionMakeWithDistance(coord, 20000, 20000)
+
+mapNode.options = options
+</pre>
+</div>
+</div>
+
+Results in:
+
+<img width = "300" src = "/static/satelliteMap.png"/>
+
+One thing to note is that setting the options value will overwrite a previously set region.
+
+### Annotations
+
+To set annotations, all you need to do is assign an array of annotations to your mapNode.
+
+Say you want to show a pin directly in the middle of your map of San Francisco.
+
+<div class = "highlight-group">
+<span class="language-toggle"><a data-lang="swift" class="swiftButton">Swift</a><a data-lang="objective-c" class = "active objcButton">Objective-C</a></span>
+
+<div class = "code">
+<pre lang="objc" class="objcCode">
+MKPointAnnotation *annotation = [[MKPointAnnotation alloc] init];
+annotation.coordinate = CLLocationCoordinate2DMake(37.7749, -122.4194);
+
+mapNode.annotations = @[annotation];
+</pre>
+<pre lang="swift" class = "swiftCode hidden">
+let annotation = MKPointAnnotation()
+annotation.coordinate = CLLocationCoordinate2DMake(37.7749, -122.4194)
+
+mapNode.annotations = [annotation]
+</pre>
+</div>
+</div>
+
+<img width = "300" src = "/static/mapWithAnnotation.png"/>
+
+No problem.
+
+### Live Map Mode
+
+Chaning your map node from a static view of some region, into a fully interactable cartographic playground is as easy as:
+
+<div class = "highlight-group">
+<span class="language-toggle"><a data-lang="swift" class="swiftButton">Swift</a><a data-lang="objective-c" class = "active objcButton">Objective-C</a></span>
+
+<div class = "code">
+<pre lang="objc" class="objcCode">
+mapNode.liveMap = YES;
+</pre>
+<pre lang="swift" class = "swiftCode hidden">
+mapNode.liveMap = true
+</pre>
+</div>
+</div>
+
+This enables "live map mode" in which the node will use an <a href = "https://developer.apple.com/library/mac/documentation/MapKit/Reference/MKMapView_Class/">MKMapView</a> to render an interactive version of your map.
+
+<img width = "300" src = "/static/liveMap.gif"/>
+
+As with UIKit views, the MKMapView used in live map mode is not thread-safe.
+
+### MKMapView Delegate
+
+If live map mode has been enabled and you need to react to any events associated with the map node, you can set the `mapDelegate` property.  This delegate should conform to the <a href = "https://developer.apple.com/library/ios/documentation/MapKit/Reference/MKMapViewDelegate_Protocol/index.html">MKMapViewDelegate</a> protocol.
+
+
 
-Features:
-- uses `MKMapSnapshotOptions` as its primary specification format for map details. Among other things, this allows specifying 3D camera angles for snapshots loaded automatically and asynchronously while scrolling, with seamless transitions to an interactive map.
 
-Gotchas:
-- the liveMap mode is backed by a MKMapView which is NOT thread-safe