### Install pyptz Library

Source: https://github.com/jahongir7174/pyptz/blob/master/README.md

Install the pyptz library using pip. This is the first step before using any of the camera control functionalities.

```bash
pip install pyptz
```

--------------------------------

### Check PyPTZ Version

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Print the installed version of the pyptz library. This is useful for ensuring compatibility or reporting issues.

```python
import pyptz
print(pyptz.__version__)  # '0.1.8'
```

--------------------------------

### Get Camera Applications

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Retrieve a list of installed applications on the camera. This method returns a requests.Response object.

```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.applications()
print(response.text)
```

--------------------------------

### Multi-Protocol Camera Initialization and Control Comparison

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Initializes ONVIF, VAPIX, and SUNAPI cameras and demonstrates common and protocol-specific operations. This example highlights differences in snapshotting, speed control, and focus adjustment across protocols.

```python
from pyptz import ONVIFCamera, VAPIXCamera, SUNAPICamera

# Initialize cameras
onvif = ONVIFCamera('192.168.1.101', '8080', 'admin', 'pass')
vapix = VAPIXCamera('192.168.1.102', 'admin', 'pass')
sunapi = SUNAPICamera('192.168.1.103', 'admin', 'pass')

# All three can move
onvif.absolute_move(pan=45.0, tilt=30.0, zoom=1.5)
vapix.absolute_move(pan=45.0, tilt=30.0, zoom=5, speed=50)
sunapi.absolute_move(pan=45.0, tilt=30.0, zoom=5.0)

# All three can query position
pan1, tilt1, zoom1 = onvif.get_ptz_status()
pan2, tilt2, zoom2 = vapix.get_ptz_status()
pan3, tilt3, zoom3, pulse = sunapi.get_ptz_status()

# Only SUNAPI can snapshot
image = sunapi.snap_shot()
if image:
    image.save('snapshot.jpg')

# Only VAPIX has speed control
vapix.set_speed(100)
current = vapix.get_speed()

# Only SUNAPI has focus
sunapi.continuous_move(
    normalized_speed=True,
    pan=0, tilt=0, zoom=0,
    focus="Far"
)
```

--------------------------------

### ONVIFCamera Get Preset Complete

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Retrieves a detailed list of all preset objects.

```python
get_preset_complete()
```

--------------------------------

### applications

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Retrieve information about installed applications on the camera. This method returns a requests.Response object containing the application data.

```APIDOC
## Method: applications

### Description
Retrieve information about installed applications on the camera.

### Signature
```python
def applications(self) -> requests.Response
```

### Parameters
None

### Returns
`requests.Response` object containing installed applications information

### Example
```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.applications()
print(response.text)
```
```

--------------------------------

### Patrol Multiple Presets with SUNAPI Camera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/package-overview.md

This example demonstrates how to make a SUNAPI camera patrol through a list of named presets, pausing at each one. Requires camera IP, username, and password.

```python
from pyptz import SUNAPICamera
import time

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')

presets = ['entrance', 'lobby', 'hallway', 'exit']
for preset_name in presets:
    camera.go_to_preset_position(preset=None, preset_name=preset_name)
    time.sleep(5)  # Stay at each preset for 5 seconds
```

--------------------------------

### Control Camera Tour Operation

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Use this method to start or stop a tour sequence on a specific camera channel. Ensure the mode is either 'Start' or 'Stop'.

```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.tour_control(channel=1, tour=1, mode='Start')
response = camera.tour_control(channel=1, tour=1, mode='Stop')
```

--------------------------------

### Catching Timeout Errors with SUNAPICamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

This example demonstrates how to catch `requests.exceptions.Timeout` for VAPIX/SUNAPI requests that take too long to complete. The `requests` library must be imported.

```python
import requests
from pyptz import SUNAPICamera

try:
    camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
    response = camera.absolute_move(pan=45.0, tilt=30.0, zoom=5.0)
except requests.exceptions.Timeout as e:
    print(f"Request timed out: {e}")
```

--------------------------------

### ONVIFCamera Get Preset

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Retrieves a list of all saved presets, including their index and name.

```python
get_preset()
```

--------------------------------

### Get ONVIF Camera Presets

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Retrieves a list of saved presets from an ONVIF camera. Each preset is returned as a tuple containing its index and name.

```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
presets = camera.get_preset()
for index, name in presets:
    print(f"Preset {index}: {name}")
```

--------------------------------

### Get Complete ONVIF Camera Preset Objects

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Retrieves detailed ONVIF preset objects, including all configuration details, from the camera. This is useful for accessing more than just the name and index.

```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
presets = camera.get_preset_complete()
for preset in presets:
    print(f"Preset name: {preset.Name}, Token: {preset.token}")
```

--------------------------------

### Get PTZ Status via ONVIF

Source: https://github.com/jahongir7174/pyptz/blob/master/README.md

Connect to an ONVIF-compliant camera and retrieve its current Pan, Tilt, and Zoom status. Ensure the camera's IP address, port, username, and password are correct.

```python
from pyptz.onvif_control import ONVIFCamera

onvif_camera = ONVIFCamera('192.168.1.100', '88', 'admin', 'password')
pan, tilt, zoom = onvif_camera.get_ptz_status()
print(pan, tilt, zoom)
```

--------------------------------

### get_preset

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Retrieves all saved presets as a list of (index, name) tuples. This method is useful for getting a quick overview of available presets.

```APIDOC
## Method: get_preset

### Description
Retrieve all saved presets as a list of (index, name) tuples.

### Signature
```python
def get_preset(self) -> list[tuple[int, str]]
```

### Parameters
None

### Returns
List of tuples where each tuple contains (preset_index: int, preset_name: str)

### Example
```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
presets = camera.get_preset()
for index, name in presets:
    print(f"Preset {index}: {name}")
```
```

--------------------------------

### Catching Invalid Tour Mode Exception

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

This example demonstrates how to catch exceptions when an invalid mode is passed to the `tour_control` method. It requires a properly configured SUNAPICamera instance.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')

try:
    response = camera.tour_control(channel=1, tour=1, mode="Invalid")
except Exception as e:
    print(f"Error: {e}")
    # Handle invalid tour mode
```

--------------------------------

### Control Camera Trace Operation

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Initiate or halt the playback of a recorded movement trace for a given camera channel. Valid modes are 'Start' and 'Stop'.

```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.trace_control(channel=1, trace=1, mode='Start')
response = camera.trace_control(channel=1, trace=1, mode='Stop')
```

--------------------------------

### Get PTZ Command Information

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Retrieve information about available PTZ commands for the device. This method returns a plain text string describing the commands.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
info = camera.info_ptz_command()
print(info)
```

--------------------------------

### Error Handling with VAPIX (Python)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Implements error handling for camera operations using a VAPIX camera. This example shows how to catch exceptions and check response status codes for successful or failed movements.

```python
from pyptz import VAPIXCamera

camera = VAPIXCamera('192.168.1.100', 'admin', 'password')

try:
    response = camera.absolute_move(pan=45.0, tilt=30.0, zoom=5, speed=50)
    if response.status_code == 200:
        print("Movement successful")
    elif response.status_code == 401:
        print("Authentication failed")
    else:
        print(f"Error: {response.status_code}")
except Exception as e:
    print(f"Exception: {e}")
```

--------------------------------

### Get PTZ Status via SUNAPI

Source: https://github.com/jahongir7174/pyptz/blob/master/README.md

Connect to a Hanwha camera using the SUNAPI and retrieve its current Pan, Tilt, and Zoom status. Use the camera's IP address, username, and password for connection.

```python
from pyptz.sunapi_control import SUNAPICamera

sunapi_camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
pan, tilt, zoom = sunapi_camera.get_ptz_status()[:3]
print(pan, tilt, zoom)
```

--------------------------------

### Initialize Camera Connections

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/INDEX.md

Instantiate camera objects for different protocols. Ensure correct IP addresses, ports, usernames, and passwords are provided.

```python
from pyptz import ONVIFCamera, VAPIXCamera, SUNAPICamera

onvif = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
vapix = VAPIXCamera('192.168.1.100', 'admin', 'password')
sunapi = SUNAPICamera('192.168.1.100', 'admin', 'password')
```

--------------------------------

### group_control

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Starts or stops a Group operation, which is a preset sequence. Requires channel, group identifier, and mode ('Start' or 'Stop').

```APIDOC
## Method: group_control

### Description
Start or stop a Group operation (preset sequence).

### Signature
```python
def group_control(self, channel: int, group: int, mode: str) -> requests.Response
```

### Parameters
#### Path Parameters
- **channel** (int) - Required - Channel number
- **group** (int) - Required - Group sequence identifier
- **mode** (str) - Required - Control mode: "Start" or "Stop"

### Returns
`requests.Response` object with status code and response content

### Throws
- `Exception` if mode is not "Start", "Stop", or None

### Example
```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.group_control(channel=1, group=1, mode='Start')
response = camera.group_control(channel=1, group=1, mode='Stop')
```
```

--------------------------------

### Initialize ONVIFCamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Instantiate the ONVIFCamera class to connect to a PTZ camera. Provide the camera's IP address, port, username, and password for authentication.

```python
from pyptz import ONVIFCamera

# Connect to an ONVIF camera
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password123')
```

--------------------------------

### VAPIXCamera Get Speed

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Retrieves the current default movement speed of the camera.

```python
get_speed()
```

--------------------------------

### Work with Presets (Python)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Manages camera presets, including creating, listing, moving to, and removing them. This pattern is useful for saving and recalling specific camera views.

```python
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')

# Create preset
camera.absolute_move(pan=45.0, tilt=30.0, zoom=2.0)
camera.set_preset('entrance')

# List presets
presets = camera.get_preset()
for index, name in presets:
    print(f"Preset {index}: {name}")

# Go to preset
camera.go_to_preset('entrance')

# Remove preset
camera.remove_preset('entrance')
```

--------------------------------

### Initialize and Check PTZ Status (Python)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Initializes an ONVIF camera connection and retrieves its current PTZ status. Ensure correct camera IP, port, username, and password are provided.

```python
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
pan, tilt, zoom = camera.get_ptz_status()
print(f"Current position: Pan={pan}, Tilt={tilt}, Zoom={zoom}")
```

--------------------------------

### Preset Methods

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Manage and navigate to camera presets for quick positioning.

```APIDOC
## Preset Methods

### set_preset

Sets a new preset position with a given name.

#### Signature

`set_preset(preset_name: str)`

### get_preset

Retrieves a list of all configured presets.

#### Signature

`get_preset() → list[(int, str)]`

### go_to_preset

Moves the camera to a specified preset.

#### Signature

`go_to_preset(preset)`

### remove_preset

Removes a preset by its name.

#### Signature

`remove_preset(preset_name: str)`

### set_home_position

Sets the current camera position as the home position.

#### Signature

`set_home_position()`

### go_home_position

Moves the camera to the home position.

#### Signature

`go_home_position(speed/channel)`
```

--------------------------------

### ONVIFCamera Get PTZ Status

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Retrieves the current Pan-Tilt-Zoom status of the camera.

```python
get_ptz_status()
```

--------------------------------

### ONVIFCamera Constructor

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Initializes a connection to an ONVIF camera using its IP address, port, username, and password for authentication.

```APIDOC
## ONVIFCamera Constructor

### Description
Initializes a connection to an ONVIF camera using its IP address, port, username, and password for authentication.

### Parameters
#### Path Parameters
- **ip** (str) - Required - IP address of the ONVIF camera
- **port** (str) - Required - Port number of the ONVIF service
- **username** (str) - Required - Username for HTTP Digest authentication
- **password** (str) - Required - Password for HTTP Digest authentication

### Request Example
```python
from pyptz import ONVIFCamera

# Connect to an ONVIF camera
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password123')
```
```

--------------------------------

### Get PTZ Status (ONVIF/VAPIX)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Retrieves the current Pan, Tilt, and Zoom status for ONVIF/VAPIX cameras.

```python
pan, tilt, zoom = camera.get_ptz_status()
# Type: tuple[float, float, float]
```

--------------------------------

### Import Main Package

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Import the main camera classes from the pyptz package.

```python
# Main package imports
from pyptz import ONVIFCamera, VAPIXCamera, SUNAPICamera
```

--------------------------------

### Initialize SUNAPICamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Instantiate the SUNAPICamera class to connect to a Hanwha camera. Provide the camera's IP address, username, and password for authentication.

```python
from pyptz import SUNAPICamera

# Connect to a Hanwha SUNAPI camera
camera = SUNAPICamera('192.168.1.100', 'admin', 'password123')
```

--------------------------------

### Retrieve SUNAPICamera Attributes Information

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Call the attributes_information method to get device capabilities. This method requires no parameters.

```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.attributes_information()
print(response.text)
```

--------------------------------

### Initialize VAPIXCamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Instantiate the VAPIXCamera class to connect to an Axis camera. Requires the camera's IP address, username, and password for HTTP Digest authentication.

```python
from pyptz import VAPIXCamera

# Connect to an Axis VAPIX camera
camera = VAPIXCamera('192.168.1.100', 'admin', 'password123')
```

--------------------------------

### tour_control

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Starts or stops a Tour operation, which is a sequence of pre-recorded movements. This method allows for controlling the execution of these tour sequences.

```APIDOC
## Method: tour_control

### Description
Starts or stops a Tour operation (group sequence execution).

### Signature
```python
def tour_control(self, channel: int, tour: int, mode: str) -> requests.Response
```

### Parameters
#### Path Parameters
- **channel** (int) - Required - Channel number
- **tour** (int) - Required - Tour sequence identifier
- **mode** (str) - Required - Control mode: "Start" or "Stop"

### Throws
- `Exception` if mode is not "Start", "Stop", or None

### Example
```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.tour_control(channel=1, tour=1, mode='Start')
response = camera.tour_control(channel=1, tour=1, mode='Stop')
```
```

--------------------------------

### List All Presets

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Retrieves a list of all configured presets on the camera. The format is a list of (number/index, name) tuples.

```python
presets = camera.list_all_preset()
# Type: list[tuple[int, str]]
# Example: [(0, 'entrance'), (1, 'lobby')]
```

--------------------------------

### Get PTZ Camera Speed

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Query the current movement speed of the PTZ head. This method returns the speed as an integer.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
current_speed = camera.get_speed()
print(f"Current speed: {current_speed}")
```

--------------------------------

### List All Presets (Server and Device) with VAPIXCamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Fetches a comprehensive list of all available preset positions, including both server-side and device-specific presets. The output is a list of tuples, each containing a preset number and its name.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
presets = camera.list_all_preset()
for number, name in presets:
    print(f"Preset {number}: {name}")
```

--------------------------------

### VAPIXCamera Constructor

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Instantiate a VAPIXCamera object for controlling Axis cameras. Requires camera IP address, username, and password.

```python
VAPIXCamera(ip: str, user: str, password: str)
```

--------------------------------

### Get PTZ Status

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/INDEX.md

Retrieve the current Pan, Tilt, and Zoom status of the camera. SUNAPI also returns zoom pulse information.

```python
pan, tilt, zoom = onvif.get_ptz_status()
pan, tilt, zoom = vapix.get_ptz_status()
pan, tilt, zoom, zoom_pulse = sunapi.get_ptz_status()
```

--------------------------------

### SUNAPICamera Constructor

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Initializes a SUNAPICamera instance to connect to a Hanwha camera using its IP address, username, and password for HTTP Digest authentication.

```APIDOC
## Class: SUNAPICamera

### Constructor

**Signature:**
```python
def __init__(self, ip: str, user: str, password: str) -> None
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| ip | str | Yes | — | IP address of the Hanwha camera |
| user | str | Yes | — | Username for HTTP Digest authentication |
| password | str | Yes | — | Password for HTTP Digest authentication |

**Returns:** SUNAPICamera instance

**Example:**
```python
from pyptz import SUNAPICamera

# Connect to a Hanwha SUNAPI camera
camera = SUNAPICamera('192.168.1.100', 'admin', 'password123')
```
```

--------------------------------

### Import PyPTZ Camera Classes

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Import all necessary camera control classes from the pyptz library. You can import them individually or as a group.

```python
from pyptz import ONVIFCamera, VAPIXCamera, SUNAPICamera
```

```python
from pyptz import ONVIFCamera
```

```python
from pyptz import VAPIXCamera
```

```python
from pyptz import SUNAPICamera
```

--------------------------------

### VAPIXCamera Constructor

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Initializes a VAPIXCamera instance to connect to an Axis camera. It requires the camera's IP address, username, and password for authentication.

```APIDOC
## Class: VAPIXCamera

### Constructor

**Signature:**
```python
def __init__(self, ip: str, user: str, password: str) -> None
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| ip | str | Yes | — | IP address of the Axis camera |
| user | str | Yes | — | Username for HTTP Digest authentication |
| password | str | Yes | — | Password for HTTP Digest authentication |

**Returns:** VAPIXCamera instance

**Example:**
```python
from pyptz import VAPIXCamera

# Connect to an Axis VAPIX camera
camera = VAPIXCamera('192.168.1.100', 'admin', 'password123')
```
```

--------------------------------

### Control SUNAPICamera Group Operation

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Initiate or terminate a Group operation using group_control. Provide the channel, group identifier, and mode ('Start' or 'Stop').

```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.group_control(channel=1, group=1, mode='Start')
response = camera.group_control(channel=1, group=1, mode='Stop')
```

--------------------------------

### ONVIFCamera Go To Preset

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Moves the camera to a specified preset position.

```python
go_to_preset(preset_position)
```

--------------------------------

### Import from Submodules

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Alternatively, import camera classes directly from their respective submodules.

```python
# Or import from submodules directly
from pyptz.onvif_control import ONVIFCamera
from pyptz.vapix_control import VAPIXCamera
from pyptz.sunapi_control import SUNAPICamera
```

--------------------------------

### Get Camera PTZ Status

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Retrieve the current pan, tilt, and zoom status of the camera. This method returns a tuple of three float values.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
pan, tilt, zoom = camera.get_ptz_status()
print(f"Current position: Pan={pan}, Tilt={tilt}, Zoom={zoom}")
```

--------------------------------

### SUNAPICamera.go_to_preset_position Optional Parameters

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Details the optional preset and preset_name parameters for the go_to_preset_position method in SUNAPICamera. Users should provide either the preset number or its name.

```APIDOC
## SUNAPICamera.go_to_preset_position Optional Parameters

### Optional Preset Parameter (SUNAPI)

**Type:** `int | None`

**Behavior:** When `None`, the `preset_name` parameter should be used. When an int is provided, the preset position number is used.

### Optional Preset Name Parameter (SUNAPI)

**Type:** `str | None`

**Behavior:** When `None`, the `preset` parameter should be used. When a string is provided, the preset position name is used.

**Note:** Either `preset` or `preset_name` should be provided, but not both.
```

--------------------------------

### trace_control

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Starts or stops a Trace operation, which involves playing back a recorded movement path. This method is used to initiate or halt the playback of these recorded traces.

```APIDOC
## Method: trace_control

### Description
Starts or stops a Trace operation (recorded movement playback).

### Signature
```python
def trace_control(self, channel: int, trace: int, mode: str) -> requests.Response
```

### Parameters
#### Path Parameters
- **channel** (int) - Required - Channel number
- **trace** (int) - Required - Trace action identifier
- **mode** (str) - Required - Control mode: "Start" or "Stop"

### Throws
- `Exception` if mode is not "Start", "Stop", or None

### Example
```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.trace_control(channel=1, trace=1, mode='Start')
response = camera.trace_control(channel=1, trace=1, mode='Stop')
```
```

--------------------------------

### Move Camera to Server Preset by Name

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Use this method to move the camera to a preset position identified by its name on the server. Requires the preset name and movement speed.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
response = camera.go_to_server_preset_name('entrance', speed=50)
```

--------------------------------

### Get Current PTZ Status

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Retrieves the current pan, tilt, and zoom position of the camera. The returned values are floats representing the camera's orientation.

```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
pan, tilt, zoom = camera.get_ptz_status()
print(f"Camera position: Pan={pan}, Tilt={tilt}, Zoom={zoom}")
```

--------------------------------

### Import PyPTZ Classes from Submodules

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Alternatively, import camera control classes directly from their respective submodules within the pyptz library.

```python
from pyptz.onvif_control import ONVIFCamera
```

```python
from pyptz.vapix_control import VAPIXCamera
```

```python
from pyptz.sunapi_control import SUNAPICamera
```

--------------------------------

### SUNAPI Control Mode Operations

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Defines the valid string or None values for starting or stopping operations like group, tour, and trace control in SUNAPI cameras.

```APIDOC
## SUNAPI Control Mode Operations

### Description
Specifies the valid string or None values for controlling the start or stop state of group, tour, and trace operations in SUNAPI cameras.

### Method
`SUNAPICamera.group_control(channel, group, mode)`
`SUNAPICamera.tour_control(channel, tour, mode)`
`SUNAPICamera.trace_control(channel, trace, mode)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **channel** (any) - Required - The channel for the control operation.
- **group/tour/trace** (any) - Required - The specific group, tour, or trace to control.
- **mode** (str or None) - Required - One of the following values: "Start", "Stop", or None.

### Request Example
Request example is not provided in the source.

### Response
#### Success Response (200)
Details of the response are not provided in the source.

#### Response Example
Response example is not provided in the source.
```

--------------------------------

### Get PTZ Status from SUNAPICamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Retrieve the current pan, tilt, zoom, and zoom pulse position of the camera. The pan value is normalized to the [0, 360) range.

```python
camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
pan, tilt, zoom, zoom_pulse = camera.get_ptz_status()
print(f"Pan: {pan}, Tilt: {tilt}, Zoom: {zoom}, ZoomPulse: {zoom_pulse}")
```

--------------------------------

### Iterate ONVIF Presets

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Retrieves all presets from an ONVIF camera and prints their names and tokens. Requires an initialized ONVIFCamera object.

```python
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
presets = camera.get_preset_complete()

for preset in presets:
    print(f"Preset: {preset.Name}, Token: {preset.token}")
```

--------------------------------

### Checking for Existing Presets with ONVIFCamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

If you try to create a preset with `set_preset` using a name that already exists on an `ONVIFCamera`, the operation will return `None`. Verify the response is `None` to detect this.

```python
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
camera.set_preset('entrance')
response = camera.set_preset('entrance')  # Already exists
if response is None:
    print("Preset with this name already exists")
```

--------------------------------

### Get PTZ Status Tuple (ONVIF/VAPIX)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Retrieves the current pan, tilt, and zoom status from an ONVIF or VAPIX camera. This tuple provides the core positional information.

```python
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
pan, tilt, zoom = camera.get_ptz_status()
```

--------------------------------

### List All Presets (VAPIX)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Fetches all stored presets from a VAPIX camera, returning a list of tuples where each tuple contains the preset number and its name. This is useful for managing and recalling preset positions.

```python
from pyptz import VAPIXCamera

camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
presets = camera.list_all_preset()

for number, name in presets:
    print(f"Preset {number}: {name}")
```

--------------------------------

### Move Camera to Server Preset by Number

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Use this method to move the camera to a preset position identified by its numeric index on the server. Requires the preset number (0-indexed) and movement speed.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
response = camera.go_to_server_preset_number(number=0, speed=50)
```

--------------------------------

### Get VAPIX Camera Response

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Demonstrates how to interact with a VAPIX camera and print the status code and text of the HTTP response. This is useful for debugging or when a specific response type is not parsed.

```python
from pyptz import VAPIXCamera

camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
response = camera.absolute_move(pan=45.0, tilt=30.0, zoom=5, speed=50)

print(f"Status: {response.status_code}")
print(f"Response: {response.text}")
```

--------------------------------

### VAPIX (Axis) Camera Control

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/package-overview.md

Connect to an Axis camera using VAPIX, get PTZ status, move to an absolute position with specified speed, and use server-side presets by name.

```python
from pyptz import VAPIXCamera

# Initialize camera connection
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')

# Get current position
pan, tilt, zoom = camera.get_ptz_status()
print(f"Position: Pan={pan}, Tilt={tilt}, Zoom={zoom}")

# Move to absolute position with speed
camera.absolute_move(pan=45.0, tilt=30.0, zoom=5, speed=50)

# Move to preset by name
camera.go_to_server_preset_name('entrance', speed=50)

# List all presets
presets = camera.list_all_preset()
for number, name in presets:
    print(f"Preset {number}: {name}")
```

--------------------------------

### ONVIF Camera Authentication

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Initializes an ONVIF camera using HTTP Digest authentication. Ensure correct IP, port, username, and password are provided. Invalid credentials will result in an HTTP 401 error and process termination.

```python
camera = ONVIFCamera(
    ip='192.168.1.100',
    port='8080',
    username='admin',
    password='password123'
)
```

--------------------------------

### Perform Continuous Camera Movement

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Use this method to initiate continuous pan, tilt, or zoom at specified velocities. Ensure the ONVIFCamera object is initialized with correct IP address, port, username, and password.

```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
response = camera.continuous_move(pan=0.5, tilt=0.3, zoom=0.1)
```

--------------------------------

### Handle Preset Not Found (ONVIF)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Checks if a 'go_to_preset' operation returned None, indicating the preset was not found. This method does not raise an exception for missing presets.

```python
response = camera.go_to_preset('nonexistent')
if response is None:
    print("Preset not found")
```

--------------------------------

### Get ONVIF PTZ Status

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Retrieves the current Pan, Tilt, and Zoom status of an ONVIF camera. Direct usage of the internal object is not recommended; use this method instead. Requires an initialized ONVIFCamera object.

```python
# Direct usage is not recommended; use get_ptz_status() instead
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
pan, tilt, zoom = camera.get_ptz_status()
```

--------------------------------

### ONVIFCamera Class Methods

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/INDEX.md

Documentation for the ONVIFCamera class, detailing methods for controlling PTZ cameras using the ONVIF protocol. This includes movement, position, and preset management.

```APIDOC
## ONVIFCamera Methods

### Description
Provides methods to control PTZ cameras via the ONVIF protocol. This class offers functionalities for camera movement, setting and retrieving PTZ status, and managing presets.

### Methods
- `absolute_move`
- `continuous_move`
- `relative_move`
- `stop_move`
- `set_home_position`
- `go_home_position`
- `get_ptz_status`
- `set_preset`
- `get_preset`
- `get_preset_complete`
- `remove_preset`
- `go_to_preset`

### Details
Each method includes full signatures, parameter tables, return type documentation, usage examples, and source file references.
```

--------------------------------

### Get PTZ Status Tuple with Zoom Pulse (SUNAPI)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Retrieves the current pan, tilt, zoom, and zoom pulse status from a SUNAPI camera. This includes additional zoom pulse information specific to SUNAPI.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
pan, tilt, zoom, zoom_pulse = camera.get_ptz_status()
```

--------------------------------

### Move Camera Upward (VAPIX)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Demonstrates how to move a VAPIX camera to the 'up' position using the `move()` method. Ensure the VAPIXCamera class is imported.

```python
from pyptz import VAPIXCamera

camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
response = camera.move(position='up', speed=50)
```

--------------------------------

### list_all_preset

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Retrieves a list of all available preset positions, including both server and device presets.

```APIDOC
## Method: list_all_preset

### Description
List all available preset positions (server and device).

### Signature
```python
def list_all_preset(self) -> list[tuple[int, str]]
```

### Parameters
None

### Returns
List of tuples where each tuple contains (preset_number: int, preset_name: str).

### Example
```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
presets = camera.list_all_preset()
for number, name in presets:
    print(f"Preset {number}: {name}")
```
```

--------------------------------

### Get PTZ Status via VAPIX

Source: https://github.com/jahongir7174/pyptz/blob/master/README.md

Connect to an Axis camera using the VAPIX API and retrieve its current Pan, Tilt, and Zoom status. Provide the camera's IP address, username, and password.

```python
from pyptz.vapix_control import VAPIXCamera

vapix_camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
pan, tilt, zoom = vapix_camera.get_ptz_status()
print(pan, tilt, zoom)
```

--------------------------------

### Move to Absolute Position (Python)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Demonstrates moving a camera to a specific absolute PTZ position using different protocols. Note the variations in parameter handling, such as the 'speed' parameter for VAPIX.

```python
# ONVIF
response = camera.absolute_move(pan=45.0, tilt=30.0, zoom=1.5)
```

```python
# VAPIX
response = camera.absolute_move(pan=45.0, tilt=30.0, zoom=5, speed=50)
```

```python
# SUNAPI
response = camera.absolute_move(pan=45.0, tilt=30.0, zoom=5.0)
```

--------------------------------

### go_to_server_preset_name

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Moves the camera to a preset position identified by its name on the server. This method allows for precise positioning based on named presets.

```APIDOC
## Method: go_to_server_preset_name

### Description
Move the camera to a preset position identified by name on the server.

### Signature
```python
def go_to_server_preset_name(self, name: str, speed: int) -> requests.Response
```

### Parameters
#### Path Parameters
- **name** (str) - Yes - Name of the server preset
- **speed** (int) - Yes - Speed of movement

### Request Example
```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
response = camera.go_to_server_preset_name('entrance', speed=50)
```

### Response
`requests.Response` object with status code and response content
```

--------------------------------

### Control Auxiliary Device (SUNAPI)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Illustrates how to control auxiliary devices on a SUNAPI camera, such as turning on the wiper, using the `aux_control()` method. The SUNAPICamera class is required.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.aux_control('WiperOn')
```

--------------------------------

### SUNAPI Relative Move with Boundary Safety (Python)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/README.md

Utilizes the SUNAPI protocol for relative PTZ movements, demonstrating automatic boundary clamping. This ensures movements stay within the camera's physical or configured limits.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')

# Relative move automatically clamps to device limits
# Pan: wraps at 360°, Tilt: [-20°, 90°], Zoom: [1, 40]
response = camera.relative_move(pan=10.0, tilt=5.0, zoom=2)
```

--------------------------------

### Control Camera Movement (SUNAPI)

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/types.md

Shows how to control the movement of a SUNAPI camera using the `movement_control()` method with the 'up' direction. The SUNAPICamera class must be imported.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
response = camera.movement_control(direction='up', speed=50.0)
```

--------------------------------

### Handle Pan Boundary Exceeded in SUNAPI

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

Demonstrates how SUNAPI automatically adjusts pan values to wrap around the 360-degree limit. Use this when relative pan movements might exceed hardware boundaries.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
# If current pan is 350 and we add 20, it becomes 10 (not 370)
response = camera.relative_move(pan=20.0, tilt=None, zoom=None)
```

--------------------------------

### Prevent VAPIX/SUNAPI Authentication Failures

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

Test credentials with a simple camera method call within a try-except block to catch `SystemExit` if authentication fails. This prevents unexpected process termination.

```python
# Test credentials before using in production
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
try:
    status = camera.get_ptz_status()
    print("Authentication successful")
except SystemExit:
    print("Authentication failed")
```

--------------------------------

### VAPIXCamera Go To Server Preset Name

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Moves the camera to a server-defined preset position by its name, with optional speed control.

```python
go_to_server_preset_name(name, speed)
```

--------------------------------

### List Device Presets with VAPIXCamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/VAPIXCamera.md

Retrieves a list of all preset positions stored directly on the VAPIX device. Requires an initialized VAPIXCamera object.

```python
camera = VAPIXCamera('192.168.1.100', 'admin', 'password')
response = camera.list_preset_device()
print(response.text)
```

--------------------------------

### SUNAPICamera Go To Preset Position

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Moves the camera to a specified preset position by name or number.

```python
go_to_preset_position(preset, preset_name)
```

--------------------------------

### ONVIFCamera Go Home Position

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Moves the camera to its pre-defined home position.

```python
go_home_position()
```

--------------------------------

### go_to_preset

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Moves the ONVIF camera to a specified preset position. This method requires the name of the preset to navigate to.

```APIDOC
## Method: go_to_preset

### Description
Move the camera to a saved preset position.

### Signature
```python
def go_to_preset(self, preset_position: str) -> object | None:
```

### Parameters
#### Path Parameters
- **preset_position** (str) - Required - Name of the preset position to move to

### Returns
ONVIF service response object if preset exists, None if preset not found

### Example
```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
response = camera.go_to_preset('entrance')
if response is not None:
    print("Camera moved to preset position")
```
```

--------------------------------

### Catch ONVIF Connection Errors

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

Use a try-except block to catch exceptions raised by the `onvif-zeep` library during ONVIF camera connection attempts. This is useful for handling network or authentication issues.

```python
from onvif import ONVIFCamera as ONVIFCameraLib

try:
    camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'wrong_password')
except Exception as e:
    print(f"Connection error: {e}")
```

--------------------------------

### Move ONVIF Camera to Preset Position

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Use this snippet to move an ONVIF camera to a specific preset position. Ensure the ONVIFCamera object is initialized with correct camera credentials and IP address. The response will be None if the preset position does not exist.

```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
response = camera.go_to_preset('entrance')
if response is not None:
    print("Camera moved to preset position")
```

--------------------------------

### ONVIFCamera Set Home Position

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/REFERENCE.md

Sets the current camera position as the home position.

```python
set_home_position()
```

--------------------------------

### Capture Snapshot After Moving to Preset with SUNAPI Camera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/package-overview.md

This code moves a SUNAPI camera to a specific preset position and then captures a snapshot, saving it with a timestamped filename. Requires camera IP, username, and password.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')

# Move to incident location
camera.go_to_preset_position(preset=1, preset_name=None)

# Capture snapshot
image = camera.snap_shot()
if image:
    import datetime
    filename = f"incident_{datetime.datetime.now().isoformat()}.jpg"
    image.save(filename)
```

--------------------------------

### Capture Camera Snapshot

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/SUNAPICamera.md

Capture a snapshot image from the camera. Returns a PIL Image object on success or None on failure.

```python
from pyptz import SUNAPICamera

camera = SUNAPICamera('192.168.1.100', 'admin', 'password')
image = camera.snap_shot()
if image:
    image.save('snapshot.jpg')
else:
    print("Failed to capture snapshot")
```

--------------------------------

### get_preset_complete

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/api-reference/ONVIFCamera.md

Retrieves complete preset objects from the ONVIF service, including all configuration details for each preset.

```APIDOC
## Method: get_preset_complete

### Description
Retrieve complete preset objects from the ONVIF service.

### Signature
```python
def get_preset_complete(self) -> object
```

### Parameters
None

### Returns
ONVIF preset objects containing all preset configuration details

### Example
```python
camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
presets = camera.get_preset_complete()
for preset in presets:
    print(f"Preset name: {preset.Name}, Token: {preset.token}")
```
```

--------------------------------

### Checking for Nonexistent Presets with ONVIFCamera

Source: https://github.com/jahongir7174/pyptz/blob/master/_autodocs/errors.md

When using `ONVIFCamera`, attempting to go to or remove a preset that does not exist will return `None`. Check the response for `None` to handle this case.

```python
from pyptz import ONVIFCamera

camera = ONVIFCamera('192.168.1.100', '8080', 'admin', 'password')
response = camera.go_to_preset('nonexistent_preset')
if response is None:
    print("Preset not found")
```