RidgeRun Developer Wiki

Metropolis Microservices/RidgeRun Services/PTZ: Difference between revisions

Page Discussion

Metropolis Microservices/RidgeRun Services/PTZ (view source)

Revision as of 19:51, 25 June 2024

347 bytes added ,  25 June
no edit summary
No edit summary
No edit summary
Line 4: Line 4:




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:
PTZ Microservice is a microservice developed by RidgeRun. It allows you to navigate a '''360-degrre''' video through pan, tilt, and zoom (PTZ).
* PAN (horizontal)
* TILT (vertical)
* ZOOM (magnify or decrease the view of the image)


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 microservice leverages the RidgeRun [[ Spherical Video PTZ | Spherical Video PTZ ]] to make possible the selection of your region of interest within the sphere.  
Line 13: Line 10:
Briefly, this service works in this way:
Briefly, this service works in this way:
# Gets an RTSP stream as an input
# Gets an RTSP stream as an input
# Performs the PTZ depending on the user instructions,
# Performs the PTZ depending on user instructions
# Returns as the output the transformed stream using the same protocol, RTSP.
# Returns the transformed video as a separate RTPS stream


{{Review|Add link to the technical documentation?|mortigoza}}
{{Review|Add link to the technical documentation?|mortigoza}}


==API documentation==
==Service 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.
This microservice can be controlled through a REST API and its documentation can be found '''HERE'''


In our PTZ Microservice, the API documentation can be found here, there you can the list of the available requests.
Additionally, the full documentation for the service can be found '''HERE'''


{{Review|We need to point this to the official documentation, not the repo|efernandez}}
{{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}}
{{Review|We could include here the link to the project documentation|efernandez}}




Line 35: Line 30:


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.  
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]
{{Review|Add link to other dependencies as rtsp-sink?|mortigoza}}
Then you have to clone into your device the repository project, available [/ptz here]
{{Review|Add link to the repository|mortigoza}}
The project is configured (via setup.py) to install the service with the name '''ptz'''. So to install it run:
<pre>
pip install .
</pre>
Then you will have the service with the following options:
<pre>
usage: ptz [-h] [--port PORT] [--host HOST] [--ptz-window-size PTZ_WINDOW_SIZE]
options:
  -h, --help            show this help message and exit
  --port PORT          Port for server
  --host HOST          Server ip address
  --ptz-window-size PTZ_WINDOW_SIZE
                        Size of the PTZ output window in pixels. The final resolution will be (Size x Size)
</pre>


===As a docker image===
===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.
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 running in your Jetson Board.


====Use prebuild image ====


====Use prebuild image (dockerhub) ====
For convenience, a docker image is available in dockerhub which as of today is available for Jetpack 6.0. Use the following command to pull it.


<syntaxhighlight lang=bash>
docker pull  
docker pull  
</syntaxhighlight>


{{Review|The service will be hosted in dockerhub, when uploaded we will update this section|efernandez}}
{{Review|The service will be hosted in dockerhub, when uploaded we will update this section|efernandez}}
Line 79: Line 48:
====Build your own image (Dockerfile)====
====Build your own image (Dockerfile)====


 
If you instead want to build your own image, a convenient Dockerfile is included as part of the service.  
 
=====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}}
{{Review|Add link to the repository|mortigoza}}
Line 112: Line 77:




=====Launch the container=====
====Launch the container====
 
The container can be launched by running the following command:


Either if you pulled the prebult image of you built your own, a docker container can be launched by running the following command:


<pre>
<syntaxhighlight lang="bash">
sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest
sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest
</pre>
</syntaxhighlight>


You can modify the name you want to give to your container with the option '''--name'''.
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 port and using the default output resolution. If a different address, port, or output resolution has to be used, you can do it by running:
Here we are creating a container called __ptz-service__ that will start the ptz-service application in the default address and port and using the default output resolution. If a different address, port, or output resolution has to be used, you can do it by running:
<syntaxhighlight lang="bash">
sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest --host=HOST --port=PORT --ptz-window-size=PTZ_WINDOW_SIZE
</syntaxhighlight>
===As a standalone application===
The service can also be run directly into you jetson device.
Before running the service, you should make sure you have all the dependencies installed. The instructions 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]
{{Review|Add link to other dependencies as rtsp-sink?|mortigoza}}
Then you have to clone into your device the repository project, available [/ptz here]
{{Review|Add link to the repository|mortigoza}}
The project is configured (via setup.py) to install the service with the name '''ptz'''. So to install it run:


<pre>
<pre>
sudo docker run --runtime nvidia -it --privileged --net=host --ipc=host --name ptz-service  ridgerun/ptz-service:latest --host=HOST --port=PORT --ptz-window-size=PTZ_WINDOW_SIZE
pip install .
</pre>
 
Then you will have the service with the following options:
 
<pre>
usage: ptz [-h] [--port PORT] [--host HOST] [--ptz-window-size PTZ_WINDOW_SIZE]
 
options:
  -h, --help            show this help message and exit
  --port PORT           Port for server
  --host HOST          Server ip address
  --ptz-window-size PTZ_WINDOW_SIZE
                        Size of the PTZ output window in pixels. The final resolution will be (Size x Size)
</pre>
</pre>


After this the service will be available under the name '''ptz'''.


==Examples==
==Examples==
Line 138: Line 134:
#Returns the stream transformed using the same protocol, RTSP, as the output.  
#Returns the stream transformed using the same protocol, RTSP, as the output.  


We can use the module available in here**, called rrms_utils, to talk to the PTZ Microservice.  
RidgeRun developed a convenient package called rrms_utils that makes the interaction with our microservices easier.


{{Review|Add link to explanation of how to install rrms-utils?|mortigoza}}
{{Review|Add link to explanation of how to install rrms-utils?|mortigoza}}


These are the imports, and commands needed to do it: (Below we explain the purpose of each one)
Following is an example of a typical application using rrms_utils to control the PTZ microservice:


<pre>
<syntaxhighlight lang="python">
from rrms_utils.ptz import PTZ
from rrms_utils.ptz import PTZ
from rrms_utils.models.ptz.stream import Stream
from rrms_utils.models.ptz.stream import Stream
Line 152: Line 148:


# Create client (by default will talk to address 127.0.0.1 and port 5020)
# Create client (by default will talk to address 127.0.0.1 and port 5020)
client = PTZ(host=192.168.100.15, port=7000)
# Change host and port for the IP address and port of the service.
client = PTZ(host=192.168.100.15, port=5020




Line 161: Line 158:
if not set_stream_result:
if not set_stream_result:
     print("Something went wrong")
     print("Something went wrong")


# Perform PTZ
# Perform PTZ
Line 172: Line 167:
if not set_position_result:
if not set_position_result:
     print("Something went wrong")
     print("Something went wrong")


# Change zoom
# Change zoom
Line 181: Line 175:
     print("Something went wrong")
     print("Something went wrong")


</syntaxhighlight>


#Receive the PTZ output - RTSP Stream:
The previous example will create an output stream at port 8000 with mapping stream_out. In order to display it you can use a player like VLC:
vlc rtsp://192.168.100.15:8000/stream_out


</pre>
<syntaxhighlight lang="bash">
vlc rtsp://BOARD_IP_ADDRESS:8000/stream_out
</syntaxhighlight>


Just replace '''BOARD_IP_ADDRESS''' with the IP address of the board running the service.


===Explanation===
===Explanation===
Retrieved from "https://developer.ridgerun.com/wiki/index.php/Special:MobileDiff/55226"