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.

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:

Returns:

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:

Returns:

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.

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:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

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:

Returns:

BeginAccessRegs()

Definition:
Void BeginAccessRegs(Void)

Summary:
Some device drivers do not support register access simultaneously with image capture. If that is the case with the current device then this function will pause the image acquisition thread in DevWare. DevWare will pause automatically on a register access if it is not already paused, but for better performance when reading or writing many registers at once you should call BeginAccessRegs() first, and then EndAccessRegs() at the end to un-pause. BeginAccessRegs() / EndAccessRegs() calls can be nested. You must call EndAccessRegs() for each call to BeginAccessRegs() or else DevWare image capture will not resume.
The use of Pause(1) / Pause(0) for this purpose is deprecated.

Parameters:

Returns:

EndAccessRegs()

Definition:
Void EndAccessRegs(Void)

Summary:
Resume image capturing if it was paused in a previous call to BeginAccessRegs().

Parameters:

Returns:

Pause()

Definition:
Void Pause(Int PauseState)

Summary:
Pause image acquisition in DevWare. If DevWare was streaming images it will stop getting new images and display the last image it did get. Pause(1) pauses, and Pause(0) un-pauses. Pause(1) / Pause(0) calls can be nested, DevWare will not un-pause until the last pause is undone.
The use of this function to bracket register accesses is deprecated. Use BeginAccessRegs() / EndAccessRegs() instead.

Parameters:

Returns:

Stop()

Definition:
Void Stop(Int StopState)

Summary:
Like Pause(), see above, but puts DevWare in the Stop state, which completely shuts down all worker threads.

Parameters:

Returns:

STATE Variable Functions

These functions give you access to the STATE variables in DevWare, which control the image color processing and display. These are the same settings that are programmed with the STATE= command in DevWare ini files. See the STATE Variables for a complete list of the STATE variables and what they do.
Some STATE variables are Int type and some are String type.

GetState()

Definition:
Int GetState(String StateName)

Summary:
Get the current value of an integer-valued variable.

Parameters:

Returns:

SetState()

Definition:
Void SetState(String StateName, Int Value)

Summary:
Set an integer-valued variable to a new value.

Parameters:

Returns:

GetStateStr()

Definition:
String GetStateStr(String StateName)
Summary:
Get the current value of a string-valued variable.
Parameters:

Returns:

SetStateStr()

Definition:
Void SetStateStr(String StateName, String Value)

Summary:
Set a string-valued variable to a new value.

Parameters:

Returns:

Option Functions

These functions access the settings in the DevWare.ini file. Option settings are other DevWare settings not included in the STATE variables. Most would not be of interest to a program using the COM interface.

You can also store your own settings with these functions. Just supply a name of your own. The setting will end up in the DevWare.ini file.
Option settings can be integer-valued or string-valued.

GetOption()

Definition:
Int GetOption(String Option)

Summary:
Get an integer-valued setting from the DevWare.ini file. Some settings are read-only.
This table shows the read-only settings. See SetOption() for the writeable settings.

Parameters:

Returns:

SetOption()

Definition:
Void SetOption(String Option, Int Value)
Summary:
Change an integer-valued setting to a new value. Some interesting option values:

Parameters:

Returns:

GetOptionStr()

Definition:
String GetOptionStr(String Option)

Summary:
Get a string-valued setting from the DevWare.ini file.
These read-only options return sensor information:

Parameters:

Returns:

SetOptionStr()

Definition:
Void SetOptionStr(String Option, String Value)

Summary:
Change a string-valued setting to a new value. Some useful string-valued options:

Parameters:

Returns:

DevWare Control Functions

Other functions and properties for controlling DevWare are described below.

SensorFile

Definition:
String SensorFile

Summary:
This is the current sensor data file. You can change the value of this property; doing so will cause DevWare to load the new sensor data file. The sensor data file can be a sensor data file or it can be an image file or video file.
Setting this property is equivalent to the File->Open Sensor Data File or File->Open Image File menu on DevWare.

PresetsFile

Definition:
String PresetsFile

Summary:
This is the current Presets file (sensor INI file). You can change the value of this property; doing so will cause DevWare to load the new Presets file. To load a Preset use the LoadPreset() function.
Setting this property is equivalent to the File->Open Presets menu on DevWare.

LoadPreset()

Definition:
Void LoadPreset(String Preset)

Summary:
Load a preset from the current sensor INI file.
These are some standard presets that most Ini files that ship with DevWare contain.

Parameters:

Returns:

LoadPreset2()

Definition:
Int LoadPreset2(String PresetsFile, String Preset, Int SuppressDlgs)

Summary:
Load a preset from the sensor INI file if supplied, else the current sensor INI file. See "LoadPreset()" for a list of some standard presets that most Ini files that ship with DevWare contain.

The SuppressDlgs parameter determines how to handle errors in the preset. To prompt the user with a dialog pass 0. To ignore errors pass 1 (this is equivalent to automatically clicking OK to every error dialog). The function will always return 1 (success) when errors are ignored. To stop execution when an error is encountered pass 2 (this is equivalent to automatically clicking Cancel to the error dialog). In this case the function will return 2 if an error was encountered, or 1 if there were no errors.

Parameters:

Returns:

RunPython()

Definition:
Int RunPython(String Statements)

Summary:
Pass the Python statements to the Python interpreter. The string can contain any number of statements separated by newline characters. This is equivalent to running a Python ini file preset with same contents.

Parameters:

Returns:

GetMouseSelection()

Definition:
Void GetMouseSelection(Int* SelectType, Int* StartX, Int* StartY, Int* EndX, Int* EndY)

Summary:
Get the state of the Mouse Selection box on the left-hand Info panel in DevWare, and the row and column coordinates of the selection.

Parameters:

Returns:

The meanings of the parameter values are as follows:

For the Rectangle selection, note that the start corner is not necessarily the upper left corner. It depends on how the user selected the rectangle. The start corner is where the user began the mouse drag and the end corner is where he ended the mouse drag. To find the upper left corner you must find the minimum of StartX and EndX and the minimum of StartY and EndY. Similarly, you must find the maximums to get the lower right corner.

Also note for the Rectangle selection that the selected area includes the start and end corners. The width of the rectangle is Abs(EndX – StartX) + 1 and the height is Abs(EndY – StartY) + 1. This is different from the Windows RECT structure where the right and bottom sides are one pixel past the edge of the rectangle.

SetMouseSelection()

Definition:
Void SetMouseSelection(Int SelectType, Int StartX, Int StartY, Int EndX, Int EndY)

Summary:
Change the mouse selection type and coordinates. See GetMouseSelection() for the meanings of the parameters.

Parameters:

Returns:

Image()

Definition:
Void Image(Int Width, Int Height, Int Type)

Summary:
Sets DevWare's current image size and type. This is equivalent to the Sensor Output controls on the Options dialog or the IMAGE= command in a .ini file. Note that this does not change anything on the sensor. It may change how the DEMO2 captures the sensor data.

Parameters:

Returns:

You can pass 0 for any parameter and that means to keep it the same. For example, Image(0, 0, 1) changes only the pixel data format, not the image dimensions.

GetGraphData()

Definition:
Variant GetGraphData(Int* Columns, Int* Rows)

Summary:
Gets the data currently being shown on the Analysis Graph window. For the data to be meaningful, the Analysis Graph window should be active and set to an appropriate graph type. To activate the Analysis Graph call SetOption("AnalysisDlg Show", 1). To select the graph type call SetOption("AnalysisDlg Type", …), see above.

The return value will be an array. The dimensions will depend on the graph. If the graph type is Intensity, Cumulative Intensity, Histogram, or Cumulative Histogram the return value will be a 2-D array. The number of columns will be the number of color channels, and the number of rows will be the number of pixels or number of pixel values. If the graph type is Noise, the return value is a 1-D array of the SNR values. The number of columns will be the number of SNR values on the graph, and the number of rows will be 1.

The data type of the returned array is always double-precision floating-point.

Parameters:

Returns:

Command()

Definition:
Void Command(Int Command, Int Param)

Summary:
Post a WM_COMMAND message the DevWare main window. This simulates selecting menus or clicking on toolbar buttons. Some interesting command codes are listed below.

Parameters:

Returns:

Quit()

Definition:
Void Quit(Void)

Summary:
Shut down DevWare. If DevWare was started via COM invocation and you want DevWare to unload completely from memory then call this function.

Parameters:

Returns:

Controlling Still Image Capture

The still image capture and save-to-file mechanism of DevWare is controlled through the SetState(), GetState() SetOption() and SetOptionStr() functions. This section describes in more detail how to automate capturing and saving images with DevWare.

Set Up Mode and Parameters

Use SetState() to set the following still image capture modes and parameters prior to taking a still image.

Set Up File Name and File Formats

Use SetState(), SetOption(), or SetOptionStr() to set the following image file choices. If you set option "Capture FileName Increment" to 1, then the image will be saved automatically when it's captured and so these settings must be done before triggering the capture. Otherwise they can be done after the image is captured, but before it is saved. These settings are equivalent to the selections on the Sensor Control -> Save Options dialog.

SetOption("Capture FileName Increment", …)
1 = Automatically save image to file(s) immediately after image is captured. 0 = Wait for Save command after capturing image. This is equivalent to the "Auto File Name Increment and Save" checkmark on the Sensor Control -> Save Options dialog.
SetOptionStr("Capture File", …)
Set the image filename.

Use SetState() to select the image file formats you want:

Trigger, Save and Dismiss Image Capture

Use SetState("Capture State", …) and GetState("Capture State") to control the still capture operation.

Initiate Capture:
SetState("Capture State", 1)
The function only initiates the capture sequence, it does not wait for the capture to finish. In your program you must wait for the capture to finish; use GetState("Capture State") to find out when the image is ready.

If Still Mode is Zero Shutter Lag then this puts the device and DevWare into the Zero Shutter Lag preview mode. To "close the shutter" and display the captured images do SetState("Capture State", 11).

Query if Capture is ready:
if (GetState("Capture State") = 9) then ...

When Capture State becomes 9 then the image is ready. If Capture State becomes 10 instead, then an error occurred. Wait until Capture State becomes 9 before attempting to save the image.

Save Capture:
SetState("Capture State", 7)
This is equivalent to clicking the Save button the Sensor Control -> Save Options dialog. The image will be saved in the selected format or formats. Capture State will return to 9 when the image is done saving.

Next Picture:
SetState("Capture State", 5)
If you have more than one image, this advances the display to the next image. Capture State will return to 9 when then next image is ready.

Previous Picture:
SetState("Capture State", 6)
If you have more than one image, this go back to the previous image. Capture State will return to 9 when the image is ready.

Dismiss Capture:
SetState("Capture State", 8)
This is equivalent to clicking the Done button on the Sensor Control -> Save Options dialog, or to clicking the Capture toolbar button again to dismiss the captured image and return to live images. Capture State will return to 0 when the live image display is restored.

Data Upload Functions

Other functions that upload data to the camera are described below.

UploadFirmware

Definition:
Int UploadFirmware(String File, Int Burstmode = true)

Summary:
For sensors with a built-in microcontroller, this function uploads firmware patches to the sensor. On certain emulation systems, it can upload the entire firmware. The file must be Motorola S-Record format (normally .s19 extension). After the firmware is uploaded, additional steps will be required to activate the new code; those steps will depend on the specifics of the device and the code that was uploaded.

Parameters:

Returns:

UploadImageFile

Definition:
UInt UploadImageFile(String File, UInt Offset, UInt Length)

Summary:
This function only applies to certain emulation systems that can accept uploaded test images. It uploads binary data from the file to the device using USB bulk transfer protocol. The function does not interpret the data in the file, it only sends it verbatim.

Parameters:

Returns:

Example Code

To use the COM interface you must create an object based on "DevWare 1.0 Type Library". How to do that depends on your development tool.

Visual Basic Example Code

Select Add Reference under the Project menu.
Select the COM tab, and select DevWare 1.0 Type Library.
Create a variable with type DevWareLib.ImageSource.

Dim devware As DevWareLib.ImageSource
devware = New DevWareLib.ImageSource

GetRgbImage()

Dim image As Object
Dim width, height, depth As Integer

image = devware.GetRgbImage(width, height, depth)

Index into the image with the x coordinate first: image(x, y). Each element is an Integer encoding the color of the pixel. You can extract the red, green and blue components by shifting and masking or by converting to a Color object. (Definitions of x and y not shown.)

Dim red, green, blue As Integer
Dim pix As Integer
pix = image(x, y)
red = pix >> 16 And 255
green = pix >> 8 And 255
blue = pix And 255

Alternately, using a Color object:

Dim pix As Color
pix = Color.FromArgb(image(x, y))

The red, green and blue components are pix.R, pix.G and pix.B.

GetRawImage()

Dim image As Object
Dim width, height, type, black, white, pattern As Integer

image = devware.GetRawImage(width, height, type, black, white, pattern)

ReadRegister(), WriteRegister()

Dim value As Integer

Read a whole register:
value = devware.ReadRegister("RED_GAIN_REG", "", 1)

Read a bitfield:
value = devware.ReadRegister("RED_GAIN_REG", "RED_GAIN_VALUE", 1)

Write a bitfield:
devware.WriteRegister("RED_GAIN_REG", "RED_GAIN_VALUE", 16)

ReadRegisterAddr(), WriteRegisterAddr()

Dim value As Integer

Read a whole register: Normal register, page 0, address 0x2D, cached
value = devware.ReadRegisterAddr(0, 0, &H2D, 0, 1)

Read a bitfield: bitfield mask 0x003F
value = devware.ReadRegisterAddr(0, 0, &H2D, &H003F, 1)

Write a whole register: Normal register, page 0, address 0x2D, value 80
devware.WriteRegisterAddr(0, 0, &H2D, 0, 80)

Write a bitfield: bitfield mask 0x003F, value 16
devware.WriteRegisterAddr(0, 0, &H2D, &H003F, 16)

PeekRegisters(), PokeRegisters()

Read device at base address 100, register 16. Register addresses are 8 bits and registers are 16 bits:
Dim value(0) As Integer
value = devware.PeekRegisters(100, 16, 1, 8, 16)

Read four successive registers starting from register 17:
Dim values(3) As Integer
values = devware.PeekRegisters(100, 17, 4, 8, 16)

Write device at base address 100, four successive registers starting from register 56:
Dim values(3) As Integer
values(0) = ..
values(1) = ..
values(2) = ..
values(3) = ..
devware.PokeRegisters(100, 56, 4, 8, 16, values)

GetState(), SetState(), GetStateStr(), SetStateStr()

Dim zoom as Integer
Dim wbcustom as String

zoom = devware.GetState("Display Zoom")
devware.SetState("Display Zoom", 16) ' zoom 2X

wbcustom = devware.GetStateStr("WB Custom")
devware.SetStateStr("WB Custom", "1.45 -0.35 -0.10 -0.35 1.6 -0.25 -0.45 -0.55 2.0")

GetOption(), SetOption(), GetOptionStr(), SetOptionStr()

Dim timeout As Integer
Dim filename As String

timeout = devware.GetOption("COM GetImage Timeout")
devware.SetOption("COM GetImage Timeout", 30000) ' 30 seconds

filename = devware.GetOptionStr("Analysis Data File")
devware.SetOptionStr("Analysis Data File", "C:\5megapix\graphdata.txt")

SensorFile

Get the current sensor file name.
Dim sensor_filename As String
sensor_filename = devware.SensorFile

Force DevWare to use a particular sensor data file:
devware.SensorFile = "sensor_data\MT9V022-REV2.xsdat"

Load a test image into DevWare
devware.SensorFile = "C:\test_images\chart_2800K.tif"

PresetsFile, LoadPreset()

Get the current presets file (sensor ini file).
Dim presets_filename As String
presets_filename = devware.PresetsFile

Switch to another presets file and load a preset.
devware.PresetsFile = "C:\5megapixel\Module_A.ini"
devware.LoadPreset("New Lens Correction")

GetMouseSelection(), SetMouseSelection()

Get the current mouse selection and create a text string describing the selection.
Dim type, startx, starty, endx, endy As Integer
Dim selstr As String
devware.GetMouseSelection(type, startx, starty, endx, endy)

Select Case type
Case 0

selstr = "None"

Case 1

selstr = "Row " + Format(starty)

Case 2

selstr = "Col " + Format(startx)

Case 3

selstr = "Rect " + Format(startx) + "," + Format(starty) + " - "
+ Format(endx) + "," + Format(endy)

Case 4

selstr = "Point " + Format(startx) + "," + Format(starty)

End Select

Set the mouse selection to a particular rectangle.
devware.SetMouseSelection(3, 100, 120, 199, 189)

Command()

Fullscreen mode:
devware.Command(169, 0)