[c++] Add SOMAMultiscaleImage class (#3094)

Add `SOMAMultiscaleImage` to `libtiledbsoma`.

libtiledbsoma/src/CMakeLists.txt

@@ -32,6 +32,7 @@ add_library(TILEDB_SOMA_OBJECTS OBJECT
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_collection.cc
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_experiment.cc
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_measurement.cc
+  ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_multiscale_image.cc
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_context.cc
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_dataframe.cc
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_dense_ndarray.cc
@@ -131,6 +132,7 @@ endif()
 #   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/soma_dense_ndarray.h
 #   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/soma_experiment.h
 #   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/soma_measurement.h
+#   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/soma_multiscale_image.h
 #   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/soma_object.h
 #   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/soma_sparse_ndarray.h
 #   ${CMAKE_CURRENT_SOURCE_DIR}/cpp_api/logger_public.h
@@ -151,6 +153,7 @@ install(FILES
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_sparse_ndarray.h
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_experiment.h
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_measurement.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_multiscale_image.h
   ${CMAKE_CURRENT_SOURCE_DIR}/soma/soma_object.h
   DESTINATION "include/tiledbsoma/soma"
 )

libtiledbsoma/src/soma/soma_multiscale_image.cc

@@ -0,0 +1,68 @@
+/**
+ * @file   soma_multiscale_image.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ *   This file defines the SOMAMultiscaleImage class.
+ */
+
+#include "soma_multiscale_image.h"
+#include "soma_collection.h"
+
+namespace tiledbsoma {
+using namespace tiledb;
+
+//===================================================================
+//= public static
+//===================================================================
+
+void SOMAMultiscaleImage::create(
+    std::string_view uri,
+    std::shared_ptr<SOMAContext> ctx,
+    std::optional<TimestampRange> timestamp) {
+    try {
+        std::filesystem::path image_uri(uri);
+        SOMAGroup::create(
+            ctx, image_uri.string(), "SOMAMultiscaleImage", timestamp);
+    } catch (TileDBError& e) {
+        throw TileDBSOMAError(e.what());
+    }
+}
+
+std::unique_ptr<SOMAMultiscaleImage> SOMAMultiscaleImage::open(
+    std::string_view uri,
+    OpenMode mode,
+    std::shared_ptr<SOMAContext> ctx,
+    std::optional<TimestampRange> timestamp) {
+    try {
+        return std::make_unique<SOMAMultiscaleImage>(mode, uri, ctx, timestamp);
+    } catch (TileDBError& e) {
+        throw TileDBSOMAError(e.what());
+    }
+}
+
+}  // namespace tiledbsoma

libtiledbsoma/src/soma/soma_multiscale_image.h

@@ -0,0 +1,105 @@
+/**
+ * @file   soma_multiscale_image.h
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ *   This file defines the SOMAMultiscaleImage class.
+ */
+
+#ifndef SOMA_MULTISCALE_IMAGE
+#define SOMA_MULTISCALE_IMAGE
+
+#include <tiledb/tiledb>
+
+#include "soma_collection.h"
+
+namespace tiledbsoma {
+
+using namespace tiledb;
+class SOMAMultiscaleImage : public SOMACollection {
+   public:
+    //===================================================================
+    //= public static
+    //===================================================================
+
+    /**
+     * @brief Create a SOMAMultiscaleImage object at the given URI.
+     *
+     * @param uri URI to create the SOMAMultiscaleImage
+     * @param schema TileDB ArraySchema
+     * @param platform_config Optional config parameter dictionary
+     */
+    static void create(
+        std::string_view uri,
+        std::shared_ptr<SOMAContext> ctx,
+        std::optional<TimestampRange> timestamp = std::nullopt);
+
+    /**
+     * @brief Open a group at the specified URI and return SOMAMultiscaleImage
+     * object.
+     *
+     * @param uri URI of the array
+     * @param mode read or write
+     * @param ctx TileDB context
+     * @param timestamp Optional pair indicating timestamp start and end
+     * @return std::shared_ptr<SOMAMultiscaleImage> SOMAMultiscaleImage
+     */
+    static std::unique_ptr<SOMAMultiscaleImage> open(
+        std::string_view uri,
+        OpenMode mode,
+        std::shared_ptr<SOMAContext> ctx,
+        std::optional<TimestampRange> timestamp = std::nullopt);
+
+    //===================================================================
+    //= public non-static
+    //===================================================================
+
+    SOMAMultiscaleImage(
+        OpenMode mode,
+        std::string_view uri,
+        std::shared_ptr<SOMAContext> ctx,
+        std::optional<TimestampRange> timestamp = std::nullopt)
+        : SOMACollection(mode, uri, ctx, timestamp) {
+    }
+
+    SOMAMultiscaleImage(const SOMACollection& other)
+        : SOMACollection(other) {
+    }
+
+    SOMAMultiscaleImage() = delete;
+    SOMAMultiscaleImage(const SOMAMultiscaleImage&) = default;
+    SOMAMultiscaleImage(SOMAMultiscaleImage&&) = default;
+    ~SOMAMultiscaleImage() = default;
+
+   private:
+    //===================================================================
+    //= private non-static
+    //===================================================================
+};
+}  // namespace tiledbsoma
+
+#endif  // SOMA_MULTISCALE_IMAGE

libtiledbsoma/src/soma/soma_object.cc

@@ -8,6 +8,7 @@
 #include "soma_dense_ndarray.h"
 #include "soma_experiment.h"
 #include "soma_measurement.h"
+#include "soma_multiscale_image.h"
 #include "soma_sparse_ndarray.h"
 
 namespace tiledbsoma {
@@ -87,8 +88,7 @@ std::unique_ptr<SOMAObject> SOMAObject::open(
             throw TileDBSOMAError(
                 "Support for SOMAScene is not yet implemented.");
         } else if (group_type == "somamultiscaleimage") {
-            throw TileDBSOMAError(
-                "Support for SOMAMultiscaleImage is not yet implemented.");
+            return std::make_unique<SOMAMultiscaleImage>(*group_);
         } else {
             throw TileDBSOMAError("Saw invalid SOMAGroup type");
         }

libtiledbsoma/src/tiledbsoma/tiledbsoma

@@ -53,6 +53,7 @@
 #include "soma/soma_group.h"
 #include "soma/soma_experiment.h"
 #include "soma/soma_measurement.h"
+#include "soma/soma_multiscale_image.h"
 #include "soma/soma_object.h"
 #include "soma/soma_dataframe.h"
 #include "soma/soma_dense_ndarray.h"

libtiledbsoma/test/CMakeLists.txt

@@ -27,6 +27,7 @@ add_executable(unit_soma
     unit_soma_dense_ndarray.cc
     unit_soma_sparse_ndarray.cc
     unit_soma_collection.cc
+    unit_soma_multiscale_image.cc
     test_indexer.cc
 # TODO: uncomment when thread_pool is enabled
 #    unit_thread_pool.cc

libtiledbsoma/test/unit_soma_multiscale_image.cc

@@ -0,0 +1,45 @@
+/**
+ * @file   unit_soma_multiscale_image.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2024 TileDB, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file manages unit tests for the SOMAMultiscaleImage class
+ */
+#include "common.h"
+
+TEST_CASE("SOMAMultiscaleImage: basic") {
+    auto ctx = std::make_shared<SOMAContext>();
+    std::string uri = "mem://unit-test-multiscale-image-basic";
+
+    SOMAMultiscaleImage::create(uri, ctx, std::nullopt);
+    auto soma_image = SOMAMultiscaleImage::open(
+        uri, OpenMode::read, ctx, std::nullopt);
+    REQUIRE(soma_image->uri() == uri);
+    REQUIRE(soma_image->ctx() == ctx);
+    REQUIRE(soma_image->type() == "SOMAMultiscaleImage");
+    soma_image->close();
+}