DEVA DEVA028 User manual

V1.1
DEVA028 USB3MegaPixel ColourCamera
User’sManual

V1.1
52 WoodsideBusiness Park
Birkenhead
WirralCH41 1EL
UnitedKingdom
Tel[phone]
Fax[phone]
Email: [e-mail]
Web: www.deva.co.uk
All information ofatechnicalnatureand particularsofthe productand itsusearegiven by
DevaElectronicControlsLtd.ingood faith.However,itisacknowledged thattheremaybe
errorsand omissionsinthismanual.Weshall notbe liableforloss ordamage whatsoever
arising fromthe useof anyinformation orparticularsin, oranyomissionsfrom, thisdocument.

DEVA028 USBUser’sManualOverview
i
1Overview........................................................................1
1.1 Product Features.....................................................................1
1.2 Typical applications................................................................2
1.3 Supportsoftware.....................................................................2
1.3.1 WindowsXP32/Vista32.............................................................................2
1.3.2 Utilities........................................................................................................2
1.4 Accessories.............................................................................3
2Installation and configuration......................................4
2.1 SoftwaresupportCDROM......................................................4
2.2 System requirements..............................................................4
2.2.1 Cameraconnection...................................................................................4
2.3 Device driverinstallation........................................................4
3SoftwareDevelopmentKit............................................5
3.1 Common definitions................................................................5
3.1.1 Data types...................................................................................................5
3.2 Programming definitions........................................................6
3.2.1 CAM_CLIENT_TYPES...............................................................................7
3.2.2 CAM_OPERATION_MODES.....................................................................7
3.2.3 CAM_CAPTURE_TYPES...........................................................................7
3.2.4 CAM_FORMAT_TYPES.............................................................................8
3.2.5 CAM_SYNC_TYPES..................................................................................8
3.2.6 CAPTURE_CONTROL_TYPES.................................................................9
3.2.7 CAPTURE_COORDINATE_TYPES...........................................................9
3.2.8 CAPTURE_CALLBACK_TYPES...............................................................9
3.2.9 CAPTURE_AUTO_ADJUST_MODES.....................................................10
3.2.10CAPTURE_IMAGE_ADUSTMENT_TYPES.............................................10
3.2.11CAPTURE_AUTO_EXPOSURE_MODES...............................................11
3.2.12CAPTURE_OVERLAY_TYPES................................................................12
3.2.13CAPTURE_CURSOR_TYPES.................................................................12

OverviewDEVA028 USBUser’sManual
ii
3.3 Data structures......................................................................13
3.3.1 CAM_IDENTIFICATION...........................................................................13
3.3.2 CAPTURE_COLOUR_ADJUSTMENT....................................................13
3.3.3 CAPTURE_IMAGE_ADJUSTMENT........................................................14
3.3.4 CAM_WINDOW........................................................................................14
3.3.5 DEST_WINDOW.......................................................................................15
3.3.6 CAPTURE_REQUIREMENT_PARAMS..................................................16
3.3.7 CAPTURE_AUTO_EXPOSURE_PARAMS.............................................17
3.3.8 CAPTURE_AUTO_ADJUST_PARAMS..................................................18
3.3.9 CAPTURE_HISTOGRAM.........................................................................18
3.3.10CAPTURE_FRAME_INFO.......................................................................19
3.3.11CAPTURE_SYNC_PARAMETERS.........................................................20
3.3.12CAPTURE_RENDER_CONFIG...............................................................20
3.3.13CAMERA_SETTINGS..............................................................................20
3.4 Initialisation and camerasetup functions...........................21
3.4.1 open_cam................................................................................................21
3.4.2 close_cam................................................................................................21
3.4.3 reset_cam................................................................................................21
3.4.4 num_cameras..........................................................................................22
3.4.5 enumerate_cameras...............................................................................22
3.4.6 get_camera_id.........................................................................................23
3.4.7 get_camera_description.........................................................................23
3.4.8 set_camera_description.........................................................................24
3.4.9 get_camera_settings..............................................................................24
3.4.10set_camera_settings...............................................................................25
3.5 Capturestream allocation and control functions...............25
3.5.1 alloc_capture...........................................................................................25
3.5.2 free_capture.............................................................................................26
3.5.3 reset_capture...........................................................................................26
3.5.4 chain_capture..........................................................................................27
3.5.5 capture_control.......................................................................................27
3.5.6 hook_capture_callback...........................................................................28
3.6 Capturestream setup and imagedata functions................29

DEVA028 USBUser’sManualOverview
iii
3.6.1 setup_capture..........................................................................................29
3.6.2 capture_occurred....................................................................................30
3.6.3 copy_capture_buffer...............................................................................31
3.6.4 flush_capture_buffer...............................................................................31
3.6.5 get_capture_params...............................................................................32
3.6.6 get_frame_info.........................................................................................32
3.7 Capturerendering functions................................................33
3.7.1 setup_timer_capture...............................................................................33
3.7.2 set_capture_render_config....................................................................34
3.7.3 get_capture_render_config....................................................................35
3.7.4 start_capture_render...............................................................................35
3.7.5 stop_capture_render...............................................................................36
3.7.6 capture_overlay.......................................................................................37
3.7.7 capture_cursor........................................................................................38
3.8 Automaticadjustmentfunctions..........................................39
3.8.1 setup_auto_adjust...................................................................................39
3.8.2 get_auto_adjust_params........................................................................39
3.9 Hardwarefunctions...............................................................40
3.9.1 setup_sync...............................................................................................40

1Overview
The DEVA028 colourcameramoduleisdesigned toenableawide range ofimage
captureapplicationstobe realised.Based on a3MpixelCMOSsensorwithbayer
mosaicforcolourreproduction the Deva028 makesuseofhigh speed USB 2.0to
transferimage datatoaPChost system.
Multiplestill and livecapturestreamsaresupported and maybe configured insize,
position and resolution tomatchthe application requirements.
The modulecan be mounted tothe customerslensassemblyorwithinthe optional
enclosurethat isavailablewithaC-Mount.
The cameramaybe integrated withDeva’smotion controlproductstoprovide
advanced auto-focusand measurement features.
1.1Product Features
•High speed USB 2.0interface
•2048 x1536 3Mpixelcolourimage
•Cropping, panning, skipping and binning modes
•6framespersecond at maxresolution
•Flexiblecapturemodes
•Touchtriggerprobe input
•Camerasyncbus
•Comprehensiveautoexposuremodes
•Colourcompensation
•Compact enclosurewithC-Mount
•Extensivesoftwaresupport
•Support and demonstration software
•Seamless integration withDevamotion controlproducts
•Advanced Auto-focusand position measurement

1.2Typical applications
The DEVA028 colourcameramoduleissuitableforawide range ofapplications
including:
•Non-contact measuring machines
•Automaticinspection machines
•Machine vision applications
•Process / QualityControl
•Microscopes/ Telescopes
•Securityand RemoteSensing
1.3Supportsoftware
Avarietyofsoftwaredrivers,librariesand utilitiesareprovided withthe DEVA028
colourcameramodule.Thesedriversbothenablethe cameratooperatewithexisting
softwaredeveloped by3rd partiesand facilitatesoftwaredevelopmentforintegration
withnewapplications.
Softwaresupportisan ongoing activity,ifsupportforaparticularapplication or
operating systemisnotcurrentlyprovided, pleasecall the Devaofficetodetermine its
availability.
1.3.1WindowsXP32/Vista32
WindowsDriverModel(WDM)driverssupportthe DEVA028 colourcameramodule
whilstthe Devacapturelibraryfunctionsareexported byaWin32 dynamiclinklibrary
(DLL).Bothoftheseitemsareinstalled automaticallyfromthe Devasoftwaresupport
CDROMwhen the cameraisfirst installed.
Forsoftwaredevelopers,the Devacapturelibraryfunctionsaredescribed laterinthis
manual.Exampleprogramswritten using common modernvisualprogramming tools
areprovided on the DevasoftwaresupportCDROMtoillustratethe useofthe Deva
capturelibraryfunctions.
Foroperation with3rd partysoftwareapplications,pleaserefertothe documentation
supplied bythe softwareprovider.
1.3.2Utilities
Demonstration image captureutilitysoftwareisprovided whichmaybe used to
quicklyverifythatthe DEVA028 colourcameramoduleisinstalled correctlyand

operationalwithoutrequiring the useof3
rd partyapplicationsorsoftware
development.
1.4Accessories
When supplied aspartofadevelopmentkit, the DEVA028 colourcameramoduleis
mounted inacompactenclosurewithC-mountlensfitting and included witha1mAto
mini-BUSB cable.
Pleasecontact Devawithyourrequirements.

2Installation and configuration
2.1SoftwaresupportCDROM
The DEVA28 issupplied withasoftwaresupportCDROMthatalsoincludessupport
and information formanyofDeva’sotherproducts.The CDROMincludesthe
following items:
WindowsXP32/Vista32 devicedriversprovide acoherentcamerahardware
management layer.
WindowsXP32/Vista32 DLLsand importlibrariescontainthe Devacapturelibrary
functions.
'C'language libraryroutinesand headerfileswhichprovide constant, structureand
function definitionsforaccess tothe Devacapturelibrary.
AVisualBasicmoduleprovidesconstant, structureand function definitionsforaccess
tothe Devacapturelibrary.
Exampleprogramsillustrating useof the Devacapturelibraryfunctions.
Demonstration image captureutilitysoftware.
2.2System requirements
The camerarequiresan IBMPCcompatible(Pentium4oraboverecommended)
running XP32 orVista32 withone spareUSB 2.0connection.
2.2.1Cameraconnection
AnAtomini-Bcableconnectsthe cameratothe PCUSB 2.0port.
2.3Device driverinstallation
Plug ‘n’PlaysoftwaresupportforWindowsXP32 and Vista32 enablessimple
installation.
Installation isatwo-stage procedure.Afterthe cameraisconnected forthe firsttime
windowswill indicatethatanewUSB devicehasbeen found and will startthe
standarddriverinstallation procedure.If thisdoesnotoccuritispossibletoinitiate
thisprocess manuallyviathe ‘add newhardware’icon inthe controlpanelorviathe
windowsdevicemanager.
Followthe instructionsand when requested select‘havedisk’and then browsetothe
directoryon the installation CDROMcontaining the Deva028 drivers.

Forexample, forXP32/Vista32 select:
\PCinterfaceproducts\Deva028\Issue1.x\Drivers\Win32
Click okand followinstructionstocompletethe first stage of the installation. Windows
will indicateasecond timethatanewUSB devicehasbeen found and will startthe
standarddriverinstallation procedureagainand the process described aboveis
repeated.
The installation maybe tested using the supplied demonstration image captureutility
softwarethat maybe found on the CD inthe utils\win32 directory.
3SoftwareDevelopmentKit
Fordevelopmentofgeneral-purposeimage captureapplications,Devaprovidesa
suiteoffunctionsbuiltintothe Devacapturelibrary. The libraryisdesigned toprovide
the facilitiesnecessaryforthe configuration and controlofliveand still image capture
fromwithinauserapplication.
The Devacapturelibraryfunctionsarecontained inaDLL that communicateswiththe
lowerleveldevicedriver.The usermustcall libraryroutinesinthe 32 bit 'camlib.dll'to
access the functionsdescribed inthismanualfrom32 bitWindowsapplications
written inMicrosoft VisualBasic, Microsoft C++, Borland Delphi, etc.
Various‘C’ headerfilesand VisualBasicmodulesareprovided toenablethe
developertointerfacetothe Devacapturelibraryand examplesourcecode is
provided toillustrateit’suse.
3.1Common definitions
Thissection isareferenceforvariousdatatypesand valuesthat areused throughout
the manual.
3.1.1Data types
The functionsand datastructuresdefined inthe libraryhaveparametersand values
made up ofasetofstandarddatatypes.The exactrepresentationsofthe datatypes
depend on the programming language being used,sogenericabbreviationshave
been assigned tothe variousdatatypes.
The usershouldusethe implementation ofthe datatype appropriatetohis
programming language.Therearenotalways directequivalentsbetween the different
languages.Forexample,VisualBasicdoesnotprovide the pointer datatype found in
‘C’,and somemoryaddressesofarrays and structureshavetobe passed asthe
integerdatatype Long.

I8 8-bit signed byte ‘C’ type:
VisualBasictype: char Byte
U8 8-bit unsigned byte
‘C’ type: VisualBasicequivalent: unsigned char Byte
I16 16-bit signed integer ‘C’ type:
VisualBasictype: Short Integer
U16 16-bit unsigned integer
‘C’ type: VisualBasicequivalent: unsigned short Integer
I32 32-bit signed integer ‘C’ type:
VisualBasictype: long Long
U32 32-bit unsigned integer ‘C’ type:
VisualBasicequivalent: unsigned long Long
F32 32-bitsingleprecision
floating point ‘C’ type:
VisualBasictype float (single) Single
F64 64-bitdoubleprecision
floating point ‘C’ type:
VisualBasictype: double Double
STR handle(pointer) to
characterarray ‘C’ type:
VisualBasicequivalent: char* Long
HDL handle(pointer) to
memoryarea ‘C’ type:
VisualBasicequivalent: (type)* Long
3.2Programming definitions
Manyofthe functionsand datastructuresinthe systemcan acceptalimited number
ofpredefined valuestodetermine theiroperation.The librarydefinesseveralsetsof
constantdefinitionsforthe validnumericvalues,and the usershouldmakeuseof
thesewhen assigning valuestosystemdataand function parametersratherthan
using theirnumericequivalents.

3.2.1CAM_CLIENT_TYPES
Type Description
CAM_CLIENT_USER_TYPE The calling application isrunning in‘Usermode’
CAM_CLIENT_WDM_TYPE The calling application isrunning asaWDMin‘Kernel
mode’
One ofthesevaluesispassed inthe call tofunction open_cam. Innormalcircumstances,
the calling application ordll isrunning inusermode and so CAM_CLIENT_USER_TYPE
isspecified.PleasecontactDevaifmoreinformation isrequired regarding accessing the
motion libraryfunctionsfromawindowsdriverorWDM.
3.2.2CAM_OPERATION_MODES
Type Description
CAM_STANDARD_RES_FULL
_SPEEDSpecifiesthe cameraoperating withstandardresolution at full speed.
CAM_HIGH_RES_HALF_SPE
ED Thismode isnot currentlyimplemented
Thesevaluesareused byfunctionssuchas setup_capture tospecifythe operating
mode foracapturestream.
3.2.3CAM_CAPTURE_TYPES
Type Description
CAPTURE_STOPThe capturestreamisreset, image capturesareno
longertriggered and the framebuffercleared.
CAPTURE_IMMEDIATE The image captureistriggered eachtimethe user
application specifies
CAPTURE_CONTROL_TYPE_PLAY or
CAPTURE_CONTROL_TYPE_FRAME_ADVANCE ina
call to capture_control.
CAPTURE_ON_PROBE A probe deviceconnected tothe probe inputtriggers
the image capture.
CAPTURE_REPEAT Imagesarecaptured repeatedlyat the ratespecified.
Thesevaluesareused byfunctionssuchas setup_capture tospecifythe triggerevent
forthe image captureofacapturestream.

3.2.4CAM_FORMAT_TYPES
Type Description
CAM_RAW Rawpixeldatareturned fromthe image sensorwithout
anyimage post-processing.
CAM_RGB32 Apixelisrepresented by4bytesinascending order
red, green and blue. The 4th byteisnot used.
CAM_RGB24 Apixelisrepresented by3bytesinascending order
red, green and blue.
CAM_RGBBYTE A pixelisrepresented by3bytesinascending order
blue, green and red.
CAM_RGBDOUBLE A pixelisrepresented by3doublesinascending order
red, green and blue.
CAM_GREYBYTE Thereisone greyscalebyteperpixel.
Thesevaluesspecifythe differenttypesofformatavailableforthe image capturedata
contained inthe framereturned byacall to copy_capture_buffer.
3.2.5CAM_SYNC_TYPES
Type Description
CAM_SYNC_OFF The specified syncsignalisdisabled.
CAM_SYNC_CAPTURE_PUL
SE The specified syncsignalwill pulseon then off automatically.
CAM_SYNC_CAPTURE_SET The specified syncsignalwill latchon and mustbe
cleared bythe userapplication.
Thesevaluesareused byfunctionssuchas setup_sync toconfigurethe operation of
signalson the camerasyncconnector.

3.2.6CAPTURE_CONTROL_TYPES
Type Description
CAPTURE_CONTROL_TYPE_
STOPThe capturestreamisstopped.
CAPTURE_CONTROL_TYPE_
PAUSE The capturestreamispaused.
CAPTURE_CONTROL_TYPE_
PLAY The capturestreamisstarted.Inthe caseofa
CAPTURE_IMMEDIATE streamasingleimage capture
istriggered.Repeated imageswill be captured atthe
specified ratefora CAPTURE_REPEAT stream.
CAPTURE_CONTROL_TYPE_
FRAME_ADVANCE Inthe caseof apaused CAPTURE_REPEAT streamor
a CAPTURE_IMMEDIATE stream,asingleimage
captureistriggered.
Thesevaluesareused bythe capture_controlfunction tocontrolthe capturestream.
3.2.7CAPTURE_COORDINATE_TYPES
Type Description
CAPTURE_COORDINATE_CA
MSpecifiesthatthe associated valuesrelatetocaptured image pixels.
CAPTURE_COORDINATE_WI
NDOW Specifiesthatthe associated valuesrelatetouser’s application windowpixels.
Thesevaluesareused byfunctionssuchas capture_overlay and capture_cursor to
determine whetherparametervaluesspecified relatetocaptured image pixelsoruser’s
application windowpixels.
3.2.8CAPTURE_CALLBACK_TYPES
Type Description
CAPTURE_CALLBACK_CAPT
URE_OCCURRED Animage capturehasbeen triggered on the capture stream.
CAPTURE_CALLBACK_CAPT
URE_ERROR Anerrorhasoccurred on the capturestream.
The callback_type memberofthe CAPTURE_CALLBACK_MSG structureissettoone
ofthesevaluestoidentifythe reason thatauserfunction,previouslyregistered byacall
to hook_capture_callback, hasbeen called.

3.2.9CAPTURE_AUTO_ADJUST_MODES
Type Description
CAPTURE_AUTO_ADJUST_O
FF The automaticadjustmentofimage and exposureis disabled.
CAPTURE_AUTO_ADJUST_O
N The automaticadjustmentofimage and/orexposureis enabled.
The adjustment_mode memberofthe CAPTURE_AUTO_ADJUST_PARAMS structure
issettoone ofthesevaluestoenableordisablethe post-process image and exposure
adjustment.
3.2.10CAPTURE_IMAGE_ADUSTMENT_TYPES
Type Description
CAPTURE_IMAGE_ADJUSTM
ENT_PER_COLOUR The range ofpixelvaluesinthe red,green and blue channelhistogramsaremaximised independentlyof
eachother.
CAPTURE_IMAGE_ADJUSTM
ENT_COMBINED_COLOURS The combined red, green and blue channelhistogramis maximised byapplying the sameadjustmenttoeach
channel.
The adjustment_type memberofthe CAPTURE_AUTO_ADJUST_PARAMS structureis
settoone ofthesevaluestospecifythe type ofpost-process image adjustmentapplied
tothe image.

3.2.11CAPTURE_AUTO_EXPOSURE_MODES
Type Description
CAPTURE_AUTO_EXPOSUR
E_OFF The automaticexposureadjustment isdisabled.
CAPTURE_AUTO_EXPOSUR
E_GAIN Whilstlighting conditionsaresuchthatthe image sensorgainremainswithinuserspecified limits,itis
adjusted asrequired whilstthe integration timeremains
fixed at itsnominalvalue. However, iflighting conditions
aresuchthat the adjusted gainreachesone ofitslimits,
the integration timeisthen adjusted asrequired within
itsownuserspecified limits.
CAPTURE_AUTO_EXPOSUR
E_INTEGRATION_TIME Whilstlighting conditionsaresuchthatthe image sensorintegration timeremainswithinuserspecified
limits,itisadjusted asrequired whilstthe gainremains
fixed at itsnominalvalue. However, iflighting conditions
aresuchthatthe adjusted integration timereachesone
ofitslimits,the gainisthen adjusted asrequired within
itsownuserspecified limits.
CAPTURE_AUTO_EXPOSUR
E_GAIN_AND_INTEGRATION
_RATIO
Auserspecified ratiodetermineshowthe image sensor
gainand integration timeareadjusted fromtheir
nominalvalues.The gainwouldchange attwicethe
rateof integration timewitharatioof 2.0and at halfthe
ratewitharatioof0.5.Aratioof1.0maybe used to
specifyequaladjustmentofeachparameter.Both
parametersareonlyadjusted withinthe userspecified
limits.
CAPTURE_AUTO_EXPOSUR
E_GAIN_AND_INTEGRATION
_MIN_TO_MAX
The userspecified limitsareused todetermine the
combined adjustmentofgainand integration time.The
parametersareadjusted inalinearfashion between the
maximumand minimumlimits.
The adjust_mode memberofthe CAPTURE_AUTO_ADJUST_PARAMS structureisset
toone of thesevaluestospecifythe type ofpost-process exposureadjustment applied to
the image.
Withinboundsspecified bythe user,automaticadjustmentsmaybe made togainand/or
integration timesothatimage qualityismaximised fordifferenttypesofimage and
lighting conditions.Thesevaluesspecifythe differenttypesofautomaticexposure
adjustmentthatmaybe selected.Changestothe image sensorsettingsaremade
following analysisof eachimage and itnormallytakesseveralframesbeforethe optimum
settingsarereached foragiven image and lighting condition.

The following graph illustrateshowthe gainand integration timechange under
varying lighting conditionsforthe different autoadjustment modes:
Integration
time
Adjust gain,integration timefixed
Integration
time
Gain
Max
Max
Min
Min
Nominal
Nominal
Adjust Integration time, gainfixed
Gain&integration time, ratio2.0
Gain&integration time, ratio0.5
Gain&integration time, min/max
3.2.12CAPTURE_OVERLAY_TYPES
Type Description
CAPTURE_OVERLAY_OFF Nooverlayisapplied tothe capturestream.
CAPTURE_OVERLAY_STAN
DARD Ausersupplied overlayisapplied tothe capture stream.
CAPTURE_OVERLAY_RAW_
HISTOGRAM Ahistogramrepresenting the pixeldataforthe raw image dataisoverlaidon the capturestream.
CAPTURE_OVERLAY_ADJUS
TED_HISTOGRAM Ahistogramrepresenting the pixeldataforthe post- processed image adjusted dataisoverlaidon the
capturestream.
Thesevaluesareused byfunctionssuchas capture_overlay tospecifythe type of
overlay.
3.2.13CAPTURE_CURSOR_TYPES
Type Description
CAPTURE_CURSOR_OFF Nocursorisapplied tothe capturestream.
CAPTURE_CURSOR_CROSS
_HAIRS Cross haircursorsareoverlaidon the capturescreen.
Thesevaluesareused byfunctionssuchas capture_cursor tospecifythe type of
cursor.