(VolPkg) Add support for transform paths (#94)

apps/src/Render.cpp

@@ -521,7 +521,7 @@ auto main(int argc, char* argv[]) -> int
         // Ask the volume package for transforms
         auto tfms = vpkg->transform(srcVolId, tgtVolId);
         useTfm = tfmIdInVpkg = not tfms.empty();
-        tfmId = (tfmIdInVpkg) ? tfms[0].first : "";
+        tfmId = tfmIdInVpkg ? tfms[0].first : "";
 
         // Report no and multiple transforms
         if (tfms.empty()) {

cmake/Buildlibcore.cmake

@@ -0,0 +1,7 @@
+FetchContent_Declare(
+    libcore
+    GIT_REPOSITORY https://github.com/educelab/libcore.git
+    GIT_TAG 3fa81bd
+    EXCLUDE_FROM_ALL
+)
+FetchContent_MakeAvailable(libcore)

cmake/VCFindDependencies.cmake

@@ -81,6 +81,9 @@ include(Buildbvh)
 ### smgl ###
 include(Buildsmgl)
 
+### libcore ###
+include(Buildlibcore)
+
 ### Boost and indicators (for app use only)
 if(VC_BUILD_APPS OR VC_BUILD_UTILS)
     find_package(Boost 1.58 REQUIRED COMPONENTS system program_options)

core/CMakeLists.txt

@@ -82,6 +82,7 @@ add_library(VC::core ALIAS vc_core)
 target_include_directories(vc_core
     PUBLIC
         $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<BUILD_INTERFACE:${libcore_SOURCE_DIR}/include>
         $<INSTALL_INTERFACE:include>
 )
 target_link_libraries(vc_core
@@ -177,6 +178,7 @@ set(test_srcs
     test/TIFFIOTest.cpp
     test/TransformsTest.cpp
     test/SegmentationTest.cpp
+    test/VolumePkgTest.cpp
 )
 
 # Add a test executable for each src

core/include/vc/core/types/Transforms.hpp

@@ -4,8 +4,10 @@
 
 #include <cstddef>
 #include <iostream>
+#include <list>
 #include <memory>
 #include <string>
+#include <vector>
 
 #include <nlohmann/json.hpp>
 #include <opencv2/core.hpp>
@@ -185,8 +187,7 @@ class Transform3D
      * Implementing derived classes should set the returned transform's source
      * to this->source() and the target to rhs->target().
      */
-    [[nodiscard]] virtual auto compose_(const Transform3D::Pointer& rhs) const
-        -> Transform3D::Pointer;
+    [[nodiscard]] virtual auto compose_(const Pointer& rhs) const -> Pointer;
 
     /** On-disk metadata type */
     using Metadata = nlohmann::ordered_json;
@@ -312,7 +313,7 @@ class AffineTransform : public Transform3D
      * Convenience function for `cv::Vec` types.
      */
     template <typename Tp, int Cn>
-    void rotate(double angle, cv::Vec<Tp, Cn> axis)
+    void rotate(const double angle, cv::Vec<Tp, Cn> axis)
     {
         static_assert(Cn >= 3, "cv::Vec must have >= 3 values");
         rotate(angle, axis[0], axis[1], axis[2]);
@@ -328,7 +329,7 @@ class AffineTransform : public Transform3D
     /** Don't allow construction on the stack */
     AffineTransform() = default;
     /** Current parameters */
-    Parameters params_{cv::Matx<double, 4, 4>::eye()};
+    Parameters params_{Parameters::eye()};
     /** @copydoc Transform3D::compose_() */
     [[nodiscard]] auto compose_(const Transform3D::Pointer& rhs) const
         -> Transform3D::Pointer final;
@@ -458,6 +459,15 @@ class CompositeTransform : public Transform3D
     [[nodiscard]] auto applyVector(const cv::Vec3d& vector) const
         -> cv::Vec3d final;
 
+    /**
+     * @brief Add a transform to the front of the composite transform stack
+     *
+     * The transform is cloned before being added to the transform stack. If
+     * the transform is also a CompositeTransform, its transform stack is
+     * expanded and copied to the front of this transform's stack.
+     */
+    void push_front(const Transform3D::Pointer& t);
+
     /**
      * @brief Add a transform to the end of the composite transform stack
      *
@@ -479,11 +489,14 @@ class CompositeTransform : public Transform3D
      */
     void simplify();
 
+    /** @brief Get a list of the stored transforms */
+    [[nodiscard]] auto transforms() const -> std::vector<Transform3D::Pointer>;
+
 private:
     /** Don't allow construction on the stack */
     CompositeTransform() = default;
     /** Transform list */
-    std::vector<Transform3D::Pointer> tfms_;
+    std::list<Transform3D::Pointer> tfms_;
     /** @copydoc Transform3D::to_meta_() */
     void to_meta_(Metadata& meta) final;
     /** @copydoc Transform3D::from_meta_() */

core/include/vc/core/types/VolumePkg.hpp

@@ -45,17 +45,17 @@ class VolumePkg
      * be written to and accessed. Only metadata keys may be modified before
      * initialize is called.
      *
-     * @param fileLocation The location to store the VolPkg
+     * @param path The location to store the VolPkg
      * @param version Version of VolumePkg you wish to construct
      */
-    VolumePkg(filesystem::path fileLocation, int version);
+    VolumePkg(filesystem::path path, int version);
 
     /**
      * @brief Construct a VolumePkg from a .volpkg file stored at
      * `fileLocation.`
-     * @param fileLocation The root of the VolumePkg file
+     * @param path The root of the VolumePkg file
      */
-    explicit VolumePkg(const filesystem::path& fileLocation);
+    explicit VolumePkg(const filesystem::path& path);
 
     /** VolumePkg shared pointer */
     using Pointer = std::shared_ptr<VolumePkg>;
@@ -65,14 +65,15 @@ class VolumePkg
      *
      * Returns a shared pointer to the VolumePkg.
      */
-    static auto New(filesystem::path fileLocation, int version) -> Pointer;
+    static auto New(const filesystem::path& fileLocation, int version)
+        -> Pointer;
 
     /**
      * @copybrief VolumePkg(filesystem::path fileLocation)
      *
      * Returns a shared pointer to the VolumePkg.
      */
-    static auto New(filesystem::path fileLocation) -> Pointer;
+    static auto New(const filesystem::path& fileLocation) -> Pointer;
     /**@}*/
 
     /** @name Metadata */
@@ -132,13 +133,13 @@ class VolumePkg
     /**
      * @brief Saves the metadata to the VolumePkg (.volpkg) file.
      */
-    void saveMetadata();
+    void saveMetadata() const;
 
     /**
      * @brief Saves the metadata to a user-specified location.
      * @param filePath Path to output file
      */
-    void saveMetadata(const filesystem::path& filePath);
+    void saveMetadata(const filesystem::path& filePath) const;
     /**@}*/
 
     /** @name Volume Data */
@@ -254,10 +255,13 @@ class VolumePkg
      * VolumePkg
      *
      * If the provided identifier ends with "*", additionally checks if the
-     * transform can be inverted.
+     * transform can be inverted. Supports transform paths using the `->`
+     * operator.
+     *
+     * @see VolumePkg::transform(Transform3D::Identifier)
      */
-
-    [[nodiscard]] auto hasTransform(Volume::Identifier id) const -> bool;
+    [[nodiscard]] auto hasTransform(const Transform3D::Identifier& id) const
+        -> bool;
 
     /** @brief Add a transform to the VolPkg */
     auto addTransform(const Transform3D::Pointer& transform)
@@ -271,17 +275,37 @@ class VolumePkg
     /**
      * @brief Get a transform by ID
      *
-     * If the provided identifier ends with "*", returns the inverse transform.
+     * If the provided ID ends with `*`, returns the inverse transform.
+     * Transform paths can be constructed with the `->` operator and will be
+     * returned as a composite transform:
+     * ```{.cpp}
+     * vpkg->transform("id1->id2->id3*");
+     * ```
+     * The source and target properties of the returned CompositeTransform is
+     * set to the source of the first transform and the target of the final
+     * transform (post-inversion), but the intermediate path is not verified.
      */
-    auto transform(Transform3D::Identifier id) -> Transform3D::Pointer;
+    [[nodiscard]] auto transform(Transform3D::Identifier id) const
+        -> Transform3D::Pointer;
 
     /**
-     * @brief Get a list of transforms which map from a source volume to a
-     * target volume
+     * @brief Get a list of transforms (possibly composite transforms) which
+     * map from a source volume to a target volume
+     *
+     * Runs breadth-first search (BFS) to find the shortest transform paths
+     * from the source to target volume. Single-transform paths are returned
+     * as their original transform type (e.g. AffineTransform,
+     * IdentityTransform). Multi-transform paths are returned as a new,
+     * unsimplified CompositeTransform. Paths are returned in order of
+     * increasing length and may include inverse transforms which satisfy the
+     * mapping.
      *
-     * The list also includes inverse transforms which satisfy the mapping.
+     * The current implementation does not return _all_ transform paths, but
+     * prunes cycles and paths which would use transforms that are already part
+     * of a shorter path.
      */
-    auto transform(const Volume::Identifier& src, const Volume::Identifier& tgt)
+    [[nodiscard]] auto transform(
+        const Volume::Identifier& src, const Volume::Identifier& tgt) const
         -> std::vector<
             std::pair<Transform3D::Identifier, Transform3D::Pointer>>;