Skip to content

README.md

Latest commit

 

History

History
315 lines (274 loc) · 11.9 KB

README.md

File metadata and controls

315 lines (274 loc) · 11.9 KB

Copyright (C) 2024, Axis Communications AB, Lund, Sweden. All Rights Reserved.

ACAP application consuming AXIS Scene Metadata

Important

  • The Message Broker API is released as a Beta API. To get all topics that can be subscribed to, see more information in the API documentation.
  • In ACAP Native SDK 1.13 which maps to AXIS OS 11.9:
    • Metadata Broker API was released as a Beta API.
    • In this release there's only one topic (com.axis.analytics_scene_description.v0.beta) that can be subscribed to.
  • In ACAP Native SDK 1.15 which maps to AXIS OS 11.11, there are the following updates:
  • In ACAP Native SDK 12.0 which maps to AXIS OS 12.0:
    • The Metadata Broker API has been renamed to Message Broker API.

Use case

  • Consume streamed analytics metadata of detected objects in the scene.

Introduction

This example showcases how an ACAP application can consume frame-by-frame scene metadata in AXIS OS by using the Message Broker API. To learn more about analytics metadata generated by Axis devices see AXIS Scene Metadata integration.

The ACAP application is a consumer that subscribes to the topic com.axis.analytics_scene_description.v0.beta.

Example data with multiple detections:

{
   "frame" : {
      "observations" : [
         {
            "bounding_box" : {
               "bottom" : 0.7413,
               "left" : 0.4396,
               "right" : 0.7661,
               "top" : 0.4234
            },
            "class" : {
               "score" : 0.74,
               "type" : "Car"
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "25"
         },
         {
            "bounding_box" : {
               "bottom" : 0.9431,
               "left" : 0.9656,
               "right" : 0.9989,
               "top" : 0.8365
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "26"
         },
         {
            "bounding_box" : {
               "bottom" : 0.839,
               "left" : 0.8295,
               "right" : 0.9782,
               "top" : 0.2037
            },
            "class" : {
               "score" : 0.75,
               "type" : "Human"
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "37"
         },
         {
            "bounding_box" : {
               "bottom" : 0.9395,
               "left" : 0.0219,
               "right" : 0.6531,
               "top" : 0.002
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "46"
         },
         {
            "bounding_box" : {
               "bottom" : 0.3181,
               "left" : 0.7094,
               "right" : 0.8114,
               "top" : 0.1012
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "48"
         }
      ],
      "operations" : [
         {
            "id" : "35",
            "type" : "DeleteOperation"
         },
         {
            "id" : "47",
            "type" : "DeleteOperation"
         }
      ],
      "timestamp" : "2024-02-14T15:37:21.040577Z"
   }
}

Getting started

These instructions will guide you on how to execute the code. Below is the structure and scripts used in the example:

consume-scene-metadata
├── app
│   ├── LICENSE
│   ├── Makefile
│   ├── manifest.json
│   └── consume_scene_metadata.c
├── Dockerfile
└── README.md
  • app/LICENSE - Text file which lists all open source licensed source code distributed with the application.
  • app/Makefile - Build and link instructions for the application.
  • app/manifest.json - Defines the application and its configuration.
  • app/consume_scene_metadata.c - Application source code.
  • Dockerfile - Assembles an image containing the ACAP Native SDK and builds the application using it.
  • README.md - Step by step instructions on how to run the example.

How to run the code

Below is the step by step instructions on how to execute the program. So basically starting with the generation of the .eap file to running it on a device:

Build the application

Standing in your working directory run the following commands:

Note

Depending on the network your local build machine is connected to, you may need to add proxy settings for Docker. See Proxy in build time.

docker build --platform=linux/amd64 --tag <APP_IMAGE> --build-arg ARCH=<ARCH> .
  • <APP_IMAGE> is the name to tag the image with, e.g., consume_scene_metadata:1.0
  • <ARCH> is the SDK architecture, armv7hf or aarch64.

Copy the result from the container image to a local directory build:

docker cp $(docker create --platform=linux/amd64 <APP_IMAGE>):/opt/app ./build

The working directory now contains a build folder with the following files:

consume-scene-metadata
├── app
│   ├── LICENSE
│   ├── Makefile
│   ├── manifest.json
│   └── consume_scene_metadata.c
├── build
│   ├── LICENSE
│   ├── Makefile
│   ├── manifest.json
│   ├── package.conf
│   ├── param.conf
│   ├── consume_scene_metadata*
│   ├── consume_scene_metadata_1_0_0_armv7hf.eap
│   ├── consume_scene_metadata_1_0_0_LICENSE.txt
│   └── consume_scene_metadata.c
├── Dockerfile
└── README.md
  • build/manifest.json - Defines the application and its configuration.
  • build/package.conf - Defines the application and its configuration.
  • build/param.conf - File containing application parameters.
  • build/consume_scene_metadata* - Application executable binary file.
  • build/consume_scene_metadata_1_0_0_armv7hf.eap - Application package .eap file.
  • build/consume_scene_metadata_1_0_0_LICENSE.txt - Copy of LICENSE file.

Install your application

Browse to the application page of the Axis device:

http://<AXIS_DEVICE_IP>/index.html#apps

  1. Click on the tab Apps in the device GUI

  2. Enable Allow unsigned apps toggle

  3. Click (+ Add app) button to upload the application file

  4. Select the newly built application package, depending on architecture:

    • consume_scene_metadata_1_0_0_aarch64.eap
    • consume_scene_metadata_1_0_0_armv7hf.eap

  5. Click Install

  6. Run the application by enabling the Start switch

The expected output

The application log can be found at

  • Browse to http://<AXIS_DEVICE_IP>/axis-cgi/admin/systemlog.cgi?appname=consume_scene_metadata.

Important

The logged output can have data which is empty or has a detection. To get a detection, make sure to have an object that can be detected by the Axis device scene data. Examples are persons and cars.

----- Contents of SYSTEM_LOG for 'consume_scene_metadata' -----

consume_scene_metadata[3844]: Subscribed to com.axis.analytics_scene_description.v0.beta (1)...
consume_scene_metadata[3844]: Subscriber started...
consume_scene_metadata[3844]: message received from topic: com.axis.analytics_scene_description.v0.beta on source: 1: Monotonic time - 483.054847000. Data - {"frame":{"observations":[{"bounding_box":{"bottom":0.7384,"left":0.4254,"right":0.7552,"top":0.4216},"class":{"score":0.74,"type":"Car"},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"25"},{"bounding_box":{"bottom":0.9431,"left":0.9656,"right":0.9989,"top":0.8384},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"26"},{"bounding_box":{"bottom":0.8378,"left":0.8102,"right":0.9693,"top":0.1988},"class":{"score":0.75,"type":"Human"},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"37"},{"bounding_box":{"bottom":0.0553,"left":0.727,"right":0.7499,"top":0.0443},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"44"},{"bounding_box":{"bottom":0.7997,"left":0.9833,"right":0.9989,"top":0.7262},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"45"},{"bounding_box":{"bottom":0.9689,"left":0.0208,"right":0.6354,"top":0.002},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"46"},{"bounding_box":{"bottom":0.3236,"left":0.7083,"right":0.8041,"top":0.0994},"timestamp":"2024-02-14T15:37:20.940582Z","track_id":"48"}],"operations":[],"timestamp":"2024-02-14T15:37:20.940582Z"}}
consume_scene_metadata[3844]: message received from topic: com.axis.analytics_scene_description.v0.beta on source: 1: Monotonic time - 483.154843000. Data - {"frame":{"observations":[{"bounding_box":{"bottom":0.7413,"left":0.4396,"right":0.7661,"top":0.4234},"class":{"score":0.74,"type":"Car"},"timestamp":"2024-02-14T15:37:21.040577Z","track_id":"25"},{"bounding_box":{"bottom":0.9431,"left":0.9656,"right":0.9989,"top":0.8365},"timestamp":"2024-02-14T15:37:21.040577Z","track_id":"26"},{"bounding_box":{"bottom":0.839,"left":0.8295,"right":0.9782,"top":0.2037},"class":{"score":0.75,"type":"Human"},"timestamp":"2024-02-14T15:37:21.040577Z","track_id":"37"},{"bounding_box":{"bottom":0.9395,"left":0.0219,"right":0.6531,"top":0.002},"timestamp":"2024-02-14T15:37:21.040577Z","track_id":"46"},{"bounding_box":{"bottom":0.3181,"left":0.7094,"right":0.8114,"top":0.1012},"timestamp":"2024-02-14T15:37:21.040577Z","track_id":"48"}],"operations":[{"id":"35","type":"DeleteOperation"},{"id":"47","type":"DeleteOperation"}],"timestamp":"2024-02-14T15:37:21.040577Z"}}

The format of a detection shown in a more readable way.

{
   "frame" : {
      "observations" : [
         {
            "bounding_box" : {
               "bottom" : 0.7413,
               "left" : 0.4396,
               "right" : 0.7661,
               "top" : 0.4234
            },
            "class" : {
               "score" : 0.74,
               "type" : "Car"
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "25"
         },
         {
            "bounding_box" : {
               "bottom" : 0.9431,
               "left" : 0.9656,
               "right" : 0.9989,
               "top" : 0.8365
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "26"
         },
         {
            "bounding_box" : {
               "bottom" : 0.839,
               "left" : 0.8295,
               "right" : 0.9782,
               "top" : 0.2037
            },
            "class" : {
               "score" : 0.75,
               "type" : "Human"
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "37"
         },
         {
            "bounding_box" : {
               "bottom" : 0.9395,
               "left" : 0.0219,
               "right" : 0.6531,
               "top" : 0.002
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "46"
         },
         {
            "bounding_box" : {
               "bottom" : 0.3181,
               "left" : 0.7094,
               "right" : 0.8114,
               "top" : 0.1012
            },
            "timestamp" : "2024-02-14T15:37:21.040577Z",
            "track_id" : "48"
         }
      ],
      "operations" : [
         {
            "id" : "35",
            "type" : "DeleteOperation"
         },
         {
            "id" : "47",
            "type" : "DeleteOperation"
         }
      ],
      "timestamp" : "2024-02-14T15:37:21.040577Z"
   }
}

License

Apache License 2.0