#include <visp3/io/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()
{
  vpImage<unsigned char> I;
#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 {
    vpImage<vpRGBa> I;
    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 104 of file vpImageIo.h.

Member Function Documentation

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, 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 234 of file vpImageIo.cpp.

References vpIoTools::checkFilename(), vpImageConvert::convert(), vpImageException::ioError, vpIoTools::path(), readJPEG(), readPGM(), readPNG(), and readPPM().

Referenced by vpDiskGrabber::acquire(), vpImageSimulator::init(), vpMbTracker::initClick(), vpKeyPoint::loadLearningData(), and vpVirtualGrabber::vpVirtualGrabber().

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 338 of file vpImageIo.cpp.

References vpIoTools::checkFilename(), vpImageConvert::convert(), vpImageException::ioError, vpIoTools::path(), readJPEG(), readPGM(), readPNG(), and readPPM().

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 1174 of file vpImageIo.cpp.

References vpRGBa::alpha_default, vpImage< Type >::bitmap, vpImageConvert::convert(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImageException::ioError, and vpImage< Type >::resize().

Referenced by read(), and readJPEG().

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 1254 of file vpImageIo.cpp.

References vpRGBa::alpha_default, vpImage< Type >::bitmap, vpImageConvert::convert(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImage< Type >::init(), vpImageException::ioError, readJPEG(), vpImage< Type >::resize(), and writeJPEG().

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 759 of file vpImageIo.cpp.

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

Referenced by vpDiskGrabber::acquire().

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 813 of file vpImageIo.cpp.

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

Referenced by read(), and readPGM().

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 870 of file vpImageIo.cpp.

References vpImageConvert::convert(), and readPGM().

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 1711 of file vpImageIo.cpp.

References vpRGBa::alpha_default, vpImage< Type >::bitmap, vpImageConvert::convert(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImageException::ioError, vpImage< Type >::resize(), and vpERROR_TRACE.

Referenced by read(), and readPNG().

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 1888 of file vpImageIo.cpp.

References vpRGBa::alpha_default, vpImage< Type >::bitmap, vpImageConvert::convert(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImage< Type >::init(), vpImageException::ioError, readPNG(), vpImage< Type >::resize(), vpERROR_TRACE, and writePNG().

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 899 of file vpImageIo.cpp.

References vpImageConvert::convert().

Referenced by read().

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 919 of file vpImageIo.cpp.

References vpRGBa::alpha_default, vpException::badValue, vpImage< Type >::getHeight(), vpImage< Type >::getSize(), vpImage< Type >::getWidth(), vpImageException::ioError, and vpImage< Type >::resize().

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, testImageAddSub.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 436 of file vpImageIo.cpp.

References vpImageConvert::convert(), vpImageException::ioError, vpCERROR, writeJPEG(), writePGM(), writePNG(), and writePPM().

Referenced by vpVideoWriter::saveFrame(), vpKeyPoint::saveLearningData(), and vpSimulator::write().

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 515 of file vpImageIo.cpp.

References vpImageConvert::convert(), vpImageException::ioError, vpCERROR, writeJPEG(), writePGM(), writePNG(), and writePPM().

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 1046 of file vpImageIo.cpp.

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

Referenced by readJPEG(), and write().

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 1103 of file vpImageIo.cpp.

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

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 593 of file vpImageIo.cpp.

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

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 639 of file vpImageIo.cpp.

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

Referenced by write(), and writePGM().

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 682 of file vpImageIo.cpp.

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

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 704 of file vpImageIo.cpp.

References vpImage< Type >::bitmap, vpImageConvert::convert(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpImageException::ioError.

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 1502 of file vpImageIo.cpp.

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

Referenced by readPNG(), and write().

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 1599 of file vpImageIo.cpp.

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

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 978 of file vpImageIo.cpp.

References vpImageConvert::convert().

Referenced by write().

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 994 of file vpImageIo.cpp.

References vpRGBa::B, vpRGBa::G, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpImageException::ioError, and vpRGBa::R.

Static Public Member Functions

Detailed Description

Member Function Documentation