---
title: "Introduction to GeoIndexR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to GeoIndexR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Overview

**GeoIndexR** is a modern, modular, and extensible R package for computing spectral and geospatial indices from multispectral raster data. Built natively on `terra`, GeoIndexR operates on `SpatRaster` objects and file paths while preserving all georeferencing, projection (CRS), resolution, and spatial extents.

Beyond standard indices, GeoIndexR features a **secure custom formula engine** (`geo_index_custom()`) enabling users to compute any mathematical expression on spectral bands with custom constants.

---

## 9-Step Complete Workflow

### Step 1: Load a Raster (SpatRaster or File Path)

You can pass a loaded `terra::SpatRaster` or directly supply a file path character string:

```{r step1}
library(GeoIndexR)
library(terra)

# Load synthetic 6-band multispectral image
img <- get_example_data()
print(img)
names(img)
```

### Step 2: Identify and Map Spectral Bands

Bands can be resolved automatically by layer name, by layer position index (`c(red = 3, nir = 4)`), or using sensor presets (`sensor = "sentinel2"`):

```{r step2}
# Band mapping by explicit role name
bands_map <- c(red = "red", nir = "nir", blue = "blue")
```

### Step 3: Compute a Standard Predefined Index

Compute standard indices using `geo_index()`:

```{r step3}
ndvi <- geo_index(img, "NDVI", bands = bands_map)
print(ndvi)
```

### Step 4: Examine Summary Statistics and Quantiles

Use `index_summary()` to compute descriptive statistics including percentiles (q05, q25, q75, q95) and NA percentages:

```{r step4}
summary_tbl <- index_summary(ndvi)
print(summary_tbl)
```

### Step 5: Visualize the Index

Use `plot_index()` with thematic color palettes automatically matched to index categories (vegetation, water, urban, soil, snow):

```{r step5, fig.width = 6, fig.height = 5}
plot_index(ndvi, "NDVI")
```

### Step 6: Save the Result to Disk

All outputs from `GeoIndexR` are standard `terra::SpatRaster` objects, ready for export:

```{r step6, eval = FALSE}
writeRaster(ndvi, "NDVI_output.tif", overwrite = TRUE)
```

### Step 7: Compute a Custom Formula Index

Compute your own formulas using `geo_index_custom()`:

```{r step7}
# Compute a custom ratio
custom_ratio <- geo_index_custom(
  img,
  formula = "(nir - red) / (nir + red)",
  bands = c(red = "red", nir = "nir"),
  name = "MyCustomNDVI"
)
print(custom_ratio)

# Compute a custom parameterized index
custom_veg <- geo_index_custom(
  img,
  formula = "G * (nir - red) / (nir + C1 * red - C2 * blue + L)",
  bands = c(blue = "blue", red = "red", nir = "nir"),
  params = list(G = 2.5, C1 = 6.0, C2 = 7.5, L = 1.0),
  name = "CustomEVI"
)
print(custom_veg)
```

### Step 8: Manage Reflectance and Scale Factors

For scale-sensitive indices (such as EVI, SAVI, MSAVI, ARVI) where input data are stored as raw integer Digital Numbers (e.g. $[0, 10000]$ in Sentinel-2 L2A), specify `scale_factor = 10000`:

```{r step8}
# Mock integer DN raster
img_dn <- img * 10000

# Calculate EVI with proper scale factor conversion
evi_scaled <- geo_index(
  img_dn,
  "EVI",
  bands = c(blue = "blue", red = "red", nir = "nir"),
  scale_factor = 10000
)
index_summary(evi_scaled)
```

### Step 9: Consult the Extensible Index Registry

Explore available indices, formulas, required bands, interpretations, and literature citations via `index_registry()`:

```{r step9}
reg <- index_registry(category = "vegetation")
reg[, c("index", "name", "required_bands", "requires_reflectance")]
```