Visual Servoing Platform  version 3.3.0
vpImageIo Class Reference

#include <vpImageIo.h>

Static Public Member Functions

static void read (vpImage< unsigned char > &I, const std::string &filename)
 
static void read (vpImage< vpRGBa > &I, const std::string &filename)
 
static void write (const vpImage< unsigned char > &I, const std::string &filename)
 
static void write (const vpImage< vpRGBa > &I, const std::string &filename)
 
static void readPFM (vpImage< float > &I, const std::string &filename)
 
static void readPGM (vpImage< unsigned char > &I, const std::string &filename)
 
static void readPGM (vpImage< vpRGBa > &I, const std::string &filename)
 
static void readPPM (vpImage< unsigned char > &I, const std::string &filename)
 
static void readPPM (vpImage< vpRGBa > &I, const std::string &filename)
 
static void readJPEG (vpImage< unsigned char > &I, const std::string &filename)
 
static void readJPEG (vpImage< vpRGBa > &I, const std::string &filename)
 
static void readPNG (vpImage< unsigned char > &I, const std::string &filename)
 
static void readPNG (vpImage< vpRGBa > &I, const std::string &filename)
 
static void writePFM (const vpImage< float > &I, const std::string &filename)
 
static void writePGM (const vpImage< unsigned char > &I, const std::string &filename)
 
static void writePGM (const vpImage< short > &I, const std::string &filename)
 
static void writePGM (const vpImage< vpRGBa > &I, const std::string &filename)
 
static void writePPM (const vpImage< unsigned char > &I, const std::string &filename)
 
static void writePPM (const vpImage< vpRGBa > &I, const std::string &filename)
 
static void writeJPEG (const vpImage< unsigned char > &I, const std::string &filename)
 
static void writeJPEG (const vpImage< vpRGBa > &I, const std::string &filename)
 
static void writePNG (const vpImage< unsigned char > &I, const std::string &filename)
 
static void writePNG (const vpImage< vpRGBa > &I, const std::string &filename)
 

Detailed Description

Read/write images with various image format.

This class has its own implementation of PGM and PPM images read/write.

This class may benefit from optional 3rd parties:

  • libpng: If installed this optional 3rd party is used to read/write PNG images. Installation instructions are provided here https://visp.inria.fr/3rd_png.
  • libjpeg: If installed this optional 3rd party is used to read/write JPEG images. Installation instructions are provided here https://visp.inria.fr/3rd_jpeg.
  • OpenCV: If installed this optional 3rd party is used to read/write other image formats TIFF, BMP, DIB, PBM, RASTER, JPEG2000. If libpng or libjpeg is not installed OpenCV is also used to consider these image formats. Installation instructions are provided here https://visp.inria.fr/3rd_opencv.

The code below shows how to convert an PPM P6 image file format into a PGM P5 image file format. The extension of the filename is here used in read() and write() functions to set the image file format (".pgm" for PGM P5 and ".ppm" for PPM P6).

#include <visp3/io/vpImageIo.h>
int main()
{
#if defined(_WIN32)
std::string filename("C:/temp/ViSP-images/Klimt/Klimt.ppm");
#else // UNIX
std::string filename("/local/soft/ViSP/ViSP-images/Klimt/Klimt.ppm");
#endif
vpImageIo::read(I, filename); // Convert the color image in a gray level image
vpImageIo::write(I, "Klimt.pgm"); // Write the image in a PGM P5 image file format
}

This other example available in tutorial-image-reader.cpp shows how to read/write jpeg images. It supposes that libjpeg is installed.

#include <visp3/io/vpImageIo.h>
int main()
{
try {
vpImageIo::read(I, "monkey.jpeg");
vpImageIo::write(I, "monkey.png");
} catch (const vpException &e) {
std::cout << e.getMessage() << std::endl;
} catch (...) {
std::cout << "Unsupported image format" << std::endl;
}
}

Definition at line 103 of file vpImageIo.h.

Member Function Documentation

◆ read() [1/2]

void vpImageIo::read ( vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Read the contents of the image filename, allocate memory for the corresponding greyscale image, update its content, and return a reference to the image.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Always supported formats are *.pgm and *.ppm. JPEG and PNG formats are supported through the stb_image public domain image loader. If libjpeg 3rd party is used, we support also *.jpg and *.jpeg files. If libpng 3rd party is used, we support also *.png files. If OpenCV 3rd party is used, we support *.jpg, *.jpeg, *.jp2, *.rs, *.ras, .tiff, *.tif, *.png, *.bmp, *.pbm files.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.
Examples
displayD3D.cpp, displayGTK.cpp, displayOpenCV.cpp, displaySequence.cpp, displayX.cpp, displayXMulti.cpp, fernClassifier.cpp, histogram.cpp, imageDiskRW.cpp, keyPointSurf.cpp, manDisplay.cpp, mbtGenericTrackingDepth.cpp, mbtGenericTrackingDepthOnly.cpp, photometricVisualServoing.cpp, planarObjectDetector.cpp, poseVirtualVS.cpp, testAprilTag.cpp, testAutoThreshold.cpp, testClick.cpp, testConnectedComponents.cpp, testContours.cpp, testConversion.cpp, testCrop.cpp, testCropAdvanced.cpp, testFloodFill.cpp, testGenericTracker.cpp, testGenericTrackerDepth.cpp, testHistogram.cpp, testImageAddSub.cpp, testImageComparison.cpp, testImageFilter.cpp, testImageMorphology.cpp, testImageResize.cpp, testImageWarp.cpp, testImgproc.cpp, testIoPGM.cpp, testIoPPM.cpp, testKeyPoint-2.cpp, testKeyPoint-3.cpp, testKeyPoint-4.cpp, testKeyPoint-5.cpp, testKeyPoint-6.cpp, testKeyPoint-7.cpp, testKeyPoint.cpp, testMomentAlpha.cpp, testMouseEvent.cpp, testPerformanceLUT.cpp, testReadImage.cpp, testTrackDot.cpp, testUndistortImage.cpp, testVideoDevice.cpp, trackDot.cpp, trackDot2.cpp, trackDot2WithAutoDetection.cpp, trackKltOpencv.cpp, trackMeCircle.cpp, trackMeEllipse.cpp, trackMeLine.cpp, tutorial-apriltag-detector.cpp, tutorial-autothreshold.cpp, tutorial-barcode-detector.cpp, tutorial-blob-auto-tracker.cpp, tutorial-bridge-opencv.cpp, tutorial-brightness-adjustment.cpp, tutorial-connected-components.cpp, tutorial-contour.cpp, tutorial-contrast-sharpening.cpp, tutorial-count-coins.cpp, tutorial-detection-object-mbt2-deprecated.cpp, tutorial-detection-object-mbt2.cpp, tutorial-ibvs-4pts-image-tracking.cpp, tutorial-image-filter.cpp, tutorial-image-reader.cpp, tutorial-image-simulator.cpp, tutorial-image-viewer.cpp, tutorial-mb-generic-tracker-rgbd-blender.cpp, tutorial-mb-generic-tracker-rgbd.cpp, tutorial-pose-from-points-image.cpp, tutorial-pose-from-qrcode-image.cpp, tutorial-undistort.cpp, and tutorial-viewer.cpp.

Definition at line 242 of file vpImageIo.cpp.

Referenced by vpMbTracker::initClick(), and vpVirtualGrabber::vpVirtualGrabber().

◆ read() [2/2]

void vpImageIo::read ( vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Read the contents of the image filename, allocate memory for the corresponding color image, update its content, and return a reference to the image.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Always supported formats are *.pgm and *.ppm. JPEG and PNG formats are supported through the stb_image public domain image loader. If libjpeg 3rd party is used, we support also *.jpg and *.jpeg files. If libpng 3rd party is used, we support also *.png files. If OpenCV 3rd party is used, we support *.jpg, *.jpeg, *.jp2, *.rs, *.ras, .tiff, *.tif, *.png, *.bmp, *.pbm files.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 346 of file vpImageIo.cpp.

◆ readJPEG() [1/2]

void vpImageIo::readJPEG ( vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Read the contents of the JPEG file, allocate memory for the corresponding gray level image, if necessary convert the data in gray level, and set the bitmap whith the gray level data. That means that the image I is a "black and white" rendering of the original image in filename, as in a black and white photograph. If necessary, the quantization formula used is $0,299 r + 0,587 g + 0,114 b$.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 1182 of file vpImageIo.cpp.

◆ readJPEG() [2/2]

void vpImageIo::readJPEG ( vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Read a JPEG file and initialize a scalar image.

Read the contents of the JPEG file, allocate memory for the corresponding image, and set the bitmap whith the content of the file.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

If the file corresponds to a grayscaled image, a conversion is done to deal with I which is a color image.

Parameters
I: Color image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 1262 of file vpImageIo.cpp.

◆ readPFM()

void vpImageIo::readPFM ( vpImage< float > &  I,
const std::string &  filename 
)
static

Read a PFM P8 file and initialize a float image.

Read the contents of the portable gray pixmap (PFM P8) filename, allocate memory for the corresponding image, and set the bitmap whith the content of the file.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 767 of file vpImageIo.cpp.

◆ readPGM() [1/2]

void vpImageIo::readPGM ( vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Read a PGM P5 file and initialize a scalar image.

Read the contents of the portable gray pixmap (PGM P5) filename, allocate memory for the corresponding image, and set the bitmap whith the content of the file.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 821 of file vpImageIo.cpp.

◆ readPGM() [2/2]

void vpImageIo::readPGM ( vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Read a PGM P5 file and initialize a scalar image.

Read the contents of the portable gray pixmap (PGM P5) filename, allocate memory for the corresponding image, and set the bitmap whith the content of the file.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

The gray level image contained in the filename is converted in a color image in I.

Parameters
I: Color image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 878 of file vpImageIo.cpp.

◆ readPNG() [1/2]

void vpImageIo::readPNG ( vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Read the contents of the PNG file, allocate memory for the corresponding gray level image, if necessary convert the data in gray level, and set the bitmap whith the gray level data. That means that the image I is a "black and white" rendering of the original image in filename, as in a black and white photograph. If necessary, the quantization formula used is $0,299 r + 0,587 g + 0,114 b$.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 1719 of file vpImageIo.cpp.

◆ readPNG() [2/2]

void vpImageIo::readPNG ( vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Read a PNG file and initialize a scalar image.

Read the contents of the PNG file, allocate memory for the corresponding image, and set the bitmap whith the content of the file.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

If the file corresponds to a grayscaled image, a conversion is done to deal with I which is a color image.

Parameters
I: Color image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 1896 of file vpImageIo.cpp.

◆ readPPM() [1/2]

void vpImageIo::readPPM ( vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Read the contents of the portable pixmap (PPM P6) filename, allocate memory for the corresponding gray level image, convert the data in gray level, and set the bitmap whith the gray level data. That means that the image I is a "black and white" rendering of the original image in filename, as in a black and white photograph. The quantization formula used is $0,299 r + 0,587 g + 0,114 b$.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 907 of file vpImageIo.cpp.

◆ readPPM() [2/2]

void vpImageIo::readPPM ( vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Read the contents of the portable pixmap (PPM P6) filename, allocate memory for the corresponding vpRGBa image.

If the image has been already initialized, memory allocation is done only if the new image size is different, else we re-use the same memory space.

Parameters
I: Image to set with the filename content.
filename: Name of the file containing the image.

Definition at line 927 of file vpImageIo.cpp.

◆ write() [1/2]

void vpImageIo::write ( const vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Write the content of the image in the file which name is given by filename.

Always supported formats are *.pgm and *.ppm. JPEG and PNG formats are supported through the stb_image_write public domain image writer. If libjpeg 3rd party is used, we support also *.jpg and *.jpeg files. If libpng 3rd party is used, we support also *.png files. If OpenCV 3rd party is used, we support *.jpg, *.jpeg, *.jp2, *.rs, *.ras, .tiff, *.tif, *.png, *.bmp, *.pbm files.

Parameters
I: Image to write.
filename: Name of the file containing the image.
Examples
displayD3D.cpp, displayGTK.cpp, displayOpenCV.cpp, displayX.cpp, displayXMulti.cpp, grab1394CMU.cpp, grab1394Two.cpp, grabDirectShow.cpp, grabDirectShowMulti.cpp, grabFlyCapture.cpp, grabV4l2.cpp, imageDiskRW.cpp, manDisplay.cpp, manGeometricFeatures.cpp, mbot-apriltag-2D-half-vs.cpp, mbot-apriltag-ibvs.cpp, mbot-apriltag-pbvs.cpp, servoAfma6Points2DCamVelocityEyeToHand.cpp, SickLDMRS-Process.cpp, sonarPioneerReader.cpp, test1394TwoGrabber.cpp, testAutoThreshold.cpp, testConnectedComponents.cpp, testContours.cpp, testConversion.cpp, testCrop.cpp, testCropAdvanced.cpp, testFloodFill.cpp, testGenericTracker.cpp, testImageAddSub.cpp, testImageDraw.cpp, testImgproc.cpp, testIoPGM.cpp, testIoPPM.cpp, testPerformanceLUT.cpp, testPylonGrabber.cpp, testUndistortImage.cpp, tutorial-bridge-opencv.cpp, tutorial-brightness-adjustment.cpp, tutorial-export-image.cpp, tutorial-franka-acquire-calib-data.cpp, tutorial-image-converter.cpp, tutorial-image-reader.cpp, tutorial-image-simulator.cpp, tutorial-image-viewer.cpp, and tutorial-undistort.cpp.

Definition at line 444 of file vpImageIo.cpp.

Referenced by vpSimulator::write().

◆ write() [2/2]

void vpImageIo::write ( const vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Write the content of the image in the file which name is given by filename.

Always supported formats are *.pgm and *.ppm. JPEG and PNG formats are supported through the stb_image_write public domain image writer. If libjpeg 3rd party is used, we support also *.jpg and *.jpeg files. If libpng 3rd party is used, we support also *.png files. If OpenCV 3rd party is used, we support *.jpg, *.jpeg, *.jp2, *.rs, *.ras, .tiff, *.tif, *.png, *.bmp, *.pbm files.

Parameters
I: Image to write.
filename: Name of the file containing the image.

Definition at line 523 of file vpImageIo.cpp.

◆ writeJPEG() [1/2]

void vpImageIo::writeJPEG ( const vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a JPEG file.

Parameters
I: Image to save as a JPEG file.
filename: Name of the file containing the image.

Definition at line 1054 of file vpImageIo.cpp.

◆ writeJPEG() [2/2]

void vpImageIo::writeJPEG ( const vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a JPEG file.

Parameters
I: Image to save as a JPEG file.
filename: Name of the file containing the image.

Definition at line 1111 of file vpImageIo.cpp.

◆ writePFM()

void vpImageIo::writePFM ( const vpImage< float > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function is built like portable gray pixmap (eg PGM P5) file. but considers float image data.

Parameters
I: Image to save as a (PFM P8) file.
filename: Name of the file containing the image.

Definition at line 601 of file vpImageIo.cpp.

◆ writePGM() [1/3]

void vpImageIo::writePGM ( const vpImage< short > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a portable gray pixmap (PGM P5) file.

Parameters
I: Image to save as a (PGM P5) file.
filename: Name of the file containing the image.

Definition at line 690 of file vpImageIo.cpp.

◆ writePGM() [2/3]

void vpImageIo::writePGM ( const vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a portable gray pixmap (PGM P5) file.

Parameters
I: Image to save as a (PGM P5) file.
filename: Name of the file containing the image.

Definition at line 647 of file vpImageIo.cpp.

◆ writePGM() [3/3]

void vpImageIo::writePGM ( const vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a portable gray pixmap (PGM P5) file. Color image is converted into a grayscale image.

Parameters
I: Image to save as a (PGM P5) file.
filename: Name of the file containing the image.

Definition at line 712 of file vpImageIo.cpp.

◆ writePNG() [1/2]

void vpImageIo::writePNG ( const vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a PNG file.

Parameters
I: Image to save as a PNG file.
filename: Name of the file containing the image.

Definition at line 1510 of file vpImageIo.cpp.

◆ writePNG() [2/2]

void vpImageIo::writePNG ( const vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Write the content of the image bitmap in the file which name is given by filename. This function writes a PNG file.

Parameters
I: Image to save as a PNG file.
filename: Name of the file containing the image.

Definition at line 1607 of file vpImageIo.cpp.

◆ writePPM() [1/2]

void vpImageIo::writePPM ( const vpImage< unsigned char > &  I,
const std::string &  filename 
)
static

Write the content of the bitmap in the file which name is given by filename. This function writes a portable gray pixmap (PPM P6) file. grayscale image is converted into a color image vpRGBa.

Parameters
I: Image to save as a (PPM P6) file.
filename: Name of the file containing the image.

Definition at line 986 of file vpImageIo.cpp.

◆ writePPM() [2/2]

void vpImageIo::writePPM ( const vpImage< vpRGBa > &  I,
const std::string &  filename 
)
static

Write the content of the bitmap in the file which name is given by filename. This function writes a portable gray pixmap (PPM P6) file.

Parameters
I: Image to save as a (PPM P6) file.
filename: Name of the file containing the image.

Definition at line 1002 of file vpImageIo.cpp.

vpImageIo::read
static void read(vpImage< unsigned char > &I, const std::string &filename)
Definition: vpImageIo.cpp:242
vpImageIo::write
static void write(const vpImage< unsigned char > &I, const std::string &filename)
Definition: vpImageIo.cpp:444
vpException::getMessage
const char * getMessage(void) const
Definition: vpException.cpp:89
vpImage< unsigned char >
vpException
error that can be emited by ViSP classes.
Definition: vpException.h:70