# onyx

## about

`onyx` is a lightweight map annotation and location data management and sharing tool built using [leaflet](https://leafletjs.com) and [typescript](https://typescriptlang.org). 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](./LICENSE) - basically do whatever you want with it but leave my name on it.

`leaflet` is distributed under a similar [2-clause BSD license](./LEAFLET-LICENSE).