---
title: "Tsunami evacuation workflow"
description: "Prepare tsunami-specific hazard and escape zones without coastline exits."
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Tsunami evacuation workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", eval = FALSE)
time_summary <- utils::read.csv(system.file(
  "extdata/pkgdown-example-time-summary.csv", package = "evacpath"
))
zone_roles <- data.frame(
  object = c("Land-only hazard zone", "Water-combined escape zone", "Road-aware escape boundary"),
  role = c("Origin and mapped-output area", "Meaningful inland exit context", "Road-preserving exit-detection boundary"),
  used_for = c("Road origins and final time outputs", "Avoiding coastline exits", "Finding candidate safety exits"),
  common_mistake_avoided = c(
    "Mapping through water or starting origins offshore",
    "Treating the shoreline as an automatic safety boundary",
    "Dropping bridge, causeway, or walkway connections"
  )
)
figure_html <- function(name, alt) {
  path <- system.file("extdata", name, package = "evacpath")
  if (!nzchar(path)) stop("Installed example figure is unavailable.", call. = FALSE)
  knitr::asis_output(sprintf(
    '<figure><img src="%s" alt="%s" style="width: 100%%; height: auto;"><figcaption>%s</figcaption></figure>',
    knitr::image_uri(path), alt, alt
  ))
}
```

Tsunami workflows often need different zones for mapped exposure and for
finding a meaningful inland exit. `prepare_tsunami_zones()` makes those roles
explicit.

## Three spatial roles

```{r zone-roles, echo = FALSE, eval = TRUE}
knitr::kable(
  zone_roles,
  col.names = c("Object", "Role", "Used for", "Common mistake avoided")
)
```

```{r tsunami-inputs-figure, echo = FALSE, eval = TRUE, results = "asis"}
figure_html("pkgdown-example-inputs.png", "The compact example shows land-only hazard mapping, roads, and candidate safety exits.")
```

The water-combined escape zone is a processing layer, so it is not shown as a
separate planning boundary in this compact map. Its role is to prevent a
land-water split from creating artificial coastline exits.

## Prepare the zones

```{r zones}
zones <- prepare_tsunami_zones(
  inundation = inundation,
  dem = dem,
  target_crs = "EPSG:32748",
  inundation_threshold = 0,
  dem_sign_multiplier = 1
)

roads_for_escape <- crop_roads_to_inner_extent(
  roads = roads,
  zone = zones$escape_zone,
  inset_x_m = 250,
  inset_y_m = 250
)

escape_boundary_zone <- make_road_aware_escape_zone(
  escape_zone = zones$escape_zone,
  roads = roads_for_escape,
  road_buffer_m = 2,
  crop_buffer_m = 3
)
```

## Model travel to safety

```{r model}
result <- run_evacpath(
  hazard_zone = zones$hazard_zone,
  escape_zone = zones$escape_zone,
  roads = roads,
  roads_for_escape = roads_for_escape,
  dem = zones$dem,
  target_crs = "EPSG:32748",
  road_aware_escape_zone = TRUE,
  escape_zone_road_buffer_m = 2,
  escape_zone_crop_buffer_m = 3
)
```

```{r tsunami-time-figure, echo = FALSE, eval = TRUE, results = "asis"}
figure_html("pkgdown-example-time.png", "Modeled evacuation time to safety for the compact tsunami example.")
```

```{r tsunami-result, echo = FALSE, eval = TRUE}
knitr::kable(time_summary, col.names = c("Modeled output", "Example value"))
```

Inspect the local hazard boundary, road network, elevation sign convention, and
projected CRS before relying on candidate escape points or modeled times.