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

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 = default 0.5).
  • "FocusFar": move focus toward far (longer distance). SpeedRatio in 0.0..1.0.
  • "Focus": generic focus move → positive SpeedRatio moves Far, negative moves Near.

To stop, invoke StartMove with Start=false (or use StopMove).

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.ONVIFPTZStartMove ("FocusNear", false, 0, 0)      // stop focus

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

Invoke SetFocusPosition (CanLock, AutoFocus, Position) to move to an absolute focus position:

  • AutoFocus=false, Position >= 0: switch to manual mode and move to the specified absolute position (in the range reported by GetFocusSettings),
  • AutoFocus=false, Position = -1: switch to manual mode only, no position change,
  • AutoFocus=true, Position = -1: switch to auto-focus mode only.

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 IR-Cut commands. The Start parameter is also ignored.

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. Start=false stops.
FocusFar continuous focus move toward far. SpeedRatio=0 uses default 0.5. Start=false stops.
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".