This PR implements transforming meshes and PPMs between volume coordinate frames when using the various render applications.
Getting started
First, you need a transform JSON file (support added in #65) which maps from a source volume to a target volume. At the time of this writing, we only support affine transforms. Place transform JSON files in *.volpkg/transforms/:
source: the Volume UUID for the input coordinate space (from)
target: the Volume UUID for the output coordinate space (to)
params: A row major, 4x4 transform matrix
Applying the transform (automatic)
When working with segmentations, the transform is automatically applied when (1) you provide the --volume flag, (2) the provided volume is not the same as the segmentation's associated volume, and (3) there is a transform mapping from the associated volume to the target volume:
For all invertible transform types (which includes affine transforms), we will also automatically invert the transform if the requested source and target volumes are the swapped equivalent of a transform's source and target.
# same transform as above inverted to map from 20230905121646 -> 20230205180739
vc_render -v Foo.volpkg -s 20231121150010 --volume 20230205180739
In the future, we plan to extend this automatic functionality to find a composite transform which maps between the source and target using multiple transforms.
Applying the transform (manual)
Of course, sometimes you need to manually specify a transform, either because the source volume can't be determined automatically or because you just want to have greater control over the transform being used. In this case, the --transform flag will let you select from a transform in the Volume Package or on disk:
Note: Specifying the transform manually does not set the target volume, but only transforms the 3D geometry. The default volume for the given input will still be used for rendering unless you also specify the --volume flag.
Controlling what gets transformed
By default, the transform is applied to the raw input mesh before any resampling or smoothing. You can change when the transform is applied using the --apply-transform-to flag. This flag has subtle but important effects on the output depending on the provided option:
raw: The transform will be applied to the mesh immediately after loading or meshing. Mesh resampling will be performed in the target volume space, which will have an effect on the automatic resampling factor. The final mesh will be very similar to a native segmentation created in the target volume.
resampled: The transform will be applied to the mesh after resampling. The mesh will be resampled in source volume space, could result in output meshes which are too dense or too sparse for the resolution of the target volume.
PPM: The transform will be applied to the points and normals stored in the PPM. This will produce a texture image that has the same dimensions as the texture rendered using the source volume, but will be filtered with the target volume's voxels. This is useful when you want to draw apples-to-apples comparisons between volumes and want the texture space to line-up.
Controlling the transform
A number of extra flags control the transform that is applied to the geometry:
--invert-transform: Inverts the loaded transform. Note that if an inverted transform was automatically loaded, this will invert back to the original transform.
--disable-transform: Disable all transform actions, including the manually specified --transform flag.
App support
The following programs support transforms:
vc_render: Full support
vc_*_from_ppm: Supports --transform and --invert-transform
Other changes
(core) Introduce VolPkg v7 with support for Transform3D and .vckeep files in required directories.
(core) VolPkg now auto-upgrades from v6 on load. VolPkgs with older versions still need to use vc_volpkg_upgrade. As a consequence, move upgrade code to VolumePkg.cpp.
(core) VolPkg will now automatically create missing required directories on load.
(core) Fix logging bug in UVMap::AlignToAxis.
(graph) Add various transform nodes,
(apps) vc_volpkg_explorer now lists transforms.
(apps) Use VOLPKG_MIN_VERSION instead of exact version and standardize the error message.
This PR implements transforming meshes and PPMs between volume coordinate frames when using the various render applications.
Getting started
First, you need a transform JSON file (support added in #65) which maps from a source volume to a target volume. At the time of this writing, we only support affine transforms. Place transform JSON files in
*.volpkg/transforms/:The important fields are:
source: the Volume UUID for the input coordinate space (from)target: the Volume UUID for the output coordinate space (to)params: A row major, 4x4 transform matrixApplying the transform (automatic)
When working with segmentations, the transform is automatically applied when (1) you provide the
--volumeflag, (2) the provided volume is not the same as the segmentation's associated volume, and (3) there is a transform mapping from the associated volume to the target volume:For all invertible transform types (which includes affine transforms), we will also automatically invert the transform if the requested source and target volumes are the swapped equivalent of a transform's source and target.
In the future, we plan to extend this automatic functionality to find a composite transform which maps between the source and target using multiple transforms.
Applying the transform (manual)
Of course, sometimes you need to manually specify a transform, either because the source volume can't be determined automatically or because you just want to have greater control over the transform being used. In this case, the
--transformflag will let you select from a transform in the Volume Package or on disk:Note: Specifying the transform manually does not set the target volume, but only transforms the 3D geometry. The default volume for the given input will still be used for rendering unless you also specify the
--volumeflag.Controlling what gets transformed
By default, the transform is applied to the raw input mesh before any resampling or smoothing. You can change when the transform is applied using the
--apply-transform-toflag. This flag has subtle but important effects on the output depending on the provided option:raw: The transform will be applied to the mesh immediately after loading or meshing. Mesh resampling will be performed in the target volume space, which will have an effect on the automatic resampling factor. The final mesh will be very similar to a native segmentation created in the target volume.resampled: The transform will be applied to the mesh after resampling. The mesh will be resampled in source volume space, could result in output meshes which are too dense or too sparse for the resolution of the target volume.PPM: The transform will be applied to the points and normals stored in the PPM. This will produce a texture image that has the same dimensions as the texture rendered using the source volume, but will be filtered with the target volume's voxels. This is useful when you want to draw apples-to-apples comparisons between volumes and want the texture space to line-up.Controlling the transform
A number of extra flags control the transform that is applied to the geometry:
--invert-transform: Inverts the loaded transform. Note that if an inverted transform was automatically loaded, this will invert back to the original transform.--disable-transform: Disable all transform actions, including the manually specified--transformflag.App support
The following programs support transforms:
vc_render: Full supportvc_*_from_ppm: Supports--transformand--invert-transformOther changes
Transform3Dand.vckeepfiles in required directories.vc_volpkg_upgrade. As a consequence, move upgrade code toVolumePkg.cpp.UVMap::AlignToAxis.vc_volpkg_explorernow lists transforms.VOLPKG_MIN_VERSIONinstead of exact version and standardize the error message.