| Title: | Read Diaspective Vision TIVITA Hyperspectral Recordings |
|---|---|
| Description: | Reads hyperspectral imaging data written by the Diaspective Vision TIVITA Suite, used for intraoperative tissue and perfusion imaging. Parses the binary 'SpecCube.dat' container (big-endian float32 samples in band-interleaved-by-pixel order behind a 12-byte dimension header), the German-language acquisition metadata log, and the parameter images the Suite exports alongside each recording (oxygenation, NIR perfusion, tissue haemoglobin and water indices). Requires no vendor SDK and contains no compiled code. Companion to 'cuvis.r', which covers Cubert snapshot cameras, and a data source for 'hyperspectR'. |
| Authors: | R. Heller [aut, cre] (ORCID: <https://orcid.org/0000-0001-8006-9742>) |
| Maintainer: | R. Heller <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-09-21 09:52:08 UTC |
| Source: | https://github.com/CTTIR/tivis.r |
Present for symmetry with cuvis.r::cuvis_available(). TIVITA support is
pure R with no vendor SDK, so this is always TRUE.
tivis_available()tivis_available()
TRUE, invisibly usable in conditionals.
tivis_available()tivis_available()
A small synthetic cube in genuine TIVITA layout, generated by
data-raw/make-fixture.R. It ships with the package so examples, tests and
vignettes run without access to clinical recordings.
tivis_example_file()tivis_example_file()
Path to the bundled *_SpecCube.dat file.
tivis_example_file()tivis_example_file()
Parses a *_meta.log file written beside a TIVITA recording. The Suite
writes an INI-style file with German section and key names, latin1
encoding and comma decimal separators; all three are handled here.
tivis_get_metadata(path)tivis_get_metadata(path)
path |
Path to a |
Numeric-looking values are converted to numbers ("7,000000" becomes
7), TRUE/FALSE become logicals, and surrounding quotes are stripped.
Unrecognised values are returned as trimmed strings.
A named list of sections, each a named list of entries. Returns an empty list if the file does not exist.
log_file <- system.file("extdata", "example_meta.log", package = "tivis.r") if (nzchar(log_file)) str(tivis_get_metadata(log_file))log_file <- system.file("extdata", "example_meta.log", package = "tivis.r") if (nzchar(log_file)) str(tivis_get_metadata(log_file))
The TIVITA Tissue camera samples 500-995 nm in 5 nm steps. The mapping was confirmed empirically: correlating each band against the TIVITA Suite's own greyscale RGB export peaks at band 12, i.e. 555 nm, which is where human photopic luminous efficiency peaks.
tivis_get_wavelengths(n_bands = 100L)tivis_get_wavelengths(n_bands = 100L)
n_bands |
Integer number of bands. Default |
Numeric vector of band centre wavelengths in nanometres.
range(tivis_get_wavelengths())range(tivis_get_wavelengths())
Walks a directory tree and returns one row per recording found. Only headers are read, so scanning a large archive is cheap.
tivis_list_measurements(root, recursive = TRUE)tivis_list_measurements(root, recursive = TRUE)
root |
Directory to search. |
recursive |
Logical. Descend into subdirectories. Default |
A data frame with one row per recording: path, dir, timestamp,
width, height, bands, file_size, and n_reference_images. Zero
rows if nothing matches.
# tivis_list_measurements("/archive/tivita")# tivis_list_measurements("/archive/tivita")
Convenience wrapper returning the cube together with everything the Suite stored alongside it: acquisition metadata and the paths of the exported parameter images.
tivis_measurement(path, bands = NULL)tivis_measurement(path, bands = NULL)
path |
Path to a |
bands |
Optional integer vector of band indices. |
A list with cube, wavelengths, metadata, references,
timestamp and path.
m <- tivis_measurement(tivis_example_file()) dim(m$cube)m <- tivis_measurement(tivis_example_file()) dim(m$cube)
TIVITA names every artefact of a recording YYYY_MM_DD_HH_MM_SS_<what>.
This extracts the acquisition time from such a name.
tivis_parse_timestamp(x)tivis_parse_timestamp(x)
x |
Character vector of file or directory names. |
A POSIXct vector, NA where no timestamp is present.
tivis_parse_timestamp("2019_11_25_13_29_24_SpecCube.dat")tivis_parse_timestamp("2019_11_25_13_29_24_SpecCube.dat")
Reads a *_SpecCube.dat file written by the Diaspective Vision TIVITA
Suite. Unlike Cubert .cu3s session files, the TIVITA container is a plain
binary format, so this package needs no vendor SDK and no compiled code.
tivis_read_cube(path, bands = NULL, validate = TRUE)tivis_read_cube(path, bands = NULL, validate = TRUE)
path |
Path to a |
bands |
Optional integer vector of band indices to read. |
validate |
Logical. Check that the file size matches the header before
reading. Default |
A numeric array with dimensions (rows, cols, bands) — matching the
convention used by hyperspectR::hsi_cube() — carrying a wavelengths
attribute in nanometres.
The format was determined empirically from reference captures and validated
against the TIVITA Suite's own _RGB-Image.png exports:
a 12-byte header of three big-endian uint32 values giving
width, height and bands;
followed by big-endian float32 samples;
stored band-interleaved-by-pixel (BIP): all bands of one pixel are contiguous, pixels run in row-major order (x varies fastest).
Values are calibrated reflectance. They are normally within [0, 1] but may
fall slightly below zero or exceed one in specular and saturated regions, so
the reader does not clamp them.
tivis_read_header() for header-only access,
tivis_get_wavelengths() for the wavelength axis.
f <- tivis_example_file() cube <- tivis_read_cube(f) dim(cube) range(attr(cube, "wavelengths"))f <- tivis_example_file() cube <- tivis_read_cube(f) dim(cube) range(attr(cube, "wavelengths"))
Parses the 12-byte header of a *_SpecCube.dat file without reading the
sample data, which makes it cheap enough to scan large archives.
tivis_read_header(path, validate = TRUE)tivis_read_header(path, validate = TRUE)
path |
Path to a |
validate |
Logical. Verify that the file size equals
|
A named list with width, height, bands, n_values and
file_size.
tivis_read_header(tivis_example_file())tivis_read_header(tivis_example_file())
The TIVITA Suite exports its computed parameter maps as PNGs next to each cube: an RGB rendering plus tissue indices. These are the Suite's own results and are useful as a reference when validating independently computed indices.
tivis_reference_images(path)tivis_reference_images(path)
path |
Path to a |
A named character vector of existing file paths. Names are the
parameter identifiers used by the Suite, for example RGB-Image,
Oxygenation, NIR-Perfusion, THI, TWI, OHI. Zero-length if none
are present.
# tivis_reference_images("/path/to/2019_11_25_13_29_24_SpecCube.dat")# tivis_reference_images("/path/to/2019_11_25_13_29_24_SpecCube.dat")