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

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

```{r setup}
library(aboveR)
library(terra)
library(sf)
```

## Overview

aboveR provides terrain analysis functions for LiDAR-derived elevation data:
change detection between DEM epochs, cut/fill volume estimation, terrain
profiling, erosion channel detection, reclamation monitoring, highwall
classification, and flood risk assessment. The package also includes access
utilities for Kentucky's KyFromAbove cloud-native elevation data on AWS S3.

## Installation

```{r, eval = FALSE}
install.packages("aboveR")
```

## Quick Start: Terrain Change Detection

Load the bundled sample DEMs — a synthetic hillside before and after
simulated mining activity:

```{r}
before <- rast(system.file("extdata/dem_before.tif", package = "aboveR"))
after  <- rast(system.file("extdata/dem_after.tif", package = "aboveR"))
```

Compute terrain change:

```{r}
change <- terrain_change(before, after)
plot(change[["change"]], main = "Elevation Change (m)")
```

The result has two layers: `change` (continuous difference) and `class`
(cut / stable / fill).

## Volume Estimation

Estimate cut and fill volumes within a boundary polygon:

```{r}
boundary <- st_read(
  system.file("extdata/boundary.gpkg", package = "aboveR"),
  quiet = TRUE
)
vol <- estimate_volume(after, before, boundary)
cat("Cut volume: ", round(vol$cut_volume_m3), "m3\n")
cat("Fill volume:", round(vol$fill_volume_m3), "m3\n")
cat("Net change: ", round(vol$net_volume_m3), "m3\n")
```

## Terrain Profiling

Extract elevation along a transect line:

```{r}
line <- st_read(
  system.file("extdata/profile_line.gpkg", package = "aboveR"),
  quiet = TRUE
)
prof <- terrain_profile(before, line)
plot(prof$distance, prof$elevation, type = "l",
     xlab = "Distance (m)", ylab = "Elevation (m)",
     main = "Terrain Profile")
```

## Surface Roughness

Compute local surface roughness (standard deviation in a moving window):

```{r}
rough <- surface_roughness(before, window = 5)
plot(rough, main = "Surface Roughness")
```

## KyFromAbove Data Access

The `kfa_*` functions provide access to Kentucky's statewide elevation data.
These require internet connectivity:
```{r, eval = FALSE}
# Find DEM tiles for an area of interest
tiles <- kfa_find_tiles(
  aoi = c(-84.55, 37.95, -84.45, 38.05),
  product = "dem",
  phase = 2
)

# Read and mosaic DEM tiles
dem <- kfa_read_dem(
  aoi = c(-84.55, 37.95, -84.45, 38.05),
  phase = 2
)
```