Improve GPX compatibility with Osmand

[vabene1111]

First of all I absolutely love facilmap! I have been search for years for a good vacation planning tool and feel like I have finally found what I was looking for.

Now that I have planned a big trip using facilmap I would love to be able to use all the data I have build offline.

I already played around with multiple android apps that are able to import the GPX files but none of them work as well as facilmap does directly (colors, icons, shapes, tracks get los or scrambled, the legend to hide/show categories is missing, ...)

Are there any tricks I can use or any plans to implement (or some starting points for me to look at) for offline capabilities?

[vabene1111]

ok so offline usage does not seem to be a priority for this project wich is totally fine as it is kinda out of scope (even tough it would still be great as facilmap is by far the best mapping system I have seen).

Since that is the case I wrote myself a little script to take the geojson exportable by facilmap and convert it into one .gpx file with points of interests and a folder with multiple GPX files for each track.

The script is super hacky and shows my inability or at least unwillingness to properly work with XML files but it produces what its supposed to produce and works quite nice in OsmAnd. It can also pretty easily be adapted and changed to whatever needs one might have.

Maybe it helps someone looking to use his facilmap offline on an android device, if not it at least did the job for me :)

https://gist.github.com/vabene1111/d5520b24bf7c5a07b9ed2fa1f8cc1d4b

[cdauth]

Thanks for your contribution!

Indeed, offline capabilities would be great, but I don't see them being feasible right now. FacilMap is just a combination of several external services, for example different map styles and routing services. All of these rely on a connection to the server, so creating offline support would essentially mean creating an entirely new app, which also feels a bit useless, as it would basically duplicate the work that Osmand has already done.

But what would be interesting would be to improve the export/import capabilities to exchange data with Osmand. Since I'm not an active user of Osmand myself, I would be curious what the specific pain points are of using the GPX export that FacilMap provides?

[vabene1111]

sure, I think that would be a great addition and also one that could be somewhat easily be incorporated into facilmap by providing an additional exporter.

I think the main problems/challenges would be

• all the icon names are messed up, here I am lacking knowledge of GPX/Mapping so I do not know if there is any standardized naming or if maybe we would need to build a little mapping table (I saw some "alias" files in OSMAnd source files but could not yet figure out how to automatically map the names
• points can have several custom extension elements which map nicely to the custom attributes you can add in facilmap
• tracks need their description in the track <metadata> tag, that is why my script exports one track per file as there is only one metadata tag. I think the exporter should also work this way both to retains the description but also because this way you can toggle and select each track individually in OSMAnd. I think there is some other way to achieve the same thing but I do not know how.
• tracks width in OSMAnd do not take a number but rather a name like bold and only has 3 options small/medium/bold
• OsmAnd has a much more limited selection of shapes (circle, square, octagon) so we need to decide how to map those

I would really love to help add this in if you feel like it would be a good feature because I just love facilmap, it has made my vacation planning so much more enjoyable. For me, my biggest challenge would be the icon thing, if you know anything about that it would save me a lot of research, other than that I think I could help.

After that we could write an exporter similar to https://github.com/FacilMap/facilmap/blob/main/server/src/export/gpx.ts
I am not super good at typescript, do you think it would help you if I start work on the semantic/logic of the exporter in python and you take it as a foundation for adding in the exporter for facilmap or do you just want to do it in typescript directly and maybe I can help answer some questions as I looked at a lot of OsmAnd .gpx files to get my little script working?

I will be on vacation and some Business trips so I am not sure when I can get started, likely end of november/beginning of december.

[cdauth]

I think what would help me the most would be to investigate a little bit how exactly the GPX files would have to look to be supported by Osmand. Maybe you can export a few GPX files with different formattings in Osmand and have a look at the documentation (and this and write a little overview over how the different settings of a FacilMap marker/line would map to an Osmand GPX object.

Unfortunately it's a bit hard right now to make changes to the code base because a lot of dependencies are really outdated. I'm in the process of updating a lot of the code right now but I don't have a lot of time, so I'm not sure how long this will take. I'm planning to take a few months off work in spring and hope to find the time there to work on FacilMap.

If it turns out that to support Osmand we have to split up the map into one GPX file per line, I would probably replace the current 3 export buttons with a single one that opens an export dialog where the exact format of the export can be configured, so it will be a bit more work than just adapting the GPX export code.

[vabene1111]

that sounds like a good plan. When I have time I will create a proper overview of the different attributes facilmap has and how they map to OSMAnd files, then if you have time you can implement it and I will improve my script if I find anything that can be added there for the meantime.

[vabene1111]

Ok so i did not want to forget everything while on vacation so I wrote everything down that I found so far (see the next comment which we can update as we go).

If you could point me to the place where I can find the list of all icons FacilMap supports or the function that generates said list I could start to look into how icon mapping could work.

[vabene1111]

OsmAnd GPX

See also OsmAnd Docs

Points

Schema

Note: I am not sure if osmand namespace needs to be included, I saw it in one example but not in another.

The osmand namespace needs to be included in the schema in addition to the normal GPX namespaces/schemas.

<gpx version="1.1" 
     creator="OsmAndRouterV2" 
     xmlns="http://www.topografix.com/GPX/1/1" 
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xmlns:osmand="https://osmand.net"
     xsi:schemaLocation="http://www.topografix.com/GPX/1/1 http://www.topografix.com/GPX/1/1/gpx.xsd">
    
    <wpt>
        <name>Name</name>
        <extensions>
            ...
        </extensions>
    </wpt>
    
    <wpt>
        <name>...</name>
        <extensions>
            ...
        </extensions>
    </wpt>
    ...
</gpx>

Color

Color is simply an extension attribute as shown below.

<gpx>
    <wpt>
        ...
        <extensions>
            <osmand:colour>#38fff8</osmand:colour>
            ...
        </extensions>
    </wpt>
</gpx>

Size

There does not seem to be an option to control the size of a marker.

TODO: find out how OsmAnd decides which markers to permanently show and which ones to make smaller or hide depending on zoom level.

Icon

OsmAnd supports lots of icon, see docs
FacilMap also support various icons, see docs

I think there is no other way than building a conversion table between the icons, this is a lot of work so need to see
if work can be limited by some kind of automation.

Icons in OsmAnd are given as an extension element

<gpx>
    <wpt>
        ...
        <extensions>
            <osmand:icon>food_restaurant</osmand:icon>
            ...
        </extensions>
    </wpt>
</gpx>

Shape

OSMAnd only supports three shapes (circle, square, octagon)
This seems to be the implementation.

<gpx>
    <wpt>
        ...
        <extensions>
            <osmand:background>circle/square/octagon</osmand:background>
            ...
        </extensions>
    </wpt>
</gpx>

Custom Attributes

All custom attributes added in FacilMap can simply be added as additional elements to the extensions element.
This way they will nicely show as attributes in OsmAnd.

<gpx>
    <wpt>
        ...
        <extensions>
            <custom_1>My Custom content 1</custom_1>
            <Website>urls-will-be-clickable</Website>
            <Custom3>Other Content</Custom3>
            ...
        </extensions>
    </wpt>
</gpx>

Tracks

OsmAnd supports all kinds of tracks and routes. I tested with <trk> which worked well.
The general structure is

<gpx>
   <metadata>
       ...
   </metadata>
    <extensions>
        ...
    </extensions>
    <trk>
        <trkseg>
            <trkpt>...</trkpt>
            ...
        </trkseg>
    </trk>
</gpx>

Since tracks only allow for 1 metadata attribute which contains the description,
the only place to store custom attributes as far as I am aware, we can only have
1 track per .gpx file. This also allows selecting which tracks should be shown in OsmAnd but
requires further work on the exporter and the user needs to import multiple files
(which is easy as multi selections and groups exist in OsmAnd).

Color

Color is identical to points

<gpx>
   <metadata>  ... </metadata>
    <extensions>
         <osmand:colour>#f56b00</osmand:colour>
    </extensions>
    <trk>
        ...
    </trk>
</gpx>

Width

OsmAnd supports only three types of width as string ("thin", "medium", "bold") or numbers from 1-24.
As FacilMap supports basically unlimited width I suggest taking the maximum width in the dataset, scaling it down
to 24 and scale all other widths accordingly. An easier solution would be to just limit it to 24 but that would yield
relative distortion.

<gpx>
   <metadata>  ... </metadata>
    <extensions>
         <osmand:width>5</osmand:width>
    </extensions>
    <trk>
        ...
    </trk>
</gpx>

Custom Attributes

Tracks do not support custom attributes like points do but you can have as much description text as required which
is also displayed nicely when clicking on it in the app.

<gpx>
   <metadata>
       <osmand:desc>
           property 1: value 1
           property 2: urls are clickable in app
           property 3: value 3
       </osmand:desc>
   </metadata>
    <extensions>
        ...
    </extensions>
    <trk>
        <trkseg>
            <trkpt>...</trkpt>
            ...
        </trkseg>
    </trk>
</gpx>

[cdauth]

Here is an overview of all icons: https://unpkg.com/facilmap-leaflet/icontest.html
You can get them as an array by running L.FacilMap.symbolList in the browser console on that page.

In addition, any single letter can be used as the icon content.

[vabene1111]

hi, just wanted to let you know that I will likely not have the time to work on that for the foreseeable future, the documentation is there so should anyone be willing to work on this feel free to pick it up, if I find some time at some point I might pick it up again.

Thanks for your amazing application

[cdauth]

What works now on https://beta.facilmap.org/ (note that any maps created/modified there will be deleted once FacilMap 4 is released):

• Marker colour is added to GPX export for OsmAnd
• Marker shape is added to GPX export for OsmAnd. Because OsmAnd only supports circle, square and octagon, marker shapes are mapped as drop/circle/triangle/triangle-down → circle, rectangle-marker/rectangle → rectangle, diamond/pentagon/hexagon/star → octagon.
• When exporting a single line (through the export dropdown in the line info), the line width and colour are added to the GPX export for OsmAnd.
• Instead of the several export options in the "Tools" menu, there is no one "Export" option that opens a dialog where the exact settings can be configured. There is now an additional option "Track points, one file per line (ZIP file)" that generates a ZIP file containing one GPX file with all markers and a folder with one GPX file for each line.

What's still missing:

• Mapping the FacilMap icons to/from OsmAnd icons. Since OsmAnd has a really nice selection of icons, ideally I would just add all those icons to FacilMap, then no mapping would even be necessary. I'm asking for the license details in Icons licenses? osmandapp/OsmAnd#19282.
• Handling marker colour and shape and line colour and width when importing GPX files from OsmAnd.

[vabene1111]

Wow that sounds amazing. Now I only need time for the next vacation so I can plan it using facilmap 😂

Thank you very much for your great work.