Onvif Java Library - Basic PTZ operations

One of the more interesting things of working with Network Video Transmitters in ONVIF are PTZ operations. PTZ stands for Pan-Tilt-Zoom. With these components, you can translate your camera and change your zoom.

There are a few possibilities to move your camera, but you can get each method over the PTZ interface. Please be aware, that you will need a connection to your NVT and a proper profile token. 

	OnvifDevice nvt = new OnvifDevice("192.168.0.20", "admin", "password");
	List<Profile> profiles = nvt.getDevices().getProfiles();
	String profileToken = profiles.get(0).getToken();
	
	PtzDevices ptzDevices = nvt.getPtz(); // get PTZ Devices

The PtzDevices offer some interesting methods to configure you movements. 

isPtzOperationsSupported(profileToken : String) : boolean // simple method to check if any PTZ operations are supported
getNode(profileToken : String) : PTZNode // returns PTZNode which is useful to get smallest and biggest values for move operations
getPanSpaces(profileToken : String) : FloatRange // returns range of pan angle (x)
getTiltSpaces(profileToken : String) : FloatRange // returns range of tilt angle (y)
getZoomSpaces(profileToken : String) : FloatRange // returns range of zoom
getStatus(profileToken : String) : PTZStatus // returns PTZStatus which holds interesting information about current 
                                             // PTZ status, may (!) contain the camera position
	
absoluteMove(profileToken : String, x : float, y : float, zoom : float) : boolean // method for absolute movements
isAbsoluteMoveSupported(profileToken : String) : boolean // simple method to check if absolute movements are supported
	
relativeMove(profileToken : String, x : float, y : float, zoom : float) : boolean // method for relative movements
isRelativeMoveSupported(profileToken : String) : boolean // simple method to check if relative movements are supported
	
continuousMove(profileToken : String, x : float, y : float, zoom : float) : boolean // method for continuos movements
stopMove(profileToken : String) : boolean // method to stop continuos movements
isContinuosMoveSupported(profileToken : String) : boolean // simple method to check if continuos movements are supported
	
getPresets(profileToken : String) : List<PTZPreset> // returns a list with all presets
setPreset(presetName : String, profileToken : String) : String // create a new preset at current camera position, 
                                                               // returns presetToken
setPreset(presetName : String, presetToken : String, profileToken : String) : String // update preset with presetToken to current
                                                                                     // camera position and new presetName
removePreset(presetToken : String, profileToken : String) : boolean // remove preset
gotoPreset(presetToken : String, profileToken : String) : boolean // move to preset

isPtzOperationsSupported() is good to check if your device does support PTZ-operations. So, if you are not sure, you can use this method to control the functionality of your NVT.
getNode() is a method to achieve the maximum values of your device. getPanSpaces(), getTiltSpaces() and getZoomSpaces() use getNode() to return the ranges for your PTZ-operations (so you don't have to go throw the all submethods of getNode(),

Knowing the limits of your operations, you can use these values to work with absoluteMove(). This is one of three (direct) movements methods and it moves the camera to one absolute position. If you want to move your relative to your current position, it is recommended to use relativeMove(). If you want to initiate a continuous movement, you should use continuousMove() and stop the movement with stopMove().
These movements methods need parameters for x and y which are synonyms in ONVIF for a generic value of pan and tilt angle.

Please notice, that not each NVT does support all of these methods. Once I worked with a device that didn't support relative movements and I had to replace that functionality with continuous and stop movements.

Often it is also interesting to work with the current PTZ position of your NVT with getStatus(profileToken).getPosition(). But your device doesn't have to support this method, so please be aware that this function might throw an exception.

I created an example which moves the camera to the middle of its pan and tilt ranges with no zoom:

import java.net.ConnectException;
import java.util.List;

import javax.xml.soap.SOAPException;

import org.onvif.ver10.schema.FloatRange;
import org.onvif.ver10.schema.Profile;

import de.onvif.soap.OnvifDevice;
import de.onvif.soap.devices.PtzDevices;

public class OnvifTest {
   public static void main(String[] args) {
      try {
         OnvifDevice nvt = new OnvifDevice("192.168.0.20", "admin", "password");
         List<Profile> profiles = nvt.getDevices().getProfiles();
         String profileToken = profiles.get(0).getToken();
			
         PtzDevices ptzDevices = nvt.getPtz();

         FloatRange panRange = ptzDevices.getPanSpaces(profileToken);
         FloatRange tiltRange = ptzDevices.getTiltSpaces(profileToken);
         float zoom = ptzDevices.getZoomSpaces(profileToken).getMin();

         float x = (panRange.getMax() + panRange.getMin()) / 2f;
         float y = (tiltRange.getMax() + tiltRange.getMin()) / 2f;

         if (ptzDevices.isAbsoluteMoveSupported(profileToken)) {
         ptzDevices.absoluteMove(profileToken, x, y, zoom);
         }
      }
      catch (ConnectException e) {
         System.err.println("Could not connect to NVT.");
      }
      catch (SOAPException e) {
         e.printStackTrace();
      }
   }
}

Congratulation! You've finished the first tutorials of the Onvif Java Library! If you want to find out more of the Onvif Java Library, find out more with the API.