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. More...

constexpr	Rectangle (int xpos, int ypos, unsigned int w, unsigned int h)
	Construct a Rectangle with the given position and size. More...

constexpr	Rectangle (const Size &size)
	Construct a Rectangle of size with its top left corner located at (0,0) More...

constexpr	Rectangle (const Point &point1, const Point &point2)
	Construct a Rectangle from two opposite corners. More...

bool	isNull () const
	Check if the rectangle is null. More...

const std::string	toString () const
	Assemble and return a string describing the rectangle. More...

Point	center () const
	Retrieve the center point of this rectangle. More...

Size	size () const
	Retrieve the size of this rectangle. More...

Point	topLeft () const
	Retrieve the coordinates of the top left corner of this Rectangle. More...

Rectangle &	scaleBy (const Size &numerator, const Size &denominator)
	Apply a non-uniform rational scaling in place to this Rectangle. More...

Rectangle &	translateBy (const Point &point)
	Translate this Rectangle in place by the given Point. More...

__nodiscard Rectangle	boundedTo (const Rectangle &bound) const
	Calculate the intersection of this Rectangle with another. More...

__nodiscard Rectangle	enclosedIn (const Rectangle &boundary) const
	Enclose a Rectangle so as not to exceed another Rectangle. More...

__nodiscard Rectangle	scaledBy (const Size &numerator, const Size &denominator) const
	Apply a non-uniform rational scaling to this Rectangle. More...

__nodiscard Rectangle	translatedBy (const Point &point) const
	Translate a Rectangle by the given amounts. More...

Rectangle	transformedBetween (const Rectangle &source, const Rectangle &target) const
	Transform a Rectangle from one reference rectangle to another. More...

Public Attributes
int	x
	The horizontal coordinate of the rectangle's top-left corner. More...

int	y
	The vertical coordinate of the rectangle's top-left corner. More...

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

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

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 )

inlineexplicit

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

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

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

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

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);

◆ 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

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

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

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

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Rectangle() [1/4]

◆ Rectangle() [2/4]

◆ Rectangle() [3/4]

◆ Rectangle() [4/4]

Member Function Documentation

◆ boundedTo()

◆ center()

◆ enclosedIn()

◆ isNull()

◆ scaleBy()

◆ scaledBy()

◆ size()

◆ topLeft()

◆ toString()

◆ transformedBetween()

◆ translateBy()

◆ translatedBy()

Member Data Documentation

◆ x

◆ y