OCamera Class Reference

#include <OCamera.h>

List of all members.


Detailed Description

Basic class to access image acquisition functions.

Example Usage
  1. create interface with CreateCameraInterface()
  2. open it with Open() (now the file descriptor of the camera is VALID)
  3. work with the camera using any other operation i.e. use
  4. after work close interface with Close() (now the file descriptor of the camera is INVALID)
  5. if interface is no longer needed call Destroy()

Object Creation/Deletion

static OCameraCreateCameraInterface (eCameraType eCam)
 Create the image acquisition interface.
virtual int Destroy ()=0
 Removes completely the interface object created with CreateCameraInterface().

Public Types

enum  eAcqMode {
  ACQ_MODE_STOP = 1, ACQ_MODE_SINGLE_SHOT = 2, ACQ_MODE_FREE_RUN = 3, ACQ_MODE_SELECT_SHOT = 4,
  ACQ_MODE_FPGA_SINGLE_SHOT = 5, ACQ_MODE_FPGA_CONTINUOUS = 6, ACQ_MODE_FREE_RUN_SLAVE = 8, ACQ_MODE_SEQUENCE_MASTER = 9,
  ACQ_MODE_SEQUENCE_SLAVE = 10, ACQ_MODE_FREE_RUN_SLAVE_STOP = 11, ACQ_MODE_Q3D_SNAPSHOT = 12
}
 acquisition mode of the camera More...
enum  eAppletType { APPLET_IN16_OUT32_INT = 0, APPLET_IN8_OUT32_INT = 1, APPLET_IN16_OUT16 = 2, APPLET_IN8_OUT16 = 3 }
 FPGA-applet types. More...
enum  eBayer2XType {
  BAYER_OUTPUT_RAW = 0, BAYER_OUTPUT_H = 1, BAYER_OUTPUT_S = 2, BAYER_OUTPUT_V = 3,
  BAYER_OUTPUT_I = 4, BAYER_OUTPUT_R = 5, BAYER_OUTPUT_G = 6, BAYER_OUTPUT_B = 7
}
 RGB or HSV(I) color component selection (available only for color sensors). More...
enum  eBayerPattern { BAYER_PATTERN_GRGR = 1, BAYER_PATTERN_BGBG = 2, BAYER_PATTERN_RGRG = 3, BAYER_PATTERN_GBGB = 4 }
 FPGA bayer pattern selection (only used for color sensors). More...
enum  eCameraType {
  CAM_TYPE_MT9V403 = 3, CAM_TYPE_GENERIC = 4, CAM_TYPE_IBIS1300 = 5, CAM_TYPE_MT9V022 = 6,
  CAM_TYPE_MT9V023 = 7
}
 sensor type of the camera More...
enum  eCorrectionType { CORRECTION_REPLACE = 0, CORRECTION_MASK_AND = 1, CORRECTION_MASK_OR = 2, CORRECTION_RESERVED_1 = 3 }
 FPGA image correction types. More...
enum  eFilterType {
  FILTER_OFF = 0, FILTER_BINARIZE_ONLY = 1, FILTER_MEDIAN = 2, FILTER_MEAN = 3,
  FILTER_SNN = 4, FILTER_SOBEL = 5, FILTER_RESERVED_1 = 6, FILTER_RESERVED_2 = 7,
  FILTER_RESERVED_3 = 8
}
 Available 3x3 filters. More...
enum  eFrequency { FREQU_20MHz = 0, FREQU_40MHz = 1, FREQU_50MHz = 2, FREQU_60MHz = 3 }
 Pixel frequency values for the camera sensor. More...
enum  eIllMode { ILL_MODE_OFF = 1, ILL_MODE_NORMAL = 2, ILL_MODE_PULSED = 3 }
 mode of the internal circular high power LED illumination (available for cameras with internal LED light) More...
enum  eIllModeExt { ILL_MODE_EXT_OFF = 0, ILL_MODE_EXT_ON_POSITIVE = 1, ILL_MODE_EXT_ON_NEGATIVE = 2 }
 mode of an external illumination trigger More...
enum  eJPEGQuality { JPEG_QUALITY_LOW = 0, JPEG_QUALITY_MEDIUM = 1, JPEG_QUALITY_GOOD = 2, JPEG_QUALITY_EXCELLENT = 3 }
 JPEG Codec quantization level. More...
enum  eLaserOutputFormat {
  LASER_OUTPUT_16_4 = 0x04, LASER_OUTPUT_8_0 = 0x10, LASER_OUTPUT_8_1 = 0x11, LASER_OUTPUT_8_2 = 0x12,
  LASER_OUTPUT_8_3 = 0x13, LASER_OUTPUT_8_4 = 0x14
}
 Laser Profiling output format selection. More...
enum  ePointPriority { PRIO_FIRST_POINT = 0, PRIO_LAST_POINT = 1, PRIO_LARGEST_FIRST = 2, PRIO_LARGEST_LAST = 3 }
 Laser Profiling point selection priority. More...
enum  eProfileDirection { DIRECTION_TOP_DOWN = 0, DIRECTION_BOTTOM_UP = 1 }
 Laser Profiling evaluation direction. More...
enum  eSplitType { SPLIT_OFF = 0, SPLIT_RAW = 1, SPLIT_PROCESSED = 2 }
 FPGA data splitting types. More...
enum  eTrigPolarity { TRIG_POL_ACTIVE_HIGH = 1, TRIG_POL_ACTIVE_LOW = 2 }
 trigger polarity of the camera's trigger More...
enum  eTrigSource { TRIG_SRC_SOFTWARE = 1, TRIG_SRC_EXTERNAL_E0 = 2, TRIG_SRC_EXTERNAL_E1 = 3 }
 trigger source of the camera More...
typedef struct
OCamera::sBinarizationParam 
sBinarizationParamType
 Binarization parameter structure type.
typedef struct
OCamera::sCalibrateSensorParam 
sCalibrateSensorParamType
 Sensor calibration parameter structure;.
typedef struct
OCamera::sFilterParam 
sFilterParamType
 Filter parameter structure type.

Public Member Functions

Operations
virtual int CalibrateSensor (sCalibrateSensorParamType *pParam=0)=0
 Perform sensor calibration for IBIS1300.
virtual int Close ()=0
 Closes the camera interface AFTER all work has been done.
virtual int Diag ()=0
 Diagnose function.
virtual int DisableImageRAM (void)=0
 Disable the image RAM.
virtual int GetDriverFileDescriptor ()=0
 Retrieve file descriptor to perform select/poll on the camera interface driver.
virtual int GetImage (OCameraImage *pImage)=0
 Get the next image from this interface.
virtual int GetImage2Buffer (OCameraImage *pImage)=0
 Get an image to a buffer supplied by the user.
virtual int GetImageCount ()=0
 Get the number of images currently pending.
virtual int GetImageToImageRAM (unsigned long ulAddr)=0
 Take one sensor image and transfer it to the image SDRAM.
virtual int GetMaxImageCount ()=0
 Gets the maximum number of images (immediate sequenced GetImage() calls).
virtual int GetNImages (OCameraImage **pImages, int dMaxImages)=0
 Get the next N available images from this interface.
virtual int GetSensorRegister (const char *pName, unsigned long *pValue)=0
 Read sensor specific configuration register.
virtual char ** GetSensorRegisterNames ()=0
 Ask for the names of registers.
virtual int GetShutterTime (void)=0
 Get the actual value of shutter time in microseconds (1E-6).
virtual int ImageRAMToImageRAM (unsigned long ulSrcAddr, unsigned long ulSrcLen, unsigned long ulDestAddr, unsigned long ulDestLen)=0
 Transfers a block of memory in the image SDRAM to another position in the image SDRAM.
virtual int InitColor ()=0
 Switches the API/driver into color mode.
virtual int InitImageRAM (void)=0
 Initialize the image RAM.
virtual int Open (int dFrameBufferSize=4096 *256, int dMaxBuffers=-1)=0
 Opens the camera interface BEFORE ANY OTHER method is called.
virtual int PurgeImages ()=0
 Purges the driver's frame buffer removing any previously acquired images.
virtual int ReadImageRAM (void *pDest, unsigned long ulAddr, unsigned long ulLen)=0
 Transfer a block of memory from the image SDRAM to a buffer supplied by the user.
virtual int ReadImageRAMReducedData (void *pDest, unsigned long ulAddr, unsigned long ulLen, unsigned long *ulRetLen)=0
 This function is used to read a defined ammount of data (for example a raw-image) from the image SDRAM via a hardware applet or the hardware JPEG encoder.
virtual int ReleaseImage (OCameraImage *pImage)=0
 Releases the image and returns image memory space to the framebuffer.
virtual int ReleaseNImages (OCameraImage **pImages, int dImages)=0
 Complement to GetNImages.
virtual int ResetSequenceCounter ()=0
 Reset the sequence counter to zero.
virtual int SequenceAbort ()=0
 Abort acquisition of an image sequence and stop all image acquisition activities.
virtual int SequenceCleanup ()=0
 After the acquisition of an image sequence perform necessary cleanups (free memory).
virtual int SequenceGetResult (OCameraSequence &oSeq)=0
 Get the result code and information about the acquired images (linked list).
virtual int SequenceInit (OCameraSequenceStorage &oStore)=0
 Initialize a triggered image acquisition.
virtual int SequenceIsFinished ()=0
 Ask whether the current sequence acquisition has finished or not.
virtual int SequenceStart (long long dt, long long Z, bool bPrePost, bool bStartStop)=0
 Start the acquisition of an image sequence with pre or post trigger.
virtual int SequenceTrigger ()=0
 Tell the driver that the trigger event has happened.
virtual int SequenceWaitFinish ()=0
 Wait until the sequence is completely acquired e.g. acquisition time Z reached.
virtual int SetAcquisitionMode (eAcqMode eAcq)=0
 Set the mode of image acquisition.
virtual int SetBayer2X (eBayer2XType eBayer2xOutput, eBayerPattern ePattern)=0
 Used on color cameras to select one of the following color components: red, green, blue; hue, saturation, value, intensity.
virtual int SetBinarization (bool bEnable, sBinarizationParamType *pParam=0)=0
 Enable or disable the FPGA-Binarization.
virtual int SetCameraWindow (int dX0, int dY0, int dWidth, int dHeight)=0
 Set the position and size of the camera sensor window.
virtual int SetCircularOverwrite (bool bOverwrite)=0
 Set circular image overwrite mode for situations, where the camera runs free until a trigger event occurs.
virtual int SetFilter (eFilterType eFilter, sFilterParamType *pParam=0)=0
 Enable or disable one of the FPGA based filters (Median, Mean, SNN, Sobel) Before initiating an ImageRAM data-transfer over an filter make sure to use SetImageRAMPictureSize().
virtual int SetFrameRate (float fFps)=0
 Set the camera's frame rate (the unit is "frames per second", float version).
virtual int SetFrameRate (int dFps)=0
 Set the camera's frame rate (the unit is "frames per second").
virtual int SetFrequency (eFrequency eFrequ)=0
 Set camera clock frequency.
virtual int SetGain (int dFactor)=0
 Set the camera sensor gain as a decimal factor.
virtual int SetHardwareApplet (bool bEnable, unsigned long nMaxSize, eAppletType eApplet=APPLET_IN16_OUT32_INT)=0
 Enable or disable a customer specific FPGA design.
virtual int SetIlluminationMode (eIllMode eIll)=0
 Set the internal illumination mode of the camera (cameras with internal LED light).
virtual int SetIlluminationModeExternal (eIllModeExt eIll)=0
 Set the external illumination trigger mode of the camera.
virtual int SetIlluminationTiming (int dDelay, int dPeriod)=0
 Specify position and duration of the pulse which switches on the illumination light source.
virtual int SetImageRAMPictureSize (int dWidth, int dHeight)=0
 When reading image data out of the ImageRAM this function must be used to setup the width and heigth of the image before calling ReadImageRAM()/ImageRAMToImageRAM()/etc.
virtual int SetJPEG (bool bEnable, eJPEGQuality eQuality=JPEG_QUALITY_MEDIUM, bool bByteStuffEnable=false, eBayerPattern ePattern=BAYER_PATTERN_GRGR, bool bForceGreyscale=false)=0
 Enables or disables the JPEG coder, specify desired quanitsation (image quality) and allows enabling of the hardware bytestuffing used in the JFIF file format.
virtual int SetMedian (bool bEnable)=0
 INFO: This is an legacy function.
virtual int SetReadTimeout (int dTimeout)=0
 Set the timeout value to wait during a GetImage() operation.
virtual int SetSensorRegister (const char *pName, unsigned long nValue)=0
 Write sensor specific configuration register.
virtual int SetShutterTime (int dShutter)=0
 Setup the shutter time in microseconds (1E-6).
virtual int SetTriggerDelay (int dDelay)=0
 Delay the trigger pulse for a specified amount of microseconds (1E-6).
virtual int SetTriggerSource (eTrigSource eTrig, eTrigPolarity ePol=TRIG_POL_ACTIVE_HIGH)=0
 Specify the mode and source of the trigger.
virtual int SetTriggerWindow (int dX0, int dY0, int dWidth, int dHeight, int dThreshMin, int dThreshMax)=0
 Setup FPGA based image triggering.
virtual int SetupImageCorrection (bool bEnable, eCorrectionType eType, unsigned long ulStartAddr, unsigned long ulSize, unsigned long ulImages)=0
 This method is used to enable a FPGA preprocessing step where the sensors image data is combined with data previously stored in the FPGAs Image-SDRAM.
virtual int SetupImageSplitting (eSplitType eType, unsigned long ulDestAddr, unsigned long ulSize)=0
 This method allows to store the raw sensor image in the FPGA attached image SDRAM during a GetImage() operation.
virtual int SetupLaserProfiling (bool bEnable, int dX0, int dY0, int dWidth, int dHeight, ePointPriority ePrio, eProfileDirection eDir, int dThreshMin, int dThreshMax, int dAreaMin, int dAreaMax, eLaserOutputFormat dSubRes=LASER_OUTPUT_16_4, unsigned char *pRefData=0)=0
 Setup laser scan profiling.
virtual int SetWhiteBalance (eBayerPattern ePattern, unsigned char *pLut=0)=0
 Setting up the FPGAs-whitebalancing tables.
virtual int SwitchIllumination (bool bOn)=0
 Permanently switch on/off internal light (only for cameras with internal LED light).
virtual int TriggerImage ()=0
 Trigger an image trigger in ACQ_MODE_SINGLE_SHOT.
virtual int TriggerImageAbort ()=0
 Abort image acquisition previously started by TriggerImage().
virtual int WaitForNImages (int nImages)=0
 Wait until N images are available.
virtual int WriteImageRAM (void *pSrc, unsigned long ulAddr, unsigned long ulLen)=0
 Transfer a block of memory (out of a user buffer) to the image SDRAM.

Classes

struct  sBinarizationParam
 Binarization parameter structure type. More...
struct  sCalibrateSensorParam
 Sensor calibration parameter structure;. More...
struct  sFilterParam
 Filter parameter structure type. More...

Member Typedef Documentation

Binarization parameter structure type.

Sensor calibration parameter structure;.

Filter parameter structure type.


Member Enumeration Documentation

acquisition mode of the camera

Enumerator:
ACQ_MODE_STOP  stop camera activities
ACQ_MODE_SINGLE_SHOT  take single shots only
ACQ_MODE_FREE_RUN  camera is free running
ACQ_MODE_SELECT_SHOT  take single frames from free running camera
ACQ_MODE_FPGA_SINGLE_SHOT  FPGA based trigger timing, single shots, legacy mode, do not use anymore.
ACQ_MODE_FPGA_CONTINUOUS  FPGA based trigger timing, continuous run, legacy mode, do not use anymore.
ACQ_MODE_FREE_RUN_SLAVE  sensor slave mode, free running
ACQ_MODE_SEQUENCE_MASTER  triggered sequence acquisition in master mode
ACQ_MODE_SEQUENCE_SLAVE  triggered sequence acquisition in slave mode
ACQ_MODE_FREE_RUN_SLAVE_STOP  stop free running slave mode
ACQ_MODE_Q3D_SNAPSHOT  reserved mode, do not use

FPGA-applet types.

Enumerator:
APPLET_IN16_OUT32_INT  standard FPGA applet type. Always use this.
APPLET_IN8_OUT32_INT  reserved, do not use!
APPLET_IN16_OUT16  reserved, do not use!
APPLET_IN8_OUT16  reserved, do not use!

RGB or HSV(I) color component selection (available only for color sensors).

Enumerator:
BAYER_OUTPUT_RAW  raw bayer pattern
BAYER_OUTPUT_H  hue
BAYER_OUTPUT_S  satturation
BAYER_OUTPUT_V  value
BAYER_OUTPUT_I  intensity
BAYER_OUTPUT_R  red
BAYER_OUTPUT_G  green
BAYER_OUTPUT_B  blue

FPGA bayer pattern selection (only used for color sensors).

Enumerator:
BAYER_PATTERN_GRGR  bayer data start with green-red-green-red color pixels
BAYER_PATTERN_BGBG  bayer data start with blue-green-blue-green color pixels
BAYER_PATTERN_RGRG  bayer data start with red-green-red-green color pixels
BAYER_PATTERN_GBGB  bayer data start with green-blue-green-blue color pixels

sensor type of the camera

Enumerator:
CAM_TYPE_MT9V403  Micron MT9V403 CMOS sensor, for VGA cameras.
CAM_TYPE_GENERIC  Camera Link camera without serial config line.
CAM_TYPE_IBIS1300  FillFactory IBIS5-A/B-1300 1280x1024 pixel sensor.
CAM_TYPE_MT9V022  Micron MT9V022 CMOS sensor, for 16:9 VGA camera (752x480).
CAM_TYPE_MT9V023  Micron MT9V023 CMOS sensor, for 16:9 VGA camera (752x480).

FPGA image correction types.

Enumerator:
CORRECTION_REPLACE  replace sensor data with data stored in FPGA-Image-RAM
CORRECTION_MASK_AND  uses bitwise AND-mask
CORRECTION_MASK_OR  uses bitwise OR-mask
CORRECTION_RESERVED_1  reserved, do not use!

Available 3x3 filters.

Enumerator:
FILTER_OFF  no filter
FILTER_BINARIZE_ONLY  no filter, allows raw-data binarization
FILTER_MEDIAN  Median filter.
FILTER_MEAN  Mean filter.
FILTER_SNN  SNN filter.
FILTER_SOBEL  Sobel filter.
FILTER_RESERVED_1  reserved, do not use!
FILTER_RESERVED_2  reserved, do not use!
FILTER_RESERVED_3  reserved, do not use!

Pixel frequency values for the camera sensor.

Adjustment of the pixel clock is not supported on every image sensor. For CAM_TYPE_MT9V403 pixel clocks from 20 to 60MHz are supported. CAM_TYPE_IBIS1300 uses a fixed frequency of 40MHz. CAM_TYPE_MT9V022 and CAM_TYPE_MT9V023 use a fixed frequency of 26,6MHz.

Enumerator:
FREQU_20MHz  20MHz pixel clock
FREQU_40MHz  40MHz pixel clock
FREQU_50MHz  50MHz pixel clock
FREQU_60MHz  60MHz pixel clock

mode of the internal circular high power LED illumination (available for cameras with internal LED light)

Enumerator:
ILL_MODE_OFF  turn the internal camera illumination off
ILL_MODE_NORMAL  operate LED illumination with nominal current (continuous operation possible)
ILL_MODE_PULSED  pulsed LED operation mode (higher brightness but limited to 1:10 duty cycle)

mode of an external illumination trigger

Enumerator:
ILL_MODE_EXT_OFF  turn off external light trigger
ILL_MODE_EXT_ON_POSITIVE  turn on external light trigger (active high)
ILL_MODE_EXT_ON_NEGATIVE  turn on external light trigger (active low)

JPEG Codec quantization level.

Enumerator:
JPEG_QUALITY_LOW  low quality, best compression rate
JPEG_QUALITY_MEDIUM  medium quality, very good compression rate
JPEG_QUALITY_GOOD  good quality (standard JPEG quality), good compression rate
JPEG_QUALITY_EXCELLENT  highest quality but moderate compression rate

Laser Profiling output format selection.

Enumerator:
LASER_OUTPUT_16_4  selects 16 bit output format including 4 bit subpixel resolution
LASER_OUTPUT_8_0  reserved, do not use!
LASER_OUTPUT_8_1  reserved, do not use!
LASER_OUTPUT_8_2  reserved, do not use!
LASER_OUTPUT_8_3  reserved, do not use!
LASER_OUTPUT_8_4  reserved, do not use!

Laser Profiling point selection priority.

Enumerator:
PRIO_FIRST_POINT  select the first matching point
PRIO_LAST_POINT  select the last matching point
PRIO_LARGEST_FIRST  select the point with the highest intensity (if several points have the same maximum intensity select the one the occurs first in the image)
PRIO_LARGEST_LAST  select the point with the highest intensity (if several points have the same maximum intensity select the one that occurs last in the image)

Laser Profiling evaluation direction.

Enumerator:
DIRECTION_TOP_DOWN  output offsets with respect to the top line (top line is zero point)
DIRECTION_BOTTOM_UP  output offsets with respect to the bottom line (bottom line is zero point)

FPGA data splitting types.

Enumerator:
SPLIT_OFF  no data splitting enabled
SPLIT_RAW  the raw-sensor image is stored in FPGA-Image-RAM and transferd to the CPU
SPLIT_PROCESSED  reserved, do not use!

trigger polarity of the camera's trigger

Enumerator:
TRIG_POL_ACTIVE_HIGH  trigger signal is active high, used for TRIG_SRC_EXTERNAL_xx
TRIG_POL_ACTIVE_LOW  trigger signal is active low, used for TRIG_SRC_EXTERNAL_xx

trigger source of the camera

Enumerator:
TRIG_SRC_SOFTWARE  a call to GetImage triggers acquisition of an image
TRIG_SRC_EXTERNAL_E0  trigger by external digital hardware input signal I0
TRIG_SRC_EXTERNAL_E1  trigger by external digital hardware input signal I1


Member Function Documentation

virtual int OCamera::CalibrateSensor ( sCalibrateSensorParamType pParam = 0  )  [pure virtual]

Perform sensor calibration for IBIS1300.

Adjusts the DAC_RAW and DAC_FINE to obtain equal behaviour of even and odd colums and overall zero black level. Resulting values are stored in Param1 and Param2 of the pParam structure as long as it is not zero.

Parameters:
*pParam pointer to the parameter structure
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::Close (  )  [pure virtual]

Closes the camera interface AFTER all work has been done.

This closes the image acquisition interface and frees memory allocated at driver level and inside the API. Any connections to device drivers are closed. After calling this function an external file descriptor received with GetDriverFileDescriptor() is no longer valid. Keep this in mind and avoid usage of this file descriptor for select() calls after calling this method.

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

static OCamera* OCamera::CreateCameraInterface ( eCameraType  eCam  )  [static]

Create the image acquisition interface.

Call this method to obtain a pointer to the image acquisition interface through which all image acquisition functionality can be accessed. The interface is created specifically for a certain image sensor type. The abstract interface remains the same for each sensor but the implementation behind is different.

Parameters:
eCam specifies the type of sensor mounted in your camera
ATTENTION: If you use the wrong sensortype CAM_TYPE_MT9V023 and have a CAM_TYPE_MT9V022 inside your camera the interface will be created anyway. The wrong sensortype can only be detected after opening the camera interface with the function Open receiving an error -ENODEV.
If you are unsure which sensor (MT9V022 or MT9V023) is inside your camera follow these steps:
  • create the interface with CreateCameraInterface(OCamera::CAM_TYPE_MT9V023)
  • open the interface with Open
  • if returnvalue of Open equals -ENODEV
    • destroy the wrong interface with Destroy
    • create the interface with CreateCameraInterface(OCamera::CAM_TYPE_MT9V022)
    • open the interface again with Open

virtual int OCamera::Destroy (  )  [pure virtual]

Removes completely the interface object created with CreateCameraInterface().

This should happen after Close() was called and the interface is no longer needed.
Be careful to DO NOT USE THE INTERFACE POINTER any longer after having called this method!!

virtual int OCamera::Diag (  )  [pure virtual]

Diagnose function.

virtual int OCamera::DisableImageRAM ( void   )  [pure virtual]

Disable the image RAM.

When this function is called the image SDRAM will loose all stored data!

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::GetDriverFileDescriptor (  )  [pure virtual]

Retrieve file descriptor to perform select/poll on the camera interface driver.

ATTENTION: You cannot use FD_SET (part of the select function usage) with a negative file descriptor.

Returns:
file descriptor on the camera interface
< 0 if camera interface is not open (s.a. Open())

virtual int OCamera::GetImage ( OCameraImage pImage  )  [pure virtual]

Get the next image from this interface.

Images are acquired from the image sensor at device driver level. Any image that is fully acquired by the driver is put into a list of pending images. Calling this method immediately returns the next image from the pending list if one is available. If the pending list is empty the method blocks and waits until the next image is available. To prevent from program hangs, a maximum amount of time to wait (timeout) can be set by a call to SetReadTimeout().

Images returned by this method are kept on an extra read list which prevents images on that list to be used for subsequent acquisitions, i.e. an image returned by this method is left untouched until it is passed back to the driver by a call to ReleaseImage().

Parameters:
pImage pointer to an OCameraImage object
Returns:
0 ... on success
-62 ... timeout occurred
-errno ... on failure always negative (see errno.h)

virtual int OCamera::GetImage2Buffer ( OCameraImage pImage  )  [pure virtual]

Get an image to a buffer supplied by the user.

The image data is directly written to the buffer from the DMA controller. This function can be used in snapshot modes ONLY

Parameters:
pImage pointer to an OCameraImage object
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::GetImageCount (  )  [pure virtual]

Get the number of images currently pending.

The return value equals the number of images currently residing in the list of pending images, i.e. images that are successfully acquired but not read by the user through calls to GetImage().
In other words this method returns the number of consecutive calls to GetImage() without a blocking wait.

Returns:
number of images currently pending

virtual int OCamera::GetImageToImageRAM ( unsigned long  ulAddr  )  [pure virtual]

Take one sensor image and transfer it to the image SDRAM.

Works only with raw images. The hardware JPEG encoder must not be enabled when using this function. The used start address must be an even byte address

Parameters:
ulAddr start address in image SDRAM for write operation
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::GetMaxImageCount (  )  [pure virtual]

Gets the maximum number of images (immediate sequenced GetImage() calls).

The return value equals the number of images that can be buffered in the driver. This number approximately equals the totally allocated buffer space given by Open() divided by the size of an image. But this is an estimation due to the memory allocation granularity in the kernel and block size effects when managing image buffers (images must completely fit in an allocated block).

Returns:
maximum number of images, that can be buffered in the driver

virtual int OCamera::GetNImages ( OCameraImage **  pImages,
int  dMaxImages 
) [pure virtual]

Get the next N available images from this interface.

In comparison to GetImage() this function returns up to N images from the drivers buffer at once. Therefore an array of OCameraImage pointers and its number is used. This call is always non-blocking. A positive return value corresponds to the number of returned images and can be between 0 and dMaxImages. ReleaseNImages can be used to free the images memory

Parameters:
pImages array of pointers to images
dMaxImages maximum number of images to be returned
Returns:
number of returned images
-errno ... on failure always negative (see errno.h)

virtual int OCamera::GetSensorRegister ( const char *  pName,
unsigned long *  pValue 
) [pure virtual]

Read sensor specific configuration register.

This method enables the user to access configuration registers of the imaging sensor for fine tuning purposes. Normally it is not necessary to use this function for acquiring images. But some image sensors offer special features the user may want to use. Note that some sensors do not offer a possibility to read back its registers.

Parameters:
pName is a string specifying the name of the image sensor register
pValue is a pointer to an unsigned 32bit value where the contents of the specified register is written to.
Returns:
0 ... on success
-EPERM ... no read access to registers on this sensor possible
-EINVAL ... invalid register name
-errno ... on failure always negative (see errno.h)

virtual char** OCamera::GetSensorRegisterNames (  )  [pure virtual]

Ask for the names of registers.

This method can be used to ask for individual names of sensor registers supported for reading and writing.

Returns:
A pointer to an array of strings (char * pointers) with a zero entry marking the end of the array.

virtual int OCamera::GetShutterTime ( void   )  [pure virtual]

Get the actual value of shutter time in microseconds (1E-6).

Depending on the type of image sensor shutter time can be configured in a certain granularity (most often in multiples of row times). Hence, not all values specified in SetShutterTime() can be actually configured on the sensor. This method returns the actually configured value of shutter time in microseconds.

Returns:
the currently set shutter time in microseconds

virtual int OCamera::ImageRAMToImageRAM ( unsigned long  ulSrcAddr,
unsigned long  ulSrcLen,
unsigned long  ulDestAddr,
unsigned long  ulDestLen 
) [pure virtual]

Transfers a block of memory in the image SDRAM to another position in the image SDRAM.

During the transfer FPGA-filters, binarization, and color component selection can be enabled. This function can be used in snapshot modes ONLY Source size and destination size should be set to the same value (except for hardware applet usage). Enabling JPEG compression with this function is not allowed!

Parameters:
ulSrcAddr source address in image SDRAM
ulSrcLen source size
ulDestAddr destination address in image SDRAM
ulDestLen destination size
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::InitColor (  )  [pure virtual]

Switches the API/driver into color mode.

This setting has to be made corresponding to the installed FPGA design - so if you have a color camera (using a color FPGA-Design), call this function when your application starts up. By default the camera driver starts up in greyscale mode - only a color camera has to be switched explicitly into the correct operation mode before its special FPGA features can be used. ATTENTION: Operating a color camera in greyscale mode (and vice versa) can and will lead to unexpected results!

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::InitImageRAM ( void   )  [pure virtual]

Initialize the image RAM.

If your application wants to use the image SDRAM, call this function first. Executon of any image SDRAM related functions before InitImageRAM() will lead to unexpected results.

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::Open ( int  dFrameBufferSize = 4096 *256,
int  dMaxBuffers = -1 
) [pure virtual]

Opens the camera interface BEFORE ANY OTHER method is called.

After creation of the image acquisition interface through CreateCameraInterface() the interface must be opened, i.e. underlying driver functions get called to put the image sensor out of reset into an operable state.
A call to Open() prepares internal data structures and allocates memory to hold image data. It is an important to know that image memory is managed at device driver level, i.e. in the linux kernel space. This is necessary for free running acquisition modes where images are acquired in the background by the driver without interaction with the user process. When it is time, the user process fetches the next pending image from the driver and maps corresponding image memory to user space (no copy of data necessary). The amount of memory allocated at driver level is specified as an argument to this method.
After opening the interface by this call any other operations from this interface may be called.

Parameters:
dFrameBufferSize size of the driver level image memory buffer in bytes
ATTENTION: A minimum size of 2*(used resolution) is needed if dMaxBuffers equals -1
dMaxBuffers specifies the maximum number of image buffers (i.e. images) to be allocated in the driver. For dMaxBuffers == -1 the number of buffers is adjusted automatically to dFrameBufferSize for every call to SetCameraWindow(), i.e. smaller windows result in a larger number of image buffers and larger windows result in smaller number of image buffers. Specifying dMaxBuffers != -1 can limit the number of image buffers allocated in the driver to the given maximum expecially in cases where the image size is very small. In such cases overhead allocations in the driver may result in significant memory consumption otherwise.
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)
-ENODEV ... maybe the wrong eCameraType has been used to create the interface (s.a. function CreateCameraInterface) => destroy the wrong interface and create a new one with the correct eCameraType before calling Open again

virtual int OCamera::PurgeImages (  )  [pure virtual]

Purges the driver's frame buffer removing any previously acquired images.

Whenever an image acquisition is stopped and later re-enabled the user may use this function to purge the driver's frame buffer to remove any previously acquired image up to the point of time when calling this function.

Note, that any image that was read by GetImage() and that ist NOT returned by ReleaseImage() will NOT be freed, i.e. the user may still borrow some images from the driver's frame buffer without getting them overwritten.

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::ReadImageRAM ( void *  pDest,
unsigned long  ulAddr,
unsigned long  ulLen 
) [pure virtual]

Transfer a block of memory from the image SDRAM to a buffer supplied by the user.

This SDRAM is only accessible via the FPGA. Transfers are made by DMA. This function can be used in snapshot modes ONLY A total number of ulLen bytes is transferred from the given image SDRAM address ulAddr. pDest must point to a 32-byte aligned buffer having a length of at least ulLen bytes. The amount of transferred data (ulLen) must always be a multiple of 32 Bytes and ulAddr must be an even byte-address.

Parameters:
pDest destination (user-space) memory buffer, which will be written to
length of buffer has to be >= ulLen
ulAddr start address in image SDRAM
ulLen number of bytes to read from image SDRAM
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::ReadImageRAMReducedData ( void *  pDest,
unsigned long  ulAddr,
unsigned long  ulLen,
unsigned long *  ulRetLen 
) [pure virtual]

This function is used to read a defined ammount of data (for example a raw-image) from the image SDRAM via a hardware applet or the hardware JPEG encoder.

The applet/JPEG coder outputs an reduced ammount of data that is transferred to the CPU's memory. Transfers are made by DMA. The end of a transfer is signaled to the PXA with a special interrupt and the total number of transfered bytes is returned. This function can be used in snapshot modes ONLY pDest must point to a 32-bit alligned buffer having a length of at least ulLen bytes. The ammount of requested data (ulLen) must always be a multiple of 32 Bytes and start at an even address (ulAddr).

Parameters:
pDest destination (user-space) memory buffer, which will be written to
length of buffer has to be >= ulLen
ulAddr start address of RAW image in image SDRAM
ulLen number of bytes to read from image SDRAM
*ulRetLen ammount of transferred data in bytes
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::ReleaseImage ( OCameraImage pImage  )  [pure virtual]

Releases the image and returns image memory space to the framebuffer.

As image memory is managed by the device driver, images returned by GetImage() are under exclusive access by the user until ReleaseImage() is called on these images. This allocate/free mechanism prevents images from being overwritten while currently processed.

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::ReleaseNImages ( OCameraImage **  pImages,
int  dImages 
) [pure virtual]

Complement to GetNImages.

The N(dmaxImages) Images in an array of OCameraImage pointers are released at once.

Parameters:
pImages array of pointers to images
dImages number of released images
Returns:
0 on succuess -errno ... on failure always negative (see errno.h)

virtual int OCamera::ResetSequenceCounter (  )  [pure virtual]

Reset the sequence counter to zero.

Every image carries a sequence number attached by hardware which is incremented by one each time an image is acquired.

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SequenceAbort (  )  [pure virtual]

Abort acquisition of an image sequence and stop all image acquisition activities.

virtual int OCamera::SequenceCleanup (  )  [pure virtual]

After the acquisition of an image sequence perform necessary cleanups (free memory).

virtual int OCamera::SequenceGetResult ( OCameraSequence oSeq  )  [pure virtual]

Get the result code and information about the acquired images (linked list).

All information is filled into the provided OCameraSequence structure.

Parameters:
oSeq image information storage place
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SequenceInit ( OCameraSequenceStorage oStore  )  [pure virtual]

Initialize a triggered image acquisition.

Tell the driver about allocated memory where the images should be written to (this is called the ring buffer).

Parameters:
oStore ring buffer, storage place for images
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SequenceIsFinished (  )  [pure virtual]

Ask whether the current sequence acquisition has finished or not.

This call does not block.

Returns:
  • positive values
    • RES_NOT_INITIALIZED
    • RES_NOT_STARTED
    • RES_FINISHED
    • RES_RUNNING
  • negative values are errno.h error codes

virtual int OCamera::SequenceStart ( long long  dt,
long long  Z,
bool  bPrePost,
bool  bStartStop 
) [pure virtual]

Start the acquisition of an image sequence with pre or post trigger.

Depending on the mode start or stop at trigger

Parameters:
dt trigger time in milliseconds (1E-3)
Z sequence length in milliseconds (1E-3)
bPrePost 
  • TRUE ... pre trigger enabled
  • FALSE ... post trigger enabled
bStartStop 
  • TRUE ... start at trigger
  • FALSE ... stop at trigger
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SequenceTrigger (  )  [pure virtual]

Tell the driver that the trigger event has happened.

virtual int OCamera::SequenceWaitFinish (  )  [pure virtual]

Wait until the sequence is completely acquired e.g. acquisition time Z reached.

virtual int OCamera::SetAcquisitionMode ( eAcqMode  eAcq  )  [pure virtual]

Set the mode of image acquisition.

This is an essential method and must be called PRIOR to getting any image from the camera. Normally this is the last method called during initialisation of the image acquisition interface before fetching the very first image.

This camera API supports a large set of several different acquisition modes with a completely different behaviour of the individual modes:

ACQ_MODE_STOP enters a stop state where no image acquisition takes place. It makes sense to enter this mode to unload the acquisition engine from unnecessarily performed work. This unloads the system memory bus (no DMA) and saves power.

In ACQ_MODE_SINGLE_SHOT each image must be triggered explicitely either per software through the call to GetImage() or an external hardware trigger input signal. Only one image is acquired for one single trigger. This mode is typically used for image processing applications where external devices (like PLCs) signal when an image from a manufactured part should be taken and evaluated. Another typical situation is a cyclically running applications that take images, process them and acquire the next images in an infinite loop at the maximum possible speed.

ACQ_MODE_FREE_RUN operates the image sensor in a continuously running mode where one image is taken immediately after the other. The resulting frame rate depends on the size of the image (transfer time from sensor array to memory) and the exposure time. Image acquisition immediately starts after calling SetAcquisitionMode() with this mode as the argument. Images are buffered by the driver and the application must keep track of the resulting frame rate. If processing time in the application is too long the image buffer may overflow after a while resulting in images to be lost.

ACQ_MODE_SELECT_SHOT is similar to ACQ_MODE_FREE_RUN and operates the image sensor in the same mode. The important difference is that the image data stream from the sensor is normally blocked resulting in all images to be lost except when GetImage() is called. In other words GetImage() simply fetches the next available image in the stream of images from the continuously running sensor. In this mode the image buffer memory can not overrun and the time it takes for GetImage() to return is less in average than for ACQ_MODE_SINGLE_SHOT where it takes at least the exposure time plus the read out time for GetImage() to return.

The most professional mode of operation is ACQ_MODE_FREE_RUN_SLAVE. In this mode the cameras FPGA completely takes control of what is going on during image acquisition (the sensor is in slave mode). ACQ_MODE_FREE_RUN_SLAVE continuously acquires images with a certain adjustable exact frame rate. It is the only mode for the MT9V403 sensor where image data read out takes place concurrently with sensor exposure resulting in a maximum speed in terms of frames per second. ACQ_MODE_FREE_RUN_SLAVE is typically used for applications where a fixed frame rate is necessary (e.g. scanning applications) and adjustment of exposure time doesn't influence the frame rate. This would be different in ACQ_MODE_FREE_RUN.

ACQ_MODE_FREE_RUN_SLAVE_STOP is a mode to temporarily stop the fixed frame rate acquisition of the ACQ_MODE_FREE_RUN_SLAVE mode, e.g. to enter a calculation phase before the next sequence of images is taken again. ACQ_MODE_FREE_RUN_SLAVE_STOP enters a stop state with almost no delay in comparison to ACQ_MODE_STOP which needs at least 50ms to take place.
ATTENTION if you have a large number of (small) images => call of function Close() may take same time (up to 700msec!!)

Parameters:
eAcq desired acquisition mode of the camera
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetBayer2X ( eBayer2XType  eBayer2xOutput,
eBayerPattern  ePattern 
) [pure virtual]

Used on color cameras to select one of the following color components: red, green, blue; hue, saturation, value, intensity.

For details please refer to the online documentation chapter "FPGA Design and FPGA-ImageRAM". Note: if you want to use a FPGA-Filter on color cameras, you also have to use this function and select a color component.

Parameters:
eBayer2xOutput selects color component emmited by Bayer2X unit
ePattern sets Bayer-Pattern start value
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetBinarization ( bool  bEnable,
sBinarizationParamType pParam = 0 
) [pure virtual]

Enable or disable the FPGA-Binarization.

The actual FPGA design supports exactly two threshold values, which must be set in the parameter structure (THRESH_LO,THRESH_HIGH). The result of the binarization is the following for each pixel: 255 when (THRESH_LOW <= x <= THRESH_HIGH) else 0 By using the bInvert parameter the output (255/0) is inverted to (0/255) Note: The binarization is executed within the FPGA's filter block. Therefore, if you want to binarize a RAW image (on color camaras a Bayer2X processed image), call SetFilter() with its FILTER_BINARIZE_ONLY parameter before. Note2: When you transfer data over a filter from the Image-RAM, make sure to set the correct image size with SetImageRAMPictureSize() before.

Parameters:
bEnable turns on/off binarization
pParam pointer to binarization paramter structure (invert, thresholds)

virtual int OCamera::SetCameraWindow ( int  dX0,
int  dY0,
int  dWidth,
int  dHeight 
) [pure virtual]

Set the position and size of the camera sensor window.

Have a look at the camera data sheet first to specify valid coordinates for this function.
Because of the way how DMA transfers from the sensor are made it is required that dWidth*dHeight is a multiple of 32bytes!

Parameters:
dX0 x-value of left upper corner
dY0 y-value of left upper corner
dWidth width in x direction
dHeight height in y direction
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetCircularOverwrite ( bool  bOverwrite  )  [pure virtual]

Set circular image overwrite mode for situations, where the camera runs free until a trigger event occurs.

Parameters:
bOverwrite 
  • TRUE ... enable circular overwrite
  • FALSE ... disable circular overwrite
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetFilter ( eFilterType  eFilter,
sFilterParamType pParam = 0 
) [pure virtual]

Enable or disable one of the FPGA based filters (Median, Mean, SNN, Sobel) Before initiating an ImageRAM data-transfer over an filter make sure to use SetImageRAMPictureSize().

There is also a set of configurable filter parameters available. For exact definitions of these parameters please refer to the online documentation (chapter. "FPGA Design and FPGA-ImageRAM"). These parameters are by default initialized with meaningfull values. Note: Due to limited onchip FPGA memory ressources median filter and laser line profiling cannot coexist on a -R2 (IBIS1300) camera. Default FPGA designs support laser line profiling. Please contact your distributor or camera vendor to obtain a median filter enabled FPGA design for the IBIS1300 camera.

Parameters:
eFilter the filter to be switched on. Use FILTER_OFF for disabling
pParam pointer to structure containing filter parameters.
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetFrameRate ( float  fFps  )  [pure virtual]

Set the camera's frame rate (the unit is "frames per second", float version).

This function may only be called in situations where the frame rate can be adjusted independently from the shutter time else this function has no effect.
SetCameraWindow() and SetShutterTime() must be called PRIOR to this method to properly adjust camera timing!!

Parameters:
fFps floating point frame rate in "frames per second"
DO NOT use frame rates below 1.0fps
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetFrameRate ( int  dFps  )  [pure virtual]

Set the camera's frame rate (the unit is "frames per second").

This function may only be called in situations where the frame rate can be adjusted independently from the shutter time else this function has no effect.
SetCameraWindow() and SetShutterTime() must be called PRIOR to this method to properly adjust camera timing!!

Parameters:
dFps frame rate in "frames per second"
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetFrequency ( eFrequency  eFrequ  )  [pure virtual]

Set camera clock frequency.

Adjust the system clock frequency of the image sensor. This must be done immediately after calling Open() to allow for a short settling time before making any settings like SetShutterTime() or SetCameraWindow().
Keep in mind that changing the clock frequency is not supported by all image sensor variants:
MT9v403: 20MHz, 40MHz, 50MHz, 60MHz
IBIS1300: fixed at 40MHz
MT9v022: fixed at 26,6MHz
MT9v023: fixed at 26,6MHz

Parameters:
eFrequ camera clock frequency
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetGain ( int  dFactor  )  [pure virtual]

Set the camera sensor gain as a decimal factor.

Make sure to specify valid gain values here.

Parameters:
dFactor gain value for the camera sensor
MT9V403 range from 1 to 18
IBIS1300 range from 1 to 16
MT9V022 range from 1 to 25
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetHardwareApplet ( bool  bEnable,
unsigned long  nMaxSize,
eAppletType  eApplet = APPLET_IN16_OUT32_INT 
) [pure virtual]

Enable or disable a customer specific FPGA design.

This method must be called if you work with Silicon Software Visual Applets or design your own FPGA preprocessing solution for this camera. Customized preprocessing designs (also called hardware applets) offer an additional path for image data to pass through the FPGA (i.e. image data can flow through your preprocessing or not). You can use this method to select between the preprocessing path or the direct pass through without any preprocessing.

Parameters:
bEnable 
  • TRUE ... enable hardware applet preprocessing
  • FALSE ... disable hardware applet preprocessing and directly read in raw image data
nMaxSize specifies the maximum amount of data (worst case) that can be delivered by the hardware applet.
Normally this is the size of an image in all cases where the hardware applet doesn't remove or add any data to an image. If compression is done the resulting size of an image may be significantly lower, whereas a bayer-to-rgb transform triples the amount of data. In any way keep in mind that nMaxSize specifies nothing else than the size of a DMA buffer to allocate. The resulting actual size of an image after preprocessing is always returned in the nSize field of the OCameraImage struct. Specifying nMaxSize too low results in data being cut off from an image. Specifying nMaxSize too large wastes memory. So you really should set nMaxSize with some care.
eApplet type of FPGA-Applet. By default use APPLET_IN16_OUT32_INT
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetIlluminationMode ( eIllMode  eIll  )  [pure virtual]

Set the internal illumination mode of the camera (cameras with internal LED light).

Parameters:
eIll mode of the internal circular high power LED illumination
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetIlluminationModeExternal ( eIllModeExt  eIll  )  [pure virtual]

Set the external illumination trigger mode of the camera.

Parameters:
eIll mode of the external illumination
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetIlluminationTiming ( int  dDelay,
int  dPeriod 
) [pure virtual]

Specify position and duration of the pulse which switches on the illumination light source.

Parameters:
dDelay is the delay of the illumination pulse with resp. to trigger in microseconds (1E-6)
dPeriod is the duration of the illumination pulse in microseconds (1E-6)
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetImageRAMPictureSize ( int  dWidth,
int  dHeight 
) [pure virtual]

When reading image data out of the ImageRAM this function must be used to setup the width and heigth of the image before calling ReadImageRAM()/ImageRAMToImageRAM()/etc.

This is necessary because the FPGA does not know about the size of an image stored into the ImageRAM. The value-pair 0/0 for dWidth/dHeight should be used for general data transfers containing no images. dWidth and dHight must always be multiples of two.

Parameters:
dWidth number of columns of the image in ImageRAM
dHeight number of rows of the image in ImageRAM
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetJPEG ( bool  bEnable,
eJPEGQuality  eQuality = JPEG_QUALITY_MEDIUM,
bool  bByteStuffEnable = false,
eBayerPattern  ePattern = BAYER_PATTERN_GRGR,
bool  bForceGreyscale = false 
) [pure virtual]

Enables or disables the JPEG coder, specify desired quanitsation (image quality) and allows enabling of the hardware bytestuffing used in the JFIF file format.

On color cameras this call furthermore allows to set the Bayer-Pattern starting value and enforcement of greyscale compression (this parameters are ignored on greyscale cameras).

Parameters:
bEnable 
  • TRUE ... enable circular overwrite
  • FALSE ... disable circular overwrite
eQuality image quality of JPEG compression
bByteStuffEnable 
  • TRUE ... enables hardware byte-stuffing
  • FALSE ... disable hardware byte-stuffing
ePattern sets the start bayer pattern for color hardware JPEG encoding, only effective for color sensor
bForceGreyscale allows to encode greyscale images on color hardware JPEG encoder
  • TRUE ... encode as greyscale image
  • FALSE ... encode as color image
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetMedian ( bool  bEnable  )  [pure virtual]

INFO: This is an legacy function.

Please use SetFilter() instead! Enable or disable the FPGA based 3x3 Median filter. Median filtering is done in FPGA without any speed loss and without additional latency during image acquisition, i.e. the median filter immediately outputs its first line of image data when the first line of input data arrives on its input. The only drawback of the applied full streaming algorithm is that median filtered images appear to be one image line shifted down.
Note: Due to limited onchip FPGA memory ressources median filter and laser line profiling cannot coexist on a -R2 (IBIS1300) camera. Default FPGA designs support laser line profiling. Please contact your distributor or camera vendor to obtain a median filter enabled FPGA design for the IBIS1300 camera. Note2: Before initiating an ImageRAM data-transfer over the median-filter make sure to use SetImageRAMPictureSize().

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetReadTimeout ( int  dTimeout  )  [pure virtual]

Set the timeout value to wait during a GetImage() operation.

This may prevent from hanging if no image could be acquired (possible cause: no camera cable or no trigger signal etc.) Without calling this function a default value of 2s is used as timeout period. If you whish to wait for infinite time pass a value of -1 to this function.

Parameters:
dTimeout timeout value in microseconds (1E-6s)
use a value of -1 to wait for infinite time
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetSensorRegister ( const char *  pName,
unsigned long  nValue 
) [pure virtual]

Write sensor specific configuration register.

This method enables the user to access configuration registers of the imaging sensor for fine tuning purposes. Normally it is not necessary to use this function. But some image sensors offer special features the user may want to use. Be especially careful when changing sensor registers to different values because this may lead to trouble with image acquisition.

Parameters:
pName is a string specifying the name of the image sensor register
nValue specifies the value that should be written to the given register
Returns:
0 ... on success
-EINVAL ... invalid register name
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetShutterTime ( int  dShutter  )  [pure virtual]

Setup the shutter time in microseconds (1E-6).

Depending on the acquisition mode the effective shutter time may be different from the given value (e.g. if the camera has predefined discrete exposure times in free run mode)

Parameters:
dShutter range from 0 to xxx.xxx microseconds
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetTriggerDelay ( int  dDelay  )  [pure virtual]

Delay the trigger pulse for a specified amount of microseconds (1E-6).

The delay is inserted between trigger event and actual trigger impulse to the camera.

Parameters:
dDelay delay of the trigger pulse in microseconds (1E-6)
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetTriggerSource ( eTrigSource  eTrig,
eTrigPolarity  ePol = TRIG_POL_ACTIVE_HIGH 
) [pure virtual]

Specify the mode and source of the trigger.

A trigger to acquire an image can be generated by software, FPGA and external hardware input signals

Parameters:
eTrig source of the trigger
ePol polarity of the trigger
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetTriggerWindow ( int  dX0,
int  dY0,
int  dWidth,
int  dHeight,
int  dThreshMin,
int  dThreshMax 
) [pure virtual]

Setup FPGA based image triggering.

The FPGA based trigger unit counts the number of pixels having a grey level between a minimum and maximum threshold inside a rectangular window of the the image. The coordinates of the window and the values for the thresholds can be adjusted by this function call. The counted number of pixels is reported for each acquired image in the associated OCameraImage structure (see nTrigCount). Reading this pixel counter value the user can easily decide whether he wants to discard or further process the image. A typical example is that someone wants to wait until an object becomes visible in a certain area of the image. Note, that the specified trigger window is always relative to the camera window, i.e. a call to SetCameraWindow() also affects the position of the trigger window.

Parameters:
dX0 x-value (relative to position of the camera window, see SetCameraWindow()) of upper left corner of trigger window
dY0 y-value (relative to position of te camera window, see SetCameraWindow()) of upper left corner of trigger window
dWidth width of trigger window in x direction
dHeight height of trigger window in y direction
dThreshMin minimum grey level for a pixel to be counted
dThreshMax maximum grey level for a pixel to be counted

virtual int OCamera::SetupImageCorrection ( bool  bEnable,
eCorrectionType  eType,
unsigned long  ulStartAddr,
unsigned long  ulSize,
unsigned long  ulImages 
) [pure virtual]

This method is used to enable a FPGA preprocessing step where the sensors image data is combined with data previously stored in the FPGAs Image-SDRAM.

For each pixel a 8-Bit value is read from the image SDRAM and combined with the pixel in the way defined by the eType parameter. This method for example can be used to replace the sensors image with a testimage stored in the image SDRAM. It is possible to store more than one image in linear way in the image-SDRAM. If ulImages is set greater then one, the next correction image is used automatically by subsequent calls to GetImage(). ATTENTION: While this funtionality is enabled, the image SDRAM is exclusively used and can not be accessed by other methods like ReadImageRAM(), WriteImageRAM(), etc.

Parameters:
bEnable enable/disable image correction
eType defines type of image correction
ulStartAddr defines start address of correction-data in image SDRAM
ulSize number of bytes used as correction data; in general the size of the current image
ulImages number of correction images to use ( always >= 1)
Returns:
0 ... on success

virtual int OCamera::SetupImageSplitting ( eSplitType  eType,
unsigned long  ulDestAddr,
unsigned long  ulSize 
) [pure virtual]

This method allows to store the raw sensor image in the FPGA attached image SDRAM during a GetImage() operation.

The length of the stored image corresponds to the current set image size. The eType parameter would allow other settings than storing the RAW image, but this are reserved for future use. So only use SPLIT_RAW/SPLIT_OFF for this. ATTENTION: While this funtionality is enabled, the image SDRAM is exclusively used and can not be accessed by other methods like ReadImageRAM(), WriteImageRAM(), etc.

Parameters:
bType defines data splitting mode
ulDestAddr start address in the image SDRAM
ulSize ammount of data stored in image SDRAM (in general the size of the selected sensor window)
Returns:
0 ... on success

virtual int OCamera::SetupLaserProfiling ( bool  bEnable,
int  dX0,
int  dY0,
int  dWidth,
int  dHeight,
ePointPriority  ePrio,
eProfileDirection  eDir,
int  dThreshMin,
int  dThreshMax,
int  dAreaMin,
int  dAreaMax,
eLaserOutputFormat  dSubRes = LASER_OUTPUT_16_4,
unsigned char *  pRefData = 0 
) [pure virtual]

Setup laser scan profiling.

This method prepares the camera do start with laser profiling, i.e. images are preprocessed by the FPGA to find a bright (or dark) line in the image. The position of the line (offset from top/bottom) is output instead of the image.

One 16 bit output offset has a 12bit integer part and a 4 bit fractional part to allow for sub pixel accuracy. The profile can be taken only horizontally, i.e. for an image of 640x480 pixel you get 640 offset values. You can specify any position and size of the image taken from the sensor that produces output data sizes in a multiple of 32 bytes. (i.e. you can specify the window in multiples of 16 pixel columns as each column produces a 16bit output value).

Output data is fetched from the FPGA via the normal call to GetImage() with the 'column wise 16bit offsets as the resulting image'.
We recommend to use acquisition mode FREE_RUN_SLAVE to produce profiles at fixed frame rates. But any other acquisition mode is possible. Keep in mind that reducing the number of lines in an image increases the highest possible frame rate but reducing the number of columns does not (but of course the amount of data will be reduced).
Every profile you acquire via the GetImage() call has a resulting size from 2*N+32 bytes. This includes the 16-bit values for N columns and an additional 32 byte data block. This block is reserved for future use and should be ignored.
Output offsets can be calculated with respect to the top or bottom line depending on your needs in the application. A value of zero is returned if no laser line was found at the corresponding position. If a laser line was found at the top(eDir==DIRECTION_TOP_DOWN)/bottom(eDir==DIRECTION_BOTTOM_UP) row of an image, an output offset of 1 is returned.
Acquiring normal images after laser profiling requires to call SetupLaserProfiling with the bEnable parameter set to false and a subsequent SetCameraWindow() call to re-establish the camera window for normal image acquisition.

Note: for the eLaserOutputFormat parameter only LASER_OUTPUT_16_4 can be used, and the pRefData parameter is ignored!

Parameters:
bEnable enables or disables the laser line profiling unit
dX0 x-value of the upper left corner of the acquired images
dY0 y-value of the upper left corner of the acquired images
dWidth width of image in x direction (columns), must be a multiple of 16!
dHeight height of image in y direction (lines), depends on desired frame rate
ePrio specifies which point to return when processing one image column
eDir specifies offsets to be calculated with respect to the top or bottom line
dThreshMin minimum grey level for a pixel to be treated as laser spot pixel
dThreshMax maximum grey level for a pixel to be treated as laser spot pixel
dAreaMin minimum grey level sum of consecutive laser spot pixels for a laser spot, must fit into 14bit, i.e. dAreaMin < 16384
dAreaMax maximum grey level sum of consecutive laser spot pixels for a laser spot, must fit into 14bit, i.e. dAreaMax < 16384
dSubRes Laser Profiling output format (always use LASER_OUTPUT_16_4 here!)
pRefData laser reference line (not supported - use 0!)
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::SetWhiteBalance ( eBayerPattern  ePattern,
unsigned char *  pLut = 0 
) [pure virtual]

Setting up the FPGAs-whitebalancing tables.

Only useable with color cameras. The FPGA-whitebalancing is based on three lookup-tables for red, green and blue. Each of these tables contains 256 bytes. All three tables are alligned in one single memory block (768 bytes) in GBR order. White balancing is always turned on, but by default the lookup tables are initialized linear and therefore there is no effect. This means for turning off FPGA-whitebalancing you have to write linear tables to the FPGA. The lookup-table is also reseted when the function is called without the pLut parameter.

Parameters:
ePattern defines how the sensors Bayer-Pattern starts at the used camera window.
pLut pointer to 768 byte array containing the three lookup tables
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h) -ENOMEM... if unable to reset lookup tables

virtual int OCamera::SwitchIllumination ( bool  bOn  )  [pure virtual]

Permanently switch on/off internal light (only for cameras with internal LED light).

Parameters:
bOn 
  • TRUE ... switch on internal light
  • FALSE ... switch off internal light
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::TriggerImage (  )  [pure virtual]

Trigger an image trigger in ACQ_MODE_SINGLE_SHOT.

This enables the user to perform image acquisition and processing in parallel. This does NOT wait until the image is ready. The acquisition is only started (i.e. the sensor is triggered). To get the image itself, someone has several options:

  1. call GetImage() immediately afterwards or some time later which immediately returns the image if it is already available or may wait until the image is available
  2. call GetImageCount() to ask for the number of images available
  3. call select() on the file descriptor returned by GetDriverFileDescriptor() until the file descriptor gets readable
    Returns:
    0 ... on success
    -errno ... on failure always negative (see errno.h)

virtual int OCamera::TriggerImageAbort (  )  [pure virtual]

Abort image acquisition previously started by TriggerImage().

This method allows to abort an ongoing image acquisition that has been previously started by TriggerImage(). This functionality may be very useful if hardware triggered acquisition is used to prevent from undesired waits.

Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

virtual int OCamera::WaitForNImages ( int  nImages  )  [pure virtual]

Wait until N images are available.

This call sleeps until the given number of images are acquired and available via calls to GetImage(). The maximum time this function waits can be specified by a call to SetReadTimeout().

Parameters:
nImages number of images to wait for
Returns:
0 ... on success
-ETIME ... timeout waiting for images
-EAGAIN ... the call was interrupted by a signal

virtual int OCamera::WriteImageRAM ( void *  pSrc,
unsigned long  ulAddr,
unsigned long  ulLen 
) [pure virtual]

Transfer a block of memory (out of a user buffer) to the image SDRAM.

This SDRAM is only accessible via the FPGA. Transfers are made by DMA. This function can be used in snapshot modes ONLY A total number of ulLen bytes is transferred to the given image SDRAM address ulAddr. pSrc must point to a 32-byte alligned buffer having a length of at least ulLen bytes. The ammount of transfered (ulLen) data must always be a multiple of 32 Bytes and ulAddr must be an even byte-address.

Parameters:
pSrc source (user-space) memory buffer, which will be read from
length of buffer has to be >= ulLen
ulAddr start address in image SDRAM for write operation
ulLen number of bytes to write to image SDRAM
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)


The documentation for this class was generated from the following file:

Generated on Mon Mar 15 16:11:05 2010 for Festo Camera API by  doxygen 1.5.6