Taevitas/third_party/include/flycapture/Image.h

//=============================================================================
// Copyright <20> 2008 Point Grey Research, Inc. All Rights Reserved.
//
// This software is the confidential and proprietary information of Point
// Grey Research, Inc. ("Confidential Information").  You shall not
// disclose such Confidential Information and shall use it only in
// accordance with the terms of the license agreement you entered into
// with Point Grey Research, Inc. (PGR).
//
// PGR MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
// SOFTWARE, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE, OR NON-INFRINGEMENT. PGR SHALL NOT BE LIABLE FOR ANY DAMAGES
// SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
// THIS SOFTWARE OR ITS DERIVATIVES.
//=============================================================================

//=============================================================================
// $Id: Image.h 244578 2015-08-21 23:30:57Z matthewg $
//=============================================================================

#ifndef PGR_FC2_IMAGE_H
#define PGR_FC2_IMAGE_H

#include "FlyCapture2Platform.h"
#include "FlyCapture2Defs.h"

namespace FlyCapture2
{
	class Error;
	class ImageStatistics;

	/**
	 * The Image class is used to retrieve images from a camera, convert
	 * between multiple pixel formats and save images to disk. Operations on
	 * Image objects are not guaranteed to be thread safe. It is recommended
	 * that operations on Image objects be protected by thread synchronization
	 * constructs such as mutexes.
	 */
	class FLYCAPTURE2_API Image
	{
		public:

			/**
			 * Set the default color processing algorithm.  This method will be
			 * used for any image with the DEFAULT algorithm set. The method used
			 * is determined at the time of the Convert() call, therefore the most
			 * recent execution of this function will take precedence. The default
			 * setting is shared within the current process.
			 *
			 * @param defaultMethod The color processing algorithm to set.
			 *
			 * @see GetDefaultColorProcessing()
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			static Error SetDefaultColorProcessing(
					ColorProcessingAlgorithm defaultMethod );

			/**
			 * Get the default color processing algorithm.
			 *
			 * @see SetDefaultColorProcessing()
			 *
			 * @return The default color processing algorithm.
			 */
			static ColorProcessingAlgorithm GetDefaultColorProcessing();

			/**
			 * Set the default output pixel format. This format will be used for any
			 * call to Convert() that does not specify an output format. The format
			 * used will be determined at the time of the Convert() call, therefore
			 * the most recent execution of this function will take precedence.
			 * The default is shared within the current process.
			 *
			 * @param format The output pixel format to set.
			 *
			 * @see GetDefaultOutputFormat()
			 *
			 * @return The default color processing algorithm.
			 */
			static Error SetDefaultOutputFormat( PixelFormat format );

			/**
			 * Get the default output pixel format.
			 *
			 * @see SetDefaultOutputFormat()
			 *
			 * @return The default pixel format.
			 */
			static PixelFormat GetDefaultOutputFormat();

			/**
			 * Calculate the bits per pixel for the specified pixel format.
			 *
			 * @param format The pixel format.
			 *
			 * @return The bits per pixel.
			 */
			static unsigned int DetermineBitsPerPixel( PixelFormat format );

			/**
			 * Default constructor.
			 */
			Image();

			/**
			 * Construct an Image object with the specified arguments.
			 * Ownership of the image buffer is not transferred to the Image object.
			 * It is the user's responsibility to delete the buffer when it is
			 * no longer in use.
			 *
			 * @param rows Rows in the image.
			 * @param cols Columns in the image.
			 * @param stride Stride of the image buffer.
			 * @param pData Pointer to the image buffer.
			 * @param dataSize Size of the image buffer.
			 * @param format Pixel format.
			 * @param bayerFormat Format of the Bayer tiled raw image.
			 */
			Image(
					unsigned int    rows,
					unsigned int    cols,
					unsigned int    stride,
					unsigned char*  pData,
					unsigned int    dataSize,
					PixelFormat     format,
					BayerTileFormat bayerFormat = NONE );

			/**
			 * Construct an Image object with the specified arguments.
			 * Ownership of the image buffer is not transferred to the Image object.
			 * It is the user's responsibility to delete the buffer when it is
			 * no longer in use.
			 *
			 * @param rows Rows in the image.
			 * @param cols Columns in the image.
			 * @param stride Stride of the image buffer.
			 * @param pData Pointer to the image buffer.
			 * @param dataSize Size of the image buffer.
			 * @param receivedDataSize Actual size of data.
			 * @param format Pixel format.
			 * @param bayerFormat Format of the Bayer tiled raw image.
			 */
			Image(
					unsigned int    rows,
					unsigned int    cols,
					unsigned int    stride,
					unsigned char*  pData,
					unsigned int    dataSize,
					unsigned int    receivedDataSize,
					PixelFormat     format,
					BayerTileFormat bayerFormat = NONE );

			/**
			 * Construct an Image object with the specified arguments.
			 * Ownership of the image buffer is not transferred to the Image object.
			 * It is the user's responsibility to delete the buffer when it is
			 * no longer in use.
			 *
			 * @param pData Pointer to the image buffer.
			 * @param dataSize Size of the image buffer.
			 */
			Image(
					unsigned char* pData,
					unsigned int   dataSize);

			/**
			 * Construct an Image object with the specified arguments.
			 *
			 * @param rows Rows in the image.
			 * @param cols Columns in the image.
			 * @param format Pixel format.
			 * @param bayerFormat Format of the Bayer tiled raw image.
			 */
			Image(
					unsigned int    rows,
					unsigned int    cols,
					PixelFormat     format,
					BayerTileFormat bayerFormat = NONE );

			/**
			 * Copy constructor. Both images will point to the same image buffer
			 * internally.
			 */
			Image( const Image& image );

			/**
			 * Default destructor. The internal image buffer will be released if
			 * there are no other Image objects holding a reference to it. This
			 * will also allow the buffer to be requeued internally.
			 */
			virtual ~Image();

			/**
			 * Assignment operator. Both images will point to the same image buffer
			 * internally. If the Image already has a buffer attached to it, it will
			 * will be released.
			 *
			 * @param image The image to copy from.
			 */
			virtual Image& operator=( const Image& image );

			/**
			 * Indexing operator.
			 *
			 * @param index The index of the byte to return.
			 *
			 * @return The address of the specified byte from the image data.
			 */
			virtual unsigned char* operator[]( unsigned int index );

			/**
			 * Indexing operator.
			 *
			 * @param row The row of the pixel to return.
			 * @param col The column of the pixel to return.
			 *
			 * @return The address of the specified byte from the image data.
			 */
			virtual unsigned char* operator()(
					unsigned int row,
					unsigned int col );

			/**
			 * Perform a deep copy of the Image. After this operation, the image
			 * contents and member variables will be the same. The Images will not
			 * share a buffer. The Image's current buffer will not be released.
			 *
			 * @param pImage The Image to copy the data from.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error DeepCopy( const Image* pImage );

			/**
			 * Sets the dimensions of the image object.
			 *
			 * @param rows Number of rows to set.
			 * @param cols Number of cols to set.
			 * @param stride Stride to set.
			 * @param pixelFormat Pixel format to set.
			 * @param bayerFormat Bayer tile format to set.
			 *
			 * @see GetDimensions()
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error SetDimensions(
					unsigned int    rows,
					unsigned int    cols,
					unsigned int    stride,
					PixelFormat     pixelFormat,
					BayerTileFormat bayerFormat );

			/**
			 * Set the data of the Image object.
			 * Ownership of the image buffer is not transferred to the Image object.
			 * It is the user's responsibility to delete the buffer when it is
			 * no longer in use.
			 *
			 * @param pData Pointer to the image buffer.
			 * @param dataSize Size of the image buffer.
			 */
			virtual Error SetData(
					const unsigned char* pData,
					unsigned int         dataSize );

			/**
			 * Set the block id of the Image object.
			 *
			 * @param blockId The blockId to assign to the image.
			 */
			virtual Error SetBlockId( const unsigned int blockId);

			/**
			 * get the block id of the Image object.
			 *
			 * @return The blockId assigned to the image.
			 */
			virtual unsigned int GetBlockId();

			/**
			 * Get the current pixel format.
			 *
			 * @return The current pixel format.
			 */
			virtual PixelFormat GetPixelFormat() const;

			/**
			 * Get the current color processing algorithm.
			 *
			 * @see SetColorProcessing()
			 *
			 * @return The current color processing algorithm.
			 */
			virtual ColorProcessingAlgorithm GetColorProcessing() const;

			/**
			 * Set the color processing algorithm. This should be set on the
			 * input Image object.
			 *
			 * @param colorProc The color processing algorithm to use.
			 *
			 * @see GetColorProcessing()
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error SetColorProcessing( ColorProcessingAlgorithm colorProc );

			/**
			 * Get the number of columns in the image.
			 *
			 * @return The number of columns.
			 */
			virtual unsigned int GetCols() const;

			/**
			 * Get the number of rows in the image.
			 *
			 * @return The number of rows.
			 */
			virtual unsigned int GetRows() const;

			/**
			 * Get the stride in the image.
			 *
			 * @return The stride (The number of bytes between rows of the image).
			 */
			virtual unsigned int GetStride() const;

			/**
			 * Get the bits per pixel of the image.
			 *
			 * @return The bits per pixel.
			 */
			virtual unsigned int GetBitsPerPixel() const;

			/**
			 * Get the Bayer tile format of the image.
			 *
			 * @return The Bayer tile format.
			 */
			virtual BayerTileFormat GetBayerTileFormat() const;

			/**
			 * Get the size of the buffer associated with the image, in bytes.
			 *
			 * @return The size of the buffer, in bytes.
			 */
			virtual unsigned int GetDataSize() const;

			/**
			 * Get the size of the compressed data, in bytes. A compressed image
			 * will have a maximum size equal to GetDataSize(), but may actually
			 * contain less data, depending on the compression level.
			 * For uncompressed images, a value smaller than the data size may
			 * indicate lost data.
			 *
			 * @return The size of the compressed data, in bytes. 0 when camera
			 *         not sending compressed data.
			 */
			virtual unsigned int GetReceivedDataSize() const;

			/**
			 * Get the image dimensions associated with the image.
			 *
			 * @param pRows Number of rows.
			 * @param pCols Number of columns.
			 * @param pStride The stride.
			 * @param pPixelFormat Pixel format.
			 * @param pBayerFormat Bayer tile format.
			 */
			virtual void GetDimensions(
					unsigned int*    pRows,
					unsigned int*    pCols = NULL,
					unsigned int*    pStride = NULL,
					PixelFormat*     pPixelFormat = NULL,
					BayerTileFormat* pBayerFormat = NULL ) const;

			/**
			 * Get a pointer to the data associated with the image. This function
			 * is considered unsafe. The pointer returned could be invalidated if
			 * the buffer is resized or released. The pointer may also be
			 * invalidated if the Image object is passed to
			 * Camera::RetrieveBuffer(). It is recommended that a Image::DeepCopy()
			 * be performed if a seperate copy of the Image data is required
			 * for further processing.
			 *
			 * @return A pointer to the image data.
			 */
			virtual unsigned char* GetData();

			virtual unsigned char* const GetData() const;

			/**
			 * Get the metadata associated with the image. This includes
			 * embedded image information.
			 *
			 * @return Metadata associated with the image.
			 */
			virtual ImageMetadata GetMetadata() const;

			/**
			 * Calculate statistics associated with the image. In order to collect
			 * statistics for a particular channel, the enabled flag for the
			 * channel must be set to true. Statistics can only be collected for
			 * images in Mono8, Mono16, RGB, RGBU, BGR and BGRU.
			 *
			 * @param pStatistics The ImageStatistics object to hold the statistics.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error CalculateStatistics( ImageStatistics* pStatistics );

			/**
			 * Get the timestamp data associated with the image.
			 *
			 * @return Timestamp data associated with the image.
			 */
			virtual TimeStamp GetTimeStamp() const;

			/**
			 * Save the image to the specified file name with the file format
			 * specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param format File format to save in.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					ImageFileFormat format = FROM_FILE_EXT );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					PNGOption*      pOption );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					PPMOption*      pOption );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					PGMOption*      pOption );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					TIFFOption*      pOption );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					JPEGOption*     pOption );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					JPG2Option*     pOption );

			/**
			 * Save the image to the specified file name with the options specified.
			 *
			 * @param pFilename Filename to save image with.
			 * @param pOption Options to use while saving image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Save(
					const char*     pFilename,
					BMPOption*     pOption );

			/**
			 * Converts the current image buffer to the specified output format and
			 * stores the result in the specified image. The destination image
			 * does not need to be configured in any way before the call is made.
			 *
			 * @param format Output format of the converted image.
			 * @param pDestImage Destination image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Convert(
					PixelFormat format,
					Image*      pDestImage ) const;

			/**
			 * Converts the current image buffer to the specified output format and
			 * stores the result in the specified image. The destination image
			 * does not need to be configured in anyway before the call is made.
			 *
			 * @param pDestImage Destination image.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error Convert( Image* pDestImage ) const;

			/**
			 * Release the buffer associated with the Image. If no buffer is
			 * associated, the function does nothing.
			 *
			 * @return An Error indicating the success or failure of the function.
			 */
			virtual Error ReleaseBuffer();

		protected:

		private:
			friend class Iso;
			struct ImageImpl;
			ImageImpl* m_pImpl;
	};
}

#endif //PGR_FC2_IMAGE_H