Package 'cuvis.r'

Title: R Bindings for the Cubert CUVIS Hyperspectral SDK
Description: Provides R bindings to the Cubert CUVIS C SDK for reading, processing, and exporting hyperspectral imaging data from Cubert snapshot cameras. Supports loading proprietary '.cu3s' session files, applying the full calibration pipeline (dark subtraction, white reference normalization, spectral radiance, reflectance), and exporting to standard formats (ENVI, TIFF). Requires the Cubert CUVIS SDK to be installed separately. This package mirrors the API of 'cuvis.python' (<https://github.com/cubert-hyperspectral/cuvis.python>) for R users.
Authors: R. Heller [aut, cre] (ORCID: <https://orcid.org/0000-0001-8006-9742>)
Maintainer: R. Heller <[email protected]>
License: Apache License (>= 2) | file LICENSE
Version: 0.1.0
Built: 2026-10-14 14:52:43 UTC
Source: https://github.com/CTTIR/cuvis.r

Help Index

Check if CUVIS SDK is Available

Description

Tests whether the Cubert CUVIS SDK library is linked and usable.

Usage

cuvis_available()

Value

Logical. TRUE if the SDK is available, FALSE otherwise.

Export a Measurement to ENVI Format

Description

Writes the measurement data as an ENVI header/binary file pair.

Usage

cuvis_export_envi(measurement, dir, permissive = TRUE)

Arguments

measurement

A cuvis_measurement object.
dir

Character. Output directory.
permissive

Logical. Allow export even if some data is missing. Default TRUE.

Value

Invisible dir.

Export a Measurement to a New Session File

Description

Saves the measurement as a new .cu3s session file.

Usage

cuvis_export_session(measurement, dir, permissive = TRUE)

Arguments

measurement

A cuvis_measurement object.
dir

Character. Output directory for the .cu3s file.
permissive

Logical. Default TRUE.

Value

Invisible dir.

Export a Measurement to TIFF Format

Description

Export a Measurement to TIFF Format

Usage

cuvis_export_tiff(
  measurement,
  dir,
  format = c("MultiChannel", "Single", "MultiPage"),
  compression = c("None", "LZW"),
  permissive = TRUE
)

Arguments

measurement

A cuvis_measurement object.
dir

Character. Output directory.
format

Character. TIFF format: "MultiChannel" (default), "Single", or "MultiPage".
compression

Character. Compression mode: "None" (default) or "LZW".
permissive

Logical. Default TRUE.

Value

Invisible dir.

Extract Hyperspectral Cube from a Measurement

Description

Returns the 3D data cube as an R array with wavelength metadata.

Usage

cuvis_get_cube(measurement)

Arguments

measurement

A cuvis_measurement object.

Value

A numeric 3D array with dimensions ⁠[rows, cols, bands]⁠. The "wavelengths" attribute contains a numeric vector of band center wavelengths in nanometers.

Examples

## Not run: 
cuvis_init()
session <- cuvis_session("path/to/file.cu3s")
mesu <- cuvis_get_measurement(session, 1)
cube <- cuvis_get_cube(mesu)
dim(cube)                        # e.g., c(100, 100, 61)
attr(cube, "wavelengths")        # wavelengths in nm
cuvis_shutdown()

## End(Not run)

Get a Measurement from a Session

Description

Extracts a single measurement from a session file by index.

Usage

cuvis_get_measurement(session, index = 1L, item_type = "no_gaps")

Arguments

session

A cuvis_session object.
index

Integer. 1-based measurement index.
item_type

Character. Type of items to enumerate: "no_gaps" (default), "all_frames", or "references".

Value

A cuvis_measurement S3 object, or NULL if no measurement exists at that index.

Get Measurement Metadata

Description

Returns metadata fields for a measurement including name, integration time, serial number, processing mode, and more.

Usage

cuvis_get_metadata(measurement)

Arguments

measurement

A cuvis_measurement object.

Value

A named list with fields: name, path, comment, integration_time (ms), averages, distance, serial_number, product_name, assembly, processing_mode (integer), capture_time (ms since epoch), measurement_flags (integer).

Get Wavelength Vector from a Measurement

Description

Convenience function to extract just the wavelength vector from a measurement's cube data.

Usage

cuvis_get_wavelengths(measurement)

Arguments

measurement

A cuvis_measurement object.

Value

Numeric vector of wavelengths in nm.

Check if a Reference is Set

Description

Check if a Reference is Set

Usage

cuvis_has_reference(
  ctx,
  type = c("dark", "white", "white_dark", "sprad", "distance")
)

Arguments

ctx

A cuvis_processing_context object.
type

Character. Reference type to check.

Value

Logical.

Initialize the CUVIS SDK

Description

Must be called before any other cuvis.r function. Loads the Cubert CUVIS SDK and configures the user settings directory.

Usage

cuvis_init(settings_dir = NULL)

Arguments

settings_dir

Character. Path to the CUVIS settings directory — the one holding ⁠factory/⁠ and ⁠user/⁠. If NULL (default), the directory is discovered in this order: the CUVIS_SETTINGS environment variable, then the standard install locations for the platform, and only as a last resort a temporary directory.

Details

The settings directory is not optional in practice. The SDK loads its factory calibration from it, and pointing it at an empty directory makes every subsequent cuvis_proc_cont_apply() fail with "Could not process measurement" — which looks like a corrupt recording rather than a configuration problem. Hence the search over real install locations before falling back to a temporary directory, and the warning when it does.

Value

Invisible NULL.

Examples

## Not run: 
cuvis_init()
# ... use SDK ...
cuvis_shutdown()

## End(Not run)

Is the CUVIS SDK Currently Initialised?

Description

Is the CUVIS SDK Currently Initialised?

Usage

cuvis_is_initialized()

Value

Logical.

Examples

cuvis_is_initialized()

Create a Processing Context for Calibration

Description

Creates a processing context from a session file or measurement. This context holds calibration references and processing parameters for reprocessing measurements.

Usage

cuvis_processing_context(base, load_references = TRUE)

Arguments

base

A cuvis_session or cuvis_measurement object.
load_references

Logical. If TRUE (default), automatically loads references embedded in the session file.

Value

A cuvis_processing_context S3 object.

CUVIS Processing Modes

Description

Named integer vector of processing modes matching the CUVIS SDK C enum values. Used internally by cuvis_reprocess().

Usage

cuvis_processing_modes

Details

  • Raw (0): Raw sensor data, no processing

  • DarkSubtract (1): Dark current subtracted

  • Reflectance (2): Normalized reflectance (0-1)

  • SpectralRadiance (3): Calibrated to physical radiance (W/m^2/sr/nm)

  • Preview (5): Low-resolution preview only

CUVIS Reference Types

Description

Named integer vector of reference types matching the CUVIS SDK C enum values. Used by cuvis_set_reference().

Usage

cuvis_reference_types

Details

  • Dark (0): Dark reference frame

  • White (1): White reference frame

  • WhiteDark (2): Dark reference for the white reference

  • SpRad (3): Spectral radiance calibration

  • Distance (4): Distance calibration

Reprocess a Measurement to a New Calibration Level

Description

Applies processing context settings to a measurement, converting it to the requested calibration level (e.g., reflectance).

Usage

cuvis_reprocess(
  ctx,
  measurement,
  mode = c("reflectance", "spectral_radiance", "dark_subtract", "raw", "preview"),
  allow_recalib = FALSE
)

Arguments

ctx

A cuvis_processing_context with references set.
measurement

A cuvis_measurement to reprocess.
mode

Character. Target processing mode: "reflectance" (default), "spectral_radiance", "dark_subtract", "raw", or "preview".
allow_recalib

Logical. Allow recalibration if needed. Default FALSE.

Value

The same cuvis_measurement object, reprocessed in place. Extract the cube with cuvis_get_cube().

Get Path to Sample Data

Description

Returns the path to Cubert sample data. Searches in order:

  1. ⁠.cuvis/⁠ directory in the working directory or any parent (up to 5 levels)

  2. CUVIS_DATA environment variable

  3. SDK default install location

Usage

cuvis_sample_data(file = NULL)

Arguments

file

Character. Specific file name (e.g., "test_mesu.cu3s"). If NULL, returns the sample data root directory.

Value

Character path, or NULL if not found.

Load the Default Sample Session

Description

Convenience function that locates and loads the first .cu3s file found in the sample data directories.

Usage

cuvis_sample_session()

Value

A cuvis_session object, or NULL with a warning if sample data is not found.

Load a Cubert Session File

Description

Opens a .cu3s session file containing one or more hyperspectral measurements with their calibration references.

Usage

cuvis_session(path)

Arguments

path

Character. Path to a .cu3s session file.

Value

A cuvis_session S3 object (wrapping an external pointer to the SDK session handle). Use cuvis_get_measurement() to extract individual measurements.

Examples

## Not run: 
cuvis_init()
session <- cuvis_session("path/to/measurement.cu3s")
print(session)
cuvis_shutdown()

## End(Not run)

Set a Calibration Reference

Description

Assigns a reference measurement (dark, white, etc.) to a processing context.

Usage

cuvis_set_reference(
  ctx,
  measurement,
  type = c("dark", "white", "white_dark", "sprad", "distance")
)

Arguments

ctx

A cuvis_processing_context object.
measurement

A cuvis_measurement object (the reference frame).
type

Character. One of "dark", "white", "white_dark", "sprad", or "distance".

Value

Invisible ctx (modified in place via external pointer).

Shut Down the CUVIS SDK

Description

Releases all SDK resources. Call when done using cuvis.r functions.

Usage

cuvis_shutdown()

Value

Invisible NULL.

Get CUVIS SDK Version

Description

Note: The SDK must be initialized with cuvis_init() before calling this function.

Usage

cuvis_version()

Value

Character string with the SDK version.