Merge pull request #1448 from dermotduffy/predefined-zoom

Add support for pre-defined zoom/pan settings per camera
2024-04-27 20:23:42 -07:00
parent f96a1229be 63797ea35b
commit dc9ea6d93f
63 changed files with 2054 additions and 638 deletions
@@ -1,3 +1,5 @@
+!> This documentation is for the unreleased `dev` branch! See the [Github README](https://github.com/dermotduffy/frigate-hass-card?tab=readme-ov-file#frigate-lovelace-card) for documentation of the released version.
+
 # Getting Started

 ## Installation
@@ -1,8 +1,8 @@
 ![logo](images/frigate-logo.svg)

-# Frigate Card <small>6.0.0 *DEV*</small>
+# Frigate Card <small>6.0.0 <small style="color: red">_*DEV*_</small></small>

 > A comprehensive camera card for Home Assistant.

 [GitHub](https://github.com/dermotduffy/frigate-hass-card/)
-[Documentation](README.md)
+[Documentation](README.md)
@@ -118,15 +118,28 @@ frigate_card_action: camera_ui

 Open the UI for the selected camera engine (e.g. the Frigate UI).

-### `default`
+### `change_zoom`

-Change to the default view.
+Zoom in and/or pan for a given camera.

 ```yaml
 action: custom:frigate-card-action
-frigate_card_action: default
+frigate_card_action: change_zoom
+[...]
 ```

+| Parameter | Description |
+| - | - |
+| `action` | Must be `custom:frigate-card-action`. |
+| `frigate_card_action` | Must be `change_zoom`. |
+| `target_id` | The [camera ID](cameras/README.md?id=cameras) or a media ID (e.g. `frigate` event ID) to change zoom/pam settings for. |
+| `zoom` | Optional parameter that controls how much to zoom-in. See the [camera zoom parameter](cameras/README.md?id=layout-configuration). |
+| `pan` | Optional parameter that controls how much to pan-x/y. See the [camera pan parameter](cameras/README.md?id=layout-configuration). |
+
+?> If neither `zoom` nor `pan` are specified the camera will return to its default zoom and pan settings.
+
+See [example of automatically zoom/panning based on state](../examples.md?id=automatically-zoom-based-on-state).
+
 ### `clip`, `clips`, `image`, `live`, `recording`, `recordings`, `snapshot`, `snapshots`

 Change to the specified view.
@@ -136,6 +149,15 @@ action: custom:frigate-card-action
 frigate_card_action: [view]
 ```

+### `default`
+
+Change to the default view.
+
+```yaml
+action: custom:frigate-card-action
+frigate_card_action: default
+```
+
 ### `download`

 Download the displayed media.
@@ -518,4 +540,14 @@ elements:
      frigate_card_action: ptz
      ptz_action: preset
      ptz_preset: doorway
+  - type: custom:frigate-card-menu-icon
+    icon: mdi:alpha-r-circle
+    title: Change Zoom
+    tap_action:
+      action: custom:frigate-card-action
+      frigate_card_action: change_zoom
+      pan:
+        x: 50
+        y: 50
+      zoom: 1
 ```
@@ -144,10 +144,12 @@ cameras:
 | Option | Default | Description |
 | - | - | - |
 | `fit` | `contain` | If `contain`, the media is contained within the card and letterboxed if necessary. If `cover`, the media is expanded proportionally (i.e. maintaining the media aspect ratio) until the camera/card dimensions are fully covered. If `fill`, the media is stretched to fill the camera/card dimensions (i.e. ignoring the media aspect ratio). See [CSS object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) for technical details and a visualization. |
+| `pan` | | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when "digitally zoomed in" (see `zoom` parameter). This can be effectively used to "pan"/cut the media shown. A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See visualizations below. |
 | `position` | | A dictionary that may contain an `x` and `y` percentage (`0` - `100`) to control the position of the media when the fit is `cover` (for other values of `fit` this option has no effect). This can be effectively used to "pan"/cut the media shown. At any given time, only one of `x` and `y` will have an effect, depending on whether media width is larger than the camera/card dimensions (in which case `x` controls the position) or the media height is larger than the camera/card dimensions (in which case `y` controls the position). A value of `0` means maximally to the left or top of the media, a value of `100` means maximally to the right or bottom of the media. See [CSS object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) for technicals. See visualizations below. |
-| `view_box` | | A dictionary that may contain a `top`, `bottom`, `left` and `right` percentage (`0` - `100`) to precisely crop what part of the media to show by specifying a % inset value from each side. Browsers apply this cropping after `position` and `fit` have been applied. See visualizations below. |
+| `view_box` | | A dictionary that may contain a `top`, `bottom`, `left` and `right` percentage (`0` - `100`) to precisely crop what part of the media to show by specifying a % inset value from each side. Browsers apply this cropping after `position` and `fit` have been applied. Unlike `zoom`, the user cannot dynamically zoom back out -- however the builtin media controls will work as normal. See visualizations below. Limited [browser support](https://caniuse.com/mdn-css_properties_object-view-box): ![](../../images/browsers/chrome_16x16.png "Google Chrome :no-zoom") ![](../../images/browsers/chromium_16x16.png "Chromium :no-zoom") ![](../../images/browsers/edge_16x16.png "Microsoft Edge :no-zoom") |
+| `zoom` | `1.0` | A value between `1.0` and `10.0` inclusive that defines how much additional "digital zoom" to apply to this camera by default. Unlike with `view_box` the user can easily "zoom back out". Often used in conjuction with `pan`. When zoomed in the [builtin browser media controls](../live.md?id=controls) will automatically be disabled (as otherwise they would be enlarged also). |

-!> The `view_box` parameter only has effect on browsers that support [`object-view-box`](https://caniuse.com/mdn-css_properties_object-view-box). As of writing this is exclusively Chromium based browsers (e.g. Google Chrome or Microsoft Edge).
+?> Layout operations are effectively applied in this order: `fit`, `position`, `view_box`, `zoom` then `pan`.

 See [media layout examples](../../examples.md?id=media-layout).

@@ -169,6 +171,11 @@ See [media layout examples](../../examples.md?id=media-layout).

 ![](../../images/media_layout/view-box.png "Media Layout Position: Taller than wider :size=400")

+#### `pan` and `zoom`: Predefined panning and zooming
+
+![](../../images/media_layout/pan-zoom.png "Panning and zooming :size=400")
+
+
 ## `triggers`

 The `triggers` block configures what triggers a camera. Triggering can be used
@@ -300,6 +307,13 @@ cameras:
      movies:
        directory_pattern: '%Y-%m-%d'
        file_pattern: '%H-%M-%S'
+  - camera_entity: camera.zoomed
+    dimensions:
+      layout:
+        zoom: 2.0
+        pan:
+          x: 50
+          y: 50
 cameras_global:
  live_provider: ha
 ```
@@ -164,6 +164,11 @@ conditions:
 | `condition` | Must be `view`. |
 | `views` | A list of [views](view.md?id=supported-views) in which this condition is satified (e.g. `clips`). |

+?> Internally, views associated with the media viewer (e.g. `clip`, `snapshot`,
+`recording`) are translated to a special view called `media` after the relevant
+media is fetched. When including views as part of a [condition](conditions.md),
+you may need to refer to this special `media` view.
+
 # Fully expanded reference

 [](common/expanded-warning.md ':include')
@@ -33,6 +33,7 @@ menu:
 | `camera_ui` | The `camera_ui` menu button: brings the user to a context-appropriate page on the UI of their camera engine (e.g. the Frigate camera homepage). Will only appear if the camera engine supports a camera UI (e.g. if `frigate.url` option is set for `frigate` engine users).|
 | `cameras` | The camera selection submenu. Will only appear if multiple cameras are configured. |
 | `clips` | The `clips` view menu button: brings the user to the `clips` view on tap and the most-recent `clip` view on hold. |
+| `default_zoom` | The `default_zoom` button allows easily returning the camera to default pan/zoom. |
 | `display_mode` | The `display_mode` button allows changing between single and grid views. |
 | `download` | The `download` menu button: allow direct download of the media being displayed.|
 | `expand` | The `expand` menu button: expand the card into a popup/dialog. |
@@ -53,7 +54,7 @@ menu:
 | Option | Default | Description |
 | - | - | - |
 | `alignment` | `matching` | Whether this button should have an alignment that is `matching` the menu alignment or `opposing` the menu. Can be used to create two separate groups of buttons on the menu. `priority` orders buttons within a given `alignment`. |
-| `enabled` | `true` for `frigate`, `cameras`, `substreams`, `live`, `clips`, `snapshots`, `timeline`, `download`, `camera_ui`, `fullscreen`, `media_player`, `display_mode`. `false` for `image`, `expand`, `microphone`, `mute`, `play`, `recordings`, `screenshot`, `ptz` | Whether or not to show the button. |
+| `enabled` | `true` for `frigate`, `cameras`, `substreams`, `live`, `clips`, `snapshots`, `timeline`, `download`, `camera_ui`, `fullscreen`, `media_player`, `display_mode` and `default_zoom`. `false` for `image`, `expand`, `microphone`, `mute`, `play`, `recordings`, `screenshot`, `ptz` | Whether or not to show the button. |
 | `icon` | | An icon to overriding the default for that button, e.g. `mdi:camera-front`. |
 | `priority` | `50` | The button priority. Higher priority buttons are ordered closer to the start of the menu alignment (i.e. a button with priority `70` will order further to the left than a button with priority `60`, when the menu alignment is `left`). Minimum `0`, maximum `100`.|

@@ -90,9 +91,15 @@ menu:
      enabled: true
      alignment: matching
      icon: mdi:video-switch
+    default_zoom:
+      priority: 50
+      enabled: true
+      alignment: matching
+      icon: mdi:magnify-close
    substreams:
      priority: 50
      enabled: true
+      alignment: matching
      icon: mdi:video-input-component
    live:
      priority: 50
@@ -997,3 +997,95 @@ cameras:
    webrtc_card:
      ui: true
 ```
+
+## Zoom
+
+### Pre-defining camera zoom and pan
+
+This example changes the default [zoom/pan settings for a camera](./configuration/cameras/README.md?id=layout-configuration) to always zoom in on a given area:
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+    dimensions:
+      layout:
+        zoom: 3
+        pan:
+          x: 20
+          y: 80
+```
+
+### Disable zooming in media views
+
+This example prevents zooming on the media viewer but keeps it on in other views (e.g. `live` view):
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+    dimensions:
+      layout:
+        zoom: 3
+        pan:
+          x: 20
+          y: 80
+media_viewer:
+  zoomable: false
+```
+
+### Different zoom settings in media viewer vs `live`
+
+This example uses different settings for the media viewer and `live` view, by overriding the camera configuration:
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.office
+    dimensions:
+      layout:
+        zoom: 2
+overrides:
+  - conditions:
+      - condition: view
+        views:
+          - media
+    set:
+      'cameras[0].dimensions.layout':
+        zoom: 3
+        pan:
+          x: 100
+          y: 100
+```
+
+### Automatically zoom based on state
+
+This example automatically zooms in and out based on the state of an entity:
+
+```yaml
+type: custom:frigate-card
+cameras:
+  - camera_entity: camera.living_room
+    live_provider: go2rtc
+debug:
+  logging: true
+automations:
+  - conditions:
+      - condition: state
+        entity: binary_sensor.door_contact
+        state: 'on'
+    actions:
+      - action: custom:frigate-card-action
+        frigate_card_action: change_zoom
+        target_id: camera.living_room
+        zoom: 4
+        pan:
+          x: 38
+          y: 20
+    actions_not:
+      - action: custom:frigate-card-action
+        frigate_card_action: change_zoom
+        target_id: camera.living_room
+```
+
+![](images/zoom-automation.gif 'Zoom automation example :size=400')