TVIPS format#

The .tvips format is the default format for image series collected by pixelated cameras from the TVIPS company. Typically individual images captured by these cameras are stored in the TIFF format which can also be loaded by RosettaSciIO. This format instead serves to store image streams from in-situ and 4D-STEM experiments. During collection, the maximum file size is typically capped meaning the dataset is typically split over multiple files ending in _xyz.tvips. The _000.tvips will contain the main header and it is essential for loading the data. If a filename is provided for loading or saving without a _000 suffix, this will automatically be added. Loading will not work if no such file is found.

Warning

While .tvips files are supported, it is a proprietary format, and future versions of the format might therefore not be readable. Complete interoperability with the official software can neither be guaranteed.

Warning

The .tvips format currently stores very limited amount of metadata about scanning experiments. To reconstruct scan data, e.g. 4D-STEM datasets, parameters like the shape and scales of the scan dimensions should be manually recorded.

API functions#

rsciio.tvips.file_reader(filename, lazy=False, scan_shape=None, scan_start_frame=0, winding_scan_axis=None, hysteresis=0, rechunking='auto')#

Read TVIPS stream file for in-situ and 4D STEM data.

Parameters:
filenamestr, pathlib.Path

Filename of the file to read or corresponding pathlib.Path.

lazybool, default=False

Whether to open the file lazily or not. The file will stay open until closed in compute() or closed manually. get_file_handle() can be used to access the file handler and close it manually.

scan_shapestr or tuple of int or None, optional

By default the data is loaded as an image stack (1 navigation axis). A tuple of integers can be provided to indicate the shape of the navigation axes. For example, (3, 4) will have 3 scan points in the y direction and 4 in the x direction. If it concerns a 4D-STEM dataset, the (…, scan_y, scan_x) dimension can be provided. "auto" can also be selected, in which case the rotidx information in the frame headers will be used to try to reconstruct the scan. Additional navigation axes must be prepended. Since this only works for square scan grids and is prone to failure, this option is not recommended.

scan_start_frameint, optional

Index of the first frame of the dataset to consider. Mainly relevant for 4D-STEM datasets.If scan_shape = "auto" this is ignored.

winding_scan_axisstr, optional

If the acquisition software collected data without beam flyback but with a winding “snake” scan, then every second scan row or column needs to be reversed to make sense of the data. This can be indicated with values "x" or "y", depending on whether winding happened along the primary or secondary axis. By default, flyback scan without winding is assumed with x the fast scan and y the slow scan direction.

hysteresisint, optional

Only applicable if winding_scan_axis is not None, as it is likely there is an overshoot of a few pixels (2-5) every second scan row. This parameter allows shifts every second row by the indicated number of scan points to align even and odd scan rows. Default is 0, no hysteresis.

rechunkingbool, str, dict, Default=”auto”

Only relevant when using lazy loading. If set to False each tvips file is a single chunk. For a better experience, with the default setting of "auto" rechunking is performed such that the navigation axes are optimally chunked and the signal axes are not chunked. If set to anything else, e.g. a dictionary, the value will be passed to the chunks argument in dask.array.rechunk.

Returns:
list of dict

List of dictionaries containing the following fields:

  • ‘data’ – multidimensional numpy.ndarray or dask.array.Array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the parsed metadata

  • ‘original_metadata’ – dictionary containing the full metadata tree from the input file

When the file contains several datasets, each dataset will be loaded as separate dictionary.

rsciio.tvips.file_writer(filename, signal, max_file_size=None, version=2, frame_header_extra_bytes=0, mode=None, show_progressbar=True)#

Write signal to TVIPS file.

Parameters:
filenamestr, pathlib.Path

Filename of the file to write to or corresponding pathlib.Path.

signaldict

Dictionary containing the signal object. Should contain the following fields:

  • ‘data’ – multidimensional numpy array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the metadata tree

max_file_sizeint or None, default=None

Approximate maximum size of individual files in bytes. In this way a dataset can be split into multiple files. A file needs to be at least the size of the main header in the first file plus one frame and its frame header. Sequential files are denoted by a suffix _xxx starting from _000. By default (None) there is no maximum and the entire dataset is stored in a single file.

versionint, default=2

TVIPS file format version (only version 1 or 2 supported).

frame_header_extra_bytesint, default=0

Number of bytes to pad the frame headers with.

modeint or None, default=None

1 for imaging, 2 for diffraction. By default, the mode is guessed from signal type and signal units.

show_progressbarbool, default=True

Whether to show the progressbar or not.