Add image(buffer, size) API

c/image_c_api.cxx

@@ -72,6 +72,25 @@ f3d_image_t* f3d_image_new_path(const char* path)
   return reinterpret_cast<f3d_image_t*>(img);
 }
 
+//----------------------------------------------------------------------------
+f3d_image_t* f3d_image_new_stream(unsigned char* byte, unsigned int size)
+{
+
+  f3d::image* img = nullptr;
+
+  try
+  {
+    img = new f3d::image(reinterpret_cast<std::byte*>(byte), static_cast<size_t>(size));
+  }
+  catch (const f3d::image::read_exception& e)
+  {
+    std::cerr << "Error loading image: " << e.what() << "\n";
+    return nullptr;
+  }
+
+  return reinterpret_cast<f3d_image_t*>(img);
+}
+
 //----------------------------------------------------------------------------
 void f3d_image_delete(f3d_image_t* img)
 {

c/image_c_api.h

@@ -57,6 +57,15 @@ extern "C"
    */
   F3D_EXPORT f3d_image_t* f3d_image_new_path(const char* path);
 
+  /**
+   * @brief Create a new image object from a stream
+   *
+   * The returned image must be deleted with f3d_image_delete().
+   *
+   * @return Pointer to the newly created image object, NULL on failure
+   */
+  F3D_EXPORT f3d_image_t* f3d_image_new_stream(unsigned char* buffer, unsigned int size);
+
   /**
    * @brief Delete an image object
    * @param img Pointer to the image object to be deleted

c/testing/CMakeLists.txt

@@ -18,6 +18,12 @@ if(VTK_VERSION VERSION_GREATER_EQUAL 9.4.20250501)
     )
 endif()
 
+if(VTK_VERSION VERSION_GREATER_EQUAL 9.6.20260128)
+  list(APPEND f3d_c_api_tests_list
+    test_image_stream.c
+    )
+endif()
+
 set(CMAKE_TESTDRIVER_EXTRA_INCLUDES "")
 set(CMAKE_TESTDRIVER_ARGVC_FUNCTION "")
 set(CMAKE_TESTDRIVER_BEFORE_TESTMAIN "")

c/testing/test_image_stream.c

@@ -0,0 +1,56 @@
+#include <image_c_api.h>
+
+#include <stdio.h>
+
+int test_image_stream()
+{
+  f3d_image_t* img = f3d_image_new_params(800, 600, 3, BYTE);
+  if (!img)
+  {
+    puts("[ERROR] Failed to create image");
+    return 1;
+  }
+
+  unsigned int count;
+  unsigned char* tempBuffer = f3d_image_save_buffer(NULL, PNG, &count); // this shouldn't crash
+  if (tempBuffer != NULL)
+  {
+    f3d_image_delete(img);
+    return 1;
+  }
+
+  f3d_image_t* temp_image_stream = f3d_image_new_stream(tempBuffer, 0);
+  if (temp_image_stream != NULL)
+  {
+    f3d_image_delete(img);
+    return 1;
+  }
+
+  unsigned int buffer_size;
+  unsigned char* buffer = f3d_image_save_buffer(img, PNG, &buffer_size);
+  if (buffer)
+  {
+    f3d_image_t* image_stream = f3d_image_new_stream(buffer, buffer_size);
+
+    if (image_stream)
+    {
+      double stream_error = f3d_image_compare(img, image_stream);
+      f3d_image_free_buffer(buffer);
+      f3d_image_delete(image_stream);
+
+      if (stream_error != 0)
+      {
+        f3d_image_delete(img);
+        return 1;
+      }
+    }
+    else
+    {
+      f3d_image_delete(img);
+      return 1;
+    }
+  }
+
+  f3d_image_delete(img);
+  return 0;
+}

java/F3DImageBindings.cxx

@@ -19,6 +19,15 @@ extern "C"
     return reinterpret_cast<jlong>(img);
   }
 
+  JNIEXPORT jlong JAVA_BIND(Image, nativeCreateFromStream)(JNIEnv* env, jclass, jbyteArray buffer)
+  {
+    jbyte* bufferData = env->GetByteArrayElements(buffer, nullptr);
+    size_t size = env->GetArrayLength(buffer);
+
+    f3d::image* img = new f3d::image(reinterpret_cast<std::byte*>(bufferData), size);
+    return reinterpret_cast<jlong>(img);
+  }
+
   JNIEXPORT jlong JAVA_BIND(Image, nativeCreate)(
     JNIEnv* env, jclass, jint width, jint height, jint channelCount, jint type)
   {

java/Image.java

@@ -55,6 +55,15 @@ public Image(int width, int height, int channelCount) {
         this(width, height, channelCount, ChannelType.BYTE);
     }
 
+    /**
+     * Create an image from given stream buffer
+     *
+     * @param buffer stream buffer
+     */
+    public Image(byte[] buffer) {
+        mNativeAddress = nativeCreateFromStream(buffer);
+    }
+
     Image(long nativeAddress) {
         mNativeAddress = nativeAddress;
     }
@@ -233,5 +242,6 @@ public void delete() {
 
     private static native long nativeCreateFromFile(String filePath);
     private static native long nativeCreate(int width, int height, int channelCount, int type);
+    private static native long nativeCreateFromStream(byte[] buffer);
     private static native void nativeDestroy(long nativeAddress);
 }

java/testing/CMakeLists.txt

@@ -17,6 +17,12 @@ if(VTK_VERSION VERSION_GREATER_EQUAL 9.4.20250501)
     )
 endif()
 
+if(VTK_VERSION VERSION_GREATER_EQUAL 9.6.20260128)
+  list(APPEND javaf3dTests_list
+    ${CMAKE_CURRENT_SOURCE_DIR}/TestImageStream.java
+    )
+endif()
+
 set(java_test_args "-ea") # enable assertions
 if (WIN32)
   list(APPEND java_test_args "--enable-native-access=ALL-UNNAMED")

java/testing/TestImageStream.java

@@ -0,0 +1,16 @@
+import app.f3d.F3D.*;
+
+public class TestImageStream {
+  public static void main(String[] args) {
+    Image img1 = new Image(300, 200, 3);
+
+    byte[] img1Buffer = img1.saveBuffer(Image.SaveFormat.PNG);
+
+    Image img2 = new Image(img1Buffer);
+
+    img1.equals(img2);
+
+    img1.delete();
+    img2.delete();
+  }
+}

library/public/image.h

@@ -5,6 +5,7 @@
 #include "export.h"
 
 /// @cond
+#include <cstddef>
 #include <filesystem>
 #include <string>
 #include <vector>
@@ -56,6 +57,15 @@ class F3D_EXPORT image
    */
   explicit image(const std::filesystem::path& filePath);
 
+  /**
+   * Read provided buffer into a new image instance, the following formats are
+   * supported: PNG, PNM , BMP, HDR, JPEG, TGA, WebP. EXR files are also
+   * supported if the associated module is built.
+   *
+   * Throws an image::read_exception in case of failure.
+   */
+  image(std::byte* byte, std::size_t size);
+
   /**
    * Create an image from a given width, height, and channel count.
    * A channel type can also be given. Default is BYTE.

library/src/image.cxx

@@ -12,6 +12,7 @@
 #include <vtkImageReader2Factory.h>
 #include <vtkImageSSIM.h>
 #include <vtkJPEGWriter.h>
+#include <vtkMemoryResourceStream.h>
 #include <vtkPNGReader.h>
 #include <vtkPNGWriter.h>
 #include <vtkPointData.h>
@@ -214,6 +215,67 @@ image::image(const fs::path& filePath)
   }
 }
 
+//----------------------------------------------------------------------------
+image::image([[maybe_unused]] std::byte* buffer, [[maybe_unused]] std::size_t size)
+  : Internals(new image::internals())
+{
+#if VTK_VERSION_NUMBER >= VTK_VERSION_CHECK(9, 6, 20260128)
+  detail::init::initialize();
+
+  if (buffer == nullptr)
+  {
+    delete this->Internals;
+    throw read_exception("Cannot read image from buffer: Buffer is empty");
+  }
+
+  vtkNew<vtkMemoryResourceStream> stream;
+  stream->SetBuffer(buffer, size);
+
+  vtkNew<vtkImageReader2Collection> availableReaders;
+  vtkImageReader2Factory::GetRegisteredReaders(availableReaders);
+
+  vtkCollectionSimpleIterator iterator;
+  vtkImageReader2* currentReader;
+  vtkImageReader2* reader = nullptr;
+
+  for (availableReaders->InitTraversal(iterator);
+       (currentReader = availableReaders->GetNextImageReader2(iterator));)
+  {
+    if (currentReader->CanReadFile(stream) > 0)
+    {
+      reader = currentReader;
+      break;
+    }
+  }
+
+  if (reader == nullptr)
+  {
+    delete this->Internals;
+    throw read_exception("Cannot read image from buffer: No image reader supports this stream.");
+  }
+
+  reader->SetStream(stream);
+  reader->Update();
+  this->Internals->Image = reader->GetOutput();
+
+  vtkPNGReader* pngReader = vtkPNGReader::SafeDownCast(reader);
+  if (pngReader != nullptr)
+  {
+    this->Internals->ReadPngMetadata(pngReader);
+  }
+
+  if (!this->Internals->Image)
+  {
+    delete this->Internals;
+    throw read_exception("Cannot read image from buffer");
+  }
+
+#else
+  delete this->Internals;
+  throw read_exception("VTK >= v9.6.20260128 is required for streaming images");
+#endif
+}
+
 //----------------------------------------------------------------------------
 image::~image()
 {

library/testing/CMakeLists.txt

@@ -68,6 +68,7 @@ endif()
 if(VTK_VERSION VERSION_GREATER_EQUAL 9.6.20260128)
   list(APPEND libf3dSDKTests_list
     TestSDKSceneInvalidHeader.cxx
+    TestImageStream.cxx
     )
 endif()
 

library/testing/TestImageStream.cxx

@@ -0,0 +1,43 @@
+#include "PseudoUnitTest.h"
+
+#include <image.h>
+
+#include <algorithm>
+#include <random>
+
+int TestImageStream([[maybe_unused]] int argc, [[maybe_unused]] char* argv[])
+{
+  PseudoUnitTest test;
+
+  constexpr unsigned int width = 64;
+  constexpr unsigned int height = 64;
+  constexpr unsigned int channels = 3;
+
+  // fill with deterministic random values
+  // do not use std::uniform_int_distribution, it's not giving the same result on different
+  // platforms
+  std::mt19937 randGenerator;
+
+  f3d::image generated(width, height, channels);
+  std::vector<uint8_t> pixels(width * height * channels);
+  std::ranges::generate(pixels, [&]() { return static_cast<uint8_t>(randGenerator() % 256); });
+  generated.setContent(pixels.data());
+
+  // check reading stream
+  std::vector<unsigned char> generatedBuffer = generated.saveBuffer();
+  std::byte* bufferData = reinterpret_cast<std::byte*>(generatedBuffer.data());
+  f3d::image bufferImage(bufferData, generatedBuffer.size());
+  test("check loading stream from image reader", generated.compare(bufferImage), 0.0);
+
+  // check reading inexistent/null stream
+  test.expect<f3d::image::read_exception>(
+    "read image from invalid/null stream", [&]() { f3d::image nullImgStream(nullptr, 10); });
+
+  // check reading invalid stream
+  std::vector<unsigned char> invalidBuffer = { 0, 1, 2, 3, 4, 5 };
+  std::byte* invalidBufferData = reinterpret_cast<std::byte*>(invalidBuffer.data());
+  test.expect<f3d::image::read_exception>("read image from invalid stream",
+    [&]() { f3d::image invalidImgStream(invalidBufferData, 10); });
+
+  return test.result();
+}

library/testing/TestSDKImage.cxx

@@ -83,17 +83,21 @@ int TestSDKImage([[maybe_unused]] int argc, [[maybe_unused]] char* argv[])
   // test exceptions
   test.expect<f3d::image::write_exception>("save incompatible buffer to BMP format",
     [&]() { std::ignore = img16.saveBuffer(f3d::image::SaveFormat::BMP); });
+
   test.expect<f3d::image::write_exception>("save incompatible buffer to PNG format",
     [&]() { std::ignore = img32.saveBuffer(f3d::image::SaveFormat::PNG); });
 
   f3d::image img2Ch(4, 4, 2);
   f3d::image img5Ch(4, 4, 5);
   test.expect<f3d::image::write_exception>("save incompatible channel count to BMP format",
     [&]() { std::ignore = img5Ch.saveBuffer(f3d::image::SaveFormat::BMP); });
+
   test.expect<f3d::image::write_exception>("save incompatible channel count to JPG format",
     [&]() { std::ignore = img2Ch.saveBuffer(f3d::image::SaveFormat::JPG); });
+
   test.expect<f3d::image::write_exception>("save image to invalid path",
     [&]() { img2Ch.save("/" + std::string(257, 'x') + "/file.ext"); });
+
   test.expect<f3d::image::write_exception>("save image to invalid filename",
     [&]() { img2Ch.save(testingDir + std::string(257, 'x') + ".ext"); });
 
@@ -174,6 +178,7 @@ int TestSDKImage([[maybe_unused]] int argc, [[maybe_unused]] char* argv[])
   {
     test.expect<f3d::image::write_exception>("invalid toTerminalText with BYTE",
       [&]() { std::ignore = f3d::image(3, 3, 1, f3d::image::ChannelType::BYTE).toTerminalText(); });
+
     test.expect<f3d::image::write_exception>("invalid toTerminalText with SHORT", [&]() {
       std::ignore = f3d::image(3, 3, 4, f3d::image::ChannelType::SHORT).toTerminalText();
     });

python/F3DPythonBindings.cxx

@@ -191,6 +191,12 @@ PYBIND11_MODULE(pyf3d, module)
     .def(py::init<>())
     .def(py::init<const std::filesystem::path&>())
     .def(py::init<unsigned int, unsigned int, unsigned int, f3d::image::ChannelType>())
+    .def(py::init(
+      [](const py::bytes& buffer)
+      {
+        const py::buffer_info info(py::buffer(buffer).request());
+        return f3d::image(reinterpret_cast<std::byte*>(info.ptr), info.size);
+      }))
     .def(py::self == py::self)
     .def(py::self != py::self)
     .def_static("supported_formats", &f3d::image::getSupportedFormats)

python/testing/CMakeLists.txt

@@ -40,6 +40,12 @@ list(APPEND pyf3dTestsNoRender_list
      test_utils.py
     )
 
+if(VTK_VERSION VERSION_GREATER_EQUAL 9.6.20260128)
+  list(APPEND pyf3dTests_list
+     test_image_stream.py
+    )
+endif()
+
 # Add all the ADD_TEST for each test
 foreach(test ${pyf3dTests_list})
   get_filename_component (TName ${test} NAME_WE)