407 lines
15 KiB
YAML
407 lines
15 KiB
YAML
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
|
||
%YAML 1.2
|
||
---
|
||
$id: http://devicetree.org/schemas/media/video-interface-devices.yaml#
|
||
$schema: http://devicetree.org/meta-schemas/core.yaml#
|
||
|
||
title: Common bindings for video receiver and transmitter devices
|
||
|
||
maintainers:
|
||
- Jacopo Mondi <jacopo@jmondi.org>
|
||
- Sakari Ailus <sakari.ailus@linux.intel.com>
|
||
|
||
properties:
|
||
flash-leds:
|
||
$ref: /schemas/types.yaml#/definitions/phandle-array
|
||
description:
|
||
An array of phandles, each referring to a flash LED, a sub-node of the LED
|
||
driver device node.
|
||
|
||
lens-focus:
|
||
$ref: /schemas/types.yaml#/definitions/phandle
|
||
description:
|
||
A phandle to the node of the focus lens controller.
|
||
|
||
rotation:
|
||
$ref: /schemas/types.yaml#/definitions/uint32
|
||
enum: [ 0, 90, 180, 270 ]
|
||
description: |
|
||
The camera rotation is expressed as the angular difference in degrees
|
||
between two reference systems, one relative to the camera module, and one
|
||
defined on the external world scene to be captured when projected on the
|
||
image sensor pixel array.
|
||
|
||
A camera sensor has a 2-dimensional reference system 'Rc' defined by its
|
||
pixel array read-out order. The origin is set to the first pixel being
|
||
read out, the X-axis points along the column read-out direction towards
|
||
the last columns, and the Y-axis along the row read-out direction towards
|
||
the last row.
|
||
|
||
A typical example for a sensor with a 2592x1944 pixel array matrix
|
||
observed from the front is:
|
||
|
||
2591 X-axis 0
|
||
<------------------------+ 0
|
||
.......... ... ..........!
|
||
.......... ... ..........! Y-axis
|
||
... !
|
||
.......... ... ..........!
|
||
.......... ... ..........! 1943
|
||
V
|
||
|
||
The external world scene reference system 'Rs' is a 2-dimensional
|
||
reference system on the focal plane of the camera module. The origin is
|
||
placed on the top-left corner of the visible scene, the X-axis points
|
||
towards the right, and the Y-axis points towards the bottom of the scene.
|
||
The top, bottom, left and right directions are intentionally not defined
|
||
and depend on the environment in which the camera is used.
|
||
|
||
A typical example of a (very common) picture of a shark swimming from left
|
||
to right, as seen from the camera, is:
|
||
|
||
0 X-axis
|
||
0 +------------------------------------->
|
||
!
|
||
!
|
||
!
|
||
! |\____)\___
|
||
! ) _____ __`<
|
||
! |/ )/
|
||
!
|
||
!
|
||
!
|
||
V
|
||
Y-axis
|
||
|
||
with the reference system 'Rs' placed on the camera focal plane:
|
||
|
||
¸.·˙!
|
||
¸.·˙ !
|
||
_ ¸.·˙ !
|
||
+-/ \-+¸.·˙ !
|
||
| (o) | ! Camera focal plane
|
||
+-----+˙·.¸ !
|
||
˙·.¸ !
|
||
˙·.¸ !
|
||
˙·.¸!
|
||
|
||
When projected on the sensor's pixel array, the image and the associated
|
||
reference system 'Rs' are typically (but not always) inverted, due to the
|
||
camera module's lens optical inversion effect.
|
||
|
||
Assuming the above represented scene of the swimming shark, the lens
|
||
inversion projects the scene and its reference system onto the sensor
|
||
pixel array, seen from the front of the camera sensor, as follows:
|
||
|
||
Y-axis
|
||
^
|
||
!
|
||
!
|
||
!
|
||
! |\_____)\__
|
||
! ) ____ ___.<
|
||
! |/ )/
|
||
!
|
||
!
|
||
!
|
||
0 +------------------------------------->
|
||
0 X-axis
|
||
|
||
Note the shark being upside-down.
|
||
|
||
The resulting projected reference system is named 'Rp'.
|
||
|
||
The camera rotation property is then defined as the angular difference in
|
||
the counter-clockwise direction between the camera reference system 'Rc'
|
||
and the projected scene reference system 'Rp'. It is expressed in degrees
|
||
as a number in the range [0, 360[.
|
||
|
||
Examples
|
||
|
||
0 degrees camera rotation:
|
||
|
||
|
||
Y-Rp
|
||
^
|
||
Y-Rc !
|
||
^ !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! 0 +------------------------------------->
|
||
! 0 X-Rp
|
||
0 +------------------------------------->
|
||
0 X-Rc
|
||
|
||
|
||
X-Rc 0
|
||
<------------------------------------+ 0
|
||
X-Rp 0 !
|
||
<------------------------------------+ 0 !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! V
|
||
! Y-Rc
|
||
V
|
||
Y-Rp
|
||
|
||
90 degrees camera rotation:
|
||
|
||
0 Y-Rc
|
||
0 +-------------------->
|
||
! Y-Rp
|
||
! ^
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! 0 +------------------------------------->
|
||
! 0 X-Rp
|
||
!
|
||
!
|
||
!
|
||
!
|
||
V
|
||
X-Rc
|
||
|
||
180 degrees camera rotation:
|
||
|
||
0
|
||
<------------------------------------+ 0
|
||
X-Rc !
|
||
Y-Rp !
|
||
^ !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! V
|
||
! Y-Rc
|
||
0 +------------------------------------->
|
||
0 X-Rp
|
||
|
||
270 degrees camera rotation:
|
||
|
||
0 Y-Rc
|
||
0 +-------------------->
|
||
! 0
|
||
! <-----------------------------------+ 0
|
||
! X-Rp !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! !
|
||
! V
|
||
! Y-Rp
|
||
!
|
||
!
|
||
!
|
||
!
|
||
V
|
||
X-Rc
|
||
|
||
|
||
Example one - Webcam
|
||
|
||
A camera module installed on the user facing part of a laptop screen
|
||
casing used for video calls. The captured images are meant to be displayed
|
||
in landscape mode (width > height) on the laptop screen.
|
||
|
||
The camera is typically mounted upside-down to compensate the lens optical
|
||
inversion effect:
|
||
|
||
Y-Rp
|
||
Y-Rc ^
|
||
^ !
|
||
! !
|
||
! ! |\_____)\__
|
||
! ! ) ____ ___.<
|
||
! ! |/ )/
|
||
! !
|
||
! !
|
||
! !
|
||
! 0 +------------------------------------->
|
||
! 0 X-Rp
|
||
0 +------------------------------------->
|
||
0 X-Rc
|
||
|
||
The two reference systems are aligned, the resulting camera rotation is
|
||
0 degrees, no rotation correction needs to be applied to the resulting
|
||
image once captured to memory buffers to correctly display it to users:
|
||
|
||
+--------------------------------------+
|
||
! !
|
||
! !
|
||
! !
|
||
! |\____)\___ !
|
||
! ) _____ __`< !
|
||
! |/ )/ !
|
||
! !
|
||
! !
|
||
! !
|
||
+--------------------------------------+
|
||
|
||
If the camera sensor is not mounted upside-down to compensate for the lens
|
||
optical inversion, the two reference systems will not be aligned, with
|
||
'Rp' being rotated 180 degrees relatively to 'Rc':
|
||
|
||
|
||
X-Rc 0
|
||
<------------------------------------+ 0
|
||
!
|
||
Y-Rp !
|
||
^ !
|
||
! !
|
||
! |\_____)\__ !
|
||
! ) ____ ___.< !
|
||
! |/ )/ !
|
||
! !
|
||
! !
|
||
! V
|
||
! Y-Rc
|
||
0 +------------------------------------->
|
||
0 X-Rp
|
||
|
||
The image once captured to memory will then be rotated by 180 degrees:
|
||
|
||
+--------------------------------------+
|
||
! !
|
||
! !
|
||
! !
|
||
! __/(_____/| !
|
||
! >.___ ____ ( !
|
||
! \( \| !
|
||
! !
|
||
! !
|
||
! !
|
||
+--------------------------------------+
|
||
|
||
A software rotation correction of 180 degrees should be applied to
|
||
correctly display the image:
|
||
|
||
+--------------------------------------+
|
||
! !
|
||
! !
|
||
! !
|
||
! |\____)\___ !
|
||
! ) _____ __`< !
|
||
! |/ )/ !
|
||
! !
|
||
! !
|
||
! !
|
||
+--------------------------------------+
|
||
|
||
Example two - Phone camera
|
||
|
||
A camera installed on the back side of a mobile device facing away from
|
||
the user. The captured images are meant to be displayed in portrait mode
|
||
(height > width) to match the device screen orientation and the device
|
||
usage orientation used when taking the picture.
|
||
|
||
The camera sensor is typically mounted with its pixel array longer side
|
||
aligned to the device longer side, upside-down mounted to compensate for
|
||
the lens optical inversion effect:
|
||
|
||
0 Y-Rc
|
||
0 +-------------------->
|
||
! Y-Rp
|
||
! ^
|
||
! !
|
||
! !
|
||
! !
|
||
! ! |\_____)\__
|
||
! ! ) ____ ___.<
|
||
! ! |/ )/
|
||
! !
|
||
! !
|
||
! !
|
||
! 0 +------------------------------------->
|
||
! 0 X-Rp
|
||
!
|
||
!
|
||
!
|
||
!
|
||
V
|
||
X-Rc
|
||
|
||
The two reference systems are not aligned and the 'Rp' reference system is
|
||
rotated by 90 degrees in the counter-clockwise direction relatively to the
|
||
'Rc' reference system.
|
||
|
||
The image once captured to memory will be rotated:
|
||
|
||
+-------------------------------------+
|
||
| _ _ |
|
||
| \ / |
|
||
| | | |
|
||
| | | |
|
||
| | > |
|
||
| < | |
|
||
| | | |
|
||
| . |
|
||
| V |
|
||
+-------------------------------------+
|
||
|
||
A correction of 90 degrees in counter-clockwise direction has to be
|
||
applied to correctly display the image in portrait mode on the device
|
||
screen:
|
||
|
||
+--------------------+
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| |\____)\___ |
|
||
| ) _____ __`< |
|
||
| |/ )/ |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
| |
|
||
+--------------------+
|
||
|
||
orientation:
|
||
description:
|
||
The orientation of a device (typically an image sensor or a flash LED)
|
||
describing its mounting position relative to the usage orientation of the
|
||
system where the device is installed on.
|
||
$ref: /schemas/types.yaml#/definitions/uint32
|
||
enum:
|
||
# Front. The device is mounted on the front facing side of the system. For
|
||
# mobile devices such as smartphones, tablets and laptops the front side
|
||
# is the user facing side.
|
||
- 0
|
||
# Back. The device is mounted on the back side of the system, which is
|
||
# defined as the opposite side of the front facing one.
|
||
- 1
|
||
# External. The device is not attached directly to the system but is
|
||
# attached in a way that allows it to move freely.
|
||
- 2
|
||
|
||
additionalProperties: true
|
||
|
||
...
|