grafton_visca/command/

focus.rs

//! Focus control commands for VISCA cameras.
//!
//! This module provides commands for controlling camera focus functionality,
//! including auto/manual modes, directional focus, and direct position control.
//!
//! # VISCA Compliance
//! Most commands in this module are part of the baseline VISCA specification.
//!
//! ## Vendor-Specific Commands
//! - `FocusLock` - PtzOptics specific
//! - `PushAF` - Sony FR7 specific

use grafton_visca_macros::ViscaEnum;

use crate::{
    command::encode::ViscaCommand,
    error::Error,
    timeout::CommandCategory,
    types::{FocusPosition, SpeedLevel},
    visca_command,
};

/// Focus mode setting.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ViscaEnum)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS), ts(export))]
pub enum FocusMode {
    /// Automatic focus mode.
    Auto = 0x02,
    /// Manual focus mode.
    Manual = 0x03,
}

/// Focus range setting.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ViscaEnum)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS), ts(export))]
pub enum FocusRange {
    /// Normal focus range.
    Normal = 0x00,
    /// 10x focus range.
    Range10x = 0x01,
    /// 4.3x focus range.
    Range4_3x = 0x02,
    /// 2.1x focus range.
    Range2_1x = 0x03,
    /// 1x focus range.
    Range1x = 0x04,
    /// 0.35x focus range.
    Range0_35x = 0x05,
}

crate::visca_range_type! {
    /// Variable focus speed.
    ///
    /// Valid range: 0 to 7 where 0 is the slowest and 7 is the fastest.
    FocusSpeed: u8 {
        min: 0,
        max: 7
    }
}

impl From<SpeedLevel> for FocusSpeed {
    fn from(level: SpeedLevel) -> Self {
        Self(level.to_focus_speed())
    }
}

/// Focus control commands.
///
/// Provides various ways to control camera focus.
#[derive(Debug, Copy, Clone)]
pub enum Focus {
    /// Stop any focus movement.
    Stop,
    /// Move focus far at standard speed.
    Far,
    /// Move focus near at standard speed.
    Near,
    /// Move focus far at variable speed.
    FarWithSpeed(FocusSpeed),
    /// Move focus near at variable speed.
    NearWithSpeed(FocusSpeed),
    /// Set focus to specific position.
    Position(FocusPosition),
    /// Enable auto focus mode.
    Auto,
    /// Enable manual focus mode.
    Manual,
    /// Trigger one-push auto focus (focus once then return to manual).
    OnePushTrigger,
    /// Set focus to infinity.
    Infinity,
    /// Toggle between auto and manual focus modes.
    ///
    /// **Vendor-Specific**: PTZOptics cameras.
    Toggle,
    /// Snap focus (one-push AF while in manual mode).
    ///
    /// Triggers a single autofocus operation, then returns to manual focus mode.
    /// **Vendor-Specific**: Some vendor/firmware command references document
    /// this opcode, but built-in profiles only expose it when their profile
    /// metadata reports one-push focus support.
    Snap,
}

impl ViscaCommand for Focus {
    const MAX_SIZE: usize = 9;
    const TIMEOUT_CATEGORY: CommandCategory = CommandCategory::Movement;

    fn write_into(
        &self,
        camera_id: crate::camera_id::CameraId,
        buffer: &mut [u8],
    ) -> Result<usize, Error> {
        use crate::command::bytes::{constants, ConstCommandBuilder};

        match self {
            Self::Stop | Self::Far | Self::Near => {
                // Demonstrate type-state pattern usage for Stop command
                if matches!(self, Self::Stop) {
                    // Use the new type-state API
                    let builder = ConstCommandBuilder::<6>::new()
                        .append(constants::focus::MOVEMENT_PREFIX)
                        .push(0x00)
                        .with_camera_id(camera_id)
                        .terminate();

                    // Now we can access bytes only after termination
                    builder.build_into(buffer)
                } else {
                    // Use legacy API for other commands
                    let mut builder = ConstCommandBuilder::<6>::new();
                    builder.append_mut(constants::focus::MOVEMENT_PREFIX);
                    builder.push_mut(match self {
                        Self::Far => 0x02,
                        Self::Near => 0x03,
                        _ => unreachable!(),
                    });
                    builder.with_camera_id_mut(camera_id);
                    builder.terminate().build_into(buffer)
                }
            }
            Self::FarWithSpeed(_) | Self::NearWithSpeed(_) => {
                let mut builder = ConstCommandBuilder::<6>::new();
                builder.append_mut(constants::focus::MOVEMENT_PREFIX);
                builder.push_mut(match self {
                    Self::FarWithSpeed(s) => 0x20 | s.value(),
                    Self::NearWithSpeed(s) => 0x30 | s.value(),
                    _ => unreachable!(),
                });
                builder.with_camera_id_mut(camera_id);
                builder.terminate().build_into(buffer)
            }
            Self::Position(position) => {
                let builder = ConstCommandBuilder::<9>::new()
                    .append(constants::focus::POSITION_PREFIX)
                    .push_visca_u16(position.value())
                    .with_camera_id(camera_id)
                    .terminate();
                builder.build_into(buffer)
            }
            Self::Auto | Self::Manual | Self::Toggle | Self::Snap => {
                let mut builder = ConstCommandBuilder::<6>::new();
                builder.append_mut(constants::focus::MODE_PREFIX);
                builder.push_mut(match self {
                    Self::Auto => 0x02,
                    Self::Manual => 0x03,
                    Self::Snap => 0x04,
                    Self::Toggle => 0x10,
                    _ => unreachable!(),
                });
                builder.with_camera_id_mut(camera_id);
                builder.terminate().build_into(buffer)
            }
            Self::OnePushTrigger | Self::Infinity => {
                let mut builder = ConstCommandBuilder::<6>::new();
                builder.append_mut(constants::focus::ONE_PUSH_PREFIX);
                builder.push_mut(match self {
                    Self::OnePushTrigger => 0x01,
                    Self::Infinity => 0x02,
                    _ => unreachable!(),
                });
                builder.with_camera_id_mut(camera_id);
                builder.terminate().build_into(buffer)
            }
        }
    }
}

/// Focus Zone selection (baseline VISCA).
///
/// Determines which area of the image the camera uses for auto focus.
#[derive(Debug, Copy, Clone, PartialEq, Eq, ViscaEnum)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS), ts(export))]
pub enum FocusZone {
    /// Focus on the top area of the image.
    Top = 0x00,
    /// Focus on the center area of the image (default).
    Center = 0x01,
    /// Focus on the bottom area of the image.
    Bottom = 0x02,
}

visca_command! {
        /// Command to set the focus zone.
    pub struct FocusZoneCommand {
        zone: FocusZone,
    };
    prefix = [0x01, 0x04, 0xAA];
    param = match *zone {
        FocusZone::Top => 0x00u8,
        FocusZone::Center => 0x01u8,
        FocusZone::Bottom => 0x02u8,
    };
    max_param_size = 1;
    category = CommandCategory::Quick;
}

impl FocusZoneCommand {
    /// Create a new focus zone command.
    pub fn new(zone: FocusZone) -> Self {
        Self { zone }
    }
}

/// Auto Focus Sensitivity levels.
///
/// Controls how responsive the auto focus system is to changes in the scene.
#[derive(Debug, Copy, Clone, PartialEq, Eq, ViscaEnum)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS), ts(export))]
pub enum AutoFocusSensitivity {
    /// Low sensitivity - slower focus response, more stable in changing scenes.
    Low = 0x00,
    /// Normal sensitivity - balanced focus response (default).
    Normal = 0x01,
    /// High sensitivity - quick focus response to scene changes.
    High = 0x02,
}

visca_command! {
        /// Command to set auto focus sensitivity.
    pub struct AutoFocusSensitivityCommand {
        sensitivity: AutoFocusSensitivity,
    };
    prefix = [0x01, 0x04, 0x58];
    param = match *sensitivity {
        AutoFocusSensitivity::High => 0x02u8,
        AutoFocusSensitivity::Normal => 0x01u8,
        AutoFocusSensitivity::Low => 0x00u8,
    };
    max_param_size = 1;
    category = CommandCategory::Quick;
}

impl AutoFocusSensitivityCommand {
    /// Create a new auto focus sensitivity command.
    pub fn new(sensitivity: AutoFocusSensitivity) -> Self {
        Self { sensitivity }
    }
}

visca_command! {
        /// Command to set the focus near limit.
    ///
    /// Sets the minimum focus distance to prevent the camera from
    /// focusing on objects too close to the lens.
    pub struct FocusNearLimitCommand {
        position: FocusPosition,
    };
    prefix = [0x01, 0x04, 0x28];
    param = {
        let value = position.value();
        [
            ((value >> 12) & 0x0F) as u8,
            ((value >> 8) & 0x0F) as u8,
            ((value >> 4) & 0x0F) as u8,
            (value & 0x0F) as u8,
        ]
    };
    max_param_size = 4;
    category = CommandCategory::Quick;
}

impl FocusNearLimitCommand {
    /// Create a new focus near limit command.
    pub fn new(position: FocusPosition) -> Self {
        Self { position }
    }
}

/// Focus Lock command.
///
/// Controls whether the camera locks focus at the current position.
///
/// **Vendor-Specific**: This command is specific to PtzOptics cameras.
#[derive(Debug, Copy, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS), ts(export))]
pub enum FocusLock {
    /// Enable focus lock
    On,
    /// Disable focus lock
    Off,
}

impl ViscaCommand for FocusLock {
    const MAX_SIZE: usize = 6;
    const TIMEOUT_CATEGORY: CommandCategory = CommandCategory::Quick;

    fn write_into(
        &self,
        camera_id: crate::camera_id::CameraId,
        buffer: &mut [u8],
    ) -> Result<usize, Error> {
        use crate::command::bytes::ConstCommandBuilder;

        let builder = match self {
            Self::On => ConstCommandBuilder::<6>::new()
                .append(crate::command::bytes::constants::focus::LOCK_PREFIX)
                .push(0x02),
            Self::Off => ConstCommandBuilder::<6>::new()
                .append(crate::command::bytes::constants::focus::LOCK_PREFIX)
                .push(0x03),
        };

        builder
            .with_camera_id(camera_id)
            .terminate()
            .build_into(buffer)
    }
}

/// Push AF command.
///
/// Controls the Push Auto Focus feature which temporarily activates
/// auto focus when pressed.
///
/// **Vendor-Specific**: This command is specific to Sony FR7 cameras.
#[derive(Debug, Copy, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
#[cfg_attr(feature = "ts-rs", derive(ts_rs::TS), ts(export))]
pub enum PushAF {
    /// Press Push AF button (activate temporary auto focus)
    Press,
    /// Release Push AF button
    Release,
}

impl ViscaCommand for PushAF {
    const MAX_SIZE: usize = 8;
    const TIMEOUT_CATEGORY: CommandCategory = CommandCategory::Quick;

    fn write_into(
        &self,
        camera_id: crate::camera_id::CameraId,
        buffer: &mut [u8],
    ) -> Result<usize, Error> {
        use crate::command::bytes::{constants, ConstCommandBuilder};

        let mut builder = ConstCommandBuilder::<8>::new();
        builder.append_mut(constants::focus::PUSH_AF_PREFIX);
        builder.push_mut(match self {
            Self::Press => 0x01,
            Self::Release => 0x00,
        });
        builder
            .with_camera_id(camera_id)
            .terminate()
            .build_into(buffer)
    }
}

#[cfg(test)]
#[allow(clippy::panic)]
mod tests {
    use super::*;
    use crate::command::bytes::VISCA_TERMINATOR;
    use crate::command::encode::ViscaCommand;
    use crate::macros::test_utils::visca_test;
    use crate::timeout::CommandTimeout;

    visca_test!(
        Focus,
        test_focus_command_stop,
        Focus::Stop,
        &[0x81, 0x01, 0x04, 0x08, 0x00, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_far_standard,
        Focus::Far,
        &[0x81, 0x01, 0x04, 0x08, 0x02, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_near_standard,
        Focus::Near,
        &[0x81, 0x01, 0x04, 0x08, 0x03, VISCA_TERMINATOR]
    );

    #[test]
    fn test_focus_command_far_variable() {
        // Valid speeds
        for speed_val in 0..=7 {
            let speed = FocusSpeed::new(speed_val)
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}"));
            let cmd = Focus::FarWithSpeed(speed);
            assert_eq!(
                cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                    .map(|b| b.to_vec())
                    .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
                vec![0x81, 0x01, 0x04, 0x08, 0x20 | speed_val, VISCA_TERMINATOR]
            );
        }
    }

    #[test]
    fn test_focus_command_near_variable() {
        // Valid speeds
        for speed_val in 0..=7 {
            let speed = FocusSpeed::new(speed_val)
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}"));
            let cmd = Focus::NearWithSpeed(speed);
            assert_eq!(
                cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                    .map(|b| b.to_vec())
                    .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
                vec![0x81, 0x01, 0x04, 0x08, 0x30 | speed_val, VISCA_TERMINATOR]
            );
        }
    }

    #[test]
    fn test_focus_speed_validation() {
        // Valid speeds
        assert!(FocusSpeed::new(0).is_ok());
        assert!(FocusSpeed::new(7).is_ok());

        // Invalid speeds
        assert!(matches!(
            FocusSpeed::new(8),
            Err(Error::InvalidParameter { .. })
        ));
    }

    #[test]
    fn test_focus_command_position() {
        let cmd = Focus::Position(FocusPosition::new(0x1234));
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![
                0x81,
                0x01,
                0x04,
                0x48,
                0x01,
                0x02,
                0x03,
                0x04,
                VISCA_TERMINATOR
            ]
        );

        let cmd = Focus::Position(FocusPosition::new(0xF000));
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![
                0x81,
                0x01,
                0x04,
                0x48,
                0x0F,
                0x00,
                0x00,
                0x00,
                VISCA_TERMINATOR
            ]
        );
    }

    visca_test!(
        Focus,
        test_focus_command_auto,
        Focus::Auto,
        &[0x81, 0x01, 0x04, 0x38, 0x02, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_manual,
        Focus::Manual,
        &[0x81, 0x01, 0x04, 0x38, 0x03, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_toggle,
        Focus::Toggle,
        &[0x81, 0x01, 0x04, 0x38, 0x10, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_snap,
        Focus::Snap,
        &[0x81, 0x01, 0x04, 0x38, 0x04, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_one_push_trigger,
        Focus::OnePushTrigger,
        &[0x81, 0x01, 0x04, 0x18, 0x01, VISCA_TERMINATOR]
    );

    visca_test!(
        Focus,
        test_focus_command_infinity,
        Focus::Infinity,
        &[0x81, 0x01, 0x04, 0x18, 0x02, VISCA_TERMINATOR]
    );

    #[test]
    fn test_focus_zone_command() {
        let cmd = FocusZoneCommand {
            zone: FocusZone::Top,
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![0x81, 0x01, 0x04, 0xAA, 0x00, VISCA_TERMINATOR]
        );

        let cmd = FocusZoneCommand {
            zone: FocusZone::Center,
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![0x81, 0x01, 0x04, 0xAA, 0x01, VISCA_TERMINATOR]
        );

        let cmd = FocusZoneCommand {
            zone: FocusZone::Bottom,
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![0x81, 0x01, 0x04, 0xAA, 0x02, VISCA_TERMINATOR]
        );
    }

    #[test]
    fn test_auto_focus_sensitivity_command() {
        let cmd = AutoFocusSensitivityCommand {
            sensitivity: AutoFocusSensitivity::High,
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![0x81, 0x01, 0x04, 0x58, 0x02, VISCA_TERMINATOR]
        );

        let cmd = AutoFocusSensitivityCommand {
            sensitivity: AutoFocusSensitivity::Normal,
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![0x81, 0x01, 0x04, 0x58, 0x01, VISCA_TERMINATOR]
        );

        let cmd = AutoFocusSensitivityCommand {
            sensitivity: AutoFocusSensitivity::Low,
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![0x81, 0x01, 0x04, 0x58, 0x00, VISCA_TERMINATOR]
        );
    }

    #[test]
    fn test_focus_near_limit_command() {
        let cmd = FocusNearLimitCommand {
            position: FocusPosition::new(0x1234),
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![
                0x81,
                0x01,
                0x04,
                0x28,
                0x01,
                0x02,
                0x03,
                0x04,
                VISCA_TERMINATOR
            ]
        );

        let cmd = FocusNearLimitCommand {
            position: FocusPosition::new(0x1000),
        };
        assert_eq!(
            cmd.to_bytes(crate::camera_id::CameraId::CAMERA_1)
                .map(|b| b.to_vec())
                .unwrap_or_else(|e| panic!("Test assertion failed: {e:?}")),
            vec![
                0x81,
                0x01,
                0x04,
                0x28,
                0x01,
                0x00,
                0x00,
                0x00,
                VISCA_TERMINATOR
            ]
        );
    }

    #[test]
    fn test_command_categories() {
        assert_eq!(Focus::Stop.timeout_class(), CommandCategory::Movement);
        assert_eq!(Focus::Auto.timeout_class(), CommandCategory::Movement);
        assert_eq!(
            FocusZoneCommand {
                zone: FocusZone::Top
            }
            .timeout_class(),
            CommandCategory::Quick
        );
        assert_eq!(
            AutoFocusSensitivityCommand {
                sensitivity: AutoFocusSensitivity::High
            }
            .timeout_class(),
            CommandCategory::Quick
        );
        assert_eq!(
            FocusNearLimitCommand {
                position: FocusPosition::new(0x1000)
            }
            .timeout_class(),
            CommandCategory::Quick
        );
    }
}