onyx

about

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).

usage

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 lat and 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 home point 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.

Overlay Creation

Clicking the Marker, Circle, or 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.

Overlay Management

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 home point 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.

Overlay Detail

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.

Import/Export

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 Marker.
• 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.

build/deploy

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.

From the src directory, you can just run ./build.sh. Once built, the final javascript file is located in the static directory with the rest of the application.

Deploying is simple: just serve the static directory.

license

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.