% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ingest_rasters.R
\name{read_sonar_tif}
\alias{read_sonar_tif}
\title{Read a bathymetric or sidescan GeoTIFF and convert to oystermapR variables}
\usage{
read_sonar_tif(
  file,
  type = c("bathy", "sidescan"),
  spatial_res = 4L,
  band = 1L,
  nodata_val = NA,
  depth_positive = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{file}{Character. Path to the GeoTIFF file (\code{.tif}).}

\item{type}{Character. Either \code{"bathy"} or \code{"sidescan"}.}

\item{spatial_res}{Integer. Decimal places for output lat/lon grid
(default \code{4}). The raster is resampled to this resolution before
converting to a dataframe.}

\item{band}{Integer. Raster band to read (default \code{1}).}

\item{nodata_val}{Numeric. Value to treat as no-data (default \code{NA}).
Override if your raster uses a sentinel (e.g. \code{-9999}).}

\item{depth_positive}{Logical. For \code{type = "bathy"}: if \code{TRUE} (default),
raster values are already positive-downward. Set \code{FALSE} if stored as
negative elevation.}

\item{verbose}{Logical (default \code{TRUE}).}
}
\value{
A dataframe with \code{lat}, \code{lon}, and the derived variable columns
ready for \code{\link[=merge_sensor_data]{merge_sensor_data()}}.
}
\description{
Reads a single-band GeoTIFF raster using \code{terra} and returns a spatially
averaged dataframe suitable for \code{\link[=merge_sensor_data]{merge_sensor_data()}}.

Two modes are supported, selected via the \code{type} argument:

\strong{\code{"bathy"}} -- Bathymetric DEM (e.g. from Ping 3DSS or post-processed
soundings). Extracts:
\itemize{
\item \code{depth} -- raster cell value (metres)
\item \code{slope} -- computed using \code{\link[terra:terrain]{terra::terrain()}}
\item \code{roughness} -- Terrain Ruggedness Index via \code{\link[terra:terrain]{terra::terrain()}}
}

\strong{\code{"sidescan"}} -- Sidescan backscatter mosaic (normalised 0--1 or raw DN).
Extracts:
\itemize{
\item \code{substrate_hardness} -- backscatter intensity normalised to [0, 1].
High backscatter -> hard/coarse substrate (rock, gravel, shell);
low backscatter -> soft substrate (mud, fine sand).
}
}
\examples{
\donttest{
bathy_df   <- read_sonar_tif("kames_bay_bathy.tif",    type = "bathy")
sidescan_df <- read_sonar_tif("kames_bay_sidescan.tif", type = "sidescan")
survey <- merge_sensor_data(bathy = bathy_df, sidescan = sidescan_df, adcp = adcp_df)
}
}
