[libcamera-devel] [PATCH v5 4/9] libcamera: properties: Add rotation property
Jacopo Mondi
jacopo at jmondi.org
Thu Feb 6 02:25:56 CET 2020
The rotation property describes the rotation of the camera sensor.
Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
---
src/libcamera/property_ids.yaml | 329 ++++++++++++++++++++++++++++++++
1 file changed, 329 insertions(+)
diff --git a/src/libcamera/property_ids.yaml b/src/libcamera/property_ids.yaml
index f384e5205ef6..c3070de9d9f8 100644
--- a/src/libcamera/property_ids.yaml
+++ b/src/libcamera/property_ids.yaml
@@ -25,4 +25,333 @@ controls:
description: |
The camera is attached to the device in a way that allows it to
be moved freely
+
+ - Rotation:
+ type: int32_t
+ description: |
+ The camera rotation is expressed as the angular difference in degrees
+ between two reference systems, one relative to the camera module
+ intrinsics characteristics, and one artificially 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 follow
+
+ 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 counterclockwise 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 !
+ ^ !
+ ! ! Y-Rc
+ ! !
+ ! !
+ ! V
+ !
+ 0 +------------------------------------>
+ 0 X-Rp
+
+ 270 degrees camera rotation
+
+ 0 Y-Rc
+ 0 +----------------------->
+ ! 0
+ ! <-----------------------------------+ 0
+ ! X-Rc !
+ ! !
+ ! !
+ ! !
+ ! !
+ ! 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 !
+ ^ !
+ ! ! Y-Rc
+ ! |\_____)\__ !
+ ! ) ____ ___.< !
+ ! |/ )/ !
+ ! V
+ !
+ 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 counterclockwise direction
+ relatively to the 'Rc' reference system.
+
+ The image once captured to memory will be rotated.
+
+ +-----------------------------------------------------+
+ | _ _ |
+ | \ / |
+ | | | |
+ | | | |
+ | | > |
+ | < | |
+ | | | |
+ | . |
+ | V |
+ +-----------------------------------------------------+
+
+ A correction of 90 degrees in counterclockwise direction has to be
+ applied to correctly display the image in portrait mode on the device
+ screen.
+
+ +---------------+
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |
+ | |\____)\___ |
+ | ) _____ __`< |
+ | |/ )/ |
+ | |
+ | |
+ | |
+ | |
+ | |
+ +---------------+
...
--
2.24.1
More information about the libcamera-devel
mailing list