% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/run_evacpath.R
\name{run_evacpath}
\alias{run_evacpath}
\title{Run the full evacuation-path modeling workflow}
\usage{
run_evacpath(
  hazard_zone,
  roads,
  dem,
  target_crs = NULL,
  region_name = NULL,
  escape_zone = NULL,
  roads_for_escape = NULL,
  escape_roads_inset_x_m = 0,
  escape_roads_inset_y_m = 0,
  road_aware_escape_zone = FALSE,
  escape_zone_road_buffer_m = NULL,
  escape_zone_crop_buffer_m = NULL,
  study_area = NULL,
  road_exclude = NULL,
  grid_resolution = NULL,
  grid_resolution_factor = 5,
  road_buffer_m = 2,
  escape_buffer_m = 5,
  final_road_buffer_m = 3,
  region_buffer_m = 5000,
  dem_resolution = NULL,
  max_origins = NULL,
  max_destinations = NULL,
  seed = 23401,
  walking_speed_mps = 1.22,
  clip_mode = c("hazard", "road_hazard", "hazard_plus_roads", "none"),
  progress = FALSE,
  progress_every = 1L,
  lcp_check_locations = FALSE
)
}
\arguments{
\item{hazard_zone}{Hazard/inundation zone as \code{SpatRaster}, \code{SpatVector}, or path.
This should usually be the land-only area where evacuation origins and final
output surfaces are mapped.}

\item{roads}{Road/pathway network as \code{SpatVector} or path.}

\item{dem}{Elevation raster as \code{SpatRaster} or path.}

\item{target_crs}{Optional projected CRS in meters, for example \code{"EPSG:32748"}.}

\item{region_name}{Optional region name stored in output polygons.}

\item{escape_zone}{Optional boundary zone used only to identify escape/safety
points. For tsunami workflows, pass the land-inundation-plus-water zone from
\code{prepare_tsunami_zones()} here. If \code{NULL}, \code{hazard_zone} is used.}

\item{roads_for_escape}{Optional road/pathway layer used only for escape-point
detection. If \code{NULL}, \code{roads} is used. This is useful when the full road
dataset extends beyond the reliable hazard-zone study extent.}

\item{escape_roads_inset_x_m}{Optional x-direction inset applied to
\code{roads_for_escape} before escape-point detection. This prevents roads from
intersecting artificial study-area extent boundaries.}

\item{escape_roads_inset_y_m}{Optional y-direction inset applied to
\code{roads_for_escape} before escape-point detection.}

\item{road_aware_escape_zone}{Logical. If \code{TRUE}, buffered \code{roads_for_escape}
are combined with \code{escape_zone} before escape points are generated. This
preserves bridge, causeway, and walkway corridors over water that can be lost
when the tsunami layer is split into land and water masks.}

\item{escape_zone_road_buffer_m}{Road buffer used when \code{road_aware_escape_zone = TRUE}.}

\item{escape_zone_crop_buffer_m}{Additional buffer used when \code{road_aware_escape_zone = TRUE}.}

\item{study_area}{Optional local study area for limiting escape-point search.}

\item{road_exclude}{Optional list passed to \code{clean_roads()}.}

\item{grid_resolution}{Evacuation-grid resolution. If \code{NULL}, calculated from
\code{terra::res(dem) * grid_resolution_factor}.}

\item{grid_resolution_factor}{Multiplier applied to DEM resolution when
\code{grid_resolution = NULL}.}

\item{road_buffer_m}{Road buffer distance.}

\item{escape_buffer_m}{Escape-point buffer distance.}

\item{final_road_buffer_m}{Output clipping buffer around roads.}

\item{region_buffer_m}{Buffer around \code{study_area} used when finding escape points.}

\item{dem_resolution}{Optional DEM resolution used before conductance creation.}

\item{max_origins}{Optional maximum number of road origin points.}

\item{max_destinations}{Optional maximum number of escape/safety destination points.
This is useful for quick tests in regions where roads intersect the hazard
boundary many times.}

\item{seed}{Random seed used when \code{max_origins} or \code{max_destinations} is supplied.}

\item{walking_speed_mps}{Walking speed in meters per second.}

\item{clip_mode}{Output clipping mode. The default \code{"hazard"} creates a
continuous time-grid polygon surface clipped to the land-only hazard zone.
Use \code{"road_hazard"} for the older road-buffer-limited output,
\code{"hazard_plus_roads"} to retain both, or \code{"none"} for unclipped Voronoi polygons.}

\item{progress}{Logical. Print progress while running least-cost paths.}

\item{progress_every}{Integer. Print progress every \code{n} origins when \code{progress = TRUE}.}

\item{lcp_check_locations}{Logical passed to \code{leastcostpath::create_lcp()}.
Default is \code{FALSE} for speed after projection/cropping checks.}
}
\value{
An \code{evacpath_result} list containing spatial outputs and parameters.
}
\description{
This high-level wrapper runs the core \code{evacpath} pipeline: read/project inputs,
create an evacuation grid, identify escape/safety points, build a road mask,
create a slope-based conductance surface, calculate minimum least-cost distance
to safety, and create evacuation-time polygons.
}
\details{
For tsunami applications, \code{hazard_zone} and \code{escape_zone} should often be
different. Use a land-only \code{hazard_zone} for origins and output mapping, but
use a water-combined \code{escape_zone} for escape-point detection so the coastline
is not treated as an artificial safety boundary. The helper
\code{prepare_tsunami_zones()} creates both objects.
}
\examples{
dem <- terra::rast(nrows = 7, ncols = 7, xmin = 0, xmax = 7, ymin = 0, ymax = 7,
  vals = 1, crs = "EPSG:3857")
hazard_raster <- terra::crop(dem, terra::ext(1, 6, 1, 6))
hazard <- terra::as.polygons(hazard_raster, dissolve = TRUE)
roads <- terra::vect(matrix(c(0, 3.5, 7, 3.5), ncol = 2, byrow = TRUE),
  type = "lines", crs = "EPSG:3857")
result <- run_evacpath(
  hazard_zone = hazard,
  roads = roads,
  dem = dem,
  grid_resolution = 1,
  road_buffer_m = 0.2,
  escape_buffer_m = 0.3,
  final_road_buffer_m = 0.2,
  max_origins = 2,
  max_destinations = 2,
  seed = 1
)
result
}
