HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
imagebufalgo.h
Go to the documentation of this file.
1 /*
2  Copyright 2008 Larry Gritz and the other authors and contributors.
3  All Rights Reserved.
4 
5  Redistribution and use in source and binary forms, with or without
6  modification, are permitted provided that the following conditions are
7  met:
8  * Redistributions of source code must retain the above copyright
9  notice, this list of conditions and the following disclaimer.
10  * Redistributions in binary form must reproduce the above copyright
11  notice, this list of conditions and the following disclaimer in the
12  documentation and/or other materials provided with the distribution.
13  * Neither the name of the software's owners nor the names of its
14  contributors may be used to endorse or promote products derived from
15  this software without specific prior written permission.
16  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 
28  (This is the Modified BSD License)
29 */
30 
31 
32 // clang-format off
33 
34 #pragma once
35 #define OPENIMAGEIO_IMAGEBUFALGO_H
36 
37 #if defined(_MSC_VER)
38 // Ignore warnings about DLL exported classes with member variables that are template classes.
39 // This happens with the std::vector<T> members of PixelStats below.
40 # pragma warning (disable : 4251)
41 #endif
42 
43 #include <OpenImageIO/imageio.h>
44 #include <OpenImageIO/imagebuf.h>
45 #include <OpenImageIO/fmath.h>
46 #include <OpenImageIO/color.h>
47 #include <OpenImageIO/parallel.h>
48 #include <OpenImageIO/span.h>
49 
50 #include <OpenEXR/ImathMatrix.h> /* because we need M33f */
51 
52 #include <limits>
53 
54 #if !defined(__OPENCV_CORE_TYPES_H__) && !defined(OPENCV_CORE_TYPES_H)
55 struct IplImage; // Forward declaration; used by Intel Image lib & OpenCV
56 namespace cv {
57  class Mat;
58 }
59 #endif
60 
61 
62 
64 
65 class Filter2D; // forward declaration
66 
67 
68 
69 /// Some generalities about ImageBufAlgo functions: (READ ME!)
70 ///
71 /// This section explains the general rules common to all ImageBufAlgo
72 /// functions. Only exceptions to these rules will be explained in the
73 /// subsequent listings of all the individual ImageBufAlgo functions.
74 ///
75 ///
76 /// ### Return values and error messages
77 ///
78 /// Most ImageBufAlgo functions that produce image data come in two forms:
79 ///
80 /// 1. Return an ImageBuf.
81 ///
82 /// The return value is a new ImageBuf containing the result image. In
83 /// this case, an entirely new image will be created to hold the result.
84 /// In case of error, the result image returned can have any error
85 /// conditions checked with `has_error()` and `geterror()`.
86 ///
87 /// // Method 1: Return an image result
88 /// ImageBuf fg ("fg.exr"), bg ("bg.exr");
89 /// ImageBuf dst = ImageBufAlgo::over (fg, bg);
90 /// if (dst.has_error())
91 /// std::cout << "error: " << dst.geterror() << "\n";
92 ///
93 /// 2. Pass a destination ImageBuf reference as the first parameter.
94 ///
95 /// The function is passed a *destination* ImageBuf where the results
96 /// will be stored, and the return value is a `bool` that is `true` if
97 /// the function succeeds or `false` if the function fails. Upon failure,
98 /// the destination ImageBuf (the one that is being altered) will have an
99 /// error message set.
100 ///
101 /// // Method 2: Write into an existing image
102 /// ImageBuf fg ("fg.exr"), bg ("bg.exr");
103 /// ImageBuf dst; // will be the output image
104 /// bool ok = ImageBufAlgo::over (dst, fg, bg);
105 /// if (! ok)
106 /// std::cout << "error: " << dst.geterror() << "\n";
107 ///
108 /// The first option (return an ImageBuf) is a more compact and intuitive
109 /// notation that is natural for most simple uses. But the second option
110 /// (pass an ImageBuf& referring to an existing destination) offers
111 /// additional flexibility, including more careful control over allocations,
112 /// the ability to partially overwrite regions of an existing image, and the
113 /// ability for the destination image to also be one of the input images
114 /// (for example, add(A,A,B) adds B into existing image A, with no third
115 /// image allocated at all).
116 ///
117 /// ### Region of interest
118 ///
119 /// Most ImageBufAlgo functions take an optional ROI parameter that
120 /// restricts the operation to a range in x, y, z, and channels. The default
121 /// ROI (also known as `ROI::All()) means no region restriction.
122 ///
123 /// For ImageBufAlgo functions that write into a destination ImageBuf
124 /// parameter and it is already initialized (i.e. allocated with a
125 /// particular size and data type), the operation will be performed on the
126 /// pixels in the destination that overlap the ROI, leaving pixels in the
127 /// destination which are outside the ROI unaltered.
128 ///
129 /// For ImageBufAlgo functions that return an ImageBuf directly, or their
130 /// `dst` parameter that is an uninitialized ImageBuf, the ROI (if set)
131 /// determines the size of the result image. If the ROI is the default
132 /// `All`, the result image size will be the union of the pixel data windows
133 /// of the input images and have a data type determind by the data types of
134 /// the input images.
135 ///
136 /// Most ImageBufAlgo functions also respect the `chbegin` and `chend`
137 /// members of the ROI, thus restricting the channel range on which the
138 /// operation is performed. The default ROI constructor sets up the ROI
139 /// to specify that the operation should be performed on all channels of
140 /// the input image(s).
141 ///
142 /// ### Constant and per-channel values
143 ///
144 /// Many ImageBufAlgo functions take per-channel constant-valued arguments
145 /// (for example, a fill color). These parameters are passed as
146 /// `cspan<float>`. These are generally expected to have length equal to the
147 /// number of channels. But you may also pass a single float which will be
148 /// used as the value for all channels. (More generally, what is happening
149 /// is that the last value supplied is replicated for any missing channel.)
150 ///
151 /// Some ImageBufAlgo functions have parameters of type `Image_or_Const`,
152 /// which may take either an ImageBuf reference, or a per-channel constant,
153 /// or a single constant to be used for all channels.
154 ///
155 /// ### Multithreading
156 ///
157 /// All ImageBufAlgo functions take an optional `nthreads` parameter that
158 /// signifies the maximum number of threads to use to parallelize the
159 /// operation. The default value for `nthreads` is 0, which signifies that
160 /// the number of thread should be the OIIO global default set by
161 /// `OIIO::attribute()`, which itself defaults to be the detected level of
162 /// hardware concurrency (number of cores available).
163 ///
164 /// Generally you can ignore this parameter (or pass 0), meaning to use all
165 /// the cores available in order to perform the computation as quickly as
166 /// possible. The main reason to explicitly pass a different number
167 /// (generally 1) is if the application is multithreaded at a high level,
168 /// and the thread calling the ImageBufAlgo function just wants to continue
169 /// doing the computation without spawning additional threads, which might
170 /// tend to crowd out the other application threads.
171 ///
172 
173 
174 
175 /// Image_or_Const: Parameter-passing helper that is a non-owning reference
176 /// to either an ImageBuf&, ImageBuf*, per-channel float constant, or a
177 /// single float constant. This lets us tame the combinatorics of functions
178 /// where each of several input parameters may be either images or constant
179 /// values.
181 public:
182  struct None {};
183  Image_or_Const (None) : m_type(NONE) {}
184  Image_or_Const (const ImageBuf &img) : m_type(IMG), m_img(&img) {}
185  Image_or_Const (const ImageBuf *img) : m_type(IMG), m_img(img) {}
186  Image_or_Const (cspan<float> val) : m_type(VAL), m_val(val) {}
187  Image_or_Const (const float& val) : m_type(VAL), m_val(val) {}
188  Image_or_Const (const std::vector<float>& val) : m_type(VAL), m_val(val) {}
189  Image_or_Const (const float *v, size_t s) : m_type(VAL), m_val(v,s) {}
190  Image_or_Const (const float *v, int s) : m_type(VAL), m_val(v,s) {}
191 
192  bool is_img () const { return m_type == IMG; }
193  bool is_val () const { return m_type == VAL; }
194  bool is_empty () const { return m_type == NONE; }
195  const ImageBuf& img () const { return *m_img; }
196  const ImageBuf* imgptr () const { return m_img; }
197  cspan<float> val () const { return m_val; }
198 
199  void swap (Image_or_Const &other) {
200  std::swap (m_type, other.m_type);
201  std::swap (m_img, other.m_img);
202  std::swap (m_val, other.m_val);
203  }
204 private:
205  enum Contents { NONE, VAL, IMG };
206  Contents m_type;
207  const ImageBuf * m_img = nullptr;
208  cspan<float> m_val;
209 };
210 
211 
212 
213 
214 namespace ImageBufAlgo {
215 
216 // old name (DEPRECATED 1.9)
218 
219 
220 
221 /// Create an all-black `float` image of size and channels as described by
222 /// the ROI. If dst is passed and is alredy initialized, keep its shape and
223 /// data type, and just zero out the pixels in the ROI.
224 ImageBuf OIIO_API zero (ROI roi, int nthreads=0);
225 bool OIIO_API zero (ImageBuf &dst, ROI roi={}, int nthreads=0);
226 
227 
228 /// Fill an image region with given channel values, either returning a new
229 /// image or altering the existing dst image within the ROI. Note that the
230 /// values arrays start with channel 0, even if the ROI indicates that a
231 /// later channel is the first to be changed.
232 ///
233 /// Three varieties of fill() exist: (a) a single set of channel values that
234 /// will apply to the whole ROI, (b) two sets of values that will create a
235 /// linearly interpolated gradient from top to bottom of the ROI, (c) four
236 /// sets of values that will be bilnearly interpolated across all four
237 /// corners of the ROI.
238 ImageBuf OIIO_API fill (cspan<float> values, ROI roi, int nthreads=0);
240  ROI roi, int nthreads=0);
241 ImageBuf OIIO_API fill (cspan<float> topleft, cspan<float> topright,
242  cspan<float> bottomleft, cspan<float> bottomright,
243  ROI roi, int nthreads=0);
245  ROI roi={}, int nthreads=0);
247  ROI roi={}, int nthreads=0);
248 bool OIIO_API fill (ImageBuf &dst, cspan<float> topleft, cspan<float> topright,
249  cspan<float> bottomleft, cspan<float> bottomright,
250  ROI roi={}, int nthreads=0);
251 
252 
253 /// Create a new image, or set the pixels in the destination image within
254 /// the ROI, to a checkerboard pattern with origin (xoffset,yoffset,zoffset)
255 /// and that alternates between color1[] and color2[] every width pixels in
256 /// x, every height pixels in y, and every depth pixels in z. The pattern
257 /// is definied in abstract "image space" independently of the pixel data
258 /// window of dst or the ROI.
259 ImageBuf OIIO_API checker (int width, int height, int depth,
260  cspan<float> color1, cspan<float> color2,
261  int xoffset, int yoffset, int zoffset,
262  ROI roi, int nthreads=0);
263 bool OIIO_API checker (ImageBuf &dst, int width, int height, int depth,
264  cspan<float> color1, cspan<float> color2,
265  int xoffset=0, int yoffset=0, int zoffset=0,
266  ROI roi={}, int nthreads=0);
267 
268 
269 /// Return an image of "noise", or add pseudorandom noise to existring
270 /// image dst in every pixel and channel specified by the roi (defaulting
271 /// to all pixels, all channels). There are several noise types to choose
272 /// from, and each behaves differently and has a different interpretation of
273 /// the A and B parameters:
274 /// "gaussian" adds Gaussian (normal distribution) noise values with
275 /// mean value A and standard deviation B.
276 /// "uniform" adds noise values uninformly distributed on range [A,B).
277 /// "salt" changes to value A a portion of pixels given by B.
278 /// If the 'mono' flag is true, a single noise value will be applied to all
279 /// channels specified by roi, but if 'mono' is false, a separate noise
280 /// value will be computed for each channel in the region.
281 ///
282 /// The random number generator is actually driven by a hash on the "image
283 /// space" coordinates and channel, independently of the pixel data window
284 /// of dst or the ROI. Choosing different seed values will result in a
285 /// different pattern, but for the same seed value, the noise at a given
286 /// pixel coordinate (x,y,z) channel c will is completely deterministic and
287 /// repeatable.
289  float A = 0.0f, float B = 0.1f, bool mono = false,
290  int seed = 0, ROI roi={}, int nthreads=0);
291 bool OIIO_API noise (ImageBuf &dst, string_view noisetype,
292  float A = 0.0f, float B = 0.1f, bool mono = false,
293  int seed = 0, ROI roi={}, int nthreads=0);
294 
295 
296 /// Generic channel shuffling: return (or store in dst) a copy of src, but
297 /// with channels in the order channelorder[0..nchannels-1]. For any
298 /// channel in which channelorder[i] < 0, it will just make dst channel i a
299 /// constant color -- set to channelvalues[i] (if channelvalues is not
300 /// empty) or 0.0 (if channelvalues is empty). In-place operation is
301 /// allowed (i.e., dst and src the same image, but an extra copy will
302 /// occur).
303 ///
304 /// If channelorder is empty, it will be interpreted as
305 /// {0, 1, ..., nchannels-1}, meaning that it's only renaming channels,
306 /// not reordering them.
307 ///
308 /// If newchannelnames is not empty, it contains an array of new channel
309 /// names. Channels for which newchannelnames[i] is the empty string (or
310 /// all channels, if newchannelnames is empty) will be named as follows:
311 /// If shuffle_channel_names is false, the resulting dst image will have
312 /// default channel names in the usual order ("R", "G", etc.), but if
313 /// shuffle_channel_names is true, the names will be taken from the
314 /// corresponding channels of the source image -- be careful with this,
315 /// shuffling both channel ordering and their names could result in no
316 /// semantic change at all, if you catch the drift.
317 ///
318 /// N.B. If you are merely interested in extending the number of channels
319 /// (with zero values for added channels) or truncating channels at the end
320 /// (but leaving the other channels intact), then you should call this as:
321 /// channels (dst, src, nchannels, {}, {}, {}, true);
323  int nchannels, cspan<int> channelorder,
324  cspan<float> channelvalues={},
325  cspan<std::string> newchannelnames={},
326  bool shuffle_channel_names=false, int nthreads=0);
327 bool OIIO_API channels (ImageBuf &dst, const ImageBuf &src,
328  int nchannels, cspan<int> channelorder,
329  cspan<float> channelvalues={},
330  cspan<std::string> newchannelnames={},
331  bool shuffle_channel_names=false, int nthreads=0);
332 
333 
334 /// Append the channels of A and B together into dst over the region of
335 /// interest. If the region passed is uninitialized (the default), it
336 /// will be interpreted as being the union of the pixel windows of A and
337 /// B (and all channels of both images). If dst is not already
338 /// initialized, it will be resized to be big enough for the region.
339 ImageBuf OIIO_API channel_append (const ImageBuf &A, const ImageBuf &B,
340  ROI roi={}, int nthreads=0);
341 bool OIIO_API channel_append (ImageBuf &dst, const ImageBuf &A,
342  const ImageBuf &B, ROI roi={}, int nthreads=0);
343 
344 
345 /// Return (or copy into dst at the corresponding locations) the specified
346 /// region of pixels of src. If dst is not already initialized, it will be
347 /// set to the same size as roi (defaulting to all of src), optionally with
348 /// the pixel type overridden by convert (if it is not UNKNOWN).
349 ImageBuf OIIO_API copy (const ImageBuf &src, TypeDesc convert=TypeUnknown,
350  ROI roi={}, int nthreads=0);
351 bool OIIO_API copy (ImageBuf &dst, const ImageBuf &src, TypeDesc convert=TypeUnknown,
352  ROI roi={}, int nthreads=0);
353 
354 /// Return (or store into dst) the specified region of src, without
355 /// altering its position in the image plane.
356 ImageBuf OIIO_API crop (const ImageBuf &src, ROI roi={}, int nthreads=0);
357 bool OIIO_API crop (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
358 
359 /// Return (or store into dst) the designated region of src, but shifted to
360 /// be at the (0,0) origin, and with the full/display resolution set to be
361 /// identical to the data region.
362 ImageBuf OIIO_API cut (const ImageBuf &src, ROI roi={}, int nthreads=0);
363 bool OIIO_API cut (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
364 
365 /// Copy into dst, beginning at (xbegin,ybegin,zbegin), the pixels of
366 /// src described by srcroi. If srcroi is ROI::All(), the entirety of src
367 /// will be used. It will copy into channels [chbegin...], as many
368 /// channels as are described by srcroi. Pixels or channels of dst outside
369 /// the range of roi will not be altered.
370 bool OIIO_API paste (ImageBuf &dst, int xbegin, int ybegin,
371  int zbegin, int chbegin, const ImageBuf &src,
372  ROI srcroi={}, int nthreads=0);
373 
374 
375 /// rotateN: Return (or copy into dst) a rotated copy of the image pixels of
376 /// src, in 90 degree increments. Pictorially:
377 ///
378 /// rotate90 rotate180 rotate270
379 /// ----------- ----------- -----------
380 /// AB --> CA AB --> DC AB --> BD
381 /// CD DB CD BA CD AC
382 ///
383 /// Only the pixels (and channels) in src that are specified by roi will be
384 /// copied to their corresponding positions in dst; the default roi is to
385 /// copy the whole data region of src. If dst is uninitialized, it will be
386 /// resized to be a float ImageBuf large enough to hold the region specified
387 /// by roi. It is an error to pass both an uninitialied dst and an undefined
388 /// roi.
389 ///
390 ImageBuf OIIO_API rotate90 (const ImageBuf &src, ROI roi={}, int nthreads=0);
391 ImageBuf OIIO_API rotate180 (const ImageBuf &src, ROI roi={}, int nthreads=0);
392 ImageBuf OIIO_API rotate270 (const ImageBuf &src, ROI roi={}, int nthreads=0);
393 bool OIIO_API rotate90 (ImageBuf &dst, const ImageBuf &src,
394  ROI roi={}, int nthreads=0);
395 bool OIIO_API rotate180 (ImageBuf &dst, const ImageBuf &src,
396  ROI roi={}, int nthreads=0);
397 bool OIIO_API rotate270 (ImageBuf &dst, const ImageBuf &src,
398  ROI roi={}, int nthreads=0);
399 
400 
401 /// flip()/flop()/transpose(): Return (or copy into dst) a subregion of src,
402 /// but with the scanlines exchanged vertically (flip), or columns exchanged
403 /// horizontally (flop), or transposed across the diagonal by swapping rows
404 /// for columns (transpose) within the display/full window. In other words,
405 ///
406 /// flip flop transpose
407 /// ----------- ----------- -----------
408 /// AB --> CD AB --> BA AB --> AC
409 /// CD AB CD DC CD BD
410 ///
411 /// Only the pixels (and channels) in src that are specified by roi will be
412 /// copied to their corresponding positions in dst; the default roi is to
413 /// copy the whole data region of src. If dst is uninitialized, it will be
414 /// resized to be a float ImageBuf large enough to hold the region specified
415 /// by roi. It is an error to pass both an uninitialied dst and an undefined
416 /// roi.
417 ImageBuf OIIO_API flip (const ImageBuf &src, ROI roi={}, int nthreads=0);
418 ImageBuf OIIO_API flop (const ImageBuf &src, ROI roi={}, int nthreads=0);
419 ImageBuf OIIO_API transpose (const ImageBuf &src, ROI roi={}, int nthreads=0);
420 bool OIIO_API flip (ImageBuf &dst, const ImageBuf &src,
421  ROI roi={}, int nthreads=0);
422 bool OIIO_API flop (ImageBuf &dst, const ImageBuf &src,
423  ROI roi={}, int nthreads=0);
424 bool OIIO_API transpose (ImageBuf &dst, const ImageBuf &src,
425  ROI roi={}, int nthreads=0);
426 
427 
428 /// Return (or store into dst) a copy of src, but with whatever seties of
429 /// rotations, flips, or flops are necessary to transform the pixels into
430 /// the configuration suggested by the Orientation metadata of the image
431 /// (and the Orientation metadata is then set to 1, ordinary orientation).
432 ImageBuf OIIO_API reorient (const ImageBuf &src, int nthreads=0);
433 bool OIIO_API reorient (ImageBuf &dst, const ImageBuf &src, int nthreads=0);
434 
435 
436 /// Return (or store into dst) a subregion of src, but circularly
437 /// shifting by the given amount. To clarify, the circular shift
438 /// of [0,1,2,3,4,5] by +2 is [4,5,0,1,2,3].
439 ///
440 /// Only the pixels (and channels) of src that are specified by roi will
441 /// be copied to dst; the default roi is to alter all the pixels in dst.
442 /// If dst is uninitialized, it will be resized to be an ImageBuf large
443 /// enough to hold the region specified by the transposed roi. It is an
444 /// error to pass both an uninitialied dst and an undefined roi.
446  int xshift, int yshift, int zshift=0,
447  ROI roi={}, int nthreads=0);
448 bool OIIO_API circular_shift (ImageBuf &dst, const ImageBuf &src,
449  int xshift, int yshift, int zshift=0,
450  ROI roi={}, int nthreads=0);
451 
452 
453 /// Return (or copy into dst) pixels of src with pixel values clamped as
454 /// follows:
455 /// * min specifies the minimum clamp value for each channel
456 /// (if min is empty, no minimum clamping is performed).
457 /// * max specifies the maximum clamp value for each channel
458 /// (if max is empty, no maximum clamping is performed).
459 /// * If clampalpha01 is true, then additionally any alpha channel is
460 /// clamped to the 0-1 range.
461 ImageBuf OIIO_API clamp (const ImageBuf &src,
464  bool clampalpha01 = false, ROI roi={}, int nthreads=0);
465 bool OIIO_API clamp (ImageBuf &dst, const ImageBuf &src,
468  bool clampalpha01 = false, ROI roi={}, int nthreads=0);
469 
470 /// Compute per-pixel sum A + B, returning the result image or storing
471 /// the result into existing image dst.
472 ///
473 /// A and B may each either be an ImageBuf&, or a cspan<float> giving a per-
474 /// channel constant, or a single constant used for all channels. (But at
475 /// least one must be an image.)
477  ROI roi={}, int nthreads=0);
479  ROI roi={}, int nthreads=0);
480 
481 
482 /// Compute per-pixel signed difference A - B, returning the result image or
483 /// storing the result into existing image dst.
484 ///
485 /// A and B may each either be an ImageBuf&, or a cspan<float> giving a per-
486 /// channel constant, or a single constant used for all channels. (But at
487 /// least one must be an image.)
489  ROI roi={}, int nthreads=0);
491  ROI roi={}, int nthreads=0);
492 
493 
494 /// Compute per-pixel absolute difference abs(A - B), returning the result
495 /// image or storing the result into existing image dst.
496 ///
497 /// A and B may each either be an ImageBuf&, or a cspan<float> giving a per-
498 /// channel constant, or a single constant used for all channels. (But at
499 /// least one must be an image.)
501  ROI roi={}, int nthreads=0);
503  ROI roi={}, int nthreads=0);
504 
505 
506 /// Compute per-pixel absolute value abs(A), returning the result image or
507 /// storing the result into existing image dst.
508 ImageBuf OIIO_API abs (const ImageBuf &A, ROI roi={}, int nthreads=0);
509 bool OIIO_API abs (ImageBuf &dst, const ImageBuf &A, ROI roi={}, int nthreads=0);
510 
511 
512 /// Compute per-pixel product A * B, returning the result image or
513 /// storing the result into existing image dst.
514 ///
515 /// Either both A and B are images, or one is an image and the other is an
516 /// cspan<float> giving a per-channel constant or a single constant
517 /// used for all channels.
519  ROI roi={}, int nthreads=0);
521  ROI roi={}, int nthreads=0);
522 
523 
524 /// div(): Compute per-pixel division A / B, returning the result image or
525 /// storing the result into existing image dst.
526 ///
527 /// We define division-by-zero to result in 0.
528 ///
529 /// A is always an image, and B is either an image or an cspan<float>
530 /// giving a per-channel constant or a single constant used for all
531 /// channels.
533  ROI roi={}, int nthreads=0);
535  ROI roi={}, int nthreads=0);
536 
537 
538 /// mad(): Compute per-pixel multiply-and-add A * B + C, returning the result
539 /// image or storing the result into existing image dst.
540 ///
541 /// A, B, and C are each either an image, or an cspan<float> giving a
542 /// per-channel constant or a single constant used for all channels. (Note:
543 /// at least one must be an image.)
545  Image_or_Const C, ROI roi={}, int nthreads=0);
547  Image_or_Const C, ROI roi={}, int nthreads=0);
548 
549 
550 
551 /// Compute per-pixel inverse 1.0 - A. returning the result image or storing
552 /// the result into existing image dst.
553 ///
554 /// Tips for callers: (1) You probably want to set roi to restrict the
555 /// operation to only the color channels, and not accidentally include
556 /// alpha, z, or others. (2) There may be situations where you want to
557 /// unpremult() before the inverst, then premult() the result, so that you
558 /// are computing the inverse of the unmasked color.
559 ImageBuf OIIO_API invert (const ImageBuf &A, ROI roi={}, int nthreads=0);
560 bool OIIO_API invert (ImageBuf &dst, const ImageBuf &A, ROI roi={}, int nthreads=0);
561 
562 
563 /// Compute per-pixel power A ^ B. returning the result image or storing
564 /// the result into existing image dst. It is permitted for dst and A to be
565 /// the same image.
566 ///
567 /// A is always an image, and B is either an image or an cspan<float>
568 /// giving a per-channel constant or a single constant used for all
569 /// channels.
571  ROI roi={}, int nthreads=0);
572 bool OIIO_API pow (ImageBuf &dst, const ImageBuf &A, cspan<float> B,
573  ROI roi={}, int nthreads=0);
574 
575 
576 /// Converts a multi-channel image into a 1-channel image via a weighted sum
577 /// of channels: (channel[0]*weight[0] + channel[1]*weight[1] + ...),
578 /// returning the resulting 1-channel image or storing the result into
579 /// channel 0 of existing image dst. The weights, if not supplied, default
580 /// to { 1, 1, 1, ... }).
582  ROI roi={}, int nthreads=0);
583 bool OIIO_API channel_sum (ImageBuf &dst, const ImageBuf &src,
585  ROI roi={}, int nthreads=0);
586 
587 
588 
589 /// rangecompress() returns (or copy into dst) all pixels and color channels
590 /// of src within region roi (defaulting to all the defined pixels of dst),
591 /// rescaling their range with a logarithmic transformation. Alpha and z
592 /// channels are not transformed.
593 ///
594 /// rangeexpand() performs the inverse transformation (logarithmic back
595 /// into linear).
596 ///
597 /// If useluma is true, the luma of channels [roi.chbegin..roi.chbegin+2]
598 /// (presumed to be R, G, and B) are used to compute a single scale
599 /// factor for all color channels, rather than scaling all channels
600 /// individually (which could result in a color shift).
601 ///
602 /// The purpose of these function is as follows: Some image operations (such
603 /// as resizing with a "good" filter that contains negative lobes) can have
604 /// objectionable artifacts when applied to images with very high-contrast
605 /// regions involving extra bright pixels (such as highlights in HDR
606 /// captured or rendered images). By compressing the range pixel values,
607 /// then performing the operation, then expanding the range of the result
608 /// again, the result can be much more pleasing (even if not exactly
609 /// correct).
610 ImageBuf OIIO_API rangecompress (const ImageBuf &src, bool useluma = false,
611  ROI roi={}, int nthreads=0);
612 bool OIIO_API rangecompress (ImageBuf &dst, const ImageBuf &src,
613  bool useluma = false, ROI roi={}, int nthreads=0);
614 ImageBuf OIIO_API rangeexpand (const ImageBuf &src, bool useluma = false,
615  ROI roi={}, int nthreads=0);
616 bool OIIO_API rangeexpand (ImageBuf &dst, const ImageBuf &src,
617  bool useluma = false, ROI roi={}, int nthreads=0);
618 
619 
620 /// Return (or copy into dst) the pixels of src within the ROI, applying a
621 /// color transform implemented by a ColorProcessor. In-place operations
622 /// (dst == src) are supported.
623 ///
624 /// If unpremult is true, divide the RGB channels by alpha (if it exists and
625 /// is nonzero) before color conversion, then re-multiply by alpha after the
626 /// after the color conversion. Passing unpremult=false skips this step,
627 /// which may be desirable if you know that the image is "unassociated alpha"
628 /// (a.k.a. "not pre-multiplied colors").
630  const ColorProcessor *processor,
631  bool unpremult, ROI roi={}, int nthreads=0);
632 bool OIIO_API colorconvert (ImageBuf &dst, const ImageBuf &src,
633  const ColorProcessor *processor,
634  bool unpremult, ROI roi={}, int nthreads=0);
635 
636 /// Apply a color transform in-place to just one color:
637 /// color[0..nchannels-1]. nchannels should either be 3 or 4 (if 4, the
638 /// last channel is alpha).
639 ///
640 /// If unpremult is true, unpremultiply before color conversion, then
641 /// premultiply after the color conversion. You'll may want to use this
642 /// flag if your image contains an alpha channel.
644  const ColorProcessor *processor, bool unpremult);
645 
646 // Less safe version with raw pointer and length.
647 inline bool colorconvert (float *color, int nchannels,
648  const ColorProcessor *processor, bool unpremult) {
649  return colorconvert ({color,nchannels}, processor, unpremult);
650 }
651 
652 
653 /// Return (or copy into dst) the pixels of src within the ROI, applying a
654 /// color transform specified by from/to names and optionally a context
655 /// key/value. In-place operations (dst == src) are supported.
656 ///
657 /// If unpremult is true, divide the RGB channels by alpha (if it exists and
658 /// is nonzero) before color conversion, then re-multiply by alpha after the
659 /// after the color conversion. Passing unpremult=false skips this step,
660 /// which may be desirable if you know that the image is "unassociated alpha"
661 /// (a.k.a. "not pre-multiplied colors").
663  string_view fromspace, string_view tospace, bool unpremult=true,
664  string_view context_key="", string_view context_value="",
665  ColorConfig *colorconfig=nullptr,
666  ROI roi={}, int nthreads=0);
667 bool OIIO_API colorconvert (ImageBuf &dst, const ImageBuf &src,
668  string_view fromspace, string_view tospace, bool unpremult=true,
669  string_view context_key="", string_view context_value="",
670  ColorConfig *colorconfig=nullptr,
671  ROI roi={}, int nthreads=0);
672 
673 
674 /// Return (or copy into dst) the pixels of src within the ROI, applying a
675 /// color transform specified by a 4x4 matrix. Following Imath conventions,
676 /// the color is a row vector and the matrix has the "translation" part in
677 /// elements [12..14] (matching the memory layout of OpenGL or RenderMan),
678 /// so the math is color * Matrix (NOT M*c). In-place operations (dst == src)
679 /// are supported.
680 ///
681 /// If unpremult is true, divide the RGB channels by alpha (if it exists and
682 /// is nonzero) before color conversion, then re-multiply by alpha after the
683 /// after the color conversion. Passing unpremult=false skips this step,
684 /// which may be desirable if you know that the image is "unassociated alpha"
685 /// (a.k.a. "not pre-multiplied colors").
687  const Imath::M44f& M, bool unpremult=true,
688  ROI roi={}, int nthreads=0);
689 bool OIIO_API colormatrixtransform (ImageBuf &dst, const ImageBuf &src,
690  const Imath::M44f& M, bool unpremult=true,
691  ROI roi={}, int nthreads=0);
692 
693 
694 /// Return (or copy into dst) the pixels of src within the ROI, applying an
695 /// OpenColorIO "look" transform. In-place operations (dst == src) are
696 /// supported.
697 ///
698 /// If unpremult is true, unpremultiply before color conversion, then
699 /// premultiply after the color conversion. You may want to use this
700 /// flag if your image contains an alpha channel. If inverse is true, it
701 /// will reverse the color transformation.
702 ImageBuf OIIO_API ociolook (const ImageBuf &src, string_view looks,
703  string_view fromspace, string_view tospace,
704  bool unpremult=true, bool inverse=false,
705  string_view key="", string_view value="",
706  ColorConfig *colorconfig=nullptr,
707  ROI roi={}, int nthreads=0);
708 bool OIIO_API ociolook (ImageBuf &dst, const ImageBuf &src, string_view looks,
709  string_view fromspace, string_view tospace,
710  bool unpremult=true, bool inverse=false,
711  string_view key="", string_view value="",
712  ColorConfig *colorconfig=nullptr,
713  ROI roi={}, int nthreads=0);
714 
715 /// Return (or copy into dst) the pixels of src within the ROI, applying an
716 /// OpenColorIO "look" transform. If from or looks are nullptr, it will not
717 /// override the look or source color space (subtly different than
718 /// passing "", the empty string, which means to use no look or source
719 /// space). If inverse is true, it will reverse the color transformation.
720 ///
721 /// If unpremult is true, divide the RGB channels by alpha (if it exists and
722 /// is nonzero) before color conversion, then re-multiply by alpha after the
723 /// after the color conversion. Passing unpremult=false skips this step,
724 /// which may be desirable if you know that the image is "unassociated alpha"
725 /// (a.k.a. "not pre-multiplied colors").
727  string_view display, string_view view,
728  string_view fromspace="", string_view looks="",
729  bool unpremult=true,
730  string_view key="", string_view value="",
731  ColorConfig *colorconfig=nullptr,
732  ROI roi={}, int nthreads=0);
733 bool OIIO_API ociodisplay (ImageBuf &dst, const ImageBuf &src,
734  string_view display, string_view view,
735  string_view fromspace="", string_view looks="",
736  bool unpremult=true,
737  string_view key="", string_view value="",
738  ColorConfig *colorconfig=nullptr,
739  ROI roi={}, int nthreads=0);
740 
741 /// Return (or copy into dst) the pixels of src within the ROI, applying an
742 /// OpenColorIO "file" transform. If inverse is true, it will reverse the
743 /// color transformation. In-place operations (dst == src) are supported.
744 ///
745 /// If unpremult is true, divide the RGB channels by alpha (if it exists and
746 /// is nonzero) before color conversion, then re-multiply by alpha after the
747 /// after the color conversion. Passing unpremult=false skips this step,
748 /// which may be desirable if you know that the image is "unassociated alpha"
749 /// (a.k.a. "not pre-multiplied colors").
752  bool unpremult=true, bool inverse=false,
753  ColorConfig *colorconfig=nullptr,
754  ROI roi={}, int nthreads=0);
755 bool OIIO_API ociofiletransform (ImageBuf &dst, const ImageBuf &src,
756  string_view name,
757  bool unpremult=true, bool inverse=false,
758  ColorConfig *colorconfig=nullptr,
759  ROI roi={}, int nthreads=0);
760 
761 /// Return (or copy into dst) pixels from src, and in the process divide all
762 /// color channels (those not alpha or z) by the alpha value, to "un-
763 /// premultiply" them. This presumes that the image starts of as
764 /// "associated alpha" a.k.a. "premultipled." The alterations are
765 /// restricted to the pixels and channels of the supplied ROI (which
766 /// defaults to all of src). Pixels in which the alpha channel is 0 will
767 /// not be modified (since the operation is undefined in that case). This
768 /// is just a copy if there is no identified alpha channel (and a no-op if
769 /// dst and src are the same image).
770 ImageBuf OIIO_API unpremult (const ImageBuf &src, ROI roi={}, int nthreads=0);
771 bool OIIO_API unpremult (ImageBuf &dst, const ImageBuf &src,
772  ROI roi={}, int nthreads=0);
773 
774 /// Return (or copy into dst) pixels from src, and in the process multiply
775 /// all color channels (those not alpha or z) by the alpha value, to
776 /// "premultiply" them. This presumes that the image starts off as
777 /// "unassociated alpha" a.k.a. "non-premultiplied." The alterations are
778 /// restricted to the pixels and channels of the supplied ROI (which
779 /// defaults to all of src). Pixels in which the alpha channel is 0 will not
780 /// be modified (since the operation is undefined in that case). This is
781 /// just a copy if there is no identified alpha channel (and a no-op if dst
782 /// and src are the same image).
783 ImageBuf OIIO_API premult (const ImageBuf &src, ROI roi={}, int nthreads=0);
784 bool OIIO_API premult (ImageBuf &dst, const ImageBuf &src,
785  ROI roi={}, int nthreads=0);
786 
787 
788 /// Return (or copy into dst) pixel values determined by looking up a color
789 /// map using values of the source image, using either the channel specified
790 /// by srcchannel, or the luminance of src's RGB if srcchannel is -1. This
791 /// happens for all pixels within the ROI (which defaults to all of src),
792 /// and if dst is not already initialized, it will be initialized to the ROI
793 /// and with color channels equal to channels.
794 ///
795 /// The knots of the interpolated map are given by knots[nknots*channels].
796 /// An input value of 0.0 corresponds to knots[0..channels-1], an input
797 /// value of 1.0 corresponds ot knots[(nknots-1)*channels..knots.size()-1].
798 ImageBuf OIIO_API color_map (const ImageBuf &src, int srcchannel,
799  int nknots, int channels, cspan<float> knots,
800  ROI roi={}, int nthreads=0);
801 bool OIIO_API color_map (ImageBuf &dst, const ImageBuf &src, int srcchannel,
802  int nknots, int channels, cspan<float> knots,
803  ROI roi={}, int nthreads=0);
804 
805 /// Return (or copy into dst) pixel values determined by looking up a color
806 /// map using values of the source image, using either the channel specified
807 /// by srcchannel, or the luminance of src's RGB if srcchannel is -1. This
808 /// happens for all pixels within the ROI (which defaults to all of src),
809 /// and if dst is not already initialized, it will be initialized to the ROI
810 /// and with 3 color channels.
811 ///
812 /// The mapname may be one of: "inferno", "viridis", "magma", or "plasma",
813 /// all of which are perceptually uniform, strictly increasing in luminance,
814 /// look good when converted to grayscale, and work for people with all
815 /// types of colorblindness. Also supported are the following color maps
816 /// that do not having those desirable qualities (and are thus not
817 /// recommended): "blue-red", "spectrum", "heat".
818 ///
819 /// Return true on successs, false on error (with an appropriate error
820 /// message set in dst).
821 ImageBuf OIIO_API color_map (const ImageBuf &src, int srcchannel,
822  string_view mapname, ROI roi={}, int nthreads=0);
823 bool OIIO_API color_map (ImageBuf &dst, const ImageBuf &src, int srcchannel,
824  string_view mapname, ROI roi={}, int nthreads=0);
825 
826 
827 
828 /// Remap contrast by transforming values [black, white] to new range
829 /// [min, max], either linearly or with optional application of a smooth
830 /// sigmoidal remapping (if scontrast != 1.0).
831 ///
832 /// The following steps are performed, in order:
833 /// 1. Linearly rescale values [black, white] to [0, 1].
834 /// 2. If scontrast != 1, apply a sigmoidal remapping where a larger
835 /// scontrast value makes a steeper slope, and the steepest part is at
836 /// value sthresh (relative to the new remapped value after steps 1 & 2;
837 /// the default is 0.5).
838 /// 3. Rescale the range of that result: 0.0 -> min and 1.0 -> max.
839 ///
840 /// Values outside of the [black,white] range will be extrapolated to
841 /// outside [min,max], so it may be prudent to apply a clamp() to the
842 /// results.
843 ///
844 /// The black, white, min, max, scontrast, sthresh parameters may each
845 /// either be a single float value for all channels, or a span giving
846 /// per-channel values.
847 ///
848 /// You can use this function for a simple linear contrast remapping of
849 /// [black, white] to [min, max] if you use the default values for sthresh.
850 /// Or just a simple sigmoidal contrast stretch within the [0,1] range if
851 /// you leave all other parameters at their defaults, or a combination of
852 /// these effects. Note that if black == white, the result will be a simple
853 /// binary thresholding where values < black map to min and values >= bkack
854 /// map to max.
856  cspan<float> black=0.0f, cspan<float> white=1.0f,
858  cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f,
859  ROI={}, int nthreads=0);
860 OIIO_API bool contrast_remap (ImageBuf &dst, const ImageBuf &src,
861  cspan<float> black=0.0f, cspan<float> white=1.0f,
863  cspan<float> scontrast=1.0f, cspan<float> sthresh=0.5f,
864  ROI={}, int nthreads=0);
865 
866 
867 
868 
870  std::vector<float> min;
871  std::vector<float> max;
872  std::vector<float> avg;
873  std::vector<float> stddev;
874  std::vector<imagesize_t> nancount;
875  std::vector<imagesize_t> infcount;
876  std::vector<imagesize_t> finitecount;
877  std::vector<double> sum, sum2; // for intermediate calculation
878 
880  PixelStats (PixelStats&& other) = default;
881  PixelStats (int nchannels) { reset(nchannels); }
882  void reset (int nchannels);
883  void merge (const PixelStats &p);
884  const PixelStats& operator= (PixelStats&& other); // Move assignment
885 };
886 
887 
888 /// Compute statistics about the ROI of the src image, returning a
889 /// PixelStats structure. Upon success, the returned vectors in the result
890 /// structure will have size == src.nchannels(). If there is a failure, the
891 /// vector sizes will be 0 and an error will be set in src.
892 PixelStats OIIO_API computePixelStats (const ImageBuf &src,
893  ROI roi={}, int nthreads=0);
894 
895 // DEPRECATED(1.9): with C++11 move semantics, there's no reason why
896 // stats needs to be passed as a parameter instead of returned.
897 bool OIIO_API computePixelStats (PixelStats &stats, const ImageBuf &src,
898  ROI roi={}, int nthreads=0);
899 
900 
901 /// Struct holding all the results computed by ImageBufAlgo::compare().
902 /// (maxx,maxy,maxz,maxc) gives the pixel coordintes (x,y,z) and color
903 /// channel of the pixel that differed maximally between the two images.
904 /// nwarn and nfail are the number of "warnings" and "failures",
905 /// respectively.
908  int maxx, maxy, maxz, maxc;
910  bool error;
911 };
912 
913 /// Numerically compare two images. The difference threshold (for any
914 /// individual color channel in any pixel) for a "failure" is
915 /// failthresh, and for a "warning" is warnthresh. The results are
916 /// stored in result. If roi is defined, pixels will be compared for
917 /// the pixel and channel range that is specified. If roi is not
918 /// defined, the comparison will be for all channels, on the union of
919 /// the defined pixel windows of the two images (for either image,
920 /// undefined pixels will be assumed to be black).
921 CompareResults OIIO_API compare (const ImageBuf &A, const ImageBuf &B,
922  float failthresh, float warnthresh,
923  ROI roi={}, int nthreads=0);
924 
925 // DEPRECATED(1.9): with C++11 move semantics, there's no reason why
926 // result needs to be passed as a parameter instead of returned.
927 bool OIIO_API compare (const ImageBuf &A, const ImageBuf &B,
928  float failthresh, float warnthresh,
929  CompareResults &result, ROI roi={}, int nthreads=0);
930 
931 /// Compare two images using Hector Yee's perceptual metric, returning
932 /// the number of pixels that fail the comparison. Only the first three
933 /// channels (or first three channels specified by roi) are compared.
934 /// Free parameters are the ambient luminance in the room and the field
935 /// of view of the image display; our defaults are probably reasonable
936 /// guesses for an office environment. The 'result' structure will
937 /// store the maxerror, and the maxx, maxy, maxz of the pixel that
938 /// failed most severely. (The other fields of the CompareResults
939 /// are not used for Yee comparison.)
940 ///
941 /// Works for all pixel types. But it's basically meaningless if the
942 /// first three channels aren't RGB in a linear color space that sort
943 /// of resembles AdobeRGB.
944 ///
945 /// Return true on success, false on error.
946 int OIIO_API compare_Yee (const ImageBuf &A, const ImageBuf &B,
947  CompareResults &result,
948  float luminance = 100, float fov = 45,
949  ROI roi={}, int nthreads=0);
950 
951 
952 /// Do all pixels within the ROI have the same values for channels
953 /// [roi.chbegin..roi.chend-1], within a tolerance of +/- threshold? If so,
954 /// return true and store that color in color[chbegin...chend-1] (if color
955 /// is not empty); otherwise return false. If roi is not defined (the
956 /// default), it will be understood to be all of the defined pixels and
957 /// channels of source.
958 OIIO_API bool isConstantColor (const ImageBuf &src, float threshold=0.0f,
959  span<float> color = {},
960  ROI roi={}, int nthreads=0);
961 inline bool isConstantColor (const ImageBuf &src, span<float> color,
962  ROI roi={}, int nthreads=0) {
963  return isConstantColor (src, 0.0f, color, roi, nthreads);
964 }
965 
966 /// Does the requested channel have a given value (within a tolerance of +/-
967 /// threshold) for every channel within the ROI? (For this function, the
968 /// ROI's chbegin/chend are ignored.) Return true if so, otherwise return
969 /// false. If roi is not defined (the default), it will be understood to be
970 /// all of the defined pixels and channels of source.
971 OIIO_API bool isConstantChannel (const ImageBuf &src, int channel,
972  float val, float threshold=0.0f,
973  ROI roi={}, int nthreads=0);
974 inline bool isConstantChannel (const ImageBuf &src, int channel, float val,
975  ROI roi, int nthreads=0) {
976  return isConstantChannel (src, channel, val, 0.0f, roi, nthreads);
977 }
978 
979 /// Is the image monochrome within the ROI, i.e., for every pixel within the
980 /// region, do all channels [roi.chbegin, roi.chend) have the same value
981 /// (within a tolerance of +/- threshold)? If roi is not defined (the
982 /// default), it will be understood to be all of the defined pixels and
983 /// channels of source.
984 OIIO_API bool isMonochrome (const ImageBuf &src, float threshold=0.0f,
985  ROI roi={}, int nthreads=0);
986 inline bool isMonochrome (const ImageBuf &src, ROI roi, int nthreads=0) {
987  return isMonochrome (src, 0.0f, roi, nthreads);
988 }
989 
990 /// Count how many pixels in the ROI match a list of colors.
991 ///
992 /// The colors to match are in colors[0..nchans-1],
993 /// colors[nchans..2*nchans-1], and so on, a total of ncolors
994 /// consecutive colors of nchans each.
995 ///
996 /// eps[0..nchans-1] are the error tolerances for a match, for each channel.
997 /// Setting eps[c] = numeric_limits<float>::max() will effectively make it
998 /// ignore the channel. The default eps is 0.001 for all channels (requires
999 /// exact matches for 8 bit images, but allows a wee bit of imprecision for
1000 /// float images.
1001 ///
1002 /// Upon success, return true and store the number of pixels that matched
1003 /// each color count[..ncolors-1]. If there is an error, returns false and
1004 /// sets an appropriate error message set in src.
1005 bool OIIO_API color_count (const ImageBuf &src, imagesize_t *count,
1006  int ncolors, cspan<float> color,
1007  cspan<float> eps = 0.001f,
1008  ROI roi={}, int nthreads=0);
1009 
1010 /// Count how many pixels in the ROI are outside the value range.
1011 /// low[0..nchans-1] and high[0..nchans-1] are the low and high
1012 /// acceptable values for each color channel.
1013 ///
1014 /// The number of pixels containing values that fall below the lower
1015 /// bound will be stored in *lowcount, the number of pixels containing
1016 /// values that fall above the upper bound will be stored in *highcount,
1017 /// and the number of pixels for which all channels fell within the
1018 /// bounds will be stored in *inrangecount. Any of these may be NULL,
1019 /// which simply means that the counts need not be collected or stored.
1020 ///
1021 /// Return true if the operation can be performed, false if there is
1022 /// some sort of error (and sets an appropriate error message in src).
1023 bool OIIO_API color_range_check (const ImageBuf &src,
1024  imagesize_t *lowcount,
1025  imagesize_t *highcount,
1026  imagesize_t *inrangecount,
1027  cspan<float> low, cspan<float> high,
1028  ROI roi={}, int nthreads=0);
1029 
1030 /// Find the minimal rectangular region within roi (which defaults to
1031 /// the entire pixel data window of src) that consists of nonzero pixel
1032 /// values. In other words, gives the region that is a "shrink-wraps"
1033 /// of src to exclude black border pixels. Note that if the entire
1034 /// image was black, the ROI returned will contain no pixels.
1035 ///
1036 /// For "deep" images, this function returns the smallest ROI that contains
1037 /// all pixels that contain depth samples, and excludes the border pixels
1038 /// that contain no depth samples at all.
1039 OIIO_API ROI nonzero_region (const ImageBuf &src, ROI roi={}, int nthreads=0);
1040 
1041 /// Compute the SHA-1 byte hash for all the pixels in the specifed
1042 /// region of the image. If blocksize > 0, the function will compute
1043 /// separate SHA-1 hashes of each 'blocksize' batch of scanlines, then
1044 /// return a hash of the individual hashes. This is just as strong a
1045 /// hash, but will NOT match a single hash of the entire image
1046 /// (blocksize==0). But by breaking up the hash into independent
1047 /// blocks, we can parallelize across multiple threads, given by
1048 /// nthreads (if nthreads is 0, it will use the global OIIO thread
1049 /// count). The 'extrainfo' provides additional text that will be
1050 /// incorporated into the hash.
1052  string_view extrainfo = "",
1053  ROI roi={},
1054  int blocksize = 0, int nthreads=0);
1055 
1056 
1057 /// Warp the src image using the supplied 3x3 transformation matrix.
1058 ///
1059 /// Only the pixels (and channels) of dst that are specified by roi will be
1060 /// copied from the warped src; the default roi is to alter all the pixels
1061 /// in dst. If dst is uninitialized, it will be sized to be an ImageBuf
1062 /// large enough to hold the warped image if recompute_roi is true, or
1063 /// will have the same ROI as src if recompute_roi is false. It is an error
1064 /// to pass both an uninitialied dst and an undefined roi.
1065 ///
1066 /// The filter is used to weight the src pixels falling underneath it for
1067 /// each dst pixel. The caller may specify a reconstruction filter by name
1068 /// and width (expressed in pixels unts of the dst image), or rotate() will
1069 /// choose a reasonable default high-quality default filter (lanczos3) if
1070 /// the empty string is passed, and a reasonable filter width if filterwidth
1071 /// is 0. (Note that some filter choices only make sense with particular
1072 /// width, in which case this filterwidth parameter may be ignored.)
1073 ///
1074 ImageBuf OIIO_API warp (const ImageBuf &src, const Imath::M33f &M,
1075  string_view filtername = string_view(),
1076  float filterwidth = 0.0f, bool recompute_roi = false,
1078  ROI roi={}, int nthreads=0);
1079 ImageBuf OIIO_API warp (const ImageBuf &src, const Imath::M33f &M,
1080  const Filter2D *filter, bool recompute_roi = false,
1082  ROI roi = {}, int nthreads=0);
1083 bool OIIO_API warp (ImageBuf &dst, const ImageBuf &src, const Imath::M33f &M,
1084  string_view filtername = string_view(),
1085  float filterwidth = 0.0f, bool recompute_roi = false,
1087  ROI roi={}, int nthreads=0);
1088 bool OIIO_API warp (ImageBuf &dst, const ImageBuf &src, const Imath::M33f &M,
1089  const Filter2D *filter, bool recompute_roi = false,
1091  ROI roi = {}, int nthreads=0);
1092 
1093 
1094 /// Rotate the src image by the angle (in radians, with positive angles
1095 /// clockwise). When center_x and center_y are supplied, they denote the
1096 /// center of rotation; in their absence, the rotation will be about the
1097 /// center of the image's display window.
1098 ///
1099 /// Only the pixels (and channels) of dst that are specified by roi will be
1100 /// copied from the rotated src; the default roi is to alter all the pixels
1101 /// in dst. If dst is uninitialized, it will be resized to be an ImageBuf
1102 /// large enough to hold the rotated image if recompute_roi is true, or will
1103 /// have the same ROI as src if recompute_roi is false. It is an error to
1104 /// pass both an uninitialied dst and an undefined roi.
1105 ///
1106 /// The filter is used to weight the src pixels falling underneath it for
1107 /// each dst pixel. The caller may specify a reconstruction filter by name
1108 /// and width (expressed in pixels unts of the dst image), or rotate() will
1109 /// choose a reasonable default high-quality default filter (lanczos3) if
1110 /// the empty string is passed, and a reasonable filter width if filterwidth
1111 /// is 0. (Note that some filter choices only make sense with particular
1112 /// width, in which case this filterwidth parameter may be ignored.)
1113 ImageBuf OIIO_API rotate (const ImageBuf &src, float angle,
1114  string_view filtername = string_view(),
1115  float filterwidth = 0.0f, bool recompute_roi = false,
1116  ROI roi={}, int nthreads=0);
1117 ImageBuf OIIO_API rotate (const ImageBuf &src, float angle,
1118  Filter2D *filter, bool recompute_roi = false,
1119  ROI roi={}, int nthreads=0);
1120 ImageBuf OIIO_API rotate (const ImageBuf &src,
1121  float angle, float center_x, float center_y,
1122  string_view filtername = string_view(),
1123  float filterwidth = 0.0f, bool recompute_roi = false,
1124  ROI roi={}, int nthreads=0);
1125 ImageBuf OIIO_API rotate (const ImageBuf &src,
1126  float angle, float center_x, float center_y,
1127  Filter2D *filter, bool recompute_roi = false,
1128  ROI roi={}, int nthreads=0);
1129 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src, float angle,
1130  string_view filtername = string_view(),
1131  float filterwidth = 0.0f, bool recompute_roi = false,
1132  ROI roi={}, int nthreads=0);
1133 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src, float angle,
1134  Filter2D *filter, bool recompute_roi = false,
1135  ROI roi={}, int nthreads=0);
1136 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src,
1137  float angle, float center_x, float center_y,
1138  string_view filtername = string_view(),
1139  float filterwidth = 0.0f, bool recompute_roi = false,
1140  ROI roi={}, int nthreads=0);
1141 bool OIIO_API rotate (ImageBuf &dst, const ImageBuf &src,
1142  float angle, float center_x, float center_y,
1143  Filter2D *filter, bool recompute_roi = false,
1144  ROI roi={}, int nthreads=0);
1145 
1146 
1147 /// Set dst, over the region of interest, to be a resized version of the
1148 /// corresponding portion of src (mapping such that the "full" image
1149 /// window of each correspond to each other, regardless of resolution).
1150 ///
1151 /// The filter is used to weight the src pixels falling underneath it for
1152 /// each dst pixel. The caller may specify a reconstruction filter
1153 /// explicitly by passing a `Filter2D*`, or by name and width (expressed in
1154 /// pixels unts of the dst image), or resize() will choose a reasonable
1155 /// default high-quality default filter (blackman-harris when upsizing,
1156 /// lanczos3 when downsizing) if the empty string is passed or if
1157 /// filterwidth is 0.
1158 ///
1159 ImageBuf OIIO_API resize (const ImageBuf &src,
1160  string_view filtername = "", float filterwidth=0.0f,
1161  ROI roi={}, int nthreads=0);
1162 bool OIIO_API resize (ImageBuf &dst, const ImageBuf &src,
1163  string_view filtername = "", float filterwidth=0.0f,
1164  ROI roi={}, int nthreads=0);
1165 ImageBuf OIIO_API resize (const ImageBuf &src, Filter2D *filter,
1166  ROI roi={}, int nthreads=0);
1167 bool OIIO_API resize (ImageBuf &dst, const ImageBuf &src, Filter2D *filter,
1168  ROI roi={}, int nthreads=0);
1169 
1170 
1171 /// Set dst, over the region of interest, to be a resampled version of the
1172 /// corresponding portion of src (mapping such that the "full" image
1173 /// window of each correspond to each other, regardless of resolution).
1174 ///
1175 /// Unlike ImageBufAlgo::resize(), resample does not take a filter; it
1176 /// just samples either with a bilinear interpolation (if interpolate is
1177 /// true, the default) or uses the single "closest" pixel (if
1178 /// interpolate is false). This makes it a lot faster than a proper
1179 /// resize(), though obviously with lower quality (aliasing when
1180 /// downsizing, pixel replication when upsizing).
1181 ImageBuf OIIO_API resample (const ImageBuf &src, bool interpolate = true,
1182  ROI roi={}, int nthreads=0);
1183 bool OIIO_API resample (ImageBuf &dst, const ImageBuf &src,
1184  bool interpolate = true, ROI roi={}, int nthreads=0);
1185 
1186 
1187 /// Fit src into dst (to a size specified by roi, if dst is not
1188 /// initialized), resizing but preserving its original aspect ratio. Thus,
1189 /// it will resize so be the largest size with the same aspect ratio that
1190 /// can fix inside the region, but will not stretch to completely fill it in
1191 /// both dimensions.
1192 ///
1193 /// If `exact` is true, will result in an exact match on aspect ratio and
1194 /// centering (partial pixel shift if necessary), whereas exact=false
1195 /// will only preserve aspect ratio and centering to the precision of a
1196 /// whole pixel.
1197 ///
1198 /// The filter is used to weight the src pixels falling underneath it for
1199 /// each dst pixel. The caller may specify a reconstruction filter
1200 /// explicitly by passing a `Filter2D*`, or by name and width (expressed in
1201 /// pixels unts of the dst image), or resize() will choose a reasonable
1202 /// default high-quality default filter (blackman-harris when upsizing,
1203 /// lanczos3 when downsizing) if the empty string is passed or if
1204 /// filterwidth is 0.
1205 ///
1206 ImageBuf OIIO_API fit (const ImageBuf &src,
1207  string_view filtername = "", float filterwidth=0.0f,
1208  bool exact=false, ROI roi={}, int nthreads=0);
1209 bool OIIO_API fit (ImageBuf &dst, const ImageBuf &src,
1210  string_view filtername = "", float filterwidth=0.0f,
1211  bool exact=false, ROI roi={}, int nthreads=0);
1212 ImageBuf OIIO_API fit (const ImageBuf &src, Filter2D *filter,
1213  bool exact=false, ROI roi={}, int nthreads=0);
1214 bool OIIO_API fit (ImageBuf &dst, const ImageBuf &src, Filter2D *filter,
1215  bool exact=false, ROI roi={}, int nthreads=0);
1216 
1217 /// Return (or store into the ROI of dst) the convolution of src and a
1218 /// kernel. If roi is not defined, it defaults to the full size of dst (or
1219 /// src, if dst was uninitialized). If dst is uninitialized, it will be
1220 /// allocated to be the size specified by roi. If normalized is true, the
1221 /// kernel will be normalized for the convolution, otherwise the original
1222 /// values will be used.
1223 ImageBuf OIIO_API convolve (const ImageBuf &src, const ImageBuf &kernel,
1224  bool normalize = true, ROI roi={}, int nthreads=0);
1225 bool OIIO_API convolve (ImageBuf &dst, const ImageBuf &src, const ImageBuf &kernel,
1226  bool normalize = true, ROI roi={}, int nthreads=0);
1227 
1228 /// Make a 1-channel FLOAT image of the named kernel. The size of the image
1229 /// will be big enough to contain the kernel given its size (width x height)
1230 /// and rounded up to odd resolution so that the center of the kernel can be
1231 /// at the center of the middle pixel. The kernel image will be offset so
1232 /// that its center is at the (0,0) coordinate. If normalize is true, the
1233 /// values will be normalized so that they sum to 1.0. If depth > 1, a
1234 /// volumetric kernel will be created. Use with caution!
1235 ///
1236 /// Kernel names can be: "gaussian", "sharp-gaussian", "box",
1237 /// "triangle", "blackman-harris", "mitchell", "b-spline", "catmull-rom",
1238 /// "lanczos3", "disk", "binomial", "laplacian".
1239 ///
1240 /// Note that "catmull-rom" and "lanczos3" are fixed-size kernels that
1241 /// don't scale with the width, and are therefore probably less useful
1242 /// in most cases.
1243 ///
1244 ImageBuf OIIO_API make_kernel (string_view name, float width, float height,
1245  float depth = 1.0f, bool normalize = true);
1246 // DEPRECATED(1.9):
1247 inline bool make_kernel (ImageBuf &dst, string_view name,
1248  float width, float height, float depth = 1.0f,
1249  bool normalize = true) {
1250  dst = make_kernel (name, width, height, depth, normalize);
1251  return ! dst.has_error();
1252 }
1253 
1254 
1255 /// Return (or copy into dst) a sharpened version of the corresponding
1256 /// region of src using the ``unsharp mask'' technique. Unsharp masking
1257 /// basically works by first blurring the image (low pass filter),
1258 /// subtracting this from the original image, then adding the residual back
1259 /// to the original to emphasize the edges. Roughly speaking,
1260 ///
1261 /// dst = src + contrast * thresh(src - blur(src))
1262 ///
1263 /// The specific blur can be selected by kernel name and width. The
1264 /// contrast is a multiplier on the overall sharpening effect. The
1265 /// thresholding step causes all differences less than 'threshold' to be
1266 /// squashed to zero, which can be useful for suppressing sharpening of
1267 /// low-contrast details (like noise) but allow sharpening of
1268 /// higher-contrast edges.
1270  string_view kernel="gaussian", float width = 3.0f,
1271  float contrast = 1.0f, float threshold = 0.0f,
1272  ROI roi={}, int nthreads=0);
1273 bool OIIO_API unsharp_mask (ImageBuf &dst, const ImageBuf &src,
1274  string_view kernel="gaussian", float width = 3.0f,
1275  float contrast = 1.0f, float threshold = 0.0f,
1276  ROI roi={}, int nthreads=0);
1277 
1278 
1279 /// Return (or copy into dst) the Laplacian of the corresponding region of
1280 /// src. The Laplacian is the generalized second derivative of the image
1281 /// $$\frac{\partial^2 s}{\partial x^2} + \frac{\partial^2 s}{\partial y^2}$$
1282 /// which is approximated by convolving the image with a discrete 3x3
1283 /// Laplacian kernel,
1284 /// [ 0 1 0 ]
1285 /// [ 1 -4 1 ]
1286 /// [ 0 1 0 ]
1287 ///
1288 ImageBuf OIIO_API laplacian (const ImageBuf &src, ROI roi={}, int nthreads=0);
1289 bool OIIO_API laplacian (ImageBuf &dst, const ImageBuf &src,
1290  ROI roi={}, int nthreads=0);
1291 
1292 
1293 /// Return (or copy into dst) a median-filtered version of the corresponding
1294 /// region of src. The size of the window over which the median is computed
1295 /// is given by width and height (if height is <= 0, it will be set to
1296 /// width, making a square filter).
1297 ///
1298 /// Median filters are good for removing high-frequency detail smaller than
1299 /// the window size (including noise), without blurring edges that are
1300 /// larger than the window size.
1302  int width = 3, int height = -1,
1303  ROI roi={}, int nthreads=0);
1304 bool OIIO_API median_filter (ImageBuf &dst, const ImageBuf &src,
1305  int width = 3, int height = -1,
1306  ROI roi={}, int nthreads=0);
1307 
1308 
1309 /// Return (or copy into dst) a dilated version of the corresponding region
1310 /// of src. Dilation is defined as the maximum value of all pixels under
1311 /// nonzero values of the structuring element (which is taken to be a width
1312 /// x height square). If height is not set, it will default to be the same
1313 /// as width. Dilation makes bright features wider and more prominent, dark
1314 /// features thinner, and removes small isolated dark spots.
1315 ImageBuf OIIO_API dilate (const ImageBuf &src, int width=3, int height=-1,
1316  ROI roi={}, int nthreads=0);
1317 bool OIIO_API dilate (ImageBuf &dst, const ImageBuf &src,
1318  int width=3, int height=-1, ROI roi={}, int nthreads=0);
1319 
1320 
1321 /// Return (or copy into dst) an eroded version of the corresponding region
1322 /// of src. Erosion is defined as the minimum value of all pixels under
1323 /// nonzero values of the structuring element (which is taken to be a width
1324 /// x height square). If height is not set, it will default to be the same
1325 /// as width. Erosion makes dark features wider, bright features thinner,
1326 /// and removes small isolated bright spots.
1327 ImageBuf OIIO_API erode (const ImageBuf &src, int width=3, int height=-1,
1328  ROI roi={}, int nthreads=0);
1329 bool OIIO_API erode (ImageBuf &dst, const ImageBuf &src,
1330  int width=3, int height=-1, ROI roi={}, int nthreads=0);
1331 
1332 
1333 /// Return (or copy into dst) the discrete Fourier transform (DFT) of the
1334 /// section of src denoted by roi, If roi is not defined, it will be all of
1335 /// src's pixels. Only one channel of src may be FFT'd at a time, so it
1336 /// will be the first channel described by roi (or, again, channel 0 if roi
1337 /// is undefined). If not already in the correct format, dst will be re-
1338 /// allocated to be a 2-channel float buffer of size width x height, with
1339 /// channel 0 being the "real" part and channel 1 being the the "imaginary"
1340 /// part. The values returned are actually the unitary DFT, meaning that it
1341 /// is scaled by 1/sqrt(npixels).
1342 ///
1343 /// Works on all pixel data type for src; dst will always be reallocated
1344 /// as FLOAT.
1345 ImageBuf OIIO_API fft (const ImageBuf &src, ROI roi={}, int nthreads=0);
1346 bool OIIO_API fft (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
1347 
1348 /// Return (or copy into dst) the inverse discrete Fourier transform of the
1349 /// section of src denoted by roi. If roi is not defined, it will be all of
1350 /// src's pixels.
1351 ///
1352 /// Src MUST be a 2-channel float image, and is assumed to be a complex
1353 /// frequency-domain signal with the "real" component in channel 0 and
1354 /// the "imaginary" component in channel 1. Dst will end up being a
1355 /// float image of one channel (the real component is kept, the
1356 /// imaginary component of the spatial-domain will be discarded).
1357 /// Just as with fft(), the ifft() function is dealing with the unitary
1358 /// DFT, so it is scaled by 1/sqrt(npixels).
1359 ///
1360 ImageBuf OIIO_API ifft (const ImageBuf &src, ROI roi={}, int nthreads=0);
1361 bool OIIO_API ifft (ImageBuf &dst, const ImageBuf &src, ROI roi={}, int nthreads=0);
1362 
1363 
1364 /// Convert a 2-channel image with "polar" values (amplitude, phase)
1365 /// into a 2-channel image with complex values (real, imaginary).
1366 ///
1367 /// The transformation between the two representations are:
1368 /// real = amplitude * cos(phase);
1369 /// imag = amplitude * sin(phase);
1370 ///
1372  ROI roi={}, int nthreads=0);
1373 bool OIIO_API polar_to_complex (ImageBuf &dst, const ImageBuf &src,
1374  ROI roi={}, int nthreads=0);
1375 
1376 /// Convert a 2-channel image with complex values (real, imaginary) into a
1377 /// 2-channel image with "polar" values (amplitude, phase).
1378 ///
1379 /// The transformation between the two representations are:
1380 /// amplitude = hypot (real, imag);
1381 /// phase = atan2 (imag, real);
1382 ///
1384  ROI roi={}, int nthreads=0);
1385 bool OIIO_API complex_to_polar (ImageBuf &dst, const ImageBuf &src,
1386  ROI roi={}, int nthreads=0);
1387 
1388 
1389 enum OIIO_API NonFiniteFixMode
1390 {
1391  NONFINITE_NONE = 0, ///< Do nothing
1392  NONFINITE_BLACK = 1, ///< Replace nonfinite pixels with black
1393  NONFINITE_BOX3 = 2, ///< Replace nonfinite pixels with 3x3 finite average
1394  NONFINITE_ERROR = 100, ///< Error if any nonfinite pixels are found
1395 };
1396 
1397 /// Return (or copy into dst) a the values of src (within the ROI), while
1398 /// repairing any non-finite (NaN/Inf) pixels. If pixelsFixed is not
1399 /// nullptr, store in it the number of pixels that contained non-finite
1400 /// value. It is permissible to operate in-place (with src and dst
1401 /// referring to the same image).
1402 ///
1403 /// How the non-finite values are repaired is specified by one of the
1404 /// following modes:
1405 /// NONFINITE_NONE do not alter the pixels (but do count the number
1406 /// of nonfinite pixels in *pixelsFixed, if non-null).
1407 /// NONFINITE_BLACK change non-finite values to 0.
1408 /// NONFINITE_BOX3 replace non-finite values by the average of any
1409 /// finite pixels within a 3x3 window.
1410 /// NONFINITE_ERROR return false (error), but don't change any values,
1411 /// if any nonfinite values are found.
1412 ///
1413 /// Works on all pixel data types, though it's just a copy for images with
1414 /// pixel data types that cannot represent NaN or Inf values.
1415 ///
1417  NonFiniteFixMode mode=NONFINITE_BOX3,
1418  int *pixelsFixed = nullptr,
1419  ROI roi={}, int nthreads=0);
1420 bool OIIO_API fixNonFinite (ImageBuf &dst, const ImageBuf &src,
1421  NonFiniteFixMode mode=NONFINITE_BOX3,
1422  int *pixelsFixed = nullptr,
1423  ROI roi={}, int nthreads=0);
1424 
1425 
1426 /// Fill the holes using a push-pull technique. The src image must have
1427 /// an alpha channel. The dst image will end up with a copy of src, but
1428 /// will have an alpha of 1.0 everywhere, and any place where the alpha
1429 /// of src was < 1, dst will have a pixel color that is a plausible
1430 /// "filling" of the original alpha hole.
1432  ROI roi={}, int nthreads=0);
1433 bool OIIO_API fillholes_pushpull (ImageBuf &dst, const ImageBuf &src,
1434  ROI roi={}, int nthreads=0);
1435 
1436 
1437 /// Convert an OpenCV cv::Mat into an ImageBuf, copying the pixels
1438 /// (optionally converting to the pixel data type specified by `convert`, if
1439 /// not UNKNOWN, which means to preserve the original data type if
1440 /// possible). Return true if ok, false if it couldn't figure out how to
1441 /// make the conversion from Mat to ImageBuf. If OpenImageIO was compiled
1442 /// without OpenCV support, this function will return an empty image with
1443 /// error message set.
1445 from_OpenCV (const cv::Mat& mat, TypeDesc convert = TypeUnknown,
1446  ROI roi={}, int nthreads=0);
1447 
1448 /// Construct an OpenCV cv::Mat containing the contents of ImageBuf src, and
1449 /// return true. If it is not possible, or if OpenImageIO was compiled
1450 /// without OpenCV support, then return false. Note that OpenCV only
1451 /// supports up to 4 channels, so >4 channel images will be truncated in the
1452 /// conversion.
1453 OIIO_API bool to_OpenCV (cv::Mat& dst, const ImageBuf& src,
1454  ROI roi={}, int nthreads=0);
1455 
1456 /// Capture a still image from a designated camera. If able to do so,
1457 /// store the image in dst and return true. If there is no such device,
1458 /// or support for camera capture is not available (such as if OpenCV
1459 /// support was not enabled at compile time), return false and do not
1460 /// alter dst.
1461 ImageBuf OIIO_API capture_image (int cameranum = 0,
1462  TypeDesc convert=TypeUnknown);
1463 // DEPRECATED(1.9):
1464 inline bool capture_image (ImageBuf &dst, int cameranum = 0,
1465  TypeDesc convert=TypeUnknown) {
1466  dst = capture_image (cameranum, convert);
1467  return !dst.has_error();
1468 }
1469 
1470 /// Convert an IplImage, used by OpenCV and Intel's Image Libray, into an
1471 /// ImageBuf (copying the pixels). If convert is not set to UNKNOWN,
1472 /// convert the IplImage to that data type. Return true if ok, false if it
1473 /// couldn't figure out how to make the conversion from IplImage to
1474 /// ImageBuf. If OpenImageIO was compiled without OpenCV support, this
1475 /// function will return an empty image with error message set.
1476 ///
1477 /// DEPRECATED(2.0). The OpenCV 1.x era IplImage-based functions should be
1478 /// avoided, giving preference to from_OpenCV.
1479 ImageBuf OIIO_API from_IplImage (const IplImage *ipl,
1480  TypeDesc convert=TypeUnknown);
1481 // DEPRECATED(1.9):
1482 inline bool from_IplImage (ImageBuf &dst, const IplImage *ipl,
1483  TypeDesc convert=TypeUnknown) {
1484  dst = from_IplImage (ipl, convert);
1485  return ! dst.has_error();
1486 }
1487 
1488 /// Construct an IplImage*, used by OpenCV and Intel's Image Library, that
1489 /// is equivalent to the ImageBuf src. If it is not possible, or if
1490 /// OpenImageIO was compiled without OpenCV support, then return nullptr.
1491 /// The ownership of the IplImage is fully transferred to the calling
1492 /// application.
1493 ///
1494 /// DEPRECATED(2.0). The OpenCV 1.x era IplImage-based functions should be
1495 /// avoided, giving preference to from_OpenCV.
1496 OIIO_API IplImage* to_IplImage (const ImageBuf &src);
1497 
1498 
1499 
1500 
1501 /// Return (or copy into dst) the composite of A over B using the
1502 /// Porter/Duff definition of "over", returning true upon success and false
1503 /// for any of a variety of failures (as described below).
1504 ///
1505 /// A and B (and dst, if already defined/allocated) must have valid alpha
1506 /// channels identified by their ImageSpec alpha_channel field. If A or
1507 /// B do not have alpha channels (as determined by those rules) or if
1508 /// the number of non-alpha channels do not match between A and B,
1509 /// over() will fail, returning false.
1510 ///
1511 /// If dst is not already an initialized ImageBuf, it will be sized to
1512 /// encompass the minimal rectangular pixel region containing the union
1513 /// of the defined pixels of A and B, and with a number of channels
1514 /// equal to the number of non-alpha channels of A and B, plus an alpha
1515 /// channel. However, if dst is already initialized, it will not be
1516 /// resized, and the "over" operation will apply to its existing pixel
1517 /// data window. In this case, dst must have an alpha channel designated
1518 /// and must have the same number of non-alpha channels as A and B,
1519 /// otherwise it will fail, returning false.
1520 ///
1521 /// A, B, and dst need not perfectly overlap in their pixel data windows;
1522 /// pixel values of A or B that are outside their respective pixel data
1523 /// window will be treated as having "zero" (0,0,0...) value.
1524 ImageBuf OIIO_API over (const ImageBuf &A, const ImageBuf &B,
1525  ROI roi={}, int nthreads=0);
1526 bool OIIO_API over (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
1527  ROI roi={}, int nthreads=0);
1528 
1529 
1530 /// Just like ImageBufAlgo::over(), but inputs A and B must have
1531 /// designated 'z' channels, and on a pixel-by-pixel basis, the z values
1532 /// will determine which of A or B will be considered the foreground or
1533 /// background (lower z is foreground). If z_zeroisinf is true, then
1534 /// z=0 values will be treated as if they are infinitely far away.
1535 ImageBuf OIIO_API zover (const ImageBuf &A, const ImageBuf &B,
1536  bool z_zeroisinf=false, ROI roi={}, int nthreads=0);
1537 bool OIIO_API zover (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
1538  bool z_zeroisinf=false, ROI roi={}, int nthreads=0);
1539 
1540 
1541 /// Return (or copy into dst) the "deep" version of "flat" input src.
1542 /// Turning a flat image into a deep one means:
1543 ///
1544 /// If the src image has a "Z" channel: if the source pixel's Z channel
1545 /// value is not infinite, the corresponding pixel of dst will get a single
1546 /// depth sample that copies the data from the soruce pixel; otherwise, dst
1547 /// will get an empty pixel. In other words, infinitely far pixels will not
1548 /// turn into deep samples.
1549 ///
1550 /// If the src image lacks a "Z" channel: if any of the source pixel's
1551 /// channel values are nonzero, the corresponding pixel of dst will get a
1552 /// single depth sample that copies the data from the source pixel and uses
1553 /// the zvalue parameter for the depth; otherwise, if all source channels in
1554 /// that pixel are zero, the destination pixel will get no depth samples.
1555 ///
1556 /// If src is already a deep image, it will just copy pixel values from src
1557 /// to dst.
1558 ImageBuf OIIO_API deepen (const ImageBuf &src, float zvalue = 1.0f,
1559  ROI roi={}, int nthreads=0);
1560 bool OIIO_API deepen (ImageBuf &dst, const ImageBuf &src, float zvalue = 1.0f,
1561  ROI roi={}, int nthreads=0);
1562 
1563 
1564 /// Return (or copy into dst) the ``flattened'' composite of deep image src.
1565 /// That is, it converts a deep image to a simple flat image by front-to-
1566 /// back compositing the samples within each pixel. If src is already a
1567 /// non-deep/flat image, it will just copy pixel values from src to dst. If
1568 /// dst is not already an initialized ImageBuf, it will be sized to match
1569 /// src (but made non-deep).
1570 ImageBuf OIIO_API flatten (const ImageBuf &src, ROI roi={}, int nthreads=0);
1571 bool OIIO_API flatten (ImageBuf &dst, const ImageBuf &src,
1572  ROI roi={}, int nthreads=0);
1573 
1574 
1575 /// Return (or copy into dst) the deep merge of the samples of deep images A
1576 /// and B, overwriting any existing samples of dst in the ROI. If
1577 /// occlusion_cull is true, any samples occluded by an opaque sample will be
1578 /// deleted.
1579 ImageBuf OIIO_API deep_merge (const ImageBuf &A, const ImageBuf &B,
1580  bool occlusion_cull = true,
1581  ROI roi={}, int nthreads=0);
1582 bool OIIO_API deep_merge (ImageBuf &dst, const ImageBuf &A,
1583  const ImageBuf &B, bool occlusion_cull = true,
1584  ROI roi={}, int nthreads=0);
1585 
1586 /// Return (or copy into dst) the samples of deep image src that are closer
1587 /// than the opaque frontier of deep image holdout, returning true upon
1588 /// success and false for any failures. Samples of src that are farther than
1589 /// the first opaque sample of holdout (for the corresponding pixel)will not
1590 /// be copied to dst. Image holdout is only used as the depth threshold; no
1591 /// sample values from holdout are themselves copied to dst.
1592 ImageBuf OIIO_API deep_holdout (const ImageBuf &src, const ImageBuf &holdout,
1593  ROI roi={}, int nthreads=0);
1594 bool OIIO_API deep_holdout (ImageBuf &dst, const ImageBuf &src,
1595  const ImageBuf &holdout,
1596  ROI roi={}, int nthreads=0);
1597 
1598 
1599 
1600 /// Render a single point at (x,y) of the given color "over" the existing
1601 /// image dst. If there is no alpha channel, the color will be written
1602 /// unconditionally (as if the alpha is 1.0).
1603 bool OIIO_API render_point (ImageBuf &dst, int x, int y,
1604  cspan<float> color=1.0f,
1605  ROI roi={}, int nthreads=0);
1606 
1607 /// Render a line from (x1,y1) to (x2,y2) of the given color "over" the
1608 /// existing image dst. If there is no alpha channel, the color will be
1609 /// written unconditionally (as if the alpha is 1.0). If skip_first_point
1610 /// is true, the very first point (x1,y1) will not be rendered; this can be
1611 /// useful for rendering segments of poly-lines to avoid double-rendering
1612 /// the vertex positions.
1613 bool OIIO_API render_line (ImageBuf &dst, int x1, int y1, int x2, int y2,
1614  cspan<float> color=1.0f,
1615  bool skip_first_point = false,
1616  ROI roi={}, int nthreads=0);
1617 
1618 /// Render an a filled or unfilled box with corners (x1,y1) and (x2,y2) of
1619 /// the given color "over" the existing image dst. If there is no alpha
1620 /// channel, the color will be written unconditionally (as if the alpha is
1621 /// 1.0).
1622 bool OIIO_API render_box (ImageBuf &dst, int x1, int y1, int x2, int y2,
1623  cspan<float> color=1.0f, bool fill = false,
1624  ROI roi={}, int nthreads=0);
1625 
1626 
1627 enum class TextAlignX { Left, Right, Center };
1629 
1630 /// Render a text string (encoded as UTF-8) into image dst. If the dst image
1631 /// is not yet initiailzed, it will be initialized to be a black background
1632 /// exactly large enought to contain the rasterized text. If dst is already
1633 /// initialized, the text will be rendered into the existing image by
1634 /// essentially doing an "over" of the character into the existing pixel
1635 /// data.
1636 ///
1637 /// The font is given by fontname (if not a full pathname to a font file, it
1638 /// will search for a matching font, defaulting to some reasonable system
1639 /// font if not supplied at all), and with a nominal height of fontsize (in
1640 /// pixels).
1641 ///
1642 /// The position is given by coordinates (x,y), with the default behavior
1643 /// to align the left edge of the character baseline to (x,y). Optionally,
1644 /// alignx and aligny can override the alignment behavior, with horizontal
1645 /// alignment choices of TextAlignX::Left, Right, and Center, and vertical
1646 /// alignment choices of TextAlginY::Baseline, Top, Bottom, or Center.
1647 ///
1648 /// The characters will be drawn in opaque white (1.0,1.0,...) in all
1649 /// channels, unless textcolor is supplied (and is expected to point to a
1650 /// float array of length at least equal to R.spec().nchannels, or defaults
1651 /// will be chosen for you). If shadow is nonzero, a "drop shadow" of that
1652 /// radius will be used to make the text look more clear by dilating the
1653 /// alpha channel of the composite (makes a black halo around the
1654 /// characters).
1655 bool OIIO_API render_text (ImageBuf &dst, int x, int y, string_view text,
1656  int fontsize=16, string_view fontname="",
1657  cspan<float> textcolor = 1.0f,
1658  TextAlignX alignx = TextAlignX::Left,
1660  int shadow = 0, ROI roi={}, int nthreads=0);
1661 
1662 
1663 /// Helper function: how big is the text that would be drawn by render_text?
1664 /// Returns the extent as an ROI (relative to the left edge of the baseline
1665 /// of the first character). The size is an ROI, but only the x and y
1666 /// dimensions are used. Failures can be detected by testing the ROI's
1667 /// defined() property.
1668 ROI OIIO_API text_size (string_view text, int fontsize=16,
1669  string_view fontname="");
1670 
1671 
1672 
1673 /// Compute a histogram of src, for the given channel and ROI. Return a
1674 /// vector of length `bins` that contains the counts of how many pixel
1675 /// values were in each of `bins` equally spaced bins covering the range of
1676 /// values [min,max]. Values < min count for bin 0, values > max count for
1677 /// bin `nbins-1`. If ignore_empty is true, no counts will be incremented
1678 /// for any pixels that are 0 in all channels.
1679 OIIO_API
1680 std::vector<imagesize_t> histogram (const ImageBuf &src, int channel=0,
1681  int bins=256, float min=0.0f, float max=1.0f,
1682  bool ignore_empty=false,
1683  ROI roi={}, int nthreads=0);
1684 
1685 
1686 /// DEPRECATED(1.9)
1687 bool OIIO_API histogram (const ImageBuf &src, int channel,
1688  std::vector<imagesize_t> &histogram, int bins=256,
1689  float min=0, float max=1, imagesize_t *submin=nullptr,
1690  imagesize_t *supermax=nullptr, ROI roi={});
1691 
1692 // DEPRECATED(1.9): never liked this.
1693 bool OIIO_API histogram_draw (ImageBuf &dst,
1694  const std::vector<imagesize_t> &histogram);
1695 
1696 
1697 
1698 enum OIIO_API MakeTextureMode {
1702  _MakeTxLast
1703 };
1704 
1705 /// Turn an image into a tiled, MIP-mapped, texture file and write it to
1706 /// disk (outputfilename). The 'mode' describes what type of texture
1707 /// file we are creating and may be one of:
1708 /// MakeTxTexture Ordinary 2D texture
1709 /// MakeTxEnvLatl Latitude-longitude environment map
1710 /// MakeTxEnvLatlFromLightProbe Latitude-longitude environment map
1711 /// constructed from a "light probe" image.
1712 ///
1713 /// If the outstream pointer is not NULL, it should point to a stream
1714 /// (for example, &std::out, or a pointer to a local std::stringstream
1715 /// to capture output), which is where console output and error messages
1716 /// will be deposited.
1717 ///
1718 /// The 'config' is an ImageSpec that contains all the information and
1719 /// special instructions for making the texture. Anything set in config
1720 /// (format, tile size, or named metadata) will take precedence over
1721 /// whatever is specified by the input file itself. Additionally, named
1722 /// metadata that starts with "maketx:" will not be output to the file
1723 /// itself, but may contain instructions controlling how the texture is
1724 /// created. The full list of supported configuration options is:
1725 ///
1726 /// Named fields:
1727 /// format Data format of the texture file (default: UNKNOWN =
1728 /// same format as the input)
1729 /// tile_width Preferred tile size (default: 64x64x1)
1730 /// tile_height
1731 /// tile_depth
1732 /// Metadata in config.extra_attribs:
1733 /// compression (string) Default: "zip"
1734 /// fovcot (float) Default: aspect ratio of the image resolution
1735 /// planarconfig (string) Default: "separate"
1736 /// worldtocamera (matrix) World-to-camera matrix of the view.
1737 /// worldtoscreen (matrix) World-to-screen space matrix of the view.
1738 /// wrapmodes (string) Default: "black,black"
1739 /// maketx:verbose (int) How much detail should go to outstream (0).
1740 /// maketx:runstats (int) If nonzero, print run stats to outstream (0).
1741 /// maketx:resize (int) If nonzero, resize to power of 2. (0)
1742 /// maketx:nomipmap (int) If nonzero, only output the top MIP level (0).
1743 /// maketx:updatemode (int) If nonzero, write new output only if the
1744 /// output file doesn't already exist, or is
1745 /// older than the input file, or was created
1746 /// with different command-line arguments. (0)
1747 /// maketx:constant_color_detect (int)
1748 /// If nonzero, detect images that are entirely
1749 /// one color, and change them to be low
1750 /// resolution (default: 0).
1751 /// maketx:monochrome_detect (int)
1752 /// If nonzero, change RGB images which have
1753 /// R==G==B everywhere to single-channel
1754 /// grayscale (default: 0).
1755 /// maketx:opaque_detect (int)
1756 /// If nonzero, drop the alpha channel if alpha
1757 /// is 1.0 in all pixels (default: 0).
1758 /// maketx:compute_average (int)
1759 /// If nonzero, compute and store the average
1760 /// color of the texture (default: 1).
1761 /// maketx:unpremult (int) If nonzero, unpremultiply color by alpha before
1762 /// color conversion, then multiply by alpha
1763 /// after color conversion (default: 0).
1764 /// maketx:incolorspace (string)
1765 /// maketx:outcolorspace (string)
1766 /// These two together will apply a color conversion
1767 /// (with OpenColorIO, if compiled). Default: ""
1768 /// maketx:colorconfig (string)
1769 /// Specifies a custom OpenColorIO color config
1770 /// file. Default: ""
1771 /// maketx:checknan (int) If nonzero, will consider it an error if the
1772 /// input image has any NaN pixels. (0)
1773 /// maketx:fixnan (string) If set to "black" or "box3", will attempt
1774 /// to repair any NaN pixels found in the
1775 /// input image (default: "none").
1776 /// maketx:set_full_to_pixels (int)
1777 /// If nonzero, doctors the full/display window
1778 /// of the texture to be identical to the
1779 /// pixel/data window and reset the origin
1780 /// to 0,0 (default: 0).
1781 /// maketx:filtername (string)
1782 /// If set, will specify the name of a high-quality
1783 /// filter to use when resampling for MIPmap
1784 /// levels. Default: "", use bilinear resampling.
1785 /// maketx:highlightcomp (int)
1786 /// If nonzero, performs highlight compensation --
1787 /// range compression and expansion around
1788 /// the resize, plus clamping negative plxel
1789 /// values to zero. This reduces ringing when
1790 /// using filters with negative lobes on HDR
1791 /// images.
1792 /// maketx:sharpen (float) If nonzero, sharpens details when creating
1793 /// MIPmap levels. The amount is the contrast
1794 /// matric. The default is 0, meaning no
1795 /// sharpening.
1796 /// maketx:nchannels (int) If nonzero, will specify how many channels
1797 /// the output texture should have, padding with
1798 /// 0 values or dropping channels, if it doesn't
1799 /// the number of channels in the input.
1800 /// (default: 0, meaning keep all input channels)
1801 /// maketx:channelnames (string)
1802 /// If set, overrides the channel names of the
1803 /// output image (comma-separated).
1804 /// maketx:fileformatname (string)
1805 /// If set, will specify the output file format.
1806 /// (default: "", meaning infer the format from
1807 /// the output filename)
1808 /// maketx:prman_metadata (int)
1809 /// If set, output some metadata that PRMan will
1810 /// need for its textures. (0)
1811 /// maketx:oiio_options (int)
1812 /// (Deprecated; all are handled by default)
1813 /// maketx:prman_options (int)
1814 /// If nonzero, override a whole bunch of settings
1815 /// as needed to make textures that are
1816 /// compatible with PRMan. (0)
1817 /// maketx:mipimages (string)
1818 /// Semicolon-separated list of alternate images
1819 /// to be used for individual MIPmap levels,
1820 /// rather than simply downsizing. (default: "")
1821 /// maketx:full_command_line (string)
1822 /// The command or program used to generate this
1823 /// call, will be embedded in the metadata.
1824 /// (default: "")
1825 /// maketx:ignore_unassoc (int)
1826 /// If nonzero, will disbelieve any evidence that
1827 /// the input image is unassociated alpha. (0)
1828 /// maketx:read_local_MB (int)
1829 /// If nonzero, will read the full input file locally
1830 /// if it is smaller than this threshold. Zero
1831 /// causes the system to make a good guess at
1832 /// a reasonable threshold (e.g. 1 GB). (0)
1833 /// maketx:forcefloat (int)
1834 /// Forces a conversion through float data for
1835 /// the sake of ImageBuf math. (1)
1836 /// maketx:hash (int)
1837 /// Compute the sha1 hash of the file in parallel. (1)
1838 /// maketx:allow_pixel_shift (int)
1839 /// Allow up to a half pixel shift per mipmap level.
1840 /// The fastest path may result in a slight shift
1841 /// in the image, accumulated for each mip level
1842 /// with an odd resolution. (0)
1843 /// maketx:bumpformat (string)
1844 /// For the MakeTxBumpWithSlopes mode, chooses
1845 /// whether to assume the map is a height map
1846 /// ("height"), a normal map ("normal"), or
1847 /// automatically determine it from the number
1848 /// of channels ("auto", the default).
1849 ///
1850 bool OIIO_API make_texture (MakeTextureMode mode,
1851  const ImageBuf &input,
1852  string_view outputfilename,
1853  const ImageSpec &config,
1854  std::ostream *outstream = nullptr);
1855 
1856 /// Version of make_texture that starts with a filename and reads the input
1857 /// from that file, rather than being given an ImageBuf directly.
1858 bool OIIO_API make_texture (MakeTextureMode mode,
1860  string_view outputfilename,
1861  const ImageSpec &config,
1862  std::ostream *outstream = nullptr);
1863 
1864 /// Version of make_texture that takes multiple filenames (reserved for
1865 /// future expansion, such as assembling several faces into a cube map).
1866 bool OIIO_API make_texture (MakeTextureMode mode,
1867  const std::vector<std::string> &filenames,
1868  string_view outputfilename,
1869  const ImageSpec &config,
1870  std::ostream *outstream = nullptr);
1871 
1872 
1873 ///////////////////////////////////////////////////////////////////////
1874 // DEPRECATED(1.9): These are all functions that take raw pointers,
1875 // which we are deprecating as of 1.9, replaced by new versions that
1876 // take span<> for length safety.
1877 
1878 inline bool fill (ImageBuf &dst, const float *values,
1879  ROI roi={}, int nthreads=0) {
1880  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
1881  return fill (dst, {values, nc}, roi, nthreads);
1882 }
1883 inline bool fill (ImageBuf &dst, const float *top, const float *bottom,
1884  ROI roi={}, int nthreads=0) {
1885  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
1886  return fill (dst, {top, nc}, {bottom, nc}, roi, nthreads);
1887 }
1888 inline bool fill (ImageBuf &dst, const float *topleft, const float *topright,
1889  const float *bottomleft, const float *bottomright,
1890  ROI roi={}, int nthreads=0) {
1891  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
1892  return fill (dst, {topleft, nc}, {topright, nc}, {bottomleft, nc},
1893  {bottomright, nc}, roi, nthreads);
1894 }
1895 
1896 inline bool checker (ImageBuf &dst, int width, int height, int depth,
1897  const float *color1, const float *color2,
1898  int xoffset=0, int yoffset=0, int zoffset=0,
1899  ROI roi={}, int nthreads=0) {
1900  int nc (roi.defined() ? roi.nchannels() : dst.nchannels());
1901  return checker (dst, width, height, depth, {color1,nc}, {color2,nc},
1902  xoffset, yoffset, zoffset, roi, nthreads);
1903 }
1904 
1905 inline bool add (ImageBuf &dst, const ImageBuf &A, const float *B,
1906  ROI roi={}, int nthreads=0) {
1907  return add (dst, A, {B,A.nchannels()}, roi, nthreads);
1908 }
1909 inline bool sub (ImageBuf &dst, const ImageBuf &A, const float *B,
1910  ROI roi={}, int nthreads=0) {
1911  return sub (dst, A, {B,A.nchannels()}, roi, nthreads);
1912 }
1913 inline bool absdiff (ImageBuf &dst, const ImageBuf &A, const float *B,
1914  ROI roi={}, int nthreads=0) {
1915  return absdiff (dst, A, cspan<float>(B,A.nchannels()), roi, nthreads);
1916 }
1917 inline bool mul (ImageBuf &dst, const ImageBuf &A, const float *B,
1918  ROI roi={}, int nthreads=0) {
1919  return mul (dst, A, {B, A.nchannels()}, roi, nthreads);
1920 }
1921 inline bool div (ImageBuf &dst, const ImageBuf &A, const float *B,
1922  ROI roi={}, int nthreads=0) {
1923  return div (dst, A, {B, A.nchannels()}, roi, nthreads);
1924 }
1925 inline bool mad (ImageBuf &dst, const ImageBuf &A, const float *B,
1926  const ImageBuf &C, ROI roi={}, int nthreads=0) {
1927  return mad (dst, A, {B, A.nchannels()}, C, roi, nthreads);
1928 }
1929 inline bool mad (ImageBuf &dst, const ImageBuf &A, const ImageBuf &B,
1930  const float *C, ROI roi={}, int nthreads=0) {
1931  return mad (dst, A, C, B, roi, nthreads);
1932 }
1933 inline bool mad (ImageBuf &dst, const ImageBuf &A, const float *B,
1934  const float *C, ROI roi={}, int nthreads=0) {
1935  return mad (dst, A, {B, A.nchannels()}, {C, A.nchannels()}, roi, nthreads);
1936 }
1937 
1938 inline bool pow (ImageBuf &dst, const ImageBuf &A, const float *B,
1939  ROI roi={}, int nthreads=0) {
1940  return pow (dst, A, {B, A.nchannels()}, roi, nthreads);
1941 }
1942 
1943 inline bool channel_sum (ImageBuf &dst, const ImageBuf &src,
1944  const float *weights=nullptr, ROI roi={},
1945  int nthreads=0) {
1946  return channel_sum (dst, src, {weights, src.nchannels()},
1947  roi, nthreads);
1948 }
1949 
1950 inline bool channels (ImageBuf &dst, const ImageBuf &src,
1951  int nchannels, const int *channelorder,
1952  const float *channelvalues=nullptr,
1953  const std::string *newchannelnames=nullptr,
1954  bool shuffle_channel_names=false, int nthreads=0) {
1955  return channels (dst, src, nchannels,
1956  { channelorder, channelorder?nchannels:0 },
1957  { channelvalues, channelvalues?nchannels:0 },
1958  { newchannelnames, newchannelnames?nchannels:0},
1959  shuffle_channel_names, nthreads);
1960 }
1961 
1962 inline bool clamp (ImageBuf &dst, const ImageBuf &src,
1963  const float *min=nullptr, const float *max=nullptr,
1964  bool clampalpha01 = false,
1965  ROI roi={}, int nthreads=0) {
1966  return clamp (dst, src, { min, min ? src.nchannels() : 0 },
1967  { max, max ? src.nchannels() : 0 }, clampalpha01,
1968  roi, nthreads);
1969 }
1970 
1971 inline bool isConstantColor (const ImageBuf &src, float *color,
1972  ROI roi={}, int nthreads=0) {
1973  int nc = roi.defined() ? std::min(roi.chend,src.nchannels()) : src.nchannels();
1974  return isConstantColor (src, {color, color ? nc : 0}, roi, nthreads);
1975 }
1976 
1977 inline bool color_count (const ImageBuf &src, imagesize_t *count,
1978  int ncolors, const float *color,
1979  const float *eps=nullptr,
1980  ROI roi={}, int nthreads=0) {
1981  return color_count (src, count, ncolors,
1982  { color, ncolors*src.nchannels() },
1983  eps ? cspan<float>(eps,src.nchannels()) : cspan<float>(),
1984  roi, nthreads);
1985 }
1986 
1987 inline bool color_range_check (const ImageBuf &src, imagesize_t *lowcount,
1988  imagesize_t *highcount, imagesize_t *inrangecount,
1989  const float *low, const float *high,
1990  ROI roi={}, int nthreads=0) {
1991  return color_range_check (src, lowcount, highcount, inrangecount,
1992  {low,src.nchannels()}, {high,src.nchannels()},
1993  roi, nthreads);
1994 }
1995 
1996 inline bool render_text (ImageBuf &dst, int x, int y, string_view text,
1997  int fontsize, string_view fontname,
1998  const float *textcolor) {
1999  return render_text (dst, x, y, text, fontsize, fontname,
2000  {textcolor, textcolor?dst.nchannels():0});
2001 }
2002 
2003 ///////////////////////////////////////////////////////////////////////
2004 
2005 } // end namespace ImageBufAlgo
2006 
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)
GLdouble s
Definition: glew.h:1390
bool OIIO_API paste(ImageBuf &dst, int xbegin, int ybegin, int zbegin, int chbegin, const ImageBuf &src, ROI srcroi={}, int nthreads=0)
GLbyte * weights
Definition: glew.h:7551
std::vector< double > sum2
Definition: imagebufalgo.h:877
ImageBuf OIIO_API warp(const ImageBuf &src, const Imath::M33f &M, string_view filtername=string_view(), float filterwidth=0.0f, bool recompute_roi=false, ImageBuf::WrapMode wrap=ImageBuf::WrapDefault, ROI roi={}, int nthreads=0)
vint4 max(const vint4 &a, const vint4 &b)
Definition: simd.h:4703
bool OIIO_API render_point(ImageBuf &dst, int x, int y, cspan< float > color=1.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API transpose(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLenum GLenum GLenum input
Definition: glew.h:13879
GT_API const UT_StringHolder filename
NONFINITE_BOX3
Replace nonfinite pixels with 3x3 finite average.
ImageBuf OIIO_API color_map(const ImageBuf &src, int srcchannel, int nknots, int channels, cspan< float > knots, ROI roi={}, int nthreads=0)
GLenum src
Definition: glew.h:2410
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:195
Matrix44< float > M44f
Definition: ImathMatrix.h:865
GLuint const GLchar * name
Definition: glew.h:1814
ImageBuf OIIO_API copy(const ImageBuf &src, TypeDesc convert=TypeUnknown, ROI roi={}, int nthreads=0)
parallel_options parallel_image_options
Definition: imagebufalgo.h:217
bool has_error(void) const
GLint GLint xoffset
Definition: glew.h:1252
GLenum mode
Definition: glew.h:2163
ImageBuf OIIO_API ifft(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLint GLint GLint GLint GLint GLint GLsizei width
Definition: glew.h:1252
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:1599
Encapsulation of options that control parallel_image().
Definition: parallel.h:54
ImageBuf OIIO_API fill(cspan< float > values, ROI roi, int nthreads=0)
GLuint const GLfloat * val
Definition: glew.h:2794
MakeTxTexture
std::string OIIO_API computePixelHashSHA1(const ImageBuf &src, string_view extrainfo="", ROI roi={}, int blocksize=0, int nthreads=0)
GLint GLsizei const GLuint64 * values
Definition: glew.h:3612
ImageBuf OIIO_API ociolook(const ImageBuf &src, string_view looks, string_view fromspace, string_view tospace, bool unpremult=true, bool inverse=false, string_view key="", string_view value="", ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
Definition: span.h:47
GLuint GLfloat GLfloat GLfloat x1
Definition: glew.h:12681
GLint GLint GLint GLint GLint GLint GLsizei GLsizei height
Definition: glew.h:1252
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
Definition: imagebufalgo.h:875
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)
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)
ImageBuf OIIO_API rangecompress(const ImageBuf &src, bool useluma=false, ROI roi={}, int nthreads=0)
Image_or_Const(const std::vector< float > &val)
Definition: imagebufalgo.h:188
ImageBuf OIIO_API reorient(const ImageBuf &src, int nthreads=0)
const GLdouble * v
Definition: glew.h:1391
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)
GLboolean reset
Definition: glew.h:4959
OIIO_API bool to_OpenCV(cv::Mat &dst, const ImageBuf &src, ROI roi={}, int nthreads=0)
GLdouble angle
Definition: glew.h:9135
std::vector< imagesize_t > finitecount
Definition: imagebufalgo.h:876
MakeTxEnvLatlFromLightProbe
GLint void * img
Definition: glew.h:1385
Matrix33< float > M33f
Definition: ImathMatrix.h:863
ImageBuf OIIO_API colorconvert(const ImageBuf &src, const ColorProcessor *processor, bool unpremult, ROI roi={}, int nthreads=0)
std::vector< float > stddev
Definition: imagebufalgo.h:873
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)
ImageBuf OIIO_API pow(const ImageBuf &A, cspan< float > B, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API flop(const ImageBuf &src, ROI roi={}, int nthreads=0)
const ImageBuf * imgptr() const
Definition: imagebufalgo.h:196
ImageBuf OIIO_API fixNonFinite(const ImageBuf &src, NonFiniteFixMode mode=NONFINITE_BOX3, int *pixelsFixed=nullptr, ROI roi={}, int nthreads=0)
CompareResults OIIO_API compare(const ImageBuf &A, const ImageBuf &B, float failthresh, float warnthresh, ROI roi={}, int nthreads=0)
GLint GLint bottom
Definition: glew.h:8008
GLint GLint GLint GLint GLint GLint GLint GLbitfield GLenum filter
Definition: glew.h:2981
ImageBuf OIIO_API fillholes_pushpull(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)
Definition: imagebufalgo.h:881
ImageBuf OIIO_API make_kernel(string_view name, float width, float height, float depth=1.0f, bool normalize=true)
GLclampf f
Definition: glew.h:3499
ImageBuf OIIO_API fft(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLint GLint GLint GLint GLint x
Definition: glew.h:1252
ImageBuf OIIO_API deep_merge(const ImageBuf &A, const ImageBuf &B, bool occlusion_cull=true, ROI roi={}, int nthreads=0)
GLint GLint GLint GLint GLint GLint y
Definition: glew.h:1252
ImageBuf OIIO_API deepen(const ImageBuf &src, float zvalue=1.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API dilate(const ImageBuf &src, int width=3, int height=-1, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API complex_to_polar(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLfloat GLfloat GLfloat top
Definition: glew.h:15186
ROI OIIO_API text_size(string_view text, int fontsize=16, string_view fontname="")
MakeTxShadow
ImageBuf OIIO_API from_IplImage(const IplImage *ipl, TypeDesc convert=TypeUnknown)
basic_string_view< char > string_view
Definition: core.h:426
ImageBuf OIIO_API erode(const ImageBuf &src, int width=3, int height=-1, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API invert(const ImageBuf &A, ROI roi={}, int nthreads=0)
cspan< float > val() const
Definition: imagebufalgo.h:197
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)
GLenum GLenum dst
Definition: glew.h:2410
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)
ImageBuf OIIO_API resize(const ImageBuf &src, string_view filtername="", float filterwidth=0.0f, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API ociofiletransform(const ImageBuf &src, string_view name, bool unpremult=true, bool inverse=false, ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
std::vector< imagesize_t > nancount
Definition: imagebufalgo.h:874
void swap(Image_or_Const &other)
Definition: imagebufalgo.h:199
Image_or_Const(const float &val)
Definition: imagebufalgo.h:187
ImageBuf OIIO_API premult(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API rotate180(const ImageBuf &src, ROI roi={}, int nthreads=0)
GLuint color
Definition: glew.h:7902
GridType::Ptr normalize(const GridType &grid, bool threaded, InterruptT *interrupt)
Normalize the vectors of the given vector-valued grid.
ImageBuf OIIO_API polar_to_complex(const ImageBuf &src, ROI roi={}, int nthreads=0)
NONFINITE_ERROR
Error if any nonfinite pixels are found.
bool is_val() const
Definition: imagebufalgo.h:193
Image_or_Const(const ImageBuf &img)
Definition: imagebufalgo.h:184
ImageBuf OIIO_API div(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API capture_image(int cameranum=0, TypeDesc convert=TypeUnknown)
std::vector< float > max
Definition: imagebufalgo.h:871
Image_or_Const(const ImageBuf *img)
Definition: imagebufalgo.h:185
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)
GLfloat GLfloat p
Definition: glew.h:16321
GLint GLint GLint GLint zoffset
Definition: glew.h:1252
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)
GLsizei const GLchar *const * string
Definition: glew.h:1844
Definition: imageio.h:115
ImageBuf OIIO_API cut(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, string_view key="", string_view value="", ColorConfig *colorconfig=nullptr, ROI roi={}, int nthreads=0)
MakeTxEnvLatl
ImageBuf OIIO_API rangeexpand(const ImageBuf &src, bool useluma=false, ROI roi={}, int nthreads=0)
Image_or_Const(None)
Definition: imagebufalgo.h:183
OIIO_API bool isConstantColor(const ImageBuf &src, float threshold=0.0f, span< float > color={}, 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)
bool OIIO_API make_texture(MakeTextureMode mode, const ImageBuf &input, string_view outputfilename, const ImageSpec &config, std::ostream *outstream=nullptr)
ImageBuf OIIO_API colormatrixtransform(const ImageBuf &src, const Imath::M44f &M, bool unpremult=true, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API rotate270(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API median_filter(const ImageBuf &src, int width=3, int height=-1, ROI roi={}, int nthreads=0)
OIIO_API IplImage * to_IplImage(const ImageBuf &src)
ImageBuf OIIO_API flip(const ImageBuf &src, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API absdiff(Image_or_Const A, Image_or_Const B, ROI roi={}, int nthreads=0)
std::vector< float > min
Definition: imagebufalgo.h:870
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)
GLuint GLfloat GLfloat GLfloat GLfloat y1
Definition: glew.h:12681
GLuint GLuint GLsizei count
Definition: glew.h:1253
NONFINITE_BLACK
Replace nonfinite pixels with black.
GLint GLint GLint yoffset
Definition: glew.h:1252
Image_or_Const(const float *v, size_t s)
Definition: imagebufalgo.h:189
ImageBuf OIIO_API channel_sum(const ImageBuf &src, cspan< float > weights=1.0f, ROI roi={}, int nthreads=0)
NONFINITE_NONE
Do nothing.
GLuint64EXT * result
Definition: glew.h:14007
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 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:190
#define OIIO_NAMESPACE_END
Definition: oiioversion.h:66
ImageBuf OIIO_API deep_holdout(const ImageBuf &src, const ImageBuf &holdout, ROI roi={}, int nthreads=0)
vint4 min(const vint4 &a, const vint4 &b)
Definition: simd.h:4694
std::vector< float > avg
Definition: imagebufalgo.h:872
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)
ImageBuf OIIO_API convolve(const ImageBuf &src, const ImageBuf &kernel, bool normalize=true, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API fit(const ImageBuf &src, string_view filtername="", float filterwidth=0.0f, bool exact=false, ROI roi={}, int nthreads=0)
Image_or_Const(cspan< float > val)
Definition: imagebufalgo.h:186
GLsizei const GLfloat * value
Definition: glew.h:1849
ImageBuf OIIO_API rotate90(const ImageBuf &src, ROI roi={}, int nthreads=0)
bool is_empty() const
Definition: imagebufalgo.h:194
ImageBuf OIIO_API zover(const ImageBuf &A, const ImageBuf &B, bool z_zeroisinf=false, ROI roi={}, int nthreads=0)
ImageBuf OIIO_API unpremult(const ImageBuf &src, ROI roi={}, int nthreads=0)
PixelStats OIIO_API computePixelStats(const ImageBuf &src, ROI roi={}, int nthreads=0)
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)
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)
GLint GLint GLsizei GLsizei GLsizei depth
Definition: glew.h:1254
MakeTxBumpWithSlopes
unsigned long long imagesize_t
Definition: imageio.h:85
#define OIIO_NAMESPACE_BEGIN
Definition: oiioversion.h:65
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:91
bool is_img() const
Definition: imagebufalgo.h:192