createRegistrationTform
Estimate and store a 2-D transform that aligns one Save Folder image to its reference image.
Description
The Save Folder must be project-bound, and its subject must have an active project-managed Image Reference. The function 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.
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
auto uses the same signal as the active Image Reference: it reads ImageReference.sourceFile, takes that source's .dat filename, and requires a file with the same name in the current Save Folder. 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. It does not fall back to another .dat. If the reference has no source filename, its source is not a .dat, or the matching file is absent, recreate the reference with source provenance or supply an explicit .dat filename. 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.