This page documents all poImg specific functions.
1. General information:
=======================
The following symbolic names and their numerical values
can be used as equivalents:
OFF false 0
ON true 1
A value of type "boolean" can be specified with one of these values.
2. Channel type:
================
There are currently 11 possible channel types.
Their Tcl symbolic names as well as their
numerical values are listed below:
BRIGHTNESS 0 Brightness for black and white images
RED 1 Red for color images
GREEN 2 Green for color images
BLUE 3 Blue for color images
MATTE 4 Transparency without color information
REDMATTE 5 Transparency for red light
GREENMATTE 6 Transparency for green light
BLUEMATTE 7 Transparency for blue light
HNORMAL 8 Direction of surface normal, horizontal
VNORMAL 9 Direction of surface normal, vertical
DEPTH 10 Distance from the eye point
NUMCHAN 11 Number of different channel types
3. Channel format:
==================
The data stored in a channel can be in the following different formats:
OFF 0 Channel is not used
UBYTE 1 Channel holds 8-bit integer values (i.e. 0..255)
FLOAT 2 Channel holds 32-bit floating point values
4. Image compression:
=====================
A channel can be compressed using one of the following methods:
OFF 0 No compression.
RLE 1 Lossless compression, e.g. run length encoding
DCT 2 Lossy compression, e.g. DCT compression
5. Drawing mode:
================
The following different drawing modes are available:
REPLACE 0 Replace old color with current color
ADD 1 Add old color and current color
SUB 2 Subtract old color from current color
XOR 3 Exclusive-or old color and current color
6. Image file formats:
======================
poSoft format po
poSoft Raw format raw
Silicon Graphics format sgi
Truevision Targa format targa
Name: IP_ApplyLogo
Usage: Put an image on top of another image.
Synopsis: UT_Bool IP_ApplyLogo
(IP_ImageId img, IP_ImageId logo,
Int32 x1, Int32 y1,
Float32 sr, Float32 sg, Float32 sb)
Description: Put an image on top of another image.
Return value: UT_Bool.
Name: IP_AsPhoto
Usage: Copy an image into a TK photo image.
Synopsis: UT_Bool IP_AsPhoto
(IP_ImageId img,
const char *photoName,
FF_ImgChanType chanMap[4],
Float32 gamma,
Float32 minVal, Float32 maxVal,
Tcl_Interp *interp)
Description: Copy an image into a TK photo image.
Return value: UT_True if succesful, else UT_False.
Name: IP_Blank
Usage: Blank all channels of an image.
Synopsis: void IP_Blank (IP_ImageId img)
Description: All channels in image "img" are filled with zeroes.
The current drawing color, mode and mask have no
effect.
Return value: None.
Name: IP_BlendFunct
Usage: Blend two images, producing an "in-between" image.
Synopsis: UT_Bool IP_BlendFunct
(IP_ImageId srcimg1,
IP_ImageId srcimg2,
IP_ImageId destimg,
UT_Bool (* d1funct)
(Float32, Float32, Float32 *, Float32 *),
UT_Bool (* d1deriv)
(Float32, Float32,
Float32 *, Float32 *, Float32 *, Float32 *),
UT_Bool (* d2funct)
(Float32, Float32, Float32 *, Float32 *),
UT_Bool (* d2deriv)
(Float32, Float32,
Float32 *, Float32 *, Float32 *, Float32 *),
UT_Bool (* bfunct)
(Float32, Float32, Float32 *),
Int32 istep,
IP_FillModeType oor)
Description: IP_BlendFunct interpolates between two source images,
"srcimg1" and "srcimg2", by displacing pixels and
blending the colors of the displaced pixels. The
result is stored in image "destimg". The interpola-
tion is defined by a set of functions, which should
be defined as follows:
UT_Bool d1funct
(Float32 x, Float32 y,
Float32 *u, Float32 *v)
UT_Bool d1deriv
(Float32 x, Float32 y,
Float32 *ux, Float32 *uy,
Float32 *vx, Float32 *vy)
UT_Bool d2funct
(Float32 x, Float32 y,
Float32 *u, Float32 *v)
UT_Bool d2deriv
(Float32 x, Float32 y,
Float32 *ux, Float32 *uy,
Float32 *vx, Float32 *vy)
UT_Bool bfunct
(Float32 x, Float32 y,
Float32 *f)
"D1funct" and "d1deriv" define how pixels from
"srcimg1" are displaced:
Given a position (x, y) in "destimg", "d1funct"
finds the corresponding position (u, v) in "srcimg1".
"D1deriv" computes the four partial derivatives of
"d1funct"; given a position (x, y), "dderiv1" returns
ux = du (x, y) / dx,
uy = du (x, y) / dy,
vx = dv (x, y) / dx,
vy = dv (x, y) / dy.
Dv = dv (x, y) / dy.
"D2funct" and "d2deriv" define how pixels from
"srcimg2" are displaced, analogous to "d1funct"
and "d1deriv".
"Bfunct" defines how the colors of the displaced pixels
from the source images are combined into colors for
the pixels in the destination image. Given a position
(x, y) in "destimg", "bfunct" computes a blending
factor "f". The color in "destimg" is "f" times the
color from "srcimg1" plus (1-f) times the color from
"srcimg2".
Evaluating the five interpolation functions for every
pixel can be quite time-consuming. In order to save
time, the functions are sampled only every "istep"
pixels; in-between values are interpolated linearly.
"Oor" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
images. The following values for "oor" are accepted:
IP_FillModeFill Pixels not covered by the input
images are filled with the
current drawing color.
IP_FillModeWrap The input images are repeated
in horizontal and vertical
direction so that the output
image is tiled with copies of
the input images.
IP_FillModeClip Input pixel coordinates are
clipped so that regions outside
the input images are filled
with the color of the nearest
input image pixel.
Notes:
- Right-handed coordinate systems are used for
positions in the source and destination images.
The lower left corner of each image is at (0, 0);
the upper right corner is at (1, 1).
- Blending factors returned by "bfunct" should be
in the range from 0.0 to 1.0. Values less than
0.0 are treated as 0.0; values above 1.0 are
treated as 1.0.
- The return value of all five interpolation functions
should normally be UT_True. Image blending is aborted
as soon as one of the interpolation functions returns
UT_False.
- Parts of IP_BlendFunct can be run concurrently on
multiple processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
Name: IP_BlendKeypoint
Usage: Blend two images, producing an "in-between" image.
Synopsis: UT_Bool IP_BlendKeypoint
(IP_ImageId srcimg1,
IP_ImageId srcimg2,
IP_ImageId destimg,
Int32 nkey,
const Float32 xsrc1[],
const Float32 ysrc1[],
const Float32 xsrc2[],
const Float32 ysrc2[],
const Float32 f[],
Int32 istep,
Float32 r,
IP_FillModeType oor)
Description: IP_BlendKeypoint interpolates between two source
images, "srcimg1" and "srcimg2", by displacing pixels
and blending the pixel colors. The result is stored
in image "destimg". The interpolation is defined by a
set of "nkey" key points:
The position of key point number "i" in "srcimg1" is
(xsrc1[i], ysrc1[i]); the key point's position in
"srcimg2" is (xsrc2[i], ysrc2[i]). The key point's
position in "destimg" is (xdest[i], ydest[i]), where
xdest[i] = xsrc1[i] * f[i] + xsrc2[i] * (1-f[i]);
ydest[i] = ysrc1[i] * f[i] + ysrc2[i] * (1-f[i]);
The color of the pixel at position (xdest[i], ydest[i])
in "destimg" is f[i] times the color of the pixel at
position (xsrc1[i], ysrc1[i]) in "srcimg1" plus
(1-f[i]) times the color of the pixel at position
(xsrc2[i], ysrc2[i]) in "srcimg2".
For pixels in "destimg", which do not coincide with
some key point, the positions in "srcimg1" and
"srcimg2", from where the pixel colors are taken, are
smoothly interpolated from the key points.
Interpolating smoothly between the key points can
be quite time-consuming. In order to save some time,
the interpolating function is sampled only every
"istep" pixels; in-between values are interpolated
linearly.
If "istep" is 1, the interpolation function is sampled
for every pixel and the resulting image looks as smooth
as possible. Setting "istep" to a value greater than 1
saves time, but the result looks less smooth.
"R" selects the smoothness of the function used to
interpolate between the key points:
If "r" is less than or equal to 0.0, interpolation is
very smooth, but changing one key point has a strong
effect on the whole image.
If "r" is greater than 0.0, a different interpolation
algorithm is used. The influence of key points is much
more limited to the area around the key points. "R"
should be somewhere around 1.0; interpolation becomes
smoother when "r" increases.
"Oor" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
images. The following values for "oor" are accepted:
IP_FillModeFill Pixels not covered by the input
images are filled with the
current drawing color.
IP_FillModeWrap The input images are repeated
in horizontal and vertical
direction so that the output
image is tiled with copies of
the input images.
IP_FillModeClip Input pixel coordinates are
clipped so that regions outside
the input images are filled
with the color of the nearest
input image pixel.
Notes:
- "Xsrc1", "ysrc1", "xsrc2" and "ysrc2" should be
in the range from 0.0 to 1.0. The lower left
corner of "srcimg1", "srcimg2" and "destimg" is
at position (0.0, 0.0); the upper right corner
is at position (1.0, 1.0).
- "Z" should be in the range from 0.0 to 1.0. Values
less than 0.0 are clipped to 0.0; values above 1.0
are clipped to 1.0.
- IP_BlendKeypoint can be run concurrently on
multiple processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
Name: IP_Blur
Usage: Blurs an image.
Synopsis: UT_Bool IP_Blur (IP_ImageId img, Float32 f, Float32 g)
Description: All channels in image "img", for which the current
drawing mask is "UT_True", are blurred:
The color of every pixel in "img" is distributed over
a rectangular area of "f" by "g" pixels using a box
filter.
Note that IP_Blur can be run concurrently on
multiple processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
See also: DepthBlur
Name: IP_ChangeGamma
Usage: Change one channel of an image by gamma-filtering
and linear scaling of the pixel data.
Synopsis: UT_Bool IP_ChangeGamma
(IP_ImageId img, FF_ImgChanType chn,
Float32 gamma, Float32 scl, Float32 off)
Description: Channel "chn" of every pixel in image "img" is changed:
The pixel's orignal value, "v", is clipped (values less
than 0.0 are set to 0.0, values greater than 1.0 are
set to 1.0). The clipped value is gamma filtered, using
gamma factor "gamma" and then scaled by "scl". "Off" is
added to the scaled value. The result replaces the
pixels original value:
v = pow (max (0, min (v, 1)), 1/gamma) * scl + off
Return value: UT_True if successful, else UT_False.
Name: IP_CompositeAlpha
Usage: Composite two images, using a black and white matte.
Synopsis: UT_Bool IP_CompositeAlpha
(IP_ImageId fgimg,
IP_ImageId bgimg,
IP_ImageId cmimg,
Float32 f_r, Float32 f_g, Float32 f_b,
Float32 b_r, Float32 b_g, Float32 b_b,
IP_ImageId mtimg,
UT_Bool fast)
Description: Image "fgimg" is composited in front of image
"bgimg". The result is stored in "cmimg".
If "mtimg" is NULL, the matte for compositing is
taken from image "fgimg". If "mtimg" is not NULL,
image "mtimg" supplies the matte.
1. Any gamma-correction in the input data is
compensated by performing an inverse gamma-
correction on the pixel data from "fgimg"
and "bgimg".
2. The FF_ImgChanTypeRed, FF_ImgChanTypeGreen and
FF_ImgChanTypeBlue channels of all pixels from
"fgimg" are scaled by "fr", "fg" and "fb".
The FF_ImgChanTypeRed, FF_ImgChanTypeGreen
and FF_ImgChanTypeBlue channels of all pixels from
"bgimg" are scaled by "br", "bg" and "bb".
3. The FF_ImgChanTypeGray, FF_ImgChanTypeRed,
FF_ImgChanTypeGreen, and FF_ImgChanTypeBlue channels
for every pixel in "cmimg" are combined from the
data in "fgimg" and "bgimg":
if "mtimg" is NULL:
cm.bright =
fg.bright +
bg.bright * (1-fg.trans);
cm.red =
fg.red +
bg.red * (1-fg.trans);
cm.green =
fg.green +
bg.green * (1-fg.trans);
cm.blue =
fg.blue +
bg.blue * (1-fg.trans);
else
cm.bright =
fg.bright * mt.trans +
bg.bright * (1-mt.trans);
cm.red =
fg.red * mt.trans +
bg.red * (1-mt.trans);
cm.green =
fg.green * mt.trans +
bg.green * (1-mt.trans);
cm.blue =
fg.blue * mt.trans +
bg.blue * (1-mt.trans);
4. The FF_ImgChanTypeGray, FF_ImgChanTypeRed,
FF_ImgChanTypeGreen and FF_ImgChanTypeBlue channels
in "cmimg" are gamma corrected according to the
image descriptor of "cmimg".
5. The FF_ImgChanTypeMatte channel for every pixel in
"cmimg" is computed:
if "mtimg" is NULL:
cm.trans = 1 - (1-fg.trans) * (1-bg.trans);
else
cm.trans = 1 - (1-mt.trans) * (1-bg.trans);
Notes:
- If necessary, "fgimg" or "bgimg" can be
identical to "cmimg", so that IP_CompositeAlpha
overwrites one of the input images with the result.
- IP_CompositeAlpha does not write to any channels in
"cmimg" for which the drawing mask is "UT_False".
- IP_CompositeAlpha does not write to the
FF_ImgChanTypeRedMatte, FF_ImgChanTypeGreenMatte,
FF_ImgChanTypeBlueMatte, FF_ImgChanTypeHoriSnr,
FF_ImgChanTypeVertSnr and FF_ImgChanTypeDepth channels
in "cmimg", even if the drawing mask for these
channels is "UT_True".
- For compositing, "fgimg", "bgimg" and
"cmimg" are aligned at the lower left corner.
If "cmimg" is wider or higher than "fgimg" or
"bgimg", IP_CompositeAlpha does not change areas
in "cmimg" which are not covered by "fgimg" or
"bgimg".
- IP_CompositeAlpha can be run concurrently on
multiple processors; see IP_SetNumThreads.
- If the "fast" flag is set to UT_True, and all pixel
data involved in the compositing are in
FF_ImgFmtTypeUByte format, IP_CompositeAlpha will
switch to a faster, but less general compositing
algorithm.
The results are usually the same as with the slower
algorithm; only if one of "fr", "fg", "fb", "br",
"bg" or "bb" is greater than 1.0 or less than 0.0,
color clipping may be different.
Return value: UT_True if successful, else UT_False.
See also: CompositeColorMatte CompositeDepth
Name: IP_CompositeColorMatte
Usage: Composite two images, using a colored matte.
Synopsis: UT_Bool IP_CompositeColorMatte
(IP_ImageId fgimg,
IP_ImageId bgimg,
IP_ImageId cmimg,
Float32 f_r, Float32 f_g, Float32 f_b,
Float32 b_r, Float32 b_g, Float32 b_b,
IP_ImageId mtimg,
UT_Bool fast)
Description: Image "fgimg" is composited in front of image
"bgimg". The result is stored in "cmimg".
If "mtimg" is NULL, the matte for compositing is
taken from image "fgimg". If "mtimg" is not NULL,
image "mtimg" supplies the matte.
1. Any gamma-correction in the input data is
compensated by performing an inverse gamma-
correction on the pixel data from "fgimg"
and "bgimg".
2. The FF_ImgChanTypeRed, FF_ImgChanTypeGreen and
FF_ImgChanTypeBlue channels of all pixels from
"fgimg" are scaled by "fr", "fg" and "fb".
The FF_ImgChanTypeRed, FF_ImgChanTypeGreen
and FF_ImgChanTypeBlue channels of all pixels from
"bgimg" are scaled by "br", "bg" and "bb".
3. The FF_ImgChanTypeRed, FF_ImgChanTypeGreen and
FF_ImgChanTypeBlue channels for every pixel in
"cmimg" are combined from the data in "fgimg" and
"bgimg":
if "mtimg" is not NUL:
cm.red = fg.red * mt.red_trans +
bg.red * (1-mt.red_trans);
cm.green = fg.green * mt.green_trans +
bg.green * (1-mt.green_trans);
cm.blue = fg.blue * mt.blue_trans +
bg.blue * (1-mt.blue_trans);
else
cm.red = fg.red +
bg.red * (1-fg.red_trans);
cm.green = fg.green +
bg.green * (1-fg.green_trans);
cm.blue = fg.blue +
bg.blue * (1-fg.blue_trans);
4. The FF_ImgChanTypeRed, FF_ImgChanTypeGreen and
FF_ImgChanTypeBlue channels in "cmimg" are gamma
corrected according to the image descriptor of
"cmimg".
5. The FF_ImgChanTypeRedMatte, FF_ImgChanTypeGreenMatte
and FF_ImgChanTypeBlueMatte channels for every pixel
in "cmimg" are combined from the data in "fgimg"
and "bgimg":
if "mtimg" is not NULL:
cm.red_trans = 1 -
(1-mt.red_trans) * (1-bg.red_trans);
cm.green_trans = 1 -
(1-mt.green_trans) * (1-bg.green_trans);
cm.blue_trans = 1 -
(1-mt.blue_trans) * (1-bg.blue_trans);
else
cm.red_trans = 1 -
(1-fg.red_trans) * (1-bg.red_trans);
cm.green_trans = 1 -
(1-fg.green_trans) * (1-bg.green_trans);
cm.blue_trans = 1 -
(1-fg.blue_trans) * (1-bg.blue_trans);
Notes:
- If necessary, "fgimg" or "bgimg" can be
identical to "cmimg", so that IP_CompositeColorMatte
overwrites one of the input images with the result.
- IP_CompositeColorMatte does not write to any channels
in "cmimg" for which the drawing mask is "UT_False".
- IP_CompositeColorMatte does not write to the
FF_ImgChanTypeGray, FF_ImgChanTypeMatte,
FF_ImgChanTypeHoriSnr, FF_ImgChanTypeVertSnr and
FF_ImgChanTypeDepth channels in "cmimg", even if the
drawing mask for these channels is "UT_True".
- For compositing, "fgimg", "bgimg" and
"cmimg" are aligned at the lower left corner.
If "cmimg" is wider or higher than "fgimg" or
"bgimg", IP_CompositeColorMatte does not change areas
in "cmimg" which are not covered by "fgimg" or
"bgimg".
- IP_CompositeColorMatte can be run concurrently on
multiple processors; see IP_SetNumThreads.
- If the "fast" flag is set to UT_True, and all pixel
data involved in the compositing are in
FF_ImgFmtTypeUByte format, IP_CompositeColorMatte will
switch to a faster, but less general compositing
algorithm.
The results are usually the same as with the slower
algorithm; only if one of "fr", "fg", "fb", "br",
"bg" or "bb" is greater than 1.0 or less than 0.0,
color clipping may be different.
Return value: UT_True if successful, else UT_False.
See also: CompositeAlpha CompositeDepth
Name: IP_CompositeDepth
Usage: Composite two images, using depth mattes.
Synopsis: UT_Bool IP_CompositeDepth
(IP_ImageId fgimg,
IP_ImageId bgimg,
IP_ImageId cmimg)
Description: Image "fgimg" and "bgimg" are combined into a new
image, "cmimg". Both, "fgimg" and "bgimg", must
include a FF_ImgChanTypeDepth channel, indicating the
distance of the pixels from the viewer.
The data from "fgimg" and "bgimg" are combined as
follows:
if fgimg.pixel is closer than bgimg.pixel
cmimg.pixel = fgimg.pixel;
else
cmimg.pixel = bgimg.pixel;
Notes:
- If necessary, "fgimg" or "bgimg" can be identical to
"cmimg", so that IP_CompositeDepth overwrites one of
the input images with the result.
- IP_CompositeDepth does not write to any channels in
"cmimg" for which the drawing mask is "UT_False".
- For compositing, "fgimg", "bgimg" and "cmimg" are
aligned at the lower left corner. If "cmimg" is wider
or higher than "fgimg" or "bgimg", IP_CompositeDepth
does not change areas in "cmimg" which are not
covered by "fgimg" or "bgimg".
- IP_CompositeDepth can be run concurrently on
multiple processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
See also: CompositeAlpha CompositeColorMatte
Name: IP_CopyChannel
Usage: Copy the pixel data of one channel in an image into
another channel.
Synopsis: UT_Bool IP_CopyChannel
(IP_ImageId srcimg, IP_ImageId destimg,
FF_ImgChanType schn, FF_ImgChanType dchn)
Description: The data from channel "schn" in image "srcimg"
are copied to channel "dchn" in image "destimg".
If width or height of the "srcimg" and "destimg"
differ, "srcimg" and "destimg" are aligned at the
lower left corner, and areas in "destimg", which
are not covered by "srcimg", are not affected by
IP_CopyChannel.
The current drawing color, mode and mask have no
effect on IP_CopyChannel.
Return value: UT_True if successful, else UT_False.
Name: IP_CopyImage
Usage: Copy the pixel data of one image into
another image.
Synopsis: UT_Bool IP_CopyImage
(IP_ImageId srcimg, IP_ImageId destimg)
Description: The data from all channels in image "srcimg"
are copied to image "destimg".
If width or height of the "srcimg" and "destimg"
differ, "srcimg" and "destimg" are aligned at the
lower left corner, and areas in "destimg", which
are not covered by "srcimg", are not affected by
IP_CopyImage.
The current drawing color, mode and mask have no
effect on IP_CopyImage.
Return value: UT_True if successful, else UT_False.
See also: CopyChannel
Name: IP_CopyRect
Usage: Copy the pixels inside a rectangular source region in
an image, to a destination region in another image.
Synopsis: void IP_CopyRect
(IP_ImageId srcimg, IP_ImageId destimg,
Int32 xs1, Int32 ys1, Int32 xs2, Int32 ys2,
Int32 xd1, Int32 yd1)
Description: One corner of the source region is at position
(xs1, ys1) in image "srcimg". The diagonally opposite
corner of the source region is at position (xs2, ys2).
The corner of the destination region, which corresponds
to (xs1, ys1) in the source region, is at position
(xd1, yd1) in image "destimg".
The current drawing color, mode and mask select which
channels in the destination region are affected, and
how the data from the source region are combined with
the original data in the destination region.
Note: The source and destination regions may be
overlapping regions in the same image.
Return value: None.
See also: WrapRect
Name: IP_Correlate
Usage: Computes the correlation coefficient for two
sets of pixels.
Synopsis: UT_Bool IP_Correlate
(IP_ImageId img1,
IP_ImageId img2,
FF_ImgChanType chn,
Int32 xs1, Int32 ys1,
Int32 xs2, Int32 ys2,
Int32 xd1, Int32 yd1,
Float32 *r)
Description: Two pixel positions, (xs1, ys1) and (xs2, ys2),
specify the lower left and upper right corners of
a rectangle S in image "img1".
A second rectangle, D, in image "img2", with the
same size as S, is specified by the position of
the pixel at the lower left corner, (xd1, yd1).
IP_Correlate treats the pixel data in
channel "chn" of S and D as samples from two
random variables and computes their correlation
coefficient.
The correlation coefficient is in the range from
-1.0 to 1.0. It can be used as a measure for the
similarity of the patterns formed by the pixels in
the two rectangles.
For more detailed explanations of the correlation
coefficient and its significance to image processing,
see textbooks on these topics, e.g.
Robert V. Hook, Allen T. Craig,
"Introduction to Mathematical Statistics",
Macmillan Publishing Co.,
4th ed. 1978,
pp 73 ff.
Bernd Jaehne,
"Digitale Bildverarbeitung",
Springer Verlag,
2nd ed. 1991,
pp 225 ff.
Return value: If the correlation coefficient was computed
successfully, it is stored in "r", and
IP_Correlate returns UT_True.
If the correlation coefficient could not be computed,
because the variance of the pixel data in S or D is
zero, some value less than -1.0 is stored in "r", and
IP_Correlate returns UT_True; no error code is
set.
If the correlation coefficient could not be computed
because of an invalid parameter specification or an
arithmetic exception, IP_Correlate returns
UT_False; an error code is stored in UT_ErrNum.
See also: FindPattern
Name: IP_CrossDissolve
Usage: Cross-dissolve between two images.
Synopsis: UT_Bool IP_CrossDissolve
(IP_ImageId fgimg,
IP_ImageId bgimg,
IP_ImageId cmimg,
Float32 mix)
Description: IP_CrossDissolve cross-dissolves between image "fgimg"
and "bgimg". The result is stored in "cmimg":
1. Any gamma-correction in the input data is
compensated by performing an inverse gamma-
correction on the pixel data from "fgimg"
and "bgimg".
2. The the pixel data for "cmimg" are combined from
the data in "fgimg" and "bgimg" ("mix" should be
in the range from 0.0 to 1.0):
cm.pixel = fg.pixel * mix + bg.pixel * (1-mix)
3. The FF_ImgChanTypeGray, FF_ImgChanTypeRed,
FF_ImgChanTypeGreen, and FF_ImgChanTypeBlue channels
in "cmimg" are gamma-corrected according to the image
descriptor of "cmimg".
Notes:
- If necessary, "fgimg" or "bgimg" can be
identical to "cmimg", so that IP_CrossDissolve
overwrites one of the input images with the
result.
- IP_CrossDissolve does not write to any channels in
"cmimg" for which the drawing mask is "UT_False".
- IP_CrossDissolve does not write to the
FF_ImgChanTypeHoriSnr, FF_ImgChanTypeVertSnr and
FF_ImgChanTypeDepth channels in "cmimg",
even if the drawing mask for these channels is
"UT_True".
- For cross-dissolving, "fgimg", "bgimg" and
"cmimg" are aligned at the lower left corner.
If "cmimg" is wider or higher than "fgimg" or
"bgimg", IP_CrossDissolve does not change areas
in "cmimg" which are not covered by "fgimg" or
"bgimg".
- IP_CrossDissolve can be run concurrently on
multiple processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
Name: IP_CutOff
Usage: Apply a cut-off filter to an image.
Synopsis: UT_Bool IP_CutOff
(IP_ImageId img, Float32 tmin,
Float32 tmax)
Description: TBD
Return value: UT_True if succesfull, else UT_False.
See also: Threshold
Name: IP_DeleteImage
Usage: Delete an image.
Synopsis: void IP_DeleteImage (IP_ImageId img)
Description: Free all memory used for image "img".
Return value: None.
See also: NewImage
Name: IP_DepthBlur
Usage: Blurs an image according to a depth channel.
Synopsis: UT_Bool IP_DepthBlur
(IP_ImageId img, Float32 f, Float32 g,
Float32 mindepth, Float32 maxdepth)
Description: All channels in image "img", for which the current
drawing mask is "UT_True", are blurred:
The color of every pixel in "img" is distributed over
a rectangular area of "f" by "g" pixels using a box
filter.
Only pixels whose depth is between "mindepth" and
"maxdepth" are blurred.
Return value: UT_True if successful, else UT_False.
See also: Blur
Name: IP_Derivates
Usage: Computes differences between adjacent pixels.
Synopsis: UT_Bool IP_Derivates
(IP_ImageId srcimg,
FF_ImgChanType srcchn,
IP_ImageId destimg,
FF_ImgChanType hchn, FF_ImgChanType vchn,
UT_Bool wrap)
Description: For each pixel in channel "srcchn" of image "srcimg",
IP_Derivates computes the differences between the pixel
and its left and bottom neighbors. The result is stored
in the "hchn" and "vchn" channels of image "destimg":
hchn (x, y) = 0.5 + srcchn (x, y) - srcchn (x-1, y)
vchn (x, y) = 0.5 + srcchn (x, y) - srcchn (x, y-1)
The "wrap" flag determines the differences computed
at the left and bottom borders of the source image.
If "wrap" is set to UT_True, IP_Derivates assumes that
srcchn (-1, y) = srcchn (w-1, y) and
srcchn (x, -1) = srcchn (x, h-1),
where "w" and "h" are the width and height of "srcimg",
in pixels.
If "wrap" is set to UT_False, IP_Derivates assumes that
srcchn (-1, y) = srcchn (0, y) and
srcchn (x, -1) = srcchn (x, 0).
Return value: UT_True if succesful, else UT_False.
Name: IP_DiffChannel
Usage: Obtain the differences of two images.
Synopsis: UT_Bool IP_DiffChannel
(IP_ImageId img1, IP_ImageId img2,
FF_ImgChanType chn,
Int32 less1[256], Int32 less2[256])
Description: Channel "chn" of images "img1" and "img2"
is read to see how much they differ.
The following notation is used:
0 < val < 256:
less1[val] == sum "sum" pixels in image "img1"
have a channel value which
is "val" less than the value
of image "img2".
less2[val] == sum "sum" pixels in image "img2"
have a channel value which
is "val" less than the value
of image "img1".
val == 0:
less1[val] == sum "sum" pixels don't differ.
less2[val] always zero.
Note:
- Only channels in FF_ImgFmtTypeUByte are allowed.
- The two images must be equal in width and height.
Return value: UT_True if successful, else UT_False.
Name: IP_DifferenceImage
Usage: Generate the difference image of two images.
Synopsis: UT_Bool IP_DifferenceImage
(IP_ImageId src1, IP_ImageId src2, IP_ImageId dest,
UT_Bool useAbsValue)
Description: TBD
Return value: UT_True if succesful, else UT_False.
See also: MarkNonZeroPixels CopyRect
Name: IP_Dilatation
Usage: Dilatation (expansion) of bright areas of an image.
Synopsis: UT_Bool IP_Dilatation (IP_ImageId img, Int32 n)
Description: A three by three pixel wide dilatation filter is
applied "n" times to all channels in image "img"
for which the current drawing mask is "UT_True".
The dilatation filter expands bright areas in
the image and eliminates dark pixels.
Return value: UT_True if succesful, else UT_False.
See also: Erosion
Name: IP_DrawAALine
Usage: Draw an antialiased line.
Synopsis: void IP_DrawAALine
(IP_ImageId img,
Float32 x1, Float32 y1,
Float32 x2, Float32 y2,
const Float32 clr1[],
const Float32 clr2[])
Description: A line is drawn from position (x1, y1) to position
(x2, y2) in image "img". The unit for "x1" and "x2"
is the width of a pixel in "img"; the unit for "y1"
and "y2" is the height of a pixel.
The line's colors at (x1, y1) and (x2, y2) are taken
from "clr1" and "clr2"; the color at in-between
positions is interpolated linearly.
The current drawing mask selects which channels in
"img" will be affected by IP_DrawAALine. The current
drawing mode is ignored; IP_DrawModeAdd mode is used
instead.
Return value: None.
See also: DrawLine DrawAAPixel
Name: IP_DrawAAPixel
Usage: Draw an antialiased point.
Synopsis: void IP_DrawAAPixel
(IP_ImageId img,
Float32 x, Float32 y,
const Float32 clr[])
Description: A point is drawn at position (x, y) in image "img". The
units for "x" and "y" are width and height of a pixel
in "img".
The point's color is taken from "clr". The current
drawing mask selects which channels in "img" will be
affected by IP_DrawAAPixel. The current drawing mode
is ignored; IP_DrawModeAdd mode is used instead.
Return value: None.
See also: DrawPixel DrawAALine
Name: IP_DrawAAText
Usage: Draw an antialiased text string.
Synopsis: void IP_DrawAAText
(IP_ImageId img,
Float32 x, Float32 y,
const char str[],
const Float32 clr[])
Description: A text string, "str", is drawn into image "img". The
lower left corner of the first character in "str" is
drawn at position (x, y).
The text string's color is taken from "clr". The
current drawing mask selects which channels in "img"
will be affected by IP_DrawAAText. The current
drawing mode is ignored; IP_DrawModeAdd mode is used
instead.
Return value: None.
See also: DrawText
Name: IP_DrawBrush
Usage: Make a brush stroke.
Synopsis: UT_Bool IP_DrawBrush
(IP_ImageId img, IP_ImageId bsh,
Int32 xi, Int32 yi, Float32 intensity)
Description: Draw a brush stroke into image "img" at pixel (xi, yi).
The brush is defined in image "bsh".
The intensity (or pressure) of the stroke is
specified in "intensity". Valid intensity values
are in the range of (0.0, 1.0), where 1.0 means
full intensity.
The current drawing color and mask select which
channels in the image are affected, and how.
Notes:
- The brush shape is taken from the
"FF_ImgChanTypeGray" channel of image "bsh".
This channel has to be in "FF_ImgFmtTypeFloat"
format with values in the range of (0.0, 1.0).
- The origin of the brush is the lower left corner
of the brush image, i.e. (xi, y1) = bsh[0][0].
Return value: UT_True if successful, else UT_False.
See also: DrawBrushLine MergeBrush
Name: IP_DrawBrushLine
Usage: Draw a brushed line into an image.
Synopsis: void IP_DrawBrushLine
(IP_ImageId img, IP_ImageId bsh,
Int32 x1, Int32 y1, Int32 x2, Int32 y2,
Int32 nstroke, Float32 intensity)
Description: Draw a line from pixel (x1, y1) to pixel (x2, y2)
in image "img".
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Return value: None.
See also: DrawLine DrawBrush MergeBrush
Name: IP_DrawCircle
Usage: Draw a circle into an image.
Synopsis: void IP_DrawCircle
(IP_ImageId img, Int32 cx, Int32 cy, Int32 r,
UT_Bool fill)
Description: Draw a filled circle into image "img", if "fill" is
set to UT_True, otherwise draw a circle outline.
The center of the circle is at pixel (cx, cy).
The radius is given with "rx".
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Return value: None.
See also: DrawRect DrawEllipse
Name: IP_DrawEllipse
Usage: Draw an ellipse into an image.
Synopsis: void IP_DrawEllipse
(IP_ImageId img, Int32 cx, Int32 cy,
Int32 rx, Int32 ry, UT_Bool fill)
Description: Draw a filled ellipse into image "img", if "fill" is
set to UT_True, otherwise draw an ellipse outline.
The horizontal radius is given with "rx", the
vertical radius with "ry".
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Note: Outline drawing is currently not supported.
Return value: None.
See also: DrawRect DrawCircle
Name: IP_DrawLine
Usage: Draws a line into an image.
Synopsis: void IP_DrawLine
(IP_ImageId img, Int32 x1, Int32 y1,
Int32 x2, Int32 y2, Int32 stipple)
Description: Draws a line from pixel (x1, y1) to pixel (x2, y2)
in image "img".
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Return value: None.
See also: DrawPixel DrawBrushLine DrawAALine
Name: IP_DrawPixel
Usage: Draws a point at pixel (x, y) into an image.
Synopsis: void IP_DrawPixel (IP_ImageId img, Int32 x, Int32 y)
Description: Draws a point at pixel (x, y) in image "img".
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Return value: None.
See also: DrawAAPixel DrawLine GetPixel
Name: IP_DrawRect
Usage: Draw a filled rectangle into an image.
Synopsis: void IP_DrawRect
(IP_ImageId img, Int32 x1, Int32 y1,
Int32 x2, Int32 y2)
Description: Draw a filled rectangle into image "img". One corner
of the rectangle is located at pixel (x1, y1). The
diagonally opposite corner is at pixel (x2, y2).
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Return value: None.
See also: DrawLine
Name: IP_DrawText
Usage: Draw a text string into an image.
Synopsis: void IP_DrawText
(IP_ImageId img, Int32 x, Int32 y,
const char str[])
Description: Draw a text string, "str", into image "img". The
lower left corner of the first character drawn is at
position (x, y).
The current drawing color, mode and mask select which
channels in the image are affected, and how.
Return value: None.
See also: GetTextSize
Name: IP_Erosion
Usage: Erosion (contraction) of bright areas of an image.
Synopsis: UT_Bool IP_Erosion (IP_ImageId img, Int32 n)
Description: A three by three pixel wide erosion filter is
applied "n" times to all channels in image "img"
for which the current drawing mask is "UT_True".
The erosion filter contracts bright areas in
the image and eliminates bright pixels.
Return value: UT_True if succesful, else UT_False.
See also: Dilatation
Name: IP_FindPattern
Usage: Attempts to find a given pattern in an image.
Synopsis: UT_Bool IP_FindPattern
(IP_ImageId img1,
IP_ImageId img2,
FF_ImgChanType chn,
Int32 xs1, Int32 ys1,
Int32 xs2, Int32 ys2,
Int32 xd1, Int32 yd1,
Int32 xd2, Int32 yd2,
Float32 *xp, Float32 *yp,
Float32 *rp)
Description: Two pixel positions, (xs1, ys1) and (xs2, ys2),
specify the lower left and upper right corners of
a rectangle, S, in channel "chn" of image "img1".
A second rectangle, D, in channel "chn" of image
"img2", which must be at least as wide and high as
S, is specified by the positions of its lower left
and upper right corners, (xd1, yd1) and (xd2, yd2).
The pixel data in S form a pattern. IP_FindPattern
tries to find an occurrence of this pattern in the
pixel data in D:
The pixel at the lower left corner of S is aligned
with some pixel in D, and the correlation coefficient
of the pixels in S and the pixels in D at the same
positions is computed.
This process is repeated, shifting S across D pixel
by pixel, and computing the corresponding correlation
coefficients, until the maximum correlation between
S and D has been found.
The maximum correlation coeffcient, and the position
of the lower left corner of S (relative to the lower
left corner of "img2") are returned in "rp", "xp"
and "yp".
"Xp", "yp" and "rp" can be interpreted as follows:
The pattern formed by the pixels in S also occurs in D.
The lower left corner of the pattern's occurence in D
is at position (xp, yp).
"Rp" indicates how well the pattern and its occurrence
in D match. "Rp" is usually in the range from -1.0 to
1.0, with higher values indicating a better match.
"Rp" values of 0.0 and below suggest that the pattern
does not occur in D at all, and that the values of "xp"
and "yp" are not usable.
Notes:
- IP_FindPattern does not detect multiple occurences
of the pattern in D. If the pattern occurs more than
once, IP_FindPattern selects an arbitray occurrence
and returns its position.
- The computation time for IP_FindPattern is
proportional to the number of pixels in S and to
the number of pixels in D. Finding an occurrence
of a big pattern or searching a large area can be
a lengthy process. If the pattern to be found has
features significantly larger than a single pixel,
computation times can be reduced by scaling the
pattern and the region to be searched down to a
lower resolution and doing a rough search to limit
the search area before trying to find the exact
position of the original pattern in the original
image.
- IP_FindPattern can be run concurrently on multiple
processors; see IP_SetNumThreads.
Return value: If "xp", "yp" and "rp" were computed successfully,
IP_FindPattern returns UT_True.
If the search for the pattern failed because
the variance of the pixels in S or in D is zero,
some value less than -1.0 is stored in "r", and
IP_FindPattern returns UT_True; no error code is
set.
If the search failed because of an invalid
parameter specification or an arithmetic exception,
IP_FindPattern returns UT_False; an error code is
stored in UT_ErrNum.
See also: Correlate
Name: IP_Flicker
Usage: Prepare an image for display on interlaced video.
Synopsis: UT_Bool IP_Flicker (IP_ImageId img)
Description: Image "img" is filtered so that flickering is reduced
when the image is displayed on a video monitor with
interlaced scanning: The pixel data in each scan line
are mixed with the data from the scan line immediately
above.
The current drawing mask selects which channels in
the image are filtered.
Notes:
- The filtered image will look slightly blurred,
and it will be shifted vertically by 0.5 pixels.
- IP_Flicker can be run concurrently on multiple
processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
Name: IP_FlipDiagonal
Usage: Flip an image diagonally.
Synopsis: void IP_FlipDiagonal (IP_ImageId img)
Description: Image "img" is mirrored about the (x == y) axis, i.e.
pixel rows change into columns and columns change into
rows.
If width and height of "img" in pixels are not equal,
the original and the mirror image do not cover each
other completely, and pixels in the original image for
which no couterpart exists in the mirror image are not
changed by IP_FlipDiagonal.
Return value: None.
See also: FlipHorizontal FlipVertical
Name: IP_FlipHorizontal
Usage: Flip an image around the horizontal mid axis.
Synopsis: void IP_FlipHorizontal (IP_ImageId img)
Description: Flip an image around the horizontal (x) axis.
Return value: None.
See also: FlipDiagonal FlipVertical
Name: IP_FlipVertical
Usage: Flip an image around the vertical mid axis.
Synopsis: void IP_FlipVertical (IP_ImageId img)
Description: Flip an image around the vertical (y) axis.
Return value: None.
See also: FlipDiagonal FlipHorizontal
Name: IP_GenJuliaSet
Usage: Generate an image of a Julia set.
Synopsis: UT_Bool IP_GenJuliaSet
(IP_ImageId img, Float32 cr, Float32 ci,
Float32 rcen, Float32 icen, Float32 rlen,
Int32 numit, UInt8 rmap[], UInt8 gmap[],
UInt8 bmap[])
Description: img: Image with red, green and blue
channels in FF_ImgFmtTypeUByte format.
cr, ci: Real and imaginary part of the additive
constant.
rcen, icen: Real and imaginary part of the center
of the screen.
rlen: Length of the displayed interval in
real direction.
numit: Number of iterations per pixel.
rmap, gmap, bmap:
Array of 256 color values for the red,
green and blue channels.
Return value: UT_True if successful, else UT_False.
See also: GenMandelbrot
Name: IP_GenMandelbrot
Usage: Generate an image of a Mandelbrot set.
Synopsis: UT_Bool IP_GenMandelbrot
(IP_ImageId img, Float32 rcen, Float32 icen,
Float32 rlen, Int32 numit,
UInt8 rmap[], UInt8 gmap[], UInt8 bmap[])
Description: img: Image with red, green and blue
channels in FF_ImgFmtTypeUByte format.
rcen, icen: Real and imaginary part of the center
of the screen.
rlen: Length of the displayed interval in
real direction.
numit: Number of iterations per pixel.
rmap, gmap, bmap:
Array of 256 color values for the red,
green and blue channels.
Return value: UT_True if successful, else UT_False.
See also: GenJuliaSet
Name: IP_GenNoise
Usage: Fill one channel of an image with fractal noise.
Synopsis: UT_Bool IP_GenNoise
(IP_ImageId img, FF_ImgChanType chn,
Int32 seed, Int32 p, Int32 coh, Float32 z)
Description: Channel "chn" of image "img" is filled with fractal
noise: A pseudo-random value in the range from 0.0 to
1.0 is assigned to every pixel so that pixels, which
are close to each other, are likely to receive similar
values.
The fractal noise pattern is generated from a seed
value, "seed", for a pseudo-random number generator.
The pattern is three-dimensional, and the values
written into "img" represent a two-dimensional slice
of it. The position of the slice is selected by the
value of "z", so that sequences of slices from the
same noise pattern can be generated by stepping
through different "z" values.
The noise pattern is periodic in x, y, (i.e.
horizontal and vertical) and z direction with a
period length of (1 << p) pixels.
The "coh" parameter determines how coherent the noise
pattern is. The pattern becomes more and more
incoherent when "coh" increases. "Coh" should be in
the range from 0 to p-1.
Return value: UT_True if successful, else UT_False.
Name: IP_GetChanRange
Usage: Obtain the range of an image channel.
Synopsis: UT_Bool IP_GetChanRange
(IP_ImageId img, FF_ImgChanType chanType,
Float32 *minVal, Float32 *maxVal)
Description: Channel "chanType" of image "img" is scanned.
The minimum resp. maximum channel values are returned
in "minVal" resp. "maxVal".
Note: The values are always returned in floating point
format.
Return value: UT_True if successful, else UT_False.
Name: IP_GetChanStats
Usage: Obtain the medium value of an image channel.
Synopsis: UT_Bool IP_GetChanStats
(IP_ImageId img, FF_ImgChanType chanType,
Float32 *meanVal, Float32 *stdVec,
UInt32 *numPix, UT_Bool useMatte)
Description: Channel "chanType" of image "img" is scanned.
The arithmetic mean value of all pixels in that channel
is returned in parameter "meanVal".
The standard deviation is returned in "stdDev".
If "useMatte" is set to UT_True, only the pixels
with a matte value unequal to zero are taken into
consideration.
The number of pixels used to calculate the mean
value is returned in parameter "numPix". In the
simple case, when "useMatte" is UT_False, this value
equals to the product of the image width and height.
Note: The mean value and standard deviation are
always returned as floating point value, even
if the channel is of type FF_ImgFmtUByte.
Return value: UT_True if successful, else UT_False.
See also: GetChanRange
Name: IP_GetColorCorrect
Usage: Get the current color correction parameters.
Synopsis: void IP_GetColorCorrect
(Float32 *gamma,
CIE_hue *red,
CIE_hue *green,
CIE_hue *blue,
CIE_hue *white)
Description: IP_GetColorCorrect returns the current gamma and color
correction parameters.
Return value: None.
See also: SetColorCorrect
Name: IP_GetCompression
Usage: Get the current compression method.
Synopsis: void IP_GetCompression (FF_ImgComprType cmp[])
Description: IP_GetCompression returns the current compression
method in "cmp".
Return value: None.
See also: SetCompression
Name: IP_GetDepthRange
Usage: Obtain the depth range of an image.
Synopsis: UT_Bool IP_GetDepthRange
(IP_ImageId img,
Float32 *minVal, Float32 *maxVal)
Description: The depth channel of image "img" is scanned.
The minimum resp. maximum depth values are returned
in "minVal" resp. "maxVal".
Return value: UT_True if successful, else UT_False.
Name: IP_GetDrawColor
Usage: Get the current drawing color.
Synopsis: void IP_GetDrawColor (Float32 clr[])
Description: IP_GetDrawColor returns the current drawing color
in "clr".
Return value: None.
See also: SetDrawColor
Name: IP_GetDrawMask
Usage: Get the current drawing mask.
Synopsis: void IP_GetDrawMask (UT_Bool msk[])
Description: IP_GetDrawMask returns the current drawing mask
in "msk".
Return value: None.
See also: SetDrawMask
Name: IP_GetDrawMode
Usage: Get the current drawing mode.
Synopsis: void IP_GetDrawMode (IP_DrawModeType dm[])
Description: IP_GetDrawMode returns the current drawing mode in "dm".
Return value: None.
See also: SetDrawMode
Name: IP_GetFileInfo
Usage: Read the image descriptor from a file.
Synopsis: UT_Bool IP_GetFileInfo
(const char fname[],
FF_ImgHdr *desc,
FF_ImgFmtType fmt[])
Description: The header of pixel file "fname" is read. Width,
height, aspect ratio gamma factor and color correction
parameters of the image stored in the file are written
to "desc".
The pixel data formats of the channels stored in the
file are written to "fmt".
Note: If you are not interested in the file header, the
pixel data formats or in the change information, call
IP_GetFileInfo with a NULL pointer instead of "desc" or
"fmt".
Return value: UT_True if successful, else UT_False.
See also: GetImageInfo
Name: IP_GetFormat
Usage: Get the current pixel data format.
Synopsis: void IP_GetFormat (FF_ImgFmtType fmt[])
Description: IP_GetFormat returns the current pixel data format
in "fmt".
Return value: None.
See also: SetFormat
Name: IP_GetImageInfo
Usage: Read the image descriptor of an IP_ImageId.
Synopsis: void IP_GetImageInfo
(IP_ImageId img,
FF_ImgHdr *desc,
FF_ImgFmtType fmt[])
Description: The image descriptor (width, height, aspect ratio, gamma
factor and color correction parameters) of IP_ImageId
"img" are written to "desc".
The pixel data formats of the channels in "img"
are written to "fmt".
Note: If you are not interested in the image descriptor
or in the channel formats, call poImgDescr with a
NULL pointer instead of "desc" or "fmt".
Return value: None.
See also: GetFileInfo
Name: IP_GetNumThreads
Usage: Get the number of processors used for parallel processing.
Synopsis: Int32 IP_GetNumThreads (void)
Description: Some operating systems do not support the thread
concurrency mechanism on which the parallel image
operations are based. On these systems, all image
processing is done serially, regardless of the
number of processors specified with IP_SetNumThreads.
Return value: IP_GetNumThreads returns the current number of
processors allocated for parallel processing.
See also: SetNumThreads
Name: IP_GetPixel
Usage: Get the value of all channels of a pixel.
Synopsis: UT_Bool IP_GetPixel
(const IP_ImageId img,
Int32 x, Int32 y,
Float32 clr[])
Description: The value of all channels of pixel (x, y) in image
"img" is converted to FF_ImgFmtTypeFloat format and
written to "clr".
Return value: UT_True, if pixel is inside the boundaries of the image.
If (x, y) is outside the boundaries of the image the
content of "clr" is undefined and UT_False is returned.
See also: DrawPixel
Name: IP_GetRadianceRange
Usage: Obtain the radiance range of an image.
Synopsis: UT_Bool IP_GetRadianceRange
(IP_ImageId img,
Float32 *minVal, Float32 *maxVal)
Description: The radiance channel of image "img" is scanned.
The minimum resp. maximum radiance values are
returned in "minVal" resp. "maxVal".
Return value: UT_True if successful, else UT_False.
Name: IP_GetSample
Usage: Sample the value of a single data channel in
an image.
Synopsis: Float32 IP_GetSample
(IP_ImageId img,
FF_ImgChanType chn,
Float32 x,
Float32 y)
Description: Return the value of channel "chn" in image "img" at
position (x, y), converted to FF_ImgFmtTypeFloat format.
If (x, y) does not coincide with a pixel's center, the
value at position (x, y) is found by bilinear
interpolation from the four nearest pixel centers.
Return value: The value of channel "chn" in image "img" at position
(x, y), converted to FF_ImgFmtTypeFloat format.
If channel "chn" is of type FF_ImgFmtTypeNone, the
return value is always 0.0.
Name: IP_GetTemperatureRange
Usage: Obtain the temperature range of an image.
Synopsis: UT_Bool IP_GetTemperatureRange
(IP_ImageId img,
Float32 *minVal, Float32 *maxVal)
Description: The temperature channel of image "img" is scanned.
The minimum resp. maximum temperature values are
returned in "minVal" resp. "maxVal".
Return value: UT_True if successful, else UT_False.
Name: IP_GetTextSize
Usage: Get the width and height in pixels of a text string.
Synopsis: void IP_GetTextSize
(const char str[], Int32 *width, Int32 *height)
Description: Return the width and height, in pixels, of a text
string, "str".
Return value: None.
See also: DrawText
Name: IP_Histogram
Usage: Obtain a histogram of one channel of an image.
Synopsis: UT_Bool IP_Histogram
(IP_ImageId img, FF_ImgChanType chn, Int32 buf[256])
Description: A histogram of channel "chn" of image "img" is
generated. The result is returned in "buf".
A histogram shows the distribution of pixel values.
The range from 0.0 to 1.0 is scaled into the range
from 0 to 255; pixel values, which are less than 0
or greater than 255 after scaling, are clamped to
0 or 255. For every pixel, whose scaled value is "i",
buf[i] is incremented by 1.
For example, (buf[5] == 45) means that there are 45
pixels in the image, whose scaled pixel value is 5.
Return value: UT_True if successful, else UT_False.
Name: IP_Interlace
Usage: Interlace two video fields into one frame.
Synopsis: UT_Bool IP_Interlace
(IP_ImageId fld1,
IP_ImageId fld2,
IP_ImageId frm,
UT_Bool skip)
Description: Images "fld1" and "fld2" are taken as the first and
second field of an interlaced video image. The images
are combined into a full video frame. The result is
stored in image "frm".
If the "skip" flag is UT_True, only every second scan line
for "fld1" and "fld2" is used to construct the
interlaced frame.
If the "skip" flag is UT_False, all scan lines from "fld1"
and "fld2" are used.
Notes:
- For interlacing, "fld1", "fld2" and "frm" are aligned
at the upper left corner. The top scan line in "frm"
is always taken from image "fld1".
- IP_Interlace does not write to any channels in "frm" for
which the current drawing mask is set to UT_False.
Return value: UT_True if successful, else UT_False.
See also: Unlace
Name: IP_MarkNonZeroPixels
Usage: Mark all non-zero pixels of an image.
Synopsis: UT_Bool IP_MarkNonZeroPixels
(IP_ImageId src, IP_ImageId dest,
Int32 threshold, Int32 *numMarkedPixels)
Description: TBD
Return value: UT_True if succesful, else UT_False.
Name: IP_Median
Usage: Apply a median filter to an image.
Synopsis: UT_Bool IP_Median (IP_ImageId img)
Description: A three pixel wide median filter is applied,
first horizontally, then vertically, to all
channels in image "img" for which the current
drawing mask is "UT_True".
Return value: UT_True if succesful, else UT_False.
Name: IP_MedianSequence
Usage: Applay a median filter to an image sequence.
Synopsis: UT_Bool IP_MedianSequence
(IP_ImageId srcimg1,
IP_ImageId srcimg2,
IP_ImageId srcimg3,
IP_ImageId destimg)
Description: A median filter is applied to all channels in image
sequence "srcimg1", "srcimg2", "srcimg3", for which
the current drawing mask is "UT_True":
Corresponding pixel values in "srcimg1", "srcimg2" and
"srcimg3" are compared and the second-largest value is
stored in "destimg".
Return value: UT_True if succesful, else UT_False.
See also: Median
Name: IP_MergeBrush
Usage: Make a brush stroke to merge one image through another.
Synopsis: UT_Bool IP_MergeBrush
(IP_ImageId backimg, IP_ImageId foreimg,
IP_ImageId bsh,
Int32 xi, Int32 yi, Float32 intensity)
Description: Draw a brush stroke into image "foreimg" at
pixel (xi, yi) based upon the color information
found in image "backimg".
The brush is defined in image "bsh".
The intensity (or pressure) of the stroke is
specified in "intensity". Valid intensity values
are in the range of (0.0, 1.0), where 1.0 means
full intensity.
The current drawing mask select which
channels in the image are affected.
Return value: UT_True if successful, else UT_False.
See also: DrawBrush DrawBrushLine
Name: IP_NewImage
Usage: Create a new image.
Synopsis: IP_ImageId IP_NewImage
(Int32 width, Int32 height, Float32 aspect)
Description: Memory for an image with "width" by "height" pixels,
and with an aspect ratio of "aspect", is allocated.
The current pixel data format defines the format
for the channels in the new image.
The current color correction parameters define the
color correction parameters for the new image.
The colors of the pixels in the image are undefined.
Return value: An identifier for the new image if successful,
else NULL.
See also: DeleteImage
Name: IP_NewImageFromFile
Usage: Read an image from a file - simple version.
Synopsis: IP_ImageId IP_NewImageFromFile (const char fname[])
Description: A new IP_ImageId with the same width, height, aspect
ratio and pixel data formats as the image stored in
file "fname" is created. The pixel data in the file are
copied into the new IP_ImageId without stretching or
squashing and without gamma or color correction.
Return value: An identifier for the image read from the file
if successful, else NULL.
See also: WriteSimple ReadImage
Name: IP_ReadImage
Usage: Read an image from a file.
Synopsis: UT_Bool IP_ReadImage
(IP_ImageId img, const char fname[],
UT_Bool stretch, UT_Bool gamma, UT_Bool color)
Description: The pixel data stored in pixel file "fname" is are
read into image "img".
If "stretch" is UT_True, the pixels in the file are
stretched or squashed so that the width and height of
the image in the file become equal to width and height
of "img".
If "stretch" is UT_False, the image in the file is clipped
or padded with zeros in order to match the width and
height of "img".
If the "gamma" flag is UT_True, the image is gamma-
corrected while it is read from the file.
If the "color" floag is UT_True, the FF_ImgChanTypeRed,
FF_ImgChanTypeGreen and FF_ImgChanTypeBlue channels are
color corrected while they are read from the file.
Return value: UT_True if successful, else UT_False.
See also: NewImageFromFile WriteImage
Name: IP_RemapValues
Usage: Change one channel of an image by remapping the
pixel data with a lookup table.
Synopsis: UT_Bool IP_RemapValues
(IP_ImageId img, FF_ImgChanType chn,
Int32 lutsize, const Float32 lut[])
Description: The original value, "v", of channel "chn" of every
pixel in image "img" is mapped into a new value which
replaces the original pixel data:
v = f (v * (lutsize - 1))
"F" is a continuous and piecewise linear function so
that for all x in the range from 0 to (lutsize - 1)
f (floor(x)) == lut[floor(x)].
Return value: UT_True if successful, else UT_False.
Name: IP_Rotate
Usage: Rotate an image by -90, 90, 180 or 270 degrees.
Synopsis: void IP_Rotate (IP_ImageId srcImg,
IP_ImageId destImg, Int32 angle)
Description: Rotate an image by -90, 90, 180 or 270 degrees.
Return value: UT_True, if a valid angle was specified. Otherwise
UT_False.
See also: WarpFunct FlipHorizontal
Name: IP_ScaleRect
Usage: Copy the pixels inside a rectangular source region in
an image, to a destination region of possibly different
size in another image.
Synopsis: UT_Bool IP_ScaleRect
(IP_ImageId srcimg, IP_ImageId destimg,
Int32 xs1, Int32 ys1, Int32 xs2, Int32 ys2,
Int32 xd1, Int32 yd1, Int32 xd2, Int32 yd2,
UT_Bool pyr, UT_Bool gc)
Description: One corner of the source region is at position
(xs1, ys1) in image "srcimg". The diagonally
opposite corner of the source region is at
position (xs2, ys2).
The corner of the destination region, which
corresponds to (xs1, ys1) in the source region,
is at position (xd1, yd1) in image "destimg".
The diagonally opposite corner of the destination
region is at position (xd2, yd2).
The "pyr" flag selects the shape of the filter
mask applied to the stretched pixel data. "UT_True"
selects a pyramid-shaped mask; "UT_False" selects a
box-shaped mask.
If the "gc" flag is set, the stretched pixel data
are gamma-corrected according to the source and
destination images' gamma factors.
The current drawing color, mode and mask select which
channels in the destination region are affected, and
how the data from the source region are combined with
the original data in the destination region.
Note: The source and destination regions should not
be overlapping regions in the same image.
Return value: UT_True if successful, otherwise UT_False.
Name: IP_SetColorCorrect
Usage: Set the current color correction parameters.
Synopsis: UT_Bool IP_SetColorCorrect
(Float32 gamma,
const CIE_hue *red,
const CIE_hue *green,
const CIE_hue *blue,
const CIE_hue *white)
Description: IP_SetColorCorrect defines the current gamma and color
correction parameters, i.e. parameters written into
the header of any newly created images.
The parameters and their default values are:
gamma 2.0 Gamma factor of the frame
buffer / monitor combination
which will be used to display
images
red (0.670, 0.330) The location of the monitor's
pure red in the CIE x-y color
diagram; default is NTSC
standard primary red.
green (0.210, 0.710) The location of the monitor's
pure green; default is NTSC
standard primary green.
blue (0.140, 0.080) The location of the monitor's
pure blue; default is NTSC
standard primary blue.
white (0.313, 0.329) The location of the monitor's
white point; default is CIE
illuminant D6500, i.e. the
color of a black body at a
temperature of 6500 Kelvin.
Return value: IP_SetColorCorrect returns UT_True if it was successful,
else UT_False.
See also: GetColorCorrect
Name: IP_SetCompression
Usage: Set the current compression method.
Synopsis: UT_Bool IP_SetCompression
(const FF_ImgComprType cmp[])
Description: IP_SetCompression defines the current compression
method for all channels, i.e. the compression method
to be used when an image is written to a file:
Cmp[i] is the compression method to be applied to
channel number "i".
By default, the current compression method is
FF_ImgComprTypeNone for all channels.
Return value: IP_SetCompression returns UT_True if it was successful,
else UT_False.
See also: GetCompression
Name: IP_SetDrawColor
Usage: Set the current drawing color.
Synopsis: UT_Bool IP_SetDrawColor (const Float32 clr[])
Description: IP_SetDrawColor defines the current drawing color for
all channels, i.e. the color used when drawing into an
image takes place: The current drawing color for
channel number "i" is set to clr[i].
Drawing colors should be in the range from 0.0 to 1.0
for all channels except FF_ImgChanTypeHoriSnr,
FF_ImgChanTypeVertSnr, FF_ImgChanTypeDepth,
FF_ImgChanTypeTemperature and FF_ImgChanTypeRadiance.
For FF_ImgChanTypeHoriSnr and FF_ImgChanTypeVertSnr,
drawing "colors" must be in the range from -1.0 to +1.0.
For FF_ImgChanTypeDepth, drawing "colors" must be
greater than 0.0, as depth information is stored as the
reciprocal value.
By default, the current drawing color is 0.0 for all
channels.
Return value: IP_SetDrawColor returns UT_True if it was successful,
else UT_False.
See also: GetDrawColor
Name: IP_SetDrawMask
Usage: Set the current drawing mask.
Synopsis: UT_Bool IP_SetDrawMask (const UT_Bool msk[])
Description: IP_SetDrawMask defines the current drawing mask, i.e.
the mask selecting which channels will be affected by
functions drawing into an image:
Drawing into channel number "i" is allowed only if
msk[i] is UT_True.
By default, the current drawing mask is "UT_True" for
all channels.
Return value: IP_SetDrawMask returns UT_True if it was successful,
else UT_False.
See also: GetDrawMask
Name: IP_SetDrawMode
Usage: Set the current drawing mode.
Synopsis: UT_Bool IP_SetDrawMode
(const IP_DrawModeType dm[])
Description: IP_SetDrawMode defines the current drawing mode for
all channels, i.e. how the current drawing color is
combined with the orignal color of pixels when drawing
into an image takes place: Dm[i] is the current drawing
mode for channel number "i".
By default, the current drawing mode is
IP_DrawModeReplace for all channels.
Return value: IP_SetDrawMode returns UT_True if it was successful,
else UT_False.
See also: GetDrawMode
Name: IP_SetFormat
Usage: Set the current pixel data format.
Synopsis: UT_Bool IP_SetFormat
(const FF_ImgFmtType fmt[])
Description: IP_SetFormat defines the current pixel data
format for all channels, i.e. the format to be used for
the different channels when a new image is created.
When memory is allocated for channel number "i" of an
image, pixel data format fmt[i] is used.
By default, the current pixel data format is
FF_ImgFmtTypeNone for all channels except for
FF_ImgChanTypeRed, FF_ImgChanTypeGreen and
FF_ImgChanTypeBlue, for which
the default is FF_ImgFmtTypeUByte.
Return value: IP_SetFormat returns UT_True if it was successful,
else UT_False.
See also: GetFormat
Name: IP_SetNumThreads
Usage: Set the number of threads used for image processing.
Synopsis: UT_Bool IP_SetNumThreads (Int32 n)
Description: Some operating systems do not support the thread
concurrency mechanism on which the parallel image
operations are based. On these systems, all image
processing is done serially, regardless of the
number of processors specified with IP_SetNumThreads.
Return value: IP_SetNumThreads attempts to allocate "n" threads
for parallel operations on images. "N" must not be
less than 1. IP_SetNumThreads returns UT_True if it is
successful, else UT_False.
See also: GetNumThreads
Name: IP_ShearHorizontal
Usage: Shear an image horizontally.
Synopsis: UT_Bool IP_ShearHorizontal
(IP_ImageId img,
Float32 m,
Float32 t)
Description: See IP_ShearVertical for detailed description.
Return value: UT_True if successful, else UT_False.
See also: ShearVertical
Name: IP_ShearVertical
Usage: Shear an image vertically.
Synopsis: UT_Bool IP_ShearVertical
(IP_ImageId img,
Float32 m,
Float32 t)
Description: IP_ShearVertical shears all channels of image
"img", for which the current drawing mask is UT_True,
by displacing the pixels in "img" vertically:
Pixel (x, y) is moved to position (x, y + x*m + t).
IP_ShearHorizontal shears image "img" by displacing
the pixels horizontally:
Pixel (x, y) is moved to position (x + y*m + t, y).
Both, IP_ShearVertical and IP_ShearHorizontal, fill
regions in "img", which are not covered by the sheared
image, with the current drawing color.
Notes:
- "M" must be in the range from -1.0 to 1.0; "t" must
be in the range from (-2.0 * s) to (2.0 * s), where
"s" is the sum of the width and height of the image,
in pixels.
- Images can be shifted with sub-pixel precision using
IP_ShearVertical and IP_ShearHorizontal.
- IP_ShearVertical and IP_ShearHorizontal can
be employed to to rotate images by small angles.
Rotations by larger angles result in undesirable
scaling of the image. If an image with square
pixels is rotated by angle "phi", using shearing
operations, the image is scaled larger by a factor
"f", where
f = sqrt (1.0 + square (tan (phi))).
- IP_ShearVertical and IP_ShearHorizontal can
be run concurrently on multiple processors; see
IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
See also: ShearHorizontal
Name: IP_Threshold
Usage: Apply a threshold filter to an image.
Synopsis: UT_Bool IP_Threshold
(IP_ImageId src, IP_ImageId dest,
Float32 t, UT_Bool overwrite)
Description: TBD
Return value: UT_True if succesful, else UT_False.
See also: CutOff
Name: IP_Unlace
Usage: Extract one video field from an interlaced frame.
Synopsis: UT_Bool IP_Unlace (IP_ImageId frm, IP_ImageId fld,
UT_Bool odd, IP_UnlaceModeType mode)
Description: Every second scan line from image "frm" is copied into
image "fld". Depending on whether the "odd" flag is set
to "UT_True" or "UT_False", the odd-numbered or the even-
numbered scan lines are copied.
"Mode" specifies the field interpolation mode.
It can have the following values:
IP_UnlaceModeNone:
The scan lines of the selected field are copied
without any modification. Image "fld" should
have half the height of image "frm".
IP_UnlaceModeCopy:
Each scan line of the selected field is copied
twice. Image "fld" should have the same height
as image "frm".
IP_UnlaceModeInterpolate:
Each scanline of the selected field is copied
into "fld", which should have the same height
as image "frm". The scanlines of the other
field are computed by interpolating between
the upper and lower scanlines of the selected
field.
Notes:
- For field extraction, "fld" and "frm" are aligned at
the upper left corner. The top scan line in "frm" is
always considered even-numbered.
- IP_Unlace does not write to any channels in "fld"
for which the current drawing mask is set to UT_False.
Return value: UT_True if successful, else UT_False.
See also: Interlace
Name: IP_WarpFunct
Usage: Perform free-form deformations on an image.
Synopsis: UT_Bool IP_WarpFunct
(IP_ImageId srcimg,
IP_ImageId destimg,
UT_Bool (* dfunct)
(Float32, Float32, Float32 *, Float32 *),
UT_Bool (* dderiv)
(Float32, Float32,
Float32 *, Float32 *, Float32 *, Float32 *),
Int32 istep,
IP_FillModeType oor)
Description: Image "srcimg" is deformed. The result is stored
in image "destimg". The deformation is defined by
an application-supplied displacement function,
"dfunct", and its derivatives, "dderiv", which
should be defined as follows:
UT_Bool dfunct
(Float32 x, Float32 y,
Float32 *u, Float32 *v)
UT_Bool dderiv
(Float32 x, Float32 y,
Float32 *ux, Float32 *uy,
Float32 *vx, Float32 *vy)
Given a position (x, y) in the destination image,
"dfunct" computes the corresonding position (u, v)
in the source image.
"Dderiv" computes the four partial derivatives of
"dfunct"; given a position (x, y), "dderiv" returns
ux = du (x, y) / dx,
uy = du (x, y) / dy,
vx = dv (x, y) / dx,
vy = dv (x, y) / dy.
Evaluating "dfunct" and "dderiv" for every pixel can
be quite time-consuming. In order to save some time,
"dfunct" and "dderiv" are sampled only every "istep"
pixels; in-between values are interpolated linearly.
"Oor" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
image. The following values for "oor" are accepted:
IP_FillModeFill Pixels not covered by the input
image are filled with the
current drawing color.
IP_FillModeWrap The input image is repeated in
horizontal and vertical
direction so that the output
image is tiled with copies of
the input image.
IP_FillModeClip Input pixel coordinates are
clipped so that regions outside
the input image are filled with
the color of the nearest input
image pixel.
Notes:
- Right-handed coordinate systems are used for
positions in the source and destination images.
The lower left corner of "srcimg" and "destimg"
is at (0, 0); the upper right corner is at (1, 1).
- The return value of "dfunct" and "dderiv" should
normally be UT_True. Image warping is aborted if
either "dfunct" or "dderiv" returns UT_False.
- Parts of IP_WarpFunct can be run concurrently on multiple
processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
Name: IP_WarpKeypoint
Usage: Perform free-form deformations on an image.
Synopsis: UT_Bool IP_WarpKeypoint
(IP_ImageId srcimg,
IP_ImageId destimg,
Int32 nkey,
const Float32 xsrc[],
const Float32 ysrc[],
const Float32 xdest[],
const Float32 ydest[],
Int32 istep,
Float32 r,
IP_FillModeType oor)
Description: Image "srcimg" is deformed smoothly. The result is
stored in image "destimg". The deformation is defined
by a set of "nkey" key points:
The position of key point number "i" in "srcimg" is
(xsrc[i], ysrc[i]); (xdest[i], ydest[i]) defines the
position of the key point in "destimg".
The pixels from "srcimg" are displaced so that the
pixel at position (xsrc[i], ysrc[i]) arrives at
position (xdest[i], ydest[i]) in "destimg". The
displacement of pixels whose positions do not coincide
with some key point is smoothly interpolated from the
key points.
Interpolating smoothly between the key points can
be quite time-consuming. In order to save some time,
the interpolating function is sampled only every
"istep" pixels; in-between values are interpolated
linearly.
If "istep" is 1, the interpolation function is sampled
for every pixel and the resulting image looks as smooth
as possible. Setting "istep" to a value greater than 1
saves time, but the result looks less smooth.
"R" selects the smoothness of the function used to
interpolate between the key points:
If "r" is less than or equal to 0.0, interpolation is
very smooth, but changing one key point has a strong
effect on the whole image.
If "r" is greater than 0.0, a different interpolation
algorithm is used. The influence of key points is much
more limited to the area around the key points. "R"
should be somewhere around 1.0; interpolation becomes
smoother when "r" increases.
"Oor" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
image. The following values for "oor" are accepted:
IP_FillModeFill Pixels not covered by the input
image are filled with the
current drawing color.
IP_FillModeWrap The input image is repeated in
horizontal and vertical
direction so that the output
image is tiled with copies of
the input image.
IP_FillModeClip Input pixel coordinates are
clipped so that regions outside
the input image are filled with
the color of the nearest input
image pixel.
Notes:
- "Xsrc" and "ysrc" should be in the range from 0.0 to
1.0. The lower left corner of "srcimg" and "destimg"
is at position (0.0, 0.0); the upper right corner is
at position (1.0, 1.0).
- IP_WarpKeypoint can be run concurrently on multiple
processors; see IP_SetNumThreads.
Return value: UT_True if successful, else UT_False.
Name: IP_WrapRect
Usage: Copy the pixels inside a rectangular source region in
an image, to a destination region in another image.
Wrap the rectangle at the image borders.
Synopsis: void IP_WrapRect
(IP_ImageId srcimg, IP_ImageId destimg,
Int32 xs1, Int32 ys1, Int32 xs2, Int32 ys2,
Int32 sx, Int32 sy)
Description: One corner of the source region is at position
(xs1, ys1) in image "srcimg". The diagonally opposite
corner of the source region is at position (xs2, ys2).
The corner of the destination region, which corresponds
to (xs1, ys1) in the source region, is at position
(xs1+sx, ys1+sy) in image "destimg".
The current drawing color, mode and mask select which
channels in the destination region are affected, and
how the data from the source region are combined with
the original data in the destination region.
Note: The source and destination regions may NOT be
overlapping regions in the same image.
Return value: None.
See also: CopyRect
Name: IP_WriteImage
Usage: Write an image to a file.
Synopsis: UT_Bool IP_WriteImage
(IP_ImageId img,
const char fname[],
const char fmt[],
const char vsn[])
Description: Image "img" is written to pixel file "fname" using
pixel file format "fmt" and file format version "vsn".
The current pixel data format and the current
compression method select which channels will be
written to the file and in which format, and how the
pixel data will be compressed.
Return value: UT_True if successful, else UT_False.
See also: WriteSimple ReadImage
Name: IP_WriteSimple
Usage: Write an image to a file - simple version.
Synopsis: UT_Bool IP_WriteSimple
(IP_ImageId img,
const char fname[],
const char fmt[],
const char vsn[])
Description: Image "img" is written to pixel file "fname", using
file format "fmt" and format version "vsn".
The pixel data format in the file will be the same as
in "img" for all channels.
The current compression method is applied to all
channels.
Return value: UT_True if successful, else UT_False.
See also: NewImageFromFile WriteImage