HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
imagebufalgo.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenImageIO project.
2 // SPDX-License-Identifier: Apache-2.0
3 // https://github.com/AcademySoftwareFoundation/OpenImageIO
4 
5 
6 // clang-format off
7 
8 #pragma once
9 #define OPENIMAGEIO_IMAGEBUFALGO_H
10 
11 #if defined(_MSC_VER)
12 // Ignore warnings about DLL exported classes with member variables that are template classes.
13 // This happens with the std::vector<T> members of PixelStats below.
14 # pragma warning (disable : 4251)
15 #endif
16 
17 #include <OpenImageIO/imageio.h>
18 #include <OpenImageIO/imagebuf.h>
19 #include <OpenImageIO/fmath.h>
20 #include <OpenImageIO/parallel.h>
21 #include <OpenImageIO/span.h>
22 #include <OpenImageIO/vecparam.h>
23 
24 #include <limits>
25 
26 #if !defined(__OPENCV_CORE_TYPES_H__) && !defined(OPENCV_CORE_TYPES_H)
27 struct IplImage; // Forward declaration; used by Intel Image lib & OpenCV
28 namespace cv {
29  class Mat;
30 }
31 #endif
32 
33 
34 
36 
37 // forward declarations
38 class ColorConfig;
39 class ColorProcessor;
40 class Filter2D;
41 
42 
43 /// @defgroup ImageBufAlgo_intro (ImageBufAlgo common principles)
44 /// @{
45 ///
46 /// This section explains the general rules common to all ImageBufAlgo
47 /// functions. Only exceptions to these rules will be explained in the
48 /// subsequent listings of all the individual ImageBufAlgo functions.
49 ///
50 ///
51 /// **Return values and error messages**
52 ///
53 /// Most ImageBufAlgo functions that produce image data come in two forms:
54 ///
55 /// 1. Return an ImageBuf.
56 ///
57 /// The return value is a new ImageBuf containing the result image. In
58 /// this case, an entirely new image will be created to hold the result.
59 /// In case of error, the result image returned can have any error
60 /// conditions checked with `has_error()` and `geterror()`.
61 ///
62 /// // Method 1: Return an image result
63 /// ImageBuf fg ("fg.exr"), bg ("bg.exr");
64 /// ImageBuf dst = ImageBufAlgo::over (fg, bg);
65 /// if (dst.has_error())
66 /// std::cout << "error: " << dst.geterror() << "\n";
67 ///
68 /// 2. Pass a destination ImageBuf reference as the first parameter.
69 ///
70 /// The function is passed a *destination* ImageBuf where the results
71 /// will be stored, and the return value is a `bool` that is `true` if
72 /// the function succeeds or `false` if the function fails. Upon failure,
73 /// the destination ImageBuf (the one that is being altered) will have an
74 /// error message set.
75 ///
76 /// // Method 2: Write into an existing image
77 /// ImageBuf fg ("fg.exr"), bg ("bg.exr");
78 /// ImageBuf dst; // will be the output image
79 /// bool ok = ImageBufAlgo::over (dst, fg, bg);
80 /// if (! ok)
81 /// std::cout << "error: " << dst.geterror() << "\n";
82 ///
83 /// The first option (return an ImageBuf) is a more compact and intuitive
84 /// notation that is natural for most simple uses. But the second option
85 /// (pass an ImageBuf& referring to an existing destination) offers
86 /// additional flexibility, including more careful control over allocations,
87 /// the ability to partially overwrite regions of an existing image, and the
88 /// ability for the destination image to also be one of the input images
89 /// (for example, add(A,A,B) adds B into existing image A, with no third
90 /// image allocated at all).
91 ///
92 /// **Region of interest**
93 ///
94 /// Most ImageBufAlgo functions take an optional ROI parameter that
95 /// restricts the operation to a range in x, y, z, and channels. The default
96 /// ROI (also known as `ROI::All()`) means no region restriction -- the
97 /// whole image will be copied or altered.
98 ///
99 /// For ImageBufAlgo functions that write into a destination ImageBuf
100 /// parameter and it is already initialized (i.e. allocated with a
101 /// particular size and data type), the operation will be performed on the
102 /// pixels in the destination that overlap the ROI, leaving pixels in the
103 /// destination which are outside the ROI unaltered.
104 ///
105 /// For ImageBufAlgo functions that return an ImageBuf directly, or their
106 /// `dst` parameter that is an uninitialized ImageBuf, the ROI (if set)
107 /// determines the size of the result image. If the ROI is the default
108 /// `All`, the result image size will be the union of the pixel data windows
109 /// of the input images and have a data type determined by the data types of
110 /// the input images.
111 ///
112 /// Most ImageBufAlgo functions also respect the `chbegin` and `chend`
113 /// members of the ROI, thus restricting the channel range on which the
114 /// operation is performed. The default ROI constructor sets up the ROI
115 /// to specify that the operation should be performed on all channels of
116 /// the input image(s).
117 ///
118 /// **Constant and per-channel values**
119 ///
120 /// Many ImageBufAlgo functions take per-channel constant-valued arguments
121 /// (for example, a fill color). These parameters are passed as
122 /// `cspan<float>`. These are generally expected to have length equal to the
123 /// number of channels. But you may also pass a single float which will be
124 /// used as the value for all channels. (More generally, what is happening
125 /// is that the last value supplied is replicated for any missing channel.)
126 ///
127 /// Some ImageBufAlgo functions have parameters of type `Image_or_Const`,
128 /// which may take either an ImageBuf reference, or a per-channel constant,
129 /// or a single constant to be used for all channels.
130 ///
131 /// **Multithreading**
132 ///
133 /// All ImageBufAlgo functions take an optional `nthreads` parameter that
134 /// signifies the maximum number of threads to use to parallelize the
135 /// operation. The default value for `nthreads` is 0, which signifies that
136 /// the number of thread should be the OIIO global default set by
137 /// `OIIO::attribute()`, which itself defaults to be the detected level of
138 /// hardware concurrency (number of cores available).
139 ///
140 /// Generally you can ignore this parameter (or pass 0), meaning to use all
141 /// the cores available in order to perform the computation as quickly as
142 /// possible. The main reason to explicitly pass a different number
143 /// (generally 1) is if the application is multithreaded at a high level,
144 /// and the thread calling the ImageBufAlgo function just wants to continue
145 /// doing the computation without spawning additional threads, which might
146 /// tend to crowd out the other application threads.
147 ///
148 ///@}
149 
150 
151 
152 /// Image_or_Const: Parameter-passing helper that is a non-owning reference
153 /// to either an `ImageBuf&`, `ImageBuf*`, per-channel float constant, or a
154 /// single float constant. This lets us tame the combinatorics of functions
155 /// where each of several input parameters may be either images or constant
156 /// values.
158 public:
159  struct None {};
160  Image_or_Const (None) : m_type(NONE) {}
161  Image_or_Const (const ImageBuf &img) : m_type(IMG), m_img(&img) {}
162  Image_or_Const (const ImageBuf *img) : m_type(IMG), m_img(img) {}
163  Image_or_Const (cspan<float> val) : m_type(VAL), m_val(val) {}
164  Image_or_Const (const float& val) : m_type(VAL), m_val(val) {}
165  Image_or_Const (const std::vector<float>& val) : m_type(VAL), m_val(val) {}
166  Image_or_Const (std::initializer_list<const float> val) : m_type(VAL), m_val(val) {}
167  Image_or_Const (const float *v, size_t s) : m_type(VAL), m_val(v,s) {}
168  Image_or_Const (const float *v, int s) : m_type(VAL), m_val(v,s) {}
169 
170  template<size_t N>
171  Image_or_Const(const float (&array)[N]) : Image_or_Const(cspan<float>(array)) {}
172 
173  bool is_img () const { return m_type == IMG; }
174  bool is_val () const { return m_type == VAL; }
175  bool is_empty () const { return m_type == NONE; }
176  const ImageBuf& img () const { return *m_img; }
177  const ImageBuf* imgptr () const { return m_img; }
178  cspan<float> val () const { return m_val; }
179 
180  void swap (Image_or_Const &other) {
181  std::swap (m_type, other.m_type);
182  std::swap (m_img, other.m_img);
183  std::swap (m_val, other.m_val);
184  }
185 private:
186  enum Contents { NONE, VAL, IMG };
187  Contents m_type;
188  const ImageBuf * m_img = nullptr;
189  cspan<float> m_val;
190 };
191 
192 
193 
194 
195 namespace ImageBufAlgo {
196 
197 // old name (DEPRECATED 1.9)
198 OIIO_DEPRECATED("use parallel_options (1.9)")
200 
201 
202 /// Create an all-black `float` image of size and channels as described by
203 /// the ROI.
204 ImageBuf OIIO_API zero (ROI roi, int nthreads=0);
205 /// Write to an existing image `dst` (allocating if it is uninitialized).
206 bool OIIO_API zero (ImageBuf &dst, ROI roi={}, int nthreads=0);
207 
208 
209 /// @defgroup fill (ImageBufAlgo::fill -- fill a region)
210 /// @{
211 ///
212 /// Fill an image region with given channel values, either returning a new
213 /// image or altering the existing `dst` image within the ROI. Note that the
214 /// values arrays start with channel 0, even if the ROI indicates that a
215 /// later channel is the first to be changed.
216 ///
217 /// Three varieties of fill() exist: (a) a single set of channel values that
218 /// will apply to the whole ROI, (b) two sets of values that will create a
219 /// linearly interpolated gradient from top to bottom of the ROI, (c) four
220 /// sets of values that will be bilinearly interpolated across all four
221 /// corners of the ROI.
222 
223 ImageBuf OIIO_API fill (cspan<float> values, ROI roi, int nthreads=0);
225  ROI roi, int nthreads=0);
226 ImageBuf OIIO_API fill (cspan<float> topleft, cspan<float> topright,
227  cspan<float> bottomleft, cspan<float> bottomright,
228  ROI roi, int nthreads=0);
230  ROI roi={}, int nthreads=0);
232  ROI roi={}, int nthreads=0);
233 bool OIIO_API fill (ImageBuf &dst, cspan<float> topleft, cspan<float> topright,
234  cspan<float> bottomleft, cspan<float> bottomright,
235  ROI roi={}, int nthreads=0);
236 /// @}
237 
238 
239 /// Create a checkerboard pattern of size given by `roi`, with origin given
240 /// by the `offset` values, checker size given by the `width`, `height`,
241 /// `depth` values, and alternating between `color1[]` and `color2[]`. The
242 /// pattern is defined in abstract "image space" independently of the pixel
243 /// data window of `dst` or the ROI.
244 ImageBuf OIIO_API checker (int width, int height, int depth,
245  cspan<float> color1, cspan<float> color2,
246  int xoffset, int yoffset, int zoffset,
247  ROI roi, int nthreads=0);
248 /// Write to an existing image `dst` (allocating if it is uninitialized).
249 bool OIIO_API checker (ImageBuf &dst, int width, int height, int depth,
250  cspan<float> color1, cspan<float> color2,
251  int xoffset=0, int yoffset=0, int zoffset=0,
252  ROI roi={}, int nthreads=0);
253 
254 
255 /// Return an image of "noise" in every pixel and channel specified by the
256 /// roi. There are several noise types to choose from, and each behaves
257 /// differently and has a different interpretation of the `A` and `B`
258 /// parameters:
259 ///
260 /// - "gaussian" adds Gaussian (normal distribution) noise values with
261 /// mean value A and standard deviation B.
262 /// - "white" adds independent uniformly distributed values on range
263 /// [A,B).
264 /// - "uniform" (synonym for "white")
265 /// - "blue" adds "blue noise" uniformly distributed on range [A,B) but
266 /// not independent; rather, they are chosen for good spectral
267 /// properties for sampling and dither.
268 /// - "salt" changes to value A a portion of pixels given by B.
269 ///
270 /// If the `mono` flag is true, a single noise value will be applied to all
271 /// channels specified by `roi`, but if `mono` is false, a separate noise
272 /// value will be computed for each channel in the region.
273 ///
274 /// The random number generator is actually driven by a hash on the "image
275 /// space" coordinates and channel, independently of the pixel data window
276 /// of `dst` or the ROI. Choosing different seed values will result in a
277 /// different pattern, but for the same seed value, the noise at a given
278 /// pixel coordinate (x,y,z) channel c will is completely deterministic and
279 /// repeatable.
281  float A = 0.0f, float B = 0.1f, bool mono = false,
282  int seed = 0, ROI roi={}, int nthreads=0);
283 /// Write to an existing image `dst` (allocating if it is uninitialized).
284 bool OIIO_API noise (ImageBuf &dst, string_view noisetype,
285  float A = 0.0f, float B = 0.1f, bool mono = false,
286  int seed = 0, ROI roi={}, int nthreads=0);
287 
288 
289 /// Return a const reference to a periodic bluenoise texture with float data
290 /// in 4 channels that are uncorrelated to each other. Note that unlike most
291 /// other ImageBufAlgo functions, it does not return an ImageBuf by value, but
292 /// by const reference.
294 
295 
296 /// Render a single point at (x,y) of the given color "over" the existing
297 /// image `dst`. If there is no alpha channel, the color will be written
298 /// unconditionally (as if the alpha is 1.0).
299 bool OIIO_API render_point (ImageBuf &dst, int x, int y,
300  cspan<float> color=1.0f,
301  ROI roi={}, int nthreads=0);
302 
303 /// Render a line from pixel (`x1`,`y1`) to (`x2`,`y2`) into `dst`, doing an
304 /// "over" of the color (if it includes an alpha channel) onto the existing
305 /// data in `dst`. The `color` should include as many values as
306 /// `roi.chend-1`. The ROI can be used to limit the pixel area or channels
307 /// that are modified, and default to the entirety of `dst`. If
308 /// `skip_first_point` is `true`, the first point (`x1`, `y1`) will not be
309 /// drawn (this can be helpful when drawing poly-lines, to avoid
310 /// double-rendering of the vertex positions).
311 bool OIIO_API render_line (ImageBuf &dst, int x1, int y1, int x2, int y2,
312  cspan<float> color=1.0f,
313  bool skip_first_point = false,
314  ROI roi={}, int nthreads=0);
315 
316 /// Render a filled or unfilled box with corners at pixels (`x1`,`y1`) and
317 /// (`x2`,`y2`) into `dst`, doing an "over" of the color (if it includes an
318 /// alpha channel) onto the existing data in `dst`. The `color` must include
319 /// as many values as `roi.chend-1`. The ROI can be used to limit the pixel
320 /// area or channels that are modified, and default to the entirety of
321 /// `dst`. If `fill` is `true`, the box will be completely filled in,
322 /// otherwise only its outlien will be drawn.
323 bool OIIO_API render_box (ImageBuf &dst, int x1, int y1, int x2, int y2,
324  cspan<float> color=1.0f, bool fill = false,
325  ROI roi={}, int nthreads=0);
326 
327 
328 enum class TextAlignX { Left, Right, Center };
329 enum class TextAlignY { Baseline, Top, Bottom, Center };
330 
331 /// Render a text string (encoded as UTF-8) into image `dst`. If the `dst`
332 /// image is not yet initialized, it will be initialized to be a black
333 /// background exactly large enough to contain the rasterized text. If
334 /// `dst` is already initialized, the text will be rendered into the
335 /// existing image by essentially doing an "over" of the character into the
336 /// existing pixel data.
337 ///
338 /// @param dst
339 /// Destination ImageBuf -- text is rendered into this image.
340 /// @param x/y
341 /// The position to place the text.
342 /// @param text
343 /// The text to draw. Linefeed (`\n`) characters are respected
344 /// as indications that the text spans multiple rows.
345 /// @param fontsize/fontname
346 /// Size and name of the font. If the name is not a full
347 /// pathname to a font file, it will search for a matching font,
348 /// defaulting to some reasonable system font if not supplied at
349 /// all), and with a nominal height of fontsize (in pixels).
350 /// @param textcolor
351 /// Color for drawing the text, defaulting to opaque white
352 /// (1.0,1.0,...) in all channels if not supplied. If provided,
353 /// it is expected to point to a float array of length at least
354 /// equal to `R.spec().nchannels`, or defaults will be chosen
355 /// for you).
356 /// @param alignx/aligny
357 /// The default behavior is to align the left edge of the
358 /// character baseline to (`x`,`y`). Optionally, `alignx` and
359 /// `aligny` can override the alignment behavior, with
360 /// horizontal alignment choices of TextAlignX::Left, Right, and
361 /// Center, and vertical alignment choices of Baseline, Top,
362 /// Bottom, or Center.
363 /// @param shadow
364 /// If nonzero, a "drop shadow" of this radius will be used to
365 /// make the text look more clear by dilating the alpha channel
366 /// of the composite (makes a black halo around the characters).
367 ///
368 /// Note that any named fonts (if not a full pathname) will search for the
369 /// fonts in the following places: (a) any directories named in the global
370 /// "font_searchpath" attribute or the `$OPENIMAGEIO_FONTS` environment
371 /// variable; (b) any font-related subdirectories (`fonts`, `Fonts`,
372 /// `share/fonts`, or `Library/Fonts`) underneath the directories in
373 /// environment variables `$HOME`, `$SystemRoot`, `$OpenImageIO_ROOT`; (c) a
374 /// number of common system font areas, including `/usr/share/fonts`,
375 /// `/Library/fonts`, and `C:/Windows/fonts`; (d) in fonts directories one
376 /// level up from the place where the currently running binary lives.
377 bool OIIO_API render_text (ImageBuf &dst, int x, int y, string_view text,
378  int fontsize=16, string_view fontname="",
379  cspan<float> textcolor = 1.0f,
380  TextAlignX alignx = TextAlignX::Left,
382  int shadow = 0, ROI roi={}, int nthreads=0);
383 
384 
385 /// The helper function `text_size()` merely computes the dimensions of the
386 /// text, returning it as an ROI relative to the left side of the baseline
387 /// of the first character. Only the `x` and `y` dimensions of the ROI will
388 /// be used. The x dimension runs from left to right, and y runs from top to
389 /// bottom (image coordinates). For a failure (such as an invalid font
390 /// name), the ROI will return `false` if you call its `defined()` method.
391 /// The `text` may contain linefeed characters to designate multiple lines
392 /// of text.
393 ROI OIIO_API text_size (string_view text, int fontsize=16,
394  string_view fontname="");
395 
396 
397 /// Generic channel shuffling: return (or store in `dst`) a copy of `src`,
398 /// but with channels in the order `channelorder[0..nchannels-1]` (or set to
399 /// a constant value, designated by `channelorder[i] = -1` and having the
400 /// fill value in `channelvalues[i]`. In-place operation is allowed (i.e.,
401 /// `dst` and `src` the same image, but an extra copy will occur).
402 ///
403 /// @param nchannels
404 /// The total number of channels that will be set up in the
405 /// `dst` image.
406 /// @param channelorder
407 /// For each channel in `dst`, the index of the `src` channel
408 /// from which to copy. Any `channelorder[i]` < 0 indicates that
409 /// the channel `i` should be filled with constant value
410 /// `channelvalues[i]` rather than copy any channel from `src`.
411 /// If `channelorder` itself is empty, the implied channel order
412 /// will be `{0, 1, ..., nchannels-1}`, meaning that it's only
413 /// renaming, truncating, or extending channels, not reordering
414 /// the channels that are already present.
415 /// @param channelvalues Fill values for color channels in which
416 /// `channelorder[i]` < 0. This can be empty if no channels are
417 /// to be filled with constant values.
418 /// @param newchannelnames
419 /// An array of new channel names. Channels for which this
420 /// specifies an empty string will have their name taken from
421 /// the `src` channel that was copied. If `newchannelnames` is
422 /// entirely empty, all channel names will simply be copied from
423 /// `src`.
424 /// @param shuffle_channel_names
425 /// If true, the channel names will be taken from the
426 /// corresponding channels of the source image -- be careful with
427 /// this, shuffling both channel ordering and their names could
428 /// result in no semantic change at all, if you catch the drift.
429 /// If false (the default), the resulting `dst` image will have
430 /// default channel names in the usual order ("R", "G", etc.).
431 ///
433  int nchannels, cspan<int> channelorder,
434  cspan<float> channelvalues={},
435  cspan<std::string> newchannelnames={},
436  bool shuffle_channel_names=false, int nthreads=0);
437 /// Write to an existing image `dst` (allocating if it is uninitialized).
438 bool OIIO_API channels (ImageBuf &dst, const ImageBuf &src,
439  int nchannels, cspan<int> channelorder,
440  cspan<float> channelvalues={},
441  cspan<std::string> newchannelnames={},
442  bool shuffle_channel_names=false, int nthreads=0);
443 
444 
445 /// Append the channels of `A` and `B` together into `dst` over the region
446 /// of interest. If the region passed is uninitialized (the default), it
447 /// will be interpreted as being the union of the pixel windows of `A` and `B`
448 /// (and all channels of both images). If `dst` is not already initialized,
449 /// it will be resized to be big enough for the region.
451  ROI roi={}, int nthreads=0);
452 /// Write to an existing image `dst` (allocating if it is uninitialized).
453 bool OIIO_API channel_append (ImageBuf &dst, const ImageBuf &A,
454  const ImageBuf &B, ROI roi={}, int nthreads=0);
455 
456 
457 /// Return the specified region of pixels of `src` as specified by `roi`
458 /// (which will default to the whole of `src`, optionally with the pixel
459 /// type overridden by convert (if it is not `TypeUnknown`).
461  ROI roi={}, int nthreads=0);
462 /// Write to an existing image `dst` (allocating if it is uninitialized).
463 /// If `dst` is not already initialized, it will be set to the same size as
464 /// `roi` (defaulting to all of `src`)
465 bool OIIO_API copy (ImageBuf &dst, const ImageBuf &src, TypeDesc convert=TypeUnknown,
466  ROI roi={}, int nthreads=0);
467 
468 
469 /// Return the specified region of `src` as an image, without altering its
470 /// position in the image plane.
471 ///
472 /// Pixels from `src` which are outside `roi` will not be copied, and new
473 /// black pixels will be added for regions of `roi` which were outside the
474 /// data window of `src`.
475 ///
476 /// Note that the `crop` operation does not actually move the pixels on the
477 /// image plane or adjust the full/display window; it merely restricts which
478 /// pixels are copied from `src` to `dst`. (Note the difference compared to
479 /// `cut()`).
480 ImageBuf OIIO_API crop (const ImageBuf &src, ROI roi={}, int nthreads=0);
481 /// Write to an existing image `dst` (allocating if it is uninitialized).
482 bool OIIO_API crop (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
483 
484 
485 /// Return the designated region of `src`, but repositioned to the image
486 /// origin and with the full/display window set to exactly cover the new
487 /// pixel data window. (Note the difference compared to `crop()`).
488 ImageBuf OIIO_API cut (const ImageBuf &src, ROI roi={}, int nthreads=0);
489 /// Write to an existing image `dst` (allocating if it is uninitialized).
490 bool OIIO_API cut (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
491 
492 
493 /// Copy `src` pixels within `srcroi` into the `dst` image, offset so that
494 /// source location (0,0,0) will be copied to destination location
495 /// (`xbegin`,`ybegin`,`zbegin`). If the `srcroi` is `ROI::All()`, the
496 /// entirety of the data window of `src` will be used. It will copy into
497 /// `channels[chbegin...]`, as many channels as are described by srcroi.
498 /// Pixels or channels of `src` inside `srcroi` will replace the
499 /// corresponding destination pixels entirely, whereas `src` pixels outside
500 /// of `srcroi` will not be copied and the corresponding offset pixels of
501 /// `dst` will not be altered.
502 bool OIIO_API paste (ImageBuf &dst, int xbegin, int ybegin,
503  int zbegin, int chbegin, const ImageBuf &src,
504  ROI srcroi={}, int nthreads=0);
505 
506 
507 /// @defgroup rotateN (rotate in 90 degree increments)
508 /// @{
509 ///
510 /// Return (or copy into `dst`) a rotated copy of the image pixels of `src`,
511 /// in 90 degree increments. Pictorially:
512 ///
513 /// rotate90 rotate180 rotate270
514 /// ----------- ----------- -----------
515 /// AB --> CA AB --> DC AB --> BD
516 /// CD DB CD BA CD AC
517 ///
518 
519 ImageBuf OIIO_API rotate90 (const ImageBuf &src, ROI roi={}, int nthreads=0);
520 ImageBuf OIIO_API rotate180 (const ImageBuf &src, ROI roi={}, int nthreads=0);
521 ImageBuf OIIO_API rotate270 (const ImageBuf &src, ROI roi={}, int nthreads=0);
522 bool OIIO_API rotate90 (ImageBuf &dst, const ImageBuf &src,
523  ROI roi={}, int nthreads=0);
524 bool OIIO_API rotate180 (ImageBuf &dst, const ImageBuf &src,
525  ROI roi={}, int nthreads=0);
526 bool OIIO_API rotate270 (ImageBuf &dst, const ImageBuf &src,
527  ROI roi={}, int nthreads=0);
528 /// @}
529 
530 
531 /// @defgroup flip-flop-transpose (flip/flop/transpose: mirroring)
532 /// @{
533 ///
534 /// Return (or copy into `dst`) a subregion of `src`, but with the scanlines
535 /// exchanged vertically (flip), or columns exchanged horizontally (flop),
536 /// or transposed across the diagonal by swapping rows for columns
537 /// (transpose) within the display/full window. In other words,
538 ///
539 /// flip flop transpose
540 /// ----------- ----------- -----------
541 /// AB --> CD AB --> BA AB --> AC
542 /// CD AB CD DC CD BD
543 ///
544 
545 ImageBuf OIIO_API flip (const ImageBuf &src, ROI roi={}, int nthreads=0);
546 ImageBuf OIIO_API flop (const ImageBuf &src, ROI roi={}, int nthreads=0);
547 ImageBuf OIIO_API transpose (const ImageBuf &src, ROI roi={}, int nthreads=0);
548 bool OIIO_API flip (ImageBuf &dst, const ImageBuf &src,
549  ROI roi={}, int nthreads=0);
550 bool OIIO_API flop (ImageBuf &dst, const ImageBuf &src,
551  ROI roi={}, int nthreads=0);
552 bool OIIO_API transpose (ImageBuf &dst, const ImageBuf &src,
553  ROI roi={}, int nthreads=0);
554 /// @}
555 
556 
557 /// Return (or store into `dst`) a copy of `src`, but with whatever seties
558 /// of rotations, flips, or flops are necessary to transform the pixels into
559 /// the configuration suggested by the "Orientation" metadata of the image
560 /// (and the "Orientation" metadata is then set to 1, ordinary orientation).
561 ImageBuf OIIO_API reorient (const ImageBuf &src, int nthreads=0);
562 /// Write to an existing image `dst` (allocating if it is uninitialized).
563 bool OIIO_API reorient (ImageBuf &dst, const ImageBuf &src, int nthreads=0);
564 
565 
566 /// Return a subregion of `src`, but circularly shifting by the given
567 /// amount. To clarify, the circular shift of [0,1,2,3,4,5] by +2 is
568 /// [4,5,0,1,2,3].
570  int xshift, int yshift, int zshift=0,
571  ROI roi={}, int nthreads=0);
572 /// Write to an existing image `dst` (allocating if it is uninitialized).
573 bool OIIO_API circular_shift (ImageBuf &dst, const ImageBuf &src,
574  int xshift, int yshift, int zshift=0,
575  ROI roi={}, int nthreads=0);
576 
577 
578 /// @defgroup rotate (rotate: arbitrary rotation)
579 /// @{
580 ///
581 /// Rotate the `src` image by the `angle` (in radians, with positive angles
582 /// clockwise). When `center_x` and `center_y` are supplied, they denote the
583 /// center of rotation, in pixel coordinates; in their absence, the rotation
584 /// will be about the center of the image's display window.
585 ///
586 /// Only the pixels (and channels) of `dst` that are specified by `roi` will
587 /// be copied from the rotated `src`; the default `roi` is to alter all the
588 /// pixels in `dst`. If `dst` is uninitialized, it will be resized to be an
589 /// ImageBuf large enough to hold the rotated image if recompute_roi is
590 /// true, or will have the same ROI as `src` if `recompute_roi` is `false`.
591 /// It is an error to pass both an uninitialized `dst` and an undefined
592 /// `roi`.
593 ///
594 /// The filter is used to weight the `src` pixels falling underneath it for
595 /// each `dst` pixel. The caller may specify a reconstruction filter by
596 /// name and width (expressed in pixels units of the `dst` image), or
597 /// `rotate()` will choose a reasonable default high-quality default filter
598 /// (lanczos3) if the empty string is passed, and a reasonable filter width
599 /// if `filterwidth` is 0. (Note that some filter choices only make sense
600 /// with particular width, in which case this filterwidth parameter may be
601 /// ignored.)
602 
603 ImageBuf OIIO_API rotate (const ImageBuf &src, float angle,
604  string_view filtername = string_view(),
605  float filterwidth = 0.0f, bool recompute_roi = false,
606  ROI roi={}, int nthreads=0);
607 ImageBuf OIIO_API rotate (const ImageBuf &src, float angle,
608  Filter2D *filter, bool recompute_roi = false,
609  ROI roi={}, int nthreads=0);
610 ImageBuf OIIO_API rotate (const ImageBuf &src,
611  float angle, float center_x, float center_y,
612  string_view filtername = string_view(),
613  float filterwidth = 0.0f, bool recompute_roi = false,
614  ROI roi={}, int nthreads=0);
615 ImageBuf OIIO_API rotate (const ImageBuf &src,
616  float angle, float center_x, float center_y,
617  Filter2D *filter, bool recompute_roi = false,
618  ROI roi={}, int nthreads=0);
619 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src, float angle,
620  string_view filtername = string_view(),
621  float filterwidth = 0.0f, bool recompute_roi = false,
622  ROI roi={}, int nthreads=0);
623 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src, float angle,
624  Filter2D *filter, bool recompute_roi = false,
625  ROI roi={}, int nthreads=0);
626 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src,
627  float angle, float center_x, float center_y,
628  string_view filtername = string_view(),
629  float filterwidth = 0.0f, bool recompute_roi = false,
630  ROI roi={}, int nthreads=0);
631 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src,
632  float angle, float center_x, float center_y,
633  Filter2D *filter, bool recompute_roi = false,
634  ROI roi={}, int nthreads=0);
635 /// @}
636 
637 
638 /// @defgroup resize (resize: resize the image with nicely filtered results)
639 /// @{
640 ///
641 /// Set `dst`, over the region of interest, to be a resized version of the
642 /// corresponding portion of `src` (mapping such that the "full" image
643 /// window of each correspond to each other, regardless of resolution).
644 /// If `dst` is not yet initialized, it will be sized according to `roi`.
645 ///
646 /// The caller may either (a) explicitly pass a reconstruction `filter`, or
647 /// (b) specify one by `filtername` and `filterwidth`. If `filter` is
648 /// `nullptr` or if `filtername` is the empty string `resize()` will choose
649 /// a reasonable high-quality default (blackman-harris when upsizing,
650 /// lanczos3 when downsizing). The filter is used to weight the `src`
651 /// pixels falling underneath it for each `dst` pixel; the filter's size is
652 /// expressed in pixel units of the `dst` image.
653 
654 ImageBuf OIIO_API resize (const ImageBuf &src,
655  string_view filtername = "", float filterwidth=0.0f,
656  ROI roi={}, int nthreads=0);
657 ImageBuf OIIO_API resize (const ImageBuf &src, Filter2D *filter,
658  ROI roi={}, int nthreads=0);
659 bool OIIO_API resize (ImageBuf &dst, const ImageBuf &src,
660  string_view filtername = "", float filterwidth=0.0f,
661  ROI roi={}, int nthreads=0);
662 bool OIIO_API resize (ImageBuf &dst, const ImageBuf &src, Filter2D *filter,
663  ROI roi={}, int nthreads=0);
664 /// @}
665 
666 
667 /// Set `dst`, over the region of interest, to be a resized version of the
668 /// corresponding portion of `src` (mapping such that the "full" image
669 /// window of each correspond to each other, regardless of resolution). If
670 /// `dst` is not yet initialized, it will be sized according to `roi`.
671 ///
672 /// Unlike `ImageBufAlgo::resize()`, `resample()` does not take a filter; it
673 /// just samples either with a bilinear interpolation (if `interpolate` is
674 /// `true`, the default) or uses the single "closest" pixel (if
675 /// `interpolate` is `false`). This makes it a lot faster than a proper
676 /// `resize()`, though obviously with lower quality (aliasing when
677 /// downsizing, pixel replication when upsizing).
678 ///
679 /// For "deep" images, this function returns copies the closest source pixel
680 /// needed, rather than attempting to interpolate deep pixels (regardless of
681 /// the value of `interpolate`).
682 ///
683 /// @see ImageBufAlgo::resize()
684 
685 ImageBuf OIIO_API resample (const ImageBuf &src, bool interpolate = true,
686  ROI roi={}, int nthreads=0);
687 /// Write to an existing image `dst` (allocating if it is uninitialized).
688 bool OIIO_API resample (ImageBuf &dst, const ImageBuf &src,
689  bool interpolate = true, ROI roi={}, int nthreads=0);
690 
691 
692 /// @defgroup fit (fit: resize the image with filtering, into a fixed size)
693 /// @{
694 ///
695 /// Fit src into `dst` (to a size specified by `roi`, if `dst` is not
696 /// initialized), resizing but preserving its original aspect ratio. Thus,
697 /// it will resize to be the largest size with the same aspect ratio that
698 /// can fit inside the region, but will not stretch to completely fill it in
699 /// both dimensions.
700 ///
701 /// The `fillmode` determines which of several methods will be used to
702 /// determine how the image will fill the new frame, if its aspect ratio
703 /// does not precisely match the original source aspect ratio:
704 /// - "width" exactly fills the width of the new frame, either cropping
705 /// or letterboxing the height if it isn't precisely the right size to
706 /// preserve the original aspect ratio.
707 /// - "height" exactly fills the height of the new frame, either cropping
708 /// or letterboxing the width if it isn't precisely the right size to
709 /// preserve the original aspect ratio.
710 /// - "letterbox" (the default) chooses whichever of "width" or "height"
711 /// will maximally fill the new frame with no image data lost (it will
712 /// only letterbox, never crop).
713 ///
714 /// If `exact` is true, will result in an exact match on aspect ratio and
715 /// centering (partial pixel shift if necessary), whereas exact=false
716 /// will only preserve aspect ratio and centering to the precision of a
717 /// whole pixel.
718 ///
719 /// The filter is used to weight the `src` pixels falling underneath it for
720 /// each `dst` pixel. The caller may specify a reconstruction filter by
721 /// name and width (expressed in pixels units of the `dst` image), or
722 /// `rotate()` will choose a reasonable default high-quality default filter
723 /// (lanczos3) if the empty string is passed, and a reasonable filter width
724 /// if `filterwidth` is 0. (Note that some filter choices only make sense
725 /// with particular width, in which case this filterwidth parameter may be
726 /// ignored.)
727 ///
728 ImageBuf OIIO_API fit (const ImageBuf &src,
729  string_view filtername = "", float filterwidth=0.0f,
730  string_view fillmode="letterbox", bool exact=false,
731  ROI roi={}, int nthreads=0);
732 ImageBuf OIIO_API fit (const ImageBuf &src, Filter2D *filter,
733  string_view fillmode="letterbox", bool exact=false,
734  ROI roi={}, int nthreads=0);
735 bool OIIO_API fit (ImageBuf &dst, const ImageBuf &src,
736  string_view filtername = "", float filterwidth=0.0f,
737  string_view fillmode="letterbox", bool exact=false,
738  ROI roi={}, int nthreads=0);
739 bool OIIO_API fit (ImageBuf &dst, const ImageBuf &src, Filter2D *filter,
740  string_view fillmode="letterbox", bool exact=false,
741  ROI roi={}, int nthreads=0);
742 
743 #ifndef DOXYGEN_SHOULD_SKIP_THIS
744 // DEPRECATED(2.3): old versions lacking the "fillmode" parameter
745 ImageBuf OIIO_API fit (const ImageBuf &src,
746  string_view filtername, float filterwidth,
747  bool exact, ROI roi={}, int nthreads=0);
748 ImageBuf OIIO_API fit (const ImageBuf &src, Filter2D *filter,
749  bool exact, ROI roi={}, int nthreads=0);
750 bool OIIO_API fit (ImageBuf &dst, const ImageBuf &src,
751  string_view filtername, float filterwidth,
752  bool exact, ROI roi={}, int nthreads=0);
753 bool OIIO_API fit (ImageBuf &dst, const ImageBuf &src, Filter2D *filter,
754  bool exact, ROI roi={}, int nthreads=0);
755 #endif
756 /// @}
757 
758 
759 /// @defgroup warp (warp: arbitrary warp by a 3x3 matrix)
760 /// @{
761 ///
762 /// Warp the `src` image using the supplied 3x3 transformation matrix.
763 ///
764 /// Only the pixels (and channels) of `dst` that are specified by `roi` will
765 /// be copied from the warped `src`; the default roi is to alter all the
766 /// pixels in dst. If `dst` is uninitialized, it will be sized to be an
767 /// ImageBuf large enough to hold the warped image if recompute_roi is true,
768 /// or will have the same ROI as src if recompute_roi is false. It is an
769 /// error to pass both an uninitialized `dst` and an undefined `roi`.
770 ///
771 /// The caller may explicitly pass a reconstruction filter, or specify one
772 /// by name and size, or if the name is the empty string `resize()` will
773 /// choose a reasonable high-quality default if `nullptr` is passed. The
774 /// filter is used to weight the `src` pixels falling underneath it for each
775 /// `dst` pixel; the filter's size is expressed in pixel units of the `dst`
776 /// image.
777 
778 ImageBuf OIIO_API warp (const ImageBuf &src, M33fParam M,
779  string_view filtername = string_view(),
780  float filterwidth = 0.0f, bool recompute_roi = false,
782  ROI roi={}, int nthreads=0);
783 ImageBuf OIIO_API warp (const ImageBuf &src, M33fParam M,
784  const Filter2D *filter, bool recompute_roi = false,
786  ROI roi = {}, int nthreads=0);
787 bool OIIO_API warp (ImageBuf &dst, const ImageBuf &src, M33fParam M,
788  string_view filtername = string_view(),
789  float filterwidth = 0.0f, bool recompute_roi = false,
791  ROI roi={}, int nthreads=0);
792 bool OIIO_API warp (ImageBuf &dst, const ImageBuf &src, M33fParam M,
793  const Filter2D *filter, bool recompute_roi = false,
795  ROI roi = {}, int nthreads=0);
796 
797 #ifdef OIIO_INTERNAL /* experimental -- not part of public API yet */
798 ImageBuf OIIO_API warp (const ImageBuf &src, M33fParam M,
799  string_view filtername,
800  float filterwidth, bool recompute_roi,
801  ImageBuf::WrapMode wrap, bool edgeclamp,
802  ROI roi={}, int nthreads=0);
803 ImageBuf OIIO_API warp (const ImageBuf &src, M33fParam M,
804  const Filter2D *filter, bool recompute_roi,
805  ImageBuf::WrapMode wrap, bool edgeclamp,
806  ROI roi = {}, int nthreads=0);
807 bool OIIO_API warp (ImageBuf &dst, const ImageBuf &src, M33fParam M,
808  string_view filtername,
809  float filterwidth, bool recompute_roi,
810  ImageBuf::WrapMode wrap, bool edgeclamp,
811  ROI roi={}, int nthreads=0);
812 bool OIIO_API warp (ImageBuf &dst, const ImageBuf &src, M33fParam M,
813  const Filter2D *filter, bool recompute_roi,
814  ImageBuf::WrapMode wrap, bool edgeclamp,
815  ROI roi = {}, int nthreads=0);
816 #endif // OIIO_INTERNAL
817 /// @}
818 
819 
820 /// @defgroup st_warp (st_warp: warp an image using per-pixel st coordinates)
821 /// @{
822 ///
823 /// Warp the `src` image using "st" coordinates from a secondary `stbuf` image.
824 ///
825 /// Each pixel in the `stbuf` image is used as a normalized image-space
826 /// coordinate in the `src` image, which is then sampled at that position using
827 /// the given reconstruction filter to produce an output pixel.
828 ///
829 /// The transform is only defined over the area of the `stbuf` image, and thus
830 /// the given `roi` argument will be intersected with its geometry.
831 ///
832 /// \b NOTE: The current behavior of this transform is modeled to match Nuke's
833 /// STMap node.
834 ///
835 /// @param dst
836 /// The output ImageBuf. If an initialized buffer is provided, its
837 /// full-size dimensions must match those of `stbuf`.
838 /// @param src
839 /// The source ImageBuf to warp.
840 /// @param stbuf
841 /// The ImageBuf holding the st coordinates. This must be holding
842 /// a floating-point pixel data type.
843 /// @param chan_s
844 /// The index of the "s" channel in the `stbuf` image. This defaults
845 /// to its first channel.
846 /// @param chan_t
847 /// The index of the "t" channel in the `stbuf` image. This defaults
848 /// to its second channel.
849 /// @param flip_s
850 /// Whether to mirror the "s" coordinate along the horizontal axis
851 /// when computing source pixel positions. This is useful if the
852 /// coordinates are defined in terms of a different image origin
853 /// than OpenImageIO's.
854 /// @param flip_t
855 /// Whether to mirror the "t" coordinate along the vertical axis
856 /// when computing source pixel positions. This is useful if the
857 /// coordinates are defined in terms of a different image origin
858 /// than OpenImageIO's.
859 
860 ImageBuf OIIO_API st_warp (const ImageBuf &src, const ImageBuf& stbuf,
861  string_view filtername=string_view(),
862  float filterwidth=0.0f, int chan_s=0, int chan_t=1,
863  bool flip_s=false, bool flip_t=false, ROI roi={},
864  int nthreads=0);
865 ImageBuf OIIO_API st_warp (const ImageBuf &src, const ImageBuf& stbuf,
866  const Filter2D *filter, int chan_s=0, int chan_t=1,
867  bool flip_s=false, bool flip_t=false, ROI roi={},
868  int nthreads=0);
869 bool OIIO_API st_warp (ImageBuf &dst, const ImageBuf &src,
870  const ImageBuf& stbuf,
871  string_view filtername=string_view(),
872  float filterwidth=0.0f, int chan_s=0, int chan_t=1,
873  bool flip_s=false, bool flip_t=false, ROI roi={},
874  int nthreads=0);
875 bool OIIO_API st_warp (ImageBuf &dst, const ImageBuf &src,
876  const ImageBuf& stbuf, const Filter2D *filter,
877  int chan_s=0, int chan_t=1, bool flip_s=false,
878  bool flip_t=false, ROI roi={}, int nthreads=0);
879 /// @}
880 
881 
882 /// Compute per-pixel sum `A + B`, returning the result image.
883 ///
884 /// `A` and `B` may each either be an `ImageBuf&`, or a `cspan<float>`
885 /// giving a per- channel constant, or a single constant used for all
886 /// channels. (But at least one must be an image.)
888  ROI roi={}, int nthreads=0);
889 /// Write to an existing image `dst` (allocating if it is uninitialized).
891  ROI roi={}, int nthreads=0);
892 
893 
894 /// Compute per-pixel signed difference `A - B`, returning the result image.
895 ///
896 /// `A` and `B` may each either be an `ImageBuf&`, or a `cspan<float>`
897 /// giving a per-channel constant, or a single constant used for all
898 /// channels. (But at least one must be an image.)
900  ROI roi={}, int nthreads=0);
901 /// Write to an existing image `dst` (allocating if it is uninitialized).
903  ROI roi={}, int nthreads=0);
904 
905 
906 /// Compute per-pixel absolute difference `abs(A - B)`, returning the result
907 /// image.
908 ///
909 /// `A` and `B` may each either be an `ImageBuf&`, or a `cspan<float>`
910 /// giving a per- channel constant, or a single constant used for all
911 /// channels. (But at least one must be an image.)
913  ROI roi={}, int nthreads=0);
914 /// Write to an existing image `dst` (allocating if it is uninitialized).
916  ROI roi={}, int nthreads=0);
917 
918 
919 /// Compute per-pixel absolute value `abs(A)`, returning the result image.
920 ImageBuf OIIO_API abs (const ImageBuf &A, ROI roi={}, int nthreads=0);
921 /// Write to an existing image `dst` (allocating if it is uninitialized).
922 bool OIIO_API abs (ImageBuf &dst, const ImageBuf &A, ROI roi={}, int nthreads=0);
923 
924 
925 /// Compute per-pixel product `A * B`, returning the result image.
926 ///
927 /// Either both `A` and `B` are images, or one is an image and the other is
928 /// a `cspan<float>` giving a per-channel constant or a single constant
929 /// used for all channels.
931  ROI roi={}, int nthreads=0);
932 /// Write to an existing image `dst` (allocating if it is uninitialized).
934  ROI roi={}, int nthreads=0);
935 
936 
937 /// Compute per-pixel division `A / B`, returning the result image.
938 /// Division by zero is defined to result in zero.
939 ///
940 /// `A` is always an image, and `B` is either an image or a `cspan<float>`
941 /// giving a per-channel constant or a single constant used for all
942 /// channels.
944  ROI roi={}, int nthreads=0);
945 /// Write to an existing image `dst` (allocating if it is uninitialized).
947  ROI roi={}, int nthreads=0);
948 
949 
950 /// Compute per-pixel multiply-and-add `A * B + C`, returning the result
951 /// image.
952 ///
953 /// `A`, `B`, and `C` are each either an image, or a `cspan<float>` giving a
954 /// per-channel constant or a single constant used for all channels. (Note:
955 /// at least one must be an image.)
957  Image_or_Const C, ROI roi={}, int nthreads=0);
958 /// Write to an existing image `dst` (allocating if it is uninitialized).
960  Image_or_Const C, ROI roi={}, int nthreads=0);
961 
962 
963 /// Return the composite of `A` over `B` using the Porter/Duff definition of
964 /// "over", returning true upon success and false for any of a variety of
965 /// failures (as described below).
966 ///
967 /// `A` and `B` (and dst, if already defined/allocated) must have valid
968 /// alpha channels identified by their ImageSpec `alpha_channel` field. If`
969 /// A` or `B` do not have alpha channels (as determined by those rules) or
970 /// if the number of non-alpha channels do not match between `A` and `B`,
971 /// `over()` will fail, returning false.
972 ///
973 /// If `dst` is not already an initialized ImageBuf, it will be sized to
974 /// encompass the minimal rectangular pixel region containing the union of
975 /// the defined pixels of `A` and `B`, and with a number of channels equal
976 /// to the number of non-alpha channels of `A` and `B`, plus an alpha
977 /// channel. However, if `dst` is already initialized, it will not be
978 /// resized, and the "over" operation will apply to its existing pixel data
979 /// window. In this case, dst must have an alpha channel designated and
980 /// must have the same number of non-alpha channels as `A` and `B`,
981 /// otherwise it will fail, returning false.
982 ///
983 /// `A`, `B`, and `dst` need not perfectly overlap in their pixel data
984 /// windows; pixel values of `A` or `B` that are outside their respective
985 /// pixel data window will be treated as having "zero" (0,0,0...) value.
986 ImageBuf OIIO_API over (const ImageBuf &A, const ImageBuf &B,
987  ROI roi={}, int nthreads=0);
988 /// Write to an existing image `dst` (allocating if it is uninitialized).
989 bool OIIO_API over (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
990  ROI roi={}, int nthreads=0);
991 
992 
993 /// Just like `ImageBufAlgo::over()`, but inputs `A` and `B` must have
994 /// designated 'z' channels, and on a pixel-by-pixel basis, the z values
995 /// will determine which of `A` or `B` will be considered the foreground or
996 /// background (lower z is foreground). If `z_zeroisinf` is true, then z=0
997 /// values will be treated as if they are infinitely far away.
998 ImageBuf OIIO_API zover (const ImageBuf &A, const ImageBuf &B,
999  bool z_zeroisinf=false, ROI roi={}, int nthreads=0);
1000 /// Write to an existing image `dst` (allocating if it is uninitialized).
1001 bool OIIO_API zover (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
1002  bool z_zeroisinf=false, ROI roi={}, int nthreads=0);
1003 
1004 
1005 
1006 /// Compute per-pixel value inverse `1.0 - A` (which you can think of as
1007 /// roughly meaning switching white and black), returning the result image.
1008 ///
1009 /// Tips for callers: (1) You probably want to set `roi` to restrict the
1010 /// operation to only the color channels, and not accidentally include
1011 /// alpha, z, or others. (2) There may be situations where you want to
1012 /// `unpremult()` before the invert, then `premult()` the result, so that
1013 /// you are computing the inverse of the unmasked color.
1014 ImageBuf OIIO_API invert (const ImageBuf &A, ROI roi={}, int nthreads=0);
1015 /// Write to an existing image `dst` (allocating if it is uninitialized).
1016 bool OIIO_API invert (ImageBuf &dst, const ImageBuf &A, ROI roi={}, int nthreads=0);
1017 
1018 
1019 /// Compute per-pixel raise-to-power `A ^ B`. returning the result image. It
1020 /// is permitted for `dst` and `A` to be the same image.
1021 ///
1022 /// `A` is always an image, and `B` is either an image or a `cspan<float>`
1023 /// giving a per-channel constant or a single constant used for all
1024 /// channels.
1026  ROI roi={}, int nthreads=0);
1027 /// Write to an existing image `dst` (allocating if it is uninitialized).
1028 bool OIIO_API pow (ImageBuf &dst, const ImageBuf &A, cspan<float> B,
1029  ROI roi={}, int nthreads=0);
1030 
1031 /// Normalize a 3D vector texture (i.e., divide each pixel by its length).
1032 /// This function assumes a 3-channel image that represents a 3-vector, or a
1033 /// 4-channel image that represents a 3-vector plus an alpha value. If an
1034 /// alpha channel is present, its value is merely copied, and is not part of
1035 /// the normalization computation. If the destination has no alpha channel but
1036 /// the sources do, the alpha channel will be dropped.
1037 ///
1038 /// `inCenter` and `outCenter` define the pixel value that corresponds to a
1039 /// 0.0 vector value for input and output, respectively. `scale` defines the
1040 /// scale factor to apply to the normalized vectors.
1041 ///
1042 /// Thus, if the input image encodes vector components into [0,1] range pixel
1043 /// values so that a pixel value 0.5 indicates a 0-length vector, then you
1044 /// should use `inCenter=0.5`, whereas if they are already using the full
1045 /// range (0.0 is encoded as 0.0), then you want `inCenter=0.0`. Similarly, if
1046 /// you want the output normalized vectors to be in the range [0,1], use
1047 /// `outCenter=0.5` and `scale=0.5`, but if you want them to be in the range
1048 /// [-1,1], use `outCenter=0.0` and `scale=1.0` (this probably will only work
1049 /// if you intend to write the results in `float` or `half` format).
1050 ///
1051 /// Expressed another way, the computation is conceptually:
1052 ///
1053 /// out = outCenter + scale * (in - inCenter) / length(in - inCenter)
1054 ///
1055 bool OIIO_API normalize(ImageBuf& dst, const ImageBuf& A, float inCenter=0.0f,
1056  float outCenter=0.0f, float scale=1.0f,
1057  ROI roi={}, int nthreads=0);
1058 
1059 ImageBuf OIIO_API normalize(const ImageBuf& A, float inCenter=0.0f,
1060  float outCenter=0.0, float scale=1.0f,
1061  ROI roi={}, int nthreads=0);
1062 
1063 
1064 /// Converts a multi-channel image into a one-channel image via a weighted
1065 /// sum of channels:
1066 ///
1067 /// (channel[0]*weight[0] + channel[1]*weight[1] + ...)
1068 ///
1069 /// returning the resulting one-channel image. The `weights`, if not
1070 /// supplied, default to `{ 1, 1, 1, ... }`).
1071 ImageBuf OIIO_API channel_sum (const ImageBuf &src, cspan<float> weights=1.0f,
1072  ROI roi={}, int nthreads=0);
1073 /// Write to an existing image `dst` (allocating if it is uninitialized).
1074 bool OIIO_API channel_sum (ImageBuf &dst, const ImageBuf &src,
1075  cspan<float> weights=1.0f,
1076  ROI roi={}, int nthreads=0);
1077 
1078 
1079 /// @defgroup maxminclamp (Maximum, minimum, clamping)
1080 /// @{
1081 ///
1082 /// `max()` and `min()` take the pixel-by-pixel, channel-by-channel
1083 /// maximum and minimum of two images, or of an image and a constant.
1084 ///
1085 /// `clamp()` restricts values of an image to the range between per-channel
1086 /// minimum and maximum constant values.
1087 
1088 
1089 /// Compute per-pixel `max(A, B)`, returning the result image.
1090 ///
1091 /// Either both `A` and `B` are images, or one is an image and the other is
1092 /// a `cspan<float>` giving a per-channel constant or a single constant
1093 /// used for all channels.
1095  ROI roi={}, int nthreads=0);
1096 /// Write to an existing image `dst` (allocating if it is uninitialized).
1098  ROI roi={}, int nthreads=0);
1099 
1100 /// Compute per-pixel `min(A, B)`, returning the result image.
1101 ///
1102 /// Either both `A` and `B` are images, or one is an image and the other is
1103 /// a `cspan<float>` giving a per-channel constant or a single constant
1104 /// used for all channels.
1106  ROI roi={}, int nthreads=0);
1107 /// Write to an existing image `dst` (allocating if it is uninitialized).
1109  ROI roi={}, int nthreads=0);
1110 
1111 
1112 
1113 /// Return pixels of `src` with pixel values clamped as follows:
1114 /// @param min
1115 /// The minimum clamp value for each channel. If `min` is
1116 /// empty, no minimum clamping is performed.
1117 /// @param max
1118 /// The maximum clamp value for each channel. If `max` is
1119 /// empty, no maximum clamping is performed.
1120 /// @param clampalpha01
1121 /// If true, then additionally any alpha channel is clamped
1122 /// to the 0-1 range.
1123 ImageBuf OIIO_API clamp (const ImageBuf &src,
1126  bool clampalpha01 = false, ROI roi={}, int nthreads=0);
1127 /// Write to an existing image `dst` (allocating if it is uninitialized).
1128 bool OIIO_API clamp (ImageBuf &dst, const ImageBuf &src,
1131  bool clampalpha01 = false, ROI roi={}, int nthreads=0);
1132 
1133 /// @}
1134 
1135 
1136 /// @defgroup maxminchan (Maximum / minimum of channels)
1137 /// @{
1138 ///
1139 /// `maxchan()` computes a one-channel image that for each pixel, contains the
1140 /// maximum value of all channels of corresponding pixel of the source image.
1141 /// `minchan()` similarly computes the minimum value of all channels.
1142 ///
1143 /// @version 2.3.10
1144 
1145 ImageBuf OIIO_API maxchan (const ImageBuf& A, ROI roi={}, int nthreads=0);
1146 bool OIIO_API maxchan (ImageBuf &dst, const ImageBuf& A,
1147  ROI roi={}, int nthreads=0);
1148 
1149 ImageBuf OIIO_API minchan (const ImageBuf& src, ROI roi={}, int nthreads=0);
1150 bool OIIO_API minchan (ImageBuf &dst, const ImageBuf& src,
1151  ROI roi={}, int nthreads=0);
1152 /// @}
1153 
1154 
1155 /// Return pixel values that are a contrast-remap of the corresponding
1156 /// values of the `src` image, transforming pixel value domain [black,
1157 /// white] to range [min, max], either linearly or with optional application
1158 /// of a smooth sigmoidal remapping (if `scontrast` != 1.0).
1159 ///
1160 /// The following steps are performed, in order:
1161 ///
1162 /// 1. Linearly rescale values [`black`, `white`] to [0, 1].
1163 /// 2. If `scontrast` != 1, apply a sigmoidal remapping where a larger
1164 /// `scontrast` value makes a steeper slope, and the steepest part is at
1165 /// value `sthresh` (relative to the new remapped value after steps 1 &
1166 /// 2; the default is 0.5).
1167 /// 3. Rescale the range of that result: 0.0 -> `min` and 1.0 -> `max`.
1168 ///
1169 /// Values outside of the [black,white] range will be extrapolated to
1170 /// outside [min,max], so it may be prudent to apply a clamp() to the
1171 /// results.
1172 ///
1173 /// The black, white, min, max, scontrast, sthresh parameters may each
1174 /// either be a single float value for all channels, or a span giving
1175 /// per-channel values.
1176 ///
1177 /// You can use this function for a simple linear contrast remapping of
1178 /// [black, white] to [min, max] if you use the default values for sthresh.
1179 /// Or just a simple sigmoidal contrast stretch within the [0,1] range if
1180 /// you leave all other parameters at their defaults, or a combination of
1181 /// these effects. Note that if `black` == `white`, the result will be a
1182 /// simple binary thresholding where values < `black` map to `min` and
1183 /// values >= `black` map to `max`.
1184 
1186  cspan<float> black=0.0f, cspan<float> white=1.0f,
1188  cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f,
1189  ROI={}, int nthreads=0);
1190 /// Write to an existing image `dst` (allocating if it is uninitialized).
1191 OIIO_API bool contrast_remap (ImageBuf &dst, const ImageBuf &src,
1192  cspan<float> black=0.0f, cspan<float> white=1.0f,
1194  cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f,
1195  ROI={}, int nthreads=0);
1196 
1197 
1198 /// @defgroup saturate (Adjust saturation of color channels)
1199 /// @{
1200 ///
1201 /// Increase or decrease color saturation of the image.
1202 ///
1203 /// The `saturate` operation returns (or copies into `dst`) the pixels of
1204 /// `src` within the ROI, and in the process adjusts the color saturation of
1205 /// the three consecutive channels starting with `firstchannel` based on the
1206 /// `scale` parameter: 0.0 fully desaturates to a greyscale image of
1207 /// percaptually equivalent luminance, 1.0 leaves the colors unchanged,
1208 /// `scale` values inside this range interpolate between them, and `scale` > 1
1209 /// would increase apparent color saturation.
1210 ///
1211 /// Channels that are within the range of `roi.chbegin` to `roi.chend-1`, but
1212 /// outside the range of `firstchannel` to `firstchannel+2` are simply copied
1213 /// unaltered. Only three channels at a time can be desaturated, by default
1214 /// the first three channels, though `firstchannel` may be used to specify a
1215 /// different subset of channels. It is allowed for `src` and `dst` to be the
1216 /// same image.
1217 ///
1218 /// @version 2.4+
1219 
1220 ImageBuf OIIO_API saturate (const ImageBuf &src, float scale = 0.0f,
1221  int firstchannel = 0, ROI roi={}, int nthreads=0);
1222 bool OIIO_API saturate (ImageBuf &dst, const ImageBuf &src, float scale = 0.0f,
1223  int firstchannel = 0, ROI roi={}, int nthreads=0);
1224 /// @}
1225 
1226 
1227 
1228 /// @defgroup color_map (Remap value range by spline or name)
1229 /// @{
1230 ///
1231 /// Remap value range by spline or name
1232 ///
1233 /// Return (or copy into `dst`) pixel values determined by looking up a
1234 /// color map using values of the source image, using either the channel
1235 /// specified by `srcchannel`, or the luminance of `src`'s RGB if
1236 /// `srcchannel` is -1. This happens for all pixels within the ROI (which
1237 /// defaults to all of `src`), and if `dst` is not already initialized, it
1238 /// will be initialized to the ROI and with color channels equal to
1239 /// `channels`.
1240 ///
1241 /// In the variant that takes a `knots` parameter, this specifies the values
1242 /// of a linearly-interpolated color map given by `knots[nknots*channels]`.
1243 /// An input value of 0.0 is mapped to `knots[0..channels-1]` (one value for
1244 /// each color channel), and an input value of 1.0 is mapped to
1245 /// `knots[(nknots-1)*channels..knots.size()-1]`.
1246 ///
1247 /// In the variant that takes a `mapname` parameter, this is the name of a
1248 /// color map. Recognized map names include: "inferno", "viridis", "magma",
1249 /// "plasma", all of which are perceptually uniform, strictly increasing in
1250 /// luminance, look good when converted to grayscale, and work for people
1251 /// with all types of colorblindness. Also "turbo" has most of these
1252 /// properties (except for being strictly increasing in luminance) and
1253 /// is a nice rainbow-like pattern. Also supported are the following color
1254 /// maps that do not have those desirable qualities (and are thus not
1255 /// recommended, but are present for back-compatibility or for use by
1256 /// clueless people): "blue-red", "spectrum", and "heat". In all cases, the
1257 /// implied `channels` is 3.
1258 
1259 ImageBuf OIIO_API color_map (const ImageBuf &src, int srcchannel,
1260  int nknots, int channels, cspan<float> knots,
1261  ROI roi={}, int nthreads=0);
1262 ImageBuf OIIO_API color_map (const ImageBuf &src, int srcchannel,
1263  string_view mapname, ROI roi={}, int nthreads=0);
1264 bool OIIO_API color_map (ImageBuf &dst, const ImageBuf &src, int srcchannel,
1265  int nknots, int channels, cspan<float> knots,
1266  ROI roi={}, int nthreads=0);
1267 bool OIIO_API color_map (ImageBuf &dst, const ImageBuf &src, int srcchannel,
1268  string_view mapname, ROI roi={}, int nthreads=0);
1269 /// @}
1270 
1271 
1272 /// @defgroup range (Nonlinear range remapping for contrast preservation)
1273 /// @{
1274 ///
1275 /// Nonlinear range remapping for contrast preservation
1276 ///
1277 /// `rangecompress()` returns (or copy into `dst`) all pixels and color
1278 /// channels of `src` within region `roi` (defaulting to all the defined
1279 /// pixels of `dst`), rescaling their range with a logarithmic
1280 /// transformation. Alpha and z channels are not transformed.
1281 ///
1282 /// `rangeexpand()` performs the inverse transformation (logarithmic back
1283 /// into linear).
1284 ///
1285 /// If `useluma` is true, the luma of channels [roi.chbegin..roi.chbegin+2]
1286 /// (presumed to be R, G, and B) are used to compute a single scale factor
1287 /// for all color channels, rather than scaling all channels individually
1288 /// (which could result in a color shift).
1289 ///
1290 /// The purpose of these function is as follows: Some image operations (such
1291 /// as resizing with a "good" filter that contains negative lobes) can have
1292 /// objectionable artifacts when applied to images with very high-contrast
1293 /// regions involving extra bright pixels (such as highlights in HDR
1294 /// captured or rendered images). By compressing the range pixel values,
1295 /// then performing the operation, then expanding the range of the result
1296 /// again, the result can be much more pleasing (even if not exactly
1297 /// correct).
1298 
1299 ImageBuf OIIO_API rangecompress (const ImageBuf &src, bool useluma = false,
1300  ROI roi={}, int nthreads=0);
1301 ImageBuf OIIO_API rangeexpand (const ImageBuf &src, bool useluma = false,
1302  ROI roi={}, int nthreads=0);
1303 bool OIIO_API rangecompress (ImageBuf &dst, const ImageBuf &src,
1304  bool useluma = false, ROI roi={}, int nthreads=0);
1305 bool OIIO_API rangeexpand (ImageBuf &dst, const ImageBuf &src,
1306  bool useluma = false, ROI roi={}, int nthreads=0);
1307 /// @}
1308 
1309 
1311  std::vector<float> min;
1312  std::vector<float> max;
1313  std::vector<float> avg;
1314  std::vector<float> stddev;
1315  std::vector<imagesize_t> nancount;
1316  std::vector<imagesize_t> infcount;
1317  std::vector<imagesize_t> finitecount;
1318  std::vector<double> sum, sum2; // for intermediate calculation
1319 
1321  PixelStats (PixelStats&& other) = default;
1322  PixelStats (int nchannels) { reset(nchannels); }
1323  void reset (int nchannels);
1324  void merge (const PixelStats &p);
1325  const PixelStats& operator= (PixelStats&& other); // Move assignment
1326 };
1327 
1328 
1329 /// Compute statistics about the ROI of the `src` image, returning a
1330 /// PixelStats structure. Upon success, the returned vectors in the result
1331 /// structure will have size == src.nchannels(). If there is a failure, the
1332 /// vector sizes will be 0 and an error will be set in src.
1333 PixelStats OIIO_API computePixelStats (const ImageBuf &src,
1334  ROI roi={}, int nthreads=0);
1335 
1336 // DEPRECATED(1.9): with C++11 move semantics, there's no reason why
1337 // stats needs to be passed as a parameter instead of returned.
1338 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1339 OIIO_DEPRECATED("use version that returns PixelStats (1.9)")
1340 bool OIIO_API computePixelStats (PixelStats &stats, const ImageBuf &src,
1341  ROI roi={}, int nthreads=0);
1342 #endif
1343 
1344 
1345 // Struct holding all the results computed by ImageBufAlgo::compare().
1346 // (maxx,maxy,maxz,maxc) gives the pixel coordinates (x,y,z) and color
1347 // channel of the pixel that differed maximally between the two images.
1348 // nwarn and nfail are the number of "warnings" and "failures",
1349 // respectively.
1352  int maxx, maxy, maxz, maxc;
1354  bool error;
1355 };
1356 
1357 /// Numerically compare two images. The difference threshold (for any
1358 /// individual color channel in any pixel) for a "failure" is `failthresh`,
1359 /// and for a "warning" is `warnthresh`. If nonzero, then `failrelative` and
1360 /// `warnrelative` are alternate thresholds as a portion the mean of the
1361 /// absolute values of the two images. It only warns or fails if both criteria
1362 /// are met. More formally, a value comparison will fail if
1363 ///
1364 /// abs(A-B) > failthresh && abs(A-B)/((abs(A)+abs(B))/2) > failrelative
1365 ///
1366 /// and analogously for warning.
1367 ///
1368 /// The results are stored in `result`. If `roi` is defined, pixels will be
1369 /// compared for the pixel and channel range that is specified. If `roi` is
1370 /// not defined, the comparison will be for all channels, on the union of the
1371 /// defined pixel windows of the two images (for either image, undefined
1372 /// pixels will be assumed to be black).
1373 CompareResults OIIO_API compare (const ImageBuf &A, const ImageBuf &B,
1374  float failthresh, float warnthresh,
1375  float failrelative, float warnrelative,
1376  ROI roi={}, int nthreads=0);
1377 
1378 /// Numerically compare two images. The difference threshold (for any
1379 /// individual color channel in any pixel) for a "failure" is
1380 /// failthresh, and for a "warning" is warnthresh. The results are
1381 /// stored in result. If roi is defined, pixels will be compared for
1382 /// the pixel and channel range that is specified. If roi is not
1383 /// defined, the comparison will be for all channels, on the union of
1384 /// the defined pixel windows of the two images (for either image,
1385 /// undefined pixels will be assumed to be black).
1386 CompareResults OIIO_API compare (const ImageBuf &A, const ImageBuf &B,
1387  float failthresh, float warnthresh,
1388  ROI roi={}, int nthreads=0);
1389 
1390 /// Compare two images using Hector Yee's perceptual metric, returning
1391 /// the number of pixels that fail the comparison. Only the first three
1392 /// channels (or first three channels specified by `roi`) are compared.
1393 /// Free parameters are the ambient luminance in the room and the field
1394 /// of view of the image display; our defaults are probably reasonable
1395 /// guesses for an office environment. The 'result' structure will
1396 /// store the maxerror, and the maxx, maxy, maxz of the pixel that
1397 /// failed most severely. (The other fields of the CompareResults
1398 /// are not used for Yee comparison.)
1399 ///
1400 /// Works for all pixel types. But it's basically meaningless if the
1401 /// first three channels aren't RGB in a linear color space that sort
1402 /// of resembles AdobeRGB.
1403 ///
1404 /// Return true on success, false on error.
1405 int OIIO_API compare_Yee (const ImageBuf &A, const ImageBuf &B,
1406  CompareResults &result,
1407  float luminance = 100, float fov = 45,
1408  ROI roi={}, int nthreads=0);
1409 
1410 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1411 // DEPRECATED(1.9): with C++11 move semantics, there's no reason why
1412 // result needs to be passed as a parameter instead of returned.
1413 OIIO_DEPRECATED("use version that returns CompareResults (1.9)")
1414 bool OIIO_API compare (const ImageBuf &A, const ImageBuf &B,
1415  float failthresh, float warnthresh,
1416  CompareResults &result, ROI roi={}, int nthreads=0);
1417 #endif
1418 
1419 
1420 /// Do all pixels within the ROI have the same values for channels
1421 /// `[roi.chbegin..roi.chend-1]`, within a tolerance of +/- `threshold`? If
1422 /// so, return `true` and store that color in `color[chbegin...chend-1]` (if
1423 /// `color` is not empty); otherwise return `false`. If `roi` is not
1424 /// defined (the default), it will be understood to be all of the defined
1425 /// pixels and channels of source.
1426 OIIO_API bool isConstantColor (const ImageBuf &src, float threshold=0.0f,
1427  span<float> color = {},
1428  ROI roi={}, int nthreads=0);
1429 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1430 inline bool isConstantColor (const ImageBuf &src, span<float> color,
1431  ROI roi={}, int nthreads=0) {
1432  return isConstantColor (src, 0.0f, color, roi, nthreads);
1433 }
1434 #endif
1435 
1436 
1437 /// Does the requested channel have a given value (within a tolerance of +/-
1438 /// `threshold`) for every channel within the ROI? (For this function, the
1439 /// ROI's chbegin/chend are ignored.) Return `true` if so, otherwise return
1440 /// `false`. If `roi` is not defined (the default), it will be understood
1441 /// to be all of the defined pixels and channels of source.
1442 OIIO_API bool isConstantChannel (const ImageBuf &src, int channel,
1443  float val, float threshold=0.0f,
1444  ROI roi={}, int nthreads=0);
1445 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1446 inline bool isConstantChannel (const ImageBuf &src, int channel, float val,
1447  ROI roi, int nthreads=0) {
1448  return isConstantChannel (src, channel, val, 0.0f, roi, nthreads);
1449 }
1450 #endif
1451 
1452 
1453 /// Is the image monochrome within the ROI, i.e., for every pixel within the
1454 /// region, do all channels [roi.chbegin, roi.chend) have the same value
1455 /// (within a tolerance of +/- threshold)? If roi is not defined (the
1456 /// default), it will be understood to be all of the defined pixels and
1457 /// channels of source.
1458 OIIO_API bool isMonochrome (const ImageBuf &src, float threshold=0.0f,
1459  ROI roi={}, int nthreads=0);
1460 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1461 inline bool isMonochrome (const ImageBuf &src, ROI roi, int nthreads=0) {
1462  return isMonochrome (src, 0.0f, roi, nthreads);
1463 }
1464 #endif
1465 
1466 
1467 /// Count how many pixels in the ROI match a list of colors. The colors to
1468 /// match are in:
1469 ///
1470 /// colors[0 ... nchans-1]
1471 /// colors[nchans ... 2*nchans-1]
1472 /// ...
1473 /// colors[(ncolors-1)*nchans ... (ncolors*nchans)-1]
1474 ///
1475 /// and so on, a total of `ncolors` consecutively stored colors of `nchans`
1476 /// channels each (`nchans` is the number of channels in the image, itself,
1477 /// it is not passed as a parameter).
1478 ///
1479 /// `eps[0..nchans-1]` are the error tolerances for a match, for each
1480 /// channel. Setting `eps[c]` = `numeric_limits<float>::max()` will
1481 /// effectively make it ignore the channel. The default `eps` is 0.001 for
1482 /// all channels (this value is chosen because it requires exact matches for
1483 /// 8 bit images, but allows a wee bit of imprecision for float images.
1484 ///
1485 /// Upon success, return `true` and store the number of pixels that matched
1486 /// each color `count[0..ncolors-1]`. If there is an error, returns `false`
1487 /// and sets an appropriate error message set in `src`.
1488 bool OIIO_API color_count (const ImageBuf &src, imagesize_t *count,
1489  int ncolors, cspan<float> color,
1490  cspan<float> eps = 0.001f,
1491  ROI roi={}, int nthreads=0);
1492 
1493 
1494 /// Count how many pixels in the image (within the ROI) are outside the
1495 /// value range described by `low[roi.chbegin..roi.chend-1]` and
1496 /// `high[roi.chbegin..roi.chend-1]` as the low and high acceptable values
1497 /// for each color channel.
1498 ///
1499 /// The number of pixels containing values that fall below the lower bound
1500 /// will be stored in `*lowcount`, the number of pixels containing
1501 /// values that fall above the upper bound will be stored in
1502 /// `*highcount`, and the number of pixels for which all channels fell
1503 /// within the bounds will be stored in `*inrangecount`. Any of these
1504 /// may be NULL, which simply means that the counts need not be collected or
1505 /// stored.
1506 bool OIIO_API color_range_check (const ImageBuf &src,
1507  imagesize_t *lowcount,
1508  imagesize_t *highcount,
1509  imagesize_t *inrangecount,
1510  cspan<float> low, cspan<float> high,
1511  ROI roi={}, int nthreads=0);
1512 
1513 /// Find the minimal rectangular region within `roi` (which defaults to the
1514 /// entire pixel data window of `src`) that consists of nonzero pixel
1515 /// values. In other words, gives the region that is a "shrink-wraps" of
1516 /// `src` to exclude black border pixels. Note that if the entire image was
1517 /// black, the ROI returned will contain no pixels.
1518 ///
1519 /// For "deep" images, this function returns the smallest ROI that contains
1520 /// all pixels that contain depth samples, and excludes the border pixels
1521 /// that contain no depth samples at all.
1522 OIIO_API ROI nonzero_region (const ImageBuf &src, ROI roi={}, int nthreads=0);
1523 
1524 
1525 /// Compute the SHA-1 byte hash for all the pixels in the specified region of
1526 /// the image. If `blocksize` > 0, the function will compute separate SHA-1
1527 /// hashes of each `blocksize` batch of scanlines, then return a hash of the
1528 /// individual hashes. This is just as strong a hash, but will NOT match a
1529 /// single hash of the entire image (`blocksize==0`). But by breaking up
1530 /// the hash into independent blocks, we can parallelize across multiple
1531 /// threads, given by `nthreads` (if `nthreads` is 0, it will use the global
1532 /// OIIO thread count). The `extrainfo` provides additional text that will
1533 /// be incorporated into the hash.
1534 std::string OIIO_API computePixelHashSHA1 (const ImageBuf &src,
1535  string_view extrainfo = "",
1536  ROI roi={},
1537  int blocksize = 0, int nthreads=0);
1538 
1539 
1540 /// Compute a histogram of `src`, for the given channel and ROI. Return a
1541 /// vector of length `bins` that contains the counts of how many pixel
1542 /// values were in each of `bins` equally spaced bins covering the range of
1543 /// values `[min,max]`. Values < `min` count for bin 0, values > `max` count
1544 /// for bin `nbins-1`. If `ignore_empty` is `true`, no counts will be
1545 /// incremented for any pixels whose value is 0 in all channels.
1546 ///
1547 /// If there was an error, the returned vector will be empty, and an error
1548 /// message will be retrievable from src.geterror().
1549 OIIO_API
1550 std::vector<imagesize_t> histogram (const ImageBuf &src, int channel=0,
1551  int bins=256, float min=0.0f, float max=1.0f,
1552  bool ignore_empty=false,
1553  ROI roi={}, int nthreads=0);
1554 
1555 
1556 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1557 /// DEPRECATED(1.9)
1558 OIIO_DEPRECATED("use version that returns vector (1.9)")
1559 bool OIIO_API histogram (const ImageBuf &src, int channel,
1560  std::vector<imagesize_t> &histogram, int bins=256,
1561  float min=0, float max=1, imagesize_t *submin=nullptr,
1562  imagesize_t *supermax=nullptr, ROI roi={});
1563 
1564 // DEPRECATED(1.9): never liked this.
1565 OIIO_DEPRECATED("this useless function is going away (1.9)")
1567  const std::vector<imagesize_t> &histogram);
1568 #endif
1569 
1570 
1571 
1572 /// Make a 1-channel `float` image of the named kernel. The size of the
1573 /// image will be big enough to contain the kernel given its size (`width` x
1574 /// `height`) and rounded up to odd resolution so that the center of the
1575 /// kernel can be at the center of the middle pixel. The kernel image will
1576 /// be offset so that its center is at the (0,0) coordinate. If `normalize`
1577 /// is true, the values will be normalized so that they sum to 1.0. If
1578 /// `depth` > 1, a volumetric kernel will be created. Use with caution!
1579 ///
1580 /// Kernel names can be: "gaussian", "sharp-gaussian", "box",
1581 /// "triangle", "blackman-harris", "mitchell", "b-spline", "catmull-rom",
1582 /// "lanczos3", "disk", "binomial", "laplacian".
1583 ///
1584 /// Note that "catmull-rom" and "lanczos3" are fixed-size kernels that
1585 /// don't scale with the width, and are therefore probably less useful
1586 /// in most cases.
1587 ///
1588 /// The ImageBuf that is returned indicates if there was an error, in which
1589 /// case return.has_error() will be true and return.geterror() can be used
1590 /// to retrieve an error message.
1591 ImageBuf OIIO_API make_kernel (string_view name, float width, float height,
1592  float depth = 1.0f, bool normalize = true);
1593 #ifndef DOXYGEN_SHOULD_SKIP_THIS
1594 // DEPRECATED(1.9):
1595 OIIO_DEPRECATED("use version that returns ImageBuf (1.9)")
1597  float width, float height, float depth = 1.0f,
1598  bool normalize = true) {
1599  dst = make_kernel (name, width, height, depth, normalize);
1600  return ! dst.has_error();
1601 }
1602 #endif
1603 
1604 
1605 /// Return the convolution of `src` and a `kernel`. If `roi` is not defined,
1606 /// it defaults to the full size `src`. If `normalized` is true, the kernel will
1607 /// be normalized for the convolution, otherwise the original values will
1608 /// be used.
1609 ImageBuf OIIO_API convolve (const ImageBuf &src, const ImageBuf &kernel,
1610  bool normalize = true, ROI roi={}, int nthreads=0);
1611 /// Write to an existing image `dst` (allocating if it is uninitialized).
1612 /// If `roi` is not defined, it defaults to the full size of `dst` (or
1613 /// `src`, if `dst` was uninitialized). If `dst` is uninitialized, it will
1614 /// be allocated to be the size specified by `roi`.
1615 bool OIIO_API convolve (ImageBuf &dst, const ImageBuf &src, const ImageBuf &kernel,
1616  bool normalize = true, ROI roi={}, int nthreads=0);
1617 
1618 
1619 /// Return the Laplacian of the corresponding region of `src`. The
1620 /// Laplacian is the generalized second derivative of the image
1621 /// \f[
1622 /// \frac{\partial^2 s}{\partial x^2} + \frac{\partial^2 s}{\partial y^2}
1623 /// \f]
1624 /// which is approximated by convolving the image with a discrete 3x3
1625 /// Laplacian kernel,
1626 ///
1627 /// [ 0 1 0 ]
1628 /// [ 1 -4 1 ]
1629 /// [ 0 1 0 ]
1630 ///
1631 ImageBuf OIIO_API laplacian (const ImageBuf &src, ROI roi={}, int nthreads=0);
1632 /// Write to an existing image `dst` (allocating if it is uninitialized).
1633 bool OIIO_API laplacian (ImageBuf &dst, const ImageBuf &src,
1634  ROI roi={}, int nthreads=0);
1635 
1636 
1637 /// @defgroup fft-ifft (Fast Fourier Transform and inverse)
1638 /// @{
1639 ///
1640 /// Fast Fourier Transform and inverse
1641 ///
1642 /// Return (or copy into `dst`) the discrete Fourier transform (DFT), or its
1643 /// inverse, of the section of `src` denoted by roi, If roi is not defined,
1644 /// it will be all of `src`'s pixels.
1645 ///
1646 /// `fft()` takes the discrete Fourier transform (DFT) of the section of
1647 /// `src` denoted by `roi`, returning it or storing it in `dst`. If `roi` is
1648 /// not defined, it will be all of `src`'s pixels. Only one channel of `src`
1649 /// may be transformed at a time, so it will be the first channel described
1650 /// by `roi` (or, again, channel 0 if `roi` is undefined). If not already
1651 /// in the correct format, `dst` will be re-allocated to be a 2-channel
1652 /// `float` buffer of size `roi.width()` x `roi.height`, with channel 0
1653 /// being the "real" part and channel 1 being the the "imaginary" part. The
1654 /// values returned are actually the unitary DFT, meaning that it is scaled
1655 /// by 1/sqrt(npixels).
1656 ///
1657 /// `ifft()` takes the inverse discrete Fourier transform, transforming a
1658 /// 2-channel complex (real and imaginary) frequency domain image and into a
1659 /// single-channel spatial domain image. `src` must be a 2-channel float
1660 /// image, and is assumed to be a complex frequency-domain signal with the
1661 /// "real" component in channel 0 and the "imaginary" component in channel 1.
1662 /// `dst` will end up being a float image of one channel (the real component
1663 /// is kept, the imaginary component of the spatial-domain will be
1664 /// discarded). Just as with `fft()`, the `ifft()` function is dealing with
1665 /// the unitary DFT, so it is scaled by 1/sqrt(npixels).
1666 ImageBuf OIIO_API fft (const ImageBuf &src, ROI roi={}, int nthreads=0);
1667 ImageBuf OIIO_API ifft (const ImageBuf &src, ROI roi={}, int nthreads=0);
1668 bool OIIO_API fft (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
1669 bool OIIO_API ifft (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
1670 /// @}
1671 
1672 
1673 /// @defgroup complex-polar (Converting complex to polar and back)
1674 /// @{
1675 ///
1676 /// Converting complex to polar and back
1677 ///
1678 /// The `polar_to_complex()` function transforms a 2-channel image whose
1679 /// channels are interpreted as complex values (real and imaginary
1680 /// components) into the equivalent values expressed in polar form of
1681 /// amplitude and phase (with phase between 0 and \f$ 2\pi \f$.
1682 ///
1683 /// The `complex_to_polar()` function performs the reverse transformation,
1684 /// converting from polar values (amplitude and phase) to complex (real and
1685 /// imaginary).
1686 ///
1687 /// In either case, the section of `src` denoted by `roi` is transformed,
1688 /// storing the result in `dst`. If `roi` is not defined, it will be all of
1689 /// `src`'s pixels. Only the first two channels of `src` will be
1690 /// transformed.
1691 ///
1692 /// The transformation between the two representations are:
1693 ///
1694 /// real = amplitude * cos(phase);
1695 /// imag = amplitude * sin(phase);
1696 ///
1697 /// amplitude = hypot (real, imag);
1698 /// phase = atan2 (imag, real);
1699 
1701  ROI roi={}, int nthreads=0);
1702 bool OIIO_API complex_to_polar (ImageBuf &dst, const ImageBuf &src,
1703  ROI roi={}, int nthreads=0);
1705  ROI roi={}, int nthreads=0);
1706 bool OIIO_API polar_to_complex (ImageBuf &dst, const ImageBuf &src,
1707  ROI roi={}, int nthreads=0);
1708 /// @}
1709 
1710 
1711 
1713 {
1714  NONFINITE_NONE = 0, ///< Do not alter the pixels (but do count the
1715  ///< number of nonfinite pixels in *pixelsFixed,
1716  ///< if non-null).
1717  NONFINITE_BLACK = 1, ///< Replace non-finite values with 0.0.
1718  NONFINITE_BOX3 = 2, ///< Replace non-finite values with the average
1719  ///< value of any finite pixels in a 3x3 window.
1720  NONFINITE_ERROR = 100, ///< Return false (error), but don't change any
1721  ///< values, if any nonfinite values are found.
1722 };
1723 
1724 /// `fixNonFinite()` returns in image containing the values of `src` (within
1725 /// the ROI), while repairing any non-finite (NaN/Inf) pixels. If
1726 /// `pixelsFixed` is not nullptr, store in it the number of pixels that
1727 /// contained non-finite value. It is permissible to operate in-place (with
1728 /// `src` and `dst` referring to the same image).
1729 ///
1730 /// How the non-finite values are repaired is specified by one of the `mode`
1731 /// parameter, which is an enum of `NonFiniteFixMode`.
1732 ///
1733 /// This function works on all pixel data types, though it's just a copy for
1734 /// images with pixel data types that cannot represent NaN or Inf values.
1737  int *pixelsFixed = nullptr,
1738  ROI roi={}, int nthreads=0);
1739 
1740 /// Write to an existing image `dst` (allocating if it is uninitialized).
1741 bool OIIO_API fixNonFinite (ImageBuf &dst, const ImageBuf &src,
1743  int *pixelsFixed = nullptr,
1744  ROI roi={}, int nthreads=0);
1745 
1746 
1747 /// Copy the specified ROI of `src` and fill any holes (pixels where alpha <
1748 /// 1) with plausible values using a push-pull technique. The `src` image
1749 /// must have an alpha channel. The `dst` image will end up with a copy of
1750 /// `src`, but will have an alpha of 1.0 everywhere within `roi`, and any
1751 /// place where the alpha of `src` was < 1, `dst` will have a pixel color
1752 /// that is a plausible "filling" of the original alpha hole.
1754  ROI roi={}, int nthreads=0);
1755 /// Write to an existing image `dst` (allocating if it is uninitialized).
1756 bool OIIO_API fillholes_pushpull (ImageBuf &dst, const ImageBuf &src,
1757  ROI roi={}, int nthreads=0);
1758 
1759 
1760 /// Return a median-filtered version of the corresponding region of `src`.
1761 /// The median filter replaces each pixel with the median value underneath
1762 /// the `width` x `height` window surrounding it. If `height` <= 0, it will
1763 /// be set to `width`, making a square window.
1764 ///
1765 /// Median filters are good for removing high-frequency detail smaller than
1766 /// the window size (including noise), without blurring edges that are
1767 /// larger than the window size.
1769  int width = 3, int height = -1,
1770  ROI roi={}, int nthreads=0);
1771 /// Write to an existing image `dst` (allocating if it is uninitialized).
1772 bool OIIO_API median_filter (ImageBuf &dst, const ImageBuf &src,
1773  int width = 3, int height = -1,
1774  ROI roi={}, int nthreads=0);
1775 
1776 
1777 /// Return a sharpened version of the corresponding region of `src` using
1778 /// the "unsharp mask" technique. Unsharp masking basically works by first
1779 /// blurring the image (low pass filter), subtracting this from the original
1780 /// image, then adding the residual back to the original to emphasize the
1781 /// edges. Roughly speaking,
1782 ///
1783 /// dst = src + contrast * thresh(src - blur(src))
1784 ///
1785 /// The specific blur can be selected by kernel name and width (for example,
1786 /// "gaussian" is typical). As a special case, "median" is also accepted as
1787 /// the kernel name, in which case a median filter is performed rather than
1788 /// a blurring convolution (Gaussian and other blurs sometimes over-sharpen
1789 /// edges, whereas using the median filter will sharpen compact
1790 /// high-frequency details while not over-sharpening long edges).
1791 ///
1792 /// The `contrast` is a multiplier on the overall sharpening effect. The
1793 /// thresholding step causes all differences less than `threshold` to be
1794 /// squashed to zero, which can be useful for suppressing sharpening of
1795 /// low-contrast details (like noise) but allow sharpening of
1796 /// higher-contrast edges.
1798  string_view kernel="gaussian", float width = 3.0f,
1799  float contrast = 1.0f, float threshold = 0.0f,
1800  ROI roi={}, int nthreads=0);
1801 /// Write to an existing image `dst` (allocating if it is uninitialized).
1802 bool OIIO_API unsharp_mask (ImageBuf &dst, const ImageBuf &src,
1803  string_view kernel="gaussian", float width = 3.0f,
1804  float contrast = 1.0f, float threshold = 0.0f,
1805  ROI roi={}, int nthreads=0);
1806 
1807 
1808 /// Return a dilated version of the corresponding region of `src`. Dilation
1809 /// is defined as the maximum value of all pixels under nonzero values of
1810 /// the structuring element (which is taken to be a width x height square).
1811 /// If height is not set, it will default to be the same as width. Dilation
1812 /// makes bright features wider and more prominent, dark features thinner,
1813 /// and removes small isolated dark spots.
1814 ImageBuf OIIO_API dilate (const ImageBuf &src, int width=3, int height=-1,
1815  ROI roi={}, int nthreads=0);
1816 /// Write to an existing image `dst` (allocating if it is uninitialized).
1817 bool OIIO_API dilate (ImageBuf &dst, const ImageBuf &src,
1818  int width=3, int height=-1, ROI roi={}, int nthreads=0);
1819 
1820 
1821 /// Return an eroded version of the corresponding region of `src`. Erosion
1822 /// is defined as the minimum value of all pixels under nonzero values of
1823 /// the structuring element (which is taken to be a width x height square).
1824 /// If height is not set, it will default to be the same as width. Erosion
1825 /// makes dark features wider, bright features thinner, and removes small
1826 /// isolated bright spots.
1827 ImageBuf OIIO_API erode (const ImageBuf &src, int width=3, int height=-1,
1828  ROI roi={}, int nthreads=0);
1829 /// Write to an existing image `dst` (allocating if it is uninitialized).
1830 bool OIIO_API erode (ImageBuf &dst, const ImageBuf &src,
1831  int width=3, int height=-1, ROI roi={}, int nthreads=0);
1832 
1833 
1834 
1835 /// @defgroup colorconvert (Color space conversions)
1836 /// @{
1837 ///
1838 /// Convert between color spaces
1839 ///
1840 /// Return (or copy into `dst`) the pixels of `src` within the ROI, applying
1841 /// a color space transformation. In-place operations (`dst` == `src`) are
1842 /// supported.
1843 ///
1844 /// The first three channels are presumed to be the color to be
1845 /// transformed, and the fourth channel (if it exists) is presumed to be
1846 /// alpha. Any additional channels will be simply copied unaltered.
1847 ///
1848 /// If OIIO was built with OpenColorIO support enabled, then the
1849 /// transformation may be between any two spaces supported by the active
1850 /// OCIO configuration, or may be a "look" transformation created by
1851 /// `ColorConfig::createLookTransform`. If OIIO was not built with
1852 /// OpenColorIO support enabled, then the only transformations available are
1853 /// from "sRGB" to "linear" and vice versa.
1854 ///
1855 /// @param fromspace/tospace
1856 /// For the varieties of `colorconvert()` that use named color
1857 /// spaces, these specify the color spaces by name.
1858 /// @param context_key/context_value
1859 /// For the varieties of `colorconvert()` that use named color
1860 /// spaces, these optionally specify a "key" name/value pair to
1861 /// establish a context (for example, a shot-specific transform).
1862 /// @param processor
1863 /// For the varieties of `colorconvert()` that have a
1864 /// `processor` parameter, it is a raw `ColorProcessor*` object
1865 /// that implements the color transformation. This is a special
1866 /// object created by a `ColorConfig` (see `OpenImageIO/color.h`
1867 /// for details).
1868 /// @param unpremult
1869 /// If true, unpremultiply the image (divide the RGB channels by
1870 /// alpha if it exists and is nonzero) before color conversion,
1871 /// then repremult after the after the color conversion. Passing
1872 /// unpremult=false skips this step, which may be desirable if
1873 /// you know that the image is "unassociated alpha" (a.k.a.,
1874 /// "not pre-multiplied colors").
1875 /// @param colorconfig
1876 /// An optional `ColorConfig*` specifying an OpenColorIO
1877 /// configuration. If not supplied, the default OpenColorIO
1878 /// color configuration found by examining the `$OCIO`
1879 /// environment variable will be used instead.
1880 ///
1881 
1882 /// Transform between named color spaces, returning an ImageBuf result.
1884  string_view fromspace, string_view tospace, bool unpremult=true,
1885  string_view context_key="", string_view context_value="",
1886  const ColorConfig* colorconfig = nullptr,
1887  ROI roi={}, int nthreads=0);
1888 
1889 /// Transform using a ColorProcessor, returning an ImageBuf result.
1891  const ColorProcessor *processor,
1892  bool unpremult, ROI roi={}, int nthreads=0);
1893 /// Transform between named color spaces, storing reults into an existing ImageBuf.
1894 bool OIIO_API colorconvert (ImageBuf &dst, const ImageBuf &src,
1895  string_view fromspace, string_view tospace, bool unpremult=true,
1896  string_view context_key="", string_view context_value="",
1897  const ColorConfig* colorconfig = nullptr,
1898  ROI roi={}, int nthreads=0);
1899 
1900 /// Transform using a ColorProcessor, storing reults into an existing ImageBuf.
1901 bool OIIO_API colorconvert (ImageBuf &dst, const ImageBuf &src,
1902  const ColorProcessor *processor,
1903  bool unpremult, ROI roi={}, int nthreads=0);
1904 
1905 /// Apply a color transform in-place to just one color:
1906 /// `color[0..nchannels-1]`. `nchannels` should either be 3 or 4 (if 4, the
1907 /// last channel is alpha).
1908 bool OIIO_API colorconvert (span<float> color,
1909  const ColorProcessor *processor, bool unpremult);
1910 
1911 // DEPRECATED(2.1): Less safe version with raw pointer and length.
1912 inline bool colorconvert (float *color, int nchannels,
1913  const ColorProcessor *processor, bool unpremult) {
1914  return colorconvert ({color,nchannels}, processor, unpremult);
1915 }
1916 
1917 /// @}
1918 
1919 
1920 /// Return a copy of the pixels of `src` within the ROI, applying a color
1921 /// transform specified by a 4x4 matrix. In-place operations
1922 /// (`dst` == `src`) are supported.
1923 ///
1924 /// The first three channels are presumed to be the color to be
1925 /// transformed, and the fourth channel (if it exists) is presumed to be
1926 /// alpha. Any additional channels will be simply copied unaltered.
1927 ///
1928 /// @param M
1929 /// A 4x4 matrix. Following Imath conventions, the color is a
1930 /// row vector and the matrix has the "translation" part in
1931 /// elements [12..14] (matching the memory layout of OpenGL or
1932 /// RenderMan), so the math is `color * Matrix` (NOT `M*c`).
1933 /// @param unpremult
1934 /// If true, unpremultiply the image (divide the RGB channels by
1935 /// alpha if it exists and is nonzero) before color conversion,
1936 /// then repremult after the after the color conversion. Passing
1937 /// unpremult=false skips this step, which may be desirable if
1938 /// you know that the image is "unassociated alpha" (a.k.a.,
1939 /// "not pre-multiplied colors").
1940 ///
1941 /// @version 2.1+
1942 ///
1944  M44fParam M, bool unpremult=true,
1945  ROI roi={}, int nthreads=0);
1946 /// Write to an existing image `dst` (allocating if it is uninitialized).
1947 bool OIIO_API colormatrixtransform (ImageBuf &dst, const ImageBuf &src,
1948  M44fParam M, bool unpremult=true,
1949  ROI roi={}, int nthreads=0);
1950 
1951 
1952 /// Return a copy of the pixels of `src` within the ROI, applying an
1953 /// OpenColorIO "look" transform to the pixel values. In-place operations
1954 /// (`dst` == `src`) are supported.
1955 ///
1956 /// The first three channels are presumed to be the color to be
1957 /// transformed, and the fourth channel (if it exists) is presumed to be
1958 /// alpha. Any additional channels will be simply copied unaltered.
1959 ///
1960 /// @param looks
1961 /// The looks to apply (comma-separated).
1962 /// @param fromspace/tospace
1963 /// For the varieties of `colorconvert()` that use named color
1964 /// spaces, these specify the color spaces by name.
1965 /// @param unpremult
1966 /// If true, unpremultiply the image (divide the RGB channels by
1967 /// alpha if it exists and is nonzero) before color conversion,
1968 /// then repremult after the after the color conversion. Passing
1969 /// unpremult=false skips this step, which may be desirable if
1970 /// you know that the image is "unassociated alpha" (a.k.a.,
1971 /// "not pre-multiplied colors").
1972 /// @param inverse
1973 /// If `true`, it will reverse the color transformation and look
1974 /// application.
1975 /// @param context_key/context_value
1976 /// Optional key/value to establish a context (for example, a
1977 /// shot-specific transform).
1978 /// @param colorconfig
1979 /// An optional `ColorConfig*` specifying an OpenColorIO
1980 /// configuration. If not supplied, the default OpenColorIO
1981 /// color configuration found by examining the `$OCIO`
1982 /// environment variable will be used instead.
1983 ImageBuf OIIO_API ociolook (const ImageBuf &src, string_view looks,
1984  string_view fromspace, string_view tospace,
1985  bool unpremult=true, bool inverse=false,
1986  string_view context_key="", string_view context_value="",
1987  const ColorConfig* colorconfig = nullptr,
1988  ROI roi={}, int nthreads=0);
1989 /// Write to an existing image `dst` (allocating if it is uninitialized).
1990 bool OIIO_API ociolook (ImageBuf &dst, const ImageBuf &src, string_view looks,
1991  string_view fromspace, string_view tospace,
1992  bool unpremult=true, bool inverse=false,
1993  string_view context_key="", string_view context_value="",
1994  const ColorConfig* colorconfig = nullptr,
1995  ROI roi={}, int nthreads=0);
1996 
1997 
1998 /// Return the pixels of `src` within the ROI, applying an OpenColorIO
1999 /// "display" transform to the pixel values. In-place operations
2000 /// (`dst` == `src`) are supported.
2001 ///
2002 /// The first three channels are presumed to be the color to be
2003 /// transformed, and the fourth channel (if it exists) is presumed to be
2004 /// alpha. Any additional channels will be simply copied unaltered.
2005 ///
2006 /// @param display
2007 /// The OCIO "display" to apply. If this is `"default"` or the
2008 /// empty string `""`, the default display will be used.
2009 /// @param view
2010 /// The OCIO "view" to use. If this is `"default"` or the empty
2011 /// string `""`, the default view for this display will be used.
2012 /// @param fromspace
2013 /// If `fromspace` is not supplied, it will assume that the
2014 /// source color space is whatever is indicated by the source
2015 /// image's metadata or filename, and if that cannot be deduced,
2016 /// it will be assumed to be scene linear.
2017 /// @param looks
2018 /// The looks to apply (comma-separated). This may be empty,
2019 /// in which case no "look" is used. Note: this parameter value
2020 /// is not used when building against OpenColorIO 2.x.
2021 /// @param unpremult
2022 /// If true, unpremultiply the image (divide the RGB channels by
2023 /// alpha if it exists and is nonzero) before color conversion,
2024 /// then repremult after the after the color conversion. Passing
2025 /// unpremult=false skips this step, which may be desirable if
2026 /// you know that the image is "unassociated alpha" (a.k.a.,
2027 /// "not pre-multiplied colors").
2028 /// @param inverse
2029 /// If `true`, it will reverse the color transformation and
2030 /// display application.
2031 /// @param context_key/context_value
2032 /// Optional key/value to establish a context (for example, a
2033 /// shot-specific transform).
2034 /// @param colorconfig
2035 /// An optional `ColorConfig*` specifying an OpenColorIO
2036 /// configuration. If not supplied, the default OpenColorIO
2037 /// color configuration found by examining the `$OCIO`
2038 /// environment variable will be used instead.
2040  string_view display, string_view view,
2041  string_view fromspace="", string_view looks="",
2042  bool unpremult=true, bool inverse=false,
2043  string_view context_key="", string_view context_value="",
2044  const ColorConfig* colorconfig = nullptr,
2045  ROI roi={}, int nthreads=0);
2046 /// Write to an existing image `dst` (allocating if it is uninitialized).
2047 bool OIIO_API ociodisplay (ImageBuf &dst, const ImageBuf &src,
2048  string_view display, string_view view,
2049  string_view fromspace="", string_view looks="",
2050  bool unpremult=true, bool inverse=false,
2051  string_view context_key="", string_view context_value="",
2052  const ColorConfig* colorconfig = nullptr,
2053  ROI roi={}, int nthreads=0);
2054 
2055 #ifndef OIIO_DOXYGEN
2056 // OIIO_DEPRECATED("prefer the kind that takes an `inverse` parameter (2.5)")
2058  string_view display, string_view view,
2059  string_view fromspace, string_view looks,
2060  bool unpremult,
2061  string_view context_key, string_view context_value="",
2062  const ColorConfig* colorconfig = nullptr,
2063  ROI roi={}, int nthreads=0);
2064 // OIIO_DEPRECATED("prefer the kind that takes an `inverse` parameter (2.5)")
2065 bool OIIO_API ociodisplay (ImageBuf &dst, const ImageBuf &src,
2066  string_view display, string_view view,
2067  string_view fromspace, string_view looks,
2068  bool unpremult,
2069  string_view context_key, string_view context_value="",
2070  const ColorConfig* colorconfig = nullptr,
2071  ROI roi={}, int nthreads=0);
2072 #endif
2073 
2074 
2075 /// Return the pixels of `src` within the ROI, applying an OpenColorIO
2076 /// "file" transform. In-place operations (`dst` == `src`) are supported.
2077 ///
2078 /// The first three channels are presumed to be the color to be
2079 /// transformed, and the fourth channel (if it exists) is presumed to be
2080 /// alpha. Any additional channels will be simply copied unaltered.
2081 ///
2082 /// @param name
2083 /// The name of the file containing the transform information.
2084 /// @param unpremult
2085 /// If true, unpremultiply the image (divide the RGB channels by
2086 /// alpha if it exists and is nonzero) before color conversion,
2087 /// then repremult after the after the color conversion. Passing
2088 /// unpremult=false skips this step, which may be desirable if
2089 /// you know that the image is "unassociated alpha" (a.k.a.,
2090 /// "not pre-multiplied colors").
2091 /// @param inverse
2092 /// If `true`, it will reverse the color transformation.
2093 /// @param colorconfig
2094 /// An optional `ColorConfig*` specifying an OpenColorIO
2095 /// configuration. If not supplied, the default OpenColorIO
2096 /// color configuration found by examining the `$OCIO`
2097 /// environment variable will be used instead.
2099  string_view name,
2100  bool unpremult=true, bool inverse=false,
2101  const ColorConfig* colorconfig = nullptr,
2102  ROI roi={}, int nthreads=0);
2103 /// Write to an existing image `dst` (allocating if it is uninitialized).
2104 bool OIIO_API ociofiletransform (ImageBuf &dst, const ImageBuf &src,
2105  string_view name,
2106  bool unpremult=true, bool inverse=false,
2107  const ColorConfig* colorconfig = nullptr,
2108  ROI roi={}, int nthreads=0);
2109 
2110 
2111 /// @defgroup premult (Premultiply or un-premultiply color by alpha)
2112 /// @{
2113 ///
2114 /// Premultiply or un-premultiply color by alpha
2115 ///
2116 /// The `unpremult` operation returns (or copies into `dst`) the pixels of
2117 /// `src` within the ROI, and in the process divides all color channels
2118 /// (those not alpha or z) by the alpha value, to "un-premultiply" them.
2119 /// This presumes that the image starts of as "associated alpha" a.k.a.
2120 /// "premultipled," and you are converting to "unassociated alpha." For
2121 /// pixels with alpha == 0, the color values are not modified.
2122 ///
2123 /// The `premult` operation returns (or copies into `dst`) the pixels of
2124 /// `src` within the ROI, and in the process multiplies all color channels
2125 /// (those not alpha or z) by the alpha value, to "premultiply" them. This
2126 /// presumes that the image starts of as "unassociated alpha" a.k.a.
2127 /// "non-premultipled" and converts it to "associated alpha / premultipled."
2128 ///
2129 /// The `repremult` operation is like `premult`, but preserves the color
2130 /// values of pixels whose alpha is 0. This is intended for cases where you
2131 /// unpremult, do an operation (such as color transforms), then want to
2132 /// return to associated/premultiplied alpha -- in that case, you want to
2133 /// make sure that "glow" pixels (those with alpha=0 but RGB > 0) are
2134 /// preserved for the round trip, and not crushed to black. This use case is
2135 /// distinct from a simple `premult` that is a one-time conversion from
2136 /// unassociated to associated alpha.
2137 ///
2138 /// All three operations are simply a copy if there is no identified alpha
2139 /// channel (and a no-op if `dst` and `src` are the same image).
2140 
2141 ImageBuf OIIO_API unpremult (const ImageBuf &src, ROI roi={}, int nthreads=0);
2142 bool OIIO_API unpremult (ImageBuf &dst, const ImageBuf &src,
2143  ROI roi={}, int nthreads=0);
2144 ImageBuf OIIO_API premult (const ImageBuf &src, ROI roi={}, int nthreads=0);
2145 bool OIIO_API premult (ImageBuf &dst, const ImageBuf &src,
2146  ROI roi={}, int nthreads=0);
2147 ImageBuf OIIO_API repremult (const ImageBuf &src, ROI roi={}, int nthreads=0);
2148 bool OIIO_API repremult (ImageBuf &dst, const ImageBuf &src,
2149  ROI roi={}, int nthreads=0);
2150 /// @}
2151 
2152 
2153 
2159 };
2160 
2161 /// @defgroup make_texture (make_texture -- Turn an image into a texture)
2162 /// @{
2163 ///
2164 /// The `make_texture()` function turns an image into a tiled, MIP-mapped,
2165 /// texture file and write it to disk (outputfilename).
2166 ///
2167 /// The return value is `true` for success, `false` if an error occurred. If
2168 /// there was an error, any error message will be retrievable via the global
2169 /// `OIIO::geterror()` call (since there is no destination `ImageBuf` in
2170 /// which to store it).
2171 ///
2172 /// Named fields in config:
2173 ///
2174 /// - format : Data format of the texture file (default: UNKNOWN = same
2175 /// format as the input)
2176 /// - tile_width/tile_height/tile_depth :
2177 /// Preferred tile size (default: 64x64x1)
2178 ///
2179 /// Metadata in `config.extra_attribs`
2180 ///
2181 /// - `compression` (string) : Default: "zip"
2182 /// - `fovcot` (float) : Default: aspect ratio of the image
2183 /// resolution.
2184 /// - `planarconfig` (string) : Default: "separate"
2185 /// - `worldtocamera` (matrix) : World-to-camera matrix of the view.
2186 /// - `worldtoscreen` (matrix) : World-to-screen space matrix of the view.
2187 /// - `worldtoNDC` (matrix) : World-to-NDC space matrix of the view.
2188 /// - `wrapmodes` (string) : Default: "black,black"
2189 /// - `handed` (string) : "left" or "right" reveals the handedness of
2190 /// the coordinates for normal maps. ("")
2191 /// - `maketx:verbose` (int) : How much detail should go to outstream (0).
2192 /// - `maketx:runstats` (int) : If nonzero, print run stats to outstream (0).
2193 /// - `maketx:resize` (int) : If nonzero, resize to power of 2. (0)
2194 /// - `maketx:nomipmap` (int) : If nonzero, only output the top MIP level (0).
2195 /// - `maketx:updatemode` (int) : If nonzero, write new output only if the
2196 /// output file doesn't already exist, or is
2197 /// older than the input file, or was created
2198 /// with different command-line arguments. (0)
2199 /// - `maketx:constant_color_detect` (int) :
2200 /// If nonzero, detect images that are entirely
2201 /// one color, and change them to be low
2202 /// resolution (default: 0).
2203 /// - `maketx:monochrome_detect` (int) :
2204 /// If nonzero, change RGB images which have
2205 /// R==G==B everywhere to single-channel
2206 /// grayscale (default: 0).
2207 /// - `maketx:opaque_detect` (int) :
2208 /// If nonzero, drop the alpha channel if alpha
2209 /// is 1.0 in all pixels (default: 0).
2210 /// - `maketx:compute_average` (int) :
2211 /// If nonzero, compute and store the average
2212 /// color of the texture (default: 1).
2213 /// - `maketx:unpremult` (int) : If nonzero, unpremultiply color by alpha
2214 /// before color conversion, then multiply by
2215 /// alpha after color conversion (default: 0).
2216 /// - `maketx:incolorspace`, `maketx:outcolorspace` (string) :
2217 /// These two together will apply a color conversion
2218 /// (with OpenColorIO, if compiled). Default: ""
2219 /// - `maketx:colorconfig` (string) :
2220 /// Specifies a custom OpenColorIO color config
2221 /// file. Default: ""
2222 /// - `maketx:checknan` (int) : If nonzero, will consider it an error if the
2223 /// input image has any NaN pixels. (0)
2224 /// - `maketx:fixnan` (string) : If set to "black" or "box3", will attempt
2225 /// to repair any NaN pixels found in the
2226 /// input image (default: "none").
2227 /// - `maketx:set_full_to_pixels` (int) :
2228 /// If nonzero, doctors the full/display window
2229 /// of the texture to be identical to the
2230 /// pixel/data window and reset the origin
2231 /// to 0,0 (default: 0).
2232 /// - `maketx:filtername` (string) :
2233 /// If set, will specify the name of a high-quality
2234 /// filter to use when resampling for MIPmap
2235 /// levels. Default: "", use bilinear resampling.
2236 /// - `maketx:highlightcomp` (int) :
2237 /// If nonzero, performs highlight compensation --
2238 /// range compression and expansion around
2239 /// the resize, plus clamping negative pixel
2240 /// values to zero. This reduces ringing when
2241 /// using filters with negative lobes on HDR
2242 /// images.
2243 /// - `maketx:sharpen` (float) : If nonzero, sharpens details when creating
2244 /// MIPmap levels. The amount is the contrast
2245 /// metric. The default is 0, meaning no
2246 /// sharpening.
2247 /// - `maketx:nchannels` (int) : If nonzero, will specify how many channels
2248 /// the output texture should have, padding with
2249 /// 0 values or dropping channels, if it doesn't
2250 /// the number of channels in the input.
2251 /// (default: 0, meaning keep all input channels)
2252 /// - `maketx:channelnames` (string) :
2253 /// If set, overrides the channel names of the
2254 /// output image (comma-separated).
2255 /// - `maketx:fileformatname` (string) :
2256 /// If set, will specify the output file format.
2257 /// (default: "", meaning infer the format from
2258 /// the output filename)
2259 /// - `maketx:oiio_options` (int) :
2260 /// (Deprecated; all are handled by default)
2261 /// - `maketx:prman_options` (int) :
2262 /// If nonzero, override a whole bunch of settings
2263 /// as needed to make textures that are
2264 /// compatible with PRMan. This also enables
2265 /// prman_metadata. (0)
2266 /// - `maketx:prman_metadata` (int) :
2267 /// If set, output some metadata that PRMan will
2268 /// need for its textures. (0)
2269 /// - `maketx:mipimages` (string) :
2270 /// Semicolon-separated list of alternate images
2271 /// to be used for individual MIPmap levels,
2272 /// rather than simply downsizing. (default: "")
2273 /// - `maketx:mipmap_metadata` (int) :
2274 /// If nonzero, will propagate metadata to every MIP
2275 /// level. The default (0) only writes metadata to
2276 /// the highest-resolution level. (0)
2277 /// - `maketx:full_command_line` (string) :
2278 /// The command or program used to generate this
2279 /// call, will be embedded in the metadata.
2280 /// (default: "")
2281 /// - `maketx:ignore_unassoc` (int) :
2282 /// If nonzero, will disbelieve any evidence that
2283 /// the input image is unassociated alpha. (0)
2284 /// - `maketx:read_local_MB` (int) :
2285 /// If nonzero, will read the full input file
2286 /// locally if it is smaller than this
2287 /// threshold. Zero causes the system to make a
2288 /// good guess at a reasonable threshold (e.g. 1
2289 /// GB). (0)
2290 /// - `maketx:forcefloat` (int) :
2291 /// Forces a conversion through float data for
2292 /// the sake of ImageBuf math. (1)
2293 /// - `maketx:hash` (int) :
2294 /// Compute the sha1 hash of the file in parallel. (1)
2295 /// - `maketx:allow_pixel_shift` (int) :
2296 /// Allow up to a half pixel shift per mipmap level.
2297 /// The fastest path may result in a slight shift
2298 /// in the image, accumulated for each mip level
2299 /// with an odd resolution. (0)
2300 /// - `maketx:bumpformat` (string) :
2301 /// For the MakeTxBumpWithSlopes mode, chooses
2302 /// whether to assume the map is a height map
2303 /// ("height"), a normal map ("normal"), or
2304 /// automatically determine it from the number
2305 /// of channels ("auto", the default).
2306 /// - `maketx:uvslopes_scale` (float) :
2307 /// If nonzero, when used in MakeTxBumpWithSlopes
2308 /// mode, this computes derivatives for the
2309 /// bumpslopes data in UV space rather than in
2310 /// texel space, and divides them by this scale
2311 /// factor. The default is 0, disabling the
2312 /// feature. If you use this feature, a suggested
2313 /// value is 256.
2314 /// - `maketx:cdf` (int) :
2315 /// If nonzero, will write a Gaussian CDF and
2316 /// Inverse Gaussian CDF as per-channel metadata
2317 /// in the texture, which can be used by shaders
2318 /// to implement Histogram-Preserving Blending.
2319 /// This is only useful when the texture being
2320 /// created is written to an image format that
2321 /// supports arbitrary metadata (e.g. OpenEXR).
2322 /// (See Burley, "On Histogram-Preserving Blending
2323 /// for Randomized Texture Tiling," JCGT 8(4), 2019,
2324 /// and Heitz/Neyret, "High-Performance By-Example
2325 /// Noise using a Histogram-Preserving Blending
2326 /// Operator," ACM SIGGRAPH / Eurographics Symposium
2327 /// on High-Performance Graphics 2018.) (default: 0)
2328 /// - `maketx:cdfsigma` (float) :
2329 /// When `maketx:cdf` is active, determines the
2330 /// CDF sigma (default: 1.0/6).
2331 /// - `maketx:cdfbits` (int) :
2332 /// When `maketx:cdf` is active, determines the
2333 /// number of bits to use for the size of the CDF
2334 /// table. (default: 8, meaning 256 bins)
2335 ///
2336 /// @param mode
2337 /// Describes what type of texture file we are creating and may
2338 /// be one of:
2339 /// - `MakeTxTexture` : Ordinary 2D texture.
2340 /// - `MakeTxEnvLatl` : Latitude-longitude environment map
2341 /// - `MakeTxEnvLatlFromLightProbe` : Latitude-longitude environment map
2342 /// constructed from a "light probe"
2343 /// image.
2344 /// - `MakeTxBumpWithSlopes` : Bump/displacement map with extra slope
2345 /// data channels (6 channels total,
2346 /// containing both the height and 1st and
2347 /// 2nd moments of slope distributions) for
2348 /// bump-to-roughness conversion in shaders.
2349 /// @param outputfilename
2350 /// Name of the file in which to save the resulting texture.
2351 /// @param config An ImageSpec that contains all the information and
2352 /// special instructions for making the texture. Anything set in config
2353 /// (format, tile size, or named metadata) will take precedence over
2354 /// whatever is specified by the input file itself. Additionally, named
2355 /// metadata that starts with "maketx:" will not be output to the file
2356 /// itself, but may contain instructions controlling how the texture is
2357 /// created. The full list of supported configuration options is listed
2358 /// below.
2359 /// @param outstream
2360 /// If not `nullptr`, it should point to a stream (for example,
2361 /// `&std::out`, or a pointer to a local `std::stringstream` to capture
2362 /// output), which is where console output and errors will be
2363 /// deposited. Note that error messages will also be retrievable from
2364 /// OIIO::geterror().
2365 ///
2366 ///
2367 
2368 /// Version of make_texture that starts with an ImageBuf.
2370  const ImageBuf &input,
2371  string_view outputfilename,
2372  const ImageSpec &config,
2373  std::ostream *outstream = nullptr);
2374 
2375 /// Version of make_texture that starts with a filename and reads the input
2376 /// from that file, rather than being given an ImageBuf directly.
2379  string_view outputfilename,
2380  const ImageSpec &config,
2381  std::ostream *outstream = nullptr);
2382 
2383 /// Version of make_texture that takes multiple filenames (reserved for
2384 /// future expansion, such as assembling several faces into a cube map).
2386  const std::vector<std::string> &filenames,
2387  string_view outputfilename,
2388  const ImageSpec &config,
2389  std::ostream *outstream = nullptr);
2390 /// @}
2391 
2392 
2393 /// Convert an OpenCV cv::Mat into an ImageBuf, copying the pixels (optionally
2394 /// converting to the pixel data type specified by `convert`, if not UNKNOWN,
2395 /// which means to preserve the original data type if possible). Return true
2396 /// if ok, false if it was not able to make the conversion from Mat to
2397 /// ImageBuf. Any error messages can be retrieved by calling `geterror()` on
2398 /// the returned ImageBuf. If OpenImageIO was compiled without OpenCV support,
2399 /// this function will return false.
2401 from_OpenCV (const cv::Mat& mat, TypeDesc convert = TypeUnknown,
2402  ROI roi={}, int nthreads=0);
2403 
2404 /// Construct an OpenCV cv::Mat containing the contents of ImageBuf src, and
2405 /// return true. If it is not possible, or if OpenImageIO was compiled without
2406 /// OpenCV support, then return false. Any error messages can be retrieved by
2407 /// calling OIIO::geterror(). Note that OpenCV only supports up to 4 channels,
2408 /// so >4 channel images will be truncated in the conversion.
2409 OIIO_API bool to_OpenCV (cv::Mat& dst, const ImageBuf& src,
2410  ROI roi={}, int nthreads=0);
2411 
2412 
2413 /// Capture a still image from a designated camera. If able to do so,
2414 /// store the image in dst and return true. If there is no such device,
2415 /// or support for camera capture is not available (such as if OpenCV
2416 /// support was not enabled at compile time), return false and do not
2417 /// alter dst.
2418 ImageBuf OIIO_API capture_image (int cameranum = 0,
2420 
2421 
2422 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2423 // DEPRECATED(1.9):
2424 OIIO_DEPRECATED("use version that returns ImageBuf (1.9)")
2425 inline bool capture_image (ImageBuf &dst, int cameranum = 0,
2427  dst = capture_image (cameranum, convert);
2428  return !dst.has_error();
2429 }
2430 #endif // DOXYGEN_SHOULD_SKIP_THIS
2431 
2432 
2433 #if defined(__OPENCV_CORE_TYPES_H__) || defined(OPENCV_CORE_TYPES_H)
2434 // These declarations are only visible if the OpenCV headers have already
2435 // been encountered.
2436 
2437 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2438 // DEPRECATED(2.0). The OpenCV 1.x era IplImage-based functions should be
2439 // avoided, giving preference to from_OpenCV.
2440 ImageBuf OIIO_API from_IplImage (const IplImage *ipl,
2442 // DEPRECATED(1.9):
2443 OIIO_DEPRECATED("use from_OpenCV (1.9)")
2444 inline bool from_IplImage (ImageBuf &dst, const IplImage *ipl,
2446  dst = from_IplImage (ipl, convert);
2447  return ! dst.has_error();
2448 }
2449 
2450 // DEPRECATED(2.0). The OpenCV 1.x era IplImage-based functions should be
2451 // avoided, giving preference to from_OpenCV.
2452 OIIO_DEPRECATED("use from_OpenCV (2.9)")
2453 OIIO_API IplImage* to_IplImage (const ImageBuf &src);
2454 #endif // DOXYGEN_SHOULD_SKIP_THIS
2455 
2456 #endif
2457 
2458 
2459 
2460 /// Return the "deep" equivalent of the "flat" input `src`. Turning a flat
2461 /// image into a deep one means:
2462 ///
2463 /// * If the `src` image has a "Z" channel: if the source pixel's Z channel
2464 /// value is not infinite, the corresponding pixel of `dst` will get a
2465 /// single depth sample that copies the data from the source pixel;
2466 /// otherwise, dst will get an empty pixel. In other words, infinitely far
2467 /// pixels will not turn into deep samples.
2468 ///
2469 /// * If the `src` image lacks a "Z" channel: if any of the source pixel's
2470 /// channel values are nonzero, the corresponding pixel of `dst` will get
2471 /// a single depth sample that copies the data from the source pixel and
2472 /// uses the zvalue parameter for the depth; otherwise, if all source
2473 /// channels in that pixel are zero, the destination pixel will get no
2474 /// depth samples.
2475 ///
2476 /// If `src` is already a deep image, it will just copy pixel values from
2477 /// `src`.
2478 ImageBuf OIIO_API deepen (const ImageBuf &src, float zvalue = 1.0f,
2479  ROI roi={}, int nthreads=0);
2480 /// Write to an existing image `dst` (allocating if it is uninitialized).
2481 bool OIIO_API deepen (ImageBuf &dst, const ImageBuf &src, float zvalue = 1.0f,
2482  ROI roi={}, int nthreads=0);
2483 
2484 
2485 /// Return the "flattened" composite of deep image `src`. That is, it
2486 /// converts a deep image to a simple flat image by front-to- back
2487 /// compositing the samples within each pixel. If `src` is already a
2488 /// non-deep/flat image, it will just copy pixel values from `src` to `dst`.
2489 /// If `dst` is not already an initialized ImageBuf, it will be sized to
2490 /// match `src` (but made non-deep).
2491 ImageBuf OIIO_API flatten (const ImageBuf &src, ROI roi={}, int nthreads=0);
2492 /// Write to an existing image `dst` (allocating if it is uninitialized).
2493 bool OIIO_API flatten (ImageBuf &dst, const ImageBuf &src,
2494  ROI roi={}, int nthreads=0);
2495 
2496 
2497 /// Return the deep merge of the samples of deep images `A` and `B`,
2498 /// overwriting any existing samples of `dst` in the ROI. If
2499 /// `occlusion_cull` is true, any samples occluded by an opaque sample will
2500 /// be deleted.
2501 ImageBuf OIIO_API deep_merge (const ImageBuf &A, const ImageBuf &B,
2502  bool occlusion_cull = true,
2503  ROI roi={}, int nthreads=0);
2504 /// Write to an existing image `dst` (allocating if it is uninitialized).
2505 bool OIIO_API deep_merge (ImageBuf &dst, const ImageBuf &A,
2506  const ImageBuf &B, bool occlusion_cull = true,
2507  ROI roi={}, int nthreads=0);
2508 
2509 
2510 /// Return the samples of deep image `src` that are closer than the opaque
2511 /// frontier of deep image holdout, returning true upon success and false
2512 /// for any failures. Samples of `src` that are farther than the first
2513 /// opaque sample of holdout (for the corresponding pixel)will not be copied
2514 /// to `dst`. Image holdout is only used as the depth threshold; no sample
2515 /// values from holdout are themselves copied to `dst`.
2516 ImageBuf OIIO_API deep_holdout (const ImageBuf &src, const ImageBuf &holdout,
2517  ROI roi={}, int nthreads=0);
2518 /// Write to an existing image `dst` (allocating if it is uninitialized).
2519 bool OIIO_API deep_holdout (ImageBuf &dst, const ImageBuf &src,
2520  const ImageBuf &holdout,
2521  ROI roi={}, int nthreads=0);
2522 
2523 
2524 
2525 
2526 ///////////////////////////////////////////////////////////////////////
2527 // DEPRECATED(1.9): These are all functions that take raw pointers,
2528 // which we are deprecating as of 1.9, replaced by new versions that
2529 // take span<> for length safety.
2530 
2531 #ifndef DOXYGEN_SHOULD_SKIP_THIS
2532 
2533 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2534 inline bool fill (ImageBuf &dst, const float *values,
2535  ROI roi={}, int nthreads=0) {
2536  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
2537  return fill (dst, {values, nc}, roi, nthreads);
2538 }
2539 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2540 inline bool fill (ImageBuf &dst, const float *top, const float *bottom,
2541  ROI roi={}, int nthreads=0) {
2542  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
2543  return fill (dst, {top, nc}, {bottom, nc}, roi, nthreads);
2544 }
2545 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2546 inline bool fill (ImageBuf &dst, const float *topleft, const float *topright,
2547  const float *bottomleft, const float *bottomright,
2548  ROI roi={}, int nthreads=0) {
2549  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
2550  return fill (dst, {topleft, nc}, {topright, nc}, {bottomleft, nc},
2551  {bottomright, nc}, roi, nthreads);
2552 }
2553 
2554 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2555 inline bool checker (ImageBuf &dst, int width, int height, int depth,
2556  const float *color1, const float *color2,
2557  int xoffset=0, int yoffset=0, int zoffset=0,
2558  ROI roi={}, int nthreads=0) {
2559  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
2560  return checker (dst, width, height, depth, {color1,nc}, {color2,nc},
2561  xoffset, yoffset, zoffset, roi, nthreads);
2562 }
2563 
2564 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2565 inline bool add (ImageBuf &dst, const ImageBuf &A, const float *B,
2566  ROI roi={}, int nthreads=0) {
2567  return add (dst, A, {B,A.nchannels()}, roi, nthreads);
2568 }
2569 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2570 inline bool sub (ImageBuf &dst, const ImageBuf &A, const float *B,
2571  ROI roi={}, int nthreads=0) {
2572  return sub (dst, A, {B,A.nchannels()}, roi, nthreads);
2573 }
2574 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2575 inline bool absdiff (ImageBuf &dst, const ImageBuf &A, const float *B,
2576  ROI roi={}, int nthreads=0) {
2577  return absdiff (dst, A, cspan<float>(B,A.nchannels()), roi, nthreads);
2578 }
2579 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2580 inline bool mul (ImageBuf &dst, const ImageBuf &A, const float *B,
2581  ROI roi={}, int nthreads=0) {
2582  return mul (dst, A, {B, A.nchannels()}, roi, nthreads);
2583 }
2584 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2585 inline bool div (ImageBuf &dst, const ImageBuf &A, const float *B,
2586  ROI roi={}, int nthreads=0) {
2587  return div (dst, A, {B, A.nchannels()}, roi, nthreads);
2588 }
2589 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2590 inline bool mad (ImageBuf &dst, const ImageBuf &A, const float *B,
2591  const ImageBuf &C, ROI roi={}, int nthreads=0) {
2592  return mad (dst, A, {B, A.nchannels()}, C, roi, nthreads);
2593 }
2594 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2595 inline bool mad (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
2596  const float *C, ROI roi={}, int nthreads=0) {
2597  return mad (dst, A, C, B, roi, nthreads);
2598 }
2599 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2600 inline bool mad (ImageBuf &dst, const ImageBuf &A, const float *B,
2601  const float *C, ROI roi={}, int nthreads=0) {
2602  return mad (dst, A, {B, A.nchannels()}, {C, A.nchannels()}, roi, nthreads);
2603 }
2604 
2605 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2606 inline bool pow (ImageBuf &dst, const ImageBuf &A, const float *B,
2607  ROI roi={}, int nthreads=0) {
2608  return pow (dst, A, {B, A.nchannels()}, roi, nthreads);
2609 }
2610 
2611 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2612 inline bool channel_sum (ImageBuf &dst, const ImageBuf &src,
2613  const float *weights=nullptr, ROI roi={},
2614  int nthreads=0) {
2615  return channel_sum (dst, src, {weights, src.nchannels()},
2616  roi, nthreads);
2617 }
2618 
2619 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2620 inline bool channels (ImageBuf &dst, const ImageBuf &src,
2621  int nchannels, const int *channelorder,
2622  const float *channelvalues=nullptr,
2623  const std::string *newchannelnames=nullptr,
2624  bool shuffle_channel_names=false, int nthreads=0) {
2625  return channels (dst, src, nchannels,
2626  { channelorder, channelorder?nchannels:0 },
2627  { channelvalues, channelvalues?nchannels:0 },
2628  { newchannelnames, newchannelnames?nchannels:0},
2629  shuffle_channel_names, nthreads);
2630 }
2631 
2632 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2633 inline bool clamp (ImageBuf &dst, const ImageBuf &src,
2634  const float *min=nullptr, const float *max=nullptr,
2635  bool clampalpha01 = false,
2636  ROI roi={}, int nthreads=0) {
2637  return clamp (dst, src, { min, min ? src.nchannels() : 0 },
2638  { max, max ? src.nchannels() : 0 }, clampalpha01,
2639  roi, nthreads);
2640 }
2641 
2642 //OIIO_DEPRECATED("use version that takes span<> instead of raw pointer (2.0)")
2643 inline bool isConstantColor (const ImageBuf &src, float *color,
2644  ROI roi={}, int nthreads=0) {
2645  int nc = roi.defined() ? std::min(roi.chend,src.nchannels()) : src.nchannels();
2646  return isConstantColor (src, {color, color ? nc : 0}, roi, nthreads);
2647 }
2648 
2649 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2650 inline bool color_count (const ImageBuf &src, imagesize_t *count,
2651  int ncolors, const float *color,
2652  const float *eps=nullptr,
2653  ROI roi={}, int nthreads=0) {
2654  return color_count (src, count, ncolors,
2655  { color, ncolors*src.nchannels() },
2656  eps ? cspan<float>(eps,src.nchannels()) : cspan<float>(),
2657  roi, nthreads);
2658 }
2659 
2660 //OIIO_DEPRECATED("use version that takes span<> instead of raw pointer (2.0)")
2661 inline bool color_range_check (const ImageBuf &src, imagesize_t *lowcount,
2662  imagesize_t *highcount, imagesize_t *inrangecount,
2663  const float *low, const float *high,
2664  ROI roi={}, int nthreads=0) {
2665  return color_range_check (src, lowcount, highcount, inrangecount,
2666  {low,src.nchannels()}, {high,src.nchannels()},
2667  roi, nthreads);
2668 }
2669 
2670 //OIIO_DEPRECATED("use version that takes cspan<> instead of raw pointer (2.0)")
2671 inline bool render_text (ImageBuf &dst, int x, int y, string_view text,
2672  int fontsize, string_view fontname,
2673  const float *textcolor) {
2674  return render_text (dst, x, y, text, fontsize, fontname,
2675  {textcolor, textcolor?dst.nchannels():0});
2676 }
2677 
2678 #endif // DOXYGEN_SHOULD_SKIP_THIS
2679 
2680 ///////////////////////////////////////////////////////////////////////
2681 
2682 } // end namespace ImageBufAlgo
2683 
OIIO_API std::vector< imagesize_t > histogram(const ImageBuf &src, int channel=0, int bins=256, float min=0.0f, float max=1.0f, bool ignore_empty=false, ROI roi={}, int nthreads=0)
bool OIIO_API paste(ImageBuf &dst, int xbegin, int ybegin, int zbegin, int chbegin, const ImageBuf &src, ROI srcroi={}, int nthreads=0)
std::vector< double > sum2
ImageBuf OIIO_API fill(cspan< float > values, ROI roi, int nthreads=0)
bool OIIO_API render_point(ImageBuf &dst, int x, int y, cspan< float > color=1.0f, ROI roi={}, int nthreads=0)
GLint GLint GLint yoffset
Definition: glcorearb.h:412
GT_API const UT_StringHolder filename
ImageBuf OIIO_API ifft(const ImageBuf &src, ROI roi={}, int nthreads=0)
bool OIIO_API color_count(const ImageBuf &src, imagesize_t *count, int ncolors, cspan< float > color, cspan< float > eps=0.001f, ROI roi={}, int nthreads=0)
const ImageBuf & img() const
Definition: imagebufalgo.h:176
ImageBuf OIIO_API copy(const ImageBuf &src, TypeDesc convert=TypeUnknown, ROI roi={}, int nthreads=0)
bool OIIO_API normalize(ImageBuf &dst, const ImageBuf &A, float inCenter=0.0f, float outCenter=0.0f, float scale=1.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API complex_to_polar(const ImageBuf &src, ROI roi={}, int nthreads=0)
Image_or_Const(const float(&array)[N])
Definition: imagebufalgo.h:171
SIM_API const UT_StringHolder angle
bool OIIO_API max(ImageBuf &dst, Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
Write to an existing image dst (allocating if it is uninitialized).
void swap(UT::ArraySet< Key, MULTI, MAX_LOAD_FACTOR_256, Clearer, Hash, KeyEqual > &a, UT::ArraySet< Key, MULTI, MAX_LOAD_FACTOR_256, Clearer, Hash, KeyEqual > &b)
Definition: UT_ArraySet.h:1699
const GLdouble * v
Definition: glcorearb.h:837
ImageBuf OIIO_API colormatrixtransform(const ImageBuf &src, M44fParam M, bool unpremult=true, ROI roi={}, int nthreads=0)
CompareResults OIIO_API compare(const ImageBuf &A, const ImageBuf &B, float failthresh, float warnthresh, float failrelative, float warnrelative, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API ociofiletransform(const ImageBuf &src, string_view name, bool unpremult=true, bool inverse=false, const ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
std::string OIIO_API computePixelHashSHA1(const ImageBuf &src, string_view extrainfo="", ROI roi={}, int blocksize=0, int nthreads=0)
Definition: span.h:74
OIIO_API bool isMonochrome(const ImageBuf &src, float threshold=0.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API channel_append(const ImageBuf &A, const ImageBuf &B, ROI roi={}, int nthreads=0)
std::vector< imagesize_t > infcount
ImageBuf OIIO_API mad(Image_or_Const A, Image_or_Const B, Image_or_Const C, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API abs(const ImageBuf &A, ROI roi={}, int nthreads=0)
Compute per-pixel absolute value abs(A), returning the result image.
GLdouble s
Definition: glad.h:3009
bool OIIO_API render_box(ImageBuf &dst, int x1, int y1, int x2, int y2, cspan< float > color=1.0f, bool fill=false, ROI roi={}, int nthreads=0)
Image_or_Const(const std::vector< float > &val)
Definition: imagebufalgo.h:165
ImageBuf OIIO_API reorient(const ImageBuf &src, int nthreads=0)
ImageBuf OIIO_API min(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
#define OIIO_DEPRECATED(msg)
Definition: platform.h:466
GLint y
Definition: glcorearb.h:103
Tto convert(const Tfrom &source)
ImageBuf OIIO_API checker(int width, int height, int depth, cspan< float > color1, cspan< float > color2, int xoffset, int yoffset, int zoffset, ROI roi, int nthreads=0)
ImageBuf OIIO_API flatten(const ImageBuf &src, ROI roi={}, int nthreads=0)
**But if you need a result
Definition: thread.h:622
OIIO_API bool to_OpenCV(cv::Mat &dst, const ImageBuf &src, ROI roi={}, int nthreads=0)
std::vector< imagesize_t > finitecount
ImageBuf OIIO_API rotate270(const ImageBuf &src, ROI roi={}, int nthreads=0)
OutGridT const XformOp bool bool
GLdouble GLdouble x2
Definition: glad.h:2349
ImageBuf OIIO_API rangecompress(const ImageBuf &src, bool useluma=false, ROI roi={}, int nthreads=0)
basic_string_view< char > string_view
Definition: core.h:501
std::vector< float > stddev
ImageBuf OIIO_API transpose(const ImageBuf &src, ROI roi={}, int nthreads=0)
OIIO_API ImageBuf from_OpenCV(const cv::Mat &mat, TypeDesc convert=TypeUnknown, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API laplacian(const ImageBuf &src, ROI roi={}, int nthreads=0)
OIIO_INLINE_CONSTEXPR TypeDesc TypeUnknown(TypeDesc::UNKNOWN)
ImageBuf OIIO_API pow(const ImageBuf &A, cspan< float > B, ROI roi={}, int nthreads=0)
const ImageBuf * imgptr() const
Definition: imagebufalgo.h:177
ImageBuf OIIO_API clamp(const ImageBuf &src, cspan< float > min=-std::numeric_limits< float >::max(), cspan< float > max=std::numeric_limits< float >::max(), bool clampalpha01=false, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API fixNonFinite(const ImageBuf &src, NonFiniteFixMode mode=NONFINITE_BOX3, int *pixelsFixed=nullptr, ROI roi={}, int nthreads=0)
GA_API const UT_StringHolder scale
ImageBuf OIIO_API polar_to_complex(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLint GLsizei GLsizei height
Definition: glcorearb.h:103
ImageBuf OIIO_API fit(const ImageBuf &src, string_view filtername="", float filterwidth=0.0f, string_view fillmode="letterbox", bool exact=false, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API fillholes_pushpull(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLfloat f
Definition: glcorearb.h:1926
ImageBuf OIIO_API flop(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API sub(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
PixelStats(int nchannels)
ImageBuf OIIO_API make_kernel(string_view name, float width, float height, float depth=1.0f, bool normalize=true)
GLboolean reset
Definition: glad.h:5138
ImageBuf OIIO_API deep_merge(const ImageBuf &A, const ImageBuf &B, bool occlusion_cull=true, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API deepen(const ImageBuf &src, float zvalue=1.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API premult(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API dilate(const ImageBuf &src, int width=3, int height=-1, ROI roi={}, int nthreads=0)
ROI OIIO_API text_size(string_view text, int fontsize=16, string_view fontname="")
ImageBuf OIIO_API rotate180(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API erode(const ImageBuf &src, int width=3, int height=-1, ROI roi={}, int nthreads=0)
GLdouble y1
Definition: glad.h:2349
ImageBuf OIIO_API invert(const ImageBuf &A, ROI roi={}, int nthreads=0)
cspan< float > val() const
Definition: imagebufalgo.h:178
ImageBuf OIIO_API maxchan(const ImageBuf &A, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API color_map(const ImageBuf &src, int srcchannel, int nknots, int channels, cspan< float > knots, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API circular_shift(const ImageBuf &src, int xshift, int yshift, int zshift=0, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API over(const ImageBuf &A, const ImageBuf &B, ROI roi={}, int nthreads=0)
OIIO_API ImageBuf contrast_remap(const ImageBuf &src, cspan< float > black=0.0f, cspan< float > white=1.0f, cspan< float > min=0.0f, cspan< float > max=1.0f, cspan< float > scontrast=1.0f, cspan< float > sthresh=0.5f, ROI={}, int nthreads=0)
std::vector< imagesize_t > nancount
void swap(Image_or_Const &other)
Definition: imagebufalgo.h:180
GLint GLint xoffset
Definition: glcorearb.h:411
ImageBuf OIIO_API saturate(const ImageBuf &src, float scale=0.0f, int firstchannel=0, ROI roi={}, int nthreads=0)
GLuint const GLchar * name
Definition: glcorearb.h:786
Image_or_Const(const float &val)
Definition: imagebufalgo.h:164
ImageBuf OIIO_API fft(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLint GLenum GLint x
Definition: glcorearb.h:409
ImageBuf OIIO_API repremult(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLint void * img
Definition: glcorearb.h:556
ImageBuf OIIO_API rotate(const ImageBuf &src, float angle, string_view filtername=string_view(), float filterwidth=0.0f, bool recompute_roi=false, ROI roi={}, int nthreads=0)
bool is_val() const
Definition: imagebufalgo.h:174
Image_or_Const(const ImageBuf &img)
Definition: imagebufalgo.h:161
ImageBuf OIIO_API st_warp(const ImageBuf &src, const ImageBuf &stbuf, string_view filtername=string_view(), float filterwidth=0.0f, int chan_s=0, int chan_t=1, bool flip_s=false, bool flip_t=false, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API div(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API colorconvert(const ImageBuf &src, string_view fromspace, string_view tospace, bool unpremult=true, string_view context_key="", string_view context_value="", const ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
Transform between named color spaces, returning an ImageBuf result.
bool OIIO_API make_texture(MakeTextureMode mode, const ImageBuf &input, string_view outputfilename, const ImageSpec &config, std::ostream *outstream=nullptr)
Version of make_texture that starts with an ImageBuf.
ImageBuf OIIO_API capture_image(int cameranum=0, TypeDesc convert=TypeUnknown)
std::vector< float > max
GLenum mode
Definition: glcorearb.h:99
GLint GLint GLsizei GLsizei GLsizei depth
Definition: glcorearb.h:476
ImageBuf OIIO_API warp(const ImageBuf &src, M33fParam M, string_view filtername=string_view(), float filterwidth=0.0f, bool recompute_roi=false, ImageBuf::WrapMode wrap=ImageBuf::WrapDefault, ROI roi={}, int nthreads=0)
GLint GLint bottom
Definition: glcorearb.h:2005
Image_or_Const(const ImageBuf *img)
Definition: imagebufalgo.h:162
ImageBuf OIIO_API noise(string_view noisetype, float A=0.0f, float B=0.1f, bool mono=false, int seed=0, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API flip(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API unpremult(const ImageBuf &src, ROI roi={}, int nthreads=0)
bool OIIO_API min(ImageBuf &dst, Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
Write to an existing image dst (allocating if it is uninitialized).
bool OIIO_API render_line(ImageBuf &dst, int x1, int y1, int x2, int y2, cspan< float > color=1.0f, bool skip_first_point=false, ROI roi={}, int nthreads=0)
GLenum GLenum dst
Definition: glcorearb.h:1793
Definition: imageio.h:85
ImageBuf OIIO_API cut(const ImageBuf &src, ROI roi={}, int nthreads=0)
IMATH_NAMESPACE::V2f IMATH_NAMESPACE::Box2i std::string this attribute is obsolete as of OpenEXR v3 float
OIIO_API const ImageBuf & bluenoise_image()
ImageBuf OIIO_API ociolook(const ImageBuf &src, string_view looks, string_view fromspace, string_view tospace, bool unpremult=true, bool inverse=false, string_view context_key="", string_view context_value="", const ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
Image_or_Const(None)
Definition: imagebufalgo.h:160
OIIO_API bool isConstantColor(const ImageBuf &src, float threshold=0.0f, span< float > color={}, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API resize(const ImageBuf &src, string_view filtername="", float filterwidth=0.0f, ROI roi={}, int nthreads=0)
int OIIO_API compare_Yee(const ImageBuf &A, const ImageBuf &B, CompareResults &result, float luminance=100, float fov=45, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API rotate90(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLenum GLsizei GLsizei GLint * values
Definition: glcorearb.h:1602
Replace non-finite values with 0.0.
GLuint color
Definition: glcorearb.h:1261
ImageBuf OIIO_API median_filter(const ImageBuf &src, int width=3, int height=-1, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API absdiff(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
LeafData & operator=(const LeafData &)=delete
std::vector< float > min
bool OIIO_API render_text(ImageBuf &dst, int x, int y, string_view text, int fontsize=16, string_view fontname="", cspan< float > textcolor=1.0f, TextAlignX alignx=TextAlignX::Left, TextAlignY aligny=TextAlignY::Baseline, int shadow=0, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API max(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
GLuint GLfloat * val
Definition: glcorearb.h:1608
GA_API const UT_StringHolder N
Image_or_Const(const float *v, size_t s)
Definition: imagebufalgo.h:167
ImageBuf OIIO_API channel_sum(const ImageBuf &src, cspan< float > weights=1.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API rangeexpand(const ImageBuf &src, bool useluma=false, ROI roi={}, int nthreads=0)
GLint GLsizei width
Definition: glcorearb.h:103
GLdouble GLdouble GLdouble top
Definition: glad.h:2817
ImageBuf OIIO_API unsharp_mask(const ImageBuf &src, string_view kernel="gaussian", float width=3.0f, float contrast=1.0f, float threshold=0.0f, ROI roi={}, int nthreads=0)
OIIO_API ROI nonzero_region(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API ociodisplay(const ImageBuf &src, string_view display, string_view view, string_view fromspace="", string_view looks="", bool unpremult=true, bool inverse=false, string_view context_key="", string_view context_value="", const ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
OutGridT XformOp bool bool MergePolicy merge
ImageBuf OIIO_API add(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
Image_or_Const(const float *v, int s)
Definition: imagebufalgo.h:168
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:127
ImageBuf OIIO_API deep_holdout(const ImageBuf &src, const ImageBuf &holdout, ROI roi={}, int nthreads=0)
GLdouble GLdouble GLdouble y2
Definition: glad.h:2349
std::vector< float > avg
ImageBuf OIIO_API crop(const ImageBuf &src, ROI roi={}, int nthreads=0)
bool OIIO_API histogram_draw(ImageBuf &dst, const std::vector< imagesize_t > &histogram)
ImageBuf OIIO_API resample(const ImageBuf &src, bool interpolate=true, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API zero(ROI roi, int nthreads=0)
uint64_t imagesize_t
Definition: imageio.h:52
ImageBuf OIIO_API convolve(const ImageBuf &src, const ImageBuf &kernel, bool normalize=true, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API minchan(const ImageBuf &src, ROI roi={}, int nthreads=0)
Image_or_Const(cspan< float > val)
Definition: imagebufalgo.h:163
bool is_empty() const
Definition: imagebufalgo.h:175
ImageBuf OIIO_API zover(const ImageBuf &A, const ImageBuf &B, bool z_zeroisinf=false, ROI roi={}, int nthreads=0)
GLint GLint GLint GLint zoffset
Definition: glcorearb.h:477
GLint GLsizei count
Definition: glcorearb.h:405
PixelStats OIIO_API computePixelStats(const ImageBuf &src, ROI roi={}, int nthreads=0)
bool OIIO_API color_range_check(const ImageBuf &src, imagesize_t *lowcount, imagesize_t *highcount, imagesize_t *inrangecount, cspan< float > low, cspan< float > high, ROI roi={}, int nthreads=0)
OIIO_API bool isConstantChannel(const ImageBuf &src, int channel, float val, float threshold=0.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API channels(const ImageBuf &src, int nchannels, cspan< int > channelorder, cspan< float > channelvalues={}, cspan< std::string > newchannelnames={}, bool shuffle_channel_names=false, int nthreads=0)
Image_or_Const(std::initializer_list< const float > val)
Definition: imagebufalgo.h:166
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:126
ImageBuf OIIO_API mul(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
int nchannels() const
#define OIIO_API
Definition: export.h:65
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
Definition: glcorearb.h:1297
GLenum src
Definition: glcorearb.h:1793
bool is_img() const
Definition: imagebufalgo.h:173