libcamera: libcamera::ipa::Pwl Class Reference

libcamera v0.5.1 Supporting cameras in Linux since 2019

Loading...
Searching...
No Matches
libcamera::ipa::Pwl Class Reference

Describe a univariate piecewise linear function in two-dimensional real space. More...

## Classes
class | Interval
| Describe an interval in one-dimensional real space. More...

## Public Types
using | Point = Vector<double, 2>
| Describe a point in two-dimensional real space.

## Public Member Functions
| Pwl ()
| Construct an empty piecewise linear function.
| Pwl (const std::vector< Point > &points)
| Construct a piecewise linear function from a list of 2D points.
| Pwl (std::vector< Point > &&points)
| Construct a piecewise linear function from a list of 2D points.
void | append (double x, double y, double eps=1e-6)
| Append a point to the end of the piecewise linear function.
bool | empty () const
| Check if the piecewise linear function is empty.
void | clear ()
| Clear the piecewise linear function.
size_t | size () const
| Retrieve the number of points in the piecewise linear function.
Interval | domain () const
| Get the domain of the piecewise linear function.
Interval | range () const
| Get the range of the piecewise linear function.
double | eval (double x, int *span=nullptr, bool updateSpan=true) const
| Evaluate the piecewise linear function.
std::pair< Pwl, bool > | inverse (double eps=1e-6) const
| Compute the inverse function.
Pwl | compose (const Pwl &other, double eps=1e-6) const
| Compose two piecewise linear functions together.
void | map (std::function< void(double x, double y)> f) const
| Apply function to (x, y) values at every control point.
Pwl & | operator*= (double d)
| Multiply the piecewise linear function.
std::string | toString () const
| Assemble and return a string describing the piecewise linear function.

## Static Public Member Functions
static Pwl | combine (const Pwl &pwl0, const Pwl &pwl1, std::function< double(double x, double y0, double y1)> f, double eps=1e-6)
| Combine two Pwls.

## Detailed Description

Describe a univariate piecewise linear function in two-dimensional real space.

A piecewise linear function is a univariate function that maps reals to reals, and it is composed of multiple straight-line segments.

While a mathematical piecewise linear function would usually be defined by a list of linear functions and for which values of the domain they apply, this Pwl class is instead defined by a list of points at which these line segments intersect. These intersecting points are known as knots.

https://en.wikipedia.org/wiki/Piecewise_linear_function

A consequence of the Pwl class being defined by knots instead of linear functions is that the values of the piecewise linear function past the ends of the function are constants as opposed to linear functions. In a mathematical piecewise linear function that is defined by multiple linear functions, the ends of the function are also linear functions and hence grow to infinity (or negative infinity). However, since this Pwl class is defined by knots, the y-value of the leftmost and rightmost knots will hold for all x values to negative infinity and positive infinity, respectively.

## Constructor & Destructor Documentation

## ◆ Pwl() [1/2]

libcamera::ipa::Pwl::Pwl | ( | const std::vector< Point > & | points | ) |

Construct a piecewise linear function from a list of 2D points.

Parameters

  [in] | points | Vector of points from which to construct the piecewise linear function

points must be in ascending order of x-value.

## ◆ Pwl() [2/2]

libcamera::ipa::Pwl::Pwl | ( | std::vector< Point > && | points | ) |

Construct a piecewise linear function from a list of 2D points.

Parameters

  [in] | points | Vector of points from which to construct the piecewise linear function

points must be in ascending order of x-value.

The contents of the points vector is moved to the newly constructed Pwl instance.

## Member Function Documentation

## ◆ append()

void libcamera::ipa::Pwl::append | ( | double | x,
|  | double | y,
|  | double | eps = 1e-6 )

Append a point to the end of the piecewise linear function.

Parameters

  [in] | x | x-coordinate of the point to add to the piecewise linear function
  [in] | y | y-coordinate of the point to add to the piecewise linear function
  [in] | eps | Epsilon for the minimum x distance between points (optional)

The point's x-coordinate must be greater than the x-coordinate of the last (= greatest) point already in the piecewise linear function.

## ◆ combine()

Pwl libcamera::ipa::Pwl::combine | ( | const Pwl & | pwl0,
|  | const Pwl & | pwl1,
|  | std::function< double(double x, double y0, double y1)> | f,
|  | double | eps = 1e-6 )
| static

Combine two Pwls.

Parameters

  [in] | pwl0 | First piecewise linear function
  [in] | pwl1 | Second piecewise linear function
  [in] | f | Function to be applied
  [in] | eps | Epsilon for the minimum x distance between points (optional)

Create a new Pwl where the y values are given by running f wherever either pwl has a knot.

Returns
  The combined pwl

## ◆ compose()

Pwl libcamera::ipa::Pwl::compose | ( | const Pwl & | other,
|  | double | eps = 1e-6 ) const

Compose two piecewise linear functions together.

Parameters

  [in] | other | The "other" piecewise linear function
  [in] | eps | Epsilon for the minimum x distance between points (optional)

The "this" function is done first, and "other" after.

Returns
  The composed piecewise linear function

## ◆ domain()

Pwl::Interval libcamera::ipa::Pwl::domain | ( |  | ) | const

Get the domain of the piecewise linear function.

Returns
  An interval representing the domain

## ◆ empty()

bool libcamera::ipa::Pwl::empty | ( |  | ) | const
| inline

Check if the piecewise linear function is empty.

Returns
  True if there are no points in the function, false otherwise

## ◆ eval()

double libcamera::ipa::Pwl::eval | ( | double | x,
|  | int * | span = nullptr,
|  | bool | updateSpan = true ) const

Evaluate the piecewise linear function.

Parameters

  [in] | x | The x value to input into the function
  [in,out] | span | Initial guess for span
  [in] | updateSpan | Set to true to update span

Evaluate Pwl, optionally supplying an initial guess for the "span". The "span" may be optionally be updated. If you want to know the "span" value but don't have an initial guess you can set it to -1.

Returns
  The result of evaluating the piecewise linear function at position x

## ◆ inverse()

std::pair< Pwl, bool > libcamera::ipa::Pwl::inverse | ( | double | eps = 1e-6 | ) | const

Compute the inverse function.

Parameters

  [in] | eps | Epsilon for the minimum x distance between points (optional)

The output includes whether the resulting inverse function is a proper (true) inverse, or only a best effort (e.g. input was non-monotonic).

Returns
  A pair of the inverse piecewise linear function, and whether or not the result is a proper/true inverse

## ◆ map()

void libcamera::ipa::Pwl::map | ( | std::function< void(double x, double y)> | f | ) | const

Apply function to (x, y) values at every control point.

Parameters

  [in] | f | Function to be applied

## ◆ operator*=()

Pwl & libcamera::ipa::Pwl::operator*= | ( | double | d | ) |

Multiply the piecewise linear function.

Parameters

  [in] | d | Scalar multiplier to multiply the function by

Returns
  This function, after it has been multiplied by d

## ◆ range()

Pwl::Interval libcamera::ipa::Pwl::range | ( |  | ) | const

Get the range of the piecewise linear function.

Returns
  An interval representing the range

## ◆ size()

size_t libcamera::ipa::Pwl::size | ( |  | ) | const
| inline

Retrieve the number of points in the piecewise linear function.

Returns
  The number of points in the piecewise linear function

## ◆ toString()

std::string libcamera::ipa::Pwl::toString | ( |  | ) | const

Assemble and return a string describing the piecewise linear function.

Returns
  A string describing the piecewise linear function

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

- src/ipa/libipa/pwl.h
- src/ipa/libipa/pwl.cpp