Create new articles under how it works

sgolebiewski-intel · sgolebiewski-intel · commit 2b577f23f754 · 2026-02-13T14:46:39.000+01:00
Signed-off-by: Sebastian Golebiewski &lt;sebastianx.golebiewski@intel.com&gt;
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/README.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/README.md
@@ -8,42 +8,40 @@ Enabling such use cases across multiple viewpoints helps in understanding the ob
 
 ## Key Features
 
-**Multi vision**:
-
-Scene-based analytics allow insights beyond single sensor views.
+**Multi vision**: Scene-based analytics allow insights beyond single sensor views.
 
 - **Vehicle axle detection**:
 
-  Vehicle class is determined based on axle and wheel count.\
-  Intended for toll classification, as well as revenue calculation and protection.\
-  Multi view and the advanced "lift axle" detection using computer vision
-  ensures accurate tariffing.
-
-- **License plate detection**:
+  Vehicle class is determined based on axle and wheel count. Intended for toll
+  classification, as well as revenue calculation and protection.
 
-  The application identifies vehicles uniquely by their license plates, which are
-  read from both front and rear views.\
-  The image evidence is included in every transaction for simplified auditing.
+- **Lift axle detection**:
 
-**Visualization & analytics**:
+  The type of axle is determined based on camera feed. Ensures accurate tariffing,
+  as lift axles may affect toll classification even when raised.
 
-Provides real-time and historical insights for toll operators.
+- **License plate detection**:
 
-**Modularity**:
+  The application identifies vehicles uniquely by their license plates, which are
+  read from both front and rear views. The image evidence is included in every
+  transaction for simplified auditing.
 
-Architecture based on modular microservices enables composability and reconfiguration.
+**Visualization & analytics**: Provides real-time and historical insights for
+toll operators.
 
-**High-throughput processing**:
+**Modularity**: Architecture based on modular microservices enables composability
+and reconfiguration.
 
-Optimized video pipelines for Intel edge devices.
+**High-throughput processing**: [Optimized video pipelines](./docs/user-guide/how-it-works/optimization.md#zero-copy-video-pipeline)
+for Intel edge devices.
 
 ## How it Works
 
 The system uses the **Metro Edge Architecture** based on three key principles:
 
-- **Perception**: Deep Learning Streamer (DLStreamer) [processes 3/4 camera feeds](./docs/user-guide/perception-layer.md).
+- **Perception**: Deep Learning Streamer (DLStreamer) [processes 3/4 camera feeds](./docs/user-guide/how-it-works/perception-layer.md).
 - **Control**: SceneScape Controller [aggregates metadata](./docs/user-guide/how-it-works.md#analytics-pipeline-downstream).
-- **Analytics**: Node-RED [transforms events into traffic insights](./docs/user-guide/how-it-works.md#node-red-transformation)
+- **Analytics**: Node-RED [transforms events into traffic insights](./docs/user-guide/how-it-works/analytics-pipeline.md#node-red-transformation)
   (Traffic Volume, Flow Efficiency, Tariffing).
 
 ## Learn More
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works.md
@@ -19,24 +19,24 @@ The application can be configured to work with live cameras.
 
 ### Core (Processing)
 
-- [**Video Analytics**](./perception-layer.md) - Deep Learning Streamer Pipeline Server
+- [**Video Analytics**](./how-it-works/perception-layer.md) - Deep Learning Streamer Pipeline Server
   (DL Streamer Pipeline Server) utilizes a pre-trained object detection model
-  to [generate object detection metadata](#zero-copy-video-pipeline) and and a local
+  to [generate object detection metadata](./how-it-works/#zero-copy-video-pipeline) and and a local
   NTP server for synchronized timestamps. This metadata is published to the MQTT broker.
 - **Sensor Fusion** - Scene Controller Microservice fuses the metadata from
   video analytics utilizing scene data obtained through the Scene Management API.
   It uses the fused tracks and the configured analytics (regions of interest)
   to generate events that are published to the MQTT broker.
-- [**Aggregate Scene Analytics**](#node-red-transformation) - Region of interests
+- [**Aggregate Scene Analytics**](./how-it-works/analytics-pipeline.md#node-red-transformation) - Region of interests
   analytics are read from the MQTT broker and
-  [stored in an InfluxDB bucket](#storage-influxdb) that enables time series
+  [stored in an InfluxDB bucket](./how-it-works/analytics-pipeline.md#storage-influxdb) that enables time series
   analysis through Flux queries.
 
 ### Live Feed Output
 
 - Fused object tracks are available on the MQTT broker and visualized through
   the Scene Management UI.
-- [Aggregated toll analytics](#analytics-pipeline-downstream) are visualized
+- [Aggregated toll analytics](./how-it-works/analytics-pipeline.md) are visualized
   through a Grafana dashboard.
 
 ### Workflow
@@ -51,65 +51,11 @@ The application can be configured to work with live cameras.
 8. Grafana visualizes real time and historical data enabling access to metrics
    and vehicle details.
 
-## Optimizations
-
-The system achieves high-throughput processing on Edge hardware through specific
-optimizations defined in `config.json`. The [`docker-compose.yml`](./_assets/docker-compose.yml)
-file mentions all the services and the pipelines are configured in `config.json` file.
-
-### Zero-Copy Video Pipeline
-
-Unlike standard OpenCV pipelines that copy frames to CPU RAM, this solution utilizes **VASurface Sharing plugin**.
-
-- **Mechanism:** Decoded video frames remain in GPU memory (`video/x-raw(memory:VAMemory)`).
-- **Benefit:** Zero-copy inference eliminates PCIe bandwidth bottlenecks, reducing end-to-end latency by ~40%.
-- **Config Evidence:** `pre-process-backend=va-surface-sharing` used in all `gvadetect` elements.
-
-### Dynamic ROI Inference (Hierarchical Execution)
-
-To maximize efficiency, heavy neural networks (like Axle Counting) do not run on the full 4K frame.
-
-- **Logic:** The "Vehicle Type" model runs first to find the bounding box.
-- **Optimization:** The Axle model is configured with `inference-region=roi-list`,
-  forcing it to execute *only* within the coordinates of the detected vehicle.
-- **Impact:** Reduces pixel processing load by >80% for sparse traffic scenes.
-
-### Hybrid Workload Distribution
-
-The pipeline intelligently maps models to available accelerators to prevent resource contention:
-
-- **GPU (Flex Series):** Handles heavy convolution tasks (Vehicle Detection, LPR, Axle Counting).
-- **CPU (Xeon):** Handles lighter classification tasks (Vehicle Color) and post-processing adapters (`gvapython`).
-
-## Analytics Pipeline (Downstream)
-
-Raw metadata is valuable, but actionable insights come from the Analytics Pipeline.
-
-## Node-RED Transformation
-
-- **Input:** The **MQTT IN Node** subscribes to `scenescape/event/region/+/+/objects`.
-- **Logic:** The **Function node** aggregates counts per region and calculates **Dwell Time** (congestion).
-- **Output:** The **InfluxDB OUT Node** writes normalized data points to InfluxDB.
-
-![Node-RED Flow](./_assets/smart_tolling_nodered.png)
-
-### Storage (InfluxDB)
-
-InfluxDB acts as a single source of truth. All critical and shared data is
-stored in one location, ensuring every user and system accesses the same,
-accurate and consistent information.
-
-![InfluxDB Dashboard 1](./_assets/smart_tolling_influx_db.png)
-
-### Visualization (Grafana)
-
-The system ships with a pre-configured dashboard (`anthem-intersection.json` schema)
-focusing on Traffic Volume, Flow Efficiency and Safety Alerts.
-
-![Grafana Dashboard 1](./_assets/garfana_Dashboard1.png)
-
 ## Learn More
 
+- [Perception Layer](./how-it-works/perception-layer.md)
+- [Optimizations](./how-it-works/optimization.md)
+- [Analytics Pipeline](./how-it-works/analytics-pipeline.md)
 - [System Requirements](./get-started/system-requirements.md)
 - [Get Started](./get-started.md)
 - [API Reference](./api-reference.md)
@@ -120,6 +66,8 @@ focusing on Traffic Volume, Flow Efficiency and Safety Alerts.
 :hidden:
 
 ./perception-layer
+./optimization
+./analytics-pipeline
 
 :::
 hide_directive-->
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works/analytics-pipeline.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works/analytics-pipeline.md
@@ -0,0 +1,32 @@
+# Analytics Pipeline (Downstream)
+
+Raw metadata is valuable, but actionable insights come from the Analytics Pipeline.
+
+## Node-RED Transformation
+
+- **Input:** The **MQTT IN Node** subscribes to `scenescape/event/region/+/+/objects`.
+- **Logic:** The **Function node** aggregates counts per region and calculates **Dwell Time** (congestion).
+- **Output:** The **InfluxDB OUT Node** writes normalized data points to InfluxDB.
+
+![Node-RED Flow](../_assets/smart_tolling_nodered.png)
+
+### Storage (InfluxDB)
+
+InfluxDB acts as a single source of truth. All critical and shared data is
+stored in one location, ensuring every user and system accesses the same,
+accurate and consistent information.
+
+![InfluxDB Dashboard 1](../_assets/smart_tolling_influx_db.png)
+
+### Visualization (Grafana)
+
+The system ships with a pre-configured dashboard (`anthem-intersection.json` schema)
+focusing on Traffic Volume, Flow Efficiency and Safety Alerts.
+
+![Grafana Dashboard 1](../_assets/garfana_Dashboard1.png)
+
+## Learn More
+
+- [Perception Layer](./perception-layer.md)
+- [Optimizations](./optimization.md)
+- [Support and Troubleshooting](../troubleshooting.md)
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works/optimization.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works/optimization.md
@@ -0,0 +1,35 @@
+# Optimization
+
+The system achieves high-throughput processing on Edge hardware through specific
+optimizations defined in `config.json`. The [`docker-compose.yml`](../_assets/docker-compose.yml)
+file mentions all the services and the pipelines are configured in `config.json` file.
+
+## Zero-Copy Video Pipeline
+
+Unlike standard OpenCV pipelines that copy frames to CPU RAM, this solution utilizes **VASurface Sharing plugin**.
+
+- **Mechanism:** Decoded video frames remain in GPU memory (`video/x-raw(memory:VAMemory)`).
+- **Benefit:** Zero-copy inference eliminates PCIe bandwidth bottlenecks, reducing end-to-end latency by ~40%.
+- **Config Evidence:** `pre-process-backend=va-surface-sharing` used in all `gvadetect` elements.
+
+## Dynamic ROI Inference (Hierarchical Execution)
+
+To maximize efficiency, heavy neural networks (like Axle Counting) do not run on the full 4K frame.
+
+- **Logic:** The "Vehicle Type" model runs first to find the bounding box.
+- **Optimization:** The Axle model is configured with `inference-region=roi-list`,
+  forcing it to execute *only* within the coordinates of the detected vehicle.
+- **Impact:** Reduces pixel processing load by >80% for sparse traffic scenes.
+
+## Hybrid Workload Distribution
+
+The pipeline intelligently maps models to available accelerators to prevent resource contention:
+
+- **GPU (Flex Series):** Handles heavy convolution tasks (Vehicle Detection, LPR, Axle Counting).
+- **CPU (Xeon):** Handles lighter classification tasks (Vehicle Color) and post-processing adapters (`gvapython`).
+
+## Learn More
+
+- [Perception Layer](./perception-layer.md)
+- [Analytics Pipeline](./analytics-pipeline.md)
+- [Support and Troubleshooting](../troubleshooting.md)
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works/perception-layer.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/how-it-works/perception-layer.md
@@ -43,5 +43,6 @@ Instead of sending raw video streams, adapters encode "Evidence Crops" as
 
 ## Learn More
 
-- [Analytics Pipeline](./how-it-works.md)
-- [Support and Troubleshooting](./troubleshooting.md)
+- [Optimizations](./optimization.md)
+- [Analytics Pipeline](../how-it-works.md)
+- [Support and Troubleshooting](../troubleshooting.md)
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/index.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/index.md
@@ -13,42 +13,40 @@ efficiency.
 
 ## Key Features
 
-**Multi vision**:
-
-Scene-based analytics allow insights beyond single sensor views.
+**Multi vision**: Scene-based analytics allow insights beyond single sensor views.
 
 - **Vehicle axle detection**:
 
-  Vehicle class is determined based on axle and wheel count.\
-  Intended for toll classification, as well as revenue calculation and protection.\
-  Multi view and the advanced "lift axle" detection using computer vision
-  ensures accurate tariffing.
-
-- **License plate detection**:
+  Vehicle class is determined based on axle and wheel count. Intended for toll
+  classification, as well as revenue calculation and protection.
 
-  The application identifies vehicles uniquely by their license plates, which are
-  read from both front and rear views.\
-  The image evidence is included in every transaction for simplified auditing.
+- **Lift axle detection**:
 
-**Visualization & analytics**:
+  The type of axle is determined based on camera feed. Ensures accurate tariffing,
+  as lift axles may affect toll classification even when raised.
 
-Provides real-time and historical insights for toll operators.
+- **License plate detection**:
 
-**Modularity**:
+  The application identifies vehicles uniquely by their license plates, which are
+  read from both front and rear views. The image evidence is included in every
+  transaction for simplified auditing.
 
-Architecture based on modular microservices enables composability and reconfiguration.
+**Visualization & analytics**: Provides real-time and historical insights for
+toll operators.
 
-**High-throughput processing**:
+**Modularity**: Architecture based on modular microservices enables composability
+and reconfiguration.
 
-[Optimized video pipelines](./how-it-works.md) for Intel edge devices.
+**High-throughput processing**: [Optimized video pipelines](./how-it-works/optimization.md#zero-copy-video-pipeline)
+for Intel edge devices.
 
 ## How it Works
 
 The system uses the **Metro Edge Architecture** based on three key layers:
 
-- **Perception**: Deep Learning Streamer (DLStreamer) [processes 3/4 camera feeds](./perception-layer.md).
-- **Control**: SceneScape Controller [aggregates metadata](./how-it-works.md#analytics-pipeline-downstream).
-- **Analytics**: Node-RED [transforms events into traffic insights](./how-it-works.md#node-red-transformation)
+- **Perception**: Deep Learning Streamer (DLStreamer) [processes 3/4 camera feeds](./how-it-works/perception-layer.md).
+- **Control**: SceneScape Controller [aggregates metadata](./how-it-works/analytics-pipeline.md).
+- **Analytics**: Node-RED [transforms events into traffic insights](./how-it-works/analytics-pipeline.md#node-red-transformation)
   (Traffic Volume, Flow Efficiency, Tariffing).
 
 ## Learn More
diff --git a/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/troubleshooting.md b/metro-ai-suite/metro-vision-ai-app-recipe/smart-tolling/docs/user-guide/troubleshooting.md
@@ -9,4 +9,7 @@
 
 ## Support Contact
 
-For further assistance, please contact the **Metro Vision AI Support Team**.
+If you run into an unexpected problem or need help with the application, you can
+browse existing issues or
+[create a new one](https://github.com/open-edge-platform/edge-ai-suites/issues)
+in the GitHub issue tracker.
