| # 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 Properties 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. | |
| leds: | |
| minItems: 1 | |
| maxItems: 1 | |
| led-names: | |
| enum: | |
| - privacy | |
| 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 | |
| ... |