{"id":28533761,"url":"https://github.com/esri/geotour-js","last_synced_at":"2025-07-07T20:31:36.463Z","repository":{"id":66035452,"uuid":"65336092","full_name":"Esri/geotour-js","owner":"Esri","description":"A JS component to animate a tour between stops on a map.","archived":false,"fork":false,"pushed_at":"2022-04-25T16:19:36.000Z","size":800,"stargazers_count":43,"open_issues_count":7,"forks_count":16,"subscribers_count":4,"default_branch":"gh-pages","last_synced_at":"2025-06-09T17:09:12.538Z","etag":null,"topics":["3d","animation","arcgis-js-api","arcgis-online","javascript","routing","tour","web-development","web-mapping"],"latest_commit_sha":null,"homepage":"https://esri.github.io/geotour-js/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Esri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-08-09T23:55:19.000Z","updated_at":"2024-09-02T14:31:05.000Z","dependencies_parsed_at":"2024-02-03T08:53:43.854Z","dependency_job_id":"dc9c41bb-be1e-43c8-807f-82858a6d64ef","html_url":"https://github.com/Esri/geotour-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Esri/geotour-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fgeotour-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fgeotour-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fgeotour-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fgeotour-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Esri","download_url":"https://codeload.github.com/Esri/geotour-js/tar.gz/refs/heads/gh-pages","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Esri%2Fgeotour-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264142585,"owners_count":23563526,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","animation","arcgis-js-api","arcgis-online","javascript","routing","tour","web-development","web-mapping"],"created_at":"2025-06-09T17:08:34.956Z","updated_at":"2025-07-07T20:31:36.457Z","avatar_url":"https://github.com/Esri.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GeoTour JS\n\nThis 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`](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-MapView.html) or a 3D [`SceneView`](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html).\n\nSee a live version [here](https://esri.github.io/geotour-js/).\n\nAll it requires is a feature service with integer `Sequence` and string `Name` fields where records are to be visited in ascending `Sequence` order.\n\n![GeoTour](./geotour.gif)\n\n## Features\n\n* Animate a tour between the stops stored in a Feature Layer.\n* Works in 2D or 3D.\n* Configuration via URL parameters.\n* Watchable properties, in line with the 4.0 ArcGIS API for JavaScript.\n\n## Usage\nInclude the component by modifying `dojoConfig` before including the JS API (see the [Advanced](#relative-paths-in-the-dojoconfig) section below for your own deployments).\n\n``` HTML\n\u003cscript type=\"text/javascript\"\u003e\nvar dojoConfig = {\n  packages: [{\n    name: \"geotour\",\n    location: 'https://esri.github.io/geotour-js/src/js'\n  }]\n};\n\u003c/script\u003e\n```\n\nThen 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:\n\n``` JavaScript\nrequire([\n  \"esri/Map\",\n  \"esri/views/MapView\",\n  \"esri/layers/TileLayer\",\n  \"geotour/tour\",\n  \"dojo/domReady!\"\n], function(Map, MapView, TileLayer, Tour) {\n\n  // Create the map.\n  var map = new Map({\n    basemap: {\n      baseLayers: [new TileLayer({\n        url: \"https://services.arcgisonline.com/arcgis/rest/services/Canvas/World_Dark_Gray_Base/MapServer\"\n      })]\n    }\n  });\n\n  // And the view.\n  var view = new MapView({\n    container: \"viewDiv\",\n    map: map,\n    center: [-100.68, 45.52], // lon, lat\n    zoom: 4\n  });\n\n  // Start a tour\n  var tour = new Tour({\n    view: view, \n    autoStart: true\n  });\n});\n```\n\n### Constructor\nThe 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:\n\n``` JavaScript\n  var tour = new Tour(view);\n```\n\nAlternatively, you can pass in a JSON object to configure the Tour. In this case the animation is started automatically as soon as possible:\n\n``` JavaScript\n  // Start as soon as the view has loaded.\n  var tour = new Tour({\n    view: view, \n    autoStart: true\n  });\n```\n\nSee the [Configuration Parameters](#configuration-parameters) section for more info.\n\n### Animating the tour\nBy 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).\n\n``` JavaScript\n  var tour = new Tour(view);\n\n  tour.watch(\"ready\", function () {\n    view.goTo(tour.extent).then(function () {\n      tour.animate();\n    });\n  });\n```\n\n### Tour properties\nA `Tour` instance has the following [watchable](https://developers.arcgis.com/javascript/latest/guide/working-with-props/index.html) properties:\n\n| Property | Description |\n| -------- | ----------- |\n| ready | `true` when enough data has been loaded to start the tour. Initially `false`. |\n| extent | An [`Extent`](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Extent.html) object describing the bounds of the tour. Will be populated by the time the tour is `ready`. |\n| loadError | Will be `undefined` unless an error is encountered loading the tour data. |\n\n### Tour methods\nA `Tour` instance has the following methods:\n\n| Method | Description |\n| ------ | ----------- |\n| `animate()` | Starts the tour animation and returns a [promise](https://developers.arcgis.com/javascript/latest/guide/working-with-promises/index.html) that is fulfilled when the animation ends. Call `cancel()` on this promise to abort the animation. |\n| `animateWithDelay()` | Same as `animate()` but the first parameter is a delay in milliseconds before the animation begins. |\n| `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. |\n\n### Configuration Parameters\n\nParameters can be passed into the tour constructor in a JSON object. The following parameters are supported:\n\n| Parameter           | Value | Default |\n| ------------------- | ----- | ------- |\n| `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` |\n| `autoStart` | Whether to start the tour automatically once the `MapView` or `SceneView` is ready. | `false` |\n| `autoStartDelay` | The delay in milliseconds before autostarting. Ignored if `autoStart` is not `true`. Default `0` (no delay). | `0` |\n| `duration` | Override the target duration of the entire animation in seconds. | `30` |\n| `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` |\n| `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](#for-use-with-routeresultserviceurl-parameter) below for more details. If the parameter is not provided, a demo service is used. | [Default Demo](https://services.arcgis.com/OfH668nDRN7tbJh0/arcgis/rest/services/Connected_States_Service/FeatureServer) |\n| `stopLayerURL`    | The URL to a public Feature Service Layer containing points to tour between. See [Creating Data](#for-use-with-stoplayerurl-parameter). |\n| `stopNameField`     | Override the field to use for reading the point's name to display on the map. | `Name` |\n| `stopSequenceField` | Override the field to use for reading the point's sequence in the tour. | `Sequence` |\n\nThe 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.\n\nThe following settings may also be provided to the API constructor only:\n\n| Parameter           | Value | Default |\n| ------------------- | ----- | ------- |\n| `tourSymbol` | A [SimpleLineSymbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-SimpleLineSymbol.html) to be used for the tour line. | 3pt Red Line. |\n| `stopSymbol` | A [MarkerSymbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-MarkerSymbol.html) subclass to be used for the tour stops. | 10px semi-transparent circle. |\n| `tourSymbol` | A [TextSymbol](https://developers.arcgis.com/javascript/latest/api-reference/esri-symbols-TextSymbol.html) to be used for the tour stop labels. | White 12pt sans-serif light. |\n| `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. |\n\nAll 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.\n\n## Samples\nTake a look at the following samples to see what GeoTour-JS can do for you:\n\n* 2D Sample with UI control (the UI is hidden while the animation progresses) [here](https://esri.github.io/geotour-js/samples/index2d.html) ([great circle version](https://esri.github.io/geotour-js/samples/index2d.html?forceGreatCircleArcs=true)).\n* 3D Sample with UI control [here](https://esri.github.io/geotour-js/samples/index3d.html) ([great circle version](https://esri.github.io/geotour-js/samples/index3d.html?forceGreatCircleArcs=true)).\n* Minimal 2D sample with property watching [here](https://esri.github.io/geotour-js/samples/simple.html) ([great circle version](https://esri.github.io/geotour-js/samples/simple.html?forceGreatCircleArcs=true)).\n* Minimal 2D auto-starting sample [here](https://esri.github.io/geotour-js/samples/simple-autostart.html) ([great circle version](https://esri.github.io/geotour-js/samples/simple-autostart.html?forceGreatCircleArcs=true)).\n* Custom WebMap with custom label symbology and `routeResultLayerURL` parameter [here](https://esri.github.io/geotour-js/samples/webmap-autostart.html) ([great circle version](https://esri.github.io/geotour-js/samples/webmap-autostart.html?forceGreatCircleArcs=true)).\n\n## Creating data\n### For use with stopLayerURL parameter\nThere 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:\n\n* Has Point Geometry.\n* Has a `Name` field to display on the map.\n* Has a `Sequence` field to determine the order the tour visits the points.\n* Is shared with everyone (i.e. public).\n\nHere are some ways to create a suitable stop service:\n\n* [Create a new Point Feature Layer](https://developers.arcgis.com/layers/#/new/) with `Name` and `Sequence` fields at [developers.arcgis.com](https://developers.arcgis.com) and add data in ArcGIS Online (use your existing ArcGIS Online account or a free Developer Account).\n* 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](https://doc.arcgis.com/en/arcgis-online/reference/csv-gpx.htm#GUID-4EDCE12E-285E-41D0-A3B8-1BAB4B111922), this is free. Geocoding locations will consume credits.\n* [Create an empty Feature Layer](https://doc.arcgis.com/en/arcgis-online/share-maps/publish-features.htm#ESRI_SECTION1_809F1266856546EF9E6D2CEF3816FD7D) from an [existing service URL](https://services.arcgis.com/OfH668nDRN7tbJh0/arcgis/rest/services/GlobalTourDemo1/FeatureServer/0) and populate the data in ArcGIS Online.\n* Publish a layer to ArcGIS Online from ArcGIS Desktop.\n\n### For use with routeResultServiceURL parameter\n\nUsing 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.\n\nFollow these steps (this will consume credits to generate the route and store the resulting service).\n\n1. 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](http://doc.arcgis.com/en/arcgis-online/get-started/get-directions.htm))).\n2. Click the **Save** icon to save the result (you can give it a name and choose a folder).\n3. 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\n4. Share the `Route layer (hosted)` item with `Everyone`.\n5. 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.\n\n## Relative Paths in the dojoConfig\nThe [Usage](#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:\n\n``` HTML\n\u003cscript type=\"text/javascript\"\u003e\n// The location.pathname.substring() logic below may look confusing but all its doing is\n// enabling us to load the api from a CDN and load local modules from the correct location.\nvar package_path = window.location.pathname.substring(0, window.location.pathname.lastIndexOf('/'));\nvar dojoConfig = {\n  packages: [{\n    name: \"geotour\",\n    location: package_path + '/src/js'\n  }]\n};\n\u003c/script\u003e\n```\n\n## Requirements\n\n* [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/)\n\n## Resources\n\n* [ArcGIS Online Directions](http://doc.arcgis.com/en/arcgis-online/get-started/get-directions.htm)\n\n## Issues\n\nFind a bug or want to request a new feature? Please let us know by submitting an issue.  Thank you!\n\n## Contributing\n\nAnyone and everyone is welcome to contribute. Please see our [guidelines for contributing](https://github.com/esri/contributing).\n\n## Licensing\nCopyright 2016 Esri\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\nA copy of the license is available in the repository's [license.txt](https://github.com/Esri/calcite-maps/blob/master/license.txt) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesri%2Fgeotour-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesri%2Fgeotour-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesri%2Fgeotour-js/lists"}