# Getting Started with aboveR

    library(aboveR)
    library(terra)
    #> terra 1.8.93
    library(sf)
    #> Linking to GEOS 3.13.1, GDAL 3.11.4, PROJ 9.7.0; sf_use_s2() is TRUE

## 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

    install.packages("aboveR")

## Quick Start: Terrain Change Detection

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

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

Compute terrain change:

    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:

    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")
    #> Cut volume:  224951 m3
    cat("Fill volume:", round(vol$fill_volume_m3), "m3\n")
    #> Fill volume: 2763 m3
    cat("Net change: ", round(vol$net_volume_m3), "m3\n")
    #> Net change:  -222188 m3

## Terrain Profiling

Extract elevation along a transect line:

    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):

    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:

    # 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
    )