You are on page 1of 24

IVA API Reference Manual

12/13/2017
SSID.SRP

Copyright © 2017 by Advantech. All Rights Reserved.


IVA API Reference Manual

Table of contents

2 Introductions .......................................................................................................... 3
2.1 SDK Overview .................................................................................................. 3
2.2 System Requirement......................................................................................... 4
2.3 SDK Package Structure ..................................................................................... 4
2.4 Start IVA .......................................................................................................... 5
3 Application Programming Interface (API) .................................................................. 6
3.1 Enumeration .................................................................................................... 6
3.1.1 IVA_EVENT ............................................................................................... 6
3.2 APIs ................................................................................................................ 7
3.2.1 Open ........................................................................................................ 7
3.2.2 Close ........................................................................................................ 8
3.2.3 GetDSPVersion .......................................................................................... 9
3.2.4 GetECUVersion ........................................................................................ 10
3.2.5 GetEyeCount ........................................................................................... 11
3.2.6 GetFowardVehicleDistance ....................................................................... 12
3.2.7 GetTimeToCollision .................................................................................. 13
3.2.8 SetDBRStartSpeed ................................................................................... 14
3.2.9 SetFWStartSpeed .................................................................................... 15
3.2.10 SetLDWStartSpeed ................................................................................ 16
3.2.11 SetCurrentSpeed ................................................................................... 17
3.2.12 SetDrivingDistractedSensitivity ............................................................... 18
3.2.13 EnterManualCalibrattion ......................................................................... 19
3.2.13.1 CalibrateBoardDistance ................................................................... 20
3.2.13.2 CalibrateCameraHeight ................................................................... 21
3.2.13.3 CalibrateBoardHeight ...................................................................... 22
3.2.14 LeaveManualCalibrattion ........................................................................ 23
3.2.15 EnterAutomaticCalibration ...................................................................... 24

2 / 24
IVA API Reference Manual

2 Introductions

Advanced driver assistance systems (ADAS) has been developed for a long time, almost has become
necessary equipment for each vehicle , ADAS not only provide the appropriate auxiliary warning to the
driver keep safety but also for fleet management provide quantitative indicators. How to drive safety and
hold good driving behavior has become the focus of each fleet management vendor duty.

IVA module provides the user's visual basis for ADAS. The system uses the front camera to analyze the
image scene, determine the lane line position and the distance of the front vehicle, through the combination
of warning conditions, to provide users with a very flexible development Environment, development for their
system.

IVA module, referred to as IVA. Mainly divided into two modules

 Front Collision Warning System (FCWS)

 Driver Behavior Recognition System (DBR)

FCWS installed in the middle of the front windshield, the system through the front camera and built-in DSP
module, analyze the image scene, the system will use the lane characteristics, such as high contrast lines,
location and other relevant information to determine the lane position, Define the image center for the
vehicle center, to provide a way to determine the lane departure, the other system will be through the
analysis of the front lane in front of the object characteristics of the vehicle to determine the location of the
vehicle, through the geometric relative position to determine the distance of front vehicle. When the vehicle
is offset or the front vehicle too close, the system will automatically trigger the relevant Event and call
corresponding Callback function, the user can register the event handler corresponding to the IVA event.

DBR installed in the cab, the system through the classifier to determine the face position, find the face to
determine the eyes closed, as the driver to judge fatigue. The system also provides additional functionality
to detect driver distract and using cell phone or eating, so that the fleet operator can coach the driver to
maintain the correct driving behavior. The result can provide as KPIs for fleet management.

IVA module output is standard RS-232 signal, providing real-time image analysis results, this design
architecture can effectively help Host side to reduce CPU usage, while the IVA module dedicated to image
analysis, Host only need to deal with the results.

2.1 SDK Overview


The SDK is divided into two parts

 DLL
 Sample code

DLL provides logic to communicate with the IVA module and alarm Trigger notification logic, most of the
developers do not need to know the details, only need to corresponding process after the interest event

3 / 24
IVA API Reference Manual

trigger.

Sample code inside the event handling includes the demo through the graphics, sound and light,
statements, LOG to demonstrate how to using event for developer.

2.2 System Requirement


Module
 TREK-IVA-FWR-100
 TREK-IVA-DBR-100
Software
 .NET Framework 3.5+
Language
 C# only

2.3 SDK Package Structure


You can get the following contents by extracting the SDK package:
Directory Description
bin DLL & Demo Program
doc Document and Release Note
sample The SDK sample source codes

4 / 24
IVA API Reference Manual

2.4 Start IVA


First Step user need to add a reference in Visual C#
1. In Solution Explorer, right-click the project node and click Add Reference.
2. In the Add Reference dialog box, select the tab indicating the type of component you want to reference.
3. Select the IVA.DLL, and then click OK.
4. Add Namespaces to your code
using IVA;

The most important thing to use IVA is to register the EventHandler, you need to register an EventHandler
to let the DLL inform you that when the event occurs, all the events you can follow the parameters
IVAControl.IVA_EVENT to control your program, it is recommended that the user should not be in the
EventHandler Spend too much time. In C # you can join events with multiple EventHandlers via the "+"
operator.

There are many parameters in the DLL that can be set, such as the start speed or the current vehicle
speed. The user needs to create an instance for each IVA module. as follows

IVAControl iva = new IVAControl();

When the instance is created, the user needs to call the Open(Port) method to open the corresponding
Serial Port. When the module is turned on, the system will be initialized in the background. When the
initialization is complete, the user should be able to get the firmware version through GetDSPVersion() or
GetECUVersion(). If the version return "Unknown", try again for a while, or check that your device is
properly connected and the power is on.

5 / 24
IVA API Reference Manual

3 Application Programming Interface (API)

The following parts describe the API usage of main IVA functions.

3.1 Enumeration
3.1.1 IVA_EVENT

 BACK_NORMAL - return to normal status

 NOT_DETECTED - Did not detect the face. This can be used to judge the driver's distraction

 DISTRACTED_DRIVING - Trigger when driver distracted.


 EATING_DRIVING - Trigger when eating on driving.

 CALLING_DRIVING - Trigger when using cell-phone on driving


 SLEEPING_DRIVING - Trigger when close your eyes for too long.

 LEFT_LANE_DEPATURE - Trigger when vehicle departure left lane

 RIGHT_LANE_DEPATURE - Trigger when vehicle departure right lane


FRONT_COLLISION_WARNING_HIGH - Trigger when forward vehicle very close; TTC < 1.2 second

 FRONT_COLLISION_ARNING_MID - Trigger when forward vehicle close; TTC < 2.0 second

 CALIBRATION_OK - Trigger when calibration OK

 CALIBRATION_NG - Trigger when calibration no OK. Please try again.


 CALIBRATION_PROCESSING - Trigger when calibration processing.

6 / 24
IVA API Reference Manual

3.2 APIs

3.2.1 Open
Syntax:

Windows public bool Open(string name )

Description:
Open the IVA module though the serial port. The library will start background thread to receive IVA
data.

Parameters:
name [in]
Specifies which Serial Port Path to connect firmware. For example "\\.\COM1"

Returns:
true - On success.
false - Open fail.

7 / 24
IVA API Reference Manual

3.2.2 Close
Syntax:

Windows void Close()

Description:
Stop receive IVA data and Close the serial port.

Parameters:
None

Returns:
None

8 / 24
IVA API Reference Manual

3.2.3 GetDSPVersion
Syntax:

Windows public string GetDSPVersion()

Description:
Get current IVA module DSP version.

Parameters:
None

Returns:
DSP version string - On success.
"Unknown" string - DSP version not ready or not exist. Please check Module is Power on and cable is
connected.

Remark:
We suggest you polling the DSP version after Open IVA module. When the version is confirmed, the
IVA module ready.

9 / 24
IVA API Reference Manual

3.2.4 GetECUVersion
Syntax:

Windows public string GetECUVersion()

Description:
Get current IVA module ECU version.

Parameters:
None

Returns:
ECU version string - On success.
"Unknown" string - ECU version not ready or not exist. Please check Module is Power on and cable is
connected.

10 / 24
IVA API Reference Manual

3.2.5 GetEyeCount
Syntax:

Windows public int GetEyeCount()

Description:
Get the current eye accumulation from IVA module. This value allows developer to better control the
display time when driving fatigue triggers.

Parameters:
None

Returns:
Eye accumulation. The range is 0~240 (0x00-0xF0)

11 / 24
IVA API Reference Manual

3.2.6 GetFowardVehicleDistance
Syntax:

Windows public int GetForwardVehicleDistance()

Description:
Get the forward vehicle distance from IVA module. This value allows developer to check current vehicle
distance. Developers can use distance to determine whether the car is too close, or by changing the
amount to decide whether to issue a warning. The method returns -1 if the vehicle can not be detected,
or if the vehicle ahead is far beyond the maximum detection distance. The system updates the value
every 40 milliseconds.

Parameters:
None

Returns:
Forward vehicle distance. The range is 0~240 (0x00-0xF0). Units are meters.

12 / 24
IVA API Reference Manual

3.2.7 GetTimeToCollision
Syntax:

Windows public double GetTimeToCollision()

Description:
Assuming the forward vehicle speed is 0. Get the estimated time to hit the car from IVA module. Time
to Collision (TTC) will use the current speed information, users need to input the current system speed
through the SetCurrentSpeed() function, so as to be more accurate.

TTC formula as below

TTC = (36/10) * (forward vehicle distance / current car speed )

IVAControl define two event type:


o FRONT_COLLISION_WARNING_HIGH
o FRONT_COLLISION_WARNING_MID

These two events determine the trigger time by the value of the TTC. < 2.0s will trigger middle. TTC M
1.2s will trigger high.

Parameters:
None

Returns:
TTC. Units are second.

13 / 24
IVA API Reference Manual

3.2.8 SetDBRStartSpeed
Syntax:

Windows public void SetDBRStartSpeed(int kmh)

Description:
Setup DBR Event start trigger speed. If current speed less then this value, the DBR event will not
trigger. The default value is 10km/h. We recommend that the starting speed should be higher than this
speed, when in the low-speed state, the driver's behavior is not very important, the system produces
too many alerts will cause the user's trouble.

Parameters:
kmh [in]
DBR event start trigger speed. Units are kilometers per hour.

Returns:
None

14 / 24
IVA API Reference Manual

3.2.9 SetFWStartSpeed
Syntax:

Windows public void SetFWStartSpeed(int kmh)

Description:
Setup FCWS Event start trigger speed. If current speed less then this value, the FCWS event will not
trigger. The default value is 30km/h. We recommend that the starting speed should be higher than this
speed, when in the low-speed state, the car may be too close, part of the vehicle characteristics
because of the lens shooting angle shielding, the system may have miscarriage of justice. The system
detects a range of 8 meters to 80 meters.

The system will automatically follow the degree of darkness of the image, automatically switch the day
and night to determine the conditions. In the daytime the system mainly uses the characteristics of the
vehicle shadows. In night the system use the tail lights of the vehicle. When the part of the vehicle tail
light is not bright or asymmetrical, the system may not be able to identify the vehicle

Parameters:
kmh [in]
FCWS event start trigger speed. Units are kilometers per hour.

Returns:
None

15 / 24
IVA API Reference Manual

3.2.10 SetLDWStartSpeed
Syntax:

Windows public void SetLDWStartSpeed(int kmh)

Description:
Setup LDWS Event start trigger speed. If current speed less then this value, the LDWS event will not
trigger. The default value is 50km/h. We recommend that the starting speed should not be lower than
this speed, with the speed down, lane line information may become discontinuous, resulting in the
system will produce too many false alarm.

Parameters:
kmh [in]
LDWS event start trigger speed. Units are kilometers per hour.

Returns:
None

16 / 24
IVA API Reference Manual

3.2.11 SetCurrentSpeed
Syntax:

Windows public void SetCurrentSpeed(int kmh)

Description:
Set current car speed. This value will affect the system startup and judgment TTC. It is recommended
that the user update at least every 40ms. In general, the speed information can be obtained through
the CAN bus or through the GPS.

Parameters:
kmh [in]
Current car speed. Units are kilometers per hour.

Returns:
None

17 / 24
IVA API Reference Manual

3.2.12 SetDrivingDistractedSensitivity
Syntax:

Windows public bool SetDrivingDistractedSensitivity(int level)

Description:
Set distracted driving Sensitivity for DBR. This value will affect the system judgment distracted driving
timing. The range only support level 1 to 3. Level 3 more sensitive than Level 1. Too sensitive may lead
to more false alarms.

Parameters:
level [in]
Sensitivity. level 1 to 3.

Returns:
true - On success.
false - setting fail. please check level range.

18 / 24
IVA API Reference Manual

3.2.13 EnterManualCalibrattion
Syntax:

Windows public void EnterManualCalibrattion()

Description:
Enter to Manual Calibration mode. Only FCWS will use this function. This method is used to correct
FCWS parameter information. Parameter information is only used when the device is not initialized by
the factory. Generally, it is not necessary to use it. Please ask the contact window for any correction. If
you do not know what you are doing, please do not use this function

Parameters:
None

19 / 24
IVA API Reference Manual

3.2.13.1 CalibrateBoardDistance
Syntax:

Windows public void CalibrateBoardDistance(int value)

Description:
This method requires access to Manual Calibrate mode to use. The board distance as below picture.

Parameters:
value [in]
The distance between calibrate board and camera. The units are cm.

20 / 24
IVA API Reference Manual

3.2.13.2 CalibrateCameraHeight
Syntax:

Windows public void CalibrateCameraHeight(int value)

Description:
This method requires access to Manual Calibrate mode to use. The Camera height as below picture.

Parameters:
value [in]
Camera Height. The units are cm.

21 / 24
IVA API Reference Manual

3.2.13.3 CalibrateBoardHeight
Syntax:

Windows public void CalibrateBoardHeight(int value)

Description:
This method requires access to Manual Calibrate mode to use. The Calibrate Board height as below
picture.

Parameters:
value [in]
Calibrate board Height. The units are cm.

22 / 24
IVA API Reference Manual

3.2.14 LeaveManualCalibrattion
Syntax:

Windows public void LeaveManualCalibrattion()

Description:
Leave manual calibration mode. Only FCWS will use this feature. When all the parameters are set, you
need to call this method to return to the detection mode. This method is used to correct FCWS
parameter information. Parameter information is only used when the device is not initialized by the
factory. Generally, it is not necessary to use it. Please ask the contact window for any correction. If you
do not know what you are doing, please do not use this function

Parameters:
None

23 / 24
IVA API Reference Manual

3.2.15 EnterAutomaticCalibration
Syntax:

Windows public void EnterAutomaticCalibration(int step)

Description:
Enter to Automatic Calibration mode. Only FCWS will use this function. This method is used to correct
FCWS parameter information. Parameter information is only used when the device is not initialized by
the factory. Generally, it is not necessary to use it. Please ask the contact window for any correction. If
you do not know what you are doing, please do not use this function. The user needs to set the basic
parameters via Manual Calibrate and then make the final calibration via Automatic Calibration.

The user needs to place the calibration board near the position, and then use the automatic calibration
step 1. Using GetCalibrateLastError() to confirm that the calibration is successful, move the calibration
board away from the front 1 meter position, and then use the Auto Calibration 2

Parameters:
step[in]
Indicate which step using calibration.

24 / 24

You might also like