% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/openfoam_docker.R
\name{sample_foam_slice}
\alias{sample_foam_slice}
\title{Sample OpenFOAM results at pedestrian level and return a raster}
\usage{
sample_foam_slice(
  case_dir,
  fields = c("U", "p"),
  z = 1.5,
  image = "opencfd/openfoam-run:2506",
  resolution = 5,
  time_step = "latestTime",
  interpolate = c("smooth", "focal", "none"),
  idw_power = 2,
  idw_maxdist = NULL,
  buildings = NULL,
  quiet = FALSE
)
}
\arguments{
\item{case_dir}{Character. OpenFOAM case directory.}

\item{fields}{Character vector of field names to sample.
Default \code{c("U", "p")}.}

\item{z}{Numeric. Height above ground in metres.  Default 1.5.}

\item{image}{Character. Docker image tag.
Default \code{"opencfd/openfoam-run:2506"}.}

\item{resolution}{Numeric. Output raster cell size in metres.  Default 5.}

\item{time_step}{Character or numeric. \code{"latestTime"} (default) or a
specific time-step number.}

\item{interpolate}{Character. Post-rasterization smoothing method.
\code{"smooth"} (default) fills NA gaps then applies a Gaussian focal
filter to all cells, producing continuous gradients similar to ParaView;
\code{"focal"} fills NA gaps only (faster, but blocky in open areas);
\code{"none"} returns the raw rasterization without any smoothing.}

\item{idw_power}{Numeric. Controls the Gaussian sigma when
\code{interpolate = "smooth"}: sigma = \code{resolution * idw_power}
metres. Default 2 (10 m sigma at 5 m resolution). Increase for a wider
blur; decrease for sharper transitions near buildings.}

\item{idw_maxdist}{Ignored (reserved for future use).}

\item{buildings}{Optional \code{sf} polygon layer of building footprints in
the domain's local coordinate system. When \code{NULL} (default) the
footprints saved by \code{\link{prepare_openfoam_inputs}} are loaded
automatically from
\code{<case_dir>/constant/gloBFPr/metadata/buildings_openfoam.rds}.
Building interiors are masked to \code{NA}, and the layer is attached to
the returned raster so \code{\link{plot_foam_map}} overlays it without
any extra argument. Pass \code{buildings = sf::st_sf(...)} to override,
or note that masking is skipped when no footprints can be found.}

\item{quiet}{Logical.  Default FALSE.}
}
\value{
A \code{terra::SpatRaster} with layers named after the sampled
fields.  Velocity \code{U} produces three extra layers:
\code{U_mag} (speed), \code{Ux}, \code{Uy}.  Building footprints, when
available, are attached as \code{attr(x, "buildings")}.
}
\description{
Uses OpenFOAM's \code{postProcess -func surfaces} utility to cut a
horizontal plane at z = 1.5 m (or any height) through the latest
time-step, then reads the resulting \code{.raw} files into R and
returns a multi-layer \code{SpatRaster}.

For the current wind workflow, \code{prepare_foam_case()} already writes a
pedestrian slice during the solver run via the \code{pedestrianSlice}
function object; use \code{\link{read_foam_pedestrian_slice}} for that
default 1.5 m output. Use this helper to sample other heights or fields
after a run.
}
\seealso{
\code{\link{plot_foam_map}}, \code{\link{read_foam_pedestrian_slice}}
}
