sharpVISION™ SDK Reference Manual Software Development Kit Copyright © 2000, 2006 Integrated Design Tools, Inc.
sharpVISION™ Camera SDK Release 2.07 Document Revision October 2006 Products Information http://www.idtvision.com North America 1804 Miccosukee Commons, suite 208 TALLAHASSE FL 32308 USA P: (+1) (850) 222-5939 F: (+1) (850) 222-4591 llourenco@idtpiv.com Europe via Pennella, 94 I-38057 - Pergine Valsugana (TN) ITALY P: (+39) 0461- 53 21 12 F: (+39) 0461- 53 21 04 pgallorosso@idtpiv.com Copyright © Integrated Design Tools, Inc.
sharpVISION™ Camera Table of Contents 1. OVERVIEW..................................................................................................7 1.1. 2. DIRECTORIES STRUCTURE .................................................................................. 8 USING SHARPVISION™ SDK....................................................................9 2.1. 2.2. 2.3. 2.4. 2.5. 2.6. 2.7. 2.8. 2.9. 2.10. 2.11. 3. PROGRAMMING LANGUAGE ...................................................................
sharpVISION™ Camera 4.2.4. 4.2.5. 4.2.6. 4.2.7. 4.2.8. 4.2.9. 4.2.10. 4.2.11. 4.2.12. 4.2.13. 4.2.14. 4.2.15. 4.2.16. 4.2.17. 4.2.18. 4.2.19. 4.2.20. 4.2.21. 4.2.22. 4.2.23. 5. SHARPVISION™ TWAIN™ DRIVER REFERENCE .................................64 5.1. 5.2. 5.3. OVERVIEW ....................................................................................................... 64 SELECT SOURCE...............................................................................................
sharpVISION™ Camera 6.6. HOW TO USE THE VIS ....................................................................................... 85 6.6.1. 6.6.2. 6.6.3. 6.6.4. 6.6.5. 6.6.6. 6.7. EXAMPLES VIS ................................................................................................. 86 6.7.1. 6.7.2. 6.7.3. 6.7.4. 6.7.5. 6.7.6. 6.7.7. 7. Snapping an image ...................................................................................................85 Opening and closing a camera .......
sharpVISION™ Camera 8.3. 8.4. APPENDIX C – CAMERA SETTINGS .................................................................. 108 APPENDIX D – DATA TYPES ............................................................................. 109 8.4.1. 8.4.2. 8.4.3. 8.4.4. 8.4.5. 8.4.6. 8.4.7. 8.4.8. 8.4.9. 8.4.10. 8.4.11. 8.5. 8.5.1. 8.5.2. 8.5.3. 8.5.4. 6 SV_CAM_TYPE..................................................................................................... 109 SV_CCD_TYPE ...........................
sharpVISION™ Camera 1. Overview The on-line documentation of the sharpVISION™ Software Development Kit and its components is divided into the following parts: Using sharpVISION™ SDK This section describes how to start using the sharpVISION™ SDK. sharpVISION™ SDK Reference This section contains a detailed description of the sharpVISION™ SDK functions. sharpVISION™ ActiveX Control Reference This section contains a detailed description of the sharpVISION™ ActiveX functions.
sharpVISION™ Camera 1.1. Directories structure The default installation directory of the SDK is “C:\Program Files\IDT\sharpVISION”. Under this directory a set of sub-directories is created: BIN: it contains the files (drivers, INF, DLLs) that can be re-distributed with the camera and your application. DOCS: it contains the SDK documentation and the camera manuals. IMAGES: it’s the default directory where the acquired images may be stored. INCLUDE: it contains the SDK header files (H and BAS).
sharpVISION™ Camera 2. Using sharpVISION™ SDK 2.1. Programming Language A C/C++ header file is included in the SDK (SharpAPI.h file in the Include sub-directory). Most compiled languages can call functions; you will need to write your own header/import/unit equivalent based on the C header file. In Windows version a Visual Basic module is included in the SDK (SharpAPI.bas file in the Include sub-directory).
sharpVISION™ Camera 2.3. Enumerate/Open a camera To get the list of available cameras, call SvEnumCameras. Use the cameraId field of the camera list in your call to SvOpenCamera. Here is a simple example of opening the first available camera: SV_ENUMITEM svList[10]; unsigned long nListLen = sizeof(szList)/sizeof(SV_ENUMITEM); SvLoadDriver(); // nListLen is the length of your SV_ENUMITEM array SvEnumCameras( &svList[0], &nListLen ); // nListLen is now the number of cameras available.
sharpVISION™ Camera 2.4. Configuring a camera The camera state is represented by the opaque SV_SETTINGS structure. You can read the default state, read the state from the camera, or send the state to the camera. Parameters are read and written to a SV_SETTINGS structure with functions SvGetParameter and SvSetParameter. The functions SvGetParameterMin and SvGetParameterMax provide information on a parameter's range. Here is an example of setting the camera to 100 ms exposure time: SV_SETTINGS svCfg; svCfg.
sharpVISION™ Camera 2.5. Synchronous Streaming Data Grab To grab an image from steaming data, you need to allocate an image buffer of sufficient size, fill out a SV_FRAME structure, then call a grab function. Here is an example of a simple, synchronous frame grab: SV_FRAME frame; unsigned long nSizeInBytes; // Image size depends on the current ROI & image format. SvGetCameraInfo( hCamera, SVI_IMG_SIZE, &nSizeInBytes ); // Fill out fields in SV_FRAME structure. frame.
sharpVISION™ Camera 2.6. Asynchronous Streaming Data Grab An asynchronous grab function is available: SvQueueOneFrame. Many frames can be queued up at a time. The maximum number of frames that can be queued at a time is 100. When an image arrives from the camera and a frame is complete, your application can receive a callback. The completed frame is removed from the queue, and if available the next frame takes its place.
sharpVISION™ Camera 2.8. Binning Binning is the process of combining adjacent pixels of the sensor during readout. The two primary benefits of binning are improved signal to noise ratio (SNR) and the ability to increase frame rate, albeit at the expense of reduced spatial resolution. The maximum image size for each binning is not an even division of the 1x1 maximum image size.
sharpVISION™ Camera 2.9. Read-out Speed and Pixel Format The maximum readout speed depends on bit depth, although this restriction may not exist in future cameras. Only 8 bit formats can run at 20 MHz; 16 bit formats are limited to 10 MHz or lower. There is no advantage to using a lower readout speed. When you call SvValidateSettings or SvSendCameraSettings, the readout speed is lowered if your image format is 16 bits. A common mistake occurs when switching from a 16 bit format to 8 bit format.
sharpVISION™ Camera 2.10. Region of Interest (ROI) Different camera models have different behaviors: 1300-DE: ROI boundaries occur on multiplies of 16, although the maximum region for a particular binning mode is not restricted to this rule. Minimum ROI is 16x16. 1400-DE and 1500-EX: they can do ROI on 4-pixel boundaries in width and 1-pixel in height. On 1300-DE cameras, your ROI is adjusted in SvSendCameraSettings before the camera state is changed.
sharpVISION™ Camera 3. sharpVISION™ SDK Reference 3.1. Initialization Functions 3.1.1. Overview: Initialization functions Initialization functions allow the user to initialize the sharpVISION camera, enumerate the available cameras, open and close them. SvGetVersion returns the DLL version numbers and the demo flag. SvLoadDriver loads the driver and initializes it. SvUnloadDriver unloads the driver. SvEnumCameras enumerates the sharpVISION cameras connected to the computer. SvOpenCamera opens a camera.
sharpVISION™ Camera 3.1.2. SvGetVersion SV_ERROR SvGetVersion( unsigned short *pVerMajor, unsigned short *pVerMinor , int* pIsDemo) Return values SVC_SUCCESS if successful, otherwise SVC_DRIVERFAULT if the version numbers could not be extracted from the driver. Parameters pVerMajor Specifies the pointer to the variable that receives the major version number. pVerMinor Specifies the pointer to the variable that receives the minor version number.
sharpVISION™ Camera 3.1.3. SvLoadDriver SV_ERROR SvLoadDriver( void ) Return values SVC_SUCCESS if successful, otherwise SVC_DRIVERALREADYLOADED if the driver is already loaded. SVC_OUTOFMEMORY if not enough memory could be allocated for the driver. SVC_NOFIREWIREDRIVER, if the firewire driver could not be found. SVC_FIREWIREFAULT, if an error occurred while calling the firewire driver. Parameters None Remarks The routine loads the sharpVISION driver DLL and initializes it.
sharpVISION™ Camera 3.1.4. SvUnloadDriver void SvUnloadDriver( void ) Return values None Parameters None Remarks This function must be called before terminating the application. This function frees any memory and resource allocated by the camera driver and unloads it.
sharpVISION™ Camera 3.1.5. SvEnumCameras SV_ERROR SvEnumCameras( PSV_ENUMITEM pItemList, unsigned long *pItemNr ) Return values SVC_SUCCESS if successful, otherwise SVC_FIREWIREFAULT, if an error occurred while calling the firewire driver. Parameters pItemList Specifies the pointer to an array of SV_ENUMITEM structures. pItemNr Specifies the pointer to the variable that receives the number of detected cameras.
sharpVISION™ Camera 3.1.6. SvOpenCamera SV_ERROR SvOpenCamera( unsigned long cameraId, SV_HANDLE* pHandle ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDCAMERAID, if the camera ID is not valid. SVC_UNKNOWNCAMERA, if the camera model is unknown to this version of the driver. SVC_FIREWIREFAULT, if an error occurred while calling the firewire driver. Parameters cameraId Specifies the ID of the camera to be opened. pHandle Specifies the pointer to the variable that receives the camera handle.
sharpVISION™ Camera 3.1.7. SvCloseCamera SV_ERROR SvCloseCamera( SV_HANDLE hCamera ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. Parameters hCamera Specifies the handle to an open camera Remarks Closes and open Camera.
sharpVISION™ Camera 3.2. Configuration Functions 3.2.1. Overview: Configuration functions The configuration functions allow the user to control the status of the sharpVISION camera. SvGetCameraInfo gets independent information from the camera, such as serial number, CCD type, etc. SvReadDefaultSettings reads default settings in the SV_SETTINGS opaque structure. SvReadCameraSettings reads camera settings in the SV_SETTINGS opaque structure. SvSendCameraSettings sends settings to the camera.
sharpVISION™ Camera 3.2.2. SvGetCameraInfo SV_ERROR SvGetCameraInfo( unsigned long *pValue ) SV_HANDLE hCamera, SV_INFO infoKey, Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_NOTSUPPORTED, if the infoKey is not supported. Parameters hCamera Specifies the handle to an open camera. infoKey Specifies which parameter the funcion returns.
sharpVISION™ Camera 3.2.3. SvReadDefaultSettings SV_ERROR SvReadDefaultSettings( SV_HANDLE hCamera, PSV_SETTINGS pSettings ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid Parameters hCamera Specifies the handle to an open camera. pSettings Specifies the pointer to the structure to be filled with the camera settings.
sharpVISION™ Camera 3.2.4. SvReadCameraSettings SV_ERROR SvReadCameraSettings ( SV_HANDLE hCamera, PSV_SETTINGS pSettings ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid Parameters hCamera Specifies the handle to an open camera. pSettings Specifies the pointer to the structure to be filled with the camera settings.
sharpVISION™ Camera 3.2.5. SvSendCameraSettings SV_ERROR SvSendCameraSettings ( SV_HANDLE hCamera, PSV_SETTINGS pSettings ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid. SVC_OUTOFMEMORY, if not enough memory is available. Parameters hCamera Specifies the handle to an open camera. pSettings Specifies the pointer to the structure that contains the camera settings.
sharpVISION™ Camera 3.2.6. SvQueueCameraSettings SV_ERROR SvQueueCameraSettings ( SV_HANDLE hCamera, PSV_SETTINGS pSettings, SV_AsyncCallback pfnCallback, unsigned long nFlags, void *pUser, unsigned long nUserData) Return values SVC_SUCCESS if successful, otherwise Parameters hCamera Specifies the handle to an open camera. pSettings Specifies the pointer to the structure that contains the camera settings. pfnCallback Specifies the pointer to the callback routine.
sharpVISION™ Camera 3.2.7. SvSetParameter SV_ERROR SvSetParameter ( PSV_SETTINGS pSettings, SV_PARAM paramKey, unsigned long nValue) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_NOTSUPPORTED, if the paramKey is not supported. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid. Parameters pSettings Specifies the pointer to the SV_SETTINGS structure the parameter is written to. infoKey Specifies which parameter the function sets.
sharpVISION™ Camera 3.2.8. SvGetParameter SV_ERROR SvGetParameter( PSV_SETTINGS pSettings, SV_PARAM paramKey, unsigned long *pValue) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_NOTSUPPORTED, if the paramKey is not supported. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid. Parameters pSettings Specifies the pointer to the SV_SETTINGS structure the parameter is read from. infoKey Specifies which parameter the function returns.
sharpVISION™ Camera 3.2.9. SvGetParameterMin SV_ERROR SvGetParameterMin( paramKey, unsigned long *pValue) PSV_SETTINGS pSettings, SV_PARAM Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_NOTSUPPORTED, if the paramKey is not supported. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid. Parameters pSettings Specifies the pointer to the SV_SETTINGS structure the parameter is read from.
sharpVISION™ Camera 3.2.10. SvGetParameterMax SV_ERROR SvGetParameterMax( paramKey, unsigned long *pValue) PSV_SETTINGS pSettings, SV_PARAM Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_NOTSUPPORTED, if the paramKey is not supported. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid. Parameters pSettings Specifies the pointer to the SV_SETTINGS structure the parameter is read from.
sharpVISION™ Camera 3.2.11. SvEnableStreaming SV_ERROR SvEnableStreaming( SV_HANDLE hCamera, unsigned long bEnable ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_BADSETTINGS, if the SV_SETTINGS structure is not valid. SVC_OUTOFMEMORY, if not enough memory is available. Parameters hCamera Specifies the handle to an open camera. bEnable Specifies whether the streaming is to be enabled or not.
sharpVISION™ Camera 3.3. Grab Functions 3.3.1. Overview: Grab functions Grab functions allow the user to capture streamed data from the digital camera. The grab process may be performed in two ways: Synchronous: calling SvGrabFrame function. Asynchronous: calling SvQueuFrame function. Both methods use the SV_FRAME structure to grab the data. SvGrabOneFrame grabs one frame synchronously. SvQueueOneFrame grabs one frame asynchronously. SvAbortGrab aborts any pending asynchronous grab.
sharpVISION™ Camera 3.3.2. SvGrabOneFrame SV_ERROR SvGrabOneFrame( SV_HANDLE hCamera, PSV_FRAME pFrame ) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_BUFFERTOOSMALL, if the frame buffer is too small for the image. SVC_FIREWIREFAULT, if an internal error occurred while calling the firewire driver. Parameters hCamera Specifies the handle to an open camera. pFrame Specifies the pointer to a SV_FRAME structure.
sharpVISION™ Camera 3.3.3. SvQueueOneFrame SV_ERROR SvQueueOneFrame(SV_HANDLE hCamera, PSV_FRAME pFrame, SV_AsyncCallback pfnCallback, unsigned long nFlags, void *pUser, unsigned long nUserData) Return values SVC_SUCCESS if successful, otherwise SVC_INVALIDHANDLE, if the camera handle is not valid. SVC_BUFFERTOOSMALL, if the frame buffer is too small for the image. SVC_FIREWIREFAULT, if an internal error occurred while calling the firewire driver. Parameters hCamera Specifies the handle to an open camera.
sharpVISION™ Camera 3.3.4. SvAbortGrab SV_ERROR SvAbortGrab( SV_HANDLE hCamera ) Return values SVC_SUCCESS if successful, otherwise Parameters hCamera Specifies the handle to an open camera. Remarks This function stops all the pending grab operations and clears the queue. After the function has returned no more SvQueueOneFrame or SvQueueCameraSettings callbacks occur.
sharpVISION™ Camera 3.3.5. SvTrigger SV_ERROR SvTrigger( SV_HANDLE hCamera ) Return values SVC_SUCCESS if successful, otherwise Parameters hCamera Specifies the handle to an open camera. Remarks This function triggers a camera exposure (software trigger). The camera trigger mode must be set to hardware or software trigger (see Appendix B). Firewire streaming must be on.
sharpVISION™ Camera 4. sharpXvision™ ActiveX Control Reference 4.1. Overview ActiveX is a set of technologies that enable software components to interact with one another in a networked environment, regardless of the language in which the components were created. An ActiveX control is a user interface element created using ActiveX technology. ActiveX controls are small, fast, and powerful, and make it easy to integrate and reuse software components.
sharpVISION™ Camera 4.2. Camera Control Functions 4.2.1. Overview: Camera Control functions Camera Control functions allows the user to control the status of the camera toolbar buttons. CmdShowCameraToolbar toggles the camera toolbar. CmdShowCameraControl shows and hides the camera settings dialog bar. CmdShowRecordDialogBox is no more supported (deprecated) CmdShowSaveSequenceDialogBox displays the save acquisition dialog box. CmdRecord starts acquiring.
sharpVISION™ Camera 4.2.2. CmdShowMainToolbar short CmdShowMainToolbar( short nShow ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters nShow Specifies if the main toolbar is visible or not. It must be one of the following values: FALSE: hides the toolbar. TRUE: shows the toolbar. Remarks This function makes the main toolbar visible or not.
sharpVISION™ Camera 4.2.3. CmdShowCameraBar void CmdShowCameraBar( short nShow ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters nShow Specifies if the camera bar is visible or not. It must be one of the following values: FALSE: hides the bar. TRUE: shows the bar. Remarks This function makes the camera bar visible or not.
sharpVISION™ Camera 4.2.4. CmdShowSaveSequenceDialogBox void CmdShowSaveSequenceDialogBox ( void ) Return values None Parameters None Remarks The function displays the "save acquired sequence" modal dialog box.
sharpVISION™ Camera 4.2.5. CmdRecord short CmdRecord( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function starts the acquisition of a sequence of images. The number of images can be set (SetFramesNumber) and read (GetFramesNumber).
sharpVISION™ Camera 4.2.6. CmdPlay short CmdPlay( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks If the camera is in idle mode, this function set the camera in play mode, otherwise it stops the camera.
sharpVISION™ Camera 4.2.7. CmdStop short CmdStop( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks If the camera is playing, the function stops the camera. If the camera is in idle mode, the function snaps a frame.
sharpVISION™ Camera 4.2.8. CmdRewind short CmdRewind( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function displays the sequence of the acquired frames in reverse order.
sharpVISION™ Camera 4.2.9. CmdFastForward short CmdFastForward( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function displays the sequence of the acquired frames.
sharpVISION™ Camera 4.2.10. CmdShowPreviousFrame short CmdShowPreviousFrame( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function displays the previous image from the list of the acquired frames.
sharpVISION™ Camera 4.2.11. CmdShowNextFrame short CmdShowNextFrame( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function displays the next image from the list of the acquired frames.
sharpVISION™ Camera 4.2.12. CmdShowFirstFrame short CmdShowFirstFrame( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function displays the first frame of a recorded sequence.
sharpVISION™ Camera 4.2.13. CmdShowLastFrame short CmdShowLastFrame( void ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters None Remarks This function displays the last frame of a recorded sequence.
sharpVISION™ Camera 4.2.14. GetImageWidth long GetImageWidth() Return values The image width, in pixels Parameters None Remarks This function returns the current value in pixels of the image width.
sharpVISION™ Camera 4.2.15. GetImageHeight long GetImageHeight() Return values The image height, in pixels Parameters None Remarks This function returns the current value in pixels of the image height.
sharpVISION™ Camera 4.2.16. GetImagePixelDepth long GetImagePixelDepth( ) Return values The image pixel depth (8 or 10 or 12) Parameters None Remarks This function returns the current value of the pixel depth of the image.
sharpVISION™ Camera 4.2.17. GetExposure long GetExposure() Return values The camera exposure, in microseconds Parameters None Remarks This function returns the current value in microseconds of camera exposure.
sharpVISION™ Camera 4.2.18. GetFramesNumber long GetFramesNumber() Return values The number of allocate frames Parameters None Remarks This function returns the current value of the number of frames that can be acquired by calling the CmdRecord () routine. After the recording the data may be read by calling the GetFrames routine.
sharpVISION™ Camera 4.2.19. GetFrames long GetFrames (long nFrames, long nStartIndex, long pDataBuff ) Return values SVC_SUCCESS, if successful, otherwise SVC_GENERICERROR, if an error occurs. Parameters nFrames Specifies the number of frames to read. nStartIndex Specifies the index of the first frame to read. pDataBuff Specifies the pointer to data buffer. Remarks This function reads one or more frames from the controls memory to a data buffer specified by the pDataBuff parameter.
sharpVISION™ Camera 4.2.20. IsCameraOK long IsCameraOK ( void ) Return values Returns 1 if the camera is initialized and open, 0 otherwise Parameters None Remarks This function returns the camera current status. Call this function before using any other routine, to check if the camera is initialized and open.
sharpVISION™ Camera 4.2.21. IsCameraRecording long IsCameraRecording ( void ) Return values Returns 1 if the camera is recording frames, 0 otherwise Parameters None Remarks This function returns the camera current recording status. Call this function to check if the camera is recording frames or not.
sharpVISION™ Camera 4.2.22. SetExposure void SetExposure ( long nExposure ) Return values None Parameters nExposure Specifies the new camera exposure value in microseconds. Remarks This function sets a new value of exposure in the camera.
sharpVISION™ Camera 4.2.23. SetFramesNumber void SetFramesNumber ( long nFrames ) Return values None Parameters nFrames Specifies the new number of frames to set. Remarks This function sets the number of frames that will be acquired in the next acquisition. The value may be read by calling the GetFramesNumber routine.
sharpVISION™ Camera 5. sharpVISION™ TWAIN™ Driver Reference 5.1. Overview TWAIN defines a standard software protocol and API (application programming interface) for communication between software applications and image acquisition devices (the data source). The sharpVISION™ TWAIN driver complies with these specifications.
sharpVISION™ Camera 5.3. Acquire images If the user selects the Acquire option, the sharp VISION User Interface is displayed. The user may select the camera parameters and operate the camera by pressing one of the buttons described below. Then the currently displayed image may be imported in the host application by pressing the “Acquire” button or the “Get Preview Image” button.
sharpVISION™ Camera 5.3.1. Parameters The camera configuration parameters may be interactively changed. Exposure Time: the camera exposure may be adjusted. The value is in microseconds with increments of 1 microsecond. Contrast and Brightness: the contrast and brightness of the image produced by the camera may be adjusted. The values range from –100 to 100. Binning: the user may select the binning mode from 1x1 to 4x4.
sharpVISION™ Camera 5.3.3. Camera Control Group Play: it’s the standard Play button of any camera interface. If the button is pressed, the camera starts previewing. Stop: press this button to stop the camera play or to refresh the preview window with a new camera snapshot or stop the current acquisition if the record button has been previously pressed.
sharpVISION™ Camera 6. sharpVISION™ LabVIEW™ Interface Reference 6.1. Overview The sharpVISION™ LabVIEW® Interface allows acquiring images and controlling the sharpVISION digital cameras from inside National Instruments LabVIEW application. It works with LabVIEW 6 and greater, on Windows 2000/XP. Windows NT is not supported.
sharpVISION™ Camera 6.2.2. IDT List Cameras Inputs Error Specifies a standard error cluster input terminal Outputs Error Specifies the return error code of the function (0 if the function is successful, otherwise not 0) IDs Specifies the array containing the IDs of the detected cameras Nr of Cameras Specifies the number of detected cameras Remarks The VI enumerates the active cameras and returns a list of the detected cameras IDs.
sharpVISION™ Camera 6.2.3. IDT Open Inputs Camera ID Specifies the ID of the camera to be opened, or 0 for the first available camera Error Specifies a standard error cluster input terminal Outputs Error Specifies the return error condition Camera ID Specifies the ID of the opened camera Remarks The VI opens the camera with a specific ID. The value can be retrieved calling the “IDT List Cameras” VI. The user may supply a specific camera ID or 0: in this case the first available camera is opened.
sharpVISION™ Camera 6.2.4. IDT Close Inputs Camera ID Specifies the ID of the camera to be closed Error Specifies a standard error cluster input terminal Outputs Error Specifies the return error condition Remarks This VI closes a camera previously open. If any error occurs during the operation, the Error Out terminal signals this error.
sharpVISION™ Camera 6.3. Configuration VIs 6.3.1. Overview: Configuration VIs Configuration VIs allow the user to read information from the camera, read configuration parameters from the camera and write configuration parameters to the camera. IDT Get Info: it reads information from the camera, such as camera model, firmware version, sensor type, sensor model, etc. The info key is one of the input parameters.
sharpVISION™ Camera 6.3.2. IDT Get Info Inputs Camera ID Specifies a valid camera ID Info Key Specifies which parameter has to be returned by the VI Error Specifies a standard error cluster input terminal Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Value Specifies the value of the info parameter Remarks This VI returns camera specific information, such as sensor type or version numbers, generally state-independent information.
sharpVISION™ Camera 6.3.3. IDT Setup Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Parameters Each input is the value of a specific parameter: exposure time (in microseconds), contrast [0,4095], brightness [0,4095], binning (1x1, 2x2, 3x3 or 4x4), ROI (X, Y, width and height). Note that set 0 to exposure, binning, ROI Width or ROI height, means set it to the default value. For ex.
sharpVISION™ Camera 6.3.4.
sharpVISION™ Camera 6.3.5. IDT Set Param Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Param Key Specifies the index of the parameter Value Specifies the value of the parameter Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Remarks This VI writes a specific configuration parameter to the camera. The parameter key is one of the input parameters. A list of the parameters indexes is available in Appendix C.
sharpVISION™ Camera 6.3.6. IDT Trig Setup Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Trigger Mode Specifies the trigger mode parameter. Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Remarks This VI configures the trigger mode to the camera (internal, external edge-low, edge-high, pulse-low and pulse-high). If any error occurs during the operation, the Error Out terminal signals this error.
sharpVISION™ Camera 6.4. Grab VIs 6.4.1. Overview: Grab VIs Grab VIs allow the user to grab images from the camera. IDT Snap: this VI executes a complete acquisition sequence. It opens the first available camera, captures an image and closes the camera. IDT Grab Setup: this VI prepares the camera to acquire images. Use this VI before IDT Grab Acquire. IDT Grab: this VI acquires an image. It waits for a new image to be available and then transforms that image into an IMAQ Image.
sharpVISION™ Camera 6.4.2. IDT Snap Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Parameters Specifies the parameters to configure the camera (exposure, binning and ROI). Image Specifies the image object input Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Image Specifies the image object output Parameters Specifies the parameters values Remarks This VI snaps an image from the camera.
sharpVISION™ Camera 6.4.3. IDT Grab Setup Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Remarks This VI prepares a camera to acquire images. The VI must be called before any call to the “IDT Grab” VI. If any error occurs during the operation, the Error Out terminal signals this error.
sharpVISION™ Camera 6.4.4. IDT Grab Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Image Specifies the image object input Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Image Specifies the image object output Remarks this VI acquires an image. It waits for a new image to be available and then transforms that image into an IMAQ Image. To abort the acquisition, set the IDT Grab Abort global variable to TRUE.
sharpVISION™ Camera 6.4.5. IDT Grab Stop Inputs Camera ID Specifies a valid camera ID Error Specifies a standard error cluster input terminal Outputs Camera ID Specifies the camera ID Error Specifies the return error condition Remarks This VI stops any camera acquisition previously started. If any error occurs during the operation, the Error Out terminal signals this error.
sharpVISION™ Camera 6.4.6. IDT Grab Abort Inputs Variable value Specifies the value to set the variable Outputs None Remarks this is a global variable. Set this to TRUE to abort the IDT Grab. Note that after the VI has aborted, this variable is reset to FALSE. See also: “IDT Grab“, “IDT Stop Grab“ 6.5. Miscellaneous VIs 6.5.1. Overview: Miscellaneous VIs Miscellaneous VIs allow the user to convert image formats and manage the error conditions in the sharpVISION VIs.
sharpVISION™ Camera 6.5.2. IDT Image To Picture Inputs Error Specifies a standard error cluster input terminal Top-Left point Specifies the coordinates of the top-left point Image Specifies the image to convert Outputs Error Specifies the return error condition Picture Specifies the output LabVIEW picture object Remarks This VI converts an IMAQ image object into a LabVIEW picture object. If any error occurs, the Error Out terminal signals this error.
sharpVISION™ Camera 6.6. How to use the VIs 6.6.1. Snapping an image The easiest way to acquire an image is to use the IDT Snap VI. It opens the first available camera, configures it, acquires an image and then closes the camera. Optionally you may set the exposure, binning and ROI parameters. 6.6.2. Opening and closing a camera A camera must be opened before using its functions and then it must be closed. To open a specific camera you have to supply to the Open VI the unique ID of that camera.
sharpVISION™ Camera 6.7. Examples VIs 6.7.1. 1_enum_cameras It’s a very simple example which shows how to display the result of a cameras enumeration. The output of the “IDT List Cameras” VI is displayed in a group of four LED and four edit boxes. If a camera is enumerated the corresponding LED is turned on and the camera ID is displayed in the edit box. 6.7.2. 2_getinfo This VI shows how to retrieve information from the camera such as camera model, firmware version, etc.
sharpVISION™ Camera 7. sharpVISION™ MATLAB™ Interface Reference 7.1. Overview The sharpVISION™ MATLAB™ Interface allows to acquire images and to control the sharpVISION digital cameras from inside the Mathworks™ MATLAB application. The interface works with MATLAB 6.5 and greater, on Windows 2000/XP Professional. Windows NT is not supported. The sharpVISION™ MATLAB™ Interface includes the ‘MEX’ file for controlling the camera (packaged in a library called sharpML.dll) and a few example .
sharpVISION™ Camera 7.2. Initialization Functions 7.2.1. Overview: Initialization functions Initialization functions allow the user to initialize the sharpVISION camera, enumerate the available cameras, open and close them. IdtSvVersion: this function retrieves the driver version. IdtSvEnumCameras: this function enumerates the IDs of the sharpVISION cameras connected o the computer. IdtSvOpenCamera: this function opens an sharpVISION camera.
sharpVISION™ Camera 7.2.2. IdtSvVersion [strVersion] = SharpML (‘IdtSvVersion’) Inputs None Outputs strVersion Specifies the driver version string (for example, ‘2.03’) Remarks This function must be called to retrieve the sharpVISION™ MATLAB interface version string.
sharpVISION™ Camera 7.2.3. IdtSvEnumCameras [nResult, nItems, svArray] = SharpML (‘IdtSvEnumCameras’) Inputs None Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) nItems Specifies the number of detected cameras svArray Specifies the array containing the IDs of the detected cameras Remarks The routine enumerates the active cameras and return an array filled with the detected cameras IDs.
sharpVISION™ Camera 7.2.4. IdtSvOpenCamera [nResult, nCameraId] = SharpML (‘IdtSvOpenCamera’, nInputId) Inputs nInputId Specifies the ID of the camera to be opened, or 0 for the first available camera Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) nCameraId Specifies the ID of the opened camera Remarks The routine opens the camera whose ID is in the variable nInputId.
sharpVISION™ Camera 7.2.5. IdtSvCloseCamera [nResult] = SharpML (‘IdtSvCloseCamera’, nCameraId) Inputs nCameraId Specifies the ID of the camera to be closed Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) Remarks This function closes a camera previously open. If any error occurs during the operation, the routine returns an error code in the nResult variable, otherwise it returns 0.
sharpVISION™ Camera 7.3. Configuration functions 7.3.1. Overview: Configuration functions Configuration functions allow the user to read information from the camera, read configuration parameters from the camera and write configuration parameters to the camera. IdtSvGetCameraInfo: this function reads information from the camera, such as camera model, firmware version, sensor type, sensor model, etc. The info key is one of the input parameters.
sharpVISION™ Camera 7.3.2.
sharpVISION™ Camera 7.3.3.
sharpVISION™ Camera 7.3.4. IdtSvSetParameter [nResult] = SharpML (‘IdtSvSetParameter’, nCameraId, nParamKey, nValue) Inputs nCameraId Specifies a valid camera ID nParamKey Specifies the index of the parameter nValue Specifies the value of the parameter Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) Remarks This function writes a specific configuration parameter to the camera. The parameter key is one of the input parameters.
sharpVISION™ Camera 7.3.5. IdtSvConfigure [nResult] = SharpML (‘IdtSvConfigure’, nCameraId, nFormat, nBinning, nRoiX, nRoiY, nRoiWidth, nRoiHeight, nExposure, nContrast, nBrightness) Inputs nCameraId Specifies a valid camera ID nFormat Specifies the value of the image format (Gray8, Gray16). nBinning Specifies the value of the binning (1x1, 2x2, 3x3, 4x4). nRoiX, nRoiY, nRoiWidth, nRoiHeight Specifies the values of the ROI. nExposure Specifies the value of the exposure time in µs.
sharpVISION™ Camera 7.3.6. IdtSvSetTriggerMode [nResult] = SharpML (‘IdtSvSetTriggerMode’, nCameraId, nTriggerMode) Inputs nCameraId Specifies a valid camera ID nTriggerMode Specifies the value to set for the trigger mode ( 0 = Internal, 1=Ext. Edge High, 2=Ext. Edge Low, 3=Ext. Pulse High, 4=Ext. Pulse High). Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0). Remarks This function sets the trigger mode.
sharpVISION™ Camera 7.4. Grab Functions 7.4.1. Overview: Grab Functions Preview Mode grab functions allow the user to snap and acquire images from the camera. IdtSvStartAcquire: this function starts an acquisition in the camera. It sends the configuration to the camera and starts the acquisition process. IdtSvAcquire: this function grabs an image from the camera. The image grab is synchronous and the function exits when the frame has been grabbed or a time out occurs.
sharpVISION™ Camera 7.4.2. IdtSvStartAcquire [nResult] = sharpML (‘IdtSvStartAcquire’, nCameraId) Inputs nCameraId Specifies a valid camera ID Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) Remarks This function starts an acquisition in the camera. It sends the configuration to the camera and starts the acquisition process.
sharpVISION™ Camera 7.4.3. IdtSvAcquire [nResult, image] = sharpML (‘IdtSvAcquire’, nCameraId) Inputs nCameraId Specifies a valid camera ID Outputs image Specifies the array where the acquired image is stored nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) Remarks It grabs an image (or two) from the camera. The image grab is synchronous and the function exits when the frame has been grabbed or a time out occurs.
sharpVISION™ Camera 7.4.4. IdtSvImageIsReady [nResult, nIsReady] = sharpML (‘IdtSvImageIsReady’, nCameraId) Inputs nCameraId Specifies a valid camera ID Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) nIsReady It is 0 if image acquisition has not been completed yet, or 1 if the image acquisition has been completed. Remarks this function is used to know whether the image acquisition has been completed and ready to be read.
sharpVISION™ Camera 7.4.5. IdtSvStopAcquire [nResult] = sharpML (‘IdtSvStopAcquire’, nCameraId) Inputs nCameraId Specifies a valid camera ID Outputs nResult Specifies the return error code of the function (0 if the function is successful, otherwise not 0) Remarks This function stops any camera acquisition previously started. If any error occurs during the operation, the routine returns an error code in the nResult variable, otherwise it returns 0.
sharpVISION™ Camera 7.5. How to use the Interface functions 7.5.1. Opening and closing a camera A camera must be opened before using its functions and then it must be closed. To open a specific camera you have to supply to the IdtSvOpenCamera function the ID of that camera. You can also supply 0 to open the first available camera. To obtain the list of all available cameras you may use the IdtSvEnumCameras function. 7.5.2.
sharpVISION™ Camera 7.6. Examples 7.6.1. IdtSvEnumEx This example shows how to obtain the list of all available cameras. 7.6.2. IdtSvInfoEx This example shows how to obtain some information from the camera. 7.6.3. IdtSvReadParmEx This example shows how to read a specific parameter from the camera. 7.6.4. IdtSvSnapEx This example shows how to capture and display a single image. 7.6.5. IdtSvSaveEx This example shows how to capture and save a stream of 5 monochrome images as bitmap files. 7.6.6.
sharpVISION™ Camera 8. Appendix 8.1. Appendix A - Return Codes The following table shows the values of the codes returned by the sharpVISION APIs. The values can be found in the SharpAPI.h header file in the Include subdirectory.
sharpVISION™ Camera 8.2. Appendix B – Information Parameters The following table shows the values and a brief description of the parameters that can be read calling the SvGetCameraInfo routine. The numeric values of the parameters can be found in the SharpAPI.h header file in the Include subdirectory. Parameter Description SVI_CAMERATYPE Camera Model ( see SV_CAM_TYPE in SharpAPI.
sharpVISION™ Camera 8.3. Appendix C – Camera Settings The following table shows the values and a brief description of the parameters that can be read and written in the camera. The numeric values of the parameters can be found in the SharpAPI.h header file in the Include subdirectory.
sharpVISION™ Camera 8.4. Appendix D – Data types This appendix describes the data types defined in the SharpAPI.h header file. 8.4.1. SV_CAM_TYPE The SV_CAM_TYPE type enumerates the camera models. SV_CT_UNKNOWN: Unknown camera model SV_CT_1300DE: sharpVISION 1300-DE. SV_CT_1400DE: sharpVISION 1400-DE. SV_CT_1500EX: sharpVISION 1500-EX. 8.4.2. SV_CCD_TYPE The SV_CAM_TYPE type enumerates the CCD models. SV_CCD_UNKNOWN: unknown CCD type. SV_CCD_ICX085AL: Sony ICX085AL CCD.
sharpVISION™ Camera SV_TM_SOFTWARE: exposure starts on software trigger. 8.4.5. SV_BINNING The SV_BINNING enumerates the binning values: SV_BIN_1X1: binning 1x1. SV_BIN_2X2: binning 2x2. SV_BIN_3X3: binning 3x3. SV_BIN_4X4: binning 4x4. 8.4.6. SV_READOUT_SPEED The SV_READOUT_SPEED enumerates the camera readout frequencies: SV_ROS_20MHZ: 20 MHz. SV_ROS_10MHZ: 10 MHz. SV_ROS_05MHZ: 5 MHz. SV_ROS_02MHZ: 2.5 MHz. 8.4.7.
sharpVISION™ Camera 8.4.10. SV_INFO The SV_INFO enumerates the camera information index. See Appendix B. 8.4.11. SV_PARAM The SV_PARAM enumerates the parameters. See Appendix C.
sharpVISION™ Camera 8.5. Appendix E – Structures This appendix describes the structures defined in the SharpAPI.h header file. 8.5.1. SV_SETTINGS The SV_SETTINGS structure is an opaque structure that contains the all the camera parameters in compact format. The user may access the structure using the SvSetParameter and SvGetParameter routines. typedef struct { unsigned long size; unsigned long _private_data[ 40 ]; } SV_SETTINGS, *PSV_SETTINGS; Members size It specifies the size of the structure.
sharpVISION™ Camera 8.5.2. SV_ENUMITEM The SV_ENUMITEM structure contains information about a camera. It must be used in the camera enumeration procedure with the SvEnumCameras routine. typedef struct { unsigned long cameraId; unsigned long cameraType; unsigned long uniqueId; unsigned long isOpen; unsigned long _reserved[ 10 ]; } SV_ENUMITEM, *PSV_ENUMITEM; Members cameraId It specifies the ID which identifies a camera among others. The user must use this camera id to open the camera with SvOpenCamera.
sharpVISION™ Camera 8.5.3. SV_FRAME The SV_FRAME structure contains information about the image frame to be grabbed. It is used to acquire images in the SvGrabOneFrame or SvQueueOneFrame routines.
sharpVISION™ Camera frameNumber Specifies the rolling frame number. reserved Reserved for future use errorCode Specifies the result code of the Grab operation timeStamp Specifies the exposure time stamp.
sharpVISION™ Camera 8.5.4. SV_AsyncCallback The SV_AsyncCallback is the prototype of the callback function passed to the SvQueueOneFrame or SvQueueCameraSettings routines. The callback is called by the driver when the change settings operation is completed. From the callback body only a subset of the sharpVISION API can be called.