Skip to content

ONVIF PTZ, Focus and IR-Cut filter

PTZ overview

The filter supports ONVIF PTZ through the IDatasteadONVIFPTZ interface that exposes the following functions:

  • GetPosition
  • SetPosition
  • StartMove
  • StopMove
  • Preset
  • SendAuxiliaryCommand
  • GetLimits

Signatures:

HRESULT GetPosition (double *Pan, double *Tilt, double *Zoom, time_t *UTCTime, int *IsMoving);
HRESULT SetPosition (double Pan, double Tilt, double Zoom, double SpeedRatio, bool IsRelative);
HRESULT StartMove   (LPCOLESTR PTZType, bool OppositeDirection, double SpeedRatio, int DurationMs);
HRESULT StopMove    (LPCOLESTR PTZType);
HRESULT Preset      (LPCOLESTR Action, LPCOLESTR PresetName);
HRESULT SendAuxiliaryCommand (LPCOLESTR AuxiliaryCommand);
HRESULT GetLimits   (double *Pan_Min, double *Pan_Max, double *Tilt_Min,
                     double *Tilt_Max, double *Zoom_Min, double *Zoom_Max);

StartMove does not take a Start parameter

A move started with StartMove is stopped with StopMove, passing the same PTZType. The second parameter of StartMove is OppositeDirection, which reverses the direction of the move; it does not start or stop it.

The PTZType values are case-insensitive: "Pan", "Tilt", "Zoom", plus the focus and IR-cut values listed below. The Action values of Preset are "Create", "Remove" and "Goto", also case-insensitive.

The usage of these functions is implemented in the "DatasteadRTSPSource_CSharp_Demo" project included in the package.

Absolute, relative and continuous Pan / Tilt / Zoom are supported, as well as Presets (predefined positions).

Note that some cameras support only partial PTZ features, e.g. only the continuous move.

All the values of the PTZ functions are expressed as "double" values.

Most of the positioning functions include a SpeedRatio parameter, the SpeedRatio value is usually in the 0 .. 1.0 range.

Before invoking any of these functions, first start the preview of the IP camera by using an onvif:// URL (see ONVIF: connecting to the RTSP streams).

From the TVideoGrabber SDK, use VideoGrabber.ONVIFPTZStartMove and VideoGrabber.ONVIFPTZStopMove.

Focus and IR-Cut filter

Focus and IR-Cut filter control are accessible through the same StartMove / StopMove functions of the IDatasteadONVIFPTZ interface, using dedicated PTZType string values. No additional function is required.

Before using focus commands, first connect to the camera with an onvif:// URL. The Imaging service must be available on the camera.

Focus -> switching auto/manual mode

Use StartMove (or ONVIFPTZStartMove from the TVideoGrabber SDK) with the following PTZType values to change the focus mode:

  • "FocusAuto": switches the camera to auto-focus mode. The SpeedRatio and DurationMs parameters are ignored. Returns E_NOTIMPL if the camera only supports manual focus (e.g. AutoFocusModes=[MANUAL]).
  • "FocusManual": switches the camera to manual focus mode.

Example:

VideoGrabber.ONVIFPTZStartMove ("FocusAuto", false, 0, 0)
VideoGrabber.ONVIFPTZStartMove ("FocusManual", false, 0, 0)

Note: before sending a continuous focus move command, the filter automatically switches the camera to manual mode if it is currently in auto mode. Some cameras silently ignore movement commands while in auto-focus mode.

Focus -> continuous move (Near / Far)

To move the focus continuously, use StartMove with one of these PTZType values:

  • "FocusNear": move focus toward near (shorter distance). SpeedRatio in 0.0..1.0; 0 uses the default 0.5.
  • "FocusFar": move focus toward far (longer distance). SpeedRatio in 0.0..1.0; 0 uses the default 0.5.
  • "Focus": generic focus move -> positive SpeedRatio moves Far, negative moves Near.

OppositeDirection = true reverses the direction, so "FocusNear" with OppositeDirection = true behaves like "FocusFar". DurationMs limits the duration of the move.

To stop the move, invoke StopMove with the same PTZType.

Examples:

VideoGrabber.ONVIFPTZStartMove ("FocusNear", false, 0.5, 5000) // focus Near at half speed for 5 s
VideoGrabber.ONVIFPTZStartMove ("FocusFar", false, 0.7, 3000)  // focus Far at 70% speed for 3 s
VideoGrabber.ONVIFPTZStopMove  ("FocusNear")                   // stop the focus move

Note: depending on the camera model, the continuous focus move uses ContinuousMove if supported, or falls back to RelativeMove automatically. The filter queries the focus capabilities on first use and selects the appropriate strategy. If neither is supported, E_NOTIMPL is returned.

Focus -> absolute position

Note

Absolute focus positioning is not exposed by the public interface in this version. "FocusAuto" and "FocusManual" switch the focus mode, and "FocusNear" / "FocusFar" move the focus; the absolute position is handled internally by the filter, using AbsoluteMove when the camera supports it.

IR-Cut filter (Day/Night mode)

The IR-Cut filter controls the camera's day/night mode via the ONVIF Imaging service. Use StartMove with one of these PTZType values:

  • "IRCutOn": IR cut filter active -> day mode, colour image. The filter blocks infrared light.
  • "IRCutOff": IR cut filter inactive -> night mode, black and white image. Infrared light passes through.
  • "IRCutAuto": camera switches automatically between day and night mode based on the ambient light level.

SpeedRatio, OppositeDirection and DurationMs are ignored for the IR-Cut commands, which take effect immediately and do not need to be stopped.

Examples:

VideoGrabber.ONVIFPTZStartMove ("IRCutOn", false, 0, 0)   // force day mode
VideoGrabber.ONVIFPTZStartMove ("IRCutOff", false, 0, 0)  // force night mode
VideoGrabber.ONVIFPTZStartMove ("IRCutAuto", false, 0, 0) // auto day/night

Note: IR-Cut filter support varies by camera.

Summary of Focus and IR-Cut PTZType values

All values are case-insensitive. Pass them as the 1st parameter of StartMove:

PTZType Effect
FocusNear continuous focus move toward near. SpeedRatio=0 uses default 0.5. Stopped with StopMove.
FocusFar continuous focus move toward far. SpeedRatio=0 uses default 0.5. Stopped with StopMove.
Focus generic focus move. Positive SpeedRatio=Far, negative=Near.
FocusAuto switch to auto-focus. Returns E_NOTIMPL if the camera does not support AUTO mode.
FocusManual switch to manual focus.
IRCutOn IR cut filter ON (day mode, colour).
IRCutOff IR cut filter OFF (night mode, B&W).
IRCutAuto IR cut filter AUTO (camera decides).

Camera compatibility notes

Focus motor support varies significantly between camera models:

  • Fixed-lens cameras (e.g. entry-level Dahua IPC-HFW series): no focus motor. Focus/IRCut commands may return SOAP_OK but have no effect. The ICR (IR Cut Removal) relay may produce a click sound that can be mistaken for a focus motor.
  • Motorized varifocal cameras: support ContinuousMove or RelativeMove depending on the model. The filter selects the appropriate strategy automatically.
  • Cameras with AUTO focus support (e.g. Axis P-series): expose AutoFocusModes=[AUTO,MANUAL] in GetOptions. FocusAuto is fully functional.
  • Cameras without AUTO focus support: expose AutoFocusModes=[MANUAL] only.

Axis IR-Cut filter (non-ONVIF)

The state of the IR Cut Filter of Axis cameras can also be set or retrieved through the dedicated RTSP_Source_Axis_IrCutFilter_str parameter. The supported values are: "enabled" / "disabled" / "auto".