Visual Servoing Platform  version 3.0.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Public Types | Public Member Functions | Static Public Member Functions | List of all members
vpImageTools Class Reference
Image manipulation

#include <visp3/core/vpImageTools.h>

Public Types

enum  vpImageInterpolationType { INTERPOLATION_NEAREST, INTERPOLATION_LINEAR, INTERPOLATION_CUBIC }
 

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, const bool useLUT)
 
template<>
void resizeBicubic (const vpImage< vpRGBa > &I, vpImage< vpRGBa > &Ires, const unsigned int i, const unsigned int j, const float u, const float v, const float xFrac, const float yFrac)
 
template<>
void resizeBilinear (const vpImage< vpRGBa > &I, vpImage< vpRGBa > &Ires, const unsigned int i, const unsigned int j, const float u, const float v, const float xFrac, const float yFrac)
 

Static Public Member Functions

template<class Type >
static void binarise (vpImage< Type > &I, Type threshold1, Type threshold2, Type value1, Type value2, Type value3, const 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)
 
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)
 
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< 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, const bool saturate=false)
 
static void imageSubtract (const vpImage< unsigned char > &I1, const vpImage< unsigned char > &I2, vpImage< unsigned char > &Ires, const bool saturate=false)
 
template<class Type >
static void resize (const vpImage< Type > &I, vpImage< Type > &Ires, const unsigned int width, const unsigned int height, const vpImageInterpolationType &method=INTERPOLATION_NEAREST)
 
template<class Type >
static void resize (const vpImage< Type > &I, vpImage< Type > &Ires, const vpImageInterpolationType &method=INTERPOLATION_NEAREST)
 
template<class Type >
static void undistort (const vpImage< Type > &I, const vpCameraParameters &cam, vpImage< Type > &newI)
 
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 75 of file vpImageTools.h.

Member Enumeration Documentation

enum vpImageTools::vpImageInterpolationType
Enumerator
INTERPOLATION_NEAREST 

Nearest neighbor interpolation (fastest).

INTERPOLATION_LINEAR 

Bi-linear interpolation.

INTERPOLATION_CUBIC 

Bi-cubic interpolation.

Examples:
testImageResize.cpp.

Definition at line 78 of file vpImageTools.h.

Member Function Documentation

template<class Type >
void vpImageTools::binarise ( vpImage< Type > &  I,
Type  threshold1,
Type  threshold2,
Type  value1,
Type  value2,
Type  value3,
const 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:
testImageBinarise.cpp, testImageMorphology.cpp, and tutorial-ibvs-4pts-ogre-tracking.cpp.

Definition at line 423 of file vpImageTools.h.

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

template<>
void vpImageTools::binarise ( vpImage< unsigned char > &  I,
unsigned char  threshold1,
unsigned char  threshold2,
unsigned char  value1,
unsigned char  value2,
unsigned char  value3,
const 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 455 of file vpImageTools.h.

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

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
Returns
The modified image.
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/vpImageTools.h>
#include <visp3/core/vpImage.h>
#include <visp3/io/vpImageIo.h>
int main()
{
vpImage<unsigned char> I;
#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
}

Definition at line 102 of file vpImageTools.cpp.

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

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
template<class Type >
static vp_deprecated void vpImageTools::createSubImage ( const vpImage< Type > &  I,
const vpRect &  rect,
vpImage< Type > &  S 
)
static
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 fonction 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 215 of file vpImageTools.h.

References crop().

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

Crop an image region of interest.

Deprecated:
This fonction 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 239 of file vpImageTools.h.

References crop().

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, and testImageAddSub.cpp.

Definition at line 266 of file vpImageTools.h.

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

Referenced by vpV4l2Grabber::acquire(), vpKeyPointSurf::buildReference(), vpFernClassifier::buildReference(), createSubImage(), crop(), vpDisplayGTK::displayImageROI(), vpPlanarObjectDetector::matchPoint(), vpKeyPointSurf::matchPoint(), vpFernClassifier::matchPoint(), and vpMeNurbs::seekExtremitiesCanny().

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 324 of file vpImageTools.h.

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

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 348 of file vpImageTools.h.

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

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 368 of file vpImageTools.h.

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

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 780 of file vpImageTools.h.

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

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/vpImageTools.h>
#include <visp3/core/vpImage.h>
#include <visp3/io/vpImageIo.h>
int main()
{
vpImage<vpRGBa> I;
#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
vpImageTools::flip(I);
vpImageIo::write(I, "Klimt-flip.ppm"); // Write the image in a PGM P5 image file format
}

Definition at line 828 of file vpImageTools.h.

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

void vpImageTools::imageAdd ( const vpImage< unsigned char > &  I1,
const vpImage< unsigned char > &  I2,
vpImage< unsigned char > &  Ires,
const 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.
Examples:
testImageAddSub.cpp.

Definition at line 284 of file vpImageTools.cpp.

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

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 issue : 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.

Definition at line 143 of file vpImageTools.cpp.

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

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 issue : 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 176 of file vpImageTools.cpp.

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

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.

Definition at line 214 of file vpImageTools.cpp.

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

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 248 of file vpImageTools.cpp.

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

void vpImageTools::imageSubtract ( const vpImage< unsigned char > &  I1,
const vpImage< unsigned char > &  I2,
vpImage< unsigned char > &  Ires,
const 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.
Examples:
testImageAddSub.cpp.

Definition at line 328 of file vpImageTools.cpp.

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

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

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

Parameters
I: Input image.
Ires: Output image resized.
width: Resize width.
height: Resize height.
method: Interpolation method.
Examples:
testImageResize.cpp.

Definition at line 994 of file vpImageTools.h.

References vpImage< Type >::resize().

template<class Type >
void vpImageTools::resize ( const vpImage< Type > &  I,
vpImage< Type > &  Ires,
const vpImageInterpolationType &  method = INTERPOLATION_NEAREST 
)
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.

Definition at line 1008 of file vpImageTools.h.

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

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

Definition at line 895 of file vpImageTools.h.

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

Definition at line 955 of file vpImageTools.h.

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

template<class Type >
void vpImageTools::undistort ( const vpImage< Type > &  I,
const vpCameraParameters &  cam,
vpImage< Type > &  undistI 
)
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_d$ is null (see cam.get_kd_mp()), undistI is just a copy of I.
Warning
This function works only with Types authorizing "+,-, multiplication by a scalar" operators.
This function is time consuming :
  • On "Rhea"(Intel Core 2 Extreme X6800 2.93GHz, 2Go RAM) or "Charon"(Intel Xeon 3 GHz, 2Go RAM) : ~8 ms for a 640x480 image.
Examples:
testUndistortImage.cpp, and tutorial-undistort.cpp.

Definition at line 609 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().