[PATCH v9 1/5] libcamera: geometry: Clarify Rectangle's top-left corner

[Laurent Pinchart]

Hi Jacopo,

Thank you for the patch.

On Mon, Sep 30, 2024 at 09:59:09PM +0200, Jacopo Mondi wrote:
> 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 <jacopo.mondi at ideasonboard.com>
> ---
>  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
> + *

I think this is way too complicated and confusing. Can't we simplify
this patch to just the two lines below ?

diff --git a/src/libcamera/geometry.cpp b/src/libcamera/geometry.cpp
index 000151364c7f..57894f767c68 100644
--- a/src/libcamera/geometry.cpp
+++ b/src/libcamera/geometry.cpp
@@ -594,6 +594,8 @@ 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.
+ * By convention, the top-left corner is defined as the corner with the lowest
+ * x and y coordinates, regardless of the origin and direction of the axes.
  *
  * The measure unit of the rectangle coordinates and size, as well as the
  * reference point from which the Rectangle::x and Rectangle::y displacements


>   * 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
>   */
>  
> -- 
> 2.46.1
> 

-- 
Regards,

Laurent Pinchart