onyx/README.md

4.6 KiB

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.

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.
  • Export: Opens the Export window to export this overlay to JSON format.
  • Delete: Deletes this overlay from the map.

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.

When importing, the imported data is added to the current overlays. If you want to overwrite your current data, clear it first.

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.