Rhodes documentation

documentation/docs/00-getting-started.md

@@ -2,18 +2,22 @@
 
 * [Get a Mapbox API token](01-mapbox-api-token.md)
 * [Check out known issues](02-known-issues.md)
+* [Check out C# API documentation](https://mapbox.github.io/mapbox-unity-sdk/api/index.html)
 
-## Enter API token into MapboxConvenience
-
-paste into inspector ...
-
-## Download `unitypackage`
+## Download Unity Package
 
 * Go to https://www.mapbox.com/unity/
 * Click `Download the SDK`
-* ....
+  * Assets—>Import package—>Custom Package (from the Unity editor menu) 
+
+    **OR**
+
+  * Double-click downloaded `.unityPackage`
 
 ## From Source
 
-* `git clone https://github.com/mapbox/mapbox-sdk-unity.git`
-* ...
+* `git clone https://github.com/mapbox/mapbox-unity-sdk.git`
+
+## Issues
+
+If you run into any issues or have any feedback, please reach out to us at unity-beta@mapbox.com or check for issues in our repo: https://github.com/mapbox/mapbox-unity-sdk/issues.

documentation/docs/01-mapbox-api-token.md

@@ -1,4 +1,13 @@
-A token is required to access Mapbox services.
+**An API token is required to access Mapbox services.**
 
-## Get your's here (it's free): https://www.mapbox.com/studio/signup/
+## Signup
 
+ [Sign up for a free account.](https://www.mapbox.com/studio/signup/)
+
+## Configure API Access in Unity
+
+Copy your token from: https://www.mapbox.com/studio/account/tokens/.
+
+Click Mapbox—>Configure Access from the Unity Editor menu. Paste your token into the `Token` field. Assuming your token is valid, it will save to a text file in `StreamingAssets/MapboxAccess.text`. This file is ignored from the git repo to prevent contributors from accidentally comitting personal tokens. At runtime, the contents of this file will be read and cached for `FileSource` request purposes. See `MapboxAccess.cs` for details.
+
+Now that your access has been configured, check out [the included examples](https://mapbox.github.io/mapbox-unity-sdk/docs/03-examples.html).

documentation/docs/02-known-issues.md

@@ -1,11 +1,40 @@
-# Known Issues
+**Please Note: Current support is limited to Unity 5.4 and above!**
 
-These issues are currently known:
+### Platform Support
 
-## Issue xxxx
+- UWP builds not currently working
+- WebGL builds not showing maps (build successful)
 
-https://github.com/mapbox/mapbox-sdk-unity/issues/XXXX
+### Vector Tile
 
-## Issue yyyy
+- Vector tile overzooming buffer hardcoded (to zero)
+- Buildings are split along tile borders (features duplicated across boundaries)
+- Building parts are not associated with specific buildings (other than spatially)
+- Some complex building data is not rendered correctly (cut out holes, floating pieces, etc.)
 
-https://github.com/mapbox/mapbox-sdk-unity/issues/YYYY
+### Global Elevation Data
+
+- Elevation textures are held in memory (post construction)
+- [Elevation fetching is inefficient](https://github.com/mapbox/mapbox-sdk-cs/issues/18)
+
+- Some tiles have invalid elevation data (`mapbox.terrain-rgb`)
+
+### Directions
+
+- [Cannot cancel direction queries](https://github.com/mapbox/mapbox-sdk-cs/issues/19)
+- DirectionsResource `geometries` property is not implemented
+
+### Traffic
+
+- Traffic visualizer is not offsetting data for both sides of the street
+
+### General
+
+- [Tile requests are not yet threaded](https://github.com/mapbox/mapbox-sdk-cs/issues/46)
+- Progress reporting of map fetching/construction is not yet implemented
+- No support for runtime texture compression (raster tiles)
+- [Texture2D memory leak when destroying tiles](https://github.com/mapbox/mapbox-sdk-cs/issues/31)
+- No support for [custom raster tile format or size](https://www.mapbox.com/api-documentation/#retrieve-tiles)
+- Tile caching is not yet implemented
+- [Request rate exceeded errors not properly reported](https://github.com/mapbox/mapbox-sdk-cs/issues/55)
+- `foreach` is being used extensively (GC cost--this is not an issue in Unity 5.5+)

documentation/docs/03-examples.md

@@ -1,23 +1,127 @@
 # Included Examples
 
-### Drive
+For each example, associated scripts and resources can be found in the same root directory as the scene itself.
 
-### Mesh Generation Basics
+### Playground
 
-### Mesh Genertaion POIs
+These examples demonstrate how to request specific Mapbox data using our C# library.
 
-### Playground
+#### Forward Geocoder
+
+*ForwardGeocoder.unity*
+
+A forward geocoding request will fetch GeoJSON from a place name query. A new request is sent every time the user input field is edited.
+
+Visit [our API documentation](https://www.mapbox.com/api-documentation/#geocoding) for more information.
+
+#### Reverse Geocoder
+
+*ReverseGeocoder.unity*
+
+A reverse geocoding request will fetch GeoJSON from a location query. The location query string must be in the format of `latitude, longitude`. A new request is sent every time the user input field is edited.
+
+Visit [our API documentation](https://www.mapbox.com/api-documentation/#geocoding) for more information.
 
 #### Directions
 
-#### Forward Geocoder
+*Directions.unity*
+
+Enter a start location query (eg. "San Francisco, CA"), this is a forward geocode request.
+
+Enter a destination query (eg. "Los Angeles, CA"), this is also a forward geocode request.
+
+When the geocode requests have been completed, a directions request is executed. A new request is sent every time the start or destination user input fields are edited.
+
+Directions results will be logged to the UI when they are available (in the form of JSON).
 
 #### Raster Tile
 
-#### Reverse Geocoder
+*RasterTile.unity*
+
+Uses a forward geocoder request to fetch a styled raster tile from a Map object. A new request is sent whenever the zoom or style are changed, or when the user input field is edited.
+
+See: https://www.mapbox.com/help/define-style/
+
+See: https://www.mapbox.com/api-documentation/#retrieve-raster-tiles-from-styles
 
 #### Vector Tile
 
+*VectorTile.unity*
+
+Uses a forward geocoder request to fetch GeoJSON from a vector tile. A new request is sent whenever the user input field is edited.
+
+In this example, the result is GeoJSON with a feature collection.
+
+Visit [our API documentation](https://www.mapbox.com/api-documentation/#retrieve-features-from-vector-tiles) for more information.
+
+### Mesh Generation Basics
+
+*MeshGeneration.unity*
+
+This example demonstates the basics of the Mapbox Unity SDK `MapVisualization` framework. Specifically, `TerrainFactory`, `MapImageFactory`, and `MeshFactory` are used together to generate a layered map.
+
+`MapController` acts as the entry point. Here, you can specify the map center (`LatLng`) and range. Range `X`, `Y`, `Z`, `W` corresponds to the number of tiles (`int`) for North, East, South, and West, respectively.
+
+See `TerrainFactory.asset` to customize the base ground mesh. This can either be `Flat` (no elevation), or modified with the [Mapbox Global Elevation Layer](https://www.mapbox.com/blog/terrain-rgb/). The `Resolution` property specifies how vertices each tile's generated plane will have. **Note: this factory is needed if you plan to also use a `MapImageFactory` (for texture application purposes).**
+
+See `MapImageFactory.asset` to customize the raster `MapId` you would like to use. Select `Custom` `Map Type` to use your own Mapbox Studio `Style URL`. 
+
+See `MeshFactory.asset` to see how specific layers are extracted from vector tiles. In this case, we are generating meshes for both `building` and `road`. Therefore, each layer has a `VectorLayerVisualizer` responsible for handling that layer's specific data (such as geometry).
+
+### Mesh Generataion Pois
+
+*PoiGeneration.unity*
+
+With the exception of a `PoiVisualizer ` (`PoiDemoPoiVisualizer`) being added to the `MeshFactory`, this example is identical to `Mesh Generation Basics`.
+
+`PoiDemoPoiVisualizer.asset` allows you to override which prefab to spawn for each `po_label` contained in the vector tile. This prefab should have a component that implements `ILabelVisualizationHelper` attached to it. This exists to inject feature data into (such as label and `Maki` icon).
+
+### Mesh Generation Styles
+
+*StylingDemoMeshGeneration.unity*
+
+This example demonstrates how to use `TypeFilters` to filter specific features for processing. In this case, we have chosen to exclude `schools` from mesh generation. Additionally, you can use `ModifierStacks` to further customize specific features (to color banks differently, for example).
+
+### Drive
+
+*Drive.unity*
+
+This example demonstrates how to utilize [Mapbox Traffic](https://www.mapbox.com/vector-tiles/mapbox-traffic-v1/) and [Mapbox Directions](https://www.mapbox.com/api-documentation/#directions) data within the Mapbox Unity SDK `MapVisualization` framework.
+
+`DirectionsHelper` is responsible for passing `Transform` positions to the `DirectionsFactory`, as waypoints, in the form of `Latitude/Longitude`.  You can use up to 25 waypoints. See `DriveDirectionFactory.asset` to analyze how the generated route is rendered.
+
+Please see `DriveTrafficVisualizer.asset` to analyze how we styled low, moderate, heavy, and severe traffic congestion. Each congestion feature uses a `ModifierStack` to customize its generated appearance (such as height, width, and material/color).
+
+The ground layer was generated with a `flat` `TerrainFactory` and a `MapImageFactory` (for raster tiles) with the Mapbox Dark style applied. 
+
+To understand 3D building generation, please see `Mesh Generation Basics`. One particular difference in this example, however, is the use of a `MergedModifierStack` for `DriveBuildingVisualizer.asset`. This `ModifierStack` is responsible for merging buildings during generation. This optimization reduces the number of transforms and draw calls in the scene, vastly improving the final frame rate.
+
 ### Slippy Vector Terrain
 
+*SlippyDemo.Unity*
+
+This example demonstrates one way to create a [slippy map](http://wiki.openstreetmap.org/wiki/Slippy_Map). The `Slippy` component attached to the `MapController` game object is responsible for requesting new tiles as needed, based on the position of the camera relative to the map. This is achieved using `raycasting` and a dictionary of known (requested and fetched) tiles.
+
+Use W, A, S, D keyboard controls to navigate the map at runtime.
+
+Please see `Mesh Generation Basics` to understand how features are customized. 
+
 ### Voxels
+
+*VoxelWorld.unity*
+
+This Minecraft-inspired example demonstrates a less traditional way to consume Mapbox data for maps or world construction.
+
+`VoxelTile` is responsible for fetching both a styled raster tile and a `mapbox.terrain-rgb` (global elevation) tile. The styled raster pixels are sampled to determine which voxels to generate, via the `VoxelFetcher`. This is achieved using a `nearest color` formula. The elevation tile pixels are sampled to determine where to vertically place the voxels.
+
+`Zoom`: what [zoom level](http://wiki.openstreetmap.org/wiki/Zoom_levels) to request the tiles at.
+
+`Elevation Multiplier`: use to exaggerate the real-world height.
+
+`Voxel Depth Padding`: determine how many voxels to spawn below the designated height. This helps fill holes in environments with extreme elevation variations.
+
+`Tile Width in Voxels`: How many voxels across each tile will generate. This will affect the detail of the world. Raster textures are downsampled according to this value.
+
+`Voxel Batch Count`: How many voxels to spawn at once. Keep this number low to prevent locking the main thread during construction. 
+
+Please read [the blog post](https://www.mapbox.com/blog/how-to-minecraft-unity/) describing how this was made for more information. 

documentation/docs/04-attribution.md

@@ -0,0 +1,7 @@
+## Attribution
+
+All uses of Mapbox’s custom maps and data must attribute both Mapbox and the appropriate data providers. Mapbox’s custom design is copyrighted and our data sources require attribution. This requirement extends to all plan levels.
+
+For your convenience, we have included a prefab called “Attribution.” You must include the the Mapbox wordmark and attribution notice on any map that uses the Mapbox Unity SDK. We provide with the SDK an Attribution prefab that includes all required information. This prefab utilizes UGUI for integration and customization. You may adjust the position of the Mapbox wordmark and attribution notice (pivots and anchors of the rect transform), but they must remain visible on the map. You may also change the background color (transparent by default) of the rect transform and the text color of the text attribution notice to best match your design aesthetics, but all information must be clearly legible. You may not otherwise alter the Mapbox wordmark or text attribution notice. If you wish to otherwise relocate or to remove the Mapbox wordmark, please contact our sales team to discuss options available under our Enterprise plans. Read more on our website: 
+
+https://www.mapbox.com/help/attribution/.

documentation/docs/toc.yml

@@ -10,5 +10,8 @@
 - name: Examples
   href: 03-examples.md
 
+- name: Attribution
+  href: 04-attribution.md  
+
 - name: HoloLens Development
   href: hololens-development.md