DevWare COM Interface
Overview
The DevWare COM interface lets your application connect to a running DevWare and get live images, access sensor registers, and do other "remote control" of DevWare.
Any programming language or tool that supports COM objects can use the interface, including Visual Basic, C++, C#, Matlab, various scripting tools, etc.
Quick Start
Here is Visual Basic code to connect to a running DevWare and get a live image. First you must add a Reference to DevWare to your project. Select Add Reference under the Project menu. Select the COM tab, and select DevWare 1.0 Type Library. Then you can create a DevWareLib.ImageSource object and use it:
' The variable "devware" encapsulates the connection to DevWare
Dim devware As DevWareLib.ImageSource
Dim image As Object
Dim width, height, depth As Integer
' Connect to DevWare. Only needs to be done once.
devware = New DevWareLib.ImageSource
' Get a processed RGB image
image = devware.GetRgbImage(width, height, depth)
' "image" will be a 2-dimensional array of Integer.
' Each element of the array is the color of the corresponding pixel.
Dim x, y, pixelcolor As Integer
x = …
y = …
pixelcolor = image(x, y)
That's all it takes!
You may need to call devware.Quit() when you are finished.
(If DevWare 1.0 Type Library does not appear in the list, open a Command Prompt window and type devware /register)
DevWare COM API
The functions and properties defined on the DevWare COM Interface are described below.
The data types of function parameters and return values have different names in different languages. This document uses the following conventions.
Byte | Unsigned 8-bit integer |
Short | 16-bit integer |
Word | Unsigned 16-bit integer (Char in VB) |
Int | 32-bit integer |
UInt | Unsigned 32-bit integer |
String | Character string |
Variant | An object that could become different types. Usually it will be an array of some sort. |
Void | To indicate a function that does not return a value. |
An asterisk after the parameter data type means the parameter is passed by reference, and the function will fill in the value. Otherwise the parameter value is provided by you.
Image Capture Functions
You can get the raw data directly from the sensor, or get the final processed RGB image that DevWare displays on the screen. The raw data can be in a variety of possible image data types including Bayer pattern at 8, 10 or 12 bits per pixel, Y-Cb-Cr, JPEG, and different RGB formats.
GetRgbImage()
Definition:
Variant GetRgbImage(Int* Width, Int* Height, Int* Depth)
Summary:
Get a processed RGB image from DevWare's live display. The return value will be a 2-dimensional array of Int values. Each array element is the RGB color, with blue in the low byte, green in bits 15:8, and red in bits 23:16. This is the same format as a Windows COLORREF type.
The function will time out after 15 seconds if no new image is available. To change the timeout use SetOption("COM GetImage Timeout", …). If DevWare is not streaming it will return a 0x0 image.
Parameters:
Width | The function will set to the image width. |
Height | The function will set to the image height. |
Depth | The function will set to 8. |
Returns:
Array of RGB image data | 2-D array of RGB colors |
GetRawImage()
Definition:
Variant GetRawImage(Int* Width, Int* Height, Int* Type, Int* Black, Int* White, Int* Pattern)
Summary:
Get a raw image from DevWare's live display. This is the data as it came out of the sensor. The data type of the image depends on the sensor and the current mode of the sensor.
The function will time out after 15 seconds if no new image is available. To change the timeout use SetOption("COM GetImage Timeout", …). If DevWare is not streaming it will return a 0x0 image.
Parameters:
Width | The function will set to the image width. |
Height | The function will set to the image height. |
Type | The function will set to the image data type. See text below |
Black | The function will set to the black level. See text below. |
White | The function will set to the white level. See text below. |
Pattern | The function will set to the Bayer pattern offset. See text below. |
Returns:
Array of image data | Depends on Type parameter |
The details of the returned array, and the meanings of the Black, White and Pattern parameters depend on the Type.
Usually the image is a 2-dimensonal array, but 24-bit RGB and 48-bit RGB are 3-D arrays with the third dimension being the color component. Compressed formats are 1-dimensional.
Black is the pixel value corresponding to black. For non-Bayer images it's usually 0. White is the white value, usually the maximum value that can be represented with the available bits. For Y-Cb-Cr data Black and White are the luma range, typically either 0-255 or 16-240 or 16-235. For compressed formats the Black and White values returned by this function are meaningless; refer to the specification of the compression format.
Type | Pixel | Image data | Black | White |
|---|---|---|---|---|
1, 3 | Bayer, 8 bits | 2-D array of Byte | Typically 10 | 255 |
2, 4 | Bayer, 10 bits | 2-D array of Short | Typically 42 | 1023 |
5 | Y-Cb-Cr | 2-D array of Short; C in low byte, Y in high byte, Cb first | Typically either 0 or 16 | Typically either 255, 240 or 235 |
6 | RGB 5-6-5 | 2-D array of Short | 0 | 31 |
7 | RGB 5-5-5 | 2-D array of Short | 0 | 31 |
8 | RGB 4-4-4-x | 2-D array of Short | 0 | 15 |
9 | RGB x-4-4-4 | 2-D array of Short | 0 | 15 |
10 | RGB, 24 bits | 3-D array of Byte | 0 | 255 |
11 | RGB, 32 bits | 2-D array of Int | 0 | 255 |
12 | Bayer, 12 bits | 2-D array of Short | Typically 168 | 4095 |
14 | RGB, 48 bits | 3-D array of Word | 0 | 65535 |
15 | JPEG | 1-D array of Byte | 0 (irrelevant) | 255 (irrelevant) |
16 | Bayer, 8 bits, stereo | 2-D array of Byte; pixels alternate between left and right images | Typically 10 | 255 |
17 | PNG | 1-D array of Byte | 0 (irrelevant) | 255 (irrelevant) |
19 | YUV 4:2:0 | 1-D array of Byte | Typically either 0 or 16 | Typically either 255, 240 or 235 |
20 | Bayer 14 | 2-D array of Short | Typically 672 | 16383 |
21 | Bayer 12 HiDy | 2-D array of Short | 0 | 4095 |
22 | Bayer 14 HiDy | 2-D array of Short | 0 | 16383 |
24 | RGB 3-3-2 | 2-D array of Byte | 0 | 7 |
25 | M420 | 1-D array of Byte | Typically either 0 or 16 | Typically either 255, 240 or 235 |
The Pattern parameter defines the Bayer pattern for Bayer images, and is 0 for all other image types. The meaning of the Pattern value is as follows:
0: | G R |
| 1: | R G |
| 2: | B G |
| 3: | G B |
Register Access Functions
These functions access the registers on the sensor.
ReadRegister()
Definition:
Int ReadRegister(String Register, String Bitfield, Int Cached)
Summary:
Read a named register or bitfield using the name defined in the sensor data file.
Parameters:
Register | Register name from sensor data file. |
Bitfield | Bitfield name from sensor data file, or use "" or "*" (asterisk) to read the whole register. |
Cached | If 0 then read from the sensor, if 1 then return the last known value. |
Returns:
Register or bitfield value |
|
WriteRegister()
Definition:
Void WriteRegister(String Register, String Bitfield, Int Value)
Summary:
Write a named register or bitfield using the name defined in the sensor data file.
Parameters:
Register | Register name from sensor data file. |
Bitfield | Bitfield name from sensor data file, or use "" or "*" (asterisk) to write the whole register. |
Value | New value for register or bitfield |
Returns:
None |
|
ReadRegisterAddr()
Definition:
Int ReadRegisterAddr(Int AddrType, Int AddrSpace, Int Addr, Int Bitmask, Int Cached)
Summary:
Read a register given its address. This function can read sensor registers or bitfields that are not defined in the sensor data file.
Parameters:
AddrType | Register address type: |
AddrSpace | Address space or page of the register, if applicable. |
Addr | Register address |
Bitmask | Bitmask of a bitfield if you want to read only a subset of the register. If 0 then returns the whole register. |
Cached | If 0 then read from the sensor, if 1 then return the last known value. |
Returns:
Value | If a bitmask was specified the return value is the value within the bitfield. |
WriteRegisterAddr()
Definition:
Void WriteRegisterAddr(Int AddrType, Int AddrSpace, Int Addr, Int Bitmask, Int Value)
Summary:
Write a register given its address. This function can write sensor registers or bitfields that are not defined in the sensor data file.
Parameters:
AddrType | Register address type: |
AddrSpace | Address space or page of the register, if applicable. |
Addr | Register address |
Bitmask | Bitmask of a bitfield if you want to write only a subset of the register. If 0 then write the whole register. |
Value | Value to write. If a bitfield bitmask was specified, this is the value within the bitfield. |
Returns:
None |
|
PeekRegisters()
Definition:
Variant PeekRegisters(Int BaseAddr, Int Addr, Int Count, Int AddrSize, Int DataSize)
Summary:
This function reads registers from any SHiP or I2C device. It can read up to 64 sequential registers in one operation.
Parameters:
BaseAddr | Device base address |
Addr | Register address |
Count | Number of registers to read |
AddrSize | Width of address in bits. May be 8 or 16 (typically 8) |
DataSize | Width of register data in bits. May be 8 or 16 (typically 16) |
Returns:
Register values | Array of Int |
PokeRegisters()
Definition:
Void PokeRegisters(Int BaseAddr, Int Addr, Int Count, Int AddrSize, Int DataSize, Variant Values)
Summary:
This function writes registers on any SHiP or I2C device. It can write up to 64 sequential registers in one operation.
Parameters:
BaseAddr | Device base address |
Addr | Register address |
Count | Number of registers to write |
AddrSize | Width of address in bits. May be 8 or 16 (typically 8) |
DataSize | Width of register data in bits. May be 8 or 16 (typically 16) |
Values | New register values in an array of Int |
Returns:
None |
|