* [PATCH v10 01/13] dt-bindings: video-interfaces: Document 'orientation' property
[not found] <20200508100158.3437161-1-jacopo@jmondi.org>
@ 2020-05-08 10:01 ` Jacopo Mondi
2020-05-11 17:20 ` Rob Herring
2020-05-08 10:01 ` [PATCH v10 02/13] dt-bindings: video-interface: Replace 'rotation' description Jacopo Mondi
2020-05-08 10:01 ` [PATCH v10 03/13] dt-bindings: Add media properties Jacopo Mondi
2 siblings, 1 reply; 8+ messages in thread
From: Jacopo Mondi @ 2020-05-08 10:01 UTC (permalink / raw)
To: open list:MEDIA INPUT INFRASTRUCTURE (V4L/DVB), libcamera-devel,
Mauro Carvalho Chehab, Hans Verkuil, Sakari Ailus,
Laurent Pinchart, Rob Herring
Cc: Jacopo Mondi, tfiga, pavel, devicetree
Add the 'orientation' device property, used to specify the device mounting
position. The property is particularly meaningful for mobile devices
with a well defined usage orientation.
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
.../devicetree/bindings/media/video-interfaces.txt | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
index f884ada0bffc8..b1ff492c7da7a 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.txt
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -89,6 +89,17 @@ Optional properties
but a number of degrees counter clockwise. Typical values are 0 and 180
(upside down).
+- orientation: 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.
+ Possible values are:
+ 0 - 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.
+ 1 - Back. The device is mounted on the back side of the system, which is
+ defined as the opposite side of the front facing one.
+ 2 - External. The device is not attached directly to the system but is
+ attached in a way that allows it to move freely.
Optional endpoint properties
----------------------------
--
2.26.1
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v10 02/13] dt-bindings: video-interface: Replace 'rotation' description
[not found] <20200508100158.3437161-1-jacopo@jmondi.org>
2020-05-08 10:01 ` [PATCH v10 01/13] dt-bindings: video-interfaces: Document 'orientation' property Jacopo Mondi
@ 2020-05-08 10:01 ` Jacopo Mondi
2020-05-08 10:01 ` [PATCH v10 03/13] dt-bindings: Add media properties Jacopo Mondi
2 siblings, 0 replies; 8+ messages in thread
From: Jacopo Mondi @ 2020-05-08 10:01 UTC (permalink / raw)
To: open list:MEDIA INPUT INFRASTRUCTURE (V4L/DVB), libcamera-devel,
Mauro Carvalho Chehab, Hans Verkuil, Sakari Ailus,
Laurent Pinchart, Rob Herring
Cc: Jacopo Mondi, tfiga, pavel, devicetree
Replace the 'rotation' property description by providing a definition
relative to the camera sensor pixel array coordinate system and the
captured scene.
Acked-by: Rob Herring <robh@kernel.org>
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
.../bindings/media/video-interfaces.txt | 359 +++++++++++++++++-
1 file changed, 356 insertions(+), 3 deletions(-)
diff --git a/Documentation/devicetree/bindings/media/video-interfaces.txt b/Documentation/devicetree/bindings/media/video-interfaces.txt
index b1ff492c7da7a..3920f25a91235 100644
--- a/Documentation/devicetree/bindings/media/video-interfaces.txt
+++ b/Documentation/devicetree/bindings/media/video-interfaces.txt
@@ -85,9 +85,362 @@ Optional properties
- lens-focus: A phandle to the node of the focus lens controller.
-- rotation: The device, typically an image sensor, is not mounted upright,
- but a number of degrees counter clockwise. Typical values are 0 and 180
- (upside down).
+- rotation: 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: The orientation of a device (typically an image sensor or a flash
LED) describing its mounting position relative to the usage orientation of the
--
2.26.1
^ permalink raw reply related [flat|nested] 8+ messages in thread* [PATCH v10 03/13] dt-bindings: Add media properties
[not found] <20200508100158.3437161-1-jacopo@jmondi.org>
2020-05-08 10:01 ` [PATCH v10 01/13] dt-bindings: video-interfaces: Document 'orientation' property Jacopo Mondi
2020-05-08 10:01 ` [PATCH v10 02/13] dt-bindings: video-interface: Replace 'rotation' description Jacopo Mondi
@ 2020-05-08 10:01 ` Jacopo Mondi
2020-05-08 11:04 ` Hans Verkuil
2 siblings, 1 reply; 8+ messages in thread
From: Jacopo Mondi @ 2020-05-08 10:01 UTC (permalink / raw)
To: open list:MEDIA INPUT INFRASTRUCTURE (V4L/DVB), libcamera-devel,
Mauro Carvalho Chehab, Hans Verkuil, Sakari Ailus,
Laurent Pinchart, Rob Herring
Cc: Jacopo Mondi, tfiga, pavel, devicetree
Add a DT header file to contain definitions for standard media properties.
The file is named after:
Documentation/devicetree/bindings/media/video-interfaces.txt
which contains the standard media properties definitions.
Initially add three macros to define the supported 'orientation'
property values.
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
include/dt-bindings/media/video-interfaces.h | 15 +++++++++++++++
1 file changed, 15 insertions(+)
create mode 100644 include/dt-bindings/media/video-interfaces.h
diff --git a/include/dt-bindings/media/video-interfaces.h b/include/dt-bindings/media/video-interfaces.h
new file mode 100644
index 0000000000000..404c697d6bd6e
--- /dev/null
+++ b/include/dt-bindings/media/video-interfaces.h
@@ -0,0 +1,15 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * include/dt-bindings/media/video-interfaces.h
+ *
+ * Copyright (C) 2020 Jacopo Mondi <jacopo@jmondi.org>
+ */
+
+#ifndef __DT_BINDINGS_MEDIA_VIDEO_INTERFACES_H__
+#define __DT_BINDINGS_MEDIA_VIDEO_INTERFACES_H__
+
+#define FRONT_CAMERA <0>
+#define BACK_CAMERA <1>
+#define EXTERNAL_CAMERA <2>
+
+#endif /* __DT_BINDINGS_MEDIA_VIDEO_INTERFACES_H__ */
--
2.26.1
^ permalink raw reply related [flat|nested] 8+ messages in thread