From patchwork Thu Feb 6 01:25:56 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 2780 Return-Path: Received: from relay10.mail.gandi.net (relay10.mail.gandi.net [217.70.178.230]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id C8BC260446 for ; Thu, 6 Feb 2020 02:23:34 +0100 (CET) Received: from uno.lan (93-34-114-233.ip49.fastwebnet.it [93.34.114.233]) (Authenticated sender: jacopo@jmondi.org) by relay10.mail.gandi.net (Postfix) with ESMTPSA id 92766240002 for ; Thu, 6 Feb 2020 01:23:34 +0000 (UTC) From: Jacopo Mondi To: libcamera-devel@lists.libcamera.org Date: Thu, 6 Feb 2020 02:25:56 +0100 Message-Id: <20200206012601.153858-5-jacopo@jmondi.org> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200206012601.153858-1-jacopo@jmondi.org> References: <20200206012601.153858-1-jacopo@jmondi.org> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v5 4/9] libcamera: properties: Add rotation property X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Feb 2020 01:23:35 -0000 The rotation property describes the rotation of the camera sensor. Reviewed-by: Laurent Pinchart Reviewed-by: Niklas Söderlund Signed-off-by: Jacopo Mondi --- 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. + + +---------------+ + | | + | | + | | + | | + | | + | | + | |\____)\___ | + | ) _____ __`< | + | |/ )/ | + | | + | | + | | + | | + | | + +---------------+ ...