GStreamer Pan Tilt Zoom and Rotate Element - Demo Tool

GStreamer PTZR
GstPTZR Basics
PTZR Camera Digital PTZR Emulation
User Guide
Pan & Tilt Zoom Rotate Rectangle
Getting Started
Evaluating GstPTZR Getting the code Building GstPTZR
Examples
PC pipelines iMX6 pipelines Tegra pipelines Demo Tool
Contact Us

The demo tool is a Python script called ptzr_test located in the tests/examples directory. It can be used to demonstrate and test the different transformations that are possible using the GStreamer PTZR element.

ptzr_test

The ptzr_test script uses Ridgerun's GStreamer Daemon (gstd) to create a pipeline that can be used to demo the features of GstPTZR. If gstd is not running, it will try to start it.

It will create a pipeline with the name p0 with a GstPTZR element with the name ptzr0. The basic pipeline that will be created will use autovideosrc to pick the first available video source (a webcam, if available; a videotestsrc if not), with some basic caps. If a pipeline with those characteristics already exists, it will use it.

It will allow the user to manipulate the different properties of the GstPTZR element in a number of different ways, according to the mode that is selected.

To start the script, start it from the console:

user@host:~/gst-ptzr$ tests/examples/ptzr_test

The script has a detailed help that can be printed by calling the script with the -h or --help switch:

user@host:~/gst-ptzr$ tests/examples/ptzr_test --help
usage: ptzr_test [-h]
                 [--interactive | --cmdline | --demo | --script SCRIPT | --file FILE]
                 [--profile PROFILE] [--pipeline-name PIPELINE_NAME]
                 [--element-name ELEMENT_NAME] [--device DEVICE]
                 [--input-resolution IN_RESOLUTION]
                 [--output-resolution OUT_RESOLUTION] [--debug] [--loop]
                 [--ip IP] [--port PORT]

PTZR demo app

optional arguments:
  -h, --help            show this help message and exit
  --interactive, -i     Start in interactive mode (default)
  --cmdline, -c         Start in command line mode
  --demo, -D            Start in demo mode
  --script SCRIPT, -s SCRIPT
                        Run the script commands provided and exit. Use
                        multiple times or separate commands with ;
  --file FILE, -f FILE  Read commands from the provided file and exit
  --profile PROFILE, -p PROFILE
                        Selects on of the known profiles when creating the
                        pipeline. Valid values include pc, pc-v4l2, imx6,
                        tegra (default: pc)
  --pipeline-name PIPELINE_NAME, -P PIPELINE_NAME
                        Specify the name of the pipeline to be used (default:
                        p0)
  --element-name ELEMENT_NAME, -E ELEMENT_NAME
                        Specify the name of the element to be used (default:
                        ptzr0)
  --device DEVICE, -v DEVICE
                        Specify the device to use when using a v4l2 profile
                        (default: /dev/video0)
  --input-resolution IN_RESOLUTION, -I IN_RESOLUTION
                        Specify the resolution (width x height) for input
                        caps. (default: 640x480)
  --output-resolution OUT_RESOLUTION, -O OUT_RESOLUTION
                        Specify the resolution (width x height) for output
                        caps. (default: 640x480)
  --debug, -d           Print debug information
  --loop, -l            In script or demo modes, loop the commands. Exit loop
                        with Control-C
  --ip IP, -a IP        Specify the IP address of the host running Gstd
                        (default: localhost)
  --port PORT           Specify the PORT address of the host running Gstd
                        (default: 5000)

user@host:~/gst-ptzr$

Modes of operation

The demo tool can be used in a number of different configurations, according to the application. This section describes the different modes and the ways to interact with the element in each mode.

Interactive

Interactive mode is the default mode. It can be started explicitly by using the -i or --interactive:

user@host:~/gst-ptzr$ tests/examples/ptzr_test -i

It will show a curses UI with all the information you need to control the GstPTZR element.

Error creating thumbnail: Unable to save thumbnail to destination

Interactive mode

The interface is designed for using the keypad for controlling the PTZR element. Most of the controls are available single-handedly on the numeric keypad of a full keyboard. Table 1 shows the controls and the actions that can be done in the interactive mode.

Table 1. Interactive mode controls

Keys	Action
left and right arrows	change pan value by the selected step
up and down arrows	change tilt value by the selected step
+ and -	change zoom value by 0.1x
/ and *	change rotate value by 5 degrees counterclockwise or clockwise
d and 0/Ins	set all values to default
./DEL	toggle output-reference mode
TAB and 5	toggle normalize-translation mode
F9 and F10	decrease and increase step used for pan/tilt from 5 preset values
q or ENTER	exit the application

Command line

To start the tool in command line mode, use the -c or --cmdline switch. It will start a command-line interface:

user@host:~/gst-ptzr$ tests/examples/ptzr_test -c
A pipeline is already running, test that it has the right elements.
The current pipeline p0 contains an element ptzr0 that can be used.
Pipeline is now running.
pipe [p0] element [ptzr0]
Welcome to the PTZR tester!

This script can be used to test all the PTZR features by creating a pipeline
that uses the gst-ptzr element. It uses a autovideosrc and caps both input and
output to a 640x480 screen.
PTZR>

The command-line interface has support for auto-completion and session history.

Table 2. Commands available in command-line mode

Command	Action
pan <nn> pan_delta <nn>	add nn to pan value
pan abs <nn> pan_level <nn>	set pan value to nn
tilt <nn> tilt_delta <nn>	add nn to tilt value
tilt abs <nn> tilt_level <nn>	set tilt value to nn
zoom <nn>	set zoom value to nn
rotate <nn> rotate_delta <nn>	add nn to rotate value
rotate abs <nn> rotate_level <nn>	set rotate value to nn
delay <nn>	wait for nn seconds. Useful for writing scripts
get_values	shows the current values of the parameters in JSON mode
status	shows the current values of the parameters in readable mode
restart	restart the pipeline
set_output_reference <nn>	set output-reference mode to nn. Valid values include: false, False, 0, true, True, 1, enable
set_normalization <nn>	set normalize-translation mode to nn. Valid values include: false, False, 0, true, True, 1, enable
defaults	set all values to default
demo [loop]	start demo mode, if loop is specified, runs in an infinite loop. Control-C exits the loop
interactive	start interactive mode
exit EOF	exit the application. EOF can be input with the Control-D key combination
help [command]	show general help. If command is specified, it will print help for the specific command

Demo

To start the tool in demo mode, use the -D or --demo switch. It will start running a series of commands that will make the image rotate in a circle.

user@host:~/gst-ptzr$ tests/examples/ptzr_test -D
A pipeline is already running, test that it has the right elements.
The current pipeline p0 contains an element ptzr0 that can be used.
Pipeline is now running.
pipe [p0] element [ptzr0]
...

Script

To start the tool in script mode, use the -s or --script switch. It will run the command and exit.

user@host:~/gst-ptzr$ tests/examples/ptzr_test --script "zoom 10"
A pipeline is already running, test that it has the right elements.
The current pipeline p0 contains an element ptzr0 that can be used.
Pipeline is now running.
pipe [p0] element [ptzr0]
OK
user@host:~/gst-ptzr$

Multiple commands can be entered by using multiple instances of -s or by separating the commands with a semi-colon:

user@host:~/gst-ptzr$ tests/examples/ptzr_test -s "zoom 10 ; delay 5 ; zoom 2"
A pipeline is already running, test that it has the right elements.
The current pipeline p0 contains an element ptzr0 that can be used.
Pipeline is now running.
pipe [p0] element [ptzr0]
OK
OK
OK
user@host:~/gst-ptzr$

File

File mode is a special script mode where the script is read from a file. To start the tool in file mode, use the -f or --file switch. It will read the commands from a file and exit. A sample file is provided.

user@host:~/gst-ptzr$ tests/examples/ptzr_test -f tests/examples/surveillance.txt
A pipeline is already running, test that it has the right elements.
The current pipeline p0 contains an element ptzr0 that can be used.
Pipeline is now running.
pipe [p0] element [ptzr0]
OK
OK
OK
...
OK
user@host:~/gst-ptzr$

Other options

Debug data

When debug is enabled, additional information about the system will be shown during the execution, in any mode that is being used. To enable debug, use the -d or --debug switch to enable it:

user@host:~/gst-ptzr$ tests/examples/ptzr_test -s "zoom 10 ; delay 5 ; zoom 2" -d
A pipeline is already running, test that it has the right elements.
The current pipeline p0 contains an element ptzr0 that can be used.
Pipeline is now running.
pipe [p0] element [ptzr0]
zoom 10  ... OK
delay 5  ... OK
zoom 2 ... OK
user@host:~/gst-ptzr$

Loop

For script, demo and file modes, the loop option can be enabled with the -l or --loop switch to repeat the commands specified in a loop. Use Control-C to exit from the loop.

Remote access

The demo tool can be run in a remote device that can access the device running gstd via network. In this use case, use the --ip IP and --port PORT to specify the IP address and PORT to use.

In this mode, the tool is not able to detect if gstd is running or not, so make sure that the daemon has been started in the remote device.

This feature is particularly useful to test the element running on an embedded system while the demo tool is run remotely from a PC.

Compatibility

ptzr_test has been tested with Python 2.7 and 3.5. If any compatibility issues arise, please report them.

It requires the following Python libraries:

cmd
curses
psutil