Camelot Cameras - API Explained

EVALUATION KIT (EVK)
CUSTOM CAMERAS FOR MASS PRODUCTION APPLICATIONS
APPLICATION PROGRAM
INTERFACE
i
Contents
©Copyright Imaging Diagnostics 2009-2011
This manual is copyrighted. All rights are reserved and no part of this publication may be
reproduced or transmitted in any form or by any means without prior written consent.
Disclaimer
The information in this manual was accurate and reliable at the time of its release. However, we reserve the right to
change the specifications of the product described in this manual without notice at any time.
Registered Trademarks
All other proprietary names mentioned in this manual are the trademarks of their respective
owners.
Revision 1.7
Software Version 2.1.1423
Print Version 03
August 2011
Ref: ID01411-CAMELOT-EVK-API V2 1 1423 A104.docx
ii
Contents
CONTENTS
PREFACE .................................................................................................................................. VII
ABOUT THIS DOCUMENT .......................................................................................... VII
TARGET AUDIENCE ................................................................................................. VII
ABOUT THIS APPLICATION ....................................................................................... VII
IMPORTANT INFORMATION ...................................................................................... VII
HOW TO CONTACT US ............................................................................................ VIII
CHAPTER 1.
INTRODUCTION .................................................................................................. 1
WHAT'S NEW IN VERSION 2.1.1290 .......................................................................... 2
List of Updated Commands................................................................................... 2
List of New Commands ........................................................................................ 3
CHAPTER 2.
API COMMAND SUMMARY TABLE ....................................................................... 4
CHAPTER 3.
INITIALIZING AND ACCESSING THE CAMERA .................................................. 10
CamEnumCams ................................................................................ 11
CamEnumCamsEx ............................................................................ 11
FillCameraList .................................................................................. 12
FillCameraListEx ............................................................................... 12
CHAPTER 4.
CONTROLLING THE CAMERA ............................................................................. 13
GETTING CAMERA PARAMETERS ............................................................................... 13
GetSensorType / CamGetSensorType .................................................. 13
GetCameraVersionInfo / CamGetCameraVersionInfo ............................. 14
GetCamCaps / CamGetCamCaps ........................................................ 15
OpenCamera / CamOpenCamera ........................................................ 15
GetState / CamGetState .................................................................... 15
CamGetMaxRegion ........................................................................... 16
CONTROLLING THE VIDEO STREAMING ...................................................................... 16
StartVideo / CamStartVideo ............................................................... 16
StartVideoStreaming / CamStartVideoStreaming .................................. 17
SetViewWindow / CamSetViewWindow ................................................ 18
GetViewWindow / CamGetViewWindow ............................................... 19
SetPixelBits / CamSetPixelBits ............................................................ 19
GetPixelBits / CamGetPixelBits ........................................................... 19
Run / CamRun ................................................................................. 19
Pause / CamPause ............................................................................ 20
StopCamera / CamStopCamera .......................................................... 20
CloseCamera / CamCloseCamera ........................................................ 21
ResetCamera / CamResetCamera ....................................................... 21
GetFrameNum / CamGetFrameNum .................................................... 21
iii
Contents
DisplayFrameNumTime / CamDisplayFrameNumTime ............................ 22
GetFPS / CamGetFPS ........................................................................ 22
GetFPSrate / CamGetFPSrate ............................................................. 22
SETTING AND GETTING THE GAIN VALUES .................................................................. 23
SetGainType / CamSetGainType ......................................................... 23
GetGainType / CamGetGainType ........................................................ 23
SetGainProportions / CamSetGainProportions ....................................... 24
EXPOSURE TIME AND SHUTTER CONTROL ................................................................... 25
GetShutterWidth / CamGetShutterWidth ............................................. 25
SetShutterWidth / CamSetShutterWidth .............................................. 25
GetShutterWidthGains / CamGetShutterWidthGains .............................. 26
GetShutterDelay / CamGetShutterDelay .............................................. 26
SetShutterDelay / CamSetShutterDelay .............................................. 26
AdjustFlicker / CamAdjustFlicker ........................................................ 27
SetExposureTime / CamSetExposureTime ............................................ 27
SetFrameRate / CamSetFrameRate ..................................................... 27
GetExposureTime / CamGetExposureTime ........................................... 28
CalcShutWidthForExpTime / CamCalcShutWidthForExpTime ................... 28
UNDERSTANDING THE CAMERA RESOLUTION TYPES ..................................................... 28
GetResolution / CamGetResolution ..................................................... 29
SetResolution / CamSetResolution ...................................................... 29
GetCaptureResolution / CamGetCaptureResolution ............................... 29
SetCaptureResolution / CamSetCaptureResolution ................................ 30
SETTING A REGION OF INTEREST (ROI)/FRAME OF VIEW (FOV) .................................. 30
GetRegion / CamGetRegion ............................................................... 30
SetRegion / CamSetRegion ................................................................ 31
BINNING .............................................................................................................. 31
SetCapBinning / CamSetCapBinning ................................................... 31
GetCapBinning / CamGetCapBinning ................................................... 32
SNAPSHOT MODE ................................................................................................... 32
EnterSnapShotMode / CamEnterSnapShotMode .................................... 32
GetSnapShotMode / CamGetSnapShotMode ......................................... 32
GetSnapShot / CamGetSnapShot........................................................ 33
CAPTURING FRAMES TO FILE.................................................................................... 33
CaptureFrame / CamCaptureFrame ..................................................... 33
CaptureFrameDone / CamCaptureFrameDone ...................................... 34
CaptureFrameDoneEx / CamCaptureFrameDoneEx ............................... 34
CaptureFrameFileBuf / CamCaptureFrameFileBuf .................................. 35
iv
Contents
GetFrameWithFlash / CamGetFrameWithFlash ...................................... 35
CHAPTER 5.
PREVIEW CONTROLS ........................................................................................ 36
GetFlipHorizontal / CamGetFlipHorizontal............................................. 36
SetFlipHorizontal / CamSetFlipHorizontal ............................................. 36
GetFlipVertical / CamGetFlipVertical .................................................... 36
SetFlipVertical / CamSetFlipVertical .................................................... 37
SetRotation / CamSetRotation ............................................................ 37
GetGreyScale / CamGetGreyScale ...................................................... 37
SetGreyScale / CamSetGreyScale ....................................................... 38
SetMonochrome / CamSetMonochrome ............................................... 38
GetMonochrome / CamGetMonochrome ............................................... 38
SetFixBadPixels / CamSetFixBadPixels................................................. 39
CHAPTER 6.
ADVANCED API COMMANDS ............................................................................. 40
SetTestData / CamSetTestData .......................................................... 40
SetLowPowerMode / CamSetLowPowerMode ........................................ 41
SetBadFrameDetection / CamSetBadFrameDetection ............................ 41
SetGetRawFullData / CamSetGetRawFullData ....................................... 41
DESCRIPTION OF THE PLL RATE FOR 5MP CAMERAS .................................................... 42
SetPllRate / CamSetPllRate ................................................................ 42
GetPllRate / CamGetPllRate ............................................................... 42
COMMANDS USING THE GPIO CONNECTOR ON THE CAMERA ......................................... 43
SetPwmTimer / CamSetPwmTimer ...................................................... 43
Using General Purpose Input/Output (GPIO) ......................................................... 44
GetGPIO / CamGetGPIO .................................................................... 44
SetGPIO / CamSetGPIO ..................................................................... 44
GetGPIO_Pins / CamGetGPIO_Pins ..................................................... 45
SetGPIO_Pins / CamSetGPIO_Pins ...................................................... 45
CheckLeds / CamCheckLeds ............................................................... 45
SETTING/GETTING SENSOR REGISTER VALUES ........................................................... 46
GetRegVal / CamGetRegVal ............................................................... 46
SetRegVal / CamSetRegVal ................................................................ 46
GetRegValues / CamGetRegValues...................................................... 47
SetRegValues / CamSetRegValues ...................................................... 47
LOOK-UP TABLE (LUT) ........................................................................................... 48
UploadLUT / CamUploadLUT............................................................... 48
SetLUT / CamSetLUT ........................................................................ 48
CHAPTER 7.
IMAGE PROCESSING COMMANDS ..................................................................... 49
COLOR CORRECTION OPTIONS – PROCESSING ON PC .................................................. 49
Histogram Stretching......................................................................................... 49
v
Contents
Histogram Equalization ...................................................................................... 49
Color Correction (CCM) ...................................................................................... 49
SetColorCorr / CamSetColorCorr ........................................................ 50
AWB (AUTOMATIC WHITE BALANCE) ....................................................................... 50
AGC (AUTOMATIC GAIN CONTROL) .......................................................................... 50
SetAGC_AWB / CamSetAGC_AWB ...................................................... 52
SingleFrameAWB / CamSingleFrameAWB ............................................ 52
PC_AWB / CamPC_AWB .................................................................... 52
CHAPTER 8.
CONFIGURING THE CAMELOT IP CAMERAS ...................................................... 53
SetIpConfig / CamSetIpConfig............................................................ 53
GetIpConfig / CamGetIpConfig ........................................................... 54
SetIpDefaultConfig / CamSetIpDefaultConfig ....................................... 54
GetIpDefaultConfig / CamGetIpDefaultConfig ....................................... 54
SetPortRange / CamSetPortRange ...................................................... 55
CHAPTER 9.
USING THE CALLBACK COMMANDS .................................................................. 56
SetDataCBPtr / CamSetDataCBPtr ...................................................... 57
SetRawFrameDataCB / CamSetRawFrameDataCB ................................. 58
SetRawFullFrameCB / CamSetRawFullFrameCB .................................... 58
SetRGBFrameDataCB / CamSetRGBFrameDataCB ................................. 58
SaveRawFrameToFileBuf / CamSaveRawFrameToFileBuf ........................ 59
SetMsgCBPtr .................................................................................... 59
CHAPTER 10. USING DEBUGPRINT ......................................................................................... 60
DebugPrint ...................................................................................... 60
GetLogs / CamGetLogs ...................................................................... 61
CHAPTER 11. UPGRADING TO THE LATEST SOFTWARE VERSION .......................................... 62
UpdateFW / CamUpdateFW ................................................................ 63
APPENDIX A MOLEX CONNECTOR TABLE ............................................................................... 64
MOLEX CONNECTOR ............................................................................................... 64
vi
PREFACE
About this Document
This document is the
Camelot and IDM Camera Series’ Evaluation Kit (EVK) API.
Target Audience
This document is meant for application programmers who wish to integrate
Camelot and IDM-500 series cameras into 3rd party applications.
About this Application
The CamelotView Sample Application was written to demonstrate to
programmers how to build applications using the Camelot.dll functional API.
This API gives the programmer full control over Camelot and IDM-500
Series Cameras.
All C/C++ applications must include the following files:

hostCamApi.h – a file containing definitions used by the camera, the API
and the sample applications

CamelotDll.h – a list of API commands in the Camelot.dll that can be
accessed by your application.
All C# applications must include the following files:

hostCamApi.cs – a file containing definitions used by the camera, the
API and the sample applications

CamelotDll.cs – a list of API commands in the Camelot.dll that can be
accessed by your application.
The final RGB images (BMP) from the CamelotDll (CamelotView) are in 32-bit
format.
If you want to use the DirectShow version, you must first compile the
Baseclasses (Debug and Release) on your working computer and have
CamelotFilter.ax in your $(System) directory.
See DirectShow documentation for more details.
Important Information
NOTE
Important information is shown as notes.
WARNING
Important Safety information is displayed in this format
vii
Camelot Cameras - API Explained
Preface
How to Contact Us
Imaging Diagnostics invites comments and feedback on this and all of our
products and documentation. Please contact us at one of the email addresses
below.
Website
http://www.imagine2d.com/
Support
support@imagine2d.com
Sales
sales@imagine2d.com
viii
Chapter 1
INTRODUCTION
Camelot is a family of digital cameras for machine vision applications. Using a
fast USB2 connection and an embedded digital signal processor, Camelot
cameras are capable of performing advanced image processing algorithms in the
camera and buffering images internally. This capability decreases the
camera/host bandwidth requirement significantly. These cameras are intended
for medical and industrial applications requiring superior image quality and high
performance.
IMPORTANT NOTE
You can download the latest version of the software from our website.
See Upgrading to the Latest Software Version on page 62.
Downloads Contain:
CamelotView.zip – Contains the latest, updated sources of the Sample
applications.
Camelot.dll – A library of commands that access and operate the camera
CamelotView.exe – An executable that uses the Camelot.dll and when
running must be in the same directory.
CamelotFilter.ax – a DirectShow filter containing commands that access
and communicate with the camera. This file must be placed in the
X:\Windows\System32 folder. Where X:\ is your system disk drive.
Camelot_FW.ldr – This is the loader file with the new/updated code for the
camera. This file must be loaded using the Sample Application or by calling
the API command UpdateFW and supplying the path to the file.
See Upgrading to the Latest Software Version on page 62.
1
Camelot Cameras - API Explained
Chapter 1 - Introduction
What's New in Version 2.1.1290
Please read the section About this Application in the Preface above for
instructions about writing C#/.NET applications.
Product Hardware and Firmware versions are updated and stored as strings
Single Frame AWB algorithm and PC_AWB added.
10Mp resolution changes coded into dll, snapshot mode
Better StartCamera/StopCamera/StartCamera sequence – no memory loss
and more efficient
If frame resolution or ROI would mean an odd value for either Frame Width
or Frame Height, odd value is changed to an even value
Added Get… commands to additional Set… commands.
If streaming data that is > 8bit - simple gamma conversion is performed
before display
Snapshot serialization - sets of pictures are captured
High quality BMP captured correctly while streaming display is regular BMP
quality
2 new FRAME_TYPEs – ACK_REQUEST and BAYER_RAW_CMP – 2 pixels of
12-bit data compressed into 3 bytes
new SAVE_FRAME_TYPE - BMP_NI - RGB24 - no header and non-colorinterleaved (RR..R, GG..G, BB..B)
Added commands for writing and reading to flash
FindIpCameras – searches over multiple gateways
List of Updated Commands
Updated Commands
Changes
CaptureFrameFileBuf
For this composite command to work, the following
structures must be defined. All the parameters needed
for saving the video are included.
CamEnumCamsEx
Same as CamEnumCams (above) with additional
parameters:

Page
35
specify whether USB or IP cameras are being
searched

whether a camera with a specific serial number is
requested
For IP cameras, the IP address from which the IP
broadcast message is sent can be specified. If not
specified, Broadcast message is sent from
12
INADDR_BROADCAST (255.255.255.255).
FillCameraListEx
Same as FillCameraList (above) with additional
parameters:

specify whether USB or IP cameras are being
searched

whether a camera with a specific serial number is
requested
For IP cameras, the IP address from which the IP
broadcast message is sent can be specified. If not
specified, Broadcast message is sent from
INADDR_BROADCAST (255.255.255.255).
2
12
Camelot Cameras - API Explained
Chapter 1 - Introduction
List of New Commands
New Commands
Description
Page
CaptureFrameDoneEx
Returns TRUE when the amount of frames specified has
been captured.
34
GetIpDefaultConfig
Get IP default configurations – similar to GetIPConfig – but
refers to default configurations.
54
SetIpDefaultConfig
Set IP default configurations – similar to SetIPConfig – but
refers to default configurations.
54
SetPortRange
Set range of ports to be used by IP application.
55
SetGainProportions
The three R G B parameters are set as ratios between the
gains – not by absolute values. When the R gain is
changed, G and B are changed proportionately.
Until a subsequent call, the gains will have the ratio
1024:((G*1024)/R):((B*1024)/R). Integer math is used in
the scaling.
3
24
Chapter 2
API COMMAND SUMMARY TABLE
NOTE
All of the commands are listed below in alphabetical order.
Command
Description
AdjustFlicker
Adjusts the Shutter
Width to avoid the 50Hz
or 60Hz flicker
experienced when using
indoor lighting.
CalcShutWidthForExpTime
Returns the shutter
width that should be
programmed in order to
get the exposure time
(in microseconds)
indicated.
CamEnumCams
Searches for all
Camelot and IDM-500
cameras connected to
your PC USB port or on
the LAN. After calling
this command the
cameras found can be
accessed using the
Cam… version of the
API commands. The
camera number is also
provided, zero-based,
as the first parameter.
4
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
CamEnumCamsEx
Same as
CamEnumCams (above)
with additional
parameters:

specify whether
USB or IP
cameras are
being searched

whether a
camera with a
specific serial
number is
requested
For IP cameras, the IP
address from which the
IP broadcast message is
sent can be specified.
If not specified,
Broadcast message is
sent from
INADDR_BROADCAST
(255.255.255.255).
CamGetMaxRegion
Gets the maximum
coordinates of the
region of interest, ROI,
that the camera is
capable of capturing.
When accessing these
commands through
interface and camera’s
pointer, these values
are in the CamCaps
(CAMERA_CAP_API)
struct.
CaptureFrame
Captures the next
frame from the camera
and saves it as a RAW,
BMP or JPEG image. If
in Snapshot mode, will
capture the next frame
after the GetSnapShot()
command is called.
CaptureFrameDone
Used to poll if frame
was captured. After
calling CaptureFrame.
This function will return
whether or not the
frame was saved.
CaptureFrameDoneEx
Returns TRUE when the
amount of frames
specified has been
captured.
CaptureFrameFileBuf
For this composite
command to work, the
following structures
must be defined. All
the parameters needed
for saving the video are
included.
5
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
CheckLeds
Checks whether the
three external LEDs
(optionally provided
with the camera) are
functioning.
To utilize this
command a separate
control board is
required.
This command is not
supported in IDM-500
cameras.
Closes all connections
to the selected camera
and releases all buffers
used for video capture.
CloseCamera
Prints a message to a
debug window, if open,
while in DEBUG mode.
DebugPrint
DisplayFrameNumTime
Displays the current
frame and time on the
frames output from
camera.
This command is not
supported in IDM-500
cameras.
EnterSnapShotMode
Enters or leaves
Snapshot Mode. When
in Snapshot Mode the
camera stops capturing
and streaming video
until a trigger is set.
When entering or
leaving Snapshot Mode,
the FPS calculations
start from 0.0 Fps.
FillCameraList
Searches for Camelot
cameras connected to
your PC USB port or on
the LAN.
After calling this
command, use the
pointer to the camera
(pCam in the
CAMERA_CAP_API
structure) to access the
API commands.
6
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
FillCameraListEx
Same as FillCameraList
(above) with additional
parameters:

specify whether
USB or IP
cameras are
being searched

whether a
camera with a
specific serial
number is
requested
For IP cameras, the IP
address from which the
IP broadcast message is
sent can be specified.
If not specified,
Broadcast message is
sent from
INADDR_BROADCAST
(255.255.255.255).
GetCamCaps
Returns a structure
containing some of the
camera’s capabilities.
GetCameraVersionInfo
Gets the camera’s
version numbers – HW,
FW see also Output
parameters.
GetCapBinning
Returns whether
binning has been
selected.
GetCaptureResolution
Returns the current
camera output
resolution.
GetExposureTime
Gets the actual
exposure time (in
microseconds) for each
frame according to the
ShutterWidth and
ShutterDelay and
capture resolution.
GetFlipHorizontal
Returns whether the
picture is flipped
horizontally.
GetFlipVertical
Returns whether the
picture is flipped
vertically.
GetFPS
Outputs the frames per
second, FPS, of the
selected camera. This is
a dynamically changing
statistic and depends
on camera resolution,
shutter width, gain and
binning.
7
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
GetFPSrate
Outputs the Bit Rate of
the selected camera.
This is a dynamically
changing statistic and
depends on camera
resolution, shutter
width, gain and binning.
GetFrameNum
Outputs the current
frame number being
captured from the
camera. This is a
sequential number that
starts at zero (0) every
time streaming starts
GetFrameWithFlash
While streaming video,
two frames are
captured with flash (in
the first the flash may
be weaker) and
streaming continues.
The flash must be
defined using the PWM
controls, and
EnableTimers set to 0
(flash for frame) See
SetPwmTimer.
GetGainType
Returns with the value
of the gain according to
the camera type.
GetGPIO
Gets the current state
and values of up to 9
GPIO (general purpose
input/output) pins that
are reserved for end
user use.
GetGPIO_Pins
Gets the current values
of the up to 20 GPIO,
general purpose
input/output, pins that
are reserved for
application use. Each
bit represents a pin and
can either be high (1)
or low (0).
8
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
Returns whether the
picture is shown in
greyscale.
Puts a green crosshair in the middle of the screen. This is helpful
for focusing and
centering camera on specific points of an object.
SetCrosshair / CamSetCrosshair
Description
Syntax
SetCrosshair(bool crosshair)
CamSetCrosshair(int nCamNum, bool crosshair)
Parameters
Input
Output
nCamNum
Camera number
crosshair
True – displays green crosshair
False – no crosshair in display
None
GetGreyScale
GetIpConfig
Gets IP configuration
according to the
NET_CONFIG_INFO
structure above.
GetIpDefaultConfig
Get IP default
configurations – similar
to GetIPConfig – but
refers to default
configurations.
GetLogs
Gets log messages
saved in the camera for
debugging purposes.
These messages are
sent to a separate
DebugPrint screen (if
opened) and can be
used to debug
applications. See Using
DebugPrint on page 60.
This command is not
supported in IDM500 cameras.
GetMonochrome
Returns whether sensor
outputs monochrome
(greyscale) data.
GetPixelBits
Returns how many bits
per pixel are being
captured by camera.
GetPllRate
Gets the camera’s PLL
(internal clock) rate.
This option is only
supported by the
5Mp models.
GetRegion
Gets the coordinates of
the region of interest,
ROI, programmed in
the registers of the
camera.
9
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
GetRegVal
Returns value of
specified register.
Register addresses and
values are in HEX
notation. If fails
returns -1.
GetRegValues
Outputs register values
to a REG_LIST_API
structure as defined in
hostCamApi.h.
GetResolution
Returns the current
resolution of the
Preview Screen.
GetSensorType
Returns the type of
sensor present in the
camera. The type may
be 1.3, 3, 5, 10
Megapixel, VGA or
WVGA sensor according
to Table 1 below.
GetShutterDelay
Returns the sensor
shutter delay. This
value is used for
controlling exposure
time and to avoid any
50Hz or 60Hz flicker.
GetShutterWidth
Returns the sensor’s
shutter width. This
value controls the time
of exposure for each
new frame captured
GetShutterWidthGains
Gets the sensor’s
current shutter width
and color gain values.
GetSnapShot
Imitates the external
trigger and instructs the
camera to capture one
frame and send it to the
PC.
GetSnapShotMode
Returns whether
camera is in Snapshot
Mode.
GetState
Returns the current
state of the camera
GetViewWindow
Returns the HANDLE of
the preview window
which was set in the
Cam/SetViewWindow
command.
OpenCamera
Camera streaming is
stopped, the sensor is
reset and the default
parameters are loaded.
The camera sensor is
reset to default values
as if powered up.
10
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
Pause
Pause the preview of
the camera output.
Streaming continues,
and callback
commands, if set, are
accessible.
PC_AWB
Request the camera to
perform the Automatic
White Balance, AWB,
algorithm on the frame
on the PC. The new,
calculated gain values
will be sent to the
camera.
ResetCamera
Closes all connections
to the selected camera,
releases all buffers used
for video capture and
resets the camera.
Run
When called, video is
streamed from the
camera. If a window
has been defined (in
the SetVideoWindow
command), the video
will be displayed.
SaveRawFrameToFileBuf
Saves a captured Raw
image to a file in RAW,
BMP or JPG format.
This function can only
be used within the
RawFrame or
RawFullFrame
callbacks.
SetAGC_AWB
Sets if a camera should
perform Automatic Gain
Control, AGC, and/or
Automatic White
Balance, AWB, on data.
Each of these
commands dynamically
changes gain values
and shutter width.
When AGC and AWB
are disabled, the last,
calculated, shutter
width and gain values
remain.
This command is not
supported in IDM500 cameras.
SetBadFrameDetection
Specifies whether the
camera should detect
and correct Bad
Frames.
11
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SetCapBinning
Sets whether binning
will be used by the
sensor for video output.
Only available if HALF
or QUARTER resolution
is selected.
SetCaptureResolution
Sets the camera output
resolution. Video
streaming is stopped
before resolution is set.
SetColorCorr
Sets the type of color
correction to be
implemented on the PC
for all incoming frames.
If using Color
Correction, default
values can be found in
the cc.ini file.
SetDataCBPtr
Sets the callback
function that is called
every time a new frame
is received, if specified.
SetExposureTime
Sets the exposure time,
in microseconds, for
each frame. If the value
entered is lower than
the minimum value for
this camera, the
camera operates at the
minimum value.
SetFixBadPixels
Sets whether “bad”
pixels should be fixed.
“Bad pixels” are defined
by one or two wrong
colored pixels in an
area of a known
hue/color. The “bad
pixels” originate from
the sensor and are
fixed on the PC.
Only if width and height
are at least 4 can this
be performed. The
“bad pixels” are fixed in
stages, so it takes a
few seconds to fix all of
them on frames of 5Mp.
SetFlipHorizontal
Sets whether the
picture should be
flipped horizontally.
SetFlipVertical
Sets whether the
picture should be
flipped vertically.
12
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SetFrameRate
Sets the frame rate of
the sensor output. The
vertical blanking
register is set so that
the frame rate is
controlled. If the frame
rate given is higher
than the sensor can
deliver the sensor
output is limited to the
maximum output
possible. If the
requested frame rate is
lower than the vertical
blanking can control,
then the frame rate will
be as low as the highest
vertical blanking value
allows.
The three R G B
parameters are set as
ratios between the
gains – not by absolute
values. When the R
gain is changed, G and
B are changed
proportionately.
SetGainProportions
Until a subsequent call,
the gains will have the
ratio
1024:((G*1024)/R):((B
*1024)/R). Integer
math is used in the
scaling.
Sets sensor’s gain
according to the type
specified.
SetGainType
13
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SetGetRawFullData
Sets mode for getting
RAW frames. For 5Mp
camera only: If a 12-bit
RAW frame is required,
puts the camera into
48MHz mode (using the
SetPllRate command)
before requesting the
RAW frame.
This command is not
supported by the
IDM-500 cameras.
Explanation of the
PLL Rate for 5Mp
cameras
We recommend using
as low a PLL rate as
possible for the the
frame rate required.
The fewer frames the
sensor captures, the
more time the DSP has
for processing them.
Since the USB
bandwidth doesn’t allow
for more than 8.5 fps,
there is no reason for
the sensor to output
14fps.
SetGPIO
Sets the current state
and values of up to 9
GPIO (general purpose
input/output) pins that
are reserved for end
user use.
SetGPIO_Pins
Sets the current values
of the up to 20 GPIO,
general purpose
input/output, pins that
are reserved for
application use. Each
bit represents a pin and
can either be high (1)
or low(0).
SetGreyScale
Sets whether the
picture should be
shown using greyscale.
SetIpConfig
Sets IP configuration
according to the
NET_CONFIG_INFO
structure above.
SetIpDefaultConfig
Set IP default
configurations – similar
to SetIPConfig – but
refers to default
configurations.
14
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SetLowPowerMode
Specifies whether the
camera should enter
Low Power mode. If
video is now streaming
the camera will enter
Low Power mode when
streaming stops.
This command is not
supported in any of
the Camelot models
or IDM-500 cameras.
SetLUT
Can be set only after a
LUT is successfully
uploaded. Indicates to
camera that all data
should be translated
with the uploaded LUT
(Look up Table).
This command is not
supported in IDM500 cameras.
SetMonochrome
Sets whether sensor
outputs monochrome
(greyscale) data. This
information is used by
the Display thread
when converting the
image from 8-bit Bayer
format to RGB (24-bit
or 32-bit).
SetMsgCBPtr
Sets pointer to an error
message callback
function. The dll
functions
FillCameraList, and
AccessCamera also
send this pointer.
SetPixelBits
Defines how many bits
per pixel will be
captured by camera.
This must be set when
camera is initialized but
not running. Default if
not set is 8 bits per
pixel.
SetPllRate
Sets the camera’s PLL
(internal clock) rate.
Video streaming is
stopped before PLL is
set. Default: 60MHz.
This option is only
supported by the
5Mp models.
SetPortRange
Set range of ports to be
used by IP application.
15
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SetPwmTimer
Sets three PWM (pulse
width modulation)
timers which you can
attach to peripherals
(LEDs, etc.) that need
PWM controlled current
source. The period is
the overall cycle, while
the width is the
duration of the period
(duty cycle) where the
signal is high. The
width must be less or
equal to the period for
each timer. The timers
(TMR1, TMR2 and
TMR3) are started
simultaneously and
therefore synchronized.
This command is not
supported in IDM500 cameras.
SetRawFrameDataCB
Sets whether a callback
function should be
called for each raw
frame received.
SetRawFullFrameCB
Sets whether a callback
function should be
called for each raw Full
frame received (as a
result of the
SetGetRawFullData
function on page 41).
SetRegion
Sets the region of
interest, ROI, to be
output by the camera.
The width and height
must be even numbers.
Video streaming is
stopped before region is
set.
SetRegVal
Sets specified register
value.
SetRegValues
Sets register values
according to list
supplied in structure.
Register addresses and
values are in HEX
notation.
SetResolution
Sets the resolution used
for the Preview Screen.
The FULL parameter (0)
gives the maximum
sensor output from the
camera. All other
resolutions are subsets
of this FULL output.
16
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SetRGBFrameDataCB
Sets whether a callback
function should be
called after each raw
frame has been
processed into an RGB
frame.
SetRotation
Sets the angle in
degrees (0, 90, 180
and 270) for rotating
the image.
SetShutterDelay
Sets the sensor shutter
delay This value is used
for controlling exposure
time and to avoid any
50Hz or 60Hz flicker.
SetShutterWidth
Sets the sensor shutter
width. This value
controls the time of
exposure for each new
frame captured
SetTestData
Specifies whether the
camera should output
Test Data or captured
video images. This
option is provided for
developers to check if
the data received is
actually the data sent
and other sensor
independent features.
WVGA, 1.3Mp and 3Mp
cameras have only 1
option – to choose a
value that is output for
even columns, and its
complement value - for
odd columns. For
example, 0x12
becomes 0xED.
The 5Mp and 10Mp
cameras have other
options for creating
patterns.
SetViewWindow
Provides the dll with a
HANDLE to a window to
be used for previewing
the video. If video
preview is required, this
command must be
called before
Run/CamRun.
17
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
SingleFrameAWB
Request the camera to
perform the Automatic
White Balance, AWB,
algorithm on a single
frame. AWB will be
performed a specified
number of times and
then cease.
This command is not
supported in IDM-500
cameras.
StartVideo
Starts a camera that
has already been
initialized. When called,
video is streamed from
the camera and
displayed in a separate
Preview window.
Initial camera settings
can be sent as
parameters.
StartVideoStreaming
Starts a video
streaming from a
camera that has
already been initialized.
When called, video is
streamed from the
camera and displayed
(if requested) in a
separate Preview
Window. Many capture
and preview settings
can be sent as
parameters using
structs.
StopCamera
Stops a running camera
but keeps it initialized.
UpdateFW
Updates the camera
Firmware. Video
streaming is stopped
before firmware is
updated.
18
Camelot Cameras - API Explained
Chapter 2 - API Command Summary Table
Command
Description
UploadLUT
Uploads a Look-up
Table, LUT, for
translating raw pixel
values in the camera
before being outputt.
The LUT can translate
from 8-bit, 10-bit or
12-bit data to 8-bit, 10bit or 12-bit output. In
this version only
translations to 8-bit
data are supported.
After the LUT is
successfully loaded,
SetLUT may be called in
order to start using the
LUT for new data.
Not all of the
Camelot models
support this
command. This
command is not
supported in the
IDM-500 series.
19
Chapter 3
INITIALIZING AND ACCESSING THE CAMERA
This chapter describes the commands for initializing and accessing the camera.
Examples of all the commands are provided in the sample application. The files
CamelotDll.h and hostCamApi.h for C++, or CamelotDll.cs and
hostCamApi.cs for C#, must be included in each project.
To use these commands, the dll library must be loaded and each command
assigned a pointer for access. The code below is written in C++ but is similar for
other languages.

To initialize and access the camera:
a. Load the dll library.
HINSTANCE hDll; // handle to Dll with commands for Camelot cameras
hDll = LoadLibrary(TEXT("Camelot.dll"));
b. Get address for the CamEnumCameras command:
typedef int (__stdcall * FARPROC_0_PARAM)(void);
FARPROC_0_PARAM
pfnEnumCameras;
pfnEnumCameras =
(FARPROC_0_PARAM)GetProcAddress(hDll, "CamEnumCameras");
int numCamFound = lpfnEnumCameras();
c. After calling CamEnumCameras() (by calling its pointer
lpfnEnumCameras()), the number of cameras found is returned and the dll
maintains a list of cameras. Each camera can now be accessed by calling one
of the Cam… commands with the camera number (zero based) as the first
parameter. Pointers to each of the Cam… commands must be individually
accessed (by calling GetProcAddress).
OR
a. Get address for the FillCameraList command and use the pointer passed
back in the CAMERA_CAP_API for accessing the camera’s interface
commands:
typedef int(__cdecl * FARPROC_2_PTR)(CAMERA_CAP_API *camArray,
funcMsgPtr funcMsgCb);
// pointer to exported command
FARPROC_2_PTR
pfnFillCameraList;
pfnFillCameraList = FARPROC_2_PTR)GetProcAddress(hDll,"FillCameraList");
b. Both funcMsgPtr funcMsgCb and CAMERA_CAP_API are defined in the
hostCamApi.h file.
funcMsgPtr funcMsgCb – a pointer to a command that will be called on
error. It can contain information and recovery code.
CAMERA_CAP_API is a structure for each camera with specific identifying
information and a pointer to the camera (pCam). The pointer can be used to
access the camera interface commands (see next chapter):
#define SENSOR_DESC_LEN
30
#define CAM_ID_LEN
20
20
Camelot Cameras - API Explained
Chapter 3 - Initializing and Accessing the Camera
typedef struct
{
unsigned int SensorType;
char
Desc[SENSOR_DESC_LEN];
unsigned int CommType;
// USB or TCP - COMM_TYPE
int
fTransportStarted;
int
reserved;
int
Width;
// maximum width
int
Height;
// maximum height
int
ActiveStartX;
// X column start
int
ActiveStartY;
// Y row start
char
CameraID[CAM_ID_LEN]; // camera’s unique serial number
unsigned int pCam;
// pointer to IBDRCamera interface
char
Color;
// 1-color, 0-monochrome
char
ProductID[CAM_ID_LEN];
// ID product number
char
FirmwareVersion[CAM_ID_LEN]; // FW version burned when shipped
char
HardwareVersion[CAM_ID_LEN]; // HW version
} CAMERA_CAP_API;
CamEnumCams
Description
Searches for all Camelot and IDM-500 cameras connected to your PC USB port or
on the LAN. After calling this command the cameras found can be accessed
using the Cam… version of the API commands. The camera number is also
provided, zero-based, as the first parameter.
Syntax
int CamEnumCams(void)
Parameters
Input
Return Values
None
int
number of cameras found
CamEnumCamsEx
Description
Same as CamEnumCams (above) with additional parameters:



specify whether USB or IP cameras are being searched
whether a camera with a specific serial number is requested
For IP cameras, the IP address from which the IP broadcast message is
sent can be specified. If not specified, Broadcast message is sent from
INADDR_BROADCAST (255.255.255.255).
int CamEnumCamerasEx(TRANSPORT_TYPE TransportType, char
*SerialNumber, char *szBroadcastIP, char *szGateway, int
CamerasPerIP,)
Syntax
Parameters
Input
TransportType
TT_USB or TT_IP
SerialNumber
Specify serial number of camera to be found
szBroadcastIP
For IP cameras, address for Broadcast message used
for searching cameras on LAN
szGateway
For IP cameras, gateway used for searching cameras
on LAN
CamerasPerIP
How many cameras are allowed with the same IP
address (should be 1, unless special proprietary board
21
Camelot Cameras - API Explained
Chapter 3 - Initializing and Accessing the Camera
is used)
Return Values
int
number of cameras found
FillCameraList
Description
Searches for Camelot cameras connected to your PC USB port or on the LAN.
After calling this command, use the pointer to the camera (pCam in the
CAMERA_CAP_API structure) to access the API commands.
Syntax
int FillCameraList(CAMERA_CAP_API *camArray, funcMsgPtr
funcMsgCb)
Parameters
Input
camArray
pointer to an empty array of MAX_CAM_NUM
elements. See above for build of CAMERA_CAP_API
structure. Array elements will be filled in for each
camera found.
funcMsgCb
pointer to a Callback command with Error messages
that will be called from the dll if an error occurs.
Recovery code can be inserted if needed.
int
number of cameras found
Output
Return Values
FillCameraListEx
Description
Same as FillCameraList (above) with additional parameters:



specify whether USB or IP cameras are being searched
whether a camera with a specific serial number is requested
For IP cameras, the IP address from which the IP broadcast message is
sent can be specified. If not specified, Broadcast message is sent from
INADDR_BROADCAST (255.255.255.255).
int FillCameraListEx(TRANSPORT_TYPE TransportType, char
*SerialNumber, char *szBroadcastIP, char *szGateway,
CAMERA_CAP_API *camArray, int CamerasPerIP, funcMsgPtr
funcMsgCb)
Syntax
Parameters
Input
TransportType
TT_USB or TT_IP
SerialNumber
Specify serial number of camera to be found
szBroadcastIP
For IP cameras, address for Broadcast message used
for searching cameras on LAN
szGateway
For IP cameras, specific Gateway used for searching
cameras on LAN
camArray
pointer to an empty array of MAX_CAM_NUM
elements. See above for build of CAMERA_CAP_API
structure. Array elements will be filled in for each
camera found.
CamerasPerIP
How many cameras are allowed with the same IP
address (should be 1, unless special proprietary board
is used)
funcMsgCb
pointer to a Callback command with Error messages
22
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
that will be called from the dll if an error occurs.
Recovery code can be inserted if needed.
Output
Return Values
int
number of cameras found
Chapter 4
Controlling the Camera
There are two ways of accessing a camera and sending it commands:
1. Calling CamEnumCams, described in the previous chapter.
Getting the number of cameras and then accessing each of the Cam…
commands individually using the camera number (zero based) as the first
parameter. In order to do this, all the pointers to the dll commands should
be accessed using the GetProcAddress command. This method is
demonstrated in the SimpleCamelot sample application.
2. Calling FillCameraList (described in previous chapter) with a pointer to an
empty array of MAX_CAM_NUM cameras the default of 30 is defined in
hostCamApi.h.
The command will return as many cameras found and the array updated with
all camera information as well as a pointer to each camera.
The pointer should be shown as described below:
int numCamFound = lpfnFillCameraList(g_CameraCap,
MessageCallback);
piBDR[camNum] = (IBDRCamera *)g_CameraCap[camNum].pCam;
Interface commands should be accessed by:
piBDR[camNum]->Command(parameters);
Allmost all of these function calls are demonstrated in the
CamelotView Sample Application.
Getting Camera Parameters
GetSensorType / CamGetSensorType
Description
Returns the type of sensor present in the camera. The type may be 1.3, 3, 5, 10
Megapixel, VGA or WVGA sensor according to Table 1 below.
Syntax
GetSensorType (int *pnSensorType)
CamGetSensorType(int nCamNum, int *pnSensorType)
Parameters
Input
nCamNum
Number of camera
Output
pnSensorType
SENSOR_UNKNOWN
SENSOR_WVGA
SENSOR_OVT_VGA
23
0
3
4
WVGA
Omni VGA sensor (IDM-500)
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
SENSOR_1300
SENSOR_3000
SENSOR_5000
SENSOR_10000
13
30
50
100
1.3 Megapixel
3 Megapixel
5 Megapixel
10 Megapixel
Table 1: Types of Cameras and their Resolutions
Width
Height
Total Raw
Pixels
Full
640
480
307,200
Half
320
240
76,800
Quarter
160
120
19,200
Resolution
Y Row
Start
X Column
Start
4
1
12
20
20
32
54
16
8
112
VGA
WVGA
Full
752
480
360,960
Half
376
240
90,240
Quarter
188
120
22,560
1.3 Mp
Full
1280
1024
1,310,720
Half
640
512
327,680
Quarter
320
256
81,920
3 Mp
Full
2048
1536
3,145,728
Half
1024
768
786,432
Quarter
512
384
196,608
5 Mp
Full
2592
1944
5,038,848
Half
1296
972
1,259,712
Quarter
648
486
314,928
10 Mp
Full
3664
2748
10,068,672
Half
1832
1374
2,517,168
Quarter
916
687
629,292
GetCameraVersionInfo / CamGetCameraVersionInfo
Description
Gets the camera’s version numbers – HW, FW see also Output parameters.
Syntax
GetCameraVersionInfo(HW_FW_VERSION_API *versionInfo)
CamGetCameraVersionInfo(int nCamNum, HW_FW_VERSION_API
*versionInfo);
Parameters
Input
nCamNum
Camera number
Output
versionInfo
An HW_FW_VERSION_API structure defined as:
unsigned int sensorVersion;
unsigned short len;
char versionInfo[MAX_VERSION_LEN];
24
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
unsigned char ExtClk; // 24 Mhz - 96 Mhz
Return Values
None
GetCamCaps / CamGetCamCaps
Description
Returns a structure containing some of the camera’s capabilities.
Syntax
GetCamCaps(CAMERA_CAP_API *CameraCap)
CamGetCamCaps(int nCamNum, CAMERA_CAP_API *CameraCap);
Parameters
Input
nCamNum
Camera number
Output
CameraCap
CAMERA_CAP_API struct which is defined as:
unsigned int SensorType; // see GetSensorType
char
Desc[SENSOR_DESC_LEN];
unsigned int CommType;
// USB or TCP - COMM_TYPE
float
FirmwareVersion;
float
HardwareVersion;
int
Width;
// maximum width
int
Height;
// maximum height
int
ActiveStartX; // X column start
int
ActiveStartY; // Y row start
char
CameraID[CAM_ID_LEN];// serial number
unsigned int pCam;
char
// pointer to camera interface
Color;
OpenCamera / CamOpenCamera
Description
Camera streaming is stopped, the sensor is reset and the default parameters are
loaded. The camera sensor is reset to default values as if powered up.
Syntax
OpenCamera(void);
CamOpenCamera(int nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
GetState / CamGetState
Description
Returns the current state of the camera.
Syntax
int GetState(void);
int CamGetState(int nCamNum)
Parameters
Input
nCamNum
Camera number
Output
int
State of camera:
25
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
NO_INIT
INIT
RUNNING
PAUSE
0
1
2
3
//
//
//
//
camera was closed, can’t access
camera is found and ready
video is streaming
display is paused
CamGetMaxRegion
Description
Gets the maximum coordinates of the region of interest, ROI, that the camera is
capable of capturing. When accessing these commands through interface and
camera’s pointer, these values are in the CamCaps (CAMERA_CAP_API) struct.
Syntax
CamGetMaxRegion(int nCamNum, int * startX, int * startY, int
*maxWidth, int *maxHeight)
Parameters
Input
Output
nCamNum
Camera number
*startX
X coordinate value (column number) for region's left side
*startY
Y coordinate (row number) for region's top row
*maxWidth
Width in pixels from startX
*maxHeight
Height in pixels from startY
None
Controlling the Video Streaming
StartVideo / CamStartVideo
Description
Starts a camera that has already been initialized. When called, video is streamed
from the camera and displayed in a separate Preview window. Initial camera
settings can be sent as parameters.
Syntax
StartVideo(int nCamNum, int nShutterWidth, int nGain,
int nResolution,int a_nX, int a_nY,
int a_nWidth, int a_nHeight, HWND hWindow);
CamStartVideo(int nCamNum, int nShutterWidth, int nGain,
int nResolution, int a_nX, int a_nY,
int a_nWidth, int a_nHeight, HWND hWindow);
Parameters
Input
Output
nCamNum
Camera number
nShutterWidth
Camera’s shutter width
nGain
Global gain
a_nX
ROI - Start X
a_nY
ROI - Start Y
a_nWidth
ROI - Width of video
a_nHeight
ROI - Height of Video
hWindow
HANDLE to video window. If NULL, will create new window
for video.
None
26
Camelot Cameras - API Explained
Return Values
Chapter 4 - Controlling the Camera
true
Succeeded
false
Failed
StartVideoStreaming / CamStartVideoStreaming
For this composite function to work, the following structures must be defined. All the parameters
needed for viewing the video are included. Capture Info structure:
typedef struct
{
RESOLUTION_TYPE
FOV_API
unsigned int
unsigned int
unsigned int
unsigned int
unsigned char
unsigned char
unsigned char
unsigned char
unsigned char
unsigned char
unsigned char
unsigned char
double
} tCaptureInfo;
Resolution;
// Capture resolution - FULL, HALF,
QUARTER
ROI;
// Capture ROI - x,y,width,height
Exposure;
// Exposure time (in microseconds) for
capture
ShutterWidth; // Shutter width- if Exposure time = 0
Gain;
// Gain for capture
NumFrames;
// number of frames to capture,
0 = streaming
WithFlash;
// should flash be on for capture
UseLUT;
// should frame be translated using
LUT that was loaded
UseAgc;
// should Automatic Gain Control be
used
UseAwb;
// should Automatic White Balance be
used
AdjustFlicker;// 0 - don't adjust, 50 - for 50Hz, 60
- for 60Hz
PixelBits;
// Bits per pixel - 8, 10, 12
PllRate ;
// for 5Mp with 24Mhz crystal - values
between 24-96
UseTestData; // Use Test Data - default data for
each sensor
FrameRate;
// rate in FPS
Preview info structure:
typedef struct
{
RESOLUTION_TYPE Resolution;
unsigned char
unsigned char
unsigned char
unsigned char
unsigned char
unsigned char
// Capture resolution - FULL,
HALF, QUARTER
FlipHorizontal; // should data be flipped
horizontally?
FlipVertical;
// should data be flipped
vertically?
DegreesRotate; // values of 0, 90, 180, 270 –
n.a.
DisableBayer;
// RAW data is displayed as is –
good for monochrome sensors
Greyscale;
// should frames be displayed in
greyscale?
UseHistogramEqualization; // use Histogram
equalization
27
Camelot Cameras - API Explained
unsigned char
unsigned char
HWND
HWND
int
int
RECT
unsigned char
Chapter 4 - Controlling the Camera
UseHistogramStretching;
// use Histogram
Stretching
UseColorCorrectionMatrix; // use Color
Correction Matrix - uploaded or default
hParentWindow;
// can be NULL
hPreviewWindow;
// HANDLE to child window with
Preview. NULL for new
window to be created
Width;
// dimensions of window to open
Height;
// dimensions of window to open
Rect;
// where to place window on
screen
FitToScreen;
// if hPreviewWindow is NULL –
0 - scroll bars, 1 - video
sized to screen
} tPreviewInfo;
Description
Starts a video streaming from a camera that has already been initialized. When
called, video is streamed from the camera and displayed (if requested) in a
separate Preview Window. Many capture and preview settings can be sent as
parameters using structs.
Syntax
StartVideoStreaming(tCaptureInfo *CaptureInfo,
tPreviewInfo *PreviewInfo);
CamStartVideoStreaming(int nCamNum, tCaptureInfo *CaptureInfo,
tPreviewInfo *PreviewInfo);
Parameters
Input
Output
Return Values
nCamNum
Camera number
CaptureInfo
Pointer to structure with capture information
PreviewInfo
Pointer to structure with preview information
None
true
Succeeded
false
Failed
SetViewWindow / CamSetViewWindow
Description
Provides the dll with a HANDLE to a window to be used for previewing the video.
If video preview is required, this command must be called before Run/CamRun.
Syntax
SetViewWindow(HWND hWindow, int a_camNum, int width,
int height)
CamSetViewWindow(int nCamNum, HWND hWindow, int a_nWidth,
int a_nHeight)
Parameters
Input
hWindow
HWND handle to the window to be used for preview
nCamNum
Camera number
width
Initial width of video to be displayed. Should be calculated
according to capture and preview resolutions.
height
Initial height of video to be displayed. Should be calculated
according to capture and preview resolutions.
28
Camelot Cameras - API Explained
Output
Chapter 4 - Controlling the Camera
None
GetViewWindow / CamGetViewWindow
Description
Returns the HANDLE of the preview window which was set in the
Cam/SetViewWindow command.
Syntax
int GetViewWindow(void);
int CamGetViewWindow(void);
Parameters
Input
none
Output
int
Handle to the preview window in which video is displayed
SetPixelBits / CamSetPixelBits
Description
Defines how many bits per pixel will be captured by camera. This must be set
when camera is initialized but not running. The default is 8 bits per pixel.
Syntax
SetPixelBits(int BitsPerPixel)
CamSetPixelBits(int nCamNum, int BitsPerPixel)
Parameters
Input
Output
nCamNum
Camera number
BitsPerPixel
8 is default.
10 or 12 (for 5Mp and 10Mp) are also options.
None
GetPixelBits / CamGetPixelBits
Description
Returns how many bits per pixel are being captured by camera.
Syntax
SetPixelBits(int *BitsPerPixel)
CamSetPixelBits(int nCamNum, int *BitsPerPixel)
Parameters
Input
nCamNum
Camera number
Output
BitsPerPixel
8, 10, or 12
Run / CamRun
Description
When called, video is streamed from the camera. If a window has been defined
(in the SetVideoWindow command), the video will be displayed.
Syntax
Run(void)
CamRun(int a_nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
29
Camelot Cameras - API Explained
Return Values
Chapter 4 - Controlling the Camera
true
Succeeded
false
Failed
Pause / CamPause
Description
Pause the preview of the camera output. Streaming continues, and callback
commands, if set, are accessible.
Syntax
Pause()
CamPause(int a_nCamNum)
Parameters
Input
a_nCamNum
Output
None
Return Values
Camera number
None
StopCamera / CamStopCamera
Description
Stops a running camera but keeps it initialized.
Syntax
StopCamera()
CamStopCamera(int a_nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
30
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
CloseCamera / CamCloseCamera
Description
Closes all connections to the selected camera and releases all buffers used for video
capture.
Syntax
CloseCamera()
CamCloseCamera(int nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
ResetCamera / CamResetCamera
Description
Closes all connections to the selected camera, releases all buffers used for video
capture and resets the camera.
Syntax
ResetCamera()
CamResetCamera(int nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
GetFrameNum / CamGetFrameNum
Description
Outputs the current frame number being captured from the camera. This is a
sequential number that starts at zero (0) every time streaming starts.
Syntax
GetFrameNum(void)
CamGetFrameNum(int nCamNum)
Parameters
Input
nCamNum
Camera number
Output
Frame number
Current frame number captured. Frame numbers are given to
each frame when captured by the camera. Not all frames are
transmitted to the PC (bandwidth limits), so Frame numbers
may not be consecutive. These Frame numbers may be used
to calculate the camera’s FPS.
31
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
DisplayFrameNumTime / CamDisplayFrameNumTime
Description
Displays the current frame and time on the frames output from camera.
This command is not supported in IDM-500 cameras.
Syntax
DisplayFrameNumTime (void)
CamDisplayFrameNumTime(int nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
GetFPS / CamGetFPS
Description
Outputs the frames per second, FPS, of the selected camera. This is a dynamically
changing statistic and depends on camera resolution, shutter width, gain and
binning.
Syntax
GetFPS(double *pFPS, double *pSkipPS, double *pDisplayPS)
CamGetFPS(int nCamNum, double *pFPS, double *pSkipPS, double
*pDisplayPS)
Parameters
Input
nCamNum
Camera number
Output
pFPS
How many FPS captured by PC.
pSkipPS
n.a. (should be NULL)
pDisplayPS
How many FPS displayed on PC Preview screen
GetFPSrate / CamGetFPSrate
Description
Outputs the Bit Rate of the selected camera. This is a dynamically changing statistic
and depends on camera resolution, shutter width, gain and binning.
Syntax
GetFPSrate(double*pFPS, double*pDisplayPS)
CamGetFPSrate(int nCamNum, double *pFPS, double *pDisplayPS)
Parameters
Input
nCamNum
Camera number
Output
pFPS
How many MegaBits/sec captured by DirectShow filter
pDisplayPS
How many MegaBits/sec displayed on PC Preview screen
32
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
Setting and Getting the Gain values
The gain values have been normalized to the range 0-1024.
All values from 0-64 relate to the analog gain, where:
0 - 32 are “real” gains of 0.0 – 4.0
33 - 64 are “real” gains of 4.25 – 8.00
Values from 65 – 1024 translate as follows;
in 1.3Mp cameras – 65-120 are analog gains of 9-15 (values over 120 are
ignored)
For other cameras, 65 – 1024 are digital gains.
SetGainType / CamSetGainType
Description
Sets sensor’s gain according to the type specified.
Syntax
SetGainType(int type, int nGain)
CamSetGainType(int nCamNum, int type, int nGain)
Parameters
Input
Output
nCamNum
Camera number
Type
RED
GREEN
BLUE
GLOBAL
PROPORTIONAL
nGain
Value of gain – range 0 – 1024. See above for short explanation of
analog/digital gains.
0
1
2
3 // sets R, G, and B gains to same value
4 // gain is for RED, sets others proportionally
None
GetGainType / CamGetGainType
Description
Returns with the value of the gain according to the camera type.
Syntax
GetGainType(int type, int *pnGain)
CamGetGainType(int nCamNum, int type, int *pnGain)
Parameters
Input
Output
nCamNum
Camera number
Type
RED
0
GREEN 1
BLUE 2
pnGain
Returned gain in range 0 - 1024
33
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
SetGainProportions / CamSetGainProportions
Description
The three R G B parameters are set as ratios between the gains – not by absolute
values. When the R gain is changed, G and B are changed proportionately.
Until a subsequent call, the gains will have the ratio 1024:((G*1024)/R):((B*1024)/R).
Integer math is used in the scaling.
Syntax
SetGainProportions (int R, int G, int B)
SetGainProportions (int nCamNum, int R, int G, int B)
Parameters
Input
Output
nCamNum
Camera number
R
A number representing weight of RED gain
G
A number representing weight of GREEN gain
B
A number representing weight of BLUE gain
pnGain
Returned gain in range 0 - 1024
34
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
Exposure Time and Shutter Control
Exposure Time
The Exposure time is the reset time of each pixel row subtracted from the
sample time. This is the amount of time required before a new row is available.
Exposure time is a function of the camera’s external PIXCLK (pixel clock), PLL
rate, shutter width, shutter delay, frame width and binning. Exposure time is
calculated per frame, and is displayed on the Main screen. Except for the WVGA
sensor, described below, all the Camelot and IDM-500 series cameras use a
rolling shutter. Rolling shutters cannot freeze moving objects as well as global
shutters can.
For more information refer to the datasheets of each specific sensor.
Shutter Control (WVGA -Wide VGA Sensor - 752 x 480 pixels)
The global shutter feature of the WVGA image sensor is able to freeze moving
objects because all pixels are exposed simultaneously. When using a global
shutter all pixels begin exposure, integrating a charge, simultaneously and end
exposure simultaneously. A new sequence only begins after the readout of all
pixels is completed.
GetShutterWidth / CamGetShutterWidth
Description
Returns the sensor’s shutter width. This value controls the time of exposure for
each new frame captured
Syntax
GetShutterWidth(int *pnShutterWidth)
CamGetShutterWidth(int nCamNum, int *nShutterWidth)
Parameters
Input
nCamNum
Camera number
Output
pnShutterWidth
Returned shutter width – values are in range from
1 – 65,500
SetShutterWidth / CamSetShutterWidth
Description
Sets the sensor shutter width. This value controls the time of exposure for each
new frame captured
Syntax
SetShutterWidth(int nShutterWidth)
CamSetShutterWidth(int nCamNum, int nShutterWidth)
Parameters
Input
Output
nCamNum
Camera number
nShutterWidth
Valid values from 1-65,500
None
35
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
GetShutterWidthGains / CamGetShutterWidthGains
Description
Gets the sensor’s current shutter width and color gain values.
Syntax
GetShutterWidthGains(SHUTTER_GAIN_API *pnShutterGains)
CamGetShutterWidthGains(int nCamNum, SHUTTER_GAIN_API
*pnShutterGains)
Parameters
Input
nCamNum
Camera number
Output
pnShutterGains
SHUTTER_GAIN_API struct which is defined as:
int shutterWidth;
int exposureTime; // in microseconds
int redGain;
int blueGain;
int greenGain;
int globalGain;
GetShutterDelay / CamGetShutterDelay
Description
Returns the sensor shutter delay. This value is used for controlling exposure time
and to avoid any 50Hz or 60Hz flicker.
Syntax
GetShutterDelay(int *pnShutterDelay)
CamGetShutterDelay(int nCamNum, int *pnShutterDelay)
Parameters
Input
nCamNum
Camera number
Output
pnShutterDelay
Returned shutter delay – values are in range from 0 –
2,047
SetShutterDelay / CamSetShutterDelay
Description
Sets the sensor shutter delay This value is used for controlling exposure time and
to avoid any 50Hz or 60Hz flicker.
Syntax
SetShutterDelay(int nShutterDelay)
CamSetShutterDelay(int nCamNum, int nShutterDelay)
Parameters
Input
Output
nCamNum
Camera number
nShutterDelay
Valid values from 0 – 2,047
None
36
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
AdjustFlicker / CamAdjustFlicker
Description
Adjusts the Shutter Width to avoid the 50Hz or 60Hz flicker experienced when using
indoor lighting.
Syntax
AdjustFlicker(bool adjust, int freqHz)
CamAdjustFlicker(int nCamNum, bool adjust, int freqHz)
Parameters
Input
nCamNum
Camera number
adjust
True – turns on this feature – whenever Shutter Width is modified,
it will be changed to adjust the flicker
False – no adjustment made for flicker
freqHz
Output
For what frequency should the flicker be adjusted? Values: 50, 60
None
SetExposureTime / CamSetExposureTime
Description
Sets the exposure time, in microseconds, for each frame. If the value entered is
lower than the minimum value for this camera, the camera operates at the
minimum value.
Syntax
SetExposureTime(int expTime)
CamSetExposureTime(int nCamNum, int expTime)
Parameters
Input
Output
nCamNum
Camera number
expTime
Number of microseconds for exposing each frame
none
SetFrameRate / CamSetFrameRate
Description
Sets the frame rate of the sensor output. The vertical blanking register is set so
that the frame rate is controlled. If the frame rate given is higher than the sensor
can deliver the sensor output is limited to the maximum output possible. If the
requested frame rate is lower than the vertical blanking can control, then the frame
rate will be as low as the highest vertical blanking value allows.
Syntax
SetFrameRate(float frameRate)
CamSetFrameRate(int nCamNum, float frameRate)
Parameters
Input
Output
nCamNum
Camera number
frameRate
Number of frames to be output by the sensor per second
none
37
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
GetExposureTime / CamGetExposureTime
Description
Gets the actual exposure time (in microseconds) for each frame according to the
ShutterWidth, ShutterDelay, and capture resolution.
Syntax
GetExposureTime(int *expTime)
CamGetExposureTime(int nCamNum, int *expTime)
Parameters
Input
nCamNum
Camera number
Input
expTime
Number of microseconds each frame is exposed
Output
none
CalcShutWidthForExpTime / CamCalcShutWidthForExpTime
Description
Returns the shutter width that should be programmed in order to get the exposure
time (in microseconds) indicated.
Syntax
CalcShutWidthForExpTime(int expTime, int *shutWidth)
CamCalcShutWidthForExpTime(int nCamNum, int expTime, int
*shutWidth)
Parameters
Input
nCamNum
Camera number
Input
expTime
Number of microseconds to expose each frame
Output
shutWidth
Value of shutter width to program inorder to get desired Exposure
time
Understanding the Camera Resolution Types
In this application we relate to two resolution types:
1. Resolution of the camera output or Capture resolution.
a. FULL - The camera outputs frames at maximum width
and height.
b. HALF - The camera outputs frames at HALF width and
HALF height of the FULL sized frame. That means that
HALF frames are really 1/4 the size (in bytes) of FULL
frames.
c. QUARTER – The camera is outputting frames at 1/16
the size of a FULL frame, since every three rows and
every 3 columns are skipped.
2. Resolution of the Preview screen on the PC.
a. FULL - What is received from the camera is displayed
at the same dimensions.
b. HALF - In preview this means that only 1/4 of the
pixels coming from the camera are displayed, since
every alternate row and column are skipped.
c. QUARTER - Only 1/16 of the pixels received from the
camera are displayed.
38
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
GetResolution / CamGetResolution
Description
Returns the current resolution of the Preview Screen.
Syntax
GetResolution(int *pnResolution)
CamGetResolution(int nCamNum, int *pnResolution)
Parameters
Input
nCamNum
Camera number
Output
pnResolution
FULL
= 0,
HALF
= 1,
QUARTER = 2,
EIGHTH
= 3,
// not yet supported
SetResolution / CamSetResolution
Description
Sets the resolution used for the Preview Screen. The FULL parameter (0) gives the
maximum sensor output from the camera. All other resolutions are subsets of this
FULL output.
Syntax
SetResolution(int nResolution)
CamSetResolution(int nCamNum, int nResolution)
Parameters
Input
nCamNum
Camera number
nResolution
FULL
= 0,
HALF
= 1,
QUARTER = 2,
EIGHTH
Output
= 3,
// not yet supported
None
GetCaptureResolution / CamGetCaptureResolution
Description
Returns the current camera output resolution.
Syntax
GetCaptureResolution(int *pnResolution)
CamGetCaptureResolution(int nCamNum, int *pnResolution)
Parameters
Input
nCamNum
Camera number
Output
pnResolution
FULL
= 0,
HALF
= 1,
QUARTER = 2,
EIGHTH
39
= 3,
// not yet supported.
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
SetCaptureResolution / CamSetCaptureResolution
Description
Sets the camera output resolution. Video streaming is stopped before resolution is
set.
Syntax
SetCaptureResolution(int nResolution)
CamSetCaptureResolution(int nCamNum, int nResolution)
Parameters
Input
nCamNum
Camera number
nResolution
FULL
= 0,
HALF
= 1,
QUARTER = 2,
EIGHTH
Output
= 3,
// not yet supported.
None
Setting a Region of Interest (ROI)/Frame of View (FOV)
A specific area or subset of the total available resolution may be defined as a
Region of Interest, ROI. This ROI is captured and/or displayed according to the
settings used. See SetCaptureResolution and/or SetResolution for more
information. The SetRegion and GetRegion commands control the ROI requested
from the camera.
GetRegion / CamGetRegion
Description
Gets the coordinates of the region of interest, ROI, programmed in the registers of
the camera.
Syntax
GetRegion(int *startX, int *startY, int *width, int *height)
CamGetRegion(int nCamNum, int * startX, int * startY, int
*width, int *height)
Parameters
Input
Output
nCamNum
Camera number
*startX
X coordinate value (column number) for region's left side
*startY
Y coordinate (row number) for region's top row
*width
Width in pixels from startX
*height
Height in pixels from startY
None
40
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
SetRegion / CamSetRegion
Description
Sets the region of interest, ROI, to be output by the camera. The width and height
must be even numbers. Video streaming is stopped before region is set.
Syntax
SetRegion(int startX, int startY, int width, int height)
CamSetRegion(int nCamNum, int startX, int startY, int width,
int height)
Parameters
Input
Output
nCamNum
Camera number
startX
X coordinate value (column number) for region's left side
must be an even value
startY
Y coordinate (row number) for region's top row must be an
even value
width
Width in pixels from startX must be an even value
height
Height in pixels from startY must be an even value
None
Binning
Binning can be set when rows and columns are skipped as in HALF and QUARTER
resolutions. The rows/columns displayed are averaged with the skipped
rows/columns. The picture should be a bit smoother but the FPS is similar to that
of a FULL Resolution frame. This could mean a lower FPS value.
SetCapBinning / CamSetCapBinning
Description
Sets whether binning will be used by the sensor for video output. Only available if
HALF or QUARTER resolution is selected.
Syntax
SetCapBinning(bool bBinning)
CamSetCapBinning(int nCamNum, bool bBinning)
Parameters
Input
Output
nCamNum
Camera number
bBinning
True
False
= use binning for video output
= don’t use binning (default)
None
41
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
GetCapBinning / CamGetCapBinning
Description
Returns whether binning has been selected.
Syntax
SetCapBinning(bool *bBinning)
CamSetCapBinning(int nCamNum, bool *bBinning)
Parameters
Input
nCamNum
Camera number
Output
bBinning
True
False
= binning is used for video output
= binning is not being used
Snapshot Mode
When the camera is in Snapshot mode frame output is stopped until an external
trigger is set. Each time the trigger is tripped a snapshot is taken, and displayed
in the SampleApplication video screen. Camelot cameras are available with an
optional external trigger.
EnterSnapShotMode / CamEnterSnapShotMode
Description
Enters or leaves Snapshot Mode. When in Snapshot Mode the camera stops
capturing and streaming video until a trigger is set.
When entering or leaving Snapshot Mode, the FPS calculations start from 0.0 Fps.
Syntax
EnterSnapShotMode(bool snapshotMode)
CamEnterSnapShotMode(int nCamNum, bool snapshotMode)
Parameters
Input
Output
nCamNum
Camera number
snapshotMode
True
False
= Snapshot mode is ON
= Snapshot mode is OFF
None
GetSnapShotMode / CamGetSnapShotMode
Description
Returns whether camera is in Snapshot Mode.
Syntax
CamGetSnapShotMode(bool *SnapMode)
CamGetSnapShotMode(int nCamNum, bool *SnapMode)
Parameters
Input
nCamNum
Camera number
Output
SnapMode
True
False
= Snapshot mode is ON
= Snapshot mode is OFF
42
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
GetSnapShot / CamGetSnapShot
Description
Imitates the external trigger and instructs the camera to capture one frame and
send it to the PC.
Syntax
GetSnapShot(bool withFlash)
CamGetSnapShot(int nCamNum, bool withFlash)
Parameters
Input
Output
nCamNum
Camera number
withFlash
True = use the external flash (optionally supplied with
camera) when snapshot is triggered
False = don’t use flash
ret
True = ACK received from cameraFalse
received
= no ACK
Capturing Frames to File
CaptureFrame / CamCaptureFrame
Description
Captures the next frame from the camera and saves it as a RAW, BMP or JPEG
image. If in Snapshot mode, will capture the next frame after the GetSnapShot()
command is called.
Syntax
CaptureFrame(char* a_sFileName, SAVE_FRAME_TYPE type, bool
bmpQuality, int jpegQuality)
CamCaptureFrame(int nCamNum, char* a_sFileName, SAVE_FRAME_TYPE
type, bool bmpQuality, int jpegQuality)
Parameters
Input
nCamNum
Camera number
a_sFileName
Valid file name – does not have to exist.
If exists, is overwritten.
type
Frame type to be saved according to table:
RAW = 0,
BMP = 1,
JPG = 2
Output
bmpQuality
False – regular Bayer conversion
True – Bayer High quality conversion. If RAW image, n.a.
jpegQuality
If JPG image, quality from 0 (low) to 100 (high).
None
43
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
CaptureFrameDone / CamCaptureFrameDone
Description
Used to poll if frame was captured. After calling CaptureFrame. This function will
return whether or not the frame was saved.
Syntax
CaptureFrameDone(bool *done)
CamCaptureFrameDone(int nCamNum, bool *done)
Parameters
Input
nCamNum
Camera number
Output
done
0 – frame not saved, 1 – frame is saved
int
1 -, 0 –
FALSE - 0
Frame not saved (yet)
TRUE - 1
Frame saved
Return
Values
CaptureFrameDoneEx / CamCaptureFrameDoneEx
Description
Returns TRUE when the amount of frames specified has been captured.
Syntax
CaptureFrameDone(bool *done, int *pFrameCount)
CamCaptureFrameDone(int nCamNum, bool *done, int *pFrameCount)
Parameters
Input
Output
Return
Values
nCamNum
Camera number
pFrameCount
How many frames should be captured before this command
returns TRUE
done
0 – pFrameCount frames not yet saved, 1 – pFrameCount
frame(s) saved
int
1 -, 0 –
FALSE - 0
Frame(s) not saved (yet)
TRUE - 1
Frame(s) saved
44
Camelot Cameras - API Explained
Chapter 4 - Controlling the Camera
CaptureFrameFileBuf / CamCaptureFrameFileBuf
For this composite command to work, the following structures must be defined. All the parameters
needed for saving the video are included.
Save Info structure:
typedef struct
{
SAVE_FRAME_TYPE
unsigned char
char
int
char
} tSaveFrameInfo;
Type;
//
Quality; //
*Buffer; //
BufferLen;
*FileName;//
Frame type - RAW, BMP (RGB32), JPG
BMP - >0 is high quality, JPG- 0-100
if not NULL will save to buffer
if not NULL, will save to file
Description
Captures the next frame from the camera and saves it as a RAW, BMP or JPG
image. This command can be called while in Snapshot mode or in video streaming
mode.
Syntax
CaptureFrameFileBuf(tSaveFrameInfo *SaveInfo);
CamCaptureFrameFileBuf(int nCamNum, tSaveFrameInfo *SaveInfo);
Parameters
Input
Output
nCamNum
Camera number
SaveInfo
Parameters for saving file
None
GetFrameWithFlash / CamGetFrameWithFlash
Description
While streaming video, two frames are captured with flash (in the first the flash
may be weaker) and streaming continues. The flash must be defined using the
PWM controls, and EnableTimers set to 0 (flash for frame) See SetPwmTimer.
Syntax
GetFrameWithFlash()
CamGetFrameWithFlash(int nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
45
Chapter 5
Preview Controls
These commands control the way the video is displayed on the PC. They only
affect the RGB image in the display, and are performed during or after Bayer
conversion.
GetFlipHorizontal / CamGetFlipHorizontal
Description
Returns whether the picture is flipped horizontally.
Syntax
GetFlipHorizontal(bool *pbFlipHorizontal)
CamGetFlipHorizontal(int nCamNum, bool *pbFlipHorizontal)
Parameters
Input
nCamNum
Camera number
Output
pbFlipHorizontal
True
False
= picture is flipped horizontally
= picture isn’t flipped horizontally
SetFlipHorizontal / CamSetFlipHorizontal
Description
Sets whether the picture should be flipped horizontally.
Syntax
SetFlipHorizontal(bool bFlipHorizontal)
CamSetFlipHorizontal(int nCamNum, bool bFlipHorizontal)
Parameters
Input
Output
nCamNum
Camera number
bFlipHorizontal
True
False
= flip the picture horizontally
= don’t flip the picture horizontally
None
GetFlipVertical / CamGetFlipVertical
Description
Returns whether the picture is flipped vertically.
Syntax
GetFlipVertical(bool *pbFlipVertical)
CamGetFlipVertical(int nCamNum, bool *pbFlipVertical)
Parameters
Input
nCamNum
Camera number
Output
pbFlipVertical
True
False
= picture is flipped vertically
= picture isn’t flipped vertically
46
Camelot Cameras - API Explained
Chapter 5 - Preview Controls
SetFlipVertical / CamSetFlipVertical
Description
Sets whether the picture should be flipped vertically.
Syntax
SetFlipVertical(bool bFlipVertical)
CamSetFlipVertical(int nCamNum, bool bFlipVertical)
Parameters
Input
Output
nCamNum
Camera number
bFlipVertical
True
False
= flip the picture vertically
= don’t flip the picture vertically
None
SetRotation / CamSetRotation
Description
Sets the angle in degrees (0, 90, 180 and 270) for rotating the image. Other
illegal values will default to Rotation of 0.
Syntax
SetRotation(int nRotation)
CamSetRotation(int nCamNum, int nRotation)
Parameters
Input
Output
nCamNum
Camera number
nRotation
DON’T ROTATE = 0,
90,
180,
270
None
SetCrosshair / CamSetCrosshair
Description
Puts a green crosshair in the middle of the screen. This is helpful for focusing and
centering camera on specific points of an object.
Syntax
SetCrosshair(bool crosshair)
CamSetCrosshair(int nCamNum, bool crosshair)
Parameters
Input
Output
nCamNum
Camera number
crosshair
True – displays green crosshair
False – no crosshair in display
None
GetGreyScale / CamGetGreyScale
Description
Returns whether the picture is shown in greyscale.
Syntax
GetGreyScale(bool *pbGreyScale)
CamGetGreyScale(int nCamNum, bool *pbGreyScale)
47
Camelot Cameras - API Explained
Chapter 5 - Preview Controls
Parameters
Input
nCamNum
Camera number
Output
pbGreyScale
True
False
= picture is in greyscale
= picture is shown in color
SetGreyScale / CamSetGreyScale
Description
Sets whether the picture should be shown using greyscale.
Syntax
SetGreyScale(bool bGreyScale)
CamSetGreyScale(int nCamNum, bool bGreyScale)
Parameters
Input
Output
nCamNum
Camera number
bGreyScale
True
False
= show picture in greyscale
= show picture in color
None
SetMonochrome / CamSetMonochrome
Description
Sets whether sensor outputs monochrome (greyscale) data. This information is
used by the Display thread when converting the image from 8-bit Bayer format to
RGB (24-bit or 32-bit).
Syntax
SetMonochrome(bool mono)
CamSetMonochrome(int nCamNum, bool mono)
Parameters
Input
Output
nCamNum
Camera number
mono
True – sensor is monochrome
False – sensor is color
None
GetMonochrome / CamGetMonochrome
Description
Returns whether sensor outputs monochrome (greyscale) data.
Syntax
GetMonochrome(bool *mono)
CamGetMonochrome(int nCamNum, bool *mono)
Parameters
Input
nCamNum
Camera number
Output
mono
True – sensor is monochrome
False – sensor is color
48
Camelot Cameras - API Explained
Chapter 5 - Preview Controls
SetFixBadPixels / CamSetFixBadPixels
Description
Sets whether “bad” pixels should be fixed. “Bad pixels” are defined by one or two
wrong colored pixels in an area of a known hue/color. The “bad pixels” originate from
the sensor and are fixed on the PC.
Only if width and height are at least 4 can this be performed. The “bad pixels” are
fixed in stages, so it takes a few seconds to fix all of them on frames of 5Mp.
Syntax
SetFixBadPixels(int fON, int *pnBadPixels)
CamSetFixBadPixels(int nCamNum, int fON, int *pnBadPixels)
Parameters
Input
Output
nCamNum
Camera number
fOn
0 – OFF
1 – ON, anything else will return number of bad pixels without fixing
pnBadPixels
Number of bad pixels (if fOn > 1)
None
49
Chapter 6
Advanced API Commands
SetTestData / CamSetTestData
Description
Specifies whether the camera should output Test Data or captured video images.
This option is provided for developers to check if the data received is actually the
data sent and other sensor independent features.
WVGA, 1.3Mp and 3Mp cameras have only 1 option – to choose a value that is
output for even columns, and its complement value - for odd columns. For example,
0x12 becomes 0xED.
The 5Mp and 10Mp cameras have other options for creating patterns.
Syntax
SetTestData(bool useTestData, int type,
int redData, int greenData, int blueData, int barWidth)
CamSetTestData(int nCamNum, bool useTestData, int type, int
redData, int greenData, int blueData, int barWidth);
Parameters
Input
nCamNum
Camera number
useTestData
True – use Test Data
False – don’t use Test Data
type
Only applicable for 5Mp sensor.
Values 0-8.
0 - Color Field (Normal Operation – like 1.3Mp and 3Mp)
1 - Horizontal Gradient
2 - Vertical Gradient
3 - Diagonal Gradient
4 - Classic Test Pattern
5 - Marching ones
6 - Monochrome Horizontal Bars
7 - Monochrome Vertical Bars
8 - Vertical Color Bars
For detailed description, see Micron’s data sheets.
Output
redData
Value for R pixel (in 5Mp).
Value for Test Data in 1.3Mp and 3Mp – is output and then
its compliment in a pattern.
greenData
Value for G pixel (in 5Mp).
blueData
Value for B pixel (in 5Mp).
barWidth
Width of bars if type 6, 7, or 8 should be an odd number
None
50
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
SetLowPowerMode / CamSetLowPowerMode
Description
Specifies whether the camera should enter Low Power mode. If video is now
streaming the camera will enter Low Power mode when streaming stops.
This command is not supported in any of the Camelot models or IDM-500
cameras.
Syntax
SetLowPowerMode(bool fOn)
CamSetLowPowerMode(int nCamNum, bool fOn)
Parameters
Input
nCamNum
Camera number
fOn
True – use LowPower mode
False – don’t use Low Power Mode
SetBadFrameDetection / CamSetBadFrameDetection
Description
Specifies whether the camera should detect and correct Bad Frames.
Syntax
SetBadFrameDetection(bool fOn)
CamBadFrameDetection (int nCamNum, bool fOn)
Parameters
Input
nCamNum
Camera number
fOn
True – detect and correct bad frames
False – don’t detect bad frames
SetGetRawFullData / CamSetGetRawFullData
Description
Sets mode for getting RAW frames. For 5Mp camera only: If a 12-bit RAW frame is
required, puts the camera into 48MHz mode (using the SetPllRate command)
before requesting the RAW frame.
This command is not supported by the IDM-500 cameras.
Explanation of the PLL Rate for 5Mp cameras
We recommend using as low a PLL rate as possible for the the frame rate required.
The fewer frames the sensor captures, the more time the DSP has for processing
them. Since the USB bandwidth doesn’t allow for more than 8.5 fps, there is no
reason for the sensor to output 14fps.
Syntax
SetGetRawFullData(SET_RAW_DATA_API *rawDataMsg)
CamSetGetRawFullData(int nCamNum, SET_RAW_DATA_API *rawDataMsg)
Parameters
Input
nCamNum
rawDataMsg
Output
Camera number
Pointer to SET_RAW_DATA_API struct defined as:
unsigned
regular, 1 unsigned
unsigned
unsigned
unsigned
unsigned
None
51
int
RAW
int
int
int
int
int
frameType; // 0 numBits;
resolution;
withLut;
count;
withFlash;
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
Description of the PLL Rate for 5Mp cameras
We recommend using as low a PLL rate as possible for the frame rate required.
The fewer frames the sensor captures, the more time the DSP has for processing
them. Since the USB bandwidth doesn’t allow for more than 8.5 fps, there is no
reason for the sensor to output 14fps.
SetPllRate / CamSetPllRate
Description
Sets the camera’s PLL (internal clock) rate. Video streaming is stopped before PLL is
set. Default: 60MHz.
This option is only supported by the 5Mp models.
Syntax
SetPllRate(int pllRate)
CamSetPllRate(int nCamNum, int pllRate)
Parameters
Input
Output
nCamNum
Camera number
pllRate
Sets the internal clock in Mhz.
Values must be in the range of 16 – 96.
None
GetPllRate / CamGetPllRate
Description
Gets the camera’s PLL (internal clock) rate. This option is only supported by the
5Mp models.
Syntax
GetPllRate(int *pllRate)
CamGetPllRate(int nCamNum, int *pllRate)
Parameters
Input
nCamNum
Camera number
Output
*pllRate
Gets the internal clock in Mhz.
52
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
Commands Using the GPIO Connector on the Camera
Camelot Cameras have a 20-pin Molex connector, described in Appendix A on
page 64.
The IDM-500 series has a 5-pin Molex connector. These pins can be defined for
specific uses in specific applications.
SetPwmTimer / CamSetPwmTimer
Description
Sets three PWM (pulse width modulation) timers which you can attach to peripherals
(LEDs, etc.) that need PWM controlled current source. The period is the overall cycle,
while the width is the duration of the period (duty cycle) where the signal is high.
The width must be less or equal to the period for each timer. The timers (TMR1,
TMR2 and TMR3) are started simultaneously and therefore synchronized.
This command is not supported in IDM-500 cameras.
Syntax
SetPwmTimer (PWM_API pwmTimer)
CamSetPwmTimer(int nCamNum, PWM_API *pwmTimer)
Parameters
Input
nCamNum
Camera number
PWM_API
PWM_API struct which is defined as:
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
unsigned
int
int
int
int
int
int
int
Timer1_period;
Timer1_width;
Timer2_period;
Timer2_width;
Timer3_period;
Timer3_width;
EnableTimers;
unsigned int timeout; // 0
or
to
on
Output
None
//
//
//
//
//
//
//
TMR1 period
TMR1 width
TMR2 period
TMR2 width
TMR3 period
TMR3 width
1- constantly on,
0 – will flash only
for specified frame
- no timeout,
number of milliseconds
shut off flash – even if
"constantly"
See The Appendix for the connector description
53
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
Using General Purpose Input/Output (GPIO)
Up to nine GPIO (general purpose input/output) pins are reserved for the user to set and read. These
pins can be configured as input, output or trigger – which means they either read a value from the
camera, set a value or trigger a frame.
These GPIO pins can turn on/off a circuit or transmit information from the camera.
// GPIO
#define
#define
#define
#define
#define
options
GPIO_OUTPUT
GPIO_INPUT
GPIO_TRIGGER
GPIO_INTERRUPT
GPIO_STROBE
#define MAX_IO_PINS
0
1
2
3
4
// n.a. yet
20
// 9 of which are provided in the 20 pin connector
typedef struct
{
struct
{
int Config;
// GPIO_OUTPUT or GPIO_INPUT or GPIO_TRIGGER
int Value;
// 0 or 1
} GpIo[MAX_IO_PINS];
} GPIO_API;
GetGPIO / CamGetGPIO
Description
Gets the current state and values of up to 9 GPIO (general purpose input/output) pins
that are reserved for end user use.
Syntax
GetGPIO(GPIO_API *gpioApi)
CamGetGPIO(int nCamNum, GPIO_API *gpioApi)
Parameters
Input
Output
nCamNum
Camera number
*gpioApi
A pointer to a GPIO_API struct (see above)
None
SetGPIO / CamSetGPIO
Description
Sets the current state and values of up to 9 GPIO (general purpose input/output) pins
that are reserved for end user use.
Syntax
SetGPIO(GPIO_API *gpioApi)
CamSetGPIO(int nCamNum, GPIO_API *gpioApi)
Parameters
Input
Output
nCamNum
Camera number
*gpioApi
A pointer to a GPIO_API struct (see above)
None
54
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
GetGPIO_Pins / CamGetGPIO_Pins
Description
Gets the current values of the up to 20 GPIO, general purpose input/output, pins that
are reserved for application use. Each bit represents a pin and can either be high (1)
or low (0).
Syntax
GetGPIO_Pins (int *pins)
CamGetGPIO_Pins (int nCamNum, int *pins)
Parameters
Input
Output
nCamNum
Camera number
*pins
A pointer to 32bit variable representing states of up
to 20 GPIOs
None
SetGPIO_Pins / CamSetGPIO_Pins
Description
Sets the current values of the up to 20 GPIO, general purpose input/output, pins that
are reserved for application use. Each bit represents a pin and can either be high (1) or
low(0).
Syntax
SetGPIO_Pins (int *pins)
CamSetGPIO_Pins (int nCamNum, int *pins)
Parameters
Input
Output
nCamNum
Camera number
*pins
A pointer to 32bit variable representing states of up to 20 GPIOs
None
CheckLeds / CamCheckLeds
Description
Checks whether the three external LEDs (optionally provided with the camera) are
functioning.
To utilize this command a separate control board is required.
This command is not supported in IDM-500 cameras.
Syntax
int CheckLeds()
CamCheckLeds(int nCamNum)
Parameters
Input
nCamNum
Camera number
Output
int
An OR-ed value representing which LED is malfunctioning.
A value of 0 means all LEDs are working properly.
1 – LED 1 is not working
2 – LED 2 is not working
4 – LED 3 is not working
55
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
Setting/Getting Sensor Register Values
GetRegVal / CamGetRegVal
Description
Returns value of specified register. Register addresses and values are in HEX
notation. If fails returns -1.
Syntax
GetRegVal(int nRegAddr, int *pnRegVal)
CamGetRegVal(int nCamNum, int nRegAddr, int *pnRegVal)
Parameters
Input
Output
nCamNum
Camera number
nRegAddr
Register number
pnRegVal
Value
SetRegVal / CamSetRegVal
WARNING
This command can change register values to undefined or inadvisable values.
This could cause the camera to malfunction or hang. Refer to Micron Data
sheets for a full description of all registers and values.
Description
Sets specified register value. Register addresses and values are in HEX notation.
Syntax
SetRegVal(int nRegAddr, int nRegVal)
CamSetRegVal(int nCamNum, int nRegAddr, int nRegVal)
Parameters
Input
Output
nCamNum
Camera number
nRegAddr
Register number
nRegVal
Value to be set. Micron registers are 16-bit (2 bytes) so values
range from 0-65535. Not all values are valid for each register –
please read sensor data sheet before changing register values.
None
56
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
GetRegValues / CamGetRegValues
Description
Outputs register values to a REG_LIST_API structure as defined in hostCamApi.h
Syntax
GetRegValues(REG_LIST_API *regApi, char numSection
CamGetRegValues(int nCamNum, REG_LIST_API *regApi, char numSection)
Parameters
Input
Output
nCamNum
Camera number
numSection
Each regApi structure holds 100 registers and values.
numSection specifies which registers should be output.
numSection = 0 – registers 0-99
= 1 – registers 100-199
=2 – registers 200-299, etc.
regApi
Structure with up to MAX_REG_NUM registers and their values
SetRegValues / CamSetRegValues
WARNING
This command can change register values to undefined or inadvisable values.
This could cause the camera to malfunction or hang. Refer to Micron Data sheets
for a full description of all registers and values.
Description
Sets register values according to list supplied in structure. Register addresses and
values are in HEX notation.
Syntax
SetRegValues(REG_LIST_API regApi)
CamSetRegValues(int nCamNum, REG_LIST_API *regApi)
Parameters
Input
Output
nCamNum
Camera number
regApi
Structure with up to MAX_REG_NUM registers and their values
None
57
Camelot Cameras - API Explained
Chapter 6 - Advanced API Commands
Look-up Table (LUT)
UploadLUT / CamUploadLUT
Description
Uploads a Look-up Table, LUT, for translating raw pixel values in the camera before
being outputt. The LUT can translate from 8-bit, 10-bit or 12-bit data to 8-bit, 10bit or 12-bit output. In this version only translations to 8-bit data are supported.
After the LUT is successfully loaded, SetLUT may be called in order to start using
the LUT for new data.
Not all of the Camelot models support this command. This command is not
supported in the IDM-500 series.
Syntax
UploadLut(char* sFileName, int numBits, bool transform)
CamUploadLut(int nCamNum, char *sFileName, int numBits, bool
transform)
Parameters
Input
Output
Return Values
nCamNum
Camera number
sFileName
Valid file name – must exist. Each value should be on a
separate line.
numBits
8, 10, or 12
For 8 bits, 256 values are expected in the file.
For 10 bits, 1024 values are expected in the file.
For 12 bits, 4096 values are expected in the file.
transform
Whether values should be transformed since 8 MSB are in
lower byte. Should be true.
None
true
Uploaded successfully
false
LUT was not uploaded successfully
SetLUT / CamSetLUT
Description
Can be set only after a LUT is successfully uploaded. Indicates to camera that all
data should be translated with the uploaded LUT (Look up Table).
This command is not supported in IDM-500 cameras.
Syntax
SetLut(bool useLUT)
CamSetLUT(int nCamNum, bool useLUT)
Parameters
Input
Output
nCamNum
Camera number
useLUT
Whether LUT should be used on new data
None
58
Chapter 7
IMAGE PROCESSING COMMANDS
Color Correction Options – Processing on PC
Histogram Stretching
Saturates the upper and lower s% of the images color range ([lo, hi]) and
linearly stretches the [ lo+s%, hi -s%] range to [0%,100%].
This provides better color separation.
Histogram Equalization
The Histogram is stretched in a non-linear manner. This method usually
increases the global contrast of many images, especially when the usable data of
the image is represented by close contrast values. Through this adjustment, the
intensities can be better distributed on the histogram. This allows for areas of
lower local contrast to gain a higher contrast. Histogram equalization
accomplishes this by effectively spreading out the most frequent intensity values.
Color Correction (CCM)
A camera's sensor may deliver images in which the colors are not true. A color
correction matrix can be generated and applied to images to provide optimal
color correction. A 3 x 3 matrix can be applied to each RGB triplet resulting in a
corrected triplet R'G'B'. It is often more effective to generate a 4 x 3 matrix that
introduces a fixed offset for each color component into the correction.
59
Camelot Cameras - API Explained
Chapter 7 - Image Processing Commands
SetColorCorr / CamSetColorCorr
Description
Sets the type of color correction to be implemented on the PC for all incoming
frames. If using Color Correction, default values can be found in the cc.ini file.
Syntax
SetColorCorr(COLOR_CORR_TYPE type)
CamSetColorCorr(int nCamNum, COLOR_CORR_TYPE type)
Parameters
Input
nCamNum
Camera number
type
Type of color correction according to table:
CC_OFF
=
CC_CLR_CORR_MATRIX =
CC_HIST_EQUALIZATION =
CC_HIST_STRETCH
=
CC_GAMMA
=
Output
0,
1,
2,
4,
8
None
AWB (Automatic White Balance)
White balance (WB) is the process of removing unrealistic color casts, so that
objects which appear white in person are rendered white in your photo. Proper
camera white balance has to take into account the "color temperature" of a light
source, which refers to the relative warmth or coolness of white light. Our eyes
are very good at judging what is white under different light sources; however
digital cameras must be programmed to perform auto white balance (AWB). An
incorrect WB can create unsightly blue, orange, or even green color casts, which
are unrealistic and particularly damaging to portraits.
AGC (Automatic Gain Control)
For a camera to produce a quality picture it needs a minimum amount of light.
When the lighting conditions are reduced below this minimum level the AGC
(Automatic gain control) increases the amount of amplification to bring the video
signal back up to the minimum required level. When the intensity of the light
source is too high the AGC reduces the gain, thereby providing a better quality
picture.
The AWB and AGC commands are not supported in IDM-500 cameras.
60
Camelot Cameras - API Explained
Chapter 7 - Image Processing Commands
Image Control structure for advanced use of AWB and AGC:
typedef struct
{//Abbreviated
int
unsigned long
fAGC;
//Switch AGC ON|OFF 1|0
periodAWB_sec; //periodAWB_sec > 0: AWB is done periodically
//
every no less than periodAWB_sec.
//periodAWB_sec = 0: AWB OFF.
//A scheduled AWB calculation will be
/postponed while an AGC run is ongoing.
Int
reserved[4];
//for future stuff
//----------------------------------------------------------------------------------//General
int
wcell
//Pixels sampled on (width / wcell) x (height / vcell) grid
, vcell;
//Default: wcell = vcell = 32
//AGC ------------------------------------------------------------------------------int
mid_brightness
// desired average brightness of image. Default: 128
, brightness_margin; //Brightnesses in range
// [mid_brightness+/-brightness_margin] are acceptable
// Default: 8
int
saturation_threshold //Any brightness < saturation_threshold is
// considered black-saturated.
//Only brightnesses of 255 are considered
//
white-saturated.
// Default: 16
, saturation_permil;
//Number of tenths of percent of pixels.
//No brightness increase will be implemented if more
// than saturation_permil of them are white-saturated.
//No brightness decrease will be implemented if more
// than saturation_permil of them are black-saturated.
unsigned long t_take_effect_ms; //Min number of ms between sensor register
//
brightness 'set's.
// Default: 0 (delay betw. successive frames)
int
exposure_lo, exposure_hi //Exposure will not be incremented beyond this
// range. Default: 50,200
, gain_lo, gain_hi
//Gain will not be incremented beyond this
// range. Default: 8,200
, gain_step;
//Gain increment used in algorithm. Default: 1
//Higher values can result in jerky algorithm
// convergence.
int
initial_gain, initial_exposure;
//AGC will start with these values
//Recommeded values: 60, 30; AGC will
// not work well in the low-gain range
//AWB ------------------------------------------------------------------------------int
fDrawAWBIndicator;
//On-frame indicator that AWB is in process 1|0
} IMAGE_CTRL_API;
61
Camelot Cameras - API Explained
Chapter 7 - Image Processing Commands
SetAGC_AWB / CamSetAGC_AWB
Description
Sets if a camera should perform Automatic Gain Control, AGC, and/or Automatic
White Balance, AWB, on data. Each of these commands dynamically changes gain
values and shutter width. When AGC and AWB are disabled, the last, calculated,
shutter width and gain values remain.
This command is not supported in IDM-500 cameras.
Syntax
SetAGC_AWB(IMAGE_CTRL_API *pica, int icaSize)
CamSetAGC_AWB(int nCamNum, IMAGE_CTRL_API *pica, int icaSize)
Parameters
Input
Output
nCamNum
Camera number
*pica
Pointer to struct IMAGE_CTRL_API defined above
icaSize
Size of ImageControlApi structure. If size of 6 int, then is
“abbreviated version” with just AWB period and AGC on/off - all
other values are defaults.
none
SingleFrameAWB / CamSingleFrameAWB
Description
Request the camera to perform the Automatic White Balance, AWB, algorithm on a
single frame. AWB will be performed a specified number of times and then cease.
This command is not supported in IDM-500 cameras.
Syntax
SingleFrameAWB(int nRepeat)
CamSingleFrameAWB(int nCamNum, int nRepeat)
Parameters
Input
Output
nCamNum
Camera number
nRepeat
On how many frames should the AWB algorithm be performed.
none
PC_AWB / CamPC_AWB
Description
Request the camera to perform the Automatic White Balance, AWB, algorithm on
the frame on the PC. The new, calculated gain values will be sent to the camera.
Syntax
PC_AWB(int period_ms)
CamPC_AWB(int nCamNum, int period_ms)
Parameters
Input
Output
nCamNum
Camera number
period_ms
How often should the AWB algorithm be performed?
none
62
Chapter 8
CONFIGURING THE CAMELOT IP CAMERAS
The Camelot IP cameras can be configured using the IP_TechnicianSetup.exe
program. When Camelot IP cameras are shipped, they have a default IP address
of 192.168.168.253.
Every camera is shipped with 3 IP configurations – one which is the “active”
configuration and two others that are “defaults”. The “active” configuration is set
using the IP_TechnicianSetup or the SetIpConfig command below. The
default configurations are set using the SetIpDefaultConfig command below. In
order to switch to one of the default settings a reset pulse (switches to default 1)
or a reset long-press (over 5 seconds – switches to default 2) is done to the IP
camera.
For more specific instructions relating to Camelot IP cameras please refer to the
ID_Camelot_IP_Guide.pdf.
The following API commands allow the user to programmatically configure the
cameras using the following structure:
typedef struct tNET_CONFIG_INFO
{
short use_dhcp;
unsigned char mac_addr[6];
int ipaddr;
int netmask;
int gateway;
unsigned short controlPort;
unsigned short dataPort;
} NET_CONFIG_INFO;
//
//
//
//
//
//
//
0 – don’t use DHCP, 1 – use DHCP
MAC address – read only
IP address
IP netmask
IP gateway
PC control port – read only
PC control port – read only
SetIpConfig / CamSetIpConfig
Description
Sets IP configuration according to the NET_CONFIG_INFO structure above.
Syntax
SetIpConfig(NET_CONFIG_INFO *ipConfig)
CamSetIpConfig(int nCamNum, NET_CONFIG_INFO *ipConfig)
Parameters
Input
Output
nCamNum
Camera number
*ipConfig
Pointer to struct NET_CONFIG_INFO defined above
none
63
Camelot Cameras - API Explained
Chapter 8 - Configuring the Camelot IP Cameras
GetIpConfig / CamGetIpConfig
Description
Gets IP configuration according to the NET_CONFIG_INFO structure above.
Syntax
GetIpConfig(NET_CONFIG_INFO *ipConfig)
CamGetIpConfig(int nCamNum, NET_CONFIG_INFO *ipConfig)
Parameters
Input
Output
nCamNum
Camera number
*ipConfig
Pointer to struct NET_CONFIG_INFO defined above
none
SetIpDefaultConfig / CamSetIpDefaultConfig
Description
Set IP default configurations – similar to SetIPConfig – but refers to default
configurations.
Syntax
SetIpConfig(int which, NET_CONFIG_INFO *ipConfig)
CamSetIpConfig(int nCamNum, int which, NET_CONFIG_INFO *ipConfig)
Parameters
Input
Output
nCamNum
Camera number
which
Which default area (1 or 2)
*ipConfig
Pointer to struct NET_CONFIG_INFO defined above
none
GetIpDefaultConfig / CamGetIpDefaultConfig
Description
Get IP default configurations – similar to GetIPConfig – but refers to default
configurations.
Syntax
GetIpConfig(int which, NET_CONFIG_INFO *ipConfig)
CamGetIpConfig(int nCamNum, int which, NET_CONFIG_INFO *ipConfig)
Parameters
Input
Output
nCamNum
Camera number
which
Which default area (1 or 2)
*ipConfig
Pointer to struct NET_CONFIG_INFO defined above
none
64
Camelot Cameras - API Explained
Chapter 8 - Configuring the Camelot IP Cameras
SetPortRange / CamSetPortRange
Description
Set range of ports to be used by IP application.
Syntax
SetPortRange(int numPorts, unsigned short portStart)
CamSetPortRange(int numPorts, unsigned short portStart)
Parameters
Input
Output
numPorts
How many ports are in the range
portStart
From which port to start
none
65
Chapter 9
USING THE CALLBACK COMMANDS
Callback commands are commands that are accessed whenever an event or
interrupt occurs. In the Camelot API, the callback command is accessed, if so
defined, for each new frame.
The callback command(s) must be of the following type:
typedef void (__stdcall *funcDataPtr) (void *dataPtr, int size,
FRAME_TYPE type, CB_DATA *pCbData);
where FRAME_TYPE is defined as:
// Frame types output from camera
typedef enum
{
NO_FRAME
= 0,
BAYER_8_BIT = 10, // regular file type for display
BAYER_RAW,
// 8, 10 or 12 bit raw full data
FILLER,
// throw away
RGB_24,
// BMP using RGB24
CONTROL_DATA,
// msgs from camera
MONO_RED,
// mono frame - use only red pixels
MONO_GREEN,
//
- use only green pixels
MONO_BLUE,
//
- use only blue pixels
RGB_32,
// BMP using RGB32
BLOCK_DATA,
// blocks sent, described in SYNC message
RGB_8_MONO
// RGB8
} FRAME_TYPE;
and where CB_DATA is defined as:
typedef struct
{
int pCamelotDlg;
// set when activating CB command –
pointer to calling dialog
int pCam;
// set when activate CB function - pointer to
camera
int camNum; // set when activate CB function - camera number
in dialog's listbox
tFrameInfo FrameInfo; // supplied by dll - data from camera
- describes captured, raw frame
int pUserData;
// supplied by user - specific to CB
functionality – used like void *
} CB_DATA;
In the CamelotView sample, there is one callback function that receives a
parameter to identify the type of frame (Raw, or RGB, etc.) received and then
proceeds to deal with it:
DataCallback( unsigned char *dataPtr, int size, FRAME_TYPE type,
CB_DATA *pCbData)
66
Camelot Cameras - API Explained
Chapter 9 - Using the Callback Commands
You can program the Sample Application to use a callback function whenever:
a raw frame (Bayer 8bit) is received
a RAW-FULL frame is received (Bayer 8,10, or 12-bit)
a frame has been converted to RGB (RGB32)
Any parameters or information needed by the command can be sent using the
pUserData pointer in CB_DATA.
There are three call back examples provided with the application:
1. a Histogram can be applied to all RAW (BAYER_8_BIT) data,
2. an Edge filter function can be applied to all RGB32 frames
3. if a Callback function is defined for RAW FULL frames (8, 10, 12-bit), then
they are saved to the disk. Otherwise, the RAW FULL frames are
converted to 8 bit data using a gamma LUT file, and displayed.
In order to setup the callback function capability, first call SetDataCBPtr with a
pointer to a function with the same format as DataCallback above.
Then set the specific type of callback required by calling one (or more) of the
following:
SetRawFrameDataCB – for raw frames before any type of processing
SetRawFullFrameCB – for RAW FULL frames (8, 10, or 12 bits)
SetRGBFrameDataCB – for RGB32 frames – after Bayer conversion
NOTE
The pointer to the frame data (*dataPtr) is only valid within the callback function.
If the data is to be used by another thread or after the callback exits, the data
must be copied to another buffer.
SetDataCBPtr / CamSetDataCBPtr
Description
Sets the callback function that is called every time a new frame is received, if specified.
Syntax
SetDataCBPtr(funcDataPtr funcPtr)
CamSetDataCBPtr(int nCamNum, funcDataPtr funcPtr)
Parameters
Input
nCamNum
Camera number
funcPtr
A pointer to an existing function of type
void func(unsigned char *rawDataPtr, int size,
FRAME_TYPE frameType, void *pUserData)
In the Camelot implementation, FRAME_TYPE is one of the following:
BAYER_8_BIT // regular raw file
BAYER_RAW
// 8, 10 or 12 bitraw, Full data
RGB_32
// BMP using RGB32
In the CamelotView sample, the Callback function is
DataCallback( unsigned char *dataPtr, int size, FRAME_TYPE
type, void *pUserData),
which can be found in Cbfunctions.cpp. The user may edit or replace
this function as appropriate.
WARNING: This function must be performed quickly so as not to
interfere with the frame rate.
Output
None
67
Camelot Cameras - API Explained
Chapter 9 - Using the Callback Commands
SetRawFrameDataCB / CamSetRawFrameDataCB
Description
Sets whether a callback function should be called for each raw frame received.
Syntax
SetRawFrameDataCB (bool useCB, void *pUserdata)
CamSetRawFrameDataCB(int nCamNum, bool useCB, void *pUserData)
Parameters
Input
Output
nCamNum
Camera number
useCb
Whether this callback function should be set.
pUserData
Pointer to user data for the Callback function
None
SetRawFullFrameCB / CamSetRawFullFrameCB
Description
Sets whether a callback function should be called for each raw Full frame received
(as a result of the SetGetRawFullData function on page 41).
Syntax
SetRawFullFrameCB (bool useCB, void *pUserdata)
CamSetRawFullFrameCB (int nCamNum, bool useCB, void *pUserdata)
Parameters
Input
Output
nCamNum
Camera number
useCb
Whether this callback function should be set.
pUserData
Pointer to user data for the Callback function
None
SetRGBFrameDataCB / CamSetRGBFrameDataCB
Description
Sets whether a callback function should be called after each raw frame has been
processed into an RGB frame.
Syntax
SetRGBFrameDataCB (bool useCB, void *pUserdata)
CamSetRGBFrameDataCB (int nCamNum, bool useCB, void *pUserdata)
Parameters
Input
Output
nCamNum
Camera number
useCb
Whether this callback function should be set.
pUserData
Pointer to user data for the Callback function
None
68
Camelot Cameras - API Explained
Chapter 9 - Using the Callback Commands
SaveRawFrameToFileBuf / CamSaveRawFrameToFileBuf
Description
Saves a captured Raw image to a file in RAW, BMP or JPG format. This command
can only be used within the RawFrame or RawFullFrame callbacks.
Syntax
SaveRawFrameToFileBuf(unsigned char *pRawFrame, tFrameInfo
*FrameInfo, tSaveFrameInfo *SaveInfo)
CamSaveRawFrameToFileBuf(int nCamNum, unsigned char *pRawFrame,
tFrameInfo *FrameInfo, tSaveFrameInfo *SaveInfo)
Parameters
Input
Output
nCamNum
Camera number
pRawFrame
Pointer to the raw data
FrameInfo
Information about frame – width, height, bytes per pixel, etc.
SaveInfo
Parameters for saving file.
None
SetMsgCBPtr
Description
Sets pointer to an error message callback function. The dll functions FillCameraList,
and AccessCamera also send this pointer.
Syntax
SetMsgCBPtr(funcMsgPtr funcPtr)
Parameters
Input
funcMsgCb
Output
None
Pointer to a Callback function with Error messages that will be
called from the dll if an error occurs. Recovery code can be
inserted if needed.
69
Chapter 10
Using DebugPrint
This section describes how to use a separate window for sending debug
messages while the application is running.

To use a separate window for sending debug messages:
1. Include BDRdebug.h in your project.
2. Open the ID_debugger window by running ID_debugger.exe.
ID_debugger.exe is included on the Installation CD.
3. In the PC code, call the DebugPrintx(msg[,val1, val2]) function with an
ASCII message as a parameter.
The message is displayed in the ID_debugger window and logged into a file
by time and date.
4. To display messages from the Camera’s DSP, use the GetLogs function
described below.
DebugPrint
Description
Prints a message to a debug window, if open, while in DEBUG mode.
Syntax
DebugPrint1(char * Str)
Parameters
Input
*Str
Output
none
Syntax
Char string – ASCII message to be printed
DebugPrint2(char * Str, int Val1)
Parameters
Input
Output
Syntax
*Str
Char string – ASCII message to be printed
Val1
Number to be printed
none
DebugPrint3(char * Str, int Val1, int Val2)
Parameters
Input
Output
*Str
Char string – ASCII message to be printed
Val1
Number to be printed
Val2
Number to be printed
none
70
Camelot Cameras - API Explained
Chapter 10 - Using DebugPrint
GetLogs / CamGetLogs
Description
Gets log messages saved in the camera for debugging purposes. These messages
are sent to a separate DebugPrint screen (if opened) and can be used to debug
applications. See Using DebugPrint on page 60.
This command is not supported in IDM-500 cameras.
Syntax
GetLogs()
CamGetLogs(int nCamNum)
Parameters
Input
nCamNum
Output
None
Camera number
71
Chapter 11
UPGRADING TO THE LATEST SOFTWARE VERSION
In order to obtain the most recent FW version, please be in touch with our
support team support@imagine2d.com. Visit our website,
http://www.imagine2d.com/ and download and then install the latest version of
both the software and camera drivers currently available.
IMPORTANT NOTES
BEWARE the UpdateFW function writes control data to the camera - an
operation that could render it non-functional if an invalid custom LDR file
is being used.
You can use the UpdateFW function to update to newer, validated
versions of the firmware available on our website.
In order to check a new *.ldr file that has not yet been validated by us at
ID, please contact us at support@imagine2d.com so we can run it for you to
assure the camera will boot after loading your file.

To install the latest version of the camera software and firmware:
1. Download the latest Camelot software version from our site to a temporary
location. At www.imagine2d.com, in the Support tab under Downloads.
2. Upload the new firmware (Camelot_FW.ldr) to the camera using the
current/old working CamelotView (NOT the file you just downloaded) or the
UpdateFW API command below.
a. In CamelotView, in the Processing tab (in the Advanced options pane)
browse to the new ldr file and click on the Update FW button.
3. When the firmware upload is successfully completed, unplug the camera and
close the CamelotSample application
4. Put the new version of CamelotView.exe and Camelot.dll into X:\Program Files\Imaging Diagnostics\Camelot.
Where: X:\ is the system disk. (It’s a good idea to keep a backup of the
older version.)
5. If using Direct Show, copy the Camelotfilter.ax file into the folder
X:\Windows\system32 where: X:\ is the system disk.
6. Reconnect the camera, copy and then run the NEW CamelotView.exe file.
72
Camelot Cameras - API Explained
Chapter 11 - Upgrading to the Latest Software Version
UpdateFW / CamUpdateFW
Description
Updates the camera Firmware. Video streaming is stopped before firmware is
updated.
Syntax
UpdateFW(char* a_sFileName)
CamUpdateFW(int nCamNum, char *a_sFileName)
Parameters
Input
Output
Return Values
nCamNum
Camera number
a_sFileName
Valid file name of type *.ldr– must exist and must be in
correct analog loader file format.
None
S_OK
0 – updated successfully
S_FALSE
1 – camera FW was not updated successfully
73
Appendix A
MOLEX CONNECTOR TABLE
Molex Connector
The table below shows the pin connection table for the Molex Connector located
on the rear of the Camelot series cameras.
Table 2: Molex Connector Table
Pin Num
Pin Name
Description
Remarks
1
GPIO1
DSP_GPIO1
PJ0-Through serial resistor
2
Power
Power
3
GPIO2
DSP_GPIO2
4
Power
Power
5
GPIO3
DSP_GPIO3
PJ2-Through serial resistor
6
PWM1
PB9
TMR1
7
GPIO4
SPI1_SS
PG11-Through serial resistor and
capacitor
8
PWM2
PB10
TMR2
9
GPIO5
SPI1_SCK
PG8-Through serial resistor
10
PWM3
PB11
TMR3
11
GPIO6
SPI1_MISO
PG9-Through serial resistor
12
PWM4
PA13
TMR7
13
GPIO7
SPI1_MOSI
PG10-Through serial resistor
14
PWM5
PH2
TMR8
15
GPIO8
UART2-TX
PB4-Through serial resistor
16
PWM6
PH3
TMR9
17
GND
GND
18
PWM7
PH4
19
GND
GND
20
GPIO9
UART2-RX
74
PJ1-Through serial resistor
TMR10
PB5-Through serial resistor
Imaging Diagnostics invites comments and feedback on this and all of our
products and documentation. Please contact us at one of the email addresses
below.
Website
http://www.imagine2d.com/
Support
We would appreciate any feedback you have about the Camelot EVK.
support@imagine2d.com
Sales
Please contact us if we can assist you in building your own custom applications.
sales@imagine2d.com
A member of the
ID01377-CAMELOT-EVK-API V2 1 1290 pv02 A102.docx
Download PDF
Similar pages