Adjust camera docs to provide clarity on how to handle aspect ratios (#1037)

* Adjust camera docs to provide clarity on how to handle aspect ratios

- When working on home-assistant/frontend#9690 with `bramkragten`, we discovered
  we need a minimum width and height to ensure the frontend images remain crisp and
  the docs were not clear on what do to when aspect ratios were not the same.

* Update docs/core/entity/camera.md

Co-authored-by: Paulus Schoutsen <balloob@gmail.com>
This commit is contained in:
J. Nick Koston 2021-08-23 12:36:26 -05:00 committed by GitHub
parent 8e5612b66b
commit d59c974151
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -26,9 +26,11 @@ Properties should always only return information from memory and not do I/O (lik
When the width and height are passed, scaling should be done on a best-effort basis. The UI will fall back to scaling at the display layer if scaling cannot be done by the camera.
- Integrations should pass on the width and height if the underlying camera is capable of scaling the image.
- Return the smallest image that meets the minimum width and minimum height.
- Integrations may choose to ignore the height parameter to preserve the aspect ratio.
- When scaling the image, aspect ratio must be preserved. If the aspect ratio is not the same as the requsted height or width, it is expected that the width and/or height of the returned image will be larger than requested.
- Pass on the width and height if the underlying camera is capable of scaling the image.
- If the integration cannot scale the image and returns a jpeg image, it will automatically be scaled by the camera integration when requested.