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
}
 acquisition mode of the camera More...
enum  eCameraType { CAM_TYPE_MT9V403 = 3, CAM_TYPE_GENERIC = 4, CAM_TYPE_IBIS1300 = 5, CAM_TYPE_MT9V022 = 6 }
 sensor type of the camera 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  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  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...

Public Member Functions

Operations
virtual int CalibrateSensor ()=0
 Perform sensor specific calibration (in general the black level on the 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 image and transfer it to the image RAM.
virtual int GetMaxImageCount ()=0
 Gets the maximum number of images (immediate sequenced GetImage() calls).
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 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.
virtual int ReleaseImage (OCameraImage *pImage)=0
 Releases the image and returns imagespace to the framebuffer.
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 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 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)=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 SetJPEG (bool bEnable, eJPEGQuality eQuality=JPEG_QUALITY_MEDIUM)=0
 Enable or disable the JPEG codec and specify desired quanitsation (image quality).
virtual int SetMedian (bool bEnable)=0
 Enable or disable the Median filter.
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 SetupLaserProfiling (bool bEnable, int dX0, int dY0, int dWidth, int dHeight, ePointPriority ePrio, eProfileDirection eDir, int dThreshMin, int dThreshMax, int dAreaMin, int dAreaMax)=0
 Setup laser scan profiling.
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 WriteImageRAM (void *pSrc, unsigned long ulAddr, unsigned long ulLen)=0
 Transfer a block of memory to the image SDRAM.


Member Enumeration Documentation

enum OCamera::eAcqMode

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

enum OCamera::eCameraType

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).

enum OCamera::eFrequency

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.

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

enum OCamera::eIllMode

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)

enum OCamera::eIllModeExt

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)

enum OCamera::eJPEGQuality

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

enum OCamera::ePointPriority

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)

enum OCamera::eProfileDirection

Laser Profiling evaluation direction.

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

enum OCamera::eTrigPolarity

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

enum OCamera::eTrigSource

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 (  )  [pure virtual]

Perform sensor specific calibration (in general the black level on the IBIS1300).

Note: not all sensors offer the possibility to calibrate something

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 langer 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

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.

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 acqusitions, 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 image and transfer it to the image RAM.

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::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::InitImageRAM ( void   )  [pure virtual]

Initialize the image RAM.

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
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)

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

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

Whenever an image qcquisition ist 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.

This SDRAM is only accessible via the FPGA. Transfers are made by DMA. A total number of ulLen bytes is transferred from the given image SDRAM address ulAddr. pDest must point to a buffer having a length of at least ulLen bytes.

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::ReleaseImage ( OCameraImage pImage  )  [pure virtual]

Releases the image and returns imagespace 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::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 lenght in milliseconds (1E-3)
bPrePost 
  • TRUE ... pretrigger enabled
  • FALSE ... posttrigger 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 mehod 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 unnecessaryly 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. Onother 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 overrrun 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.

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

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 datasheet 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::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.

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 
) [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 passthrough 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.
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::SetJPEG ( bool  bEnable,
eJPEGQuality  eQuality = JPEG_QUALITY_MEDIUM 
) [pure virtual]

Enable or disable the JPEG codec and specify desired quanitsation (image quality).

Parameters:
bEnable 
  • TRUE ... enable circular overwrite
  • FALSE ... disable circular overwrite
eQuality image quality of JPEG compression
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

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

Enable or disable the Median filter.

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.)

Parameters:
dTimeout timeout value in microseconds (1E-6)
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 sould 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 predifined 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 wether 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 te 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::SetupLaserProfiling ( bool  bEnable,
int  dX0,
int  dY0,
int  dWidth,
int  dHeight,
ePointPriority  ePrio,
eProfileDirection  eDir,
int  dThreshMin,
int  dThreshMax,
int  dAreaMin,
int  dAreaMax 
) [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 subpixel accuracy. The profile can be taken only horizontally, i.e. for an image of 640x480 pixel you get 640 offest 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 '16bit offest as the resulting image'.
We recommend to use acquisition mode FREE_RUN_SLAVE to produce profiles at fixed framerates. But any other acquisition mode is possible. Keep in mind that reducing the number of lines in an image increases the highest possible framerate but reducing the number of columns does not (but of course the amount of data will be reduced).

Output offsets can be calculated with respect to the top or bottom line depending on your needs in the application.

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.

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 offests to be calculated with respect to the top or bottm line
dThreshMin minimum grey level for a pixel to be treates as laser spot pixel
dThreshMax maximum grey level for a pixel to be treates as laser spot pixel
dAreaMin minimum grey level sum of consecutive laser spot pixels for a laser spot
dAreaMax maximum grey level sum of consecutive laser spot pixels for a laser spot
Returns:
0 ... on success
-errno ... on failure always negative (see errno.h)

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::WriteImageRAM ( void *  pSrc,
unsigned long  ulAddr,
unsigned long  ulLen 
) [pure virtual]

Transfer a block of memory to the image SDRAM.

This SDRAM is only accessible via the FPGA. Transfers are made by DMA. A total number of ulLen bytes is transferred from/to the given image SDRAM address ulAddr. pSrc must point to a buffer having a length of at least ulLen bytes.

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 Fri Oct 12 10:31:11 2007 for Festo SBOx-C API by  doxygen 1.5.1-4