GeoTour JS

This component takes a feature service of stops and animates great circle lines between them using the 4.0 ArcGIS API for JavaScript in either a 2D MapView or a 3D SceneView.

See a live version here.

All it requires is a feature service with integer Sequence and string Name fields where records are to be visited in ascending Sequence order.

Features

• Animate a tour between the stops stored in a Feature Layer.
• Works in 2D or 3D.
• Configuration via URL parameters.
• Watchable properties, in line with the 4.0 ArcGIS API for JavaScript.

Usage

Include the component by modifying dojoConfig before including the JS API (see the Advanced section below for your own deployments).

<script type="text/javascript">
var dojoConfig = {
  packages: [{
    name: "geotour",
    location: 'https://esri.github.io/geotour-js/src/js'
  }]
};
</script>

Then create a tour instance, passing the MapView or SceneView to use for display. The instance will read properties from the URL's QueryString, loading features and parsing out arcs to animate through. The following code loads the default demo data and automatically starts the tour animation:

require([
  "esri/Map",
  "esri/views/MapView",
  "esri/layers/TileLayer",
  "geotour/tour",
  "dojo/domReady!"
], function(Map, MapView, TileLayer, Tour) {

  // Create the map.
  var map = new Map({
    basemap: {
      baseLayers: [new TileLayer({
        url: "https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Dark_Gray_Base/MapServer"
      })]
    }
  });

  // And the view.
  var view = new MapView({
    container: "viewDiv",
    map: map,
    center: [-100.68, 45.52], // lon, lat
    zoom: 4
  });

  // Start a tour
  var tour = new Tour({
    view: view, 
    autoStart: true
  });
});

Constructor

The constructor requires at least one parameter, the MapView or SceneView to animate the tour in. By default, the tour will load its data but will wait to be manually started:

  var tour = new Tour(view);

Alternatively, you can pass in a JSON object to configure the Tour. In this case the animation is started automatically as soon as possible:

  // Start as soon as the view has loaded.
  var tour = new Tour({
    view: view, 
    autoStart: true
  });

See the Configuration Parameters section for more info.

Animating the tour

By default, the tour will not start automatically (see the constructors above). You should wait until the tour is ready (that is, it has loaded all its data and is ready to start).

  var tour = new Tour(view);

  tour.watch("ready", function () {
    view.goTo(tour.extent).then(function () {
      tour.animate();
    });
  });

Tour properties

A Tour instance has the following watchable properties:

Property	Description
ready	true when enough data has been loaded to start the tour. Initially false.
extent	An Extent object describing the bounds of the tour. Will be populated by the time the tour is ready.
loadError	Will be undefined unless an error is encountered loading the tour data.

Tour methods

A Tour instance has the following methods:

Method	Description
animate()	Starts the tour animation and returns a promise that is fulfilled when the animation ends. Call cancel() on this promise to abort the animation.
animateWithDelay()	Same as animate() but the first parameter is a delay in milliseconds before the animation begins.
clearDisplay()	When you start an animation, any graphics from a previous display of the tour are cleared. This function is useful if you need to clear the display without starting a new animation.

Configuration Parameters

Parameters can be passed into the tour constructor in a JSON object. The following parameters are supported:

Parameter	Value	Default
allowURLParameters	Set this to false to prevent configuration being read from the URL. It can also be set to an array to whitelist only specific properties (e.g. ["duration", "autoStartDelay"]). Defaults to true to allow all properties to be specified in the URL.	true
autoStart	Whether to start the tour automatically once the MapView or SceneView is ready.	false
autoStartDelay	The delay in milliseconds before autostarting. Ignored if autoStart is not true. Default 0 (no delay).	0
duration	Override the target duration of the entire animation in seconds.	30
forceGreatCircleArcs	Any non-false value (but why not use true) will force Great Circle lines to be drawn between stops in the case where detailed polylines are provided through the default demo or with routeResultServiceURL.	false
routeResultServiceURL	A URL to a service created from an ArcGIS Online Directions calculation. If this is provided, stopLayerURL, stopNameField and stopSequenceField are ignored. See Creating a route service below for more details. If the parameter is not provided, a demo service is used.	Default Demo
stopLayerURL	The URL to a public Feature Service Layer containing points to tour between. See Creating Data.
stopNameField	Override the field to use for reading the point's name to display on the map.	Name
stopSequenceField	Override the field to use for reading the point's sequence in the tour.	Sequence

The above parameters may also be read from the URL's Query String. Parameters passed to the URL will override parameters passed to the API constructor. To prevent the URL parameters overriding the constructor parameters, use allowURLParameters in the constructor.

The following settings may also be provided to the API constructor only:

Parameter	Value	Default
tourSymbol	A SimpleLineSymbol to be used for the tour line.	3pt Red Line.
stopSymbol	A MarkerSymbol subclass to be used for the tour stops.	10px semi-transparent circle.
tourSymbol	A TextSymbol to be used for the tour stop labels.	White 12pt sans-serif light.
labelPositions	A JSON object with offsetBelow, leftAlign and rightAlign arrays. Each array contains the stop sequences (starting at 1) of items that should be affected by the array. For example, to ensure that the 1st, 5th and 7th labels are all right aligned and the 4th and 5th appear below the stop, use labelPositions: { offsetBelow: [4,5], rightAlign: [1,5,7] }.	Labels are horizontally centered above the stop.

All parameters are optional. If no parameters are provided, a demo dataset with a detailed real-world route is used (see the routeResultServiceURL parameter). If a stopLayerURL is provided instead, the component will generate Great Circle Arcs between the stops.

Samples

Take a look at the following samples to see what GeoTour-JS can do for you:

• 2D Sample with UI control (the UI is hidden while the animation progresses) here (great circle version).
• 3D Sample with UI control here (great circle version).
• Minimal 2D sample with property watching here (great circle version).
• Minimal 2D auto-starting sample here (great circle version).
• Custom WebMap with custom label symbology and routeResultLayerURL parameter here (great circle version).

Creating data

For use with stopLayerURL parameter

There are many ways to create a Stop Service that you can pass to stopLayerURL. The key is to create a Feature Service Layer that meets the following criteria:

• Has Point Geometry.
• Has a Name field to display on the map.
• Has a Sequence field to determine the order the tour visits the points.
• Is shared with everyone (i.e. public).

Here are some ways to create a suitable stop service:

• Create a new Point Feature Layer with Name and Sequence fields at developers.arcgis.com and add data in ArcGIS Online (use your existing ArcGIS Online account or a free Developer Account).
• Upload a CSV file to ArcGIS Online. Be sure to include a Name and Sequence column and populate them appropriately. If the rows in the file have suitable lat/lon or x/y fields, this is free. Geocoding locations will consume credits.
• Create an empty Feature Layer from an existing service URL and populate the data in ArcGIS Online.
• Publish a layer to ArcGIS Online from ArcGIS Desktop.

For use with routeResultServiceURL parameter

Using the ArcGIS Online Map Viewer, you can create a Route Service that represents a set of directions between a sequence of points to use with the routeResultServiceURL parameter.

Follow these steps (this will consume credits to generate the route and store the resulting service).

1. Calculate directions in the ArcGIS Map Viewer (if you have a Feature Service with up to 50 points, you can use that (see the Tip at 3.c here)).
2. Click the Save icon to save the result (you can give it a name and choose a folder).
3. Browse to the saved route's Portal Item page (there is a shortcut SHARE THE ROUTE link in the Directions panel once the route has been saved), and Publish it. This will create a new Route layer (hosted) item
4. Share the Route layer (hosted) item with Everyone.
5. Copy the Route layer (hosted) item's URL property from the right hand side of the Portal Item page. You can use this URL as the value for the routeResultServiceURL url parameter.

Relative Paths in the dojoConfig

The Usage section above shows a fixed location for the component. But since it's not recommended to rely on GitHub as a CDN like this, the following code sets up dojo to load the component relative to the HTML file:

<script type="text/javascript">
// The location.pathname.substring() logic below may look confusing but all its doing is
// enabling us to load the api from a CDN and load local modules from the correct location.
var package_path = window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/'));
var dojoConfig = {
  packages: [{
    name: "geotour",
    location: package_path + '/src/js'
  }]
};
</script>

Requirements

• ArcGIS API for JavaScript

Resources

• ArcGIS Online Directions

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue. Thank you!

Contributing

Anyone and everyone is welcome to contribute. Please see our guidelines for contributing.

Licensing

Copyright 2016 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.