From patchwork Mon Sep 30 19:59:09 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 21440 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id 6824CC3257 for ; Mon, 30 Sep 2024 19:59:39 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 1173A63518; Mon, 30 Sep 2024 21:59:39 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="uD8UHZfE"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 9538A63516 for ; Mon, 30 Sep 2024 21:59:31 +0200 (CEST) Received: from ideasonboard.com (unknown [95.131.46.153]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id EC1BBA2F; Mon, 30 Sep 2024 21:57:58 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1727726280; bh=x+I7ykB+ojLGHL4GByGX0cx9G+UWeYOz0fLsOocL+64=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=uD8UHZfEQ2X7IkDXhTDOugEskqzUfyPH9DgcTPDvUhazFduGKjwZ5jRJ5+P/KtNaE vI4y0438bdqAtWIjXthcL/uWXGTPD8OKwLMw+m4u0iTMLTSmP7x53iRJrC4f/S2UfU wyLuVlp/8JYlQnbiYSVuwg2+0t5U4N9ZXHijnCXY= From: Jacopo Mondi To: libcamera-devel@lists.libcamera.org Cc: Jacopo Mondi , Harvey Yang Subject: [PATCH v9 1/5] libcamera: geometry: Clarify Rectangle's top-left corner Date: Mon, 30 Sep 2024 21:59:09 +0200 Message-ID: <20240930195915.152187-2-jacopo.mondi@ideasonboard.com> X-Mailer: git-send-email 2.46.1 In-Reply-To: <20240930195915.152187-1-jacopo.mondi@ideasonboard.com> References: <20240930195915.152187-1-jacopo.mondi@ideasonboard.com> MIME-Version: 1.0 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The libcamera::Rectangle class allows defining rectangles regardless of the orientation of the reference system where a rectangle is used in. This implies that, depending on the reference system in use, the rectangle's top-left corner, as defined by libcamera, doesn't correspond to the visual top-left position. ^ | | ------------------- | ^ | h | | | y| o---->------------- | w -------------------------------> (0,0) x (0,0) x ------------------------------> | w y| o---->------------- | | | h | v | | ------------------- | V Clarify that a Rectangle's top-left corner corresponds to the point with the smaller x and y coordinates and that the horizontal and vertical dimensions are obtained by positive increments along the corresponding axes. Signed-off-by: Jacopo Mondi Reviewed-by: Harvey Yang Reviewed-by: David Plowman --- src/libcamera/geometry.cpp | 93 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/src/libcamera/geometry.cpp b/src/libcamera/geometry.cpp index 000151364c7f..6eb432e5d803 100644 --- a/src/libcamera/geometry.cpp +++ b/src/libcamera/geometry.cpp @@ -595,6 +595,88 @@ std::ostream &operator<<(std::ostream &out, const SizeRange &sr) * Rectangles are used to identify an area of an image. They are specified by * the coordinates of top-left corner and their horizontal and vertical size. * + * libcamera canonically defines a rectangle's 'top-left' corner as the point + * with the smaller 'x' and smaller 'y' coordinates. Depending on the reference + * system where the rectangle is used this might not correspond to the visual + * top-left corner of the rectangle. + * + * The rectangle's horizontal and vertical dimensions are obtained by positively + * increments along the corresponding axes by the given horizontal and vertical + * sizes. + * + * Examples: + * + * \verbatim + + X = top-left corner + o = reference system origin point + + ^ + | + | ----------------- + | ^ | + | | | + | X--->------------- + | + o-------------------------------> + (0,0) + + + (0,0) + <-------------------------------o + | + -------------<---X | + | | | + | V | + ----------------- | + V + + + (0,0) + o-------------------------------> + | X--->------------- + | | | + | v | + | ----------------- + | + V + + ^ + | + ----------------- | + | ^ | + | | | + -------------<---X | + <-------------------------------o + (0,0) + + ^ + | + ------|----------- + ^ | | + | | | + X--->--|----------- + ---------------o----------------> + |(0,0) + | + | + | + | + + ^ + | + | + | + | + | + ---------------o----------------> + (0,0)| ------------ + | ^ | + | | | + | X--->-------- + | + \endverbatim + * * The measure unit of the rectangle coordinates and size, as well as the * reference point from which the Rectangle::x and Rectangle::y displacements * refers to, are defined by the context were rectangle is used. @@ -611,6 +693,8 @@ std::ostream &operator<<(std::ostream &out, const SizeRange &sr) * \param[in] x The horizontal coordinate of the top-left corner * \param[in] y The vertical coordinate of the top-left corner * \param[in] size The size + * + * The rectangle's top-left corner is the point with the smaller x and y values. */ /** @@ -620,6 +704,8 @@ std::ostream &operator<<(std::ostream &out, const SizeRange &sr) * \param[in] y The vertical coordinate of the top-left corner * \param[in] width The width * \param[in] height The height + * + * The rectangle's top-left corner is the point with the smaller x and y values. */ /** @@ -632,11 +718,15 @@ std::ostream &operator<<(std::ostream &out, const SizeRange &sr) /** * \var Rectangle::x * \brief The horizontal coordinate of the rectangle's top-left corner + * + * The rectangle's top-left corner is the point with the smaller x and y values. */ /** * \var Rectangle::y * \brief The vertical coordinate of the rectangle's top-left corner + * + * The rectangle's top-left corner is the point with the smaller x and y values. */ /** @@ -685,6 +775,9 @@ Point Rectangle::center() const /** * \fn Point Rectangle::topLeft() const * \brief Retrieve the coordinates of the top left corner of this Rectangle + * + * The rectangle's top-left corner is the point with the smaller x and y values. + * * \return The Rectangle's top left corner */