Document/enforce that -vertfile and -i are in the same voxel coordinate system

[jcohenadad]

Currently the usage says:

  -vertfile <str>       Vertebral labeling file. Only use with flag -vert (default: ./label/template/PAM50_levels.nii.gz)

We need to check (look into the code) if the input file is transformed into the same voxel coordinate system as the input image, or if it is not.

And depending on the answer, we need to specify in the usage what is expected from this input vertfile.

The same comment applies to:

• sct_extract_metric
• sct_process_segmentation

[yanchunCoBIUS]

Code check:

In the code, the details are in the following:

• sct_extract_metric.py:
  • Both input(-i) and vertebral labelling file (-vertfile) have the same coordinate system: RPI
    • Input: input_im = Image(fname_data).change_orientation("RPI")
    • Vertebral labeling file: im_vertebral_labeling = Image(fname_vertebral_labeling).change_orientation("RPI")
  • Not checking dimensions between input(-i) and vertebral labelling file (-vertfile).
• sct_process_segmentation.py:
  • similar to sct_extract_metric.py.
  • Both input(-i) and vertebral labelling file (-vertfile) have the same coordinate system: RPI
  • Not checking dimensions between input(-i) and vertebral labelling file (-vertfile).

Questions:

Do I need to do some test for dimensions between input(-i) and vertebral labelling file (-vertfile), similar to the following check between atlas and data?

# Check dimensions consistency between atlas and data
    if (nx, ny, nz) != (nx_atlas, ny_atlas, nz_atlas):
        printv('\nERROR: Metric data and labels DO NOT HAVE SAME DIMENSIONS.', 1, type='error')

[jcohenadad]

Do I need to do some test for dimensions between input(-i) and vertebral labelling file (-vertfile), similar to the following check between atlas and data?

Good question-- it depends how the information from the fname_vertebral_labeling file is retrieve-- if it is retrieved from the matrix directly (Image.data()), it means that it is in the voxel space, and in that case, yes, the dimensions between the input and the vertebral labeling file must match.

If it is retrieve from the "physical" coordinate system (ie: using the affine transformation in the header), then it is not necessary-- but it doubt it is the case...

[joshuacwnewton]

In #3120, we partially address this issue by throwing an error in the API when the -vertfile and the metric (calculated from -i) have mismatched # of slices.

spinalcordtoolbox/spinalcordtoolbox/aggregate_slicewise.py

Lines 235 to 240 in 269018a

	if vert_level:
	vert_level_slices = Image(vert_level).change_orientation('RPI').data.shape[2]
	metric_slices = metric.data.shape[0]
	if vert_level_slices != metric_slices:
	raise ValueError(f"Shape mismatch between vertfile [{vert_level_slices}] and metric [{metric_slices}]). "
	f"Please verify that your vertfile has the same number of slices as your input image.")

However, as @jcohenadad points out in #3120 (comment), this check might be too shallow, so a deeper verification could be done instead.

the test could be made more sensitive. e.g., if a user inputs a vertebral level file from another region/subject/whatever that happens to have the same number of slices as the metric, processing will go on but will be wrong. Alternatively, the qform and XYZ dimensions of the image header could be compared (ie: to make sure both volumes are in the exact same coordinate system).