onyx is a lightweight map annotation and location data management and sharing tool built using leaflet and typescript. It is intended as a standalone tool to generate, manage, and share simple location data in the form of points, circles, and paths (polylines and polygons). All of these have associated titles and descriptions and can be easily imported from or exported to JSON format for easy sharing. All data is saved locally via the
localStorage API, and the only network calls are those to retrieve either the streetmap or satellite tile data (and of course geolocation if you opt in).
note: On mobile, for best experience you should “install to home screen” or “create shortcut” from your browser of choice, so that you can use
onyx as an app without the browser UI getting in the way.
When you launch the application for the first time (and subsequent times if you don’t set
home), it will ask for your current location to set the
home point. If you deny permission or it can’t determinte your location, you can set it later via the menu and the map will zoom out to fit the entire Earth.
The exception to this behavior is when passing at least
lng values in the query string (eg from a location share link), in which case a marker or circle will be placed on that location and the map centered on it.
Along the bottom is the control bar, containing the following buttons:
Home: If the
homepoint has been set, center the map view on it.
Marker: Enter marker creation mode.
Circle: Enter circle creation mode.
Path: Enter path creation mode.
Tileset: Swap the map tiles between the streetmap and satellite imagery.
Save: Saves your current overlays to local storage.
Clear: Clears all overlays from the map.
Restore: Restores overlays from local storage.
Menu: Show/hide the overlay management menu.
Clicking an overlay shows a popup with the name and description.
Path buttons, you enter overlay creation mode for that overlay type. A small window at the bottom of the screen appears with a cancel button which allows you to leave this mode.
For Markers and Circles, you just click anywhere on the map to bring up the Overlay Creation window.
For Paths, you click points on the map to add them to the polyline — you will see it once you have added at least two points. Once you have added at least three points, an OK button appears on the window at bottom, and clicking it opens the Overlay Creation window.
In the Overlay Creation window, you can set a name and optionally a description for the overlay. For circles, you also set the radius in meters, which defaults to 500. For paths, there is a checkbox for whether to close the polyline (creating a polygon), or leave it as-is. Pressing the
OK button saves the overlay to the map.
Opening the menu shows a list of all overlays organized by type; clicking on any overlay brings up the Overlay Detail window. At the bottom of the menu are also three buttons:
Set Home: Sets the
homepoint to the center of the current map view.
Import: Opens the Import window to import overlay data from JSON format.
Export All: Opens the Export window to export all overlay data to JSON format.
This window is similar to the Overlay Creation window save the addition of three buttons:
Go Here: Centers the map view on this overlay.
Share: Opens the Export window to export this overlay as a shareable link.
Export: Opens the Export window to export this overlay to JSON format.
Delete: Deletes this overlay from the map.
In addition to being reachable from the menu, you can also reach this screen by clicking on an overlay and then clicking on the text in the tooltip.
When exporting, the
Copy to Clipboard button does just that. The JSON data can then be saved to a text file, emailed to a friend, or what have you. A link from the
Share button can be given to anyone to put in their browser.
When importing, the imported data is added to the current overlays. If you want to overwrite your current data, clear it first.
When using a share link, the following query string values are valid:
lat: required; should be a number
lng: required; should be a number
rad: optional; should be a positive number; if omitted, the shared overlay will be a
name: optional; defaults to lat,lng
desc: optional; defaults to empty
tile: optional; if “sat” the tileset will use satellite data; if omitted or any other value, the tileset will use the OpenStreetMap data.
If you want to hack on
onyx and rebuild it, I recommend rebuilding the
sourcemapper (written in
go) in the
buildtools directory first (in case your
glibc version is older).
The build process for
onyx is a bit unorthodox. Instead of using modules, the
typescript code is all concatenated before transpiling. The
sourcemapper is used to show lines in the original source where transpilation errors occured, in a plumbable address format so you can right-click in
acme and go directly to that line of code.
src directory, you can just run
./build.sh. Once built, the final
static directory with the rest of the application.
Deploying is simple: just serve the
onyx is distributed under the MIT license - basically do whatever you want with it but leave my name on it.
leaflet is distributed under a similar 2-clause BSD license.