pyzernike.xy_zernike_polynomial

pyzernike.xy_zernike_polynomial(x: ndarray, y: ndarray, n: array | Sequence[Integral], m: array | Sequence[Integral], Rx: Real = 1.0, Ry: Real = 1.0, x0: Real = 0.0, y0: Real = 0.0, alpha: Real = 0.0, h: Real = 0.0, x_derivative: array | Sequence[Integral] | None = None, y_derivative: array | Sequence[Integral] | None = None, default: Real = nan, precompute: bool = True) → List[ndarray]

Computes the Zernike polynomial \(Z_{n}^{m}(\rho_{eq}, \theta_{eq})\) for given cartesian coordinates \((x, y)\) on an elliptic annulus domain.

See also

• pyzernike.zernike_polynomial() for computing the Zernike polynomial \(Z_{n}^{m}\) for polar coordinates \((\rho, \theta)\).

• pyzernike.cartesian_to_elliptic_annulus() to convert Cartesian coordinates to elliptic annulus domain polar coordinates.

• The page Mathematical description in the documentation for the mathematical extension of the Zernike polynomials on the elliptic domain.

See also

For the mathematical development of the method, see the paper Generalization of Zernike polynomials for regular portions of circles and ellipses by Rafael Navarro, José L. López, José Rx. Díaz, and Ester Pérez Sinusía. The associated paper is available in the resources folder of the package.

Download the PDF : PDF

Lets consider the extended elliptic annulus domain defined by the following parameters:

The parameters to define the extended domain of the Zernike polynomial.

The parameters are:

• \(R_x\) and \(R_y\) are the lengths of the semi-axis of the ellipse.

• \(x_0\) and \(y_0\) are the coordinates of the center of the ellipse.

• \(\alpha\) is the rotation angle of the ellipse in radians.

• \(h=\frac{a}{R_x}=\frac{b}{R_y}\) defining the inner boundary of the ellipse.

The Zernike polynomial \(Z_{n}^{m}(\rho_{eq}, \theta_{eq})\) is computed for the equivalent polar coordinates.

This function allows to compute several Zernike polynomials at once for different sets of (order, azimuthal frequency, derivative orders) given as sequences, which can be more efficient than calling the polynomial function multiple times.

• The parameters x and y must be numpy arrays of the same shape.

• The parameters n, m, x_derivative and y_derivative must be sequences of integers with the same length.

The output is a list of numpy arrays, each containing the values of the Zernike polynomial for the corresponding order and azimuthal frequency. The list has the same length as the input sequences and the arrays have the same shape as x.

Note

If the input x or y are not floating point numpy arrays, it is converted to one with numpy.float64 dtype. If the input x or y are floating point numpy arrays (ex: numpy.float32), the computation will be done in numpy.float32. If the input x and y are not of the same dtype, they are both converted to numpy.float64.

Warning

The only available derivatives are the first and second order derivatives with respect to x or y independently (jacobian and hessian matrix). For more complex derivatives, please implement the Faa di Bruno’s formula using the standard Zernike polynomial function with polar coordinates.

• Available derivatives (:math:(dx, dy)): (0, 0), (1, 0), (0, 1), (2, 0), (0, 2), (1, 1).

Parameters:

• x (numpy.ndarray) – The x coordinates in Cartesian system with shape (…,).

• y (numpy.ndarray) – The y coordinates in Cartesian system with shape (…,).

• n (Sequence[Integral] or numpy.array) – A sequence (List, Tuple) or 1D numpy array of the radial order(s) of the Zernike polynomial(s) to compute. Must be non-negative integers.

• m (Sequence[Integral] or numpy.array) – A sequence (List, Tuple) or 1D numpy array of the azimuthal frequency(ies) of the Zernike polynomial(s) to compute. Must be non-negative integers.

• Rx (Real, optional) – The length of the semi-axis of the ellipse along x axis. Must be strictly positive. The default is 1.0, which corresponds to the unit circle.

• Ry (Real, optional) – The length of the semi-axis of the ellipse along y axis. Must be strictly positive. The default is 1.0, which corresponds to the unit circle.

• x0 (Real, optional) – The x coordinate of the center of the ellipse. Can be any real number. The default is 0.0, which corresponds to an ellipse centered at the origin.

• y0 (Real, optional) – The y coordinate of the center of the ellipse. Can be any real number. The default is 0.0, which corresponds to an ellipse centered at the origin.

• alpha (Real, optional) – The rotation angle of the ellipse in radians. Can be any real number. The default is 0.0, such as \(x\) and \(y\) axis are aligned with the ellipse axes.

• h (Real, optional) – The ratio of the inner semi-axis to the outer semi-axis. Must be in the range [0, 1). The default is 0.0, which corresponds to a filled ellipse.

• x_derivative (Optional[Union[Sequence[Integral], numpy.array]], optional) – A sequence (List, Tuple) or 1D numpy array of the order(s) of the x derivative(s) to compute. Must be non-negative integers. If None, is it assumed that x_derivative is 0 for all polynomials.

• y_derivative (Optional[Union[Sequence[Integral], numpy.array]], optional) – A sequence (List, Tuple) or 1D numpy array of the order(s) of the y derivative(s) to compute. Must be non-negative integers. If None, is it assumed that y_derivative is 0 for all polynomials.

• default (Real, optional) – The default value to use for points outside the elliptic annulus domain. Must be a real number. The default is numpy.nan.

• precompute (bool, optional) – If True, precomputes the useful terms for better performance when computing multiple polynomials with the same rho values. If False, computes the useful terms on the fly for each polynomial to avoid memory overhead. The default is True.

Returns:

A list of numpy arrays containing the Zernike polynomial values for each order and azimuthal frequency. Each array has the same shape as x.

Return type:

List[numpy.ndarray]

Raises:

• TypeError – If the x or y values can not be converted to a numpy array of floating points values. If n, m, x_derivative or y_derivative (if not None) are not sequences of integers.

• ValueError – If the x and y do not have the same shape. If the lengths of n, m, x_derivative and y_derivative (if not None) are not the same. If Rx or Ry are not strictly positive. If h is not in the range [0, 1[. If the derivative orders are higher than 2 or mixed (ex: (1, 1)).

Examples

Let’s consider a full circle with a radius of 10 centered at the origin (1, 1). The value of the zernike polynomial \(Z_{2}^{0}\) at the point (x, y) is given by:

import numpy
from pyzernike import xy_zernike_polynomial # or Zxy
x = numpy.linspace(-10, 10, 100)
y = numpy.linspace(-10, 10, 100)
X, Y = numpy.meshgrid(x, y)

output = xy_zernike_polynomial(X, Y, n=[2], m=[0], Rx=10, Ry=10, x0=1.0, y0=1.0) # List with a single numpy array
zernike_n2_m0 = output[0] # Shape similar to X and Y

returns a list with a single numpy array containing the values of the Zernike polynomial \(Z_{2}^{0}\) at the points (X, Y) within the circle of radius 10.

To compute the first derivative with respect to x and y, we can use:

output = xy_zernike_polynomial(X, Y, n=[2, 2], m=[0, 0], Rx=10, Ry=10, x0=1.0, y0=1.0, x_derivative=[1, 0], y_derivative=[0, 1]) # List with two numpy arrays
zernike_n2_m0_dx = output[0] # First derivative with respect to x
zernike_n2_m0_dy = output[1] # First derivative with respect to y