From: Jacopo Mondi <jacopo@jmondi.org> To: Mauro Carvalho Chehab <mchehab@kernel.org>, Hans Verkuil <hverkuil-cisco@xs4all.nl>, Sakari Ailus <sakari.ailus@linux.intel.com>, Laurent Pinchart <laurent.pinchart@ideasonboard.com>, tfiga@google.com, pavel@ucw.cz Cc: Jacopo Mondi <jacopo@jmondi.org>, linux-media@vger.kernel.org (open list:MEDIA INPUT INFRASTRUCTURE (V4L/DVB)) Subject: [PATCH v3 04/11] media: v4l2-ctrl: Document V4L2_CID_CAMERA_SENSOR_ROTATION Date: Thu, 12 Sep 2019 22:10:48 +0200 Message-ID: <20190912201055.13964-5-jacopo@jmondi.org> (raw) In-Reply-To: <20190912201055.13964-1-jacopo@jmondi.org> Add documentation for the V4L2_CID_CAMERA_SENSOR_ROTATION camera control. The newly added read-only control reports the camera device mounting rotation. Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> --- .../media/uapi/v4l/ext-ctrls-camera.rst | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) diff --git a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst index f879dcc9409c..74991522ca3a 100644 --- a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst +++ b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst @@ -542,6 +542,123 @@ enum v4l2_scene_mode - +``V4L2_CID_CAMERA_SENSOR_ROTATION (integer)`` + This read-only control describes the sensor orientation expressed as + rotation in counterclockwise degrees along the axis perpendicular to the + device mounting plane, and directed away from the sensor lens. Possible + values for the control are 90, 180 and 270 degrees. To compensate the device + mounting rotation on the captured images, a rotation of the same amount of + degrees, in the same counterclockwise rotation direction should be applied + along the axis directed from the observer to the captured image when + displayed on a screen. + + To better understand the effect of the sensor rotation on the acquired + images when displayed on a screen, it is helpful to consider a fictional + scan-out sequence of the sensor's pixels, assuming the pixel array having + its top-left pixel at position (0, 0) with values on the 'x' axis increasing + towards the right direction, and values on the 'y' axis increasing towards + the bottom. The effect of sensor rotation could be easily visualized + considering the sequence of captured pixels. + + Assuming the following scene has to be captured:: + + o + -|- + / \ + + An upright mounted sensor has its pixel array displaced as follow:: + + x + (0,0)----------------------> + ! 0,0 0,1 0,2 ... 0,line-len + ! 1,0 1,1 1,2 ... + ! ... + ! ... + ! (num-col,0)... (num-col,line-len) + y V + + + Assuming pixels are scanned out from (0,0) to (num-col,line-len) + progressively:: + + (0,0) ---->-------------> (0,line-len)---! + !------------------------------------<a--! + V + (1,0) ---->-------------> (1,line-len)---! + !------------------------------------<---! + V + (...) .-->--------------> ( ,,,, ) ---! + !------------------------------------<---! + V + (num-col,0)------------->(num-col,line-len) + + + If a rotation of 90 degrees counterclockwise along the axis perpendicular to + the sensor's lens and directed towards the scene to be captured is applied + to the sensor, the pixel array would then be rotated as follows:: + + x ^ 0,line-len,,,(num-col,line-len + ! .... + ! 0,2 1,2 ... + ! 0,1 1,1 ... + ! 0,0 1,0 ... num-col,0 + (0,0)------------------------> + y + + And the pixel scan-out sequence would then proceed as follows:: + + (0,line-len) (num-cols,line-len) + ^\ ^\ ^\ ^\ ^ + ! \ ! \ ! \ ! \ ! + ! \ ! \ ! \ ! \ ! + ! \ ! \ ! \ ! \ ! + ! \! \! \! \! + (0,0) (1,0) .... (num-cols,0) + + Which when applied to the capture scene gives:: + + (0,line-len) (num-cols,line-len) + ^\ ^\ ^\ ^\ ^ + ! \ ! \ 0 \ ! \ ! + ! \ ! \ -|- \ ! \ ! + ! \ ! / \ \ ! \ ! + ! \! \! \! \! + (0,0) (1,0) .... (num-cols,0) + + Producing the following image once captured to memory and + displayed to the user:: + + \ ! + --0 + / ! + + Which has a rotation of the same amount of degrees applied on the opposite + rotation direction along the axis that goes from the observer to the + displayed image. + + In order to compensate the sensor mounting rotation, when expressed + as counterclockwise rotation along the axis directed from the sensor to + the captured scene, a rotation of the same amount of degrees in the + same counterclockwise rotation direction but applied along the axis + directed from the observer to the captured image, has to be applied.:: + + ------- 90 degree counterclockwise + | o | mounting rotation applied + | -|- | along the axis directed + | / \ | away from the sensor lens + ------- + ------- + | \ ! | Resulting captured + | --0 | image when displayed + | / ! | on screen + ------- + ------- + | o | Rotation compensation + | -|- | is 90 degrees counterclockwise + | / \ | along the axis directed to the + ------- displayed image + + .. [#f1] This control may be changed to a menu control in the future, if more options are required. -- 2.23.0
next prev parent reply index Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-09-12 20:10 [PATCH v3 00/11] media: Report camera sensor properties Jacopo Mondi 2019-09-12 20:10 ` [PATCH v3 01/11] dt-bindings: video-interfaces: Document 'location' property Jacopo Mondi 2019-09-13 13:45 ` Hans Verkuil 2019-09-27 15:27 ` Pavel Machek 2019-09-28 12:48 ` Jacopo Mondi 2019-09-12 20:10 ` [PATCH v3 02/11] media: v4l2-ctrl: Document V4L2_CID_CAMERA_SENSOR_LOCATION Jacopo Mondi 2019-09-13 13:48 ` Hans Verkuil 2019-09-12 20:10 ` [PATCH v3 03/11] dt-bindings: video-interfaces: Expand rotation description Jacopo Mondi 2019-09-13 13:50 ` Hans Verkuil 2019-09-12 20:10 ` Jacopo Mondi [this message] 2019-09-13 14:02 ` [PATCH v3 04/11] media: v4l2-ctrl: Document V4L2_CID_CAMERA_SENSOR_ROTATION Hans Verkuil 2019-09-13 18:49 ` Jacopo Mondi 2019-09-24 15:53 ` Jacopo Mondi 2019-09-27 11:20 ` Hans Verkuil 2019-09-12 20:10 ` [PATCH v3 05/11] media: v4l2-ctrls: Add camera location and rotation Jacopo Mondi 2019-09-12 20:10 ` [PATCH v3 06/11] media: v4l2-fwnode: Add helper to parse device properties Jacopo Mondi 2019-09-13 14:08 ` Hans Verkuil 2019-09-13 19:04 ` Jacopo Mondi 2019-09-27 10:57 ` Hans Verkuil 2019-09-12 20:10 ` [PATCH v3 07/11] include: v4l2-ctrl: Sort forward declarations Jacopo Mondi 2019-09-12 20:10 ` [PATCH v3 08/11] media: v4l2-ctrls: Sort includes alphabetically Jacopo Mondi 2019-09-12 20:10 ` [PATCH v3 09/11] media: v4l2-ctrls: Add helper to register properties Jacopo Mondi 2019-09-13 14:25 ` Hans Verkuil 2019-09-12 20:10 ` [PATCH v3 10/11] media: i2c: ov5670: Parse and " Jacopo Mondi 2019-09-12 20:10 ` [PATCH v3 11/11] media: i2c: ov13858: " Jacopo Mondi
Reply instructions: You may reply publically to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20190912201055.13964-5-jacopo@jmondi.org \ --to=jacopo@jmondi.org \ --cc=hverkuil-cisco@xs4all.nl \ --cc=laurent.pinchart@ideasonboard.com \ --cc=linux-media@vger.kernel.org \ --cc=mchehab@kernel.org \ --cc=pavel@ucw.cz \ --cc=sakari.ailus@linux.intel.com \ --cc=tfiga@google.com \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Linux-Media Archive on lore.kernel.org Archives are clonable: git clone --mirror https://lore.kernel.org/linux-media/0 linux-media/git/0.git # If you have public-inbox 1.1+ installed, you may # initialize and index your mirror using the following commands: public-inbox-init -V2 linux-media linux-media/ https://lore.kernel.org/linux-media \ linux-media@vger.kernel.org public-inbox-index linux-media Example config snippet for mirrors Newsgroup available over NNTP: nntp://nntp.lore.kernel.org/org.kernel.vger.linux-media AGPL code for this site: git clone https://public-inbox.org/public-inbox.git