Pathfinding¶

PathManager¶

This manager is the entry point for calculated paths and managing them. You can check the public API’s from the Pointr Docs Center.

Path¶

This is the class which defines the calculated Path. It will be returned by PathManager when there is a valid path between the given source and destination. You can check the methods of this class from here.

You will get an instance of this class by either calling pathManager.calculatePath methods, which will calculate a static path between the source and destination, or from the PathSessionListener callback, onPathSessionCalculatedPath which will give a new instance of this class each time the path changes in the current session. If you use the static paths provided by calculatePath methods, you will need to implement a structure to call this method periodically. This may result in unexpected and inaccurate path updates, so it is not the recommended way. The recommended method is using PathSession.

PathfindingMode¶

This is an enum which signifies the mode of the pathfinding done with the Pointr Mobile SDK. It is not persisted through runs, so the implementer should persist it on the client side. It has 3 options; Normal, Easy, Accessible. The default value of it is Normal. The Accessible value for it is for people with special needs (i.e. using a wheelchair), where the Pointr Mobile SDK avoids paths which go through stairs or steps, and only uses paths that go through elevators or ramps. This can be set through the following path manager API: setCurrentMode(newMode: PathfindingMode)

Pointr provides different methods in terms of accessibility to navigate through a facility. These enum types are as below;

• PathfindingMode.Normal : DefaultMode, shortest path available
• PathfindingMode.Easy : Avoids staircases, but doesn’t avoid escalators and may not be the shortest available path but relatively comfortable path for families and elderly.
• PathfindingMode.Accessible : Does not include any steps, thus avoids staircases and also avoids escalators. It is the best path for people using devices that don’t fit in escalators such as wheelchairs, wheeled walkers and wheeled baby carriers.

The PathManager method to set the pathfinding mode is setCurrentMode, which takes in one of the mentioned types. This selection is not persisted across runs. If the implementor wants this preference to be persisted, they need to implement their own logic.

Pointr.getPointr()?.pathManager?.setCurrentMode(PathfindingMode.Easy)

PathSession¶

This is one of the most important classes in this section. It is used when the client wants to start a path session, which they can assign a listener to get dynamic path updates periodically.

After calling the method pathManager.startPathSession(destination: PoiContainer) or pathManager.startPathSession(listOfDestinations: List), you will get an instance of this class. You should then add a PathSessionListener to this object, and get dynamic updates regarding the current path and PathSessionState. This is the recommended method of using Path Management with Pointr Mobile SDK. Please check the code snippet below to see an example implementation of this ;

val pathManager = Pointr.getPointr()?.pathManager

val pathSession = pathManager?.startPathSession(destionationPoiContainer as PoiContainer)
pathSession?.addListener(object : PathSessionListener {
    override fun onPathSessionCalculatedPath(
        pathSession:PathSession,
        calculatedPath: Path
    ) {
        // Do operations with the new calculated path
    }

    override fun onPathSessionUpdateState(
        pathSession: PathSession,
        sessionState: PathSessionState
    ) {
        when (sessionState) {
            PathSessionState.Aborted -> {
                // Do stuff with aborted path
            }
            PathSessionState.Active -> {
                // Do stuff with active path
            }
            PathSessionState.Arrived -> {
                // Do stuff with arrived path
            }
            PathSessionState.Faded -> {
                // Do stuff with faded path
            }
            PathSessionState.Failed -> {
                // Do stuff with failed path
            }
            PathSessionState.Init -> {
                // Do stuff with initial path
            }
        }
    }
})

Path Direction¶

PathDirections are contained within the Path object, indicating the steps that the user needs to take to reach their destination. Currently these have default messages and icons.

Customize the messages or icons¶

Once the client has a valid calculated Path object, they should use the PathDirection class and utilize the directionType: PathDirectionType and nodeType: NodeType fields to generate customized messages and icons for the directions properly. These two fields are enums, their values can be checked from.

The PathDirectionType signifies the direction in a more general way, and NodeType is used to differentiate the specific node type. I.e. PathDirectionType might be “DownwardPortal” and NodeType would signify which type of portal it is, “Lift” or “Stairs” or “Ramp” etc.

Please click here to download the example file “PathDirectionHelperMethods.kt”, to give an idea of how to implement custom direction messages and icons using these fields.

PTRPathManager¶

This manager is the entry point for calculated paths and managing them. You can check the public API’s from the Pointr Docs Center.

PTRPath¶

This is the class which defines the calculated Path. It will be returned by PTRPathManager when there is a valid path between the given source and destination. You can check the methods of this class from here.

You will get an instance of this class by either calling pathManager.calculatePath methods, which will calculate a static path between the source and destination, or from the PTRPathSessionDelegate callback, func onPathSession(_ pathSession: PTRPathSession, calculatedPath path: PTRPath) which will give a new instance of this class each time the path changes in the current session. If you use the static paths provided by calculatePath methods, you will need to implement a structure to call this method periodically. This may result in unexpected and inaccurate path updates, so it is not the recommended way. The recommended method is using PTRPathSession.

PTRPathfindingMode¶

This is an enum which signifies the mode of the pathfinding done with the Pointr Mobile SDK. It is not persisted through runs, so the implementer should persist it on the client side. It has 3 options; Normal, Easy, Accessible. The default value of it is Normal. The Accessible value for it is for people with special needs (i.e. using a wheelchair), where the Pointr Mobile SDK avoids paths which go through stairs or steps, and only uses paths that go through elevators or ramps. This can be set through the following path manager API: func setCurrentMode(_ newMode: PTRPathfindingMode)

Pointr provides a few modes to navigate through a facility that provide the below types of routes while pathfinding:

• PTRPathfindingModeNormal : DefaultMode, shortest path available
• PTRPathfindingModeEasy : Avoids staircases, but doesn’t avoid escalators and may not be the shortest available path but relatively comfortable path for families and elderly.
• PTRPathfindingModeAccessible : Does not include any steps, thus avoids staircases and also avoids escalators. It is the best path for people using devices that don’t fit in escalators such as wheelchairs, wheeled walkers and wheeled baby carriers.

The PTRPathManagerInterface provides a method called setCurrentMode through which the mode of pathfinding can be set to one of the above mentioned types.

Code sample to set path finding mode in iOS:

Pointr.shared.pathManager?.setCurrentMode(.normal)
or
Pointr.shared.pathManager?.setCurrentMode(.easy)
or
Pointr.shared.pathManager?.setCurrentMode(.accessible)

PTRPathSession¶

This is one of the most important classes in this section. It is used when the client wants to start a path session, which they can assign a listener to get dynamic path updates periodically.

After calling the method pathManager.startPathSession(withDestinations: [PTRLocation]), you will get an instance of this class. You should then add a conformance to PTRPathSessionDelegate from your class, and get dynamic updates regarding the current path and PTRPathSessionState. This is the recommended method of using Path Management with Pointr Mobile SDK. Please check the code snippet below to see an example implementation of this

class ExamplePointrStart: UIViewController, PTRPathSessionDelegate {
    override func viewDidLoad() {
        let pathManager = Pointr.shared.pathManager

        let pathSession = pathManager?.startPathSession(withDestinations: [destination])

        pathSession?.addListener(self)
    }

    func onPathSession(_ pathSession: PTRPathSession, calculatedPath path: PTRPath) {
        // Do operations with the new calculated path
    }

    func onPathSession(_ pathSession: PTRPathSession, updatedState state: PTRPathSessionState) {
        switch state {
            case .aborted: // Handle aborted state
                break
            case .active: // Handle active state
                break
            case .arrived: // Handle arrived state
                break
            case .faded: // Handle faded state
                break
            case .failed: // Handle failed state
                break
            case .`init`: // Handle initial state
                break
            default
                break
        }
    }
}

Path Direction¶

PathDirections are contained within the Path object, indicating the steps that the user needs to take to reach their destination. Currently these have default messages and icons.

Customize the messages or icons¶

Once the client has a valid calculated Path object, they should use the PathDirection class and utilize the directionType: PTRPathDirectionType and nodeType: PTRNodeType fields to generate customized messages and icons for the directions properly. These two fields are enums, their values can be checked from.

The PTRPathDirectionType signifies the direction in a more general way, and NodeType is used to differentiate the specific node type. I.e. PathDirectionType might be “DownwardPortal” and PTRNodeType would signify which type of portal it is, “Lift” or “Stairs” or “Ramp” etc.

Please click here to download the example file “PathDirectionHelperMethods.swift”, to give an idea of how to implement custom direction messages and icons using these fields.