modules.vision.devices.vendors.hikvision.ds_2dy9250iax_a

Classes Diagram

Module Dependencies

Classes

DS2DY9250IAXA

Inherits from: BaseVendor

Singleton PTZ camera controller.
Provides an interface to control a PTZ (Pan-Tilt-Zoom) camera, ensuring only one
instance of the class exists across the entire program.
Datasheet: https://www.hikvision.com/content/dam/hikvision/products/S000000001/S000000002/S000000011/S000000013/OFR000059/M000005882/Data_Sheet/Datasheet-of-DS-2DY9250IAX-A-D_20190816.pdf

Constructor

DS2DY9250IAXA(self, name: str, host: str, username: str, password: str, start_azimuth: int = None, end_azimuth: int = None, rtsp_port: int = 554, video_channel: int = 1)

Members

_instance

_lock

_PAN_RANGE

_TILT_RANGE

_ZOOM_RANGE

_SPEED_RANGE

CHANNEL_ID

XML_CONTENT_TYPE

_initialized

_name

_host

_username

_password

_client

_start_azimuth

_end_azimuth

_current_pan

_current_tilt

_current_zoom

_current_elevation

_current_azimuth

_current_zoom_hw

_current_pan_speed

_current_tilt_speed

_last_angle_update_time

_status

rtsp_url

rtsp_stream

system_status_updater

Methods

_build_absolute_position_xml(elevation: float, azimuth: float, zoom: float) → str

@staticmethod

Build XML command for absolute positioning.

_build_continuous_movement_xml(pan: int, tilt: int) → str

@staticmethod

Build XML command for continuous movement.

_build_3d_position(start_x: int, start_y: int, end_x: int, end_y: int) → str

@staticmethod

_calculate_pan_tilt(self, pan_speed: int, tilt_speed: int) → tuple[int, int]

Calculate pan and tilt values based on axis and direction.

_convert_pan_to_azimuth(self, pan: float) → int

_azimuth_to_pan(self, elevation: int) → float

_convert_tilt_to_elevation(self, tilt: float) → int

_elevation_to_tilt(self, azimuth: int) → float

_convert_zoom_to_hw_zoom(self, zoom: int) → int

_hw_zoom_to_zoom(self, zoom: int) → int

_convert_logical_to_hardware(self, pan, tilt, zoom)

_convert_hardware_to_logical(self, elevation, azimuth, zoom)

_set_absolute_ptz_position(self, pan: float | None = None, tilt: float | None = None, zoom: int | None = None) → bool

Command the camera to move to an absolute pan/tilt/zoom position.

This method issues an absolute PTZ movement request to the camera using
logical pan, tilt, and zoom coordinates. Any axis set to None will
retain its current value. Before sending the command, the method enforces
both an angular tolerance threshold and a minimum time interval between
updates to avoid redundant or excessive PTZ commands.

Logical PTZ values are converted to hardware-specific coordinates prior
to transmission. On successful execution, both logical and hardware PTZ
state caches are updated to reflect the new target position.

The command will not be sent if: \

• The controller is not initialized \
• The requested movement is within the configured angle tolerance \
• The minimum time interval since the last update has not elapsed
  
  Parameters
  ----------
  pan: float | None, optional
  Target pan angle in logical degrees. If None, the current pan
  position is used.
  tilt: float | None, optional
  Target tilt angle in logical degrees. If None, the current tilt
  position is used.
  zoom: int | None, optional
  Target zoom level in logical units. If None, the current zoom
  level is used.
  
  Returns
  -------
  bool
  True if the PTZ command was successfully sent and the internal state
  was updated, False otherwise.

_set_relative_ptz_position(self, pan: float | None = None, tilt: float | None = None, zoom: int | None = None) → bool

Move the camera by a relative pan, tilt, and zoom offset.

Parameters
----------
pan: float | None
Pan offset in logical degrees. If None, pan is unchanged.
tilt: float | None
Tilt offset in logical degrees. If None, the tilt is unchanged.
zoom: int | None
Zoom offset in logical units. If None, the zoom is unchanged.

_send_continuous_ptz_command(self, pan: int, tilt: int) → bool

Sends a continuous pan-tilt-zoom (PTZ) command to the PTZ client.

This method constructs an XML payload for the PTZ command, specifying the pan
and tilt values, and attempts to send the command via the PTZ client. If the
client is not initialized or an error occurs during transmission, the method
logs the error and returns False.

Args:
pan: The pan (horizontal) value to send in the PTZ command.
tilt: The tilt (vertical) value to send in the PTZ command.

Returns:
bool: True if the command was sent successfully, otherwise False.

_start_continuous(self, pan_speed: int, tilt_speed: int) → bool

Start or update a continuous Pan-Tilt (PT) movement.

This method initiates or updates a continuous pan and tilt movement
using the specified speeds. If the camera is not initialized, the
movement is not started and the method returns False.

If the requested pan and tilt speeds are already active, no new
movement command is issued and the method returns True.

Args:
pan_speed (int): Horizontal (pan) movement speed. The sign
determines the direction.
tilt_speed (int): Vertical (tilt) movement speed. The sign
determines the direction.

Returns:
bool: True if the movement is active or successfully started;
False otherwise.

_update_status(self) → None

Update internal status from PTZ camera.

stop_continuous(self) → None

Stops any ongoing continuous PTZ (Pan-Tilt-Zoom) commands.

This method sends a stop signal to terminate any currently running
continuous PTZ commands. It sets the pan and tilt velocity to zero, ensuring
that the movement of the camera stops immediately.

Raises:
Exception: If there is an issue while sending the stop command.

is_initialized(self) → bool

get_azimuth(self) → int

Gets the azimuth value from the PTZ (Pan-Tilt-Zoom) status.

The method retrieves the PTZ status and extracts the azimuth value from the
AbsoluteHigh component. The azimuth represents the horizontal angle of the
camera's orientation in the PTZ system.

Returns:
int: The azimuth value as an integer.

get_elevation(self) → int

Gets the elevation value from the PTZ (Pan-Tilt-Zoom) status.

The method retrieves PTZ status data and extracts the 'elevation' value
from the absolute high-position information.

Returns:
int: The elevation value extracted from the PTZ status.

get_instance(cls) → DS2DY9250IAXA

@classmethod

Return the singleton PTZ instance, if already created.

get_status(self, force_update: bool = False) → dict

Retrieve current PTZ status and parse useful values.

set_3d_position(self, start_x, start_y, end_x, end_y) → bool

get_zoom(self) → int

Gets the zoom level of the PTZ (Pan-Tilt-Zoom) camera.

This method retrieves the absolute zoom level from the camera's current
status data. The zoom level represents the current zoom factor of the
camera, as an integer value.

Returns:
int: The current absolute zoom level of the camera.

get_speed(self) → tuple[int, int]

Return the current pan and tilt speed.

get_video_stream(self)

release_stream(self)

Safely release the RTSP stream.

_update_status_loop(self)

Continuously update PTZ status in a separate thread.
Send on the IPC status informations

Attributes

logger