---
title: "Getting started with osmnxr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with osmnxr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 6.5, fig.height = 5.5)
```

```{r setup}
library(osmnxr)
```

## What is osmnxr?

`osmnxr` is *OSMnx for R*: it downloads, models, analyzes and visualizes street
networks from [OpenStreetMap](https://www.openstreetmap.org/). The public API is
tidyverse-friendly and returns [`sf`](https://r-spatial.github.io/sf/) objects;
the heavy graph computation (routing, metrics, simplification) runs in a bundled
**Rust core**.

The central object is the `osm_graph`: a pair of `sf` tables (nodes and edges)
plus metadata.

## A real network

The usual entry point is a place name, which downloads from OpenStreetMap:

```{r, eval = FALSE}
g <- ox_graph_from_place("Olinda, Brazil", network_type = "drive")
g <- ox_simplify(g)
```

So this vignette runs offline, we load that exact network — the historic centre
of Olinda, Brazil — from the copy bundled with the package:

```{r}
g <- ox_example("olinda")
g
```

```{r}
plot(g)
```

## Network statistics

```{r}
ox_basic_stats(g)
```

## Routing

Snap coordinates to graph nodes, then compute the shortest path (Dijkstra, in
Rust):

```{r}
orig <- ox_nearest_nodes(g, x = -34.8553, y = -8.0089)
dest <- ox_nearest_nodes(g, x = -34.8505, y = -8.0125)
route <- ox_shortest_path(g, orig, dest)
length(route) # nodes along the route
```

```{r}
route_xy <- sf::st_coordinates(g$nodes)[match(route, g$nodes$osmid), ]
plot(g, col = "grey80", lwd = 0.6)
lines(route_xy, col = "#b7410e", lwd = 3)
```

## Where to next

- [Routing and isochrones](routing-and-isochrones.html) — travel time, route
  alternatives, service areas.
- [Urban metrics](urban-metrics.html) — circuity, centrality, chokepoints.
- [Street orientation](street-orientation.html) — grid order across cities.
- [Accessibility analysis](accessibility.html) — access to schools, hospitals,
  parks.
- [Features and points of interest](features-and-pois.html) — download POIs and
  buildings.

No network needed at all? `example_osm_graph()` builds a synthetic grid for
quick experiments.