Routing

Routing is done using Trimble Maps data specifically designed for commercial vehicles. This data includes bridge heights and clearances, load limits, weight limits and allowances, one-way road designations, left-hand and dangerous turn restrictions, urban road classifications, as well as hazmat, truck-restricted, truck-designated and truck-prohibited roads.

Routing Layer

The first step in generating routes is to add a routing layer to your map. The routing layer will be responsible for both retrieving and drawing the routes based on the stops and properties you define.

var routingLayer = new ALKMaps.Layer.Routing("Route Layer");
myMap.addLayer(routingLayer);

Add Route

Once you have a routing layer added to your map, the next step is to add routes. To generate a route you will need at least two stops (an origin and a destination).

The addRoute method of the routing layer takes up to four parameters for creating a route: stops, functionOptions, routeOptions, and reportOptions.

Please note that the addRoute callback will return stops as an array of ALKMaps.Geometry.Point objects, and the coordinates will be in meters if your map is in Spherical Mercator. Previously the format of stops array in the return object was [[lon,lat],[lon,lat],...], and the coordinates were always in degrees regardless of map projection.

You also have the ability to transform entire arrays of ALKMaps.LonLat or ALKMaps.Geometry.Point objects to another projection. This can be done by passing an array followed by the source and destination projections to either the ALKMaps.LonLat.transformArray or ALKMaps.Geometry.Point.transformArray functions.

Stops

The stops parameter of the addRoute method should contain an array of ALKMaps.LonLat objects representing the stops of the route.

Function Options

The functionOptions parameter contains options related to the functionality of the route.

Route Options

The routeOptions parameter contains options related to the generation of the route and optional reports.

Report Options

Remove Route

You can remove individual routes in a particular routing layer by calling the removeRoute method with the routeId of the route you would like to remove.

routingLayer.removeRoute("myRoute");

Set Route Visibility

You can set the visibility of individual routes in a particular routing layer by calling the setRouteVisibility method with the routeId of the route as the first parameter and a boolean indicating whether or not the route should be visible as the second. True indicates that the route should be shown, and false indicates that the route should be hidden.

routingLayer.setRouteVisibility("myRoute", false); //hides the route

Interactive Routes

By default, routes are static. The route will be drawn on the map and the stops will be indicated by the appropriate markers. If you would like to your users to interact with the routes by moving the location of a stop or dragging the routes, you just need to set the isDraggable property of the routing layer in the constructor to true.

var routingLayer = new ALKMaps.Layer.Routing("Route Layer", {
  isDraggable: true
});
myMap.addLayer(routingLayer);

The interactivity of a routing layer can also be set dynamically by calling the setDraggable method on an existing routing layer.

routingLayer.setDraggable(false);

Once the user has moved around the stops, you may want to retrieve the new location of the stops, as well as any new stops that may have been created while dragging. The get this information you will need to use the getRouteElements method on the routing layer. This method take the routeId of the route.

var routeElements = routingLayer.getRouteElements("PhiladelphiaToAtlanticCity");

var numberOfStops = routeElements.stops.length;

for (var i = 0; i < numberOfStops; i++) {
  console.log("Stop " + i);
  console.log("Lon: " + routeElements.stops[i].geometry.x);
  console.log("Lat: " + routeElements.stops[i].geometry.y);
}

Route Handles

The route handles (icons displayed at the origin, destination, and waypoints) can be shown/hidden or changed.

Visibility

The visibility of route handles can be set when the route is added via the showHandles option in the functionOptions of the addRoute call.

routingLayer.addRoute({
...
    functionOptions:{
      routeId: "PhiladelphiaToAtlanticCity",
      showHandles: false
    },
    ...
});

The visibility can also be changed after the route has been created via a call to the setRouteHandleVisibility on the routing layer. The function takes the routeId and a boolean value indicating the visibility as parameters.

routingLayer.setRouteHandleVisibility("PhiladelphiaToAtlanticCity", false);

Graphics

In addition to being hidden, the route handle graphics can be changed via the setRouteHandle function on the routing layer or by using the externalImages parameter of addRoute. Changes to the route handle graphics only affect handles that are currently part of the route. Handles added after the graphic change will need to be set after they are added.

routingLayer.setRouteHandle("MyRoute", "O", {
  externalGraphic: "https://maps.alk.com/api/1.2/img/fav.png"
});

The only field of the externalImages object is images, an array of image locations that at each index matches up to the corresponding element of the stops array. To use the ALKMaps default image for only certain handles, simply place null at that index of the images array.

routingLayer.addRoute({
  stops: ALKMaps.LonLat.transformArray([
    new ALKMaps.LonLat(-75.173297, 39.942892),
    new ALKMaps.LonLat(-74.83153, 39.61703),
    new ALKMaps.LonLat(-74.83153, 39.45703),
    new ALKMaps.LonLat(-74.438942, 39.362469)
    ], new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject()),
    externalImages:
    {
      images: [ALKMaps.IMAGE.TRUCK_BLUE, ALKMaps.IMAGE.FAVORITE, null, ALKMaps.IMAGE.TRUCK_GREEN]
    },
  ...

});

SVG

You now have the ability to specify custom SVG content to render your route handles using the handleSvg property of the functionOptions parameter of addRoute. The available properties of the handleSvg object are explained in the table below.

Route Colors

Different route colors are generated by the toolkit for each new route created. If you would like to specify a particular color for a route, you can pass in the color as a style object when the route is created.

routingLayer.addRoute({
  ...
  functionOptions:{
    routeId: "PhiladelphiaToAtlanticCity",
    style: {
      strokeOpacity: 0.9,
      strokeColor: "#0000FF"
    }
  },
  ...
});

Route Arrows

You now have ability to either have arrows spaced evenly along your route, or have a single arrow placed at the end of your route. These arrows are customizable in terms of style, spacing, and size. Everything is done through the style parameter inside the functionOptions of the addRoute function call. The settings/options are laid out in the table below.

Arrows Along Route

The following piece of sample code demonstrates a route with arrows spaced at 50 pixels and sized at “100%”.

Arrow at End of Route

The following piece of sample code demonstrates a route with a single arrow at the end of the route sized at “250%”.