docs

docs/docs/configuration/autotracking.md

@@ -107,6 +107,8 @@ Before restarting Frigate, you should set `calibrate_on_startup` in your config
 
 You can recalibrate at any time by removing the `movement_weights` parameter, setting `calibrate_on_startup` to `True`, and then restarting Frigate. You may need to recalibrate or remove `movement_weights` from your config altogether if autotracking is erratic. If you change your `return_preset` in any way or if you change your camera's detect `fps` value, a recalibration is also recommended.
 
+If you initially calibrate with zooming disabled and then enable zooming at a later point, you should also recalibrate.
+
 ## Best practices and considerations
 
 Every PTZ camera is different, so autotracking may not perform ideally in every situation. This experimental feature was initially developed using an EmpireTech/Dahua SD1A404XB-GNR.
@@ -119,7 +121,7 @@ A fast [detector](object_detectors.md) is recommended. CPU detectors will not pe
 
 A full-frame zone in `required_zones` is not recommended, especially if you've calibrated your camera and there are `movement_weights` defined in the configuration file. Frigate will continue to autotrack an object that has entered one of the `required_zones`, even if it moves outside of that zone.
 
-Some users have found it helpful to adjust the zone `inertia` value or the camera's `max_disappeared` parameter as well. See the [configuration reference](index.md).
+Some users have found it helpful to adjust the zone `inertia` value. See the [configuration reference](index.md).
 
 ## Zooming
 
@@ -131,7 +133,7 @@ Relative zooming attempts to make a zoom movement concurrently with any pan/tilt
 
 You can optionally adjust the `zoom_factor` for your camera in your configuration file. Lower values will leave more space from the scene around the tracked object while higher values will cause your camera to zoom in more on the object. However, keep in mind that Frigate needs a fair amount of pixels and scene details outside of the bounding box of the tracked object to estimate the motion of your camera. If the object is taking up too much of the frame, Frigate will not be able to track the motion of the camera and your object will be lost.
 
-The range of this option is from 0.1 to 0.75. The default value of 0.3 should be sufficient for most users. Because every PTZ and scene is different, you should experiment to determine what works best for you.
+The range of this option is from 0.1 to 0.75. The default value of 0.3 is conservative and should be sufficient for most users. Because every PTZ and scene is different, you should experiment to determine what works best for you.
 
 ## Usage applications
 
@@ -157,4 +159,4 @@ This is often caused by the same reason as above - the `MoveStatus` ONVIF parame
 
 ### I'm seeing this error in the logs: "Autotracker: motion estimator couldn't get transformations". What does this mean?
 
-To maintain object tracking during PTZ moves, Frigate tracks the motion of your camera based on the details of the frame. If you are seeing this message, it could mean that your `zoom_factor` may be set too high or the scene around your detected object does not have enough details (like hard edges or color variatons). Try reducing `zoom_factor` or finding a way to alter the scene around your object.
+To maintain object tracking during PTZ moves, Frigate tracks the motion of your camera based on the details of the frame. If you are seeing this message, it could mean that your `zoom_factor` may be set too high, the scene around your detected object does not have enough details (like hard edges or color variatons), or your camera's shutter speed is too slow and motion blur is occurring. Try reducing `zoom_factor`, finding a way to alter the scene around your object, or changing your camera's shutter speed.

frigate/ptz/autotrack.py

@@ -350,33 +350,41 @@ class PtzAutoTracker:
 
                 zoom_in_values.append(self.ptz_metrics[camera]["ptz_zoom_level"].value)
 
-                # relative move to -0.01
+                if (
-                self.onvif._move_relative(
+                    self.config.cameras[camera].onvif.autotracking.zooming
-                    camera,
+                    == ZoomingModeEnum.relative
-                    0,
+                ):
-                    0,
+                    # relative move to -0.01
-                    -1e-2,
+                    self.onvif._move_relative(
-                    1,
+                        camera,
-                )
+                        0,
+                        0,
+                        -1e-2,
+                        1,
+                    )
 
-                while not self.ptz_metrics[camera]["ptz_stopped"].is_set():
+                    while not self.ptz_metrics[camera]["ptz_stopped"].is_set():
-                    self.onvif.get_camera_status(camera)
+                        self.onvif.get_camera_status(camera)
 
-                zoom_out_values.append(self.ptz_metrics[camera]["ptz_zoom_level"].value)
+                    zoom_out_values.append(
+                        self.ptz_metrics[camera]["ptz_zoom_level"].value
+                    )
 
-                # relative move to 0.01
+                    # relative move to 0.01
-                self.onvif._move_relative(
+                    self.onvif._move_relative(
-                    camera,
+                        camera,
-                    0,
+                        0,
-                    0,
+                        0,
-                    1e-2,
+                        1e-2,
-                    1,
+                        1,
-                )
+                    )
 
-                while not self.ptz_metrics[camera]["ptz_stopped"].is_set():
+                    while not self.ptz_metrics[camera]["ptz_stopped"].is_set():
-                    self.onvif.get_camera_status(camera)
+                        self.onvif.get_camera_status(camera)
 
-                zoom_in_values.append(self.ptz_metrics[camera]["ptz_zoom_level"].value)
+                    zoom_in_values.append(
+                        self.ptz_metrics[camera]["ptz_zoom_level"].value
+                    )
 
             self.ptz_metrics[camera]["ptz_max_zoom"].value = max(zoom_in_values)
             self.ptz_metrics[camera]["ptz_min_zoom"].value = min(zoom_out_values)
@@ -986,10 +994,14 @@ class PtzAutoTracker:
                         camera, obj, obj.obj_data["box"], debug_zoom
                     )
                 ) is not None:
+                    level = (
+                        self.ptz_metrics[camera]["ptz_max_zoom"].value
+                        - self.ptz_metrics[camera]["ptz_min_zoom"].value
+                    ) / 10
                     if result:
-                        zoom = min(1.0, current_zoom_level + 0.1)
+                        zoom = min(1.0, current_zoom_level + level)
                     else:
-                        zoom = max(0.0, current_zoom_level - 0.2)
+                        zoom = max(0.0, current_zoom_level - 2 * level)
 
         # relative zooming concurrently with pan/tilt
         if camera_config.onvif.autotracking.zooming == ZoomingModeEnum.relative:
@@ -1032,8 +1044,10 @@ class PtzAutoTracker:
                     )
                     logger.debug(f"{camera}: Zoom calculation: {zoom}")
                     if not result:
-                        zoom = -(1 - abs(zoom)) if zoom > 0 else -(zoom + 1)
+                        # zoom out with special condition if zooming out because of velocity, edges, etc.
+                        zoom = -(1 - zoom) if zoom > 0 else -(zoom + 1)
                     if result:
+                        # zoom in
                         zoom = 1 - zoom
 
         logger.debug(f"{camera}: Zooming: {result} Zoom amount: {zoom}")

frigate/ptz/onvif.py

@@ -201,7 +201,10 @@ class OnvifController:
                     "relative_zoom_range"
                 ] = ptz_config.Spaces.RelativeZoomTranslationSpace[0]
             except Exception:
-                if self.config.cameras[camera_name].onvif.autotracking.zooming:
+                if (
+                    self.config.cameras[camera_name].onvif.autotracking.zooming
+                    == ZoomingModeEnum.relative
+                ):
                     self.config.cameras[camera_name].onvif.autotracking.zooming = False
                     logger.warning(
                         f"Disabling autotracking zooming for {camera_name}: Relative zoom not supported"
@@ -296,7 +299,7 @@ class OnvifController:
         self.cams[camera_name]["active"] = True
         self.ptz_metrics[camera_name]["ptz_stopped"].clear()
         logger.debug(
-            f"{camera_name} PTZ start time: {self.ptz_metrics[camera_name]['ptz_frame_time'].value}"
+            f"{camera_name}: PTZ start time: {self.ptz_metrics[camera_name]['ptz_frame_time'].value}"
         )
         self.ptz_metrics[camera_name]["ptz_start_time"].value = self.ptz_metrics[
             camera_name