poImg Reference Manual
The reference manual lists all available C functions and Tcl commands in alphabetical order.
The Tcl commands are mostly wrapped C functions. These commands are documented in accordance with the corresponding C function. They have a section called Tcl usage:, which explains the Tcl call method and parameters.
Note the following conventions in the Tcl usage documentation sections:
- A parameter postfix of :return indicates, that the parameter is not a real parameter, but the return value of the command.
- A parameter postfix of :out indicates, that the parameter is an output parameter, i.e. a Tcl variable with that name is created and filled with the appropriate value.
- Parameters of the form ?param=1.0? indicate an optional parameter and its default value.
A B C D E F G H I J M N P R S T U W
A
AddChannel
Name: IP_AddChannel
Usage: Add a channel to an image.
Synopsis: UT_Bool IP_AddChannel(
IP_ImageId img,
FF_ImgChanType channel,
FF_ImgFmtType formatType)
Tcl usage: $img AddChannel channel formatType
Description: Add a new channel "channel" to image "img".
The new channel is using pixel format "formatType".
The contents of the new channel are not initialized.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: DeleteChannel
AsPhoto
Name: IP_AsPhoto
Usage: Copy an image into a Tk photo image.
Synopsis: UT_Bool IP_AsPhoto(
Tcl_Interp *interp,
IP_ImageId srcImg,
const char *photoName,
FF_ImgChanType chanMapList[4],
Float32 gamma,
Float32 minValue, Float32 maxValue)
Tcl usage: $srcImg AsPhoto photoName ?chanMapList? ?gamma=1.0? ?minValue=-1.0? ?maxValue=-1.0?
Description: Copy image "srcImg" into Tk photo image "photoName".
Notes:
- To have more advanced floating point mapping,
ex. "Automatic Gain Control", use poImgUtil::AsPhoto.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: NewImageFromPhoto poImgUtil::AsPhoto
AsPhoto
Name: poImgUtil::AsPhoto
Usage: Create a Tk photo from an image.
Tcl usage: AsPhoto { img args }
img: image
args: Arguments for img::raw parser
Tcl usage: $srcImg AsPhoto photoName ?chanMapList? ?gamma=1.0? ?minValue=-1.0? ?maxValue=-1.0?
Description: Create a Tk photo from image "img".
The following img::raw options can be
supplied in parameter "args":
-verbose
-map
-min
-max
-gamma
-saturation
-cutoff
See the img::raw documentation for a description
of the options:
https://tkimg.sourceforge.net/RefMan/files/img-raw.html
Use this utility procedure only, if image "img" has
FLOAT channels and the improved mapping algorithms
like automatic gain control are needed.
Otherwise AsPhoto is much faster.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The Tk photo image.See also: AsPhoto
B
Blank
Name: IP_Blank
Usage: Blank all channels of an image.
Synopsis: void IP_Blank(IP_ImageId img)
Tcl usage: $img Blank
Description: All channels in image "img" are filled with zeroes.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: BlankRect
BlankRect
Name: IP_BlankRect
Usage: Blank all channels of an image rectangle.
Synopsis: void IP_BlankRect(
IP_ImageId img,
Int32 x1, Int32 y1,
Int32 x2, Int32 y2)
Tcl usage: $img BlankRect x1 y1 x2 y2
Description: Draw a filled rectangle of zeros into all
channels of image "img".
One corner of the rectangle is located at
pixel (x1, y1). The diagonally opposite
corner is at pixel (x2, y2).
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: Blank
Blend
Name: poImgUtil::Blend
Usage: Blend between two images.
Tcl usage: Blend { srcImg1 srcImg2 mixFactor }
srcImg1: image
srcImg2: image
mixFactor: float
Description: The pixel data for the result image are combined
from the data in "srcImg1" and "srcImg2".
"mixFactor" should be in the range from 0.0 to 1.0.
res.pixel = srcImg1.pixel * mixFactor +
srcImg2.pixel * (1-mixFactor)
Notes:
The blended image has the same format and size as
image "srcImg1".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The blended image.See also: BlendFunct BlendKeypoint
BlendFunct
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 (* mixFunct)
(Float32, Float32, Float32 *),
Int32 interpStep,
IP_FillModeType fillMode)
Tcl usage: $destImg BlendFunct srcImg1 srcImg2 d1Funct d1Deriv d2Funct d2Deriv mixFunct interpStep ?fillMode=FILL?
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 interpolation
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 mixFunct
(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), "d1Deriv" 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".
"mixFunct" 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", "mixFunct" 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 "interpStep"
pixels; in-between values are interpolated linearly.
"fillMode" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
images. The following values for "fillMode" 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 "mixFunct" 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.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: WarpFunct WarpKeypoint BlendKeypoint SetNumThreads
BlendKeypoint
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 numKeys,
const Float32 xsrc1List[],
const Float32 ysrc1List[],
const Float32 xsrc2List[],
const Float32 ysrc2List[],
const Float32 mixList[],
Int32 interpStep,
Float32 smoothness,
IP_FillModeType fillMode)
Tcl usage: $destImg BlendKeypoint srcImg1 srcImg2 numKeys xsrc1List ysrc1List xsrc2List ysrc2List mixList interpStep ?smoothness=0.0? ?fillMode=FILL?
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 "numKeys" key points:
The position of key point number "i" in "srcImg1" is
(xsrc1List[i], ysrc1List[i]); the key point's position in
"srcImg2" is (xsrc2List[i], ysrc2List[i]). The key point's
position in "destImg" is (xdest[i], ydest[i]), where
xdest[i] = xsrc1List[i] * mixList[i] + xsrc2List[i] * (1-mixList[i]);
ydest[i] = ysrc1List[i] * mixList[i] + ysrc2List[i] * (1-mixList[i]);
The color of the pixel at position (xdest[i], ydest[i])
in "destImg" is mixList[i] times the color of the pixel at
position (xsrc1List[i], ysrc1List[i]) in "srcImg1" plus
(1-mixList[i]) times the color of the pixel at position
(xsrc2List[i], ysrc2List[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
"interpStep" pixels; in-between values are interpolated
linearly.
If "interpStep" is 1, the interpolation function is sampled
for every pixel and the resulting image looks as smooth
as possible. Setting "interpStep" to a value greater than 1
saves time, but the result looks less smooth.
"smoothness" selects the smoothness of the function used to
interpolate between the key points:
If "smoothness" 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 "smoothness" 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. "smoothness"
should be somewhere around 1.0; interpolation becomes
smoother when "smoothness" increases.
"fillMode" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
images. The following values for "fillMode" 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:
- "xsrc1List", "ysrc1List", "xsrc2List" and "ysrc2List"
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).
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: WarpKeypoint WarpFunct BlendFunct SetNumThreads
Blur
Name: IP_Blur
Usage: Blur an image.
Synopsis: UT_Bool IP_Blur(
IP_ImageId img,
Float32 hori, Float32 vert)
Tcl usage: $img Blur hori ?vert=hori?
Description: The value of every pixel in "img" is distributed
over a rectangular area of "hori" by "vert" pixels
using a box filter.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: DepthBlur SetNumThreads
C
ChangeChannelGamma
Name: IP_ChangeChannelGamma
Usage: Change one channel of an image by gamma filtering
and linear scaling of the pixel data.
Synopsis: UT_Bool IP_ChangeChannelGamma(
IP_ImageId img,
FF_ImgChanType channel,
Float32 gamma, Float32 scale, Float32 offset)
Tcl usage: $img ChangeChannelGamma channel gamma ?scale=1.0? ?offset=0.0?
Description: Channel "channel" 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 "scale". "offset"
is added to the scaled value. The result replaces the
pixels original value:
v = pow (max (0, min (v, 1)), 1/gamma) * scale + offset
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: RemapChannelValues ComputeChannelDerivates
CompositeColorMatte
Name: IP_CompositeColorMatte
Usage: Composite two images using a color matte.
Synopsis: UT_Bool IP_CompositeColorMatte(
IP_ImageId fgImg,
IP_ImageId bgImg,
IP_ImageId destImg,
Float32 fr, Float32 fg, Float32 fb,
Float32 br, Float32 bg, Float32 bb,
UT_Bool fastMode,
IP_ImageId matteImg)
Tcl usage: $destImg CompositeColorMatte fgImg bgImg ?fr=1.0? ?fg=1.0? ?fb=1.0? ?br=1.0? ?bg=1.0? ?bb=1.0? ?fastMode=false? ?matteImg=None?
Description: Image "fgImg" is composited in front of image
"bgImg". The result is stored in "destImg".
If "matteImg" is NULL, the matte for compositing is
taken from image "fgImg". If "matteImg" is not NULL,
image "matteImg" supplies the matte.
1. The red, green and blue channels of all pixels
from "fgImg" are scaled by "fr", "fg" and "fb".
The red, green and blue channels of all pixels
from "bgImg" are scaled by "br", "bg" and "bb".
2. The red, green and blue channels for every pixel
in "destImg" are combined from the data in "fgImg"
and "bgImg":
if "matteImg" is not NUL:
cm.red = fg.red * mt.red_matte +
bg.red * (1-mt.red_matte);
cm.green = fg.green * mt.green_matte +
bg.green * (1-mt.green_matte);
cm.blue = fg.blue * mt.blue_matte +
bg.blue * (1-mt.blue_matte);
else
cm.red = fg.red +
bg.red * (1-fg.red_matte);
cm.green = fg.green +
bg.green * (1-fg.green_matte);
cm.blue = fg.blue +
bg.blue * (1-fg.blue_matte);
3. The FF_ImgChanTypeRedMatte, FF_ImgChanTypeGreenMatte
and FF_ImgChanTypeBlueMatte channels for every pixel
in "destImg" are combined from the data in "fgImg"
and "bgImg":
if "matteImg" is not NULL:
cm.red_matte = 1 -
(1-mt.red_matte) * (1-bg.red_matte);
cm.green_matte = 1 -
(1-mt.green_matte) * (1-bg.green_matte);
cm.blue_matte = 1 -
(1-mt.blue_matte) * (1-bg.blue_matte);
else
cm.red_matte = 1 -
(1-fg.red_matte) * (1-bg.red_matte);
cm.green_matte = 1 -
(1-fg.green_matte) * (1-bg.green_matte);
cm.blue_matte = 1 -
(1-fg.blue_matte) * (1-bg.blue_matte);
Notes:
- If necessary, "fgImg" or "bgImg" can be
identical to "destImg", so that IP_CompositeColorMatte
overwrites one of the input images with the result.
- IP_CompositeColorMatte does not write to the
FF_ImgChanTypeBrightness, FF_ImgChanTypeMatte,
FF_ImgChanTypeHoriSnr, FF_ImgChanTypeVertSnr and
FF_ImgChanTypeDepth channels in "destImg", even if the
drawing mask for these channels is set.
- For compositing, "fgImg", "bgImg" and
"destImg" are aligned at the lower left corner.
If "destImg" is wider or higher than "fgImg" or
"bgImg", IP_CompositeColorMatte does not change areas
in "destImg" which are not covered by "fgImg" or
"bgImg".
- If the "fastMode" 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.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: RGB
Float format: RGB
Return value: UT_True if successful, else UT_False.See also: CompositeMatte CompositeDepth CrossDissolve SetNumThreads
CompositeDepth
Name: IP_CompositeDepth
Usage: Composite two images using a depth matte.
Synopsis: UT_Bool IP_CompositeDepth(
IP_ImageId fgImg,
IP_ImageId bgImg,
IP_ImageId destImg)
Tcl usage: $destImg CompositeDepth fgImg bgImg
Description: Image "fgImg" and "bgImg" are combined into a new
image "destImg". 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
destImg.pixel = fgImg.pixel;
else
destImg.pixel = bgImg.pixel;
Notes:
- If necessary, "fgImg" or "bgImg" can be identical to
"destImg", so that IP_CompositeDepth overwrites one of
the input images with the result.
- For compositing, "fgImg", "bgImg" and "destImg" are
aligned at the lower left corner. If "destImg" is wider
or higher than "fgImg" or "bgImg", IP_CompositeDepth
does not change areas in "destImg" which are not
covered by "fgImg" or "bgImg".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: CompositeMatte CompositeColorMatte CrossDissolve SetNumThreads
CompositeMatte
Name: IP_CompositeMatte
Usage: Composite two images using a grayscale matte.
Synopsis: UT_Bool IP_CompositeMatte(
IP_ImageId fgImg,
IP_ImageId bgImg,
IP_ImageId destImg,
Float32 fr, Float32 fg, Float32 fb,
Float32 br, Float32 bg, Float32 bb,
UT_Bool fastMode,
IP_ImageId matteImg)
Tcl usage: $destImg CompositeMatte fgImg bgImg ?fr=1.0? ?fg=1.0? ?fb=1.0? ?br=1.0? ?bg=1.0? ?bb=1.0? ?fastMode=false? ?matteImg=None?
Description: Image "fgImg" is composited in front of image
"bgImg". The result is stored in "destImg".
If "matteImg" is NULL, the matte for compositing is
taken from image "fgImg". If "matteImg" is not NULL,
image "matteImg" supplies the matte.
1. The red, green and blue channels of all pixels
from "fgImg" are scaled by "fr", "fg" and "fb".
The red, green and blue channels of all pixels
from "bgImg" are scaled by "br", "bg" and "bb".
2. The brightness, red, green and blue channels
for every pixel in "destImg" are combined from the
data in "fgImg" and "bgImg":
if "matteImg" is NULL:
cm.bright =
fg.bright +
bg.bright * (1-fg.matte);
cm.red =
fg.red +
bg.red * (1-fg.matte);
cm.green =
fg.green +
bg.green * (1-fg.matte);
cm.blue =
fg.blue +
bg.blue * (1-fg.matte);
else
cm.bright =
fg.bright * mt.matte +
bg.bright * (1-mt.matte);
cm.red =
fg.red * mt.matte +
bg.red * (1-mt.matte);
cm.green =
fg.green * mt.matte +
bg.green * (1-mt.matte);
cm.blue =
fg.blue * mt.matte +
bg.blue * (1-mt.matte);
3. The FF_ImgChanTypeMatte channel for every pixel in
"destImg" is computed:
if "matteImg" is NULL:
cm.matte = 1 - (1-fg.matte) * (1-bg.matte);
else
cm.matte = 1 - (1-mt.matte) * (1-bg.matte);
Notes:
- If necessary, "fgImg" or "bgImg" can be
identical to "destImg", so that IP_CompositeMatte
overwrites one of the input images with the result.
- IP_CompositeMatte does not write to the
FF_ImgChanTypeRedMatte, FF_ImgChanTypeGreenMatte,
FF_ImgChanTypeBlueMatte, FF_ImgChanTypeHoriSnr,
FF_ImgChanTypeVertSnr and FF_ImgChanTypeDepth channels
in "destImg", even if the drawing mask for these
channels is set.
- For compositing, "fgImg", "bgImg" and
"destImg" are aligned at the lower left corner.
If "destImg" is wider or higher than "fgImg" or
"bgImg", IP_CompositeMatte does not change areas
in "destImg" which are not covered by "fgImg" or
"bgImg".
- If the "fastMode" flag is set to UT_True, and all pixel
data involved in the compositing are in
FF_ImgFmtTypeUByte format, IP_CompositeMatte 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.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: RGB, Brightness
Float format: RGB, Brightness
Return value: UT_True if successful, else UT_False.See also: CompositeColorMatte CompositeDepth CrossDissolve SetNumThreads
ComputeChannelDerivates
Name: IP_ComputeChannelDerivates
Usage: Compute differences between adjacent pixels.
Synopsis: UT_Bool IP_ComputeChannelDerivates(
IP_ImageId srcImg,
FF_ImgChanType srcChannel,
IP_ImageId destImg,
FF_ImgChanType horizontalChannel,
FF_ImgChanType verticalChannel,
UT_Bool wrap)
Tcl usage: $destImg ComputeChannelDerivates srcImg srcChannel horizontalChannel verticalChannel ?wrap=true?
Description: For each pixel in channel "srcChannel" of image "srcImg",
the differences between the pixel and its left and bottom
neighbors are computed.
The result is stored in the "horizontalChannel" and
"verticalChannel" channels of image "destImg":
horizontalChannel (x, y) = 0.5 + srcChannel (x, y) - srcChannel (x-1, y)
verticalChannel (x, y) = 0.5 + srcChannel (x, y) - srcChannel (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_ComputeChannelDerivates
assumes that
srcChannel (-1, y) = srcChannel (w-1, y) and
srcChannel (x, -1) = srcChannel (x, h-1),
where "w" and "h" are the width and height of "srcImg" in pixels.
If "wrap" is set to UT_False, IP_ComputeChannelDerivates
assumes that
srcChannel (-1, y) = srcChannel (0, y) and
srcChannel (x, -1) = srcChannel (x, 0).
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: ChangeChannelGamma RemapChannelValues
CopyChannel
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 srcChannel,
FF_ImgChanType destChannel)
Tcl usage: $destImg CopyChannel srcImg srcChannel destChannel
Description: The data from channel "srcChannel" in image "srcImg"
are copied to channel "destChannel" 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.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: CopyImage
CopyImage
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)
Tcl usage: $srcImg CopyImage destImg:return
$destImg CopyImage srcImg
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.
Tcl note: The function can be called in two ways.
1. The destination image is created by the Tcl wrapper
and returned by the function.
2. Direct mapping of the C function, where the destination
image has to be supplied by the caller. The caller is
responsible for correct image format and size.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: CopyChannel
CopyRect
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)
Tcl usage: $destImg CopyRect srcImg xs1 ys1 xs2 ys2 xd1 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".
Note: The source and destination regions may be
overlapping regions in the same image.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawRect BlankRect WrapRect
CorrelateChannel
Name: IP_CorrelateChannel
Usage: Compute the correlation coefficient for two
sets of pixels.
Synopsis: UT_Bool IP_CorrelateChannel(
IP_ImageId srcImg,
IP_ImageId destImg,
FF_ImgChanType channel,
Int32 xs1, Int32 ys1,
Int32 xs2, Int32 ys2,
Int32 xd1, Int32 yd1,
Float32 *correlationFactor)
Tcl usage: $destImg CorrelateChannel srcImg channel xs1 ys1 xs2 ys2 xd1 yd1 correlationFactor:return
Description: Two pixel positions, (xs1, ys1) and (xs2, ys2),
specify the lower left and upper right corners of
a rectangle S in image "srcImg".
A second rectangle, D in image "destImg" with the
same size as S, is specified by the position of
the pixel at the lower left corner, (xd1, yd1).
IP_CorrelateChannel treats the pixel data in
channel "channel" 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, 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.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: If the correlation coefficient was computed
successfully, it is stored in "correlationFactor" and
IP_CorrelateChannel returns UT_True.
No error code is set.
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 "correlationFactor"
and IP_CorrelateChannel 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_CorrelateChannel returns
UT_False. An error code is stored in UT_ErrNum.See also: FindChannelPattern
CreateBrushImage
Name: poImgUtil::CreateBrushImage
Usage: Create a brush image.
Tcl usage: CreateBrushImage { img channel }
img: image
channel: Channel type number or name
Description: Use channel "channel" of image "img" to
create a new image suitable as a brush image.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The brush image if successful. Otherwise an error is thrown.See also: DrawBrush
CreateChannelNoise
Name: IP_CreateChannelNoise
Usage: Fill one channel of an image with fractal noise.
Synopsis: UT_Bool IP_CreateChannelNoise(
IP_ImageId img,
FF_ImgChanType channel,
Int32 seed, Int32 period,
Int32 coherency, Float32 slice)
Tcl usage: $img CreateChannelNoise channel seed period coherency slice
Description: Channel "channel" 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 "slice", so that sequences of slices from the
same noise pattern can be generated by stepping
through different "slice" values.
The noise pattern is periodic in x, y, (i.e.
horizontal and vertical) and z direction with a
period length of (1 << period) pixels.
The "coherency" parameter determines how coherent the
noise pattern is. The pattern becomes more and more
incoherent when "coherency" increases.
"coherency" should be in the range from 0 to period-1.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All (Range [0.0, 1.0]
Return value: UT_True if successful, else UT_False.See also: JuliaSet Mandelbrot
CrossDissolve
Name: IP_CrossDissolve
Usage: Cross-dissolve between two images.
Synopsis: UT_Bool IP_CrossDissolve(
IP_ImageId fgImg,
IP_ImageId bgImg,
IP_ImageId destImg,
Float32 mixFactor)
Tcl usage: $destImg CrossDissolve fgImg bgImg mixFactor
Description: Cross-dissolve between image "fgImg"
and "bgImg". The result is stored in "destImg":
The pixel data for "destImg" are combined from
the data in "fgImg" and "bgImg" ("mixFactor" should be
in the range from 0.0 to 1.0):
cm.pixel = fg.pixel * mixFactor + bg.pixel * (1-mixFactor)
Notes:
- If necessary, "fgImg" or "bgImg" can be
identical to "destImg", so that IP_CrossDissolve
overwrites one of the input images with the
result.
- IP_CrossDissolve does not write to the
FF_ImgChanTypeHoriSnr, FF_ImgChanTypeVertSnr,
FF_ImgChanTypeDepth, FF_ImgChanTypeTemperature
and FF_ImgChanTypeRadiance channels in "destImg",
even if the drawing mask for these channels is set.
- For cross-dissolving, "fgImg", "bgImg" and
"destImg" are aligned at the lower left corner.
If "destImg" is wider or higher than "fgImg" or
"bgImg", IP_CrossDissolve does not change areas
in "destImg" which are not covered by "fgImg" or
"bgImg".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: RGB, Brightness
Float format: RGB, Brightness
Return value: UT_True if successful, else UT_False.See also: CompositeMatte CompositeColorMatte CompositeDepth SetNumThreads
CutOff
Name: IP_CutOff
Usage: Apply a cut-off filter to an image.
Synopsis: UT_Bool IP_CutOff(
IP_ImageId img,
Float32 thresholdMin,
Float32 thresholdMax)
Tcl usage: $img CutOff thresholdMin ?thresholdMax=1.0?
Description: Each pixel of image "img" less than "thresholdMin" is
set to 0. Each pixel larger than "thresholdMax" is set
to 255 (for UByte channels) resp. 1.0 (for Float channels).
All other pixels are left unmodified.
The threshold values must be in the range [0.0, 1.0].
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if succesfull, else UT_False.See also: Threshold
D
DeleteChannel
Name: IP_DeleteChannel
Usage: Delete a channel from an image.
Synopsis: UT_Bool IP_DeleteChannel(
IP_ImageId img,
FF_ImgChanType channel)
Tcl usage: $img DeleteChannel channel
Description: Free the memory used by channel "channel"
of image "img". The pixel format of the
deleted channel is set to FF_ImgFmtTypeNone.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: AddChannel
DeleteImage
Name: poImgUtil::DeleteImage
Usage: Delete one or more images.
Tcl usage: DeleteImg { args }
args: List of images
Description: Delete all images specified in list "args".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: NewImage
DepthBlur
Name: IP_DepthBlur
Usage: Blur an image according to a depth channel.
Synopsis: UT_Bool IP_DepthBlur(
IP_ImageId img,
Float32 hori, Float32 vert,
Float32 minDepth, Float32 maxDepth)
Tcl usage: $img DepthBlur hori ?vert=hori? ?minDepth=-1.0? ?maxDepth=-1.0?
Description: The value of every pixel in "img" is distributed
over a rectangular area of "hori" by "vert" pixels
using a box filter.
Only pixels whose depth is between "minDepth" and
"maxDepth" are blurred.
If the depth of all pixels is the same, no blurring
is done.
If "minDepth" is negative, the minimum depth of the
image is used instead.
If "maxDepth" is negative, the maximum depth of the
image is used instead.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: Blur SetNumThreads
DiffChannel
Name: IP_DiffChannel
Usage: Obtain the channel difference of two images.
Synopsis: UT_Bool IP_DiffChannel(
IP_ImageId srcImg1,
IP_ImageId srcImg2,
FF_ImgChanType channel,
Int32 lessList1[256],
Int32 lessList2[256])
Tcl usage: $srcImg1 DiffChannel srcImg2 channel lessList1:out lessList2:out
Description: Channel "channel" of images "srcImg1" and "srcImg2"
is read to see how much they differ.
The following notation is used:
0 < val < 256:
lessList1[val] == sum "sum" pixels in image "srcImg1"
have a channel value which
is "val" less than the value
of image "srcImg2".
lessList2[val] == sum "sum" pixels in image "srcImg2"
have a channel value which
is "val" less than the value
of image "srcImg1".
val == 0:
lessList1[val] == sum "sum" pixels don't differ.
lessList2[val] always zero.
Note:
- Only channels in FF_ImgFmtTypeUByte are allowed.
- The two images must be equal in width and height.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: No
Return value: UT_True if successful, else UT_False.See also: DifferenceImage
DifferenceImage
Name: IP_DifferenceImage
Usage: Generate a difference image of two images.
Synopsis: UT_Bool IP_DifferenceImage(
IP_ImageId srcImg1,
IP_ImageId srcImg2,
IP_ImageId destImg)
Tcl usage: $srcImg2 DifferenceImage srcImg1 destImg:return
$destImg DifferenceImage srcImg1 srcImg2
Description: The difference of all pixels of images "srcImg1"
and "srcImg2" is computed and stored in image "destImg":
destImg[x,y] = abs (srcImg1[x,y] - srcImg2[x,y])
Tcl note: The function can be called in two ways.
1. The destination image is created by the Tcl wrapper
and returned by the function.
2. Direct mapping of the C function, where the destination
image has to be supplied by the caller. The caller is
responsible for correct image format and size.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: MarkNonZeroPixels
Dilatation
Name: IP_Dilatation
Usage: Dilatation (expansion) of bright areas of an image.
Synopsis: UT_Bool IP_Dilatation(
IP_ImageId img,
Int32 count)
Tcl usage: $img Dilatation ?count=1?
Description: A three by three pixel wide dilatation filter is
applied "count" times to image "img".
The dilatation filter expands bright areas in
the image and eliminates dark pixels.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.
DrawAALine
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 colorList1[FF_NumImgChanTypes],
const Float32 colorList2[FF_NumImgChanTypes])
Tcl usage: $img DrawAALine x1 y1 x2 y2 colorList1 ?colorList2=colorList1?
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 "colorList1" and "colorList2".
The color at in-between positions is interpolated linearly.
Note:
- Draw mode IP_DrawModeAdd mode is used.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawLine DrawAAPixel DrawAAText
DrawAAPixel
Name: IP_DrawAAPixel
Usage: Draw an antialiased point.
Synopsis: void IP_DrawAAPixel(
IP_ImageId img,
Float32 x, Float32 y,
const Float32 colorList[FF_NumImgChanTypes])
Tcl usage: $img DrawAAPixel x y colorList
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 "colorList".
Note:
- Draw mode IP_DrawModeAdd mode is used.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawPixel DrawAALine DrawAAText
DrawAAText
Name: IP_DrawAAText
Usage: Draw an antialiased text string.
Synopsis: void IP_DrawAAText(
IP_ImageId img,
Float32 x, Float32 y,
const char *string,
const Float32 colorList[FF_NumImgChanTypes])
Tcl usage: $img DrawAAText x y string colorList
Description: A text string "string" is drawn into image "img".
The lower left corner of the first character in
"string" is drawn at position (x, y).
The text string's color is taken from "colorList".
Note:
- Draw mode IP_DrawModeAdd mode is used.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawText DrawAAPixel DrawAALine
DrawBrush
Name: IP_DrawBrush
Usage: Draw a brush stroke into an image.
Synopsis: UT_Bool IP_DrawBrush(
IP_ImageId img,
IP_ImageId brushImg,
Int32 x, Int32 y,
Float32 intensity)
Tcl usage: $img DrawBrush brushImg x y ?intensity=1.0?
Description: Draw a brush stroke into image "img" at pixel (x, y).
The brush is defined in image "brushImg".
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. Values outside of this range are
automatically clipped to 0.0 or 1.0.
Notes:
- The brush shape is taken from the
FF_ImgChanTypeBrightness channel of image "brushImg".
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.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: DrawBrushLine MergeBrush DrawPixel
DrawBrushLine
Name: IP_DrawBrushLine
Usage: Draw a line of brush strokes into an image.
Synopsis: void IP_DrawBrushLine(
IP_ImageId img,
IP_ImageId brushImg,
Int32 x1, Int32 y1, Int32 x2, Int32 y2,
Int32 strokes, Float32 intensity)
Tcl usage: $img DrawBrushLine brushImg x1 y1 x2 y2 ?strokes=1? ?intensity=1.0?
Description: Draw a line of brush strokes from pixel (x1, y1)
to pixel (x2, y2) in image "img".
See IP_DrawBrush for the requirements of a brush image.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawLine DrawBrush MergeBrush
DrawCircle
Name: IP_DrawCircle
Usage: Draw a circle into an image.
Synopsis: void IP_DrawCircle(
IP_ImageId img,
Int32 cx, Int32 cy,
Int32 radius, UT_Bool fill)
Tcl usage: $img DrawCircle cx cy radius ?fill=true?
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 by "radius".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawPixel DrawLine DrawRect DrawEllipse DrawBrush
DrawEllipse
Name: IP_DrawEllipse
Usage: Draw an ellipse into an image.
Synopsis: void IP_DrawEllipse(
IP_ImageId img,
Int32 cx, Int32 cy,
Int32 radius1, Int32 radius2,
UT_Bool fill)
Tcl usage: $img DrawEllipse cx cy radius1 radius2 ?fill=true?
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 by "radius1", the
vertical radius by "radius2".
Note: Outline drawing is currently not supported.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawPixel DrawLine DrawRect DrawCircle DrawBrush
DrawLine
Name: IP_DrawLine
Usage: Draw a line into an image.
Synopsis: void IP_DrawLine(
IP_ImageId img,
Int32 x1, Int32 y1,
Int32 x2, Int32 y2,
Int32 stipple)
Tcl usage: $img DrawLine x1 y1 x2 y2 ?stipple=1?
Description: Draw a line from pixel (x1, y1) to pixel (x2, y2)
in image "img". Draw a pixels of the line every
"stipple" time. A "stipple" value of 1 draws a
solid line.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawPixel DrawCircle DrawEllipse DrawBrushLine DrawText DrawAALine
DrawPixel
Name: IP_DrawPixel
Usage: Draw a point into an image.
Synopsis: void IP_DrawPixel(
IP_ImageId img,
Int32 x, Int32 y)
Tcl usage: $img DrawPixel x y
Description: Draw a point at pixel (x, y) in image "img".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawLine DrawCircle DrawEllipse DrawBrush DrawText DrawAAPixel GetPixel
DrawRect
Name: IP_DrawRect
Usage: Draw a rectangle into an image.
Synopsis: void IP_DrawRect(
IP_ImageId img,
Int32 x1, Int32 y1,
Int32 x2, Int32 y2,
UT_Bool fill)
Tcl usage: $img DrawRect x1 y1 x2 y2 ?fill=true?
Description: Draw a rectangle into image "img".
One corner of the rectangle is located at pixel (x1, y1).
The diagonally opposite corner is at pixel (x2, y2).
If "fill" is UT_True, the rectangle is filled,
otherwise only the outline is drawn.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawPixel DrawLine DrawCircle DrawEllipse DrawBrush DrawText
DrawReticle
Name: poImgUtil::DrawReticle
Usage: Draw a reticle into an image.
Tcl usage: DrawReticle { img holeSize numCircles circleRadius circleIncr }
img: image
holeSize: integer
numCircles: integer
circleRadius: integer
circleIncr: integer
Description: Draw a reticle into image "img".
A reticle consists of 2 horizontal and 2 vertical
lines positioned at the image center. If "holeSize"
is zero, the lines meet at the image center.
Otherwise a circle with diameter of "holeSize" is
drawn at the image center.
Additional circles can be specified by setting
"numCircles" to a value greater than zero. The
initial radius of the first circle is given with
"circleRadius". The radius of all other circles
is incremented by "circleIncr".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: DrawLine DrawCircle
DrawText
Name: IP_DrawText
Usage: Draw a text string into an image.
Synopsis: void IP_DrawText(
IP_ImageId img,
Int32 x, Int32 y,
const char *string)
Tcl usage: $img DrawText x y string
Description: Draw text string "string" into image "img".
The lower left corner of the first character
drawn is at position (x, y).
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: DrawAAText GetTextSize GetTextScale SetTextScale DrawPixel
E
Erosion
Name: IP_Erosion
Usage: Erosion (contraction) of bright areas of an image.
Synopsis: UT_Bool IP_Erosion(
IP_ImageId img,
Int32 count)
Tcl usage: $img Erosion ?count=1?
Description: A three by three pixel wide erosion filter is
applied "count" times to image "img".
The erosion filter contracts bright areas in
the image and eliminates bright pixels.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: Dilatation Median
F
FindChannelPattern
Name: IP_FindChannelPattern
Usage: Attempt to find a given pattern in an image.
Synopsis: UT_Bool IP_FindChannelPattern
(IP_ImageId srcImg1,
IP_ImageId srcImg2,
FF_ImgChanType channel,
Int32 xs1, Int32 ys1,
Int32 xs2, Int32 ys2,
Int32 xd1, Int32 yd1,
Int32 xd2, Int32 yd2,
Float32 *xp, Float32 *yp,
Float32 *rp)
Tcl usage: $srcImg1 FindChannelPattern srcImg2 channel xs1 ys1 xs2 ys2 xd1 yd1 xd2 yd2 xp:out yp:out rp:out
Description: Two pixel positions, (xs1, ys1) and (xs2, ys2),
specify the lower left and upper right corners of
a rectangle, S, in channel "channel" of image "srcImg1".
A second rectangle, D, in channel "channel" of image
"srcImg2", 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_FindChannelPattern
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 "srcImg2") 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_FindChannelPattern does not detect multiple occurences
of the pattern in D. If the pattern occurs more than
once, IP_FindChannelPattern selects an arbitray
occurrence and returns its position.
- The computation time for IP_FindChannelPattern 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.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: If "xp", "yp" and "rp" were computed successfully,
IP_FindChannelPattern returns UT_True.
No error code is set.
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 "rp" and
IP_FindChannelPattern returns UT_True.
No error code is set.
If the search failed because of an invalid
parameter specification or an arithmetic exception,
IP_FindChannelPattern returns UT_False.
An error code is stored in UT_ErrNum.See also: CorrelateChannel SetNumThreads
Flicker
Name: IP_Flicker
Usage: Prepare an image for display on interlaced video.
Synopsis: UT_Bool IP_Flicker(IP_ImageId img)
Tcl usage: $img Flicker
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.
Note:
- The filtered image will look slightly blurred,
and it will be shifted vertically by 0.5 pixels.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: Interlace Unlace SetNumThreads
FlipDiagonal
Name: IP_FlipDiagonal
Usage: Flip an image diagonally.
Synopsis: void IP_FlipDiagonal(IP_ImageId img)
Tcl usage: $img FlipDiagonal
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.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: FlipHorizontal FlipVertical Rotate90
FlipHorizontal
Name: IP_FlipHorizontal
Usage: Flip an image around the horizontal axis.
Synopsis: void IP_FlipHorizontal(IP_ImageId img)
Tcl usage: $img FlipHorizontal
Description: Flip an image around the horizontal (x) mid axis.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: FlipDiagonal FlipVertical Rotate90
FlipVertical
Name: IP_FlipVertical
Usage: Flip an image around the vertical axis.
Synopsis: void IP_FlipVertical(IP_ImageId img)
Tcl usage: $img FlipVertical
Description: Flip an image around the vertical (y) mid axis.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: FlipDiagonal FlipHorizontal Rotate90
G
GetChannelFormat
Name: IP_GetChannelFormat
Usage: Get the numeric value of a channel format name.
Synopsis: UT_Bool IP_GetChannelFormat(
const char *channelFormatName,
FF_ImgFmtType *channelFormat)
Tcl usage: poImageState GetChannelFormat channelFormatName channelFormat:return
Description: The numeric value of channel format name
"channelFormatName" is returned in "channelFormat".
Possible format names:
"NONE", "UBYTE", "FLOAT"
Return value: UT_True, if successful, otherwise UT_False.See also: GetChannelFormatName GetDrawModeType GetFillModeType GetChannelType GetUnlaceModeType
GetChannelFormatName
Name: IP_GetChannelFormatName
Usage: Get the name of a channel format.
Synopsis: const char *IP_GetChannelFormatName(
FF_ImgFmtType channelFormat)
Tcl usage: poImageState GetChannelFormatName channelFormat channelFormatName:return
Description: Possible channel format names:
"NONE", "UBYTE", "FLOAT"
Return value: A pointer to the name of the channel format.See also: GetChannelFormat GetDrawModeTypeName GetFillModeTypeName GetChannelTypeName GetUnlaceModeTypeName
GetChannelHistogram
Name: IP_GetChannelHistogram
Usage: Obtain a histogram of one channel of an image.
Synopsis: UT_Bool IP_GetChannelHistogram(
IP_ImageId img,
FF_ImgChanType channel,
Int32 histogramList[256])
Tcl usage: $img GetChannelHistogram channel histogramList:out
Description: A histogram of channel "channel" of image "img" is
generated. The result is returned in "histogramList".
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",
histogramList[i] is incremented by 1.
For example, (histogramList[5] == 45) means that there
are 45 pixels in the image, whose scaled pixel value is 5.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: GetChannelStats GetChannelRange
GetChannelRange
Name: IP_GetChannelRange
Usage: Obtain the range of an image channel.
Synopsis: UT_Bool IP_GetChannelRange(
IP_ImageId img,
FF_ImgChanType channel,
Int32 x1, Int32 y1,
Int32 x2, Int32 y2,
Float32 *minValue, Float32 *maxValue)
Tcl usage: $img GetChannelRange channel x1 y1 x2 y2 minValue:out maxValue:out
Description: Channel "channel" of image "img" is scanned.
If the values for rectangle "x1, y1" and "x2, y2"
are set to a negative value (eg. -1), the whole
image is used for scanning. Otherwise only the
pixels within the rectangle are considered.
The minimum resp. maximum channel values are returned
in "minValue" resp. "maxValue".
Note: The values are always returned in floating point
format.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: GetChannelStats GetChannelHistogram
GetChannelStats
Name: IP_GetChannelStats
Usage: Obtain statistics of an image channel.
Synopsis: UT_Bool IP_GetChannelStats(
IP_ImageId img,
FF_ImgChanType channel,
Int32 x1, Int32 y1,
Int32 x2, Int32 y2,
Float32 *meanValue,
Float32 *stdDev,
UInt32 *numPixels,
UT_Bool useMatte)
Tcl usage: $img GetChannelStats channel x1 y1 x2 y2 meanValue:out ?stdDev:out? ?numPixels:out? ?useMatte=false?
Description: Channel "channel" of image "img" is scanned.
If the values for rectangle "x1, y1" and "x2, y2"
are set to a negative value (eg. -1), the whole
image is used for scanning. Otherwise only the
pixels within the rectangle are considered.
The arithmetic mean value of all pixels in the
channel is returned in parameter "meanValue".
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 statistics
is returned in parameter "numPixels".
In the simple case, when "useMatte" is UT_False and
the whole image is considered, 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.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: GetChannelRange GetChannelHistogram
GetChannelType
Name: IP_GetChannelType
Usage: Get the numeric value of a channel type name.
Synopsis: UT_Bool IP_GetChannelType(
const char *channelTypeName,
FF_ImgChanType *channelType)
Tcl usage: poImageState GetChannelType channelTypeName channelType:return
Description: The numeric value of channel type name
"channelTypeName" is returned in "channelType".
Possible channel type names:
"NONE", "BW", "RED", "GREEN", "BLUE",
"MATTE", "REDMATTE", "GREENMATTE", "BLUEMATTE",
"HORINORMAL", "VERTNORMAL", "DEPTH",
"TEMPERATURE", "RADIANCE".
Return value: UT_True, if successful, otherwise UT_False.See also: GetChannelTypeName GetDrawModeType GetFillModeType GetChannelFormat GetUnlaceModeType
GetChannelTypeName
Name: IP_GetChannelTypeName
Usage: Get the name of a channel type.
Synopsis: const char *FF_ImgGetChannelTypeName(
FF_ImgChanType channelType)
Tcl usage: poImageState GetChannelTypeName channelType channelTypeName:return
Description: Possible channel type names:
"NONE", "BW", "RED", "GREEN", "BLUE",
"MATTE", "REDMATTE", "GREENMATTE", "BLUEMATTE",
"HORINORMAL", "VERTNORMAL", "DEPTH",
"TEMPERATURE", "RADIANCE"
"UNKNOWN" for invalid channel type.
Return value: A pointer to the name of the channel type.See also: GetChannelType GetDrawModeTypeName GetFillModeTypeName GetChannelFormatName GetUnlaceModeTypeName
GetChannelTypeNames
Name: poImgUtil::GetChannelTypeNames
Usage: Get all channel type names.
Tcl usage: GetChannelTypeNames {}
Description: Get all channel type names.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The channel type names as a list of strings.See also: poImgUtil::GetDefaultFormat SetFormat
GetColorCorrect
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)
Tcl usage: poImageState GetColorCorrect gamma:out ?rx:out? ?ry:out? ?gx:out? ?gy:out? ?bx:out? ?by:out? ?wx:out? ?wy:out?
Description: Get the current gamma and color correction parameters.
Return value: None.See also: SetColorCorrect GetDrawMask GetDrawMode GetDrawColor GetFormat PushState PopState
GetDefaultDrawColor
Name: poImgUtil::GetDefaultDrawColor
Usage: Get default draw color.
Tcl usage: GetDefaultDrawColor {}
Description: Get the default draw color.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The default draw color as a list of floats.See also: poImgUtil::GetDefaultDrawMask poImgUtil::GetDefaultDrawMode poImgUtil::GetDefaultFormat SetDrawColor
GetDefaultDrawMask
Name: poImgUtil::GetDefaultDrawMask
Usage: Get default draw mask.
Tcl usage: GetDefaultDrawMask {}
Description: Get the default draw mask.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The default draw mask as a list of booleans.See also: poImgUtil::GetDefaultDrawColor poImgUtil::GetDefaultDrawMode poImgUtil::GetDefaultFormat SetDrawMask
GetDefaultDrawMode
Name: poImgUtil::GetDefaultDrawMode
Usage: Get default draw mode.
Tcl usage: GetDefaultDrawMode {}
Description: Get the default draw mode.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The default draw mode as a list of enumeration
values: REPLACE ADD SUB XOR.See also: poImgUtil::GetDefaultDrawColor poImgUtil::GetDefaultDrawMask poImgUtil::GetDefaultFormat SetDrawMode
GetDefaultFormat
Name: poImgUtil::GetDefaultFormat
Usage: Get default pixel formats.
Tcl usage: GetDefaultFormat {}
Description: Get the default pixel formats.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The default formats as a list of format
enumeration values: NONE, UBYTE, FLOAT.See also: poImgUtil::GetDefaultDrawColor poImgUtil::GetDefaultDrawMask poImgUtil::GetDefaultFormat SetDrawMode
GetDrawColor
Name: IP_GetDrawColor
Usage: Get the current draw color.
Synopsis: void IP_GetDrawColor(
Float32 drawColorList[FF_NumImgChanTypes])
Tcl usage: poImageState GetDrawColor drawColorList:out
Description: Get the current draw color in "drawColorList".
Return value: None.See also: SetDrawColor GetDrawMask GetDrawMode GetColorCorrect GetFormat PushState PopState
GetDrawMask
Name: IP_GetDrawMask
Usage: Get the current draw mask.
Synopsis: void IP_GetDrawMask(
UT_Bool drawMaskList[FF_NumImgChanTypes])
Tcl usage: poImageState GetDrawMask drawMaskList:out
Description: Get the current draw mask in "drawMaskList".
Return value: None.See also: SetDrawMask GetDrawColor GetDrawMode GetColorCorrect GetFormat PushState PopState
GetDrawMode
Name: IP_GetDrawMode
Usage: Get the current draw mode.
Synopsis: void IP_GetDrawMode(
IP_DrawModeType drawModeList[FF_NumImgChanTypes])
Tcl usage: poImageState GetDrawMode drawModeList:out
Description: Get the current draw mode in "drawModeList".
Return value: None.See also: SetDrawMode GetDrawMask GetDrawColor GetColorCorrect GetFormat PushState PopState
GetDrawModeType
Name: IP_GetDrawModeType
Usage: Get the numeric value of a draw mode name.
Synopsis: UT_Bool IP_GetDrawModeType(
const char *drawModeTypeName,
IP_DrawModeType *drawModeType)
Tcl usage: poImageState GetDrawModeType drawModeTypeName drawModeType:return
Description: The numeric value of draw mode name "drawModeTypeName"
is returned in "drawModeType".
Possible draw mode names:
"REPLACE", "ADD", "SUB", "XOR"
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: UT_True, if successful, otherwise UT_False.See also: GetDrawModeTypeName GetChannelType GetFillModeType GetChannelFormat GetUnlaceModeType
GetDrawModeTypeName
Name: IP_GetDrawModeTypeName
Usage: Get the name of a draw mode type.
Synopsis: const char *IP_GetDrawModeTypeName(
IP_DrawModeType drawModeType)
Tcl usage: poImageState GetDrawModeTypeName drawModeType drawModeTypeName:return
Description: Possible draw mode type names:
"REPLACE", "ADD", "SUB", "XOR"
"UNKNOWN" for invalid draw mode type.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: A pointer to the name of the draw mode type.See also: GetDrawModeType GetChannelTypeName GetFillModeTypeName GetChannelFormatName
GetFileFormat
Name: IP_GetFileFormat
Usage: Read the image format from a file.
Synopsis: UT_Bool IP_GetFileFormat(
const char *fileName,
FF_ImgFmtType formatList[FF_NumImgChanTypes])
Tcl usage: poImageState GetFileFormat fileName formatList:out
Description: The header of pixel file "fileName" is read.
The pixel data formats of the channels stored in the
file are written to "formatList".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: GetFileInfo GetImageInfo
GetFileInfo
Name: IP_GetFileInfo
Usage: Read the image descriptor from a file.
Synopsis: UT_Bool IP_GetFileInfo(
const char *fileName,
FF_ImgHdr *desc)
Tcl usage: poImageState GetFileInfo fileName width:out height:out ?aspect:out? ?gamma:out? ?rx:out? ?ry:out? ?gx:out? ?gy:out? ?bx:out? ?by:out? ?wx:out? ?wy:out?
Description: The header of pixel file "fileName" is read. Width,
height, aspect ratio, gamma factor and color correction
parameters of the image stored in the file are written
to "desc".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: GetFileFormat GetImageInfo
GetFillModeType
Name: IP_GetFillModeType
Usage: Get the numeric value of a fill mode name.
Synopsis: UT_Bool IP_GetFillModeType(
const char *fillModeTypeName,
IP_FillModeType *fillModeType)
Tcl usage: poImageState GetFillModeType fillModeTypeName fillModeType:return
Description: The numeric value of fill mode name "fillModeTypeName"
is returned in "fillModeType".
Possible fill mode names:
"FILL", "WRAP", "CLIP"
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: UT_True, if successful, otherwise UT_False.See also: GetFillModeTypeName GetChannelType GetDrawModeType GetChannelFormat
GetFillModeTypeName
Name: IP_GetFillModeTypeName
Usage: Get the name of a fill mode type.
Synopsis: const char *IP_GetFillModeTypeName(
IP_FillModeType fillModeType)
Tcl usage: poImageState GetFillModeTypeName fillModeType fillModeTypeName:return
Description: Possible fill mode type names:
"REPLACE", "ADD", "SUB", "XOR"
"UNKNOWN" for invalid fill mode type.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: A pointer to the name of the fill mode type.See also: GetFillModeType GetChannelTypeName GetDrawModeTypeName GetChannelFormatName
GetFormat
Name: IP_GetFormat
Usage: Get the current pixel data format.
Synopsis: void IP_GetFormat(
FF_ImgFmtType formatList[FF_NumImgChanTypes])
Tcl usage: poImageState GetFormat formatList:out
Description: Get the current pixel data format in "formatList".
Return value: None.See also: SetFormat GetDrawMask GetDrawColor GetDrawMode GetColorCorrect PushState PopState
GetHistogram
Name: poImgUtil::GetHistogram
Usage: Get image histogram.
Tcl usage: GetHistogram { img description }
img: image
description: string, optional ("")
Description: Return the histogram of RGB(A) image "img" as a dictionary.
The dictionary has the following keys:
- "RED", "GREEN" and "BLUE", each containing a list of 256 values
representing the number of pixels with that color value.
- "width" and "height" containing the width and the height
of the supplied image.
- Key "description" can be specified as optional parameter.
If "description" is not specified or an empty string,
the identifier of "img" is used as the description.
If the image has a matte channel, additionally key "MATTE"
is set.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: RGB
Return Value: Image histogram as dictionary.See also: poImgUtil::ScaleHistogram GetChannelHistogram
GetImageFormat
Name: IP_GetImageFormat
Usage: Read the pixel data format of an image.
Synopsis: void IP_GetImageInfo(
IP_ImageId img,
FF_ImgFmtType formatList[FF_NumImgChanTypes])
Tcl usage: $img GetImageFormat formatList:out
Description: The pixel data formats of the channels in "img"
are written to "formatList".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: GetImageInfo GetFileFormat HasChannel
GetImageInfo
Name: IP_GetImageInfo
Usage: Read the descriptor of an image.
Synopsis: void IP_GetImageInfo(
IP_ImageId img,
FF_ImgHdr *desc)
Tcl usage: $img GetImageInfo width:out height:out ?aspect:out? ?gamma:out? ?rx:out? ?ry:out? ?gx:out? ?gy:out? ?bx:out? ?by:out? ?wx:out? ?wy:out?
Description: The image descriptor (width, height, aspect ratio,
gamma factor and color correction parameters) of
image "img" are written to "desc".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: None.See also: GetImageFormat GetFileInfo HasChannel
GetImageStats
Name: poImgUtil::GetImageStats
Usage: Get image statistics.
Tcl usage: GetImageStats { img x1 y1 x2 y2 }
img: image
x1: integer, optional (-1)
y1: integer, optional (-1)
x2: integer, optional (-1)
y2: integer, optional (-1)
Description: Return a dictionary containing image statistics of an
RGB(A) image. If the image does not contain red, green
and blue channels, an error is thrown.
The returned dictionary has the following keys:
- "min RED" "min GREEN" "min BLUE" containing the minimum
values of the corresponding channels.
- "max RED" "max GREEN" "max BLUE" containing the maximum
values of the corresponding channels.
- "mean RED" "mean GREEN" "mean BLUE" containing the mean
values of the corresponding channels.
- "std RED" "std GREEN" "std BLUE" containing the standard
deviations of the corresponding channels.
- "num" containing the number of pixels of the image.
If the image has an additional matte channel, the
corresponding min, max, mean and std keys are set for "MATTE".
(x1, y1) and (x2, y2) define a rectangle for which the
image statistics are calculated. If these parameters are
not specified or all negative, the statistics is calculated
for the complete image.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: RGB
Return Value: Image statistics as dictionary.See also: GetChannelStats GetChannelRange
GetNumThreads
Name: IP_GetNumThreads
Usage: Get the number of threads used for parallel processing.
Synopsis: Int32 IP_GetNumThreads (void)
Tcl usage: poImageState GetNumThreads numThreads:return
Description: Return the number of threads used for parallel processing.
Return value: Return the current number of threads allocated
for parallel processing.See also: SetNumThreads HasThreadSupport
GetPixel
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 colorList[FF_NumImgChanTypes])
Tcl usage: $img GetPixel x y colorList:out
Description: The value of all channels of pixel (x, y) in image
"img" is converted to FF_ImgFmtTypeFloat format
and written to "colorList".
If a channel is of type FF_ImgFmtTypeNone, the
converted value is 0.0.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
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 "colorList" is undefined and
UT_False is returned.
GetSample
Name: IP_GetSample
Usage: Sample the value of all channels of a pixel.
Synopsis: UT_Bool IP_GetSample(
IP_ImageId img,
Float32 x, Float32 y,
Float32 colorList[FF_NumImgChanTypes])
Tcl usage: $img GetSample x y colorList:out
Description: The value of all channels at image position (x, y)
in image "img" is converted to FF_ImgFmtTypeFloat
format and written to "colorList".
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.
If a channel is of type FF_ImgFmtTypeNone, the
converted value is 0.0.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
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 "colorList" is undefined and
UT_False is returned.
GetTextScale
Name: IP_GetTextScale
Usage: Get the text scaling factor.
Synopsis: Int32 IP_GetTextScale(void)
Tcl usage: poImageState GetTextScale textScale:return
Description: Return the text scaling factor.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: Text scaling factor.See also: GetTextSize SetTextScale DrawText DrawAAText
GetTextSize
Name: IP_GetTextSize
Usage: Get the width and height in pixels of a text string.
Synopsis: void IP_GetTextSize(
const char *string,
Int32 *width, Int32 *height)
Tcl usage: poImageState GetTextSize string width:out height:out
Description: The width and height in pixels of text string "string"
is returned in "width" and "height".
If an empty string is given, "width" and "height"
are set to 0.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: None.See also: DrawText DrawAAText GetTextScale SetTextScale
GetUnlaceModeType
Name: IP_GetUnlaceModeType
Usage: Get the numeric value of an unlace mode name.
Synopsis: UT_Bool IP_GetUnlaceModeType
(const char *unlaceModeTypeName,
IP_UnlaceModeType *unlaceModeType)
Tcl usage: poImageState GetUnlaceModeType unlaceModeTypeName unlaceModeType:return
Description: The numeric value of unlace mode name
"unlaceModeTypeName" is returned in "unlaceModeType".
Possible unlace mode names:
"EXTRACT", "REPLICATE", "INTERPOLATE"
Return value: UT_True, if successful, otherwise UT_False.See also: GetUnlaceModeTypeName GetChannelType GetDrawModeType GetFillModeType GetChannelFormat
GetUnlaceModeTypeName
Name: IP_GetUnlaceModeTypeName
Usage: Get the name of an unlace mode type.
Synopsis: const char *IP_GetUnlaceModeTypeName(
IP_UnlaceModeType unlaceModeType)
Tcl usage: poImageState GetUnlaceModeTypeName unlaceModeType unlaceModeTypeName:return
Description: Possible unlace mode type names:
"EXTRACT", "REPLICATE", "INTERPOLATE"
"UNKNOWN" for invalid unlace mode type.
Return value: A pointer to the name of the unlace mode type.See also: GetUnlaceModeType GetChannelTypeName GetDrawModeTypeName GetFillModeTypeName GetChannelFormatName
H
HasChannel
Name: IP_HasChannel
Usage: Check existence of a channel in an image.
Synopsis: UT_Bool IP_HasChannel(
IP_ImageId img,
FF_ImgChanType channel)
Tcl usage: $img HasChannel channel bool:return
Description: Check, if channel "channel" exists in image "img".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if channel exists, else UT_False.See also: AddChannel GetImageInfo GetImageFormat
HasPhotoSupport
Name: HasPhotoSupport
Usage: Check Tk photo support.
Tcl usage: poImageState HasPhotoSupport bool:return
Description: Check, if poImg has been compiled to support
Tk photos. This is the default mode.
Support for Tk photos can be disabled at compile
time by setting configure flag:
--enable-tkphotos=off
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: If compiled with Tk photo support, return true.
Otherwise false.See also: MemCheck HasThreadSupport
HasThreadSupport
Name: HasThreadSupport
Usage: Check thread support.
Tcl usage: poImageState HasThreadSupport bool:return
Description: Check, if poImg has been compiled to support
threading. This is the default mode.
Support for threading can be disabled at compile
time by setting configure flag:
--enable-threads=off
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: If compiled with thread support, return true.
Otherwise false.See also: MemCheck HasPhotoSupport
I
Interlace
Name: IP_Interlace
Usage: Interlace two video fields into one frame.
Synopsis: UT_Bool IP_Interlace(
IP_ImageId fieldImg1,
IP_ImageId fieldImg2,
IP_ImageId frameImg,
UT_Bool skipLines)
Tcl usage: $frameImg Interlace fieldImg1 fieldImg2 ?skipLines=true?
Description: Images "fieldImg1" and "fieldImg2" 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 "frameImg".
If the "skipLines" flag is UT_True, only every second
scan line of "fieldImg1" and "fieldImg2" is used to
construct the interlaced frame. The field images must
have the same size as the frame image.
If the "skipLines" flag is UT_False, all scan lines
from "fieldImg1" and "fieldImg2" are used. The field
images must have half the height of the frame image.
Note:
- For interlacing, "fieldImg1", "fieldImg2" and "frameImg"
are aligned at the upper left corner. The top scan line
in "frameImg" is always taken from image "fieldImg1".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.
J
JuliaSet
Name: IP_JuliaSet
Usage: Generate an image of a Julia set.
Synopsis: UT_Bool IP_JuliaSet(
IP_ImageId img,
Float32 radd, Float32 iadd,
Float32 rcen, Float32 icen, Float32 rlen,
Int32 numIterations,
const UInt8 redColorList[256],
const UInt8 greenColorList[256],
const UInt8 blueColorList[256])
Tcl usage: $img JuliaSet radd iadd rcen icen rlen numIterations redColorList greenColorList blueColorList
Description: img: Image with red, green and blue
channels in FF_ImgFmtTypeUByte format.
radd, iadd: 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.
numIterations: Number of iterations per pixel.
redColorList
greenColorList
blueColorList: Array of 256 color values for the red,
green and blue channels.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: No
Return value: UT_True if successful, else UT_False.See also: Mandelbrot CreateChannelNoise
M
Mandelbrot
Name: IP_Mandelbrot
Usage: Generate an image of a Mandelbrot set.
Synopsis: UT_Bool IP_Mandelbrot(
IP_ImageId img,
Float32 rcen, Float32 icen, Float32 rlen,
Int32 numIterations,
const UInt8 redColorList[256],
const UInt8 greenColorList[256],
const UInt8 blueColorList[256])
Tcl usage: $img Mandelbrot rcen icen rlen numIterations redColorList greenColorList blueColorList
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.
numIterations: Number of iterations per pixel.
redColorList
greenColorList
blueColorList: Array of 256 color values for the red,
green and blue channels.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: No
Return value: UT_True if successful, else UT_False.See also: JuliaSet CreateChannelNoise
MarkNonZeroPixels
Name: IP_MarkNonZeroPixels
Usage: Mark all non-zero pixels of an image.
Synopsis: UT_Bool IP_MarkNonZeroPixels(
IP_ImageId srcImg,
IP_ImageId destImg,
Float32 threshold,
Int32 *numMarkedPixels)
Tcl usage: $srcImg MarkNonZeroPixels threshold numMarkedPixels:out destImg:return
$destImg MarkNonZeroPixels threshold numMarkedPixels:out srcImg
Description: Each pixel of image "srcImg" is checked, if its
value is larger than "threshold". If true, this pixel
is set in image "destImg" to the current draw color.
Otherwise the pixel value of "srcImg" is copied to "destImg".
The number of pixels marked with the current draw color is
returned in "numMarkedPixels".
Use this function in combination with IP_DifferenceImage
to check, if two images are identical.
Tcl note: The function can be called in two ways.
1. The destination image is created by the Tcl wrapper
and returned by the function.
2. Direct mapping of the C function, where the destination
image has to be supplied by the caller. The caller is
responsible for correct image format and size.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: DifferenceImage
Median
Name: IP_Median
Usage: Apply a median filter to an image.
Synopsis: UT_Bool IP_Median(IP_ImageId img)
Tcl usage: $img Median
Description: A three pixel wide median filter is applied to
image "img". First horizontally, then vertically.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: MedianSequence Blur
MedianSequence
Name: IP_MedianSequence
Usage: Apply a median filter to an image sequence.
Synopsis: UT_Bool IP_MedianSequence(
IP_ImageId srcImg1,
IP_ImageId srcImg2,
IP_ImageId srcImg3,
IP_ImageId destImg)
Tcl usage: $destImg MedianSequence srcImg1 srcImg2 srcImg3
Description: A median filter is applied to image sequence
"srcImg1", "srcImg2", "srcImg3".
Corresponding pixel values in "srcImg1", "srcImg2" and
"srcImg3" are compared and the second-largest value is
stored in "destImg".
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: Median
MemCheck
Name: MemCheck
Usage: Check memory usage.
Tcl usage: poImageState MemCheck bool:return
Description: Check, if all memory allocated by the poImg library
has been freed.
More detailed information regarding allocated memory
blocks can enabled at compile time by setting configure flag:
--enable-memdebug=on
The information is printed onto stdout.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: If all memory has been freed, return true.
Otherwise false.See also: HasPhotoSupport HasThreadSupport
MergeBrush
Name: IP_MergeBrush
Usage: Make a brush stroke to merge two images.
Synopsis: UT_Bool IP_MergeBrush(
IP_ImageId srcImg,
IP_ImageId destImg,
IP_ImageId brushImg,
Int32 x, Int32 y,
Float32 intensity)
Tcl usage: $destImg MergeBrush srcImg brushImg x y ?intensity=1.0?
Description: Draw a brush stroke into image "destImg" at
pixel (x, y) based upon the color information
found in image "srcImg".
The brush is defined in image "brushImg".
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.
See IP_DrawBrush for the requirements of a brush image.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: DrawBrush DrawBrushLine
N
NewImage
Name: IP_NewImage
Usage: Create a new image.
Synopsis: IP_ImageId IP_NewImage(
Int32 width, Int32 height,
Float32 aspect,
const char *options)
Tcl usage: poImage NewImage width height ?aspect? poImg:return
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 values of the pixels in the image are undefined.
Tcl note:
If "aspect" is not specified, it is set to width / height.
The "options" parameter is not exposed at
the Tcl level, but used internally by the C interface.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: An identifier for the new image if successful,
else NULL.NewImageFromFile NewImageFromPhoto
NewImageFromFile
Name: IP_NewImageFromFile
Usage: Read an image from a file.
Synopsis: IP_ImageId IP_NewImageFromFile(
const char *fileName,
const char *options)
Tcl usage: poImage NewImageFromFile fileName ?options? poImg:return
Description: A new image with the same width, height, aspect
ratio and pixel data formats as the image stored in
file "fileName" is created.
The pixel data in the file is copied into the new
image without scaling and without gamma or color
correction.
The possible option values are format dependent and are
identical to the values offered by the Img extension.
The following read options are recognized by all formats:
-verbose <bool>
-withalpha <bool>
The following read options are recognized by the RAW format:
-scanorder <TopDown|BottomUp>
-useheader <bool>
-skipbytes <bool>
-byteorder <Intel|Motorola>
-width <integer>
-height <integer>
-numchan <integer>
-pixeltype <double|float|int|short|byte>
Note, that the mapping options of the Img extension
"-map", "-min", "-max", "-gamma", "-saturation", "-cutoff"
are not supported, as the poImg extension supports
floating point images.
To display floating point images using photo images,
see the IP_AsPhoto or poImgUtil::AsPhoto command.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: An identifier for the image read from the file
if successful, else NULL.See also: NewImage NewImageFromPhoto ReadImage WriteImage AsPhoto poImgUtil::AsPhoto
NewImageFromFile
Name: poImgUtil::NewImageFromFile
Usage: Read an image from a file.
Tcl usage: NewImageFromFile { fileName options }
fileName: string
options: string, optional ("")
Tcl usage: poImage NewImageFromFile fileName ?options? poImg:return
Description: First try to read the image file using NewImageFromFile.
If this fails, try to read the image file using the Tk
"image create photo" command.
The option string "options" is transfered to the call
of NewImageFromFile.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The image if successful. Otherwise an error is thrown.See also: NewImageFromFile NewImageFromPhoto
NewImageFromPhoto
Name: IP_NewImageFromPhoto
Usage: Create an image from a Tk photo.
Synopsis: IP_ImageId IP_NewImageFromPhoto(
Tcl_Interp *interp,
const char *photoName)
Tcl usage: poImage NewImageFromPhoto photoName poImg:return
Description: The Tk photo "photoName" is copied into
a new image.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: No
Return value: An identifier for the new image if successful,
else NULL.See also: AsPhoto
P
PopState
Name: IP_PopState
Usage: Pop current state from stack.
Synopsis: Int32 IP_PopState (void)
Tcl usage: poImageState PopState stackIndex:return
Description: Pop current state from stack.
The state consists of the following members:
Pixel format.
Draw mask.
Draw color.
Draw mode.
Return value: The current stack index starting with zero.
If more IP_PopState functions have been called than
preceeding IP_PushState functions, -1 is returned.See also: PushState SetFormat SetDrawMask SetDrawColor SetDrawMode
PushState
Name: IP_PushState
Usage: Push current state onto stack.
Synopsis: Int32 IP_PushState (void)
Tcl usage: poImageState PushState stackIndex:return
Description: Push current state onto stack.
The state consists of the following members:
Pixel format.
Draw mask.
Draw color.
Draw mode.
Return value: The current stack index starting with zero.
If the maximum stack depth is exceed, -1 is returned.
The maximum stack depth is 10.See also: PopState GetFormat GetDrawMask GetDrawColor GetDrawMode
R
ReadImage
Name: IP_ReadImage
Usage: Read an image from a file.
Synopsis: UT_Bool IP_ReadImage
(IP_ImageId img,
const char *fileName,
const char *options)
Tcl usage: $img ReadImage fileName ?options?
Description: The pixel data stored in image file "fileName" is
read into image "img" using options "options".
If option "-scale" is true, the pixels in the file are
scaled, so that the width and height of the image in
the file becomes equal to width and height of "img".
If "-scale" is false, the image in the file is copied
into "img". If "img" is larger than the image in the
file, the regions not covered by the image in the
file are filled with zeros.
Default value of option "-scale" is false.
Note that the image scaling algorithm has been
designed to transform the pixel data quickly on the
fly, while the data is read from the image file.
The quality of the scaled picture is not optimal:
Aliasing may occur at high-contrast edges, especially
when the image is shrunk or blown up by some large
amount.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: NewImageFromFile NewImageFromPhoto WriteImage
RemapChannelValues
Name: IP_RemapChannelValues
Usage: Change one channel of an image by remapping the
pixel data with a lookup table.
Synopsis: UT_Bool IP_RemapChannelValues(
IP_ImageId img,
FF_ImgChanType channel,
Int32 lutSize, const Float32 lutList[])
Tcl usage: $img RemapChannelValues channel lutList
Description: The original value "v" of channel "channel" 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)) == lutList[floor(x)].
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: ChangeChannelGamma ComputeChannelDerivates
ReplaceTransparency
Name: poImgUtil::ReplaceTransparency
Usage: Replace transparency with color.
Tcl usage: ReplaceTransparency { img red green blue }
img: image
red: float
green: float
blue: float
Description: Replace all transparent pixels of image "img"
with color value ("red", "green", "blue").
The color values must be in the range [0.0, 1.0].
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGBA
Float format: RGBA
Return Value: RGB image with replaced transparency.See also: poImgUtil::SetTransparentColor CompositeMatte
Rotate
Name: poImgUtil::Rotate
Usage: Rotate an image by an arbitray angle.
Tcl usage: Rotate { srcImg destImg angle xcen ycen fillMode }
srcImg: image
destImg: image
angle: float
xcen, ycen: float, optional (0.5, 0.5)
fillMode: string, optional (FILL)
Description: Image "srcImg" is rotated counterclockwise by
"angle" around position (xcen, ycen). The result
is stored in image "destImg".
"fillMode" determines how pixels in "destImg",
which are not covered by the rotated version of
"srcImg" are treated.
Acceptable values for "fillMode" are FILL, CLIP, WRAP.
See the description of "WarpFunct" for details.
The x and y coordinates in "srcImg" and "destImg"
increase from left to right and from bottom to top.
The lower left corners are at (0.0, 0.0).
The upper right corners are at (1.0, 1.0).
"angle" is measured in radians.
Use procedure "poVecUtil::DegToRad" to convert an angle
given in degrees into radians.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return Value: None.See also: poImgUtil::Transform WarpFunct SetNumThreads
Rotate90
Name: IP_Rotate90
Usage: Rotate an image by -90, 90, 180 or 270 degrees.
Synopsis: void IP_Rotate90(
IP_ImageId srcImg,
IP_ImageId destImg,
Int32 angle)
Tcl usage: $srcImg Rotate90 angle destImg:return
Description: Rotate image "srcImg" by -90, 90, 180 or 270 degrees
and return the rotated image in "destImg".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True, if a valid angle was specified.
Otherwise UT_False.See also: FlipHorizontal FlipVertical FlipDiagonal
S
ScaleHistogram
Name: poImgUtil::ScaleHistogram
Usage: Get scaled image histogram.
Tcl usage: ScaleHistogram { histoDict height histoType }
histoDict: Histogram dictionary
height: integer
histoType: string, optional ("log")
Description: Return a scaled histogram dictionary based on
histogram dictionary "histoDict" as obtained by
poImgUtil::GetHistogram.
The values of histogram "histoDict" are scaled
either logarithmically or linearly, depending
on the value of "histoType".
Possible "histoType" values are: "log" or "lin".
The returned dictionary has 3 keys "RED", "GREEN" and "BLUE",
each containing a list of 256 values, so that the maximum value
is equal to "height".
Use this procedure to scale histogram values to fit into an
image or canvas of size "256 x height".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: RGB
Return Value: Scaled image histogram as dictionary.See also: poImgUtil::GetHistogram GetChannelHistogram
ScaleImage
Name: poImgUtil::ScaleImage
Usage: Scale an image.
Tcl usage: ScaleImage { img newWidth newHeight }
img: image
newWidth: integer
newHeight: integer
Description: Scale the image "img" to new size
"newWidth" by "newHeight" and return
the scaled image.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The scaled image if successful. Otherwise an error is thrown.See also: ScaleRect
ScalePhoto
Name: poImgUtil::ScalePhoto
Usage: Scale a Tk photo image.
Tcl usage: ScalePhoto { photo newWidth newHeight }
photo: Tk photo
newWidth: integer
newHeight: integer
Description: Scale the Tk photo "photo" to new size
"newWidth" by "newHeight" and return
the scaled Tk photo.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: The scaled image if successful. Otherwise an error is thrown.See also: ScaleRect NewImageFromPhoto
ScaleRect
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 usePyramidFilter,
UT_Bool gammaCorrect)
Tcl usage: $destImg ScaleRect srcImg xs1 ys1 xs2 ys2 xd1 yd1 xd2 yd2 ?usePyramidFilter=false? ?gammaCorrect=false?
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 "usePyramidFilter" flag selects the shape of the
filter mask applied to the scaled pixel data.
"UT_True" selects a pyramid-shaped mask.
"UT_False" selects a box-shaped mask.
If the "gammaCorrect" flag is set to "UT_True",
the scaled pixel data are gamma corrected according
to the source and destination images' gamma factors.
Note: The source and destination regions should not
be overlapping regions in the same image.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, otherwise UT_False.
SetColorCorrect
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)
Tcl usage: poImageState SetColorCorrect ?gamma? ?rx? ?ry? ?gx? ?gy? ?bx? ?by? ?wx? ?wy?
Description: Define 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 1.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.
Tcl note: If no parameter is specified, the current
color correction values are reset to the default values.
Return value: UT_True if successful, else UT_False.See also: GetColorCorrect SetDrawMask SetDrawMode SetDrawColor SetFormat PushState PopState
SetDrawColor
Name: IP_SetDrawColor
Usage: Set the current draw color.
Synopsis: UT_Bool IP_SetDrawColor(
const Float32 drawColorList[FF_NumImgChanTypes])
Tcl usage: poImageState SetDrawColor ?drawColorList?
Description: Define the current draw color for all channels,
i.e. the color used when drawing into an image
takes place: The current draw color for
channel number "i" is set to "drawColorList[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,
draw colors must be in the range from -1.0 to +1.0.
For FF_ImgChanTypeDepth, draw colors must be
greater than 0.0, as depth information is stored as the
reciprocal value.
By default, the current draw color is 0.0 for all
channels.
Tcl note: If "drawColorList" is not specified, the
current draw color is reset to the default values.
If "drawColorList" has less elements than NUMCHAN
(FF_NumImgChanTypes), the missing elements are filled
with zeros.
Return value: UT_True if successful, else UT_False.See also: GetDrawColor SetDrawMask SetDrawMode SetColorCorrect SetFormat PushState PopState
SetDrawColorAll
Name: poImgUtil::SetDrawColorAll
Usage: Set current draw color.
Tcl usage: SetDrawColorAll { value }
value: float
Description: Set the current draw color of all channels
to "value".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawColor poImgUtil::SetDrawColorChan poImgUtil::SetDrawColorRGB poImgUtil::SetDrawColorRGBA
SetDrawColorChan
Name: poImgUtil::SetDrawColorChan
Usage: Set current draw color.
Tcl usage: SetDrawColorChan { channel value reset }
channel: Channel type number or name
value: float
reset: bool, optional (false)
Description: Set the current draw color of channel
"channel" to "value".
If "reset" is false, only the draw color of
the specified channel is changed. Otherwise
the draw color of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawColor poImgUtil::SetDrawColorAll poImgUtil::SetDrawColorRGB poImgUtil::SetDrawColorRGBA poImgUtil::GetChannelTypeNames
SetDrawColorRGB
Name: poImgUtil::SetDrawColorRGB
Usage: Set current draw color.
Tcl usage: SetDrawColorRGB { r g b reset }
r, g, b: float
reset: bool, optional (false)
Description: Set the current draw color of the RGB
channels to "r", "g" and "b".
If "reset" is false, only the draw color of
the RGB channels is changed. Otherwise
the draw color of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawColor poImgUtil::SetDrawColorAll poImgUtil::SetDrawColorChan poImgUtil::SetDrawColorRGBA poImgUtil::GetChannelTypeNames
SetDrawColorRGBA
Name: poImgUtil::SetDrawColorRGBA
Usage: Set current draw color.
Tcl usage: SetDrawColorRGBA { r g b a reset }
r, g, b, a: float
reset: bool, optional (false)
Description: Set the current draw color of the RGBA
channels to "r", "g", "b" and "a".
If "reset" is false, only the draw color of
the RGBA channels is changed. Otherwise
the draw color of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawColor poImgUtil::SetDrawColorAll poImgUtil::SetDrawColorChan poImgUtil::SetDrawColorRGB poImgUtil::GetChannelTypeNames
SetDrawMask
Name: IP_SetDrawMask
Usage: Set the current draw mask.
Synopsis: UT_Bool IP_SetDrawMask(
const UT_Bool drawMaskList[FF_NumImgChanTypes])
Tcl usage: poImageState SetDrawMask ?drawMaskList?
Description: Define the current draw 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
drawMaskList[i] is UT_True.
By default, the current draw mask is UT_True for
all channels.
Tcl note: If "drawMaskList" is not specified, the
current draw mask is reset to the default values.
If "drawMaskList" has less elements than NUMCHAN
(FF_NumImgChanTypes), the missing elements are filled
with zeros.
Return value: UT_True if successful, else UT_False.See also: GetDrawMask SetDrawColor SetDrawMode SetColorCorrect SetFormat PushState PopState
SetDrawMaskAll
Name: poImgUtil::SetDrawMaskAll
Usage: Set current draw mask.
Tcl usage: SetDrawMaskAll { value }
value: bool
Description: Set the current draw mask of all channels
to "value".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMask poImgUtil::SetDrawMaskChan poImgUtil::SetDrawMaskRGB poImgUtil::SetDrawMaskRGBA
SetDrawMaskChan
Name: poImgUtil::SetDrawMaskChan
Usage: Set current draw mask.
Tcl usage: SetDrawMaskChan { channel value reset }
channel: Channel type number or name
value: bool
reset: bool, optional (false)
Description: Set the current draw mask of channel
"channel" to "value".
If "reset" is false, only the draw mask of
the specified channel is changed. Otherwise
the draw mask of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMask poImgUtil::SetDrawMaskAll poImgUtil::SetDrawMaskRGB poImgUtil::SetDrawMaskRGBA poImgUtil::GetChannelTypeNames
SetDrawMaskRGB
Name: poImgUtil::SetDrawMaskRGB
Usage: Set current draw mask.
Tcl usage: SetDrawMaskRGB { r g b reset }
r, g, b: bool
reset: bool, optional (false)
Description: Set the current draw mask of the RGB
channels to "r", "g" and "b".
If "reset" is false, only the draw mask of
the RGB channels is changed. Otherwise
the draw mask of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMask poImgUtil::SetDrawMaskAll poImgUtil::SetDrawMaskChan poImgUtil::SetDrawMaskRGBA poImgUtil::GetChannelTypeNames
SetDrawMaskRGBA
Name: poImgUtil::SetDrawMaskRGBA
Usage: Set current draw mask.
Tcl usage: SetDrawMaskRGBA { r g b a reset }
r, g, b, a: bool
reset: bool, optional (false)
Description: Set the current draw mask of the RGBA
channels to "r", "g", "b" and "a".
If "reset" is false, only the draw mask of
the RGBA channels is changed. Otherwise
the draw mask of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMask poImgUtil::SetDrawMaskAll poImgUtil::SetDrawMaskChan poImgUtil::SetDrawMaskRGB poImgUtil::GetChannelTypeNames
SetDrawMode
Name: IP_SetDrawMode
Usage: Set the current draw mode.
Synopsis: UT_Bool IP_SetDrawMode(
const IP_DrawModeType drawModeList[FF_NumImgChanTypes])
Tcl usage: poImageState SetDrawMode ?drawModeList?
Description: Define the current draw mode for all channels,
i.e. how the current draw color is combined with
the orignal color of pixels when drawing into an
image takes place: "drawModeList[i]" is the
current draw mode for channel number "i".
Enumeration IP_DrawModeType has the following members:
IP_DrawModeReplace: 0 Replace old color with current color
IP_DrawModeAdd : 1 Add old color and current color
IP_DrawModeSub : 2 Subtract old color from current color
IP_DrawModeXor : 3 Exclusive-or old color and current color
By default, the current draw mode is
IP_DrawModeReplace for all channels.
Tcl note: If "drawModeList" is not specified, the
current draw mode is reset to the default values.
If "drawModeList" has less elements than NUMCHAN
(FF_NumImgChanTypes), the missing elements are filled
with zeros.
The draw mode enumeration values can be accessed in
Tcl using the following global variables:
REPLACE ADD SUB XOR
Return value: UT_True if successful, else UT_False.See also: GetDrawMode SetDrawMask SetDrawColor SetColorCorrect SetFormat PushState PopState
SetDrawModeAll
Name: poImgUtil::SetDrawModeAll
Usage: Set current draw mode.
Tcl usage: SetDrawModeAll { value }
value: Draw mode number or name
Description: Set the current draw mode of all channels
to "value".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMode poImgUtil::SetDrawModeChan poImgUtil::SetDrawModeRGB poImgUtil::SetDrawModeRGBA
SetDrawModeChan
Name: poImgUtil::SetDrawModeChan
Usage: Set current draw mode.
Tcl usage: SetDrawModeChan { channel value reset }
channel: Channel type number or name
value: Draw mode number or name
reset: bool, optional (false)
Description: Set the current draw mode of channel
"channel" to "value".
If "reset" is false, only the draw mode of
the specified channel is changed. Otherwise
the draw mode of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMode poImgUtil::SetDrawModeAll poImgUtil::SetDrawModeRGB poImgUtil::SetDrawModeRGBA poImgUtil::GetChannelTypeNames
SetDrawModeRGB
Name: poImgUtil::SetDrawModeRGB
Usage: Set current draw mode.
Tcl usage: SetDrawModeRGB { r g b reset }
r, g, b: Draw mode number or name
reset: bool, optional (false)
Description: Set the current draw mode of the RGB
channels to "r", "g" and "b".
If "reset" is false, only the draw mode of
the RGB channels is changed. Otherwise
the draw mode of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMode poImgUtil::SetDrawModeAll poImgUtil::SetDrawModeChan poImgUtil::SetDrawModeRGBA poImgUtil::GetChannelTypeNames
SetDrawModeRGBA
Name: poImgUtil::SetDrawModeRGBA
Usage: Set current draw mode.
Tcl usage: SetDrawModeRGBA { r g b a reset }
r, g, b, a: Draw mode number or name
reset: bool, optional (false)
Description: Set the current draw mode of the RGBA
channels to "r", "g", "b" and "a".
If "reset" is false, only the draw mode of
the RGBA channels is changed. Otherwise
the draw mode of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetDrawMode poImgUtil::SetDrawModeAll poImgUtil::SetDrawModeChan poImgUtil::SetDrawModeRGB poImgUtil::GetChannelTypeNames
SetFormat
Name: IP_SetFormat
Usage: Set the current pixel data format.
Synopsis: UT_Bool IP_SetFormat(
const FF_ImgFmtType formatList[FF_NumImgChanTypes])
Tcl usage: poImageState SetFormat ?formatList?
Description: Define 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 formatList[i] is used.
Enumeration FF_ImgFmtType has the following members:
FF_ImgFmtTypeNone : 0 None. channel does not exist
FF_ImgFmtTypeUByte: 1 Unsigned 8-bit integers
FF_ImgFmtTypeFloat: 2 32-bit floating point numbers
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.
Tcl note: If "formatList" is not specified, the
current pixel data format is reset to the default values.
If "formatList" has less elements than NUMCHAN
(FF_NumImgChanTypes), the missing elements are filled
with zeros.
The format enumeration values can be accessed in
Tcl using the following global variables:
NONE UBYTE FLOAT
Return value: UT_True if successful, else UT_False.See also: GetFormat SetDrawMask SetDrawColor SetDrawMode SetColorCorrect PushState PopState
SetFormatAll
Name: poImgUtil::SetFormatAll
Usage: Set current pixel data format.
Tcl usage: SetFormatAll { value }
value: Pixel format number or name
Description: Set the current pixel data format of
all channels to "value".
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetFormat poImgUtil::SetFormatChan poImgUtil::SetFormatRGB poImgUtil::SetFormatRGBA
SetFormatChan
Name: poImgUtil::SetFormatChan
Usage: Set current pixel data format.
Tcl usage: SetFormatChan { channel value reset }
channel: Channel type number or name
value: Pixel format number or name
reset: bool, optional (false)
Description: Set the current pixel data format mode of
channel "channel" to "value".
If "reset" is false, only the format of
the specified channel is changed. Otherwise
the format of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetFormat poImgUtil::SetFormatAll poImgUtil::SetFormatRGB poImgUtil::SetFormatRGBA poImgUtil::GetChannelTypeNames
SetFormatRGB
Name: poImgUtil::SetFormatRGB
Usage: Set current pixel data format.
Tcl usage: SetFormatRGB { r g b reset }
r, g, b: Pixel format number or name
reset: bool, optional (false)
Description: Set the current pixel format mode of the
RGB channels to "r", "g" and "b".
If "reset" is false, only the format of
the RGB channels is changed. Otherwise
the format of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetFormat poImgUtil::SetFormatAll poImgUtil::SetFormatChan poImgUtil::SetFormatRGBA poImgUtil::GetChannelTypeNames
SetFormatRGBA
Name: poImgUtil::SetFormatRGBA
Usage: Set current pixel data format.
Tcl usage: SetFormatRGBA { r g b a reset }
r, g, b, a: Pixel format number or name
reset: bool, optional (false)
Description: Set the current pixel format mode of the
RGBA channels to "r", "g", "b" and "a".
If "reset" is false, only the format of
the RGBA channels is changed. Otherwise
the format of all other channels are
reset to the default values.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return Value: None.See also: SetFormat poImgUtil::SetFormatAll poImgUtil::SetFormatChan poImgUtil::SetFormatRGB poImgUtil::GetChannelTypeNames
SetNumThreads
Name: IP_SetNumThreads
Usage: Set the number of threads used for parallel processing.
Synopsis: UT_Bool IP_SetNumThreads (Int32 numThreads)
Tcl usage: poImageState SetNumThreads numThreads
Description: Attempt to allocate "numThreads" threads for parallel
operations on images.
If "numThreads" is set to zero (which is the default),
serial processing is used.
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 threads specified with IP_SetNumThreads.
The same is true, if the library was compiled without
thread support.
Return value: UT_True if successful, else UT_False.See also: GetNumThreads HasThreadSupport
SetTextScale
Name: IP_SetTextScale
Usage: Set the text scaling factor.
Synopsis: UT_Bool IP_SetTextScale(Int32 scale)
Tcl usage: poImageState SetTextScale scale
Description: Set the text scaling factor.
The text scaling factor must be an integer
greater than 0.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: N/A
Float format: N/A
Return value: UT_True if successful, else UT_False.See also: GetTextSize GetTextScale DrawText DrawAAText
SetTransparentColor
Name: poImgUtil::SetTransparentColor
Usage: Set transparency according to color.
Tcl usage: SetTransparentColor { img red green blue threshold }
img: image
red: float
green: float
blue: float
threshold: integer, optional (0)
Description: Set the transparency of all pixels of image "img"
having color value ("red", "green", "blue") to
fully transparent.
The color values must be in the range [0.0, 1.0].
"threshold" defines, how exact the color values have
to match. If "threshold" is zero, the color values
must match exactly.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGBA
Float format: RGBA
Return Value: None.See also: poImgUtil::ReplaceTransparency DifferenceImage
ShearHorizontal
Name: IP_ShearHorizontal
Usage: Shear an image horizontally.
Synopsis: UT_Bool IP_ShearHorizontal(
IP_ImageId img,
Float32 m,
Float32 t)
Tcl usage: $img ShearHorizontal m t
Description: See IP_ShearVertical for a detailed description.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: ShearVertical
ShearVertical
Name: IP_ShearVertical
Usage: Shear an image vertically.
Synopsis: UT_Bool IP_ShearVertical(
IP_ImageId img,
Float32 m,
Float32 t)
Tcl usage: $img ShearVertical m t
Description: IP_ShearVertical shears image "img" 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 draw 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 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))).
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: ShearHorizontal
Stamp
Name: IP_Stamp
Usage: Stamp an image on top of another image.
Synopsis: UT_Bool IP_Stamp(
IP_ImageId img, IP_ImageId stampImg,
Int32 x, Int32 y,
Float32 sr, Float32 sg, Float32 sb)
Tcl usage: $img Stamp stampImg x y ?sr=1.0? ?sg=1.0? ?sb=1.0?
Description: Image "stampImg" is copied onto image "img"
considering the matte channel of "stampImg".
If "stampImg" does not have a matte channel,
"stampImg" completely replaces the content of "img".
The lower left corner of "stampImg" is placed at
pixel position (x, y) in image "img". The red,
green and blue channels of image "stampImg" are
scaled according to the values specified in
"sr", "sg" and "sb". The scale values must be in
the range [0.0, 1.0].
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: RGB(A)
Float format: RGB(A)
Return value: UT_True if successful, else UT_False.See also: CompositeMatte ChangeChannelGamma SetNumThreads
T
Threshold
Name: IP_Threshold
Usage: Apply a threshold filter to an image.
Synopsis: UT_Bool IP_Threshold
(IP_ImageId srcImg, IP_ImageId destImg,
Float32 threshold, UT_Bool overwrite)
Tcl usage: $destImg Threshold srcImg threshold ?overwrite=false?
Description: Each pixel of image "srcImg" greater than "threshold" is
set to white (255) in image "destImg".
All other pixels in "destImg" are left unmodified,
if "overwrite" is "UT_False".
If "overwrite" is "UT_True", these pixels are set to black (0).
The "threshold" value must be in the range 0.0 .. 1.0.
Note:
- Only RGB channels in UByte format are supported.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: RGB
Float format: No
Return value: UT_True if successful, else UT_False.See also: CutOff
Transform
Name: poImgUtil::Transform
Usage: Apply a transformation matrix to an image.
Tcl usage: Transform { srcImg destImg tfm fillMode }
srcImg: image
destImg: image
tfm: Tfm2D (2-dim. transformation matrix)
fillMode: string, optional (FILL)
Description: Image "srcImg" is transformed geometrically according
to transformation matrix "tfm".
The result is stored in image "destImg":
Each pixel in destImg at position "d", is filled with
the color at position "s" in "srcImg", where
s = d * tfm.
If "s" is not within the boundaries of the source
image, "fillMode" determines what color is assigned
to the pixel at position "d".
Acceptable values for "fillMode" are FILL, CLIP, WRAP.
See the description of "WarpFunct" for details.
The x and y coordinates in "srcImg" and "destImg"
increase from left to right and from bottom to top.
The lower left corners are at (0.0, 0.0).
The upper right corners are at (1.0, 1.0).
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return Value: None.See also: poImgUtil::Rotate WarpFunct SetNumThreads
U
Unlace
Name: IP_Unlace
Usage: Extract one video field from an interlaced frame.
Synopsis: UT_Bool IP_Unlace(
IP_ImageId frameImg,
IP_ImageId fieldImg,
UT_Bool useOddRows,
IP_UnlaceModeType unlaceMode)
Tcl usage: $fieldImg Unlace frameImg ?useOddRows=true? ?unlaceMode=EXTRACT?
Description: Every second scan line from image "frameImg" is copied into
image "fieldImg". Depending on whether the "useOddRows" flag
is set to "UT_True" or "UT_False", the odd-numbered or the
even-numbered scan lines are copied.
"unlaceMode" specifies the field interpolation mode.
It can have the following values:
IP_UnlaceModeExtract:
The scan lines of the selected field are extracted
without any modification. Image "fieldImg" should
have half the height of image "frameImg".
IP_UnlaceModeReplicate:
Each scan line of the selected field is copied
twice. Image "fieldImg" should have the same height
as image "frameImg".
IP_UnlaceModeInterpolate:
Each scanline of the selected field is copied
into "fieldImg", which should have the same height
as image "frameImg". The scanlines of the other
field are computed by interpolating between
the upper and lower scanlines of the selected
field.
Note:
- For field extraction, "fieldImg" and "frameImg" are aligned
at the upper left corner. The top scan line in "frameImg"
is always considered even-numbered.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.
W
WarpFunct
Name: IP_WarpFunct
Usage: Perform free-form deformations on an image.
Synopsis: UT_Bool IP_WarpFunct(
IP_ImageId srcImg,
IP_ImageId destImg,
UT_Bool (* d1Funct)
(Float32, Float32, Float32 *, Float32 *),
UT_Bool (* d1Deriv)
(Float32, Float32,
Float32 *, Float32 *, Float32 *, Float32 *),
Int32 interpStep,
IP_FillModeType fillMode)
Tcl usage: $destImg WarpFunct srcImg d1Funct d1Deriv interpStep ?fillMode=FILL?
Description: Image "srcImg" is deformed. The result is stored
in image "destImg". The deformation is defined by
an application-supplied displacement function,
"d1Funct", and its derivatives, "d1Deriv", 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)
Given a position (x, y) in the destination image,
"d1Funct" computes the corresonding position (u, v)
in the source image.
"d1Deriv" computes the four partial derivatives of
"d1Funct"; given a position (x, y), "d1Deriv" returns
ux = du (x, y) / dx,
uy = du (x, y) / dy,
vx = dv (x, y) / dx,
vy = dv (x, y) / dy.
Evaluating "d1Funct" and "d1Deriv" for every pixel can
be quite time-consuming. In order to save some time,
"d1Funct" and "d1Deriv" are sampled only every "interpStep"
pixels; in-between values are interpolated linearly.
"fillMode" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
image. The following values for "fillMode" 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 "d1Funct" and "d1Deriv" should
normally be UT_True. Image warping is aborted if
either "d1Funct" or "d1Deriv" returns UT_False.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: BlendFunct WarpKeypoint BlendKeypoint SetNumThreads
WarpKeypoint
Name: IP_WarpKeypoint
Usage: Perform free-form deformations on an image.
Synopsis: UT_Bool IP_WarpKeypoint(
IP_ImageId srcImg,
IP_ImageId destImg,
Int32 numKeys,
const Float32 xsrcList[],
const Float32 ysrcList[],
const Float32 xdestList[],
const Float32 ydestList[],
Int32 interpStep,
Float32 smoothness,
IP_FillModeType fillMode)
Tcl usage: $destImg WarpKeypoint srcImg numKeys xsrcList ysrcList xdestList ydestList interpStep ?smoothness=0.0? ?fillMode=FILL?
Description: Image "srcImg" is deformed smoothly. The result is
stored in image "destImg". The deformation is defined
by a set of "numKeys" key points:
The position of key point number "i" in "srcImg" is
(xsrcList[i], ysrcList[i]); (xdestList[i], ydestList[i])
defines the position of the key point in "destImg".
The pixels from "srcImg" are displaced so that the
pixel at position (xsrcList[i], ysrcList[i]) arrives at
position (xdestList[i], ydestList[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
"interpStep" pixels; in-between values are interpolated
linearly.
If "interpStep" is 1, the interpolation function is sampled
for every pixel and the resulting image looks as smooth
as possible. Setting "interpStep" to a value greater than 1
saves time, but the result looks less smooth.
"smoothness" selects the smoothness of the function used to
interpolate between the key points:
If "smoothness" 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 "smoothness" 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 "smoothness" increases.
"fillMode" selects how colors are assigned to output image
pixels which are not covered by pixels in the input
image. The following values for "fillMode" 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:
- "xsrcList" and "ysrcList" 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).
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: Yes
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: BlendKeypoint WarpFunct BlendFunct SetNumThreads
WrapRect
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)
Tcl usage: $destImg WrapRect srcImg xs1 ys1 xs2 ys2 sx 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".
Note: The source and destination regions may NOT be
overlapping regions in the same image.
States: State settings influencing functionality:
Draw mask: Yes
Draw mode: Yes
Draw color: Yes
Threading: No
UByte format: All
Float format: All
Return value: None.See also: BlankRect CopyRect DrawRect
WriteImage
Name: IP_WriteImage
Usage: Write an image to a file.
Synopsis: UT_Bool IP_WriteImage(
IP_ImageId img,
const char *fileName,
const char *format,
const char *options)
Tcl usage: $img WriteImage fileName format ?options?
Description: Image "img" is written to pixel file "fileName" using
pixel file format "format" and file format options "options".
The current pixel data format selects, which channels will
be written to the file and in which format.
The possible option values are format dependent and are
identical to the values offered by the Img extension.
The following write options are recognized:
-verbose <bool> : POI RAW SGI TGA
-withalpha <bool> : POI RAW SGI TGA
-compression <None|Rle> : POI SGI TGA
-scanorder <TopDown|BottomUp>: RAW TGA
-useheader <bool> : RAW
-byteorder <Intel|Motorola> : RAW
The default values for the write options are:
-verbose <bool> : false
-withalpha <bool> : false
-compression <none|rle> : rle
-scanorder <TopDown|BottomUp>: TopDown
-useheader <bool> : true
-byteorder <Intel|Motorola> : System byte order
Note, that FLOAT channels of POI images are always
written uncompressed.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: WriteSimple ReadImage NewImageFromFile NewImageFromPhoto SetFormat
WriteSimple
Name: IP_WriteSimple
Usage: Write an image to a file - simple version.
Synopsis: UT_Bool IP_WriteSimple(
IP_ImageId img,
const char *fileName,
const char *format,
const char *options)
Tcl usage: $img WriteSimple fileName format ?options?
Description: Image "img" is written to pixel file "fileName" using
file format "format" and format options "options".
The pixel data format in the file will be the same as
in "img" for all channels.
The possible option values are format dependent and are
identical to the values offered by the Img extension.
See IP_WriteImage for write option details.
States: State settings influencing functionality:
Draw mask: No
Draw mode: No
Draw color: No
Threading: No
UByte format: All
Float format: All
Return value: UT_True if successful, else UT_False.See also: NewImageFromFile ReadImage WriteImage