Getting Started

📋 Prerequisites

Ubuntu 24.04 or newer (Linux recommended), Desktop edition (or Server edition with GUI installed).
Docker
Make (sudo apt install make)
Python 3 (sudo apt install python3) - required for video download and validation scripts
Intel hardware (CPU, iGPU, dGPU, NPU)
Intel drivers:
- Intel GPU drivers
- NPU
Sufficient disk space for models, videos, and results

Note

First-time setup downloads AI models, sample videos, and Docker images - this may take 5-15 minutes depending on your internet connection.

Choose Your Workload Type

🛡️ Loss Prevention

Purpose: Detect theft, suspicious behavior, and inventory shrinkage
Use When: You want to monitor customer interactions and prevent loss
Includes: Hidden items detection, fake scan detection, product switching alerts

🛒 Automated Self-Checkout

Purpose: Validate customer scanning and detect checkout fraud
Use When: You want to ensure proper product scanning at self-checkout stations
Options: Object detection, age verification, product classification

🧠 Enhanced Loss Prevention with LVLM

Purpose: Advanced item recognition using Large Vision Language Models
Use When: You need higher accuracy for complex items or edge cases
Includes: Agent-based LVLM invocation, traditional CV fallback, improved item identification

Quick Configuration Reference

🛡️ Loss Prevention Hardware Options

Configuration	Command	Best For
CPU (Default)	`make run-lp RENDER_MODE=1`	Basic setups, testing
GPU	`make run-lp WORKLOAD_DIST=workload_to_pipeline_gpu.json RENDER_MODE=1`	Performance, real-time processing
NPU + GPU	`make run-lp WORKLOAD_DIST=workload_to_pipeline_gpu-npu.json RENDER_MODE=1`	Latest Intel hardware
Heterogeneous	`make run-lp WORKLOAD_DIST=workload_to_pipeline_hetero.json RENDER_MODE=1`	Mixed workloads across hardware
VLM	`make run-lp STREAM_LOOP=false CAMERA_STREAM=camera_to_workload_vlm.json WORKLOAD_DIST=workload_to_pipeline_vlm.json RENDER_MODE=1`	Advanced AI-powered detection

Included Detection Types: Hidden items, fake scanning, product switching, multi-product ID, sweet-heartening

🛒 Automated Self-Checkout Quick Commands

Object Detection (Identify scanned products):

# GPU (recommended)
make run-lp CAMERA_STREAM=camera_to_workload_asc_object_detection.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_gpu.json RENDER_MODE=1

# CPU alternative
make run-lp CAMERA_STREAM=camera_to_workload_asc_object_detection.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json RENDER_MODE=1

Age Verification (Age-restricted products):

# GPU (recommended)
make run-lp CAMERA_STREAM=camera_to_workload_asc_age_verification.json WORKLOAD_DIST=workload_to_pipeline_asc_age_verification_gpu.json RENDER_MODE=1

Combined Detection & Classification:

# GPU (recommended)
make run-lp CAMERA_STREAM=camera_to_workload_asc_object_detection_classification.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_classification_gpu.json RENDER_MODE=1

Tip

Hardware Selection: Replace _gpu with _cpu or _npu in any command above based on your available hardware.

Complete Reference: For the full configuration matrix with all hardware combinations and detailed specifications, see Complete Workload Configuration Matrix in Advanced Settings.

Step by step instructions:

Clone the repo with the below command

git clone -b <release-or-tag> --single-branch https://github.com/intel-retail/loss-prevention

>Replace with the version you want to clone (for example, v4.0.0).

git clone -b v4.0.0 --single-branch https://github.com/intel-retail/loss-prevention

Run Loss Prevention (Recommended for First Time)

Simple Setup with Visual Output:
```
# RENDER_MODE=1 shows live video with detection boxes (recommended for first run)
make run-lp RENDER_MODE=1
```
Alternative Options:
```
# Headless mode - no visual output (for servers or automated testing)
make run-lp
```
What This Does: - Downloads AI models (YOLOv5, EfficientNet) - Downloads sample videos for testing
- Starts the loss prevention pipeline - Enables 6 detection types: hidden items, fake scanning, product switching, etc. - Visual mode shows real-time detection boxes and alerts

Run Automated Self-Checkout Workloads

Object Detection (Identifies scanned products):

# GPU accelerated - recommended for performance
CAMERA_STREAM=camera_to_workload_asc_object_detection.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_gpu.json make run-lp RENDER_MODE=1

# CPU version - for systems without GPU
CAMERA_STREAM=camera_to_workload_asc_object_detection.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_cpu.json make run-lp RENDER_MODE=1

Age Verification (For age-restricted products):

# Detects customer age for alcohol/tobacco purchases
CAMERA_STREAM=camera_to_workload_asc_age_verification.json WORKLOAD_DIST=workload_to_pipeline_asc_age_verification_gpu.json make run-lp RENDER_MODE=1

Combined Detection & Classification:

# Both identifies AND categorizes products
CAMERA_STREAM=camera_to_workload_asc_object_detection_classification.json WORKLOAD_DIST=workload_to_pipeline_asc_object_detection_classification_gpu.json make run-lp RENDER_MODE=1

Tip

Display Options: Add RENDER_MODE=1 to any command above to see live video with detection boxes. Remove it for headless operation (servers/automation).

Choose Your Hardware: Replace _gpu with _cpu or _npu based on your available hardware. See Automated Self-Checkout Configurations for all options.

What You'll See When Working

🛡️ Loss Prevention Results

Visual: Red bounding boxes around suspicious activities
Alerts: Console notifications for hidden items, fake scanning, product switching
Logs: Detection confidence scores and behavior analysis

🛒 Automated Self-Checkout Results

Object Detection: Green boxes around identified products with labels
Age Verification: Face detection boxes with estimated age ranges
Classification: Product categories and scanning validation status

Expected Performance

Startup Time: 2-5 minutes (first run includes downloads)
Processing: Real-time video analysis at 15-30 FPS
Results: JSON files appear in results/ folder within seconds

Verify Results

After starting Loss Prevention you will begin to see result files being written into the results/ directory. Here are example outputs from the 3 log files.

gst-launch__gst.log

/GstPipeline:pipeline0/GstGvaWatermark:gvawatermark0/GstCapsFilter:capsfilter1: caps = video/x-raw(memory:VASurface), format=(string)RGBA
/GstPipeline:pipeline0/GstFPSDisplaySink:fpsdisplaysink0/GstXImageSink:ximagesink0: sync = true
Got context from element 'vaapipostproc1': gst.vaapi.Display=context, gst.vaapi.Display=(GstVaapiDisplay)"\(GstVaapiDisplayGLX\)\ vaapidisplayglx0", gst.vaapi.Display.GObject=(GstObject)"\(GstVaapiDisplayGLX\)\ vaapidisplayglx0";
Progress: (open) Opening Stream
Pipeline is PREROLLED ...
Prerolled, waiting for progress to finish...
Progress: (connect) Connecting to rtsp://localhost:8554/camera_0
Progress: (open) Retrieving server options
Progress: (open) Retrieving media info
Progress: (request) SETUP stream 0

pipeline_gst.log

r_gst.jsonl

{
    "objects": [
        {
            "detection": {
                "bounding_box": {
                    "x_max": 0.7873924346958825,
                    "x_min": 0.6701603093745723,
                    "y_max": 0.7915918938548927,
                    "y_min": 0.14599881349270305
                },
                "confidence": 0.8677337765693665,
                "label": "apple",
                "label_id": 39
            },
            "h": 697,
            "region_id": 610,
            "roi_type": "apple",
            "w": 225,
            "x": 1287,
            "y": 158
        },
        {
            "detection": {
                "bounding_box": {
                    "x_max": 0.3221945836811382,
                    "x_min": 0.19950163649114616,
                    "y_max": 0.7924592239981934,
                    "y_min": 0.1336837231479251
                },
                "confidence": 0.8625879287719727,
                "label": "apple",
                "label_id": 39
            },
            "h": 711,
            "region_id": 611,
            "roi_type": "apple",
            "w": 236,
            "x": 383,
            "y": 144
        },
        {
            "detection": {
                "bounding_box": {
                    "x_max": 0.5730873789069046,
                    "x_min": 0.42000878963365595,
                    "y_max": 0.9749763191740435,
                    "y_min": 0.12431765065780453
                },
                "confidence": 0.854443371295929,
                "label": "apple",
                "label_id": 39
            },
            "h": 919,
            "region_id": 612,
            "roi_type": "apple",
            "w": 294,
            "x": 806,
            "y": 134
        }
    ],
    "resolution": {
        "height": 1080,
        "width": 1920
    },
    "timestamp": 755106652
}