On 10/7/19 6:29 PM, Jacopo Mondi wrote: > 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@xxxxxxxxxx> > --- > .../media/uapi/v4l/ext-ctrls-camera.rst | 116 ++++++++++++++++++ > 1 file changed, 116 insertions(+) > > diff --git a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst > index b151c016256c..e1fee4814e5b 100644 > --- a/Documentation/media/uapi/v4l/ext-ctrls-camera.rst > +++ b/Documentation/media/uapi/v4l/ext-ctrls-camera.rst > @@ -542,6 +542,122 @@ 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 for 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,num-col) > + ! 1,0 1,1 1,2 ... > + ! ... > + ! ... > + ! (num-lines,0)...(num-col,num-lines) Hmm, how about 'max-col' and 'max-row'? num-col is wrong anyway since it would have to be num-cols - 1 because you start at 0. It's easier to go with max-col/row. > + y V > + > + > + Assuming pixels are scanned out from (0,0) to (num-lines,num-col) > + progressively:: > + > + (0,0) ---->-------------> (0,num-col) > + (1,0) ---->-------------> (1,num-col) > + ( .... )-->-------------> ( .... ) > + (num-lines,0)----------->(num-lines,num-col) > + > + > + 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,num-col) ... ... (num-lines,num-col) > + ! .... > + ! 0,2 1,2 ... ... > + ! 0,1 1,1 ... ... > + ! 0,0 1,0 ... (num-lines,0) > + (0,0)------------------------------------> > + y > + > + And the pixel scan-out sequence would then proceed as follows starting > + from pixel (0,0):: > + > + (0,num-col) (num-lines,num-col) > + ^ ^ ^ ^ ^ > + ! ! ! ! ! > + ! ! ! ! ! > + ! ! ! ! ! > + ! ! ! ! ! > + (0,0) (1,0).... (num-lines,0) > + > + Which when applied to the capture scene gives:: > + > + (0,num-col) (num-lines,num-col) > + ^ ^ ^ ^ ^ > + ! ! 0 ! ! > + ! ! -|- ! ! > + ! ! /!\ ! ! > + ! ! ! ! ! > + (0,0) (1,0).... (num-lines,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 > + image when displayed on the screen. > + > + 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 > + +------+ > + | > + V > + +------+ > + | \ ! | Resulting captured > + | --0 | image when displayed > + | / ! | on screen > + +------+ > + | > + V > + +------+ > + | 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. > This gave me a headache, but you are correct w.r.t. image and mounting rotation. Regards, Hans
