libcamera v0.5.1 Supporting cameras in Linux since 2019 |

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | List of all members
libcamera::Rectangle Class Reference

Describe a rectangle's position and dimensions. More...

## Public Member Functions
constexpr | Rectangle ()
| Construct a Rectangle with all coordinates set to 0.
constexpr | Rectangle (int xpos, int ypos, const Size &size)
| Construct a Rectangle with the given position and size.
constexpr | Rectangle (int xpos, int ypos, unsigned int w, unsigned int h)
| Construct a Rectangle with the given position and size.
constexpr | Rectangle (const Size &size)
| Construct a Rectangle of size with its top left corner located at (0,0)
constexpr | Rectangle (const Point &point1, const Point &point2)
| Construct a Rectangle from two opposite corners.
bool | isNull () const
| Check if the rectangle is null.
const std::string | toString () const
| Assemble and return a string describing the rectangle.
Point | center () const
| Retrieve the center point of this rectangle.
Size | size () const
| Retrieve the size of this rectangle.
Point | topLeft () const
| Retrieve the coordinates of the top left corner of this Rectangle.
Rectangle & | scaleBy (const Size &numerator, const Size &denominator)
| Apply a non-uniform rational scaling in place to this Rectangle.
Rectangle & | translateBy (const Point &point)
| Translate this Rectangle in place by the given Point.
Rectangle | boundedTo (const Rectangle &bound) const
| Calculate the intersection of this Rectangle with another.
Rectangle | enclosedIn (const Rectangle &boundary) const
| Enclose a Rectangle so as not to exceed another Rectangle.
Rectangle | scaledBy (const Size &numerator, const Size &denominator) const
| Apply a non-uniform rational scaling to this Rectangle.
Rectangle | translatedBy (const Point &point) const
| Translate a Rectangle by the given amounts.
Rectangle | transformedBetween (const Rectangle &source, const Rectangle &target) const
| Transform a Rectangle from one reference rectangle to another.

## Public Attributes
int | x
| The horizontal coordinate of the rectangle's top-left corner.
int | y
| The vertical coordinate of the rectangle's top-left corner.
unsigned int | width
| The distance between the left and right sides.
unsigned int | height
| The distance between the top and bottom sides.

## Detailed Description

Describe a rectangle's position and dimensions.

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 refers to, are defined by the context were rectangle is used.

## Constructor & Destructor Documentation

## ◆ Rectangle() [1/4]

libcamera::Rectangle::Rectangle | ( | int | x,
|  | int | y,
|  | const Size & | size )
| inline constexpr

Construct a Rectangle with the given position and size.

Parameters

  [in] | x | The horizontal coordinate of the top-left corner
  [in] | y | The vertical coordinate of the top-left corner
  [in] | size | The size

The rectangle's top-left corner is the point with the smaller x and y values.

## ◆ Rectangle() [2/4]

libcamera::Rectangle::Rectangle | ( | int | x,
|  | int | y,
|  | unsigned int | width,
|  | unsigned int | height )
| inline constexpr

Construct a Rectangle with the given position and size.

Parameters

  [in] | x | The horizontal coordinate of the top-left corner
  [in] | y | The vertical coordinate of the top-left corner
  [in] | width | The width
  [in] | height | The height

The rectangle's top-left corner is the point with the smaller x and y values.

## ◆ Rectangle() [3/4]

libcamera::Rectangle::Rectangle | ( | const Size & | size | ) |
| inline explicit constexpr

Construct a Rectangle of size with its top left corner located at (0,0)

Parameters

  [in] | size | The desired Rectangle size

## ◆ Rectangle() [4/4]

libcamera::Rectangle::Rectangle | ( | const Point & | point1,
|  | const Point & | point2 )
| inline constexpr

Construct a Rectangle from two opposite corners.

Parameters

  [in] | point1 | One of corners of the rectangle
  [in] | point2 | The opposite corner of point1

## Member Function Documentation

## ◆ boundedTo()

Rectangle libcamera::Rectangle::boundedTo | ( | const Rectangle & | bound | ) | const
| nodiscard

Calculate the intersection of this Rectangle with another.

Parameters

  [in] | bound | The Rectangle that is intersected with this Rectangle

This function calculates the standard intersection of two rectangles. If the rectangles do not overlap in either the x or y direction, then the size of that dimension in the result (its width or height) is set to zero. Even when one dimension is set to zero, note that the other dimension may still have a positive value if there was some overlap.

Returns
  A Rectangle that is the intersection of the input rectangles

## ◆ center()

Point libcamera::Rectangle::center | ( |  | ) | const

Retrieve the center point of this rectangle.

Returns
  The center Point

## ◆ enclosedIn()

Rectangle libcamera::Rectangle::enclosedIn | ( | const Rectangle & | boundary | ) | const
| nodiscard

Enclose a Rectangle so as not to exceed another Rectangle.

Parameters

  [in] | boundary | The limit that the returned Rectangle will not exceed

The Rectangle is modified so that it does not exceed the given boundary. This process involves translating the Rectangle if any of its edges lie beyond boundary, so that those edges then lie along the boundary instead.

If either width or height are larger than boundary, then the returned Rectangle is clipped to be no larger. But other than this, the Rectangle is not clipped or reduced in size, merely translated.

Note that this is not a conventional Rectangle intersection function which is provided by boundedTo().

Returns
  A Rectangle that does not extend beyond a boundary Rectangle

## ◆ isNull()

bool libcamera::Rectangle::isNull | ( |  | ) | const
| inline

Check if the rectangle is null.

Returns
  True if both the width and height are 0, or false otherwise

## ◆ scaleBy()

Rectangle & libcamera::Rectangle::scaleBy | ( | const Size & | numerator,
|  | const Size & | denominator )

Apply a non-uniform rational scaling in place to this Rectangle.

Parameters

  [in] | numerator | The numerators of the x and y scaling factors
  [in] | denominator | The denominators of the x and y scaling factors

A non-uniform scaling is applied in place such the resulting x coordinates are multiplied by numerator.width / denominator.width, and similarly for the y coordinates (using height in place of width).

Returns
  A reference to this object

## ◆ scaledBy()

Rectangle libcamera::Rectangle::scaledBy | ( | const Size & | numerator,
|  | const Size & | denominator ) const
| nodiscard

Apply a non-uniform rational scaling to this Rectangle.

Parameters

  [in] | numerator | The numerators of the x and y scaling factors
  [in] | denominator | The denominators of the x and y scaling factors

A non-uniform scaling is applied such the resulting x coordinates are multiplied by numerator.width / denominator.width, and similarly for the y coordinates (using height in place of width).

Returns
  The non-uniformly scaled Rectangle

## ◆ size()

Size libcamera::Rectangle::size | ( |  | ) | const
| inline

Retrieve the size of this rectangle.

Returns
  The Rectangle size

## ◆ topLeft()

Point libcamera::Rectangle::topLeft | ( |  | ) | const
| inline

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.

Returns
  The Rectangle's top left corner

## ◆ toString()

const std::string libcamera::Rectangle::toString | ( |  | ) | const

Assemble and return a string describing the rectangle.

Returns
  A string describing the Rectangle

## ◆ transformedBetween()

Rectangle libcamera::Rectangle::transformedBetween | ( | const Rectangle & | source,
|  | const Rectangle & | destination ) const

Transform a Rectangle from one reference rectangle to another.

Parameters

  [in] | source | The source reference rectangle
  [in] | destination | The destination reference rectangle

The source and destination parameters describe two rectangles defined in different reference systems. The Rectangle is translated from the source reference system into the destination reference system.

The typical use case for this function is to translate a selection rectangle specified in a reference system, in example the sensor's pixel array, into the same rectangle re-scaled and translated into a different reference system, in example the output frame on which the selection rectangle is applied to.

For example, consider a sensor with a resolution of 4040x2360 pixels and a assume a rectangle of (100, 100)/3840x2160 (sensorFrame) in sensor coordinates is mapped to a rectangle (0,0)/(1920,1080) (displayFrame) in display coordinates. This function can be used to transform an arbitrary rectangle from display coordinates to sensor coordinates or vice versa:

Rectangle sensorReference(100, 100, 3840, 2160);
Rectangle displayReference(0, 0, 1920, 1080);
// Bottom right quarter in sensor coordinates
Rectangle sensorRect(2020, 100, 1920, 1080);
displayRect = sensorRect.transformedBetween(sensorReference, displayReference);
// displayRect is now (960, 540)/960x540
// Transformation back to sensor coordinates
sensorRect = displayRect.transformedBetween(displayReference, sensorReference);
libcamera::Rectangle::Rectangle
constexpr Rectangle()
Construct a Rectangle with all coordinates set to 0.
Definition geometry.h:243

## ◆ translateBy()

Rectangle & libcamera::Rectangle::translateBy | ( | const Point & | point | ) |

Translate this Rectangle in place by the given Point.

Parameters

  [in] | point | The amount to translate the Rectangle by

The Rectangle is translated in the x-direction by the point's x coordinate and in the y-direction by the point's y coordinate.

Returns
  A reference to this object

## ◆ translatedBy()

Rectangle libcamera::Rectangle::translatedBy | ( | const Point & | point | ) | const
| nodiscard

Translate a Rectangle by the given amounts.

Parameters

  [in] | point | The amount to translate the Rectangle by

The Rectangle is translated in the x-direction by the point's x coordinate and in the y-direction by the point's y coordinate.

Returns
  The translated Rectangle

## Member Data Documentation

## ◆ x

int libcamera::Rectangle::x

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.

## ◆ y

int libcamera::Rectangle::y

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.

The documentation for this class was generated from the following files:

- include/libcamera/geometry.h
- src/libcamera/geometry.cpp