Improve documentation related to how Autoscoper loads volumes into its world space.

[NicerNewerCar]

See this comment BrownBiomechanics/SlicerAutoscoperM#97 (comment)

Autoscoper/libautoscoper/src/Volume.cpp

Lines 107 to 139 in 8fe9748

	// Count the number of slices
	int dircount = 0;
	do {
	dircount++;
	} while (TIFFReadDirectory(tif));
	width_ = img.width;
	height_ = img.height;
	depth_ = dircount;
	bps_ = img.bitsPerSample;
	data_ = new unsigned char[width_ * height_ * depth_ * (bps_ / 8)];
	unsigned char* dp = (unsigned char*)data_;
	for (size_t i = 0; i < depth_; ++i) {
	TIFFSetDirectory(tif, i);
	tiffImageRead(tif, &img);
	if (img.width != width_ || img.height != height_ || img.bitsPerSample != bps_) {
	throw std::runtime_error("Unsupported TIFF image format. Non uniform volume slices in " + filename
	+ ".\n"
	"Slice "
	+ std::to_string(i) + " has dimensions " + std::to_string(img.width) + "x"
	+ std::to_string(img.height) + "x" + std::to_string(img.bitsPerSample)
	+ " but expected dimensions is " + std::to_string(width_) + "x" + std::to_string(height_)
	+ "x" + std::to_string(bps_));
	}
	memcpy(dp, img.data, width_ * height_ * (bps_ / 8));
	tiffImageFree(&img);
	dp += width_ * height_ * (bps_ / 8);
	}
	TIFFClose(tif);

Autoscoper/libautoscoper/src/TiffImage.cpp

Lines 115 to 162 in 8fe9748

	int tiffImageRead(TIFF* tif, TiffImage* img)
	{
	if (!tiffImageReadMeta(tif, img)) {
	return 0;
	}
	// Allocate buffer for image data.
	img->dataSize = img->height * (size_t)TIFFRasterScanlineSize(tif);
	img->data = malloc(img->dataSize);
	if (!img->data) {
	printf("Unable to allocate space for image (%lu bytes).\n", img->dataSize);
	return 0;
	}
	if (img->planarConfig != PLANARCONFIG_CONTIG) {
	printf("Support for planar data has not yet been implemented.\n");
	free(img->data);
	return 0;
	}
	if (TIFFIsTiled(tif)) {
	return tiffReadContigTiledData(tif, (uint8_t*)img->data, img->width, img->height, img->samplesPerPixel);
	} else {
	return tiffReadContigStrippedData(tif, (uint8_t*)img->data, img->width, img->height, img->samplesPerPixel);
	}
	}
	TiffImage* tiffImageCopy(TiffImage* img)
	{
	TiffImage* copy = (TiffImage*)malloc(sizeof(TiffImage));
	if (!copy) {
	printf("Unable to allocate space for TiffImage struct.\n");
	return 0;
	}
	memcpy(copy, img, sizeof(TiffImage));
	// Allocate buffer for image data.
	img->data = malloc(img->dataSize);
	if (!img->data) {
	printf("Unable to allocate space for image (%lu bytes).\n", img->dataSize);
	return 0;
	}
	memcpy(copy->data, img->data, img->dataSize);
	return copy;
	}

[NicerNewerCar]

Loading in the same volume in both Autoscoper and Slicer. Both are placed at the origin. Autoscoper: Red: +X, Green: +Y, Blue: +Z. Origin is at the center of the XZ plane pictured. Slicer: R: +X, A: +Y, S +Z. Origin is denoted by the red markup. I tried to get similar angles (relative to the axes) for the screenshots. After the Y/Z Flip the volume, within slicer, is now in the same orientation as the volume in Autoscoper, just on the wrong side of the origin. So we can apply an offset in the X direction to account for this.

	Autoscoper	Slicer
Loaded in
Flip Y/Z in Slicer
X offset

[NicerNewerCar]

@amymmorton @jcfr Starting to workshop a diagram to showcase all of the transforms within the pre-processing module.
This will be followed up with a brief summary of what each transform is and where it gets generated.

A couple of changes that will need to go in for this:

• Rename the volume name transforms to be Slicer2{volumeName}
• Rename the Origin2Dicom to be Slicer2Dicom
• Put together Dicom2{volumeName} transforms

Let me know if there is anything else you would like to see.

I also had a couple of questions:

1. Where this should reside within the RTD? I was thinking under the advanced topics category.
2. Standardize on 2 or To?
3. Are all of the space names okay? Slicer, Dicom, {volumeName}, Autoscoper Or did you have any other suggestions?

[amymmorton]

We need to make sure that we are consitent with previous bvr processing and scalable to 3dct/4dct.

Historical bvr:
*established *
-{volumeName}.tfm == partial volume tiff stacks to their dicom origin
-{pose_volumeName}.tra == transform of {AUT_volumeName} model file(representative of partialvolume) from AUTCS to optimized location in target frame

*established -- but not yet created in preprocessing flow:

• {AUT_volumeName}.stl == stl model of {volumeName} scaled by voxel resolution and oriented as AUT interprets the tiff
  in matlab the eq is

y_sz = size(volumeName.tif,1) * inv(volumeName.tfm)(1,1) ;
CT_to_AUT_4x4 = RT_to_fX4(eul2rotm([0,0,pi]),[0 y_sz 0]);
{AUT_volumeName}.stl = RT_transform(PVOL_volumeName.stl, CT_to_AUT_4x4(1:3,1:3), CT_to_AUT_4x4(1:3,4),1);

where PVOL_volumeName.stl == segmented volumeName.stl in dicom space * 'translation from inv(volumeName.tfm)

The additional complexity of the vrgs has to be compatible with this bvr cs convention