Add support for pre-defined zoom/pan settings.

docs/configuration/actions.md

@@ -118,15 +118,24 @@ 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) to adjust the pan/zoom of, or a media ID (e.g. `frigate` event ID) to zoom in on specific media items. |
+| `zoom` | How much to zoom-in. See the [camera zoom parameter](cameras/README.md?id=layout-configuration). |
+| `pan` | How much to pan-x/y. See the [camera pan parameter](cameras/README.md?id=layout-configuration). |
+
 ### `clip`, `clips`, `image`, `live`, `recording`, `recordings`, `snapshot`, `snapshots`
 
 Change to the specified view.
@@ -136,6 +145,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.

docs/configuration/cameras/README.md

@@ -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
 ```

docs/configuration/conditions.md

@@ -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')

docs/configuration/menu.md

@@ -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