2,599
edits
No edit summary |
Efernandez (talk | contribs) No edit summary |
||
Line 4: | Line 4: | ||
PTZ Microservice is a | PTZ Microservice is a microservice developed by RidgeRun. It allows you to navigate a '''360-degrre''' video through pan, tilt, and zoom (PTZ). | ||
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 | # Performs the PTZ depending on user instructions | ||
# Returns | # 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}} | ||
== | ==Service documentation== | ||
This microservice can be controlled through a REST API and its documentation can be found '''HERE''' | |||
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 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 | 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 ==== | |||
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. | |||
{{Review|Add link to the repository|mortigoza}} | {{Review|Add link to the repository|mortigoza}} | ||
Line 112: | Line 77: | ||
====Launch the container==== | |||
Either if you pulled the prebult image of you built your own, a docker container can be launched by running the following command: | |||
< | <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 | ||
</ | </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> | ||
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. | ||
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}} | ||
Following is an example of a typical application using rrms_utils to control the PTZ microservice: | |||
< | <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= | # 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> | |||
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: | |||
</ | <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=== |