output: github_document

zonebuilder

A rust crate for building zones.

It is an in-progress project to implement the functionality in the zonebuilder R package in the systems programming language Rust.

Why?

• It should eventually enable more people to benefit from free and open source software for creating zoning systems because Rust enables the creation of binaries for Windows, Mac and the free and open source Linux operating system on which the package was originally developed
• To enable deployment of the zonebuilder techniques online, as demonstrated in the web folder (Rust can also compile to WASM enabling complex applications such as A/B Street to run in browser --- the thinking being if that can run in browser surely as simple application to build zones can!)
• Computational efficiency: the process of building zones is not particularly computationally intensive but this Rust crate may eventually be fast and quick to install and use, possibly from higher level languages such as R using Rust interfaces such as extendr
• For fun and education: as a simple crate it serves as a good way to show how Rust code is organised and how it works

Installation of the Rust crate

To install the zonebuilder crate, you need first install Rust. Install the latest version on crates.io with

bash cargo install zonebuilder

You can install the development version as follows:

bash cargo install --git https://github.com/zonebuilders/zonebuilder-rust --branch main

Download and run binaries

Rust can create binaries for all major operating systems. Watch this space for how to run zonebuilders using a binary (no compilation or Rust toolchain required).

Running zonebuilder from the system command line

The zonebuilder binary has a command line interface. Assuming you are installing the crate locally, you can build the binary for Windows, Mac and Linux system shells as follows:

{r, engine='bash'} cargo build

You can see instructions on using the tool with the following command:

{r, engine='bash'} ./target/debug/zonebuilder -h

Let's try making zones with fewer segments and circles (specified by the -s and -d arguments respectively):

{r, engine='bash'} ./target/debug/zonebuilder -s 3 -d 1.0,3.0 > zones.geojson

The The result looks like this:

{r, echo=FALSE} z = sf::read_sf("zones.geojson") plot(z, key.pos = 1)

You can also set the precision of outputs. The default is 6 decimal places, as shown in the output below:

{r} head(sf::st_coordinates(z))

Let's see the output when a precision of 2 decimal places is used:

{r, engine='bash'} ./target/debug/zonebuilder --precision 2 > zones.geojson

That results in this:

{r, echo=FALSE} z = sf::read_sf("zones.geojson") plot(z)

You can run the crate as follows (note the use of -- to pass the arguments to the zonebuilder binary not cargo run):

{r, engine='bash'} cargo run -- --precision 3 > zones.geojson

Take a look at the output:

{r, engine='bash'} head -n 20 zones.geojson

Then read in the GeoJSON file with another tool, e.g. R (this step runs from an R console that has the sf library installed):

```{r circle} zones = sf::read_sf("zones.geojson") plot(zones)

interactive version:

mapview::mapview(zones)

file.remove("zones.geojson") ```

You can generate the same plot in R with the zonebuilder package as follows:

{r rversion} zones = zonebuilder::zb_zone(x = "london", n_circles = 5) plot(zones$geometry)

```{r engine='bash', echo=FALSE, eval=FALSE} cd pwd

rm -rvf zonebuilder-rust

```