importFromTif
Imports imaging data from .TIF files.
Description
This function imports imaging data stored in multi-frame .TIF files and saves each imaging channel in a .dat file to be used in umIT. The function reads the TIFF files listed in an info.json file inside a folder (RawFolder) and saves the output files to a SaveFolder. Optional parameters perform spatial and temporal binning. In DataViewer, this function runs from File > Import > from .tif.
Input data format
The RawFolder must contain:
- one or more TIFF files, each an image time series with dimensions Y,X,T(ime) from a single channel. A recording split into several files is imported as one sequence when the files share a base name followed by a number, for example fluo.tif, fluo_1.tif, fluo_2.tif (the file without a number comes first);
- a file named info.json that describes the TIFF files (see below).
The info.json file
info.json holds a list Tiffiles with one entry per channel. Each entry has the following fields:
- filename: name of the TIFF file (or of the first file of a sequence) in the RawFolder;
- FrameRateHz: recording frame rate, in hertz;
- ExposureMsec: illumination exposure, in milliseconds;
- IlluminationColor: name of the imaging channel. It gives the name of the output file (see Output);
- CamIdx (optional): index of the camera, 1 by default.
Other top-level fields of info.json are copied into AcqInfos.mat as acquisition information.
Example of an info.json file for two channels:
{
"Tiffiles": [
{"filename": "img_fluo.tif", "FrameRateHz": 30, "ExposureMsec": 0.1, "IlluminationColor": "Fluo"},
{"filename": "img_red.tif", "FrameRateHz": 30, "ExposureMsec": 0.1, "IlluminationColor": "Red"}
]
} Important
All channels of a recording are imported in one call, and they must have identical frame size, number of frames, FrameRateHz and ExposureMsec. Otherwise the import stops with an error.
Output
One .dat file per entry of Tiffiles, stored in the SaveFolder and named after IlluminationColor in lower case (spaces become underscores; Amber becomes yellow). For example, the entries above create fluo.dat and red.dat. The pixel values are saved in single precision, and the header of each .dat file holds its axes, size, frame rate and exposure (after binning).
The function also writes AcqInfos.mat (the acquisition values before binning, with the binning factors) and records the RawFolder in DataParams.mat. AcqInfos.mat holds no rig information.
Rig
A TIFF import never uses a rig. A SaveFolder without a rig ledger is recorded as "no rig" in its folder rig ledger; a folder that already has a rig binding keeps it. To process the folder with rig-dependent functions such as HemoCompute, bind a rig in DataViewer (Management > Rig > Folder Rig). An invalid folder rig ledger stops the import before any file is written.
Importing into a used Save Folder
An import into a SaveFolder that already holds an import is always a fresh import, also when you only want to add a channel: the files derived from the previous import are deleted (or zipped first, see backupOpts), the rig commitments are reset, and the folder starts again from an empty state. Import all the channels of a recording together. What is deleted and what is kept is described on the ImagesClassification page; the rules are the same.
Parameters
The parameters of this function are the following:
Performs binning on each frame of the imported channels using a bicubic interpolation. The BinningSpatial values represent the scale factor that a frame is divided by. For example, for a recording with original frame size of 1024 by 1024 pixels, a BinningSpatial value of 2 will result in a frame of size 512 by 512 pixels.
A BinningSpatial value of 1 equals to no binning.
Performs binning across frames (i.e. over the time dimension) using a linear interpolation. The BinningTemp values represent the scale factor for the temporal dimension of a recording. For example, for a recording with original frame rate of 10Hz, a BinningTemp value of 2 will reduce the number of frames in half, resulting in a frame rate of 5Hz. The number of frames must be divisible by BinningTemp.
A BinningTemp value of 1 equals to no binning.
Used only when the SaveFolder already holds an import; ignored for an empty SaveFolder. GENBACKUP zips the files to delete into bkp_<date>_<time>.zip in the SaveFolder (the zip is kept) before deleting them; ERASE deletes them without a zip. In a direct MATLAB call, the default is empty (a dialog asks), and any other text is used as the name of the zip file.