diff --git a/src/doc/imagecache.rst b/src/doc/imagecache.rst index 8a51f57f80..96c6215306 100644 --- a/src/doc/imagecache.rst +++ b/src/doc/imagecache.rst @@ -46,46 +46,26 @@ for you. It is reasonable to access thousands of image files totalling hundreds of GB of pixels, efficiently and using a memory footprint on the order of 50 MB. -Below are some simple code fragments that shows ImageCache in action:: - - #include - using namespace OIIO; - - // Create an image cache and set some options - ImageCache *cache = ImageCache::create (); - cache->attribute ("max_memory_MB", 500.0f); - cache->attribute ("autotile", 64); - - // Get a block of pixels from a file. - // (for brevity of this example, let's assume that 'size' is the - // number of channels times the number of pixels in the requested region) - float pixels[size]; - cache->get_pixels ("file1.jpg", 0, 0, ROI(xbegin, xend, ybegin, yend), - make_span(pixels)); - - // Get information about a file - ImageSpec spec; - bool ok = cache->get_imagespec ("file2.exr", spec); - if (ok) - std::cout << "resolution is " << spec.width << "x" - << spec.height << "\n"; - - // Request and hold a tile, do some work with its pixels, then release - ImageCache::Tile *tile; - tile = cache->get_tile ("file2.exr", 0, 0, x, y, z); - // The tile won't be freed until we release it, so this is safe: - TypeDesc format; - void *p = cache->tile_pixels (tile, format); - // Now p points to the raw pixels of the tile, whose data format - // is given by 'format'. - cache->release_tile (tile); - // Now cache is permitted to free the tile when needed - - // Note that all files were referenced by name, we never had to open - // or close any files, and all the resource and memory management - // was automatic. - - ImageCache::destroy (cache); +Below are some simple code fragments that shows ImageCache in action: + +.. tabs:: + + .. tab:: C++ + .. literalinclude:: ../../testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp + :language: c++ + :start-after: BEGIN-imagecache-example1 + :end-before: END-imagecache-example1 + + .. tab:: Python + + .. literalinclude:: ../../testsuite/docs-examples-python/src/docs-examples-imagecache.py + :language: py + :start-after: BEGIN-imagecache-example1 + :end-before: END-imagecache-example1 + +Note that all files were referenced by name, we never had to open +or close any files, and all the resource and memory management +was automatic. .. _sec-imagecache-api: diff --git a/testsuite/docs-examples-cpp/ref/out-arm.txt b/testsuite/docs-examples-cpp/ref/out-arm.txt index bbb53c3af6..09e3148815 100644 --- a/testsuite/docs-examples-cpp/ref/out-arm.txt +++ b/testsuite/docs-examples-cpp/ref/out-arm.txt @@ -1,4 +1,5 @@ pixels holds unassociated alpha +resolution is 512x384 example_output_error1 error: Uninitialized input image example_output_error2 diff --git a/testsuite/docs-examples-cpp/ref/out-linuxarm.txt b/testsuite/docs-examples-cpp/ref/out-linuxarm.txt index d4919eeef6..003b5ec05c 100644 --- a/testsuite/docs-examples-cpp/ref/out-linuxarm.txt +++ b/testsuite/docs-examples-cpp/ref/out-linuxarm.txt @@ -1,4 +1,5 @@ pixels holds unassociated alpha +resolution is 512x384 example_output_error1 error: Uninitialized input image example_output_error2 diff --git a/testsuite/docs-examples-cpp/ref/out.txt b/testsuite/docs-examples-cpp/ref/out.txt index 5854393bba..67420798bd 100644 --- a/testsuite/docs-examples-cpp/ref/out.txt +++ b/testsuite/docs-examples-cpp/ref/out.txt @@ -1,4 +1,5 @@ pixels holds unassociated alpha +resolution is 512x384 example_output_error1 error: Uninitialized input image example_output_error2 diff --git a/testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp b/testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp index e88fa5de53..101260f0c0 100644 --- a/testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp +++ b/testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp @@ -11,20 +11,55 @@ // "example1" to a helpful short name that identifies the example. // BEGIN-imagecache-example1 -#include +#include +#include +#include using namespace OIIO; void example1() { - // - // Example code fragment from the docs goes here. - // - // It probably should generate either some text output (which will show up - // in "out.txt" that captures each test's output), or it should produce a - // (small) image file that can be compared against a reference image that - // goes in the ref/ subdirectory of this test. - // + // Create an image cache and set some options + auto cache = ImageCache::create(); + cache->attribute("max_memory_MB", 500.0f); + cache->attribute("autotile", 64); + + ustring filename("tahoe.tif"); + + // Get information about a file + ImageSpec spec; + bool ok = cache->get_imagespec(filename, spec); + if (ok) + std::cout << "resolution is " << spec.width << "x" << spec.height + << "\n"; + + // Get a block of pixels from a file. + const int xbegin = 0, xend = 4, ybegin = 0, yend = 4; + const int nchannels = spec.nchannels; + ROI roi(xbegin, xend, ybegin, yend, 0, 1, 0, nchannels); + std::vector pixels(roi.width() * roi.height() * nchannels); + image_span pixelspan(pixels.data(), nchannels, roi.width(), + roi.height()); + cache->get_pixels(filename, 0, 0, roi, pixelspan); + + // Request and hold a tile, do some work with its pixels, then release + ImageCache::Tile* tile = cache->get_tile(filename, 0, 0, 0, 0, 0); + if (tile) { + // The tile won't be freed until we release it, so this is safe: + TypeDesc format; + const void* p = cache->tile_pixels(tile, format); + // Now p points to the raw pixels of the tile, whose data format + // is given by 'format'. + (void)p; + cache->release_tile(tile); + // Now cache is permitted to free the tile when needed + } + + // Note that all files were referenced by name, we never had to open + // or close any files, and all the resource and memory management + // was automatic. + + ImageCache::destroy(cache); } // END-imagecache-example1 diff --git a/testsuite/docs-examples-python/ref/out-arm.txt b/testsuite/docs-examples-python/ref/out-arm.txt index 90a3f94f2b..d04b76afbd 100644 --- a/testsuite/docs-examples-python/ref/out-arm.txt +++ b/testsuite/docs-examples-python/ref/out-arm.txt @@ -1,4 +1,5 @@ pixels holds unassociated alpha +resolution is 512x384 example1 example_output_error1 error: Uninitialized input image diff --git a/testsuite/docs-examples-python/ref/out-linuxarm.txt b/testsuite/docs-examples-python/ref/out-linuxarm.txt index 94c92a7c54..a7b1783de4 100644 --- a/testsuite/docs-examples-python/ref/out-linuxarm.txt +++ b/testsuite/docs-examples-python/ref/out-linuxarm.txt @@ -1,4 +1,5 @@ pixels holds unassociated alpha +resolution is 512x384 example1 example_output_error1 error: Uninitialized input image diff --git a/testsuite/docs-examples-python/ref/out.txt b/testsuite/docs-examples-python/ref/out.txt index 6c6c628cb6..0d460ee956 100644 --- a/testsuite/docs-examples-python/ref/out.txt +++ b/testsuite/docs-examples-python/ref/out.txt @@ -1,4 +1,5 @@ pixels holds unassociated alpha +resolution is 512x384 example1 example_output_error1 error: Uninitialized input image diff --git a/testsuite/docs-examples-python/src/docs-examples-imagecache.py b/testsuite/docs-examples-python/src/docs-examples-imagecache.py index 868b019d43..bc11bf1fd7 100644 --- a/testsuite/docs-examples-python/src/docs-examples-imagecache.py +++ b/testsuite/docs-examples-python/src/docs-examples-imagecache.py @@ -19,14 +19,24 @@ import numpy as np def example1() -> None: - # - # Example code fragment from the docs goes here. - # - # It probably should generate either some text output (which will show up - # in "out.txt" that captures each test's output), or it should produce a - # (small) image file that can be compared against a reference image that - # goes in the ref/ subdirectory of this test. - # + # Create an image cache and set some options + cache = oiio.ImageCache() + cache.attribute("max_memory_MB", 500.0) + cache.attribute("autotile", 64) + + # Get information about a file + spec = cache.get_imagespec("tahoe.tif") + print(f"resolution is {spec.width}x{spec.height}") + + # Get a block of pixels from a file (returns a numpy array, or None + # on failure). + roi = oiio.ROI(0, 4, 0, 4, 0, 1, 0, spec.nchannels) + pixels = cache.get_pixels("tahoe.tif", 0, 0, roi) + + # Note that all files were referenced by name, we never had to open + # or close any files, and all the resource and memory management + # was automatic. + oiio.ImageCache.destroy(cache) return # END-imagecache-example1