VideoSource_Base.hh

/*
This file is part of the BIAS library (Basic ImageAlgorithmS).

Copyright (C) 2003-2009 (see file CONTACT for details)
Multimediale Systeme der Informationsverarbeitung
Institut fuer Informatik
Christian-Albrechts-Universitaet Kiel

BIAS is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

BIAS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with BIAS; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

#ifndef __BIASVIDEOSOURCE_HH__
#define __BIASVIDEOSOURCE_HH__

#include <bias_config.h>
#include <vector>
#include <Base/Image/Image.hh>
#include <Base/Common/BIASpragmaStart.hh>
#include <Image/VideoStream.hh>

#define D_V4L  (1<<0)
#define D_DCAM (1<<1)
#define D_VSO_DISK (1<<2)
#define D_DCAM_F7 (1<<3)
#define D_DV (1<<4)
#define D_VS_WHITEB (1<<5)
#define D_NET (1<<6)
#define D_DV2 (1<<8)
#define D_DTD (1<<9)

namespace BIAS{

  // forward declaration
  template <class T> class BIASVideoSource_EXPORT Camera;

  class BIASVideoSource_EXPORT VideoSourceCapabilities;

  /**
      \class VideoSource
      \ingroup g_videosource
      \author evers
      \brief  Defines a common interface to different devices.

      Specialized classes for each deviceclass should be derived and most methods
      have to be reimplemented.

      Usage:

      VideoSource *foo;

      Image<type> bar;

      /// assume to have a class for DCAM cams
      foo = new VideoSource_DCAM;

      /// select a colormode with SetColorMode() if required
      //  the default colormode depends on the used Camera(kind of VideoSource)

      // set a image size for grabbing foo->SetSize(width,height)
      foo->SetSize(768,576);

      /// Want to take the second channel (what ever this means)
      foo->SetChannel(2);

      /// take the first appropriate device
      foo->OpenDevice();

      foo->InitImage(bar);

      // do last preparations
      foo->PreGrab();

      // get one frame
      foo->GrabSingle(bar);

      // stop enetually running things (isochronous transfers for example)
      foo->PostGrab();

      // clean up
      foo->CloseDevice();
  */

  class BIASVideoSource_EXPORT VideoSource : public BIAS::Debug
  {

  public:
    VideoSource();  
    virtual ~VideoSource();

    /// selects the first available device to open (e.g. /dev/video0 for V4L,
    /// id 0 = first camera for DCAM/DV)
    virtual int OpenDevice();

    /// a device name like "/dev/video1" can be specified here
    virtual int OpenDevice(const char *device);

    /// a device number  can be specified here (DCAM) or port number (Net)
    virtual int OpenDevice(int device);

    /// used by derived class VideoSource_Disk
    virtual int OpenDevice(std::string Prefix, std::string Postfix,
                           int DigitCount, int PictureCount,int StartCount=0);

    /// used by derived class VideoSource_Disk
    virtual int OpenDevice(const std::vector<std::string> &FileNames);

    virtual int CloseDevice();

    virtual int GetAllDevices(std::vector<std::string> &devices);

    virtual int GrabSingle(BIAS::Camera <unsigned char> &image);
    virtual int GrabSingle(BIAS::Camera <float> &image);
#ifdef BUILD_IMAGE_CHAR
    virtual int GrabSingle(BIAS::Camera <char> &image);
#endif
#ifdef BUILD_IMAGE_SHORT
    virtual int GrabSingle(BIAS::Camera <short int> &image);
#endif
#ifdef BUILD_IMAGE_INT
    virtual int GrabSingle(BIAS::Camera <int> &image);
#endif
#ifdef BUILD_IMAGE_USHORT
    virtual int GrabSingle(BIAS::Camera <unsigned short int> &image);
#endif
#ifdef BUILD_IMAGE_UINT
    virtual int GrabSingle(BIAS::Camera <unsigned int> &image);
#endif
#ifdef BUILD_IMAGE_DOUBLE
    virtual int GrabSingle(BIAS::Camera <double> &image);
#endif
    /// Do last preparations before grabbing (e.g. start ISO transfer)
    virtual int PreGrab();

    /// Stop anything started in PreGrab()
    virtual int PostGrab();

    // The following functions are not inline to let other class overload them,
    // but they are still implemented for this class.

    /** Set image size and number of bytes per pixel (e.g. 1 = 8 bit gray image)
        @attention Must be used before OpenDevice()!
    */
    virtual void SetSize(int w, int h, int bytesperpixel=1);

    /** Select colormodel to use. Not all sources support all colormodels.
        @attention Must be used before OpenDevice()!
+    */
    virtual int SetColorModel(BIAS::ImageBase::EColorModel  mode);

    /** Use channel to select one of many cameras on the same
        @attention Must be used before OpenDevice()!
    */
    void SetDeviceChannel(int channel) { DeviceChannel_ = channel; }

    /** If more than one channel is present, names can be returned here.
        The position in the vector corresponds to the channel number in SetChannel().
     */
    virtual void GetDeviceChannelNames(std::vector<std::string> &names) {}

    /** Set frame per second for image capturing.
        @attention Must be used before OpenDevice()!
     */
    void SetFPS(float fps) { FramesPerSecond_ = fps; }

    /** @brief Specify if there is an external trigger to be used.
        @param[in] trigger Specifies if external trigger should be acticated
     */
    virtual void SetExternalTrigger(bool trigger = true) { bExternalTrigger_ = trigger; }
    
    /** @attention Must be used before OpenDevice()! */
    void SetBytesPerPixel(unsigned char bpp) { BytesPerPixel_ = (float) bpp; }

    inline int GetWidth() const { return Width_; }

    inline int GetHeight() const { return Height_; }

    inline int GetColorChannels() const { return ColorChannels_; }

    inline BIAS::ImageBase::EColorModel GetColorModel() const { return ColorMode_; }

    inline float GetBytesPerPixel() const { return BytesPerPixel_; }

    /** @attention Call this only after opening the device successfully. */
    virtual int InitImage(BIAS::ImageBase &Image);

    /** Use this method to learn something about the capabilities of the source
        (only useful for V4L sources, e.g. /dev/video0). Output is send to stdout.
     */
    virtual int GetCapabilities(VideoSourceCapabilities &caps);
    virtual int GetCapabilities(const char *device, VideoSourceCapabilities &caps);

    /// Use this to enable/disable any automatic modes addressed via enumerations
    virtual int AutoMode(int a, bool b);
    inline int GetID() const { return ID_; }

    inline bool IsActive() const { return Active_; }

    /// Specify if SetShutter(), SetGain() ... would work for this camera
    inline bool IsControllable() { return IsControllable_; }

    /// This function is used to control features like shutter, zoom, etc.
    virtual int SetFeature(int feature, unsigned int value);

    /// This function is used to query features like shutter, zoom, etc.
    virtual unsigned int GetFeature( int feature);

    // The following functions define more convenient camera parameter control

    virtual bool HasControlShutter() { return false; }
    /// Get shutter (exposure time) in seconds.
    virtual float GetShutter();
    /// Set shutter (exposure time) in seconds.
    virtual int SetShutter(float exptime);
    virtual void SetAutoShutter(bool b) { BIASERR("Please overload function!"); }
    virtual bool GetAutoShutter() { BIASERR("Please overload function!"); return false; }
    virtual void GetShutterRange(double &min, double &max) {
      min = minShutter_; max = maxShutter_;
    }
    virtual bool HasControlGain() { return false; }
    /// Get gain in dB.
    virtual float GetGain();
    /// Set gain in dB.
    virtual int SetGain(float g);
    virtual void SetAutoGain(bool b) { BIASERR("Please overload function!"); }
    virtual bool GetAutoGain() { BIASERR("Please overload function!"); return false; }
    virtual void GetGainRange(double &min, double &max) {
      min = minGain_; max = maxGain_;
    }
    virtual bool HasControlBrightness() { return false; }
    /// Get brightness as value in interval [0, 100]. */
    virtual float GetBrightness() { BIASERR("Please overload function!"); return 0.0f; }
    /// Set brightness as value in interval [0, 100]. */
    virtual int SetBrightness(float g) { BIASERR("Please overload function!"); return 0; }
    virtual void SetAutoBrightness(bool b) { BIASERR("Please overload function!"); }
    virtual bool GetAutoBrightness() { BIASERR("Please overload function!"); return false; }
    virtual void GetBrightnessRange(double &min,double &max) {
         min = minBrightness_; max = maxBrightness_;
    }
    virtual bool HasControlContrast() { return false; }
    /// Get contrast as value in interval [0, 100]. */
    virtual float GetContrast() { BIASERR("Please overload function!"); return 0.0f; }
    /// Set contrast as value in interval [0, 100]. */
    virtual int SetContrast(float g) { BIASERR("Please overload function!"); return 0; }
    virtual void SetAutoContrast(bool b) { BIASERR("Please overload function!"); }
    virtual bool GetAutoContrast() { BIASERR("Please overload function!"); return false; }
    virtual void GetContrastRange(double &min, double &max) {
      min = minContrast_; max = maxContrast_;
    }

    virtual bool HasControlWhiteBalance() { BIASERR("Please overload function!"); return false; }

    /// Reset digital zoom, pan, and tilt to defaults to ensure compliance with calibration.
    virtual void ResetPanTiltZoom() {}

    virtual int OnePushAuto(int feature);

    /// Set white balance as values in interval [0, 100]. */
    virtual int SetWhiteBalance(float rvalue, float bvalue);
    /// Get white balance as values in interval [0, 100]. */
    virtual int GetWhiteBalance(float &rvalue, float &bvalue);

    /// Set white balance to optimal value in software.
    virtual int SoftwareWhiteBalance();

    /** @brief Enables the very fast direct-to-disk mode.
        @attention Use this _after_ OpenDevice() because the image size must be known!
        @author evers
    */
    int SetDirectToDisk(const std::string &filename);

    virtual void EnsureLatestFrame(const bool b) {}

    std::string GetIdentifier() const { return Identifier_; }

    /** @brief Specify if grab should wait for new frames.
        If you want as many images as possible and don't care about equal ones,
        call this with waitForNew = false. By default, GrabSingle() blocks until
        a new frame arrives from the camera. Only used in V4L and DSHOW.
        @author grest
     */
    inline virtual void SetWaitForNew(bool waitForNew) { WaitForNew_ = waitForNew; }

  protected:

    int WriteDirect_(const unsigned char *data, const BIAS::UUID &uuid,
                     const long int &sec, const long int &usec);

    /// Image format
    int Width_;
    int Height_;
    int ColorChannels_;

    /// Capturing framerate
    float FramesPerSecond_;

    /// BytesPerPixel cannot be int (e.g.  it is 1.5 for YUV420p)
    float BytesPerPixel_;

    /// Device name
    const char *DefaultDevice_;

    /// Device channel
    int DeviceChannel_;

    /// Color mode used by camera
    BIAS::ImageBase::EColorModel ColorMode_;

    /// Complete_initialized_ is set when OpenDevice(), UseChannel() etc. are done
    bool CompleteInitialized_;

    /// Active flag is set in PreGrab() und unset in PostGrab()
    bool Active_;

    /// Grabbing flag is set and unset in GrabSingle() methods
    bool Grabbing_;

    /// External trigger flag
    bool bExternalTrigger_;

    /// Camera ID
    int ID_;

    /// Wait for new frames in GrabSingle()
    bool WaitForNew_;

    /// Write directly to disk
    bool DirectToDisk_;

    /// File descriptor for direct-to-disk mode
    int DtDFd_;

    /// 512 byte aligned buffer, contains VSImageHeader and image data
    char *DtDBuffer_;

    /// Buffer size must be multiple of 512
    unsigned int DtDBufferSize_;

    /// Image size, useful for allocating and copying memory
    unsigned int ImageSize_;

    /// Pointer to the beginning of DtDBuffer_
    BIAS::VideoStream::VSImageHeader *DtDImageHeader_;

    /// Pointer into DtDBuffer after VSImageHeader
    char *DtDStartOfImage_;

    /// Must be initialized be the derived classes
    bool IsControllable_;

    /// Feature ranges
    double minContrast_, maxContrast_;
    double minGain_, maxGain_;
    double minShutter_, maxShutter_;
    double minBrightness_, maxBrightness_;
    
    /// Verbose camera descriptor
    std::string Identifier_;

  };

}// namespace MIP
#include <Base/Common/BIASpragmaEnd.hh>
#endif