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