createRegistrationTform
Estimate and store a 2-D transform that aligns one Save Folder image to its reference image.
Description
The function takes the reference image from ReferenceSource or, for a folder bound to a project, from the subject's active Image Reference (a project is not required). It then selects a moving .dat, reduces its Y-X-T data to one image (computed in X slabs, so the whole recording is never loaded into memory), estimates a similarity transform, calculates advisory quality-control metrics, and updates DataParams.mat: the reference image and where it came from, and the estimated transform.
An aligned folder is refused (Umitoolbox:ImageRegistration:alreadyAligned): after apply, only a fresh import of the raw data allows a new alignment. Without a reference source, the function stops with Umitoolbox:ImageRegistration:noReferenceSource, which explains both ways to supply one.
No .dat samples are changed.
This function estimates and stores a candidate only. Use applyRegistrationTformOnFolder separately after visual review.
Input
SaveFolder must contain valid DataParams.mat, AcqInfos.mat, and one or more eligible .dat files. The moving file must be a Y-X-T .dat; a file with any other layout is refused with an unsupportedLayout error.
Output
outFile is a file manifest containing the updated DataParams.mat and timestamped QC .fig and .png files.
Quality control
The timestamped QC figure shows the filtered reference, the filtered moving image, the registered moving image, and an overlay. Inspect matching vessels or other stable anatomy, along with the field-of-view borders. The numeric values below are stored in DataParams.registration.qcMetrics; the summary is stored in qcStatus and qcWarning.
| Metric | How to interpret it |
|---|---|
| MIBefore | Mutual information between the filtered reference and moving images before registration. It is a baseline similarity value, not a pass/fail score. |
| MIAfter | Mutual information after applying the estimated transform. Compare it with MIBefore; values from different recordings are not directly graded against one universal threshold. |
| MIDelta | MIAfter - MIBefore. A positive value means this metric improved. A non-finite or non-positive value sets review_recommended. |
| translationXY_px | X and Y displacement in pixels. A maximum component greater than 20% of the image diagonal triggers a review warning. Large values may be valid, but often indicate mismatched fields of view. |
| rotationDeg | Estimated in-plane rotation. An absolute rotation above 15 degrees triggers a review warning. |
| scaleXY | X/Y scale, where 1 means no scaling. A deviation greater than 10% from 1 on either axis triggers a review warning. |
| determinant | Area scaling of the transform's linear component. For an ordinary similarity transform it should be positive and consistent with the reported scale; unexpected values deserve visual review. |
estimated_not_reviewed means none of the automatic warning conditions fired; it does not mean the registration has been accepted. review_recommended means one or more conditions fired and the reason is recorded in qcWarning.
Parameters
The reference image. A path to a .dat file of another UMIT Save Folder uses the mean of up to 100 evenly spaced frames of that file; any other path is a reference file (exported by UMIT, or a TIF, MAT or UMT image). With the default '', a folder bound to a project uses the subject's active Image Reference; an unbound folder is refused (noReferenceSource). In a pipeline, pass the path as a parameter so that every folder of a batch is aligned to the same reference.
auto uses the .dat file named by the reference's source when the current Save Folder has a file with that name. For example, a reference created from green.dat makes auto register the current folder's green.dat, even if derived files such as GSR.dat are also present. Otherwise it uses the folder's only Y-X-T .dat file. It never guesses between channels: when several Y-X-T files qualify, it stops with Umitoolbox:createRegistrationTform:AutoSourceFileAmbiguous, and when there is none, with AutoSourceFileNotFound; pass an explicit .dat filename then. The selected file must be a Y-X-T .dat.
When false, the same QC figure and PNG are generated invisibly for non-interactive processing.
Chooses the statistic used to collapse the Y-X-T file into the 2-D moving image. It is computed in X slabs sized from the available memory, so the whole recording is never loaded at once. If needed, that image is resized to the reference size before registration.
QC metrics are advisory.
Inspect anatomical alignment and borders visually. A higher mutual-information value does not guarantee a scientifically acceptable transform.