+ View the NASA Portal

Search JPL

Search CLARAty

- Algorithms- Infrastructure - Doxygen (public)- Doxygen (private)- Tutorials

- Repository- Nightly Build- Nightly Regression- Feature/Bug Tracking- Build Targets- Procedure- Conventions- Tools

camera.h

Go to the documentation of this file.

// -*-c++-*-
//---------------------------< /-/ CLARAty /-/ >------------------------------
/**
 * @file  camera.h
 *
 * Defines the base logical camera class.
 *
 * <br>@b Designer(s):  Daniel Clouse, Clay Kunz, Issa Nesnas
 * <br>@b Author(s):    Daniel Clouse
 * <br>@b Date:         June 9, 2006
 *
 * <b>Software License:</b><br>
 * <code>  http://claraty.jpl.nasa.gov/license/open_src/  or
 *         file: license/open_src.txt  </code>
 *
 * &copy; 2006, Jet Propulsion Laboratory, California Institute of Technology<br>
 * &copy; 2007, NASA Ames Research Center
 *
 * $Revision: 1.11 $
 */
//-----------------------------------------------------------------------------

#ifndef CAMERA_H
#define CAMERA_H

#include "claraty/share.h"         // Time
#include "claraty/device.h"
#include "claraty/image.h"

#include "claraty/exception.h"

namespace claraty {

//-----------------------------------------------------------------------------
/**
 * @defgroup hardware_pkg Hardware Package
 *
 * The CLARAty Hardware Package contains modules that relate directly
 * to the hardware.
 *
 */
//@{
//@}

//-----------------------------------------------------------------------------
/**
 * @defgroup device Device
 * @ingroup hardware_pkg
 *
 * Image acquisition/Camera related classes.
 *
 * Both physical camera and logical cameras are derived from the Device
 * base class.  A physical camera represents the state of the actual hardware.
 * Implementations are responsible for enforcing that no more than one
 * physical camera variable be constructed for each hardware camera.
 *
 * Camera is derived from Device, and is the base class for all logical
 * cameras.  A logical camera represents the user's view of the camera state.
 * A change of state in one logical camera does not affect the state of
 * another logical camera, even if they both refer to the same piece of
 * hardware.  A logical camera implementation is required to maintain a local
 * cache of logical camera state.  The acquire member function performs an
 * atomic operation which both sets the physical camera state to match that
 * of the logical camera, and acquires a single image.
 *
 * A logical camera should not be shared between tasks.  A physical camera
 * may be safely shared between tasks if each task constructs its own
 * logical camera and all access to the physical camera is via these
 * logical cameras.
 *
 * An algorithm may be written without knowledge of the type of Camera
 * being used:
 *
 * <code>
 * void my_algorithm(Camera & my_camera) {
 *   Camera_Image<uint8_t> my_image;
 *   my_camera.set_exposure(0.25);
 *   my_camera.acquire(my_image);
 *   ...
 * }
 * </code>
 *
 * We can then pass a specific implemenation to the algorithm:
 * 
 * <code>
 * XYZ_HW_Camera hw_camera(0x0233432, 0x343);
 * XYZ_Camera my_logical_camera(hw_camera);
 * my_algorithm(my_logical_camera);
 * </code>
 *
 */
//@{
//@}

/**
 * @ingroup device
 * Camera class.
 */
//@{
//@}


class Camera_Model;
class Feature_Map;
template <typename Pixel> class Camera_Image;

class Camera : public Device {
  friend class Camera_Group;

public:
  static const double DONT_CARE = -DOUBLE_EPSILON;
  
  // Specifies the camera's image format.
  enum IMAGE_FORMAT { MONO8,                  // Image<uint8_t>
                      YUV411,                 // Image<uint8_t>
                      YUV422,                 // Image<uint8_t>
                      YUV444,                 // Image<uint8_t>
                      RGB8,                   // Image<uint8_t>
                      MONO16,                 // Image<uint16_t>
                      RGB16 };                // Image<uint16_t>

public:
  
  // @name Constructor
  // @{
  
  Camera(const std::string & device_name = "def_cam",
         Camera_Model* camera_model_ptr = NULL);  
  // @}
  
  // @name Destructor
  // @{
  
  virtual ~Camera()
  { }
  // @}
  
  // @name Observers / Mutators
  // @{
  
  void set_camera_model_ptr(Camera_Model * cm) {_camera_model_ptr = cm;}
  
  const Camera_Model * get_camera_model_ptr() const
  {
    return _camera_model_ptr;
  }
  
  // gain_proportion  is in range 0.0 .. 1.0
  // DONT_CARE means set to a default value and allow the value to be
  // changed by other tasks.
  virtual bool         set_contrast(double gain_proportion = DONT_CARE) { return false; }
  virtual double       get_contrast() const { return 1.0; }
  
  // offset_proportion  is in range 0.0 .. 1.0
  virtual bool         set_brightness(double offset = DONT_CARE)   { return false; }
  virtual double       get_brightness() const                      { return 1.0;   }
  virtual bool         set_exposure  (double seconds = DONT_CARE)  { return false; }
  virtual double       get_exposure  () const                      { return 1.0;   }
  
  // Setting width_pixels or height_pixels to -1 means no change.
  virtual bool         set_format(IMAGE_FORMAT format,
                                  int width_pixels = -1,
                                  int height_pixels = -1)          { return false; }
  virtual IMAGE_FORMAT get_format() const                          { return MONO8; }
  
  // Get_width and get_height return the number of pixels in the image as set
  // by set_format.  Note that for many image formats, the number of pixels
  // is not the same as the number of elements in the image to be returned
  // from acquire.  For example, an RGB format image has 3 times as many
  // elements as pixels.
  // Get_subframe_width and get_subframe_height return the number of pixels
  // in the image returned from acquire.  If subframing is in effect
  // (see set_subframe), the number of pixels in the image will be less than
  // those set by set_format.
  virtual int          get_width()  const = 0;
  virtual int          get_height() const = 0;
  
  virtual bool         set_subframe(int width_offset,
                                    int height_offset,
                                    int width,
                                    int height)     { return false; }
  virtual int          get_subframe_width_offset()  const { return 0; }
  virtual int          get_subframe_height_offset() const { return 0; }
  
  // Always return the size of the image to be returned from acquire.
  // Note this implementation assumes subframes are not supported.
  virtual int          get_subframe_width() const { return get_width(); };
  virtual int          get_subframe_height() const { return get_height(); };
  
  // @}
  
  
  // @name Acquisition
  // @{ 

  /**
   * @brief Acquire an Image (unsigned char version).
   *
   * A derived class must implement acquire with the following behavior:
   * 1. Verify that the the current image format (as set by set_format) is not one of
   *    the 8 bit formats (MONO8, YUV411, YUV422, YUV444, RGB8), otherwise throw
   *    invalid_argument.
   * 2. Set the physical camera parameter settings to match those of this
   *    logical camera parameters.
   * 3. Resize the image to match the current camera format if necessary.
   * 4. Acquire an image from the physical camera.
   * 5. If *timestamp_ptr not NULL, fill with the time the image was acquired.
   * 6. If *feature_map_prt not NULL, fill with the camera parameter setting in
   *    effect at the time the image was acquired.
   *
   * During this process any other error encountered causes an exception
   * derived from Camera_Exception to be thrown.
   *    
   * @param[out] image
   *             Returns newly acquired Image.  The Image is resized to
   *             match the image size returned by the camera.
   * @param[out] timestamp_ptr
   *             If not NULL, returns time of image acquisition.
   * @param[out] feature_map_ptr
   *             If not NULL, returns camera feature settings in effect
   *             at image acquisition time.
   */
  virtual void acquire(Image<uint8_t> & image,
                       Time           * timestamp_ptr   = NULL,
                       Feature_Map    * feature_map_ptr = NULL) 
    throw (std::exception) = 0;
  
  /**
   * @brief Acquire an Image (unsigned short version).
   *
   * Behavior is the same as that of the unsigned char version except
   * that this version works with MONO16 and RGB16 formats only.
   */
  virtual void acquire(Image<uint16_t> & image,
                       Time            * timestamp_ptr   = NULL,
                       Feature_Map     * feature_map_ptr = NULL) 
    throw (std::exception) = 0;
  
  
  template <class Pixel_Type>
  void acquire(Camera_Image<Pixel_Type> & image) throw (std::exception);
  
  // @}
  
  virtual bool io(FDM_Map map);

protected:
  void _verify_pixel_format(size_t pixel_size);

  template <class Pixel_Type>
  void _verify_resize_image (Image<Pixel_Type> & image);

protected:
  Camera_Model * _camera_model_ptr;
};

std::ostream & operator << (std::ostream & os, const Camera & rhs);

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------
/** 
 * @brief Acquire a Camera_Image (template version).
 *
 * Acquire a Camera_Image using the current feature settings from this
 * logical camera.  This routine may fail for a number of reasons.  In
 * particular, it fails if the Pixel_Type of the image parameter does
 * not match that expected by the camera, as controlled by the
 * set_format member function.  On failure, an exception is thrown.
 *
 * @param[out]  image
 *              Returns newly acquired Camera_Image.  The image is
 *              resized to match the image size returned by the camera.
 *              The timestamp, and feature_map portions of the
 *              Camera_Image are updated by this routine.  The
 *              camera_model portion of the Camera_Image returns the
 *              Camera_Model as set by the Camera constructor or
 *              set_camera_model_ptr().
 */
template <class Pixel_Type>
void 
Camera::acquire(Camera_Image<Pixel_Type> &image) throw (std::exception)
{
  // Camera must be a friend of Camera_Image; requires change in Camera_Image  
  acquire(image, &image._timestamp, &image._feature_map);
  image._frame_num = 0;
}

//-----------------------------------------------------------------------------
/**
 * Verify that the image size matches the camera frame size.  If the image
 * size does not match the camera frame size, this function will resize
 * the image to the proper camera frame size.
 *
 * @param[in] image  reference to an image object to be resized
 */
template<class Pixel_Type>
void Camera::
_verify_resize_image(Image<Pixel_Type> & image)
{
  if ((image.get_width () != get_width()) && 
      (image.get_height() != get_height())) 
    image.resize(get_height(), get_width());
}

//-----------------------------------------------------------------------------

/**
 * @}
 * @}
 */

} // namespace claraty
  
#endif  // CAMERA_H

Last modified: June 05 2007 10:19:53

JPL PRIVACY STATEMENT GLOSSARY SITEMAP FEEDBACK CONTACT US

Site Manager: Issa A.D. Nesnas
Site Maintainer: Kelly Breed
Document Clearance #: CL 07-0635