Starting Feature Demos

Introduction

This guide gives an overview of the UVAP features and aims to teach the user the followings:

Start UVAP for the basic detections.
Visualize the basic detections with Python scripts.
Resolve a few simple use cases.

Requirements

To start the demos, UVAP needs to be installed first. For detailed instructions and more information, see Installation.

Notations

For the notations used in this document, see Typographic Conventions.

Starting the Analysis

Configuring UVAP

To configure UVAP:

$ "${UVAP_HOME}"/scripts/config.sh --stream-uri [STREAM_URI] \
  --demo-mode [DEMO_MODE]

Where:

[STREAM_URI]

A URI referring to a valid video file or stream. Replace [STREAM_URI] (including brackets) with one of the followings:
- An IP camera, for example:
```
rtsp://192.168.0.1/
```
  The Stream URI can also contain username and password if the stream is protected, for example:
```
rtsp://username:password@192.168.0.1/
```
- A USB device, for example:
```
/dev/video0
```
- A pre-recorded video
Multiple streams to be analyzed may be configured by using more --stream-uri [STREAM_URI] parameter pairs, for example:
```
$ "${UVAP_HOME}"/scripts/config.sh \
  --stream-uri "rtsp://192.168.0.1/" \
  --stream-uri "rtsp://username:password@192.168.0.2/" \
  --stream-uri "rtsp://192.168.0.3/" \
  --demo-mode [DEMO_MODE]
```
The Stream URI(s) can be changed later by running this configuration script again.
[DEMO_MODE]

The demo mode. Different configuration are used for base detections to save GPU resources. Replace [DEMO_MODE] (including the brackets) with a string of the following set:
- base
- fve
- skeleton

There are more optional parameters for the config.sh script to override defaults. Use the --help parameter to get more details:

$ "${UVAP_HOME}"/scripts/config.sh --help

Expected output:

Usage: ./config.sh [OPTION]...

Options (those, that do not have a default value, are mandatory options):
    --demo-mode                                     <base|skeleton|fve>
    --stream-uri                                    file name / device name / RTSP URL of a stream to analyze - may be specified multiple times
    --demo-applications-dir                         directory path of demo applications scripts - default: "${UVAP_HOME}"/scripts/../demo_applications
    --templates-dir                                 directory path of configuration templates - default: "${UVAP_HOME}"/scripts/../templates
    --config-ac-dir                                 directory path of configuration files - will be created if not existent - default: "${UVAP_HOME}"/scripts/../config
    --demo-image-name                               tag of docker image to use - default: will be determined by git tags
    --configurator-image-name                       tag of docker image to use - default: will be determined by git tags
    --host-name                                     the domain name of the host useful to access services remotely - default: localhost
    --web-player-port-number                        default port of the uvap web player ms - default: 9999
    --use-dev-tags                                  if given, docker image tags will be determined via docker-util
    --keep-rate-number                              n means keep every nth frame - default: 1
    --fps-number                                    frame rate - default: 8
    --video-processing-mode                         <mgr|vc> decides which video stream processing mode is used - default: mgr

Running the Components of UVAP

For running the components of UVAP, see the instructions below:

Setting the Retention Period

Kafka has a default retention period set to 168 hours. The *.Image.jpg topics require a large amount of storage space because they contain all frames in JPEG image format. To change the retention period of JPEG topics run the set_retention.sh script.

Attention! By default, the retention period is 0 which means nothing is deleted. Without these settings, the *.Image.jpg topics use a lot of storage.

For guidance on setting the retention period, see the Setting the Retention Period Guide.

Reconfiguring UVAP

UVAP configuration can be modified after starting UVAP successfully. This can come in handy if, for example, desired to switch to a different demo mode.

To modify configuration:

Stop and remove the running Docker containers of UVAP microservices:

$ docker container stop $(docker container ls -a -f 'name=uvap_*' -q)
$ docker container rm $(docker container ls -a -f 'name=uvap_*' -q)

Reconfigure UVAP with the config.sh script as described in Configuring UVAP.
Run the UVAP microservices by starting the demo of your choice. See more details in the following sections.

Demo Usage

Tree view of the demo package

demo_applications/
├── apps
│   └── uvap
│       ├── demography_DEMO.py
│       ├── head_detection_DEMO.py
│       ├── head_pose_DEMO.py
│       ├── list_messages.py
│       ├── list_topics.py
│       ├── pass_detection_DEMO.py
│       ├── reid_with_name_DEMO.py
│       ├── reidentification_DEMO.py
│       ├── show_image_DEMO.py
│       ├── skeleton_DEMO.py
│       └── tracker_DEMO.py
├── resources
│   ├── powered_by_black.png
│   └── powered_by_white.png
└── utils
    ├── kafka
    │   ├── kafka-cli.py
    │   └── time_ordered_generator_with_timeout.py
    ├── uvap
    │   ├── graphics.py
    │   └── uvap.py
    ├── generator_interface.py
    ├── heartbeat.py
    └── jinja_template_filler.py

Environment

All dependencies are packed in a Docker image (ultinous/uvap:uvap_demo_applications_latest). Run the docker container in interactive mode:

$ docker run -it --rm --name "python_env" \
  -v "/tmp/.X11-unix":"/tmp/.X11-unix" \
  -v "${UVAP_HOME}/demo_applications":"/ultinous_app" \
  -e DISPLAY=$DISPLAY \
  -u $(id -u):$(id -g) \
  --net=uvap \
  --env="QT_X11_NO_MITSHM=1" \
  ultinous/uvap:uvap_demo_applications_latest /bin/bash

The scripts in the /apps/uvap folder (see the Tree View of the Demo Package) can be run in the Docker container, and all of them have a help function. For example:

<DOCKER># python3 apps/uvap/show_image_DEMO.py -h

Expected output:

usage: show_image_DEMO.py [-h] [-f] [-d] [-o OFFSET] broker topic

positional arguments:
  broker                The name of the kafka broker.
  topic                 The name of topic (*.Image.jpg).

optional arguments:
  -h, --help            show this help message and exit
  -f, --full_screen
  -d, --dump            if set images are stored in jpg files
  -o OFFSET, --offset OFFSET

Description:
           Plays and optionally dumps video from a jpeg topic (a topic that ends with Image.jpg).

Helper Scripts

The [DEMO_MODE] should be base during the configuration.

The following Kafka data can be listed:

Topics
Messages

List Topics

To list topics from Kafka:

<DOCKER># python3 /ultinous_app/apps/uvap/list_topics.py kafka:9092

Expected output:

base.cam.0.ages.AgeRecord.json
base.cam.0.anonymized_original.Image.jpg
base.cam.0.dets.ObjectDetectionRecord.json
base.cam.0.frameinfo.FrameInfoRecord.json
base.cam.0.genders.GenderRecord.json
base.cam.0.masks.FaceMaskRecord.json
base.cam.0.original.Image.jpg
base.cam.0.poses.HeadPose3DRecord.json
base.cam.0.tracks.TrackChangeRecord.json
base.cam.0.passdet.PassDetectionRecord.json

List Messages

To list messages from a topic:

<DOCKER># python3 /ultinous_app/apps/uvap/list_messages.py kafka:9092 \
          [TOPIC]

Where [TOPIC] is a specified Kafka topic, for example:

<DOCKER># python3 /ultinous_app/apps/uvap/list_messages.py kafka:9092 \
          base.cam.0.genders.GenderRecord.json

Expected output:

1561360391236 <bound method NoKeyErrorDict.asdict of {'base': {'0': {'head_detection': {'1561360391236_0': {'gender': {'gender': 'MALE', 'confidence': 0.952010512, 'end_of_frame': False}}}}}}>
1561360391272 <bound method NoKeyErrorDict.asdict of {'base': {'0': {'head_detection': {'1561360391272_0': {'gender': {'gender': 'MALE', 'confidence': 0.941216767, 'end_of_frame': False}}}}}}>
1561360391304 <bound method NoKeyErrorDict.asdict of {'base': {'0': {'head_detection': {'1561360391304_0': {'gender': {'gender': 'MALE', 'confidence': 0.947949708, 'end_of_frame': False}}}}}}>
1561360391336 <bound method NoKeyErrorDict.asdict of {'base': {'0': {'head_detection': {'1561360391336_0': {'gender': {'gender': 'MALE', 'confidence': 0.919374943, 'end_of_frame': False}}}}}}>

Web Display

There is an alternative way for demo presentation compared to Python scripts displaying in a window. The following demos run in Docker and instead of the display, write their results into Kafka Topics (*[name_of_demo].Image.jpg). From these topics, it is possible to play image streams using the Web Display application.

Starting the Topic Writer Demo

The following script template can be used to start the demos.

Attention! Before starting this microservice, the command below silently stops and removes the Docker container named uvap_demo, if such already exists.

If this script is run in a demo mode for the first time, the demo application is creating a new (*.Image.jpg) topic in Kafka. Similarly to the other JPEG topics, these demo-written-topics consume a lot of storage space, unless their retention time is decreased with the set_retention.sh script; for more information see Setting the Retention Period.

$ "${UVAP_HOME}"/scripts/run_demo.sh \
  --demo-name [NAME_OF_DEMO] \
  --demo-mode [DEMO_MODE] \
  -- --net uvap

Where:

[NAME_OF_DEMO]

The demo name. Replace [NAME_OF_DEMO] (including brackets) with a string from the following set:
- demography
- face_mask
- head_detection
- head_pose
- reid_with_name
- reidentification
- show_image
- skeleton
- tracker
- pass_detection
[DEMO_MODE]

The demo mode. Replace[DEMO_MODE] (including brackets) with a string from the following set:
- base
- skeleton
- fve

The output of the above command contains the following:

Information about pulling the required Docker image
The ID of the Docker container created
The name of the Docker container created: uvap_demo

The available parametrization can be found in the basic, fve and skeleton demo descriptions.

There are more optional parameters for the run_demo.sh script to override defaults. Use the --help parameter to get more details.

Viewing in a Browser

Uvap web player access from client machine (optional); If you want to use the web player from a client machine (different from the processing node), you will have to modify the web player's default config. Open this config file:~/uvap/config/uvap_web_player/uvap_web_player.properties Modify the com.ultinous.uvap.web.player.advertised.host parameter to the <HOST_MACHINE_IP> (default: localhost) Restart uvap_web_player if it is running Restart the web player with the following command:
$ docker restart uvap_web_player
Warning! UVAP config will override this configuration file.

For guidance on starting the web player see Starting Web Player.

Base Mode Demos

The [DEMO_MODE] should be base during the configuration. Base mode demos are the following:

Feature Vector Mode Demos

The [DEMO_MODE] should be fve during the configuration. Feature vector mode Demos are the following:

Skeleton Mode Demos

The [DEMO_MODE] should be skeleton during the configuration. Skeleton mode demos are the following:

Human skeleton

Person Detection

Movement Detection

Facial Properties and Recognition

Image and Video

Starting Microservices

Starting Feature Demos

Introduction

Requirements

Notations

Starting the Analysis

Configuring UVAP

Running the Components of UVAP

Setting the Retention Period

Reconfiguring UVAP

Demo Usage

Tree view of the demo package

Environment

Helper Scripts

List Topics

List Messages

Web Display

Starting the Topic Writer Demo

Viewing in a Browser

Base Mode Demos

Feature Vector Mode Demos

Skeleton Mode Demos