Separate Markers and Waypoints

[jchudge]

Based on feedback from PC - this would be helpful to those users who have created a large number of Markers to manage them more effectively.

Allow the user to filter the Markers by alpha, data (recency), and location

[MBtheOtaku]

I can look into this. How would you propose we could do this fix and what files would have to be modified?

[steinbro]

This feature might need a little more fleshing out. Internally, I don't believe the code makes any distinction between markers and waypoints; they are all just saved points in the database. A waypoint is just a marker that happens to be used in a route. When you add a new waypoint to a route that wasn't previously saved, a new marker is created.

So, when we talk about separating markers and waypoints, are we saying we want a list of saved points that are not in routes, and a list of saved points that are? If a user first creates a marker and later adds it to a route, should it disappear from the markers list, or should be considered both a marker and a waypoint? I'm not sure the latter behavior is possible at present, since it would require tracking knowledge of how a saved point was originally created.

[jchudge]

The way it was described by PC was for the waypoints to be separate from the markers - because he found the announcement of waypoints on an approach to his destination to be unnecessary and negatively impacting the experience because PC only wants to hear the required selected information. This has led to PC deleting a number of waypoints that were supporting local personal walking routes.

[JJGatchalian]

I'm trying to understand this. So you're saying that PC wants the waypoints separate from the markers because he doesn't want to hear the marker's information on every waypoint, slowing his experience down. Based on that explanation, I'm under the impression that the final version should look like this. The waypoints created from existing markers should still be part of the markers list; however, the waypoints created on the fly from unmarked places should only appear in each specific route when editing or creating the route. That way those waypoints don't clutter the markers list. Also, the user will only hear the beacon and distance to each waypoint without saying the marker's info unless the waypoint is in the markers list. Then if the user chooses to delete waypoints from a route, those waypoints, whether from an existing marker or created on the fly, should not affect the markers list since it's now a separate issue. That means that the reverse would be true also. The user should be able to delete a marker from the markers list, and it wouldn't affect the waypoint from the route at the same location either. Or if a user wants to save a waypoint as a marker, they could go to the Waypoint Details screen and press Save As Marker. There might be more issues to deal with, but this is just my rough concept. If my understanding is correct, I don't believe that this change should affect the help documentation for routes. Please correct me if I'm wrong. Thanks.

[jchudge]

@JJGatchalian @MBtheOtaku @steinbro @wdturner

We discussed this in some detail at our weekly meeting today and I'll summarise as follows (@steinbro please correct anything amiss!)

• This would need to consider both the impact on the audio experience, but also how to provide better list management of the waypoints and markers
• We appreciate the terminology can be a little confusing between them so clearer definitions of them would be helpful!
• @MBtheOtaku a good first starting point would be to see if you can define, and document, the underlying data model for Markers (and from that, make suggestions or recommendations on how the current experience could be improved - including the impact on the UI and behaviour of the audio callouts
• @JJGatchalian I like your suggestion above because it makes it very route-centric which was the intention behind their original design :-)
• @MBtheOtaku let us know what you think...

[MBtheOtaku]

I'm currently trying to make sense of what exactly this issue wants as well but I will spend a couple days really trying to formulate and see if I can define the datal model for the Markers. Do we know which parts of the code exactly handles the waypoints and markers?

[JJGatchalian]

If we decide to use my suggestion, we can just make sure that the waypoints for each individual route do not conflict with markers. Sorting the streamlined markers list by recency could be omitted altogether because it may not apply. We just have to make sure that waypoints created on the fly within the creation of routes don't show up in the markers list, and any marker or waypoint shouldn't delete the other counterpart if they share the same location.

[jchudge]

I'm currently trying to make sense of what exactly this issue wants as well but I will spend a couple days really trying to formulate and see if I can define the datal model for the Markers. Do we know which parts of the code exactly handles the waypoints and markers?

@MBtheOtaku I'm not sure about which parts of the code to look at here...but would be worthwhile to trawl through it and highlight the relevant areas...which will come in very handy for work later on :-)

[steinbro]

@MBtheOtaku I would start with:

soundscape/apps/ios/GuideDogs/Code/Data/Models/Database Models/Routes/RouteWaypoint.swift

Lines 12 to 19 in ed2a339

	/*
	Represents the waypoints belonging to a route.
	Each waypoint in the `Route` object is represented by
	an existing `ReferenceEntity` (e.g., `markerId`) and an
	index that reflects the waypoint's ordering within the
	route.
	*/

soundscape/apps/ios/GuideDogs/Code/Data/Models/Database Models/ReferenceEntity.swift

Lines 26 to 47 in ed2a339

	class ReferenceEntity: Object, ObjectKeyIdentifiable {
	// MARK: Constants
	struct Keys {
	static let entityId = "GDAReferenceEntityID"
	}
	// MARK: Properties
	@Persisted(primaryKey: true) var id: String = UUID().uuidString // Primary key
	@Persisted var entityKey: String?
	@Persisted var lastUpdatedDate: Date?
	@Persisted var lastSelectedDate: Date? = Date()
	@Persisted var isNew: Bool = true
	@Persisted var isTemp: Bool = true
	@Persisted var latitude: CLLocationDegrees = 0.0
	@Persisted var longitude: CLLocationDegrees = 0.0
	@Persisted var nickname: String?
	@Persisted var estimatedAddress: String?
	@Persisted var annotation: String?

What might be confusing is that the terminology used in the code doesn't match the language shown to the user. For example, the UI makes no mention of a "reference entity" but a "marker" might be just the user-friendly name for the same thing. We want some confirmation of that data model, ideally as some new documentation in the docs folder..

Once we understand the data model, we can then determine how to distinguish markers that are meaningful locations versus just points that were saved as breadcrumbs for a route. And after that, we can determine what changes to the UI and audio callouts we should make in order to cut down on the clutter from insignificant waypoints.

[JJGatchalian]

This is just a thought. The term "Reference Entity" probably could have been a holdover from the early days of Microsoft Soundscape when the UI used to refer to "markers" as "reference points." Then around 2020, the term was changed to "markers" in the UI, but the developers may have left the old terminology alone in the code.

[MBtheOtaku]

I have added a txt file and created a pull request for this issue. Any feedback would be good and let me know if we want to dive into more detail for any section if we think I missed something. Otherwise we can move on to the next phase of brainstorming how we could fix this issue. I have been pondering a potential fix but would like to bring it up after the document has been analyzed.

[JJGatchalian]

I checked the documentation, and just to clarify, I believe that the two types of waypoints, those linked to markers or those created on the fly, should behave the same way. It wouldn't matter whether or not the waypoint shares the location of a linked marker. That means that if the user deletes the marker at the same location as a waypoint, the leftover waypoint should behave the same way as a waypoint created on the fly without using an existing marker in the first place.