Add experimental move-seek command

Author: jochenwezel

AGENTS.md

@@ -16,4 +16,8 @@
   short aliases are `-x` and `-y`.
 - Unknown command-line parameters must fail loudly. Do not silently ignore
   parser errors or selector options that are not valid for a verb.
+- DirectShow/IAMCameraControl results can differ between the agent sandbox and
+  a normal interactive process. If camera capability reads unexpectedly report
+  "IAMCameraControl (UVC) is not supported", re-run the same command outside the
+  sandbox before treating it as a real device limitation.
 - Always create GitHub issues in English.

PTZControlConsole/Program.cs

@@ -34,6 +34,7 @@ class Program
         typeof(ZoomAbsoluteOptions),
         typeof(ZoomRelativeOptions),
         typeof(MoveAbsoluteOptions),
+        typeof(MoveSeekOptions),
         typeof(MoveRelativeOptions)
     };
     private static readonly Type[] AllVerbTypes = PublicVerbTypes.Concat(new[] { typeof(DocsOptions) }).ToArray();
@@ -131,6 +132,7 @@ static int RunParsed(object parsed) =>
             ZoomAbsoluteOptions options => SetAbsoluteZoom(ResolveCamera(ToOptions(options)), options.Value, ParseMode(options.ModeName)),
             ZoomRelativeOptions options => SetRelativeZoom(ResolveCamera(ToOptions(options)), options.ValueDelta, ParseMode(options.ModeName)),
             MoveAbsoluteOptions options => MoveAbsolute(ResolveCamera(ToOptions(options)), ToOptions(options), ParseMode(options.ModeName)),
+            MoveSeekOptions options => MoveSeek(ResolveCamera(ToOptions(options)), ToOptions(options), ParseMode(options.ModeName), options),
             MoveRelativeOptions options => MoveRelative(ResolveCamera(ToOptions(options)), ToOptions(options), ParseMode(options.ModeName)),
             DocsOptions options => GenerateDocs(options),
             _ => throw new ArgumentException("Unknown command.")
@@ -600,6 +602,42 @@ static int MoveAbsolute(string camera, Options options, ValueMode mode)
         return Ok();
     }
 
+    static int MoveSeek(string camera, Options options, ValueMode mode, MoveSeekOptions seekOptions)
+    {
+        if (options.X is null && options.Y is null) throw new ArgumentException("move-seek requires -x/--pan and/or -y/--tilt.");
+
+        var panTarget = options.X is null ? (int?)null : ConvertAbsoluteValue(camera, UvcCameraProperty.Pan, options.X.Value, mode);
+        var tiltTarget = options.Y is null ? (int?)null : ConvertAbsoluteValue(camera, UvcCameraProperty.Tilt, options.Y.Value, mode);
+        var panTolerance = panTarget is null ? 0 : ConvertSeekTolerance(camera, UvcCameraProperty.Pan, seekOptions.Tolerance, mode);
+        var tiltTolerance = tiltTarget is null ? 0 : ConvertSeekTolerance(camera, UvcCameraProperty.Tilt, seekOptions.Tolerance, mode);
+        var maxIterations = Math.Max(1, seekOptions.MaxIterations);
+        var settleMs = Math.Max(0, seekOptions.SettleMilliseconds);
+
+        var lastDistance = GetSeekDistance(camera, panTarget, tiltTarget);
+        for (var iteration = 1; iteration <= maxIterations; iteration++)
+        {
+            var panCurrent = panTarget is null ? (int?)null : CameraBackend.GetValue(camera, UvcCameraProperty.Pan);
+            var tiltCurrent = tiltTarget is null ? (int?)null : CameraBackend.GetValue(camera, UvcCameraProperty.Tilt);
+            var panReached = panTarget is null || Math.Abs(panTarget.Value - panCurrent!.Value) <= panTolerance;
+            var tiltReached = tiltTarget is null || Math.Abs(tiltTarget.Value - tiltCurrent!.Value) <= tiltTolerance;
+            if (panReached && tiltReached)
+                return Ok();
+
+            var panDirection = panTarget is null ? (int?)null : Math.Sign(panTarget.Value - panCurrent!.Value);
+            var tiltDirection = tiltTarget is null ? (int?)null : Math.Sign(tiltTarget.Value - tiltCurrent!.Value);
+            CameraBackend.MoveRelativePanTilt(camera, panDirection, tiltDirection);
+            if (settleMs > 0)
+                Thread.Sleep(settleMs);
+
+            var distance = GetSeekDistance(camera, panTarget, tiltTarget);
+            if (distance >= lastDistance)
+                throw new InvalidOperationException($"move-seek did not make progress after {iteration} iteration(s). Current distance: {distance}; previous distance: {lastDistance}.");
+            lastDistance = distance;
+        }
+
+        throw new TimeoutException($"move-seek did not reach the target within {maxIterations} iteration(s). Final distance: {lastDistance}.");
+    }
+
     static int MoveRelative(string camera, Options options, ValueMode mode)
     {
         if (options.X is null && options.Y is null) throw new ArgumentException("move-relative requires -x/--pan and/or -y/--tilt.");
@@ -616,6 +654,16 @@ static int MoveRelative(string camera, Options options, ValueMode mode)
         return Ok();
     }
 
+    static int GetSeekDistance(string camera, int? panTarget, int? tiltTarget)
+    {
+        var distance = 0;
+        if (panTarget is not null)
+            distance += Math.Abs(panTarget.Value - CameraBackend.GetValue(camera, UvcCameraProperty.Pan));
+        if (tiltTarget is not null)
+            distance += Math.Abs(tiltTarget.Value - CameraBackend.GetValue(camera, UvcCameraProperty.Tilt));
+        return distance;
+    }
+
     static int Ok()
     {
         Console.WriteLine("OK");
@@ -901,6 +949,16 @@ static int ClampRawValue(string camera, UvcCameraProperty property, int value)
         return Math.Clamp(value, range.min, range.max);
     }
 
+    static int ConvertSeekTolerance(string camera, UvcCameraProperty property, int tolerance, ValueMode mode)
+    {
+        tolerance = Math.Max(0, tolerance);
+        if (mode == ValueMode.Raw)
+            return tolerance;
+
+        var range = CameraBackend.GetRange(camera, property);
+        return Math.Max(1, (int)Math.Round((range.max - range.min) * (tolerance / 100.0)));
+    }
+
     static int AddRawDelta(string camera, UvcCameraProperty property, int delta)
     {
         var range = CameraBackend.GetRange(camera, property);
@@ -1187,6 +1245,19 @@ sealed class MoveAbsoluteOptions : MoveOptions
     {
     }
 
+    [Verb("move-seek", HelpText = "Experimentally seek absolute pan and/or tilt values using relative movement.")]
+    sealed class MoveSeekOptions : MoveOptions
+    {
+        [Option("tolerance", Default = 2, HelpText = "Allowed target distance in the selected mode.")]
+        public int Tolerance { get; set; }
+
+        [Option("max-iterations", Default = 30, HelpText = "Maximum relative correction attempts.")]
+        public int MaxIterations { get; set; }
+
+        [Option("settle-ms", Default = 250, HelpText = "Delay after each relative movement attempt.")]
+        public int SettleMilliseconds { get; set; }
+    }
+
     [Verb("move-relative", HelpText = "Change pan and/or tilt by relative deltas.")]
     sealed class MoveRelativeOptions : MoveOptions
     {

docs/generated/cli-help.md

@@ -25,6 +25,8 @@ PTZControlConsole 1.0.0.0
   zoom-absolute        Set an absolute zoom value.
   zoom-relative        Change zoom by a relative delta.
   move-absolute        Set absolute pan and/or tilt values.
+  move-seek            Experimentally seek absolute pan and/or tilt values using
+                       relative movement.
   move-relative        Change pan and/or tilt by relative deltas.
   help                 Display more information on a specific command.
   version              Display version information.
@@ -336,6 +338,37 @@ PTZControlConsole 1.0.0.0
 
 ```
 
+## move-seek
+
+```text
+PTZControlConsole 1.0.0.0
+
+  --tolerance          (Default: 2) Allowed target distance in the selected
+                       mode.
+
+  --max-iterations     (Default: 30) Maximum relative correction attempts.
+
+  --settle-ms          (Default: 250) Delay after each relative movement
+                       attempt.
+
+  -x, --pan            Pan axis value.
+
+  -y, --tilt           Tilt axis value.
+
+  -m, --mode           Required. Value mode: percent or raw.
+
+  -c, --camera         Camera device name fragment.
+
+  -d, --device-path    Concrete camera device path.
+
+  -s, --slot           PTZControl camera slot 1..3.
+
+  --help               Display this help screen.
+
+  --version            Display version information.
+
+```
+
 ## move-relative
 
 ```text

docs/syntax.md

@@ -119,10 +119,14 @@ uses device/driver raw values.
 
 ```text
 PTZControlConsole move-absolute -m|--mode percent|raw [-x|--pan VALUE] [-y|--tilt VALUE] [-c|--camera "NamePart" | -d|--device-path "DevicePath" | -s|--slot 1..3]
+PTZControlConsole move-seek -m|--mode percent|raw [-x|--pan VALUE] [-y|--tilt VALUE] [--tolerance VALUE] [--max-iterations COUNT] [--settle-ms MS] [-c|--camera "NamePart" | -d|--device-path "DevicePath" | -s|--slot 1..3]
 PTZControlConsole move-relative -m|--mode percent|raw [-x|--pan VALUE_DELTA] [-y|--tilt VALUE_DELTA] [-c|--camera "NamePart" | -d|--device-path "DevicePath" | -s|--slot 1..3]
 ```
 
 `-x`/`--pan` controls pan. `-y`/`--tilt` controls tilt.
+`move-seek` is experimental. It reads the current raw pan/tilt values, moves
+relatively toward the target, and re-checks progress until the target is reached
+or the iteration limit is hit.
 
 ## Selection options
 

scripts/test-console-camera-linux.sh

@@ -240,6 +240,8 @@ run_preparation_command "Move pan away from absolute percent position 40" move-a
 run_camera_command "Move pan axis to absolute percent position 40" true move-absolute --mode percent --pan 40 "${selector[@]}"
 run_preparation_command "Move tilt away from absolute percent position 60" move-absolute --mode percent --tilt 40 "${selector[@]}"
 run_camera_command "Move tilt axis to absolute percent position 60" true move-absolute --mode percent --tilt 60 "${selector[@]}"
+run_preparation_command "Move pan and tilt away from seek percent target 50/50" move-absolute --mode percent --pan 0 --tilt 0 "${selector[@]}"
+run_camera_command "Seek pan and tilt to absolute percent position 50/50 using relative movement" true move-seek --mode percent --pan 50 --tilt 50 --tolerance 5 --max-iterations 40 --settle-ms 250 "${selector[@]}"
 run_preparation_command "Move pan before relative percent +10" move-absolute --mode percent --pan 40 "${selector[@]}"
 run_camera_command "Change pan axis by relative percent value +10" true move-relative --mode percent --pan 10 "${selector[@]}"
 run_preparation_command "Move pan before relative percent -10" move-absolute --mode percent --pan 60 "${selector[@]}"
@@ -258,6 +260,8 @@ run_preparation_command "Move tilt away from absolute raw +$RAW_MOVE_ABSOLUTE" m
 run_camera_command "Move tilt axis to absolute raw position +$RAW_MOVE_ABSOLUTE" true move-absolute --mode raw --tilt "$RAW_MOVE_ABSOLUTE" "${selector[@]}"
 run_preparation_command "Move tilt away from absolute raw -$RAW_MOVE_ABSOLUTE" move-absolute --mode raw --tilt 0 "${selector[@]}"
 run_camera_command "Move tilt axis to absolute raw position -$RAW_MOVE_ABSOLUTE" true move-absolute --mode raw --tilt "-$RAW_MOVE_ABSOLUTE" "${selector[@]}"
+run_preparation_command "Move pan and tilt away from seek raw target 0/0" move-absolute --mode raw --pan "$RAW_MOVE_ABSOLUTE" --tilt "$RAW_MOVE_ABSOLUTE" "${selector[@]}"
+run_camera_command "Seek pan and tilt to absolute raw position 0/0 using relative movement" true move-seek --mode raw --pan 0 --tilt 0 --tolerance "$RAW_MOVE_DELTA" --max-iterations 40 --settle-ms 250 "${selector[@]}"
 run_preparation_command "Move pan before relative raw +$RAW_MOVE_DELTA" move-absolute --mode raw --pan 0 "${selector[@]}"
 run_camera_command "Change pan axis by relative raw value +$RAW_MOVE_DELTA" true move-relative --mode raw --pan "$RAW_MOVE_DELTA" "${selector[@]}"
 run_preparation_command "Move pan before relative raw -$RAW_MOVE_DELTA" move-absolute --mode raw --pan 0 "${selector[@]}"

scripts/test-console-camera-windows.ps1

@@ -199,6 +199,8 @@ Invoke-PreparationCommand "Move pan away from absolute percent position 40" (@("
 Invoke-CameraCommand "Move pan axis to absolute percent position 40" (@("move-absolute", "--mode", "percent", "--pan", "40") + $selector)
 Invoke-PreparationCommand "Move tilt away from absolute percent position 60" (@("move-absolute", "--mode", "percent", "--tilt", "40") + $selector)
 Invoke-CameraCommand "Move tilt axis to absolute percent position 60" (@("move-absolute", "--mode", "percent", "--tilt", "60") + $selector)
+Invoke-PreparationCommand "Move pan and tilt away from seek percent target 50/50" (@("move-absolute", "--mode", "percent", "--pan", "0", "--tilt", "0") + $selector)
+Invoke-CameraCommand "Seek pan and tilt to absolute percent position 50/50 using relative movement" (@("move-seek", "--mode", "percent", "--pan", "50", "--tilt", "50", "--tolerance", "5", "--max-iterations", "40", "--settle-ms", "250") + $selector)
 Invoke-PreparationCommand "Move pan before relative percent +10" (@("move-absolute", "--mode", "percent", "--pan", "40") + $selector)
 Invoke-CameraCommand "Change pan axis by relative percent value +10" (@("move-relative", "--mode", "percent", "--pan", "10") + $selector)
 Invoke-PreparationCommand "Move pan before relative percent -10" (@("move-absolute", "--mode", "percent", "--pan", "60") + $selector)
@@ -217,6 +219,8 @@ Invoke-PreparationCommand "Move tilt away from absolute raw +$RawMoveAbsolute" (
 Invoke-CameraCommand "Move tilt axis to absolute raw position +$RawMoveAbsolute" (@("move-absolute", "--mode", "raw", "--tilt", "$RawMoveAbsolute") + $selector)
 Invoke-PreparationCommand "Move tilt away from absolute raw -$RawMoveAbsolute" (@("move-absolute", "--mode", "raw", "--tilt", "0") + $selector)
 Invoke-CameraCommand "Move tilt axis to absolute raw position -$RawMoveAbsolute" (@("move-absolute", "--mode", "raw", "--tilt", "$(-1 * $RawMoveAbsolute)") + $selector)
+Invoke-PreparationCommand "Move pan and tilt away from seek raw target 0/0" (@("move-absolute", "--mode", "raw", "--pan", "$RawMoveAbsolute", "--tilt", "$RawMoveAbsolute") + $selector)
+Invoke-CameraCommand "Seek pan and tilt to absolute raw position 0/0 using relative movement" (@("move-seek", "--mode", "raw", "--pan", "0", "--tilt", "0", "--tolerance", "$RawMoveDelta", "--max-iterations", "40", "--settle-ms", "250") + $selector)
 Invoke-PreparationCommand "Move pan before relative raw +$RawMoveDelta" (@("move-absolute", "--mode", "raw", "--pan", "0") + $selector)
 Invoke-CameraCommand "Change pan axis by relative raw value +$RawMoveDelta" (@("move-relative", "--mode", "raw", "--pan", "$RawMoveDelta") + $selector)
 Invoke-PreparationCommand "Move pan before relative raw -$RawMoveDelta" (@("move-absolute", "--mode", "raw", "--pan", "0") + $selector)