api(fmath.h): Add span version of convert_type

lgritz · lgritz · commit 9f668c7a0662 · 2025-04-20T21:08:21.000-07:00
api(imageio.h): Add span/image_span functions

* span convert_pixel_values
* image_span convert_image and parallel_convert_image

Signed-off-by: Larry Gritz &lt;lg@larrygritz.com&gt;
diff --git a/src/include/OpenImageIO/fmath.h b/src/include/OpenImageIO/fmath.h
@@ -757,7 +757,7 @@ scaled_conversion(const S& src, F scale, F min, F max)
 template<typename S, typename D>
 void convert_type (const S *src, D *dst, size_t n, D _min, D _max)
 {
-    if (std::is_same<S,D>::value) {
+    if constexpr (std::is_same<S,D>::value) {
         // They must be the same type.  Just memcpy.
         memcpy (dst, src, n*sizeof(D));
         return;
@@ -968,6 +968,25 @@ inline void convert_type (const S *src, D *dst, size_t n)
 
 
 
+/// Copy (type convert) consecutive values from the cspan `src` holding data
+/// of type S into the span `dst` holding the same number of elements of data
+/// of type D.
+///
+/// The conversion is not a simple cast, but correctly remaps the 0.0->1.0
+/// range from and to the full positive range of integral types. It's just a
+/// straight copy if both types are identical. Optional arguments `min` and
+/// `max` can give nonstandard quantizations.
+template<typename S, typename D>
+void convert_type (cspan<S> src, span<D> dst,
+                   D min = std::numeric_limits<D>::min(),
+                   D max = std::numeric_limits<D>::min())
+{
+    OIIO_DASSERT(src.size() == dst.size());
+    convert_type(src.data(), dst.data(), std::min(src.size(), dst.size()),
+                 min, max);
+}
+
+
 
 /// Convert a single value from the type of S to the type of D.
 /// The conversion is not a simple cast, but correctly remaps the
@@ -978,7 +997,7 @@ template<typename S, typename D>
 inline D
 convert_type (const S &src)
 {
-    if (std::is_same<S,D>::value) {
+    if constexpr (std::is_same<S,D>::value) {
         // They must be the same type.  Just return it.
         return (D)src;
     }
diff --git a/src/include/OpenImageIO/imageio.h b/src/include/OpenImageIO/imageio.h
@@ -3418,6 +3418,25 @@ get_extension_map()
 OIIO_API bool convert_pixel_values (TypeDesc src_type, const void *src,
                                     TypeDesc dst_type, void *dst, int n = 1);
 
+/// Helper function: copy values from spans `src` to `dst`, converting between
+/// types as appropriate. Return true if ok, false if it didn't know how to do
+/// the conversion.
+///
+/// The conversion is of normalized (pixel-like) values -- for example 'UINT8'
+/// 255 will convert to float 1.0 and vice versa, not float 255.0. If you want
+/// a straight C-like data cast conversion (e.g., uint8 255 -> float 255.0),
+/// then you should prefer the un-normalized convert_type() utility function
+/// found in typedesc.h.
+template<typename SrcType, typename DstType>
+bool
+convert_pixel_values(cspan<SrcType> src, span<DstType> dst)
+{
+    OIIO_DASSERT(dst.size() >= src.size());
+    return convert_pixel_values(TypeDescFromC_v<SrcType>, src.data(),
+                                TypeDescFromC_v<DstType>, dst.data(),
+                                std::min(dst.size(), src.size()));
+}
+
 
 /// Helper routine for data conversion: Convert an image of nchannels x
 /// width x height x depth from src to dst.  The src and dst may have
@@ -3436,6 +3455,50 @@ OIIO_API bool convert_image (int nchannels, int width, int height, int depth,
                              stride_t dst_xstride, stride_t dst_ystride,
                              stride_t dst_zstride);
 
+/// Helper routine for data conversion: Convert an image described by
+/// image_span `src` into image_span `dst`, which must be the same dimensions
+/// but possibly differing data type and strides.  Clever use of this function
+/// can not only exchange data among different formats (e.g., half to 8-bit
+/// unsigned), but also can copy selective channels, copy subimages, etc.
+/// Return true if ok, false if it didn't know how to do the conversion.
+template<typename SrcType, typename DstType>
+bool
+convert_image(image_span<SrcType> src, image_span<DstType> dst)
+{
+    // For now, just implement by wrapping the pointer-based version.
+    OIIO_DASSERT(src.nchannels() == dst.nchannels()
+                 && src.width() == dst.width() && src.height() == dst.height()
+                 && src.depth() == dst.depth());
+    return convert_image(src.nchannels(), src.width(), src.height(),
+                         src.depth(), src.data(), TypeDescFromC_v<SrcType>,
+                         src.xstride(), src.ystride(), src.zstride(),
+                         dst.data(), TypeDescFromC_v<DstType>, dst.xstride(),
+                         dst.ystride(), dst.zstride());
+}
+
+
+/// Helper routine for data conversion: Convert an image described by
+/// image_span `src` into image_span `dst`, which must be the same dimensions
+/// but possibly differing data type and strides. The data types are passed as
+/// `TypeDesc`, and the spans are untyped bytes that provide the dimensions
+/// and memory layout.
+inline bool
+convert_image(image_span<const std::byte> src, TypeDesc src_type,
+              image_span<std::byte> dst, TypeDesc dst_type)
+{
+    // For now, just implement by wrapping the pointer-based version.
+    OIIO_DASSERT(src.nchannels() == dst.nchannels()
+                 && src.width() == dst.width() && src.height() == dst.height()
+                 && src.depth() == dst.depth());
+    OIIO_DASSERT(src_type.size() == src.chansize()
+                 && dst_type.size() == dst.chansize());
+    return convert_image(src.nchannels(), src.width(), src.height(),
+                         src.depth(), src.data(), src_type, src.xstride(),
+                         src.ystride(), src.zstride(), dst.data(), dst_type,
+                         dst.xstride(), dst.ystride(), dst.zstride());
+}
+
+
 
 /// A version of convert_image that will break up big jobs into multiple
 /// threads.
@@ -3448,6 +3511,48 @@ OIIO_API bool parallel_convert_image (
                stride_t dst_xstride, stride_t dst_ystride,
                stride_t dst_zstride, int nthreads=0);
 
+/// A version of convert_image that will break up big jobs into multiple
+/// threads. The data types are taken from the spans.
+template<typename SrcType, typename DstType>
+bool
+parallel_convert_image(image_span<SrcType> src, image_span<DstType> dst,
+                       int nthreads = 0)
+{
+    // For now, just implement by wrapping the pointer-based version.
+    OIIO_DASSERT(src.nchannels() == dst.nchannels()
+                 && src.width() == dst.width() && src.height() == dst.height()
+                 && src.depth() == dst.depth());
+    return parallel_convert_image(src.nchannels(), src.width(), src.height(),
+                                  src.depth(), src.data(),
+                                  TypeDescFromC_v<SrcType>, src.xstride(),
+                                  src.ystride(), src.zstride(), dst.data(),
+                                  TypeDescFromC_v<SrcType>, dst.xstride(),
+                                  dst.ystride(), dst.zstride(), nthreads);
+}
+
+/// A version of convert_image that will break up big jobs into multiple
+/// threads. The data types are passed as `TypeDesc`, and the spans are
+/// untyped bytes that provide the dimensions and memory layout.
+inline bool
+parallel_convert_image(image_span<const std::byte> src, TypeDesc src_type,
+                       image_span<std::byte> dst, TypeDesc dst_type,
+                       int nthreads = 0)
+{
+    // For now, just implement by wrapping the pointer-based version.
+    OIIO_DASSERT(src.nchannels() == dst.nchannels()
+                 && src.width() == dst.width() && src.height() == dst.height()
+                 && src.depth() == dst.depth());
+    OIIO_DASSERT(src_type.size() == src.chansize()
+                 && dst_type.size() == dst.chansize());
+    return parallel_convert_image(src.nchannels(), src.width(), src.height(),
+                                  src.depth(), src.data(),
+                                  src_type, src.xstride(),
+                                  src.ystride(), src.zstride(), dst.data(),
+                                  dst_type, dst.xstride(),
+                                  dst.ystride(), dst.zstride(), nthreads);
+}
+
+
 
 /// Add random [-ditheramplitude,ditheramplitude] dither to the color channels
 /// of the image.  Dither will not be added to the alpha or z channel.  The
diff --git a/src/libOpenImageIO/CMakeLists.txt b/src/libOpenImageIO/CMakeLists.txt
@@ -253,7 +253,7 @@ if (OIIO_BUILD_TESTS AND BUILD_TESTING)
     add_test (unit_color ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/color_test)
 
     fancy_add_executable (NAME image_span_test SRC image_span_test.cpp
-                          LINK_LIBRARIES OpenImageIO
+                          LINK_LIBRARIES OpenImageIO Imath::Imath
                           FOLDER "Unit Tests" NO_INSTALL)
     add_test (unit_image_span ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/image_span_test)
 
diff --git a/src/libOpenImageIO/image_span_test.cpp b/src/libOpenImageIO/image_span_test.cpp
@@ -3,7 +3,10 @@
 // https://github.com/AcademySoftwareFoundation/OpenImageIO
 
 
+#include <OpenImageIO/half.h>
+
 #include <OpenImageIO/benchmark.h>
+#include <OpenImageIO/fmath.h>
 #include <OpenImageIO/imageio.h>
 #include <OpenImageIO/parallel.h>
 #include <OpenImageIO/unittest.h>
@@ -120,7 +123,7 @@ fill_image_span(image_span<T> img)
 
 
 // Check that an image span in the characteristic way
-template<typename T>
+template<typename T, typename S = T>
 bool
 check_image_span(image_span<T> img, int xoff = 0, int yoff = 0, int zoff = 0)
 {
@@ -129,7 +132,8 @@ check_image_span(image_span<T> img, int xoff = 0, int yoff = 0, int zoff = 0)
         for (uint32_t y = 0; y < img.height(); ++y) {
             for (uint32_t x = 0; x < img.width(); ++x) {
                 for (uint32_t c = 0; c < img.nchannels(); ++c) {
-                    auto v = testvalue<T>(x + xoff, y + yoff, z + zoff, c);
+                    auto v = convert_type<S, T>(
+                        testvalue<S>(x + xoff, y + yoff, z + zoff, c));
                     OIIO_CHECK_EQUAL(img(x, y, z)[c], v);
                     if (img(x, y, z)[c] != v) {
                         print("\tError at ({}, {}, {})[{}]\n", x, y, z, c);
@@ -279,6 +283,72 @@ test_image_span_contiguize()
 
 
 
+template<typename Stype = float, typename Dtype = Stype>
+void
+test_image_span_convert_image()
+{
+    // Benchmark old (ptr) versus new (span) convert_image functions
+    const int xres = 2048, yres = 1536, nchans = 4;
+    const size_t schansize = sizeof(Stype);
+    const size_t dchansize = sizeof(Dtype);
+    print("\nTesting convert_image {} -> {} (total {}M values):\n",
+          TypeDescFromC_v<Stype>, TypeDescFromC_v<Dtype>,
+          xres * yres * nchans * 3 / 4 / 1024 / 1024);
+
+    // We test different amounts of contiguity. Each test copies 3/4 of the
+    // total image, to keep the total number of bytes copied identical.
+    const stride_t src_xstride(schansize * nchans);
+    const stride_t src_ystride(src_xstride * xres);
+    const stride_t dst_xstride(dchansize * nchans);
+    const stride_t dst_ystride(dst_xstride * xres);
+    for (int i = 0; i < 3; ++i) {
+        size_t nc(nchans), w(xres), h(yres);
+        std::string label;
+        if (i == 0) {
+            // Fully contiguous region -- copy 3/4 of the image.
+            label = "contig buffer";
+            h     = h * 3 / 4;
+        } else if (i == 1) {
+            // Contiguous scanlines -- copy 3/4 of the width of each scanline.
+            label = "contig scanlines";
+            w     = w * 3 / 4;
+        } else if (i == 2) {
+            // Contiguous pixels -- copy 3 of 4 channels of each pixel.
+            label = "contig pixels";
+            nc    = nc * 3 / 4;
+        }
+
+        print("  test convert_image {}\n", label);
+        std::vector<Stype> sbuf(xres * yres * nchans, Stype(10));
+        std::vector<Dtype> dbuf(xres * yres * nchans, Dtype(20));
+
+        // Spans for src and dst
+        image_span sispan(sbuf.data(), nc, w, h, 1, schansize, src_xstride,
+                          src_ystride, AutoStride);
+        image_span dispan(dbuf.data(), nc, w, h, 1, dchansize, dst_xstride,
+                          dst_ystride, AutoStride);
+
+        fill_image_span(sispan);
+
+        // Benchmark old (ptr) versus new (span) contiguize functions
+        Benchmarker bench;
+        bench.units(Benchmarker::Unit::ms);
+
+        bench(Strutil::format("    convert_image image_span {}", label),
+              [&]() { convert_image(sispan, dispan); });
+        // Test correctness
+        bench(Strutil::format("    convert_image raw ptrs   {}", label), [&]() {
+            convert_image(nc, w, h, 1, sbuf.data(), TypeDescFromC_v<Stype>,
+                          src_xstride, src_ystride, AutoStride, dbuf.data(),
+                          TypeDescFromC_v<Dtype>, dst_xstride, dst_ystride,
+                          AutoStride);
+        });
+        OIIO_CHECK_ASSERT((check_image_span<Dtype, Stype>(dispan)));
+    }
+}
+
+
+
 int
 main(int /*argc*/, char* /*argv*/[])
 {
@@ -297,5 +367,16 @@ main(int /*argc*/, char* /*argv*/[])
     test_image_span_contiguize<uint16_t>();
     test_image_span_contiguize<uint8_t>();
 
+    test_image_span_convert_image<float, half>();
+    test_image_span_convert_image<float, uint16_t>();
+    test_image_span_convert_image<float, uint8_t>();
+    test_image_span_convert_image<half, float>();
+    test_image_span_convert_image<uint16_t, float>();
+    test_image_span_convert_image<uint8_t, float>();
+    test_image_span_convert_image<uint16_t, uint8_t>();
+    test_image_span_convert_image<uint8_t, uint16_t>();
+    test_image_span_convert_image<uint16_t, half>();
+    test_image_span_convert_image<half, uint16_t>();
+
     return unit_test_failures;
 }
diff --git a/src/libutil/fmath_test.cpp b/src/libutil/fmath_test.cpp
@@ -334,13 +334,22 @@ test_convert_type(double tolerance = 1e-6)
 
 template<typename S, typename D>
 void
-do_convert_type(const std::vector<S>& svec, std::vector<D>& dvec)
+do_convert_type_ptr(const std::vector<S>& svec, std::vector<D>& dvec)
 {
     convert_type(&svec[0], &dvec[0], svec.size());
     DoNotOptimize(dvec[0]);  // Be sure nothing is optimized away
 }
 
 
+template<typename S, typename D>
+void
+do_convert_type_span(const std::vector<S>& svec, std::vector<D>& dvec)
+{
+    convert_type(svec, dvec);
+    DoNotOptimize(dvec[0]);  // Be sure nothing is optimized away
+}
+
+
 template<typename S, typename D>
 void
 benchmark_convert_type()
@@ -349,17 +358,24 @@ benchmark_convert_type()
     const size_t size    = iterations;
     const S testval(1.0);
     std::vector<S> svec(size, testval);
-    std::vector<D> dvec(size);
-    Strutil::print("Benchmark conversion of {:6} -> {:6} : ",
-                   TypeDesc(BaseTypeFromC<S>::value).c_str(),
-                   TypeDesc(BaseTypeFromC<D>::value).c_str());
-    float time = time_trial(bind(do_convert_type<S, D>, std::cref(svec),
+    std::vector<D> dvec(size), dvec2(size);
+    print("Benchmark conversion of {:6} -> {:6} (ptr) : ",
+          TypeDesc(BaseTypeFromC<S>::value), TypeDesc(BaseTypeFromC<D>::value));
+    float time = time_trial(bind(do_convert_type_ptr<S, D>, std::cref(svec),
                                  std::ref(dvec)),
                             ntrials, repeats)
                  / repeats;
-    Strutil::print("{:7.1f} Mvals/sec\n", (size / 1.0e6) / time);
+    print("{:7.1f} Mvals/sec\n", (size / 1.0e6) / time);
+    print("Benchmark conversion of {:6} -> {:6} (span): ",
+          TypeDesc(BaseTypeFromC<S>::value), TypeDesc(BaseTypeFromC<D>::value));
+    float time2 = time_trial(bind(do_convert_type_ptr<S, D>, std::cref(svec),
+                                  std::ref(dvec2)),
+                             ntrials, repeats)
+                  / repeats;
+    print("{:7.1f} Mvals/sec\n", (size / 1.0e6) / time2);
     D r = convert_type<S, D>(testval);
     OIIO_CHECK_EQUAL(dvec[size - 1], r);
+    OIIO_CHECK_EQUAL(dvec2[size - 1], r);
 }
 
 
