Alert-Lib
alert-lib
contains classes related to distance estimation, speed calculation, alerts, camera, and AR overlays.
Distance Estimation
The distance filter estimates the distance of an object from the camera.
The StaticDistanceEstimator
class uses an assumed width/height and the camera's properties to determine the camera's distance from an object. The estimator works with cars and pedestrians by default, but may be extended if other objects are needed for your use case. Distances are in meters for default values. For any custom values, the distance unit is the same as the provided size.
public void estimateDistance(List<Recognition> recognitions, Size frameSize, int sensorRotation, float focalLength, SizeF sensorSize)
The following list describes the method parameters:
-
recognitions
- List of recognitions to process -
frameSize
- Size of the image that recognitions were derived from at 0 rotation -
sensorRotation
- Clockwise rotation to each frame's natural orientation as a multiple of 90 degrees -
focalLength
- Focal length of the capture camera in millimeters -
sensorSize
- Size of the physical camera sensor in millimeters
Note
The distance value for a Recognition
may already be available from the ML model.
RoI - Region of Interest
A Region of Interest (RoI) defines a region of the source image to enable filtering of detections based on their location in the image. For example, when only detections in front of the vehicle are relevant, detections on the far side can be removed.
The SDK defines the following types of regions:
- Primary: This region type typically represents the ego lane
- Secondary: This region type typically represents a region including adjacent lanes on either side of the ego lane
The SDK can generate an RoI via the following methods:
-
makeStaticRoi
: A static RoI is generated based on vertices defined by the application Note
The static RoI vertices must meet the following constraints:
- The vertices must form a convex polygon
- The x and y of each vertex must have a value between 0.0 to 1.0, representing a percentage of the image's width and height, respectively
-
makeLaneRoi
: The lane RoI is generated based on the output of the Road Lanes model - The primary region is defined by the 2 ego lane markings
- The secondary region is defined by the adjacent lane markings, if present
Note
If you are using LSModelManager
class for model detection, you have to set the LSModelManager#setRecognitionProcessor()
callback so that you can filter results using Roi
before they are passed to recognition callback and tracker.
Alerts
Live Sense SDK supports several types of alerts via the LSDAlertManager
class.
Entry
Entry alerts signal to the application when a detection first enters the primary RoI region.
These alerts support pedestrian detection to alert the driver when a pedestrian has entered the road, and vehicle detection to alert of another vehicle merging into the ego lane.
Lane Departure
A lane departure alert indicates the subject vehicle is leaving the ego lane and entering the adjacent region.
There are two severity levels of lane departure alerts:
-
WARNING
: The subject vehicle is likely drifting from their lane rather than intentionally changing lanes. -
INFO
: The subject vehicle has departed from the lane.
Note
For lane departure alerts, the SDK assumes the following:
- The camera is reasonably well centered within the vehicle and facing straight ahead.
- If the camera is placed too far to one side of the vehicle, the SDK may generate false positive alerts.
- The camera has a field of view similar to a phone's wide angle camera
- Ultra wide lenses cause false positive alerts.
TTC - Time to Collision
Live Sense SDK provides the feature of alerting the user/driver of Time to Collision. This feature helps to avoid accidents and ensure driver safety. This feature is applicable to car
, car-brake-light-on
, and pedestrian
detections in the vehicle's expected path. Time to Collision, or TTC, is calculated as follows:
Time to Collision (T) = -1 * d / ( Δd / Δt ) when Δd < 0
- d = distance to the object
- Δd = change in distance to the object between processed frames
- Δt = change in time between processed frames
This calculation only applies when the distance to an object is decreasing. Otherwise, TTC is infinite and no alert is generated.
LSDAlertManager
contains extra heuristics for alerting user of possible hazards in their path. These include time-to-collision with the leading vehicle and people entering the vehicle's direct path.
The following list describes the different severity of alerts based on the value of TTC:
-
INFO
- If T > 2.5secs -
WARNING
- If 1.8secs < T <= 2.5secs -
ALERT
- If T <= 1.8secs
These are the default configured values. The values for WARNING
and ALERT
can be changed by the following methods:
public void setTimeToCollisionWarning(float timeInSeconds)
public void setTimeToCollisionAlert(float timeInSeconds)
For LSDAlertManager
to fully function it requires the following inputs:
- Certain properties of the camera being used. For more information, see
LSDCameraProperties
. - This only needs to be set once per camera setup. This does not include device rotation.
- The vehicle's current speed, normally provided by the device's location services.
- This should be continuously fed in via
setCurrentSpeed()
using device accelerometer or GPS.
- The latest collection of
LSDObjectRecognition
. - Continuously fed in via
determineAlerts()
.
The LSDAlertManager.onAlerts
property is available for an asynchronous feed of alerts.
Usage
Kotlin
val alertManager = LSDAlertManager()
alertManager.setCameraProperties(cameraController.cameraProperties)
alertManager.onAlerts.addListener { alerts: MutableList<LSDAlert> ->
}
alertManager.setCurrentSpeed(speedMetersPerSecond)
alertManager.determineAlerts(objectRecognitions, imageWidth, imageHeight, imageRotation, imageTimestamp)
Java
LSDAlertManager alertManager = new LSDAlertManager();
alertManager.setCameraProperties(cameraController.getCameraProperties());
alertManager.onAlerts.addListener(lsdAlerts -> {
});
alertManager.setCurrentSpeed(speedMetersPerSecond);
alertManager.determineAlerts(objectRecognitions, imageWidth, imageHeight, imageRotation, imageTimestamp);