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

[David Plowman]

Hi Jacopo

Thanks for the clarification here.

Yes, I think this is exactly right. I think the important point is
that the "top left" is the corner with smallest x and y in the
coordinate system in which the rectangle was created.

(A viewer might be standing, for example, upside down with respect to
that, in which case it's not _their_ top left any more. But it's the
viewer's problem to deal with their own "transform".)

Reviewed-by: David Plowman <david.plowman at raspberrypi.com>

Thanks!
David

On Tue, 1 Oct 2024 at 08:19, Cheng-Hao Yang <chenghaoyang at chromium.org> wrote:
>
> Hi Jacopo,
>
> Thanks for the updated description.
> It makes more sense to me.
>
> Reviewed-by: Harvey Yang <chenghaoyang at chromium.org>
>
> BR,
> Harvey
>
> On Tue, Oct 1, 2024 at 3:59 AM Jacopo Mondi
> <jacopo.mondi at ideasonboard.com> 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
> > + *
> >   * 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
> >