# osmx-rs
This is a Rust port of [OSMExpress](https://github.com/protomaps/OSMExpress/), a fast storage format for OpenStreetMap data created by Brandon Liu for [Protomaps](https://protomaps.com/). The format supports random access (looking up nodes, ways and relations by ID), spatial indexing of node locations, and in-place updates.
## Usage
See the [docs](https://docs.rs/osmx/latest) for API documentation and the [examples](./examples) directory for commented example programs.
The [README](https://github.com/protomaps/OSMExpress/blob/main/README.md), [Manual](https://github.com/protomaps/OSMExpress/blob/main/docs/MANUAL.md), and [Programming Guide](https://github.com/protomaps/OSMExpress/blob/main/docs/PROGRAMMING_GUIDE.md) of the OSMExpress C++ reference implementation may also be helpful.
## Features
This crate supports reading from `.osmx` database files, including:
- fetching nodes, ways and relations by ID
- reading an element's tags
- getting a node's location, a way's nodes, or a relation's members
- finding nodes in a region using the spatial index
- getting reverse relationships (finding all ways that a node is part of, or all relations that an element is a member of)
It does _not_ yet support:
- reading element metadata (e.g. the version number of an element or the changeset and user that most recently modified it)
- writing data to an `.osmx` database, or creating a new `.osmx` database
Pull requests for these missing features are welcome.
## Safety
osmx-rs is not designed for reading untrusted input files. Using this crate to read a malformed `.osmx` file may cause the process to panic, or worse. Pull requests to improve safety or prevent panics are welcome.
Also worth noting that osmx-rs depends on the [lmdb](https://crates.io/crates/lmdb) crate, which wraps the [LMDB](https://www.symas.com/lmdb) C API and therefore requires the use of `unsafe`.
## CLI command
This repository also contains a CLI tool for interacting with `.osmx` files.
Usage: `osmx-rs [COMMAND] [ARGS...]`
Commands:
- `expand`: convert an OSM PBF file to an OSMX database
- `stat`: print statistics about the contents of an OSMX database
The command is intended to be useful tool, but also to be an illustrative example of how to use the `osmx-rs` crate to create and interact with `.osmx` files. The source code can be found in the `bin/` directory.
## License
This code can be used under the terms of either the [MIT license](./LICENSE-MIT) or [Apache-2.0 license](./LICENSE-APACHE), at your option.