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

<!-- badges: start -->
[![R-CMD-check](https://github.com/CTTIR/cuvis.r/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/CTTIR/cuvis.r/actions/workflows/R-CMD-check.yaml)
[![pkgdown](https://github.com/CTTIR/cuvis.r/actions/workflows/pkgdown.yaml/badge.svg)](https://cttir.github.io/cuvis.r/)
[![CRAN status](https://www.r-pkg.org/badges/version/cuvis.r)](https://CRAN.R-project.org/package=cuvis.r)
[![Codecov test coverage](https://codecov.io/gh/CTTIR/cuvis.r/branch/main/graph/badge.svg)](https://app.codecov.io/gh/CTTIR/cuvis.r?branch=main)
[![CRAN downloads](https://cranlogs.r-pkg.org/badges/cuvis.r)](https://cran.r-project.org/package=cuvis.r)
[![CRAN downloads total](https://cranlogs.r-pkg.org/badges/grand-total/cuvis.r)](https://cran.r-project.org/package=cuvis.r)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
<!-- badges: end -->

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

## Overview

**cuvis.r** provides R bindings to the Cubert CUVIS C SDK for reading,
processing, and exporting hyperspectral imaging data from Cubert snapshot
cameras. It mirrors the API of
[cuvis.python](https://github.com/cubert-hyperspectral/cuvis.python).

## Prerequisites

1. Install the **Cubert CUVIS SDK** (>= 3.4.0) from
   <https://cloud.cubert-gmbh.de/s/qpxkyWkycrmBK9m>
2. Set the `CUVIS_SDK` environment variable to the SDK install directory
3. Install cuvis.r from GitHub:

```{r install}
remotes::install_github("cttir/cuvis.r")
```

## Quick Start

### Initialize the SDK

Every cuvis.r session begins with `cuvis_init()` and ends with
`cuvis_shutdown()`:

```{r init}
library(cuvis.r)

cuvis_init()
```

### Load a Session File

Cubert cameras store measurements in `.cu3s` session files. Load one
with `cuvis_session()`:
```{r load}
session <- cuvis_session("path/to/measurement.cu3s")
print(session)
```

### Extract a Measurement

Session files contain one or more measurements. Access them by index
(1-based):

```{r mesu}
mesu <- cuvis_get_measurement(session, 1)
print(mesu)
```

### Inspect Metadata

```{r metadata}
md <- cuvis_get_metadata(mesu)
md$name
md$integration_time
md$serial_number
md$product_name
```

### Get the Data Cube

The hyperspectral data cube is returned as a 3D R array
`[rows, cols, bands]` with wavelength metadata attached:

```{r cube}
# First, process to generate the cube
ctx <- cuvis_processing_context(session)
cuvis_reprocess(ctx, mesu, mode = "raw")

cube <- cuvis_get_cube(mesu)
dim(cube)                        # e.g., c(100, 100, 61)
attr(cube, "wavelengths")        # wavelengths in nm
```

You can subset bands, compute means, or use standard R array operations:

```{r ops}
# Mean reflectance per band
band_means <- apply(cube, 3, mean, na.rm = TRUE)

# Extract a single band (e.g., band 30)
single_band <- cube[, , 30]
image(single_band, main = "Band 30")
```

### Export to Standard Formats

```{r export}
# ENVI format (widely supported by remote sensing tools)
cuvis_export_envi(mesu, "output/envi/")

# Multi-channel TIFF
cuvis_export_tiff(mesu, "output/tiff/")
```

### Shutdown

```{r shutdown}
cuvis_shutdown()
```

## Next Steps

- See `vignette("cuvis-r-calibration")` for the full calibration workflow
  (dark/white references, reflectance conversion)
- See the [cuvis.python examples](https://github.com/cubert-hyperspectral/cuvis.python.examples)
  for workflow patterns that translate directly to cuvis.r