Metropolis Microservices/RidgeRun Services/PTZ: Difference between revisions

Revision as of 16:17, 25 June 2024

‎

Metropolis Microservices for NVIDIA Jetson

Table of Contents [Sticky]

PTZ Microservice is a custom microservice developed by RidgeRun. What makes it special is that it allows you to navigate a 360-degrre video through PTZ. PTZ are the controls available that can be updated at any time during execution, and it means:

PAN (horizontal)
TILT (vertical)
ZOOM (magnify or decrease the view of the image)

This microservice leverages the RidgeRun Spherical Video PTZ to make possible the selection of your region of interest within the sphere.

Briefly, this service gets an RTSP stream, performs the PTZ depending on the user instructions, and then returns as the output the transformed stream using the same protocol, RTSP.

API documentation

Usually, in the Microservices architectures the communication with the outside world is handle through well-defined APIs. This APIs specify methods, data formats, and protocols for interaction.

In our PTZ Microservice, the API documentation can be found here, there you can the list of the available requests.

‎

‎ ‎

‎

Running the service

‎

PTZ Microservice can run as a standalone application or as docker image. The docker approach has some benefits, for example: since the application is encapsulated along with its dependencies, less conflicts arise in the process of deployment.

As a standalone application

Before running the service, you should make sure you have all the dependencies installed. The intructions to do it can be found here: Spherical Video PTZ Building and Installation

Then you have to clone into your device the repository project, available here

The project is configured (via setup.py) to install the service with the name ptz. So to install it run:

pip install .

Then you will have the service with the following options:

usage: ptz [-h] [--port PORT] [--host HOST]

options:
 -h, --help   show this help message and exit
 --port PORT  Port for server
 --host HOST  Server ip address

As a docker image

Before starting with docker support make sure you have nvidia runtime in your system. Follow these instructions to have docker up and runing in your Jetson Board.

Use prebuild image (dockerhub)

docker pull

‎

Build your own image (Dockerfile)

Build the container

We can build the ptz microservice container using the Dockerfile in the docker directory. This includes a base NVIDA image and the dependencies to run the ptz microservice application.

‎

First, we need to prepare the context directory for this build, please create a directory and include all the needed repositories (listed below). The Dockerfile will look for all the source code in the context directory and copy them to the container.

ptz-context/
.
├── gst-cuda
├── gst-rr-panoramaptz
├── gst-rtsp-sink
├── libpanorama
├── ptz
└── rrms-utils

Then build the container image running the the following command from the folder containing the Dockerfile and context directory:

sudo docker build \
--network=host \
-f Dockerfile \
-t ridgerun/ptz-service:latest ptz-context/

Change ptz-context to your context's path and the tag (-t) to the name you want to give to your image.

Launch the container

The container can be launched by running the following command:

sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest

You can modify the name you want to give to your container with the option --name.

Here we are creating a container called ptz-service that will start the ptz-service application in the default address and path. If a different address and port have to be used, you can do it by running:

sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest --host=HOST --port=PORT

Examples

Once you have a ptz-microservices-docker running you can run and test its functionality:

‎

Run the ptz microservice

ptz --host=192.168.100.15 –port=5010

Create an stream RTSP source using this pipeline:

gst-launch-1.0 videotestsrc pattern=0 ! video/x-raw,width=640,height=480 ! queue ! videoconvert ! queue ! videoscale ! video/x-raw,width=1920,height=1080,format=I420 ! queue ! x264enc key-int-max=30 option-string="keyint=30:min-keyint=30:repeat-headers=1" bitrate=10000 ! video/x-h264, mapping=/stream_in ! perf ! rtspsink service=7000  -v

(you can modify th IPs, ports, and mapping depending on your needs. Just make sure you configure the other pipelines to match them)

Set and update the desired ptz values via the API following the format specified in here:

Set the input URI, the output port, and the output mapping (in this example we assume that the RTSP source is being played from the same IP as the ptz microservice):

curl -X PUT -H "Content-Type: application/json" -d '{"in_uri": "rtsp://192.168.100.15:7000/stream_in","out_port": "8000","out_mapping": "/stream_out"}' http://192.168.100.15:5010/stream

(you can modify th IPs, ports, and mapping depending on your needs. Just make sure you configure the other pipelines to match them)

Using the client ****

Receive the output result via RTSP using this pipeline:

gst-launch-1.0 rtspsrc location=rtsp://192.168.100.15:8000/stream_out ! queue ! decodebin ! queue ! videoconvert ! autovideosink -v

(you can modify th IPs, ports, and mapping depending on your needs. Just make sure you configure the other pipelines to match them)

@@ Line 4: / Line 4: @@
-PTZ Microservice allows you to navigate a video through PTZ.
+PTZ Microservice is a custom microservice developed by RidgeRun. What makes it special is that it allows you to navigate a '''360-degrre''' video through PTZ. PTZ are the controls available that can be updated at any time during execution, and it means:
+* PAN (horizontal)
+* TILT (vertical)
+* ZOOM (magnify or decrease the view of the image)
-It leverages the RidgeRun [[ Spherical Video PTZ | Spherical Video PTZ ]] to make possible the selection of your region of interest within the sphere. This is specified through pan (horizontal), tilt (vertical), and zoom controls, which can be updated at any time during execution.
+This microservice leverages the RidgeRun [[ Spherical Video PTZ | Spherical Video PTZ ]] to make possible the selection of your region of interest within the sphere.
-This service receives an RTSP stream, performs the PTZ depending on the user instructions, and then returns the stream using the same protocol, RTSP.
+Briefly, this service gets an RTSP stream, performs the PTZ depending on the user instructions, and then returns as the output the transformed stream using the same protocol, RTSP.
-==API configuration==
-Take a look at the [https://gitlab.ridgerun.com/ridgerun/rnd/jetson-microservices-and-genai/apis/-/blob/develop/ptz/openapi.yaml?ref_type=heads API Documentation] for a list of the available requests.
+==API documentation==
+Usually, in the Microservices architectures the communication  with the outside world is handle through well-defined APIs. This APIs specify methods, data formats, and protocols for interaction.
+In our PTZ Microservice, the API documentation can be found here, there you can the list of the available requests.
 {{Review|We need to point this to the official documentation, not the repo|efernandez}}
 {{Review|We could include here the link to the project documentation|efernandez}}
 ==Running the service==
 {{Review|Here you can specify that the service can be run directly into the host or using docker. Then describe both options|efernandez}}
+PTZ Microservice can run as a standalone application or as docker image. The docker approach has some benefits, for example: since the application is encapsulated along with its dependencies, less conflicts arise in the process of deployment.
+===As a standalone application===
 Before running the service, you should make sure you have all the dependencies installed. The intructions to do it can be found here: [https://developer.ridgerun.com/wiki/index.php/Spherical_Video_PTZ/User_Guide/Building_and_Installation Spherical Video PTZ Building and Installation]
@@ Line 42: / Line 55: @@
 </pre>
-==PTZ Microservice Docker==
+===As a docker image===
+Before starting with docker support make sure you have nvidia runtime in your system. Follow [https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuration these instructions] to have docker up and runing in your Jetson Board.
-*****dockerhub?
+====Use prebuild image (dockerhub) ====
+docker pull
 {{Review|The service will be hosted in dockerhub, when uploaded we will update this section|efernandez}}
-Before starting with docker support make sure you have nvidia runtime in your system. Follow [https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuration these instructions] to have docker up and runing in your Jetson Board.
+====Build your own image (Dockerfile)====
 ===Build the container===
 We can build the ptz microservice container using the Dockerfile in the docker directory. This includes a base NVIDA image and the dependencies to run the ptz microservice application.
+{{Review|Add link to the repository|mortigoza}}
 First, we need to prepare the context directory for this build, please create a directory and include all the needed repositories (listed below). The Dockerfile will look for all the source code in the context directory and copy them to the container.
@@ Line 94: / Line 117: @@
 sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest --host=HOST --port=PORT
 </pre>
 ==Examples==