Visual Servoing Platform  version 3.5.1 under development (2023-09-22)
vpImageTools Class Reference

#include <visp3/core/vpImageTools.h>

Public Types

enum  vpImageInterpolationType { INTERPOLATION_NEAREST , INTERPOLATION_LINEAR , INTERPOLATION_CUBIC , INTERPOLATION_AREA }
 

Public Member Functions

template<class Type >
void createSubImage (const vpImage< Type > &I, unsigned int roi_top, unsigned int roi_left, unsigned int roi_height, unsigned int roi_width, vpImage< Type > &crop)
 
template<class Type >
void createSubImage (const vpImage< Type > &I, const vpRect &roi, vpImage< Type > &crop)
 
template<>
void binarise (vpImage< unsigned char > &I, unsigned char threshold1, unsigned char threshold2, unsigned char value1, unsigned char value2, unsigned char value3, bool useLUT)
 
template<>
void resizeBicubic (const vpImage< vpRGBa > &I, vpImage< vpRGBa > &Ires, unsigned int i, unsigned int j, float u, float v, float xFrac, float yFrac)
 
template<>
void resizeBilinear (const vpImage< vpRGBa > &I, vpImage< vpRGBa > &Ires, unsigned int i, unsigned int j, float u, float v, float xFrac, float yFrac)
 
template<>
void resize (const vpImage< unsigned char > &I, vpImage< unsigned char > &Ires, const vpImageInterpolationType &method, unsigned int)
 
template<>
void resize (const vpImage< vpRGBa > &I, vpImage< vpRGBa > &Ires, const vpImageInterpolationType &method, unsigned int)
 
template<>
void warpLinear (const vpImage< vpRGBa > &src, const vpMatrix &T, vpImage< vpRGBa > &dst, bool affine, bool centerCorner, bool fixedPoint)
 

Static Public Member Functions

template<class Type >
static void binarise (vpImage< Type > &I, Type threshold1, Type threshold2, Type value1, Type value2, Type value3, bool useLUT=true)
 
static void changeLUT (vpImage< unsigned char > &I, unsigned char A, unsigned char newA, unsigned char B, unsigned char newB)
 
template<class Type >
static void crop (const vpImage< Type > &I, double roi_top, double roi_left, unsigned int roi_height, unsigned int roi_width, vpImage< Type > &crop, unsigned int v_scale=1, unsigned int h_scale=1)
 
static void columnMean (const vpImage< double > &I, vpRowVector &result)
 
template<class Type >
static void crop (const vpImage< Type > &I, const vpImagePoint &topLeft, unsigned int roi_height, unsigned int roi_width, vpImage< Type > &crop, unsigned int v_scale=1, unsigned int h_scale=1)
 
template<class Type >
static void crop (const vpImage< Type > &I, const vpRect &roi, vpImage< Type > &crop, unsigned int v_scale=1, unsigned int h_scale=1)
 
template<class Type >
static void crop (const unsigned char *bitmap, unsigned int width, unsigned int height, const vpRect &roi, vpImage< Type > &crop, unsigned int v_scale=1, unsigned int h_scale=1)
 
static void extract (const vpImage< unsigned char > &Src, vpImage< unsigned char > &Dst, const vpRectOriented &r)
 
static void extract (const vpImage< unsigned char > &Src, vpImage< double > &Dst, const vpRectOriented &r)
 
template<class Type >
static void flip (const vpImage< Type > &I, vpImage< Type > &newI)
 
template<class Type >
static void flip (vpImage< Type > &I)
 
static void imageDifference (const vpImage< unsigned char > &I1, const vpImage< unsigned char > &I2, vpImage< unsigned char > &Idiff)
 
static void imageDifference (const vpImage< vpRGBa > &I1, const vpImage< vpRGBa > &I2, vpImage< vpRGBa > &Idiff)
 
static void imageDifferenceAbsolute (const vpImage< unsigned char > &I1, const vpImage< unsigned char > &I2, vpImage< unsigned char > &Idiff)
 
static void imageDifferenceAbsolute (const vpImage< double > &I1, const vpImage< double > &I2, vpImage< double > &Idiff)
 
static void imageDifferenceAbsolute (const vpImage< vpRGBa > &I1, const vpImage< vpRGBa > &I2, vpImage< vpRGBa > &Idiff)
 
static void imageAdd (const vpImage< unsigned char > &I1, const vpImage< unsigned char > &I2, vpImage< unsigned char > &Ires, bool saturate=false)
 
static void imageSubtract (const vpImage< unsigned char > &I1, const vpImage< unsigned char > &I2, vpImage< unsigned char > &Ires, bool saturate=false)
 
static void initUndistortMap (const vpCameraParameters &cam, unsigned int width, unsigned int height, vpArray2D< int > &mapU, vpArray2D< int > &mapV, vpArray2D< float > &mapDu, vpArray2D< float > &mapDv)
 
static double interpolate (const vpImage< unsigned char > &I, const vpImagePoint &point, const vpImageInterpolationType &method=INTERPOLATION_NEAREST)
 
static void integralImage (const vpImage< unsigned char > &I, vpImage< double > &II, vpImage< double > &IIsq)
 
static double normalizedCorrelation (const vpImage< double > &I1, const vpImage< double > &I2, bool useOptimized=true)
 
static void normalize (vpImage< double > &I)
 
static void remap (const vpImage< unsigned char > &I, const vpArray2D< int > &mapU, const vpArray2D< int > &mapV, const vpArray2D< float > &mapDu, const vpArray2D< float > &mapDv, vpImage< unsigned char > &Iundist)
 
static void remap (const vpImage< vpRGBa > &I, const vpArray2D< int > &mapU, const vpArray2D< int > &mapV, const vpArray2D< float > &mapDu, const vpArray2D< float > &mapDv, vpImage< vpRGBa > &Iundist)
 
template<class Type >
static void resize (const vpImage< Type > &I, vpImage< Type > &Ires, unsigned int width, unsigned int height, const vpImageInterpolationType &method=INTERPOLATION_NEAREST, unsigned int nThreads=0)
 
template<class Type >
static void resize (const vpImage< Type > &I, vpImage< Type > &Ires, const vpImageInterpolationType &method=INTERPOLATION_NEAREST, unsigned int nThreads=0)
 
static void templateMatching (const vpImage< unsigned char > &I, const vpImage< unsigned char > &I_tpl, vpImage< double > &I_score, unsigned int step_u, unsigned int step_v, bool useOptimized=true)
 
template<class Type >
static void undistort (const vpImage< Type > &I, const vpCameraParameters &cam, vpImage< Type > &newI, unsigned int nThreads=2)
 
template<class Type >
static void undistort (const vpImage< Type > &I, vpArray2D< int > mapU, vpArray2D< int > mapV, vpArray2D< float > mapDu, vpArray2D< float > mapDv, vpImage< Type > &newI)
 
template<class Type >
static void warpImage (const vpImage< Type > &src, const vpMatrix &T, vpImage< Type > &dst, const vpImageInterpolationType &interpolation=INTERPOLATION_NEAREST, bool fixedPointArithmetic=true, bool pixelCenter=false)
 

Deprecated functions

template<class Type >
static vp_deprecated void createSubImage (const vpImage< Type > &I, unsigned int i_sub, unsigned int j_sub, unsigned int nrow_sub, unsigned int ncol_sub, vpImage< Type > &S)
 
template<class Type >
static vp_deprecated void createSubImage (const vpImage< Type > &I, const vpRect &rect, vpImage< Type > &S)
 

Detailed Description

Various image tools; sub-image extraction, modification of the look up table, binarisation...

Definition at line 73 of file vpImageTools.h.

Member Enumeration Documentation

◆ vpImageInterpolationType

Enumerator
INTERPOLATION_NEAREST 

Nearest neighbor interpolation.

INTERPOLATION_LINEAR 

Bi-linear interpolation (optimized by SIMD lib if enabled).

INTERPOLATION_CUBIC 

Bi-cubic interpolation.

INTERPOLATION_AREA 

Area interpolation (optimized by SIMD lib if enabled).

Definition at line 76 of file vpImageTools.h.

Member Function Documentation

◆ binarise() [1/2]

template<class Type >
void vpImageTools::binarise ( vpImage< Type > &  I,
Type  threshold1,
Type  threshold2,
Type  value1,
Type  value2,
Type  value3,
bool  useLUT = true 
)
inlinestatic

Binarise an image.

  • Pixels whose values are less than threshold1 are set to value1
  • Pixels whose values are greater then or equal to threshold1 and less then or equal to threshold2 are set to value2
  • Pixels whose values are greater than threshold2 are set to value3
Examples
testConnectedComponents.cpp, testContours.cpp, testFloodFill.cpp, testImageBinarise.cpp, and tutorial-ibvs-4pts-ogre-tracking.cpp.

Definition at line 455 of file vpImageTools.h.

References vpImage< Type >::bitmap, vpImage< Type >::getHeight(), and vpImage< Type >::getWidth().

Referenced by vp::autoThreshold().

◆ binarise() [2/2]

template<>
void vpImageTools::binarise ( vpImage< unsigned char > &  I,
unsigned char  threshold1,
unsigned char  threshold2,
unsigned char  value1,
unsigned char  value2,
unsigned char  value3,
bool  useLUT 
)
inline

Binarise an image.

  • Pixels whose values are less than threshold1 are set to value1
  • Pixels whose values are greater then or equal to threshold1 and less then or equal to threshold2 are set to value2
  • Pixels whose values are greater than threshold2 are set to value3

Definition at line 487 of file vpImageTools.h.

References vpImage< Type >::bitmap, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::performLut().

◆ changeLUT()

void vpImageTools::changeLUT ( vpImage< unsigned char > &  I,
unsigned char  A,
unsigned char  A_star,
unsigned char  B,
unsigned char  B_star 
)
static

Change the look up table (LUT) of an image. Considering pixel gray level values $ l $ in the range $[A, B]$, this method allows to rescale these values in $[A^*, B^*]$ by linear interpolation:

$ \left\{ \begin{array}{ll} l \in ]-\infty, A] \mbox{, } & l = A^* \\ l \in [B, \infty[ \mbox{, } & l = B^* \\ l \in ]A, B[ \mbox{, } & l = A^* + (l-A) * \frac{B^*-A^*}{B-A} \end{array} \right. $

Parameters
I: Image to process.
A: Low gray level value of the range to consider.
A_star: New gray level value $ A^*$ to attribute to pixel who's value was A
B: Height gray level value of the range to consider.
B_star: New gray level value $ B^*$ to attribute to pixel who's value was B
Exceptions
vpImageException::incorrectInitializationErrorIf $B \leq A$.

As shown in the example below, this method can be used to binarize an image. For an unsigned char image (in the range 0-255), thresholding this image at level 127 can be done by:

#include <visp3/core/vpImage.h>
#include <visp3/core/vpImageTools.h>
#include <visp3/io/vpImageIo.h>
int main()
{
#ifdef _WIN32
std::string filename("C:/Temp/visp-images/Klimt/Klimt.ppm");
#else
std::string filename("/local/soft/ViSP/ViSP-images/Klimt/Klimt.ppm");
#endif
// Read an image from the disk
vpImageIo::read(I, filename);
// Binarize image I:
// - gray level values less than or equal to 127 are set to 0,
// - gray level values greater than 128 are set to 255
vpImageTools::changeLUT(I, 127, 0, 128, 255);
vpImageIo::write(I, "Klimt.pgm"); // Write the image in a PGM P5 image file format
}
static void read(vpImage< unsigned char > &I, const std::string &filename, int backend=IO_DEFAULT_BACKEND)
Definition: vpImageIo.cpp:143
static void write(const vpImage< unsigned char > &I, const std::string &filename, int backend=IO_DEFAULT_BACKEND)
Definition: vpImageIo.cpp:287
static void changeLUT(vpImage< unsigned char > &I, unsigned char A, unsigned char newA, unsigned char B, unsigned char newB)

Definition at line 97 of file vpImageTools.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImageException::incorrectInitializationError, and vpERROR_TRACE.

◆ columnMean()

void vpImageTools::columnMean ( const vpImage< double > &  I,
vpRowVector V 
)
static

Compute the column-wise mean intensities.

Parameters
I: The image.
V: The result vector.

Definition at line 513 of file vpImageTools.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpRowVector::resize().

◆ createSubImage() [1/4]

template<class Type >
static vp_deprecated void vpImageTools::createSubImage ( const vpImage< Type > &  I,
const vpRect rect,
vpImage< Type > &  S 
)
static

◆ createSubImage() [2/4]

template<class Type >
void vpImageTools::createSubImage ( const vpImage< Type > &  I,
const vpRect roi,
vpImage< Type > &  crop 
)

Crop an image region of interest.

Deprecated:
This function is deprecated. You should rather use crop(const vpImage<Type> &, const vpRect &, vpImage<Type> &).
Parameters
I: Input image from which a sub image will be extracted.
roi: Region of interest in image I corresponding to the cropped part of the image.
crop: Cropped image.
See also
crop(const vpImage<Type> &, const vpRect &, vpImage<Type> &)

Definition at line 271 of file vpImageTools.h.

References crop().

◆ createSubImage() [3/4]

template<class Type >
static vp_deprecated void vpImageTools::createSubImage ( const vpImage< Type > &  I,
unsigned int  i_sub,
unsigned int  j_sub,
unsigned int  nrow_sub,
unsigned int  ncol_sub,
vpImage< Type > &  S 
)
static

◆ createSubImage() [4/4]

template<class Type >
void vpImageTools::createSubImage ( const vpImage< Type > &  I,
unsigned int  roi_top,
unsigned int  roi_left,
unsigned int  roi_height,
unsigned int  roi_width,
vpImage< Type > &  crop 
)

Crop a region of interest (ROI) in an image.

Deprecated:
This function is deprecated. You should rather use crop(const vpImage<Type> &, unsigned int, unsigned int, unsigned int, unsigned int, vpImage<Type> &).
Parameters
I: Input image from which a sub image will be extracted.
roi_top: ROI vertical position of the upper/left corner in the input image.
roi_left: ROI horizontal position of the upper/left corner in the input image.
roi_height: Cropped image height corresponding to the ROI height.
roi_width: Cropped image width corresponding to the ROI height.
crop: Cropped image.
See also
crop(const vpImage<Type> &, unsigned int, unsigned int, unsigned int, unsigned int, vpImage<Type> &)

Definition at line 250 of file vpImageTools.h.

References crop().

◆ crop() [1/4]

template<class Type >
void vpImageTools::crop ( const unsigned char *  bitmap,
unsigned int  width,
unsigned int  height,
const vpRect roi,
vpImage< Type > &  crop,
unsigned int  v_scale = 1,
unsigned int  h_scale = 1 
)
static

Crop a region of interest (ROI) in an image. The ROI coordinates and dimension are defined in the original image.

Setting v_scale and h_scale to values different from 1 allows also to subsample the cropped image.

Parameters
bitmap: Pointer to the input image from which a sub image will be extracted.
width,height: Size of the input image.
roi: Region of interest corresponding to the cropped part of the image.
crop: Cropped image.
v_scale[in] : Vertical subsampling factor applied to the ROI.
h_scale[in] : Horizontal subsampling factor applied to the ROI.

Definition at line 404 of file vpImageTools.h.

References crop(), vpRect::getHeight(), vpRect::getLeft(), vpRect::getTop(), and vpRect::getWidth().

◆ crop() [2/4]

template<class Type >
void vpImageTools::crop ( const vpImage< Type > &  I,
const vpImagePoint topLeft,
unsigned int  roi_height,
unsigned int  roi_width,
vpImage< Type > &  crop,
unsigned int  v_scale = 1,
unsigned int  h_scale = 1 
)
static

Crop a region of interest (ROI) in an image. The ROI coordinates and dimension are defined in the original image.

Setting v_scale and h_scale to values different from 1 allows also to subsample the cropped image.

Parameters
I: Input image from which a sub image will be extracted.
topLeft: ROI position of the upper/left corner in the input image.
roi_height: Cropped image height corresponding to the ROI height.
roi_width: Cropped image width corresponding to the ROI height.
crop: Cropped image.
v_scale[in] : Vertical subsampling factor applied to the ROI.
h_scale[in] : Horizontal subsampling factor applied to the ROI.
See also
crop(const vpImage<Type> &, const vpRect &, vpImage<Type> &)

Definition at line 356 of file vpImageTools.h.

References crop(), vpImagePoint::get_i(), and vpImagePoint::get_j().

◆ crop() [3/4]

template<class Type >
void vpImageTools::crop ( const vpImage< Type > &  I,
const vpRect roi,
vpImage< Type > &  crop,
unsigned int  v_scale = 1,
unsigned int  h_scale = 1 
)
static

Crop a region of interest (ROI) in an image. The ROI coordinates and dimension are defined in the original image.

Setting v_scale and h_scale to values different from 1 allows also to subsample the cropped image.

Parameters
I: Input image from which a sub image will be extracted.
roi: Region of interest in image I corresponding to the cropped part of the image.
crop: Cropped image.
v_scale[in] : Vertical subsampling factor applied to the ROI.
h_scale[in] : Horizontal subsampling factor applied to the ROI.

Definition at line 379 of file vpImageTools.h.

References crop(), vpRect::getHeight(), vpRect::getLeft(), vpRect::getTop(), and vpRect::getWidth().

◆ crop() [4/4]

template<class Type >
void vpImageTools::crop ( const vpImage< Type > &  I,
double  roi_top,
double  roi_left,
unsigned int  roi_height,
unsigned int  roi_width,
vpImage< Type > &  crop,
unsigned int  v_scale = 1,
unsigned int  h_scale = 1 
)
static

Crop a region of interest (ROI) in an image. The ROI coordinates and dimension are defined in the original image.

Setting v_scale and h_scale to values different from 1 allows also to subsample the cropped image.

Parameters
I: Input image from which a sub image will be extracted.
roi_top: ROI vertical position of the upper/left corner in the input image.
roi_left: ROI horizontal position of the upper/left corner in the input image.
roi_height: Cropped image height corresponding to the ROI height.
roi_width: Cropped image width corresponding to the ROI height.
crop: Cropped image.
v_scale[in] : Vertical subsampling factor applied to the ROI.
h_scale[in] : Horizontal subsampling factor applied to the ROI.
See also
crop(const vpImage<Type> &, const vpRect &, vpImage<Type> &)
Examples
testCrop.cpp, testCropAdvanced.cpp, testImageNormalizedCorrelation.cpp, and testImageTemplateMatching.cpp.

Definition at line 301 of file vpImageTools.h.

References vpImage< Type >::getHeight(), and vpImage< Type >::getWidth().

Referenced by vpV4l2Grabber::acquire(), createSubImage(), crop(), vpDisplayGTK::displayImageROI(), vpMeNurbs::seekExtremitiesCanny(), and templateMatching().

◆ extract() [1/2]

void vpImageTools::extract ( const vpImage< unsigned char > &  Src,
vpImage< double > &  Dst,
const vpRectOriented r 
)
static

Extract a rectangular region from an image.

Parameters
Src: The source image.
Dst: The resulting image.
r: The rectangle area.

Definition at line 606 of file vpImageTools.cpp.

References vpImagePoint::get_i(), vpImagePoint::get_j(), vpRectOriented::getHeight(), vpRectOriented::getOrientation(), vpRectOriented::getTopLeft(), vpRectOriented::getWidth(), interpolate(), INTERPOLATION_LINEAR, vpImage< Type >::resize(), and vpMath::round().

◆ extract() [2/2]

void vpImageTools::extract ( const vpImage< unsigned char > &  Src,
vpImage< unsigned char > &  Dst,
const vpRectOriented r 
)
static

Extract a rectangular region from an image.

Parameters
Src: The source image.
Dst: The resulting image.
r: The rectangle area.

Definition at line 583 of file vpImageTools.cpp.

References vpImagePoint::get_i(), vpImagePoint::get_j(), vpRectOriented::getHeight(), vpRectOriented::getOrientation(), vpRectOriented::getTopLeft(), vpRectOriented::getWidth(), interpolate(), INTERPOLATION_LINEAR, vpImage< Type >::resize(), and vpMath::round().

◆ flip() [1/2]

template<class Type >
void vpImageTools::flip ( const vpImage< Type > &  I,
vpImage< Type > &  newI 
)
static

Flip vertically the input image and give the result in the output image.

Parameters
I: Input image to flip.
newI: Output image which is the flipped input image.

Definition at line 826 of file vpImageTools.h.

References vpImage< Type >::bitmap, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ flip() [2/2]

template<class Type >
void vpImageTools::flip ( vpImage< Type > &  I)
static

Flip vertically the input image.

Parameters
I: Input image which is flipped and modified in output.

The following example shows how to use this function:

#include <visp3/core/vpImage.h>
#include <visp3/core/vpImageTools.h>
#include <visp3/io/vpImageIo.h>
int main()
{
#ifdef _WIN32
std::string filename("C:/Temp/visp-images/Klimt/Klimt.ppm");
#else
std::string filename("/local/soft/ViSP/ViSP-images/Klimt/Klimt.ppm");
#endif
// Read an image from the disk
vpImageIo::read(I, filename);
// Flip the image
// Write the image in a PGM P5 image file format
vpImageIo::write(I, "Klimt-flip.ppm");
}
static void flip(const vpImage< Type > &I, vpImage< Type > &newI)
Definition: vpImageTools.h:826

Definition at line 867 of file vpImageTools.h.

References vpImage< Type >::bitmap, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ imageAdd()

void vpImageTools::imageAdd ( const vpImage< unsigned char > &  I1,
const vpImage< unsigned char > &  I2,
vpImage< unsigned char > &  Ires,
bool  saturate = false 
)
static

Compute the image addition: $ Ires = I1 + I2 $.

Parameters
I1: The first image.
I2: The second image.
Ires: $ Ires = I1 + I2 $
saturate: If true, saturate the result to [0 ; 255] using vpMath::saturate, otherwise overflow may occur.
Note
The simd lib is used to accelerate processing on x86 and ARM architecture.
Warning
This function does not work in-place (Ires object must be different from I1 and I2).
Examples
perfImageAddSub.cpp, and testImageAddSub.cpp.

Definition at line 279 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

Referenced by vp::fillHoles().

◆ imageDifference() [1/2]

void vpImageTools::imageDifference ( const vpImage< unsigned char > &  I1,
const vpImage< unsigned char > &  I2,
vpImage< unsigned char > &  Idiff 
)
static

Compute the signed difference between the two images I1 and I2 for visualization purpose: Idiff = I1-I2

  • pixels with a null difference are set to 128.
  • A negative difference implies a pixel value < 128
  • A positive difference implies a pixel value > 128
Parameters
I1: The first image.
I2: The second image.
Idiff: The result of the difference.
Examples
photometricVisualServoing.cpp, photometricVisualServoingWithoutVpServo.cpp, testImageDifference.cpp, and testUndistortImage.cpp.

Definition at line 134 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getSize(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ imageDifference() [2/2]

void vpImageTools::imageDifference ( const vpImage< vpRGBa > &  I1,
const vpImage< vpRGBa > &  I2,
vpImage< vpRGBa > &  Idiff 
)
static

Compute the signed difference between the two images I1 and I2 RGB components for visualization purpose: Idiff = I1-I2. The fourth component named A is not compared. It is set to 0 in the resulting difference image.

  • pixels with a null difference are set to R=128, G=128, B=128.
  • A negative difference implies a pixel R, G, B value < 128
  • A positive difference implies a pixel R, G, B value > 128
Parameters
I1: The first image.
I2: The second image.
Idiff: The result of the difference between RGB components.

Definition at line 161 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getSize(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ imageDifferenceAbsolute() [1/3]

void vpImageTools::imageDifferenceAbsolute ( const vpImage< double > &  I1,
const vpImage< double > &  I2,
vpImage< double > &  Idiff 
)
static

Compute the difference between the two images I1 and I2.

Parameters
I1: The first image.
I2: The second image.
Idiff: The result of the difference.

Definition at line 213 of file vpImageTools.cpp.

References vpMath::abs(), vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ imageDifferenceAbsolute() [2/3]

void vpImageTools::imageDifferenceAbsolute ( const vpImage< unsigned char > &  I1,
const vpImage< unsigned char > &  I2,
vpImage< unsigned char > &  Idiff 
)
static

Compute the difference between the two images I1 and I2

Warning
: This is NOT for visualization If you want to visualize difference images during servo, please use vpImageTools::imageDifference(..,..,..) function.
Parameters
I1: The first image.
I2: The second image.
Idiff: The result of the difference.
Examples
testGaussianFilter.cpp, and testUndistortImage.cpp.

Definition at line 188 of file vpImageTools.cpp.

References vpMath::abs(), vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ imageDifferenceAbsolute() [3/3]

void vpImageTools::imageDifferenceAbsolute ( const vpImage< vpRGBa > &  I1,
const vpImage< vpRGBa > &  I2,
vpImage< vpRGBa > &  Idiff 
)
static

Compute the difference between the two images I1 and I2 RGB components. The fourth component named A is not compared. It is set to 0 in the resulting difference image.

Warning
: This is NOT for visualization. If you want to visualize difference images during servo, please use vpImageTools::imageDifference(..,..,..) function.
Parameters
I1: The first image.
I2: The second image.
Idiff: The result of the difference between RGB components.

Definition at line 242 of file vpImageTools.cpp.

References vpRGBa::A, vpMath::abs(), vpRGBa::B, vpImage< Type >::bitmap, vpException::dimensionError, vpRGBa::G, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpRGBa::R, and vpImage< Type >::resize().

◆ imageSubtract()

void vpImageTools::imageSubtract ( const vpImage< unsigned char > &  I1,
const vpImage< unsigned char > &  I2,
vpImage< unsigned char > &  Ires,
bool  saturate = false 
)
static

Compute the image addition: $ Ires = I1 - I2 $.

Parameters
I1: The first image.
I2: The second image.
Ires: $ Ires = I1 - I2 $
saturate: If true, saturate the result to [0 ; 255] using vpMath::saturate, otherwise overflow may occur.
Note
The simd lib is used to accelerate processing on x86 and ARM architecture.
Warning
This function does not work in-place (Ires object must be different from I1 and I2).
Examples
perfImageAddSub.cpp, and testImageAddSub.cpp.

Definition at line 312 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

Referenced by vp::fillHoles().

◆ initUndistortMap()

void vpImageTools::initUndistortMap ( const vpCameraParameters cam,
unsigned int  width,
unsigned int  height,
vpArray2D< int > &  mapU,
vpArray2D< int > &  mapV,
vpArray2D< float > &  mapDu,
vpArray2D< float > &  mapDv 
)
static

Compute the undistortion transformation map.

Parameters
cam: Camera intrinsic parameters with distortion coefficients.
width: Image width.
height: Image height.
mapU: 2D array that contains at each coordinate the u-coordinate in the distorted image.
mapV: 2D array that contains at each coordinate the v-coordinate in the distorted image.
mapDu: 2D array that contains at each coordinate the $ \Delta u $ for the interpolation.
mapDv: 2D array that contains at each coordinate the $ \Delta v $ for the interpolation.
Examples
testRealSense2_T265_undistort.cpp, testUndistortImage.cpp, and tutorial-apriltag-detector-live-T265-realsense.cpp.

Definition at line 343 of file vpImageTools.cpp.

References vpCameraParameters::get_kud(), vpCameraParameters::get_projModel(), vpCameraParameters::get_px(), vpCameraParameters::get_py(), vpCameraParameters::get_u0(), vpCameraParameters::get_v0(), vpCameraParameters::getKannalaBrandtDistortionCoefficients(), vpCameraParameters::ProjWithKannalaBrandtDistortion, vpArray2D< Type >::resize(), and vpMath::sqr().

◆ integralImage()

void vpImageTools::integralImage ( const vpImage< unsigned char > &  I,
vpImage< double > &  II,
vpImage< double > &  IIsq 
)
static

Compute the integral images:

$ II(u,v)=\sum_{u^{'}\leq u, v^{'}\leq v}I(u,v) $

$ IIsq(u,v)=\sum_{u^{'}\leq u, v^{'}\leq v}I(u,v)^2 $.

Parameters
I: Input image.
II: Integral image II.
IIsq: Integral image IIsq.
Examples
testImageTemplateMatching.cpp.

Definition at line 461 of file vpImageTools.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getSize(), vpImage< Type >::getWidth(), vpImage< Type >::resize(), and vpMath::sqr().

Referenced by templateMatching().

◆ interpolate()

double vpImageTools::interpolate ( const vpImage< unsigned char > &  I,
const vpImagePoint point,
const vpImageInterpolationType method = INTERPOLATION_NEAREST 
)
static

Get the interpolated value at a given location.

Parameters
I: The image to perform intepolation in.
point: The image point.
method: The interpolation method (only interpolation with vpImageTools::INTERPOLATION_NEAREST and vpImageTools::INTERPOLATION_LINEAR are implemented).

Definition at line 544 of file vpImageTools.cpp.

References vpImagePoint::get_i(), vpImagePoint::get_j(), INTERPOLATION_CUBIC, INTERPOLATION_LINEAR, INTERPOLATION_NEAREST, vpException::notImplementedError, and vpMath::round().

Referenced by extract().

◆ normalize()

void vpImageTools::normalize ( vpImage< double > &  I)
static

Normalize the image intensities.

Parameters
I: The image to normalize.

Definition at line 529 of file vpImageTools.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getSum(), and vpImage< Type >::getWidth().

◆ normalizedCorrelation()

double vpImageTools::normalizedCorrelation ( const vpImage< double > &  I1,
const vpImage< double > &  I2,
bool  useOptimized = true 
)
static

Compute a correlation between 2 images.

Parameters
I1: The first image.
I2: The second image.
useOptimized: Use SSE if true and available.
Examples
testImageNormalizedCorrelation.cpp.

Definition at line 486 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getMeanValue(), vpImage< Type >::getSize(), and vpImage< Type >::getWidth().

Referenced by templateMatching().

◆ remap() [1/2]

void vpImageTools::remap ( const vpImage< unsigned char > &  I,
const vpArray2D< int > &  mapU,
const vpArray2D< int > &  mapV,
const vpArray2D< float > &  mapDu,
const vpArray2D< float > &  mapDv,
vpImage< unsigned char > &  Iundist 
)
static

Apply the transformation map to the image.

Parameters
I: Input grayscale image.
mapU: Map that contains at each destination coordinate the u-coordinate in the source image.
mapV: Map that contains at each destination coordinate the v-coordinate in the source image.
mapDu: Map that contains at each destination coordinate the $ \Delta u $ for the interpolation.
mapDv: Map that contains at each destination coordinate the $ \Delta v $ for the interpolation.
Iundist: Output transformed grayscale image.
Examples
testUndistortImage.cpp.

Definition at line 773 of file vpImageTools.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

Referenced by undistort().

◆ remap() [2/2]

void vpImageTools::remap ( const vpImage< vpRGBa > &  I,
const vpArray2D< int > &  mapU,
const vpArray2D< int > &  mapV,
const vpArray2D< float > &  mapDu,
const vpArray2D< float > &  mapDv,
vpImage< vpRGBa > &  Iundist 
)
static

Apply the transformation map to the image.

Parameters
I: Input color image.
mapU: Map that contains at each destination coordinate the u-coordinate in the source image.
mapV: Map that contains at each destination coordinate the v-coordinate in the source image.
mapDu: Map that contains at each destination coordinate the $ \Delta u $ for the interpolation.
mapDv: Map that contains at each destination coordinate the $ \Delta v $ for the interpolation.
Iundist: Output transformed color image.

Definition at line 816 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpArray2D< Type >::data, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImage< Type >::resize().

◆ resize() [1/4]

template<class Type >
void vpImageTools::resize ( const vpImage< Type > &  I,
vpImage< Type > &  Ires,
const vpImageInterpolationType method = INTERPOLATION_NEAREST,
unsigned int  nThreads = 0 
)
static

Resize the image using one interpolation method (by default it uses the nearest neighbor interpolation).

Parameters
I: Input image.
Ires: Output image resized (you have to init the image Ires at the desired size).
method: Interpolation method.
nThreads: Number of threads to use if OpenMP is available (zero will let OpenMP uses the optimal number of threads).
Warning
The input I and output Ires images must be different objects.
Note
The SIMD lib is used to accelerate processing on x86 and ARM architecture for:
  • unsigned char and vpRGBa image types
  • and only with INTERPOLATION_AREA and INTERPOLATION_LINEAR methods

Definition at line 1082 of file vpImageTools.h.

References vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), INTERPOLATION_AREA, INTERPOLATION_CUBIC, INTERPOLATION_LINEAR, and INTERPOLATION_NEAREST.

◆ resize() [2/4]

template<class Type >
void vpImageTools::resize ( const vpImage< Type > &  I,
vpImage< Type > &  Ires,
unsigned int  width,
unsigned int  height,
const vpImageInterpolationType method = INTERPOLATION_NEAREST,
unsigned int  nThreads = 0 
)
static

Resize the image using one interpolation method (by default it uses the nearest neighbor interpolation).

Parameters
I: Input image.
Ires: Output image resized to width, height.
width: Resized width.
height: Resized height.
method: Interpolation method.
nThreads: Number of threads to use if OpenMP is available (zero will let OpenMP uses the optimal number of threads).
Warning
The input I and output Ires images must be different objects.
Note
The SIMD lib is used to accelerate processing on x86 and ARM architecture for:
  • unsigned char and vpRGBa image types
  • and only with INTERPOLATION_AREA and INTERPOLATION_LINEAR methods
Examples
testImageResize.cpp, testUndistortImage.cpp, and tutorial-image-colormap.cpp.

Definition at line 1056 of file vpImageTools.h.

References vpImage< Type >::resize().

◆ resize() [3/4]

template<>
void vpImageTools::resize ( const vpImage< unsigned char > &  I,
vpImage< unsigned char > &  Ires,
const vpImageInterpolationType method,
unsigned int   
)
inline

◆ resize() [4/4]

template<>
void vpImageTools::resize ( const vpImage< vpRGBa > &  I,
vpImage< vpRGBa > &  Ires,
const vpImageInterpolationType method,
unsigned int   
)
inline

◆ resizeBicubic()

template<>
void vpImageTools::resizeBicubic ( const vpImage< vpRGBa > &  I,
vpImage< vpRGBa > &  Ires,
unsigned int  i,
unsigned int  j,
float  u,
float  v,
float  xFrac,
float  yFrac 
)
inline

Definition at line 930 of file vpImageTools.h.

◆ resizeBilinear()

template<>
void vpImageTools::resizeBilinear ( const vpImage< vpRGBa > &  I,
vpImage< vpRGBa > &  Ires,
unsigned int  i,
unsigned int  j,
float  u,
float  v,
float  xFrac,
float  yFrac 
)
inline

Definition at line 1004 of file vpImageTools.h.

References vpImage< Type >::getHeight(), and vpImage< Type >::getWidth().

◆ templateMatching()

void vpImageTools::templateMatching ( const vpImage< unsigned char > &  I,
const vpImage< unsigned char > &  I_tpl,
vpImage< double > &  I_score,
unsigned int  step_u,
unsigned int  step_v,
bool  useOptimized = true 
)
static

Match a template image into another image using zero-mean normalized cross-correlation:

$\frac{\sum_{u^{'},v^{'}} (I(u+u^{'},v+v^{'})-\bar{I}_{u^{'},v^{'}}) (T(u^{'},v^{'})-\bar{T}_{u^{'},v^{'}})}{\sqrt{\sum_{u^{'},v^{'}} (I(u+u^{'},v+v^{'})-\bar{I}_{u^{'},v^{'}})^2 \sum_{u^{'},v^{'}}(T(u^{'},v^{'})-\bar{T}_{u^{'},v^{'}})^2}}$

Parameters
I: Input image.
I_tpl: Template image.
I_score: Output template matching score.
step_u: Step in u-direction to speed-up the computation.
step_v: Step in v-direction to speed-up the computation.
useOptimized: Use optimized version (SSE, OpenMP, integral images, ...) if true and available.
Examples
testImageTemplateMatching.cpp.

Definition at line 637 of file vpImageTools.cpp.

References vpImage< Type >::bitmap, vpImageConvert::convert(), crop(), vpImage< Type >::getHeight(), vpImage< Type >::getSize(), vpImage< Type >::getWidth(), integralImage(), normalizedCorrelation(), and vpImage< Type >::resize().

◆ undistort() [1/2]

template<class Type >
void vpImageTools::undistort ( const vpImage< Type > &  I,
const vpCameraParameters cam,
vpImage< Type > &  undistI,
unsigned int  nThreads = 2 
)
static

Undistort an image

Parameters
I: Input image to undistort.
cam: Parameters of the camera causing distortion.
undistI: Undistorted output image. The size of this image will be the same than the input image I. If the distortion parameter $k_{ud}$ is null, meaning that cam.get_kud() == 0, undistI is just a copy of I.
nThreads: Number of threads to use if pthreads library is available.
Warning
This function works only with Types authorizing "+,-, multiplication by a scalar" operators.

Since this function is time consuming, if you want to undistort multiple images, you should rather call initUndistortMap() once and then remap() to undistort the images. This will be less time consuming.

See also
initUndistortMap(), remap()
Examples
testRealSense2_T265_undistort.cpp, testUndistortImage.cpp, tutorial-apriltag-detector-live-T265-realsense.cpp, and tutorial-undistort.cpp.

Definition at line 641 of file vpImageTools.h.

References vpImage< Type >::bitmap, vpCameraParameters::get_kud(), vpCameraParameters::get_px(), vpCameraParameters::get_py(), vpCameraParameters::get_u0(), vpCameraParameters::get_v0(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImage< Type >::resize(), and vpMath::sqr().

◆ undistort() [2/2]

template<class Type >
void vpImageTools::undistort ( const vpImage< Type > &  I,
vpArray2D< int >  mapU,
vpArray2D< int >  mapV,
vpArray2D< float >  mapDu,
vpArray2D< float >  mapDv,
vpImage< Type > &  newI 
)
static

Undistort an image.

Parameters
I: Input image to undistort.
mapU: Map that contains at each destination coordinate the u-coordinate in the source image.
mapV: Map that contains at each destination coordinate the v-coordinate in the source image.
mapDu: Map that contains at each destination coordinate the $ \Delta u $ for the interpolation.
mapDv: Map that contains at each destination coordinate the $ \Delta v $ for the interpolation.
newI: Undistorted output image. The size of this image will be the same as the input image I.
Note
To undistort a fisheye image, you have to first call initUndistortMap() function to calculate maps and then call undistort() with input maps.

Definition at line 814 of file vpImageTools.h.

References remap().

◆ warpImage()

template<class Type >
void vpImageTools::warpImage ( const vpImage< Type > &  src,
const vpMatrix T,
vpImage< Type > &  dst,
const vpImageInterpolationType interpolation = INTERPOLATION_NEAREST,
bool  fixedPointArithmetic = true,
bool  pixelCenter = false 
)
static

Apply a warping (affine or perspective) transformation to an image.

Parameters
src: Input image.
T: Transformation / warping matrix, a 2x3 matrix for an affine transformation or a 3x3 matrix for a perspective transformation (homography).
dst: Output image, if empty it will be of the same size than src and zero-initialized.
interpolation: Interpolation method (only INTERPOLATION_NEAREST and INTERPOLATION_LINEAR are accepted, if INTERPOLATION_CUBIC is passed, INTERPOLATION_NEAREST will be used instead).
fixedPointArithmetic: If true and if pixelCenter is false, fixed-point arithmetic is used if possible. Otherwise (e.g. the input image is too big) it fallbacks to the default implementation.
pixelCenter: If true, pixel coordinates are at (0.5, 0.5), otherwise at (0,0). Fixed-point arithmetic cannot be used with pixelCenter option.
Examples
testImageWarp.cpp.

Definition at line 1239 of file vpImageTools.h.

References vpArray2D< Type >::getCols(), vpImage< Type >::getHeight(), vpArray2D< Type >::getRows(), vpImage< Type >::getSize(), vpImage< Type >::getWidth(), INTERPOLATION_CUBIC, INTERPOLATION_NEAREST, vpMatrix::inverseByLU(), vpMath::nul(), and vpImage< Type >::resize().

◆ warpLinear()

template<>
void vpImageTools::warpLinear ( const vpImage< vpRGBa > &  src,
const vpMatrix T,
vpImage< vpRGBa > &  dst,
bool  affine,
bool  centerCorner,
bool  fixedPoint 
)
inline