prysm.coordinates#

Coordinate conversions.

prysm.coordinates.optimize_xy_separable(x, y)#

Optimize performance for downstream operations.

Parameters:

  • x (ndarray) – 2D or 1D array

  • y (ndarray) – 2D or 1D array

Returns:

optimized arrays (x as 1D row, y as 1D column)

Return type:

x, y

Notes

If a calculation is separable in x and y, performing it on a meshgrid of x/y takes 2N^2 operations, for N= the linear dimension (the 2 being x and y). If the calculation is separable, this can be reduced to 2N by using numpy broadcast functionality and two 1D calculations.

prysm.coordinates.broadcast_1d_to_2d(x, y)#

Broadcast two (x,y) vectors to 2D.

Parameters:

  • x (ndarray) – ndarray of shape (n,)

  • y (ndarray) – ndarray of shape (m,)

Returns:

  • xx (ndarray) – ndarray of shape (m, n)

  • yy (ndarray) – ndarray of shape (m, n)

prysm.coordinates.cart_to_polar(x, y, vec_to_grid=True)#

Return the (rho,phi) coordinates of the (x,y) input points.

Parameters:

  • x (ndarray or number) – x coordinate

  • y (ndarray or number) – y coordinate

  • vec_to_grid (bool, optional) – if True, convert a vector (x,y) input to a grid (r,t) output

Returns:

  • rho (ndarray or number) – radial coordinate

  • phi (ndarray or number) – azimuthal coordinate

prysm.coordinates.polar_to_cart(rho, phi)#

Return the (x,y) coordinates of the (rho,phi) input points.

Parameters:

  • rho (ndarray or number) – radial coordinate

  • phi (ndarray or number) – azimuthal coordinate

Returns:

  • x (ndarray or number) – x coordinate

  • y (ndarray or number) – y coordinate

prysm.coordinates.sample_axis(distribution, lo, hi, n, dtype=None)#

Generate samples between two endpoints under a named distribution.

Parameters:

  • distribution (str) – One of ‘uniform’, ‘random’, or ‘cheby’. Cheby uses Chebyshev-Gauss-Lobatto nodes mapped monotonically from lo to hi.

  • lo (float) – Lower and upper endpoints.

  • hi (float) – Lower and upper endpoints.

  • n (int) – Number of samples.

  • dtype (dtype, optional) – Output dtype. Defaults to prysm’s configured precision.

Returns:

The sampled coordinate axis.

Return type:

ndarray

prysm.coordinates.promote_3d_point(P, dtype=None)#

Coerce a scalar or trailing-coordinate iterable into a 3-vector.

Scalars are interpreted as a z coordinate and return [0, 0, P]. Iterables are right-aligned, so [z], [y, z], and [x, y, z] are all accepted.

Parameters:

  • P (scalar or iterable) – scalar (interpreted as z), or iterable of length 1, 2, or 3 holding the trailing coordinates [z], [y, z], or [x, y, z]

  • dtype (dtype, optional) – output dtype; defaults to prysm’s configured precision

Returns:

length-3 vector (x, y, z)

Return type:

ndarray

prysm.coordinates.coerce_3d_rotation(R)#

Return None, a supplied rotation matrix, or a matrix from Euler angles.

Parameters:

R (None, ndarray, list, or tuple) – if None, returned as-is. If a list or tuple of Euler angles (Z, Y, X) in degrees, converted via make_rotation_matrix. Otherwise returned unchanged (assumed to already be a 3x3 matrix).

Returns:

None, or a 3x3 rotation matrix

Return type:

None or ndarray

prysm.coordinates.apply_tilt_decenter(P, R, tilt=None, decenter=None, tilt_radians=False, dtype=None)#

Combine a base 3D position and rotation with tilt/decenter offsets.

Parameters:

  • P (ndarray) – length-3 position vector

  • R (ndarray or None) – 3x3 base rotation matrix, or None for identity

  • tilt (tuple of float, optional) – (Z, Y, X) Euler angles applied as an additional rotation on the right of R

  • decenter (array-like, optional) – length-3 vector added to P

  • tilt_radians (bool, optional) – if True, tilt is in radians; otherwise degrees

  • dtype (dtype, optional) – output dtype; defaults to prysm’s configured precision

Returns:

  • P (ndarray) – updated length-3 position

  • R (ndarray or None) – updated 3x3 rotation matrix (or None if no rotations are present)

prysm.coordinates.uniform_cart_to_polar(x, y, data)#

Interpolate data uniformly sampled in cartesian coordinates to polar coordinates.

Parameters:

  • x (ndarray) – sorted 1D array of x sample pts

  • y (ndarray) – sorted 1D array of y sample pts

  • data (ndarray) – data sampled over the (x,y) coordinates

Returns:

  • rho (ndarray) – samples for interpolated values

  • phi (ndarray) – samples for interpolated values

  • f(rho,phi) (ndarray) – data uniformly sampled in (rho,phi)

prysm.coordinates.resample_2d(array, sample_pts, query_pts, kind='cubic')#

Resample 2D array to be sampled along queried points.

Parameters:

  • array (ndarray) – 2D array

  • sample_pts (tuple) – pair of ndarray objects that contain the x and y sample locations, each array should be 1D

  • query_pts (tuple) – points to interpolate onto, also 1D for each array

  • kind (str, {'linear', 'cubic', 'quintic'}) – kind / order of spline to use

Returns:

array resampled onto query_pts

Return type:

ndarray

prysm.coordinates.make_xy_grid(shape, *, dx=0, diameter=0, grid=True)#

Create an x, y grid from -1, 1 with n number of samples.

Parameters:

  • shape (int or tuple of int) – number of samples per dimension. If a scalar value, broadcast to both dimensions. Order is numpy axis convention, (row, col)

  • dx (float) – inter-sample spacing, ignored if diameter is provided

  • diameter (float) – diameter, clobbers dx if both given

  • grid (bool, optional) – if True, return meshgrid of x,y; else return 1D vectors (x, y)

Returns:

  • x (ndarray) – x grid

  • y (ndarray) – y grid

prysm.coordinates.make_rotation_matrix(zyx, radians=False)#

Build a rotation matrix.

Parameters:

  • zyx (tuple of float) – Z, Y, X rotation angles in that order

  • radians (bool, optional) – if True, abg are assumed to be radians. If False, abg are assumed to be degrees.

Returns:

3x3 rotation matrix

Return type:

ndarray

prysm.coordinates.promote_3d_transformation_to_homography(M)#

Convert a 3D transformation to 4D homography.

Parameters:

M (ndarray) – 3x3 transformation matrix

Returns:

4x4 homography with M in the upper-left block and 1 in the (3,3) corner

Return type:

ndarray

prysm.coordinates.promote_affine_transformation_to_homography(Maff)#

Convert a 2D affine transformation to a 3x3 homography.

Parameters:

Maff (ndarray) – 2x3 affine transformation matrix

Returns:

3x3 homography with Maff in the top two rows and [0, 0, 1] in the bottom row

Return type:

ndarray

prysm.coordinates.make_homomorphic_translation_matrix(tx=0, ty=0, tz=0)#

Create a homographic transformation matrix for a 3D translation.

Parameters:

  • tx (float, optional) – translation along x

  • ty (float, optional) – translation along y

  • tz (float, optional) – translation along z

Returns:

4x4 homography that translates (x, y, z) by (tx, ty, tz)

Return type:

ndarray

prysm.coordinates.drop_z_3d_transformation(M)#

Drop the Z entries of a 3D homography.

Drops the third row and third column of 4D transformation matrix M.

Parameters:

M (ndarray) – 4x4 ndarray for (x, y, z, w)

Returns:

3x3 array, (x, y, w)

Return type:

ndarray

prysm.coordinates.pack_xy_to_homographic_points(x, y)#

Pack (x, y) vectors into a vector of coordinates in homogeneous form.

Parameters:

  • x (ndarray) – x points

  • y (ndarray) – y points

Returns:

3xN array (x, y, w)

Return type:

ndarray

prysm.coordinates.apply_homography(M, x, y)#

Apply a homographic transformation M to arrays x and y.

Parameters:

  • M (ndarray) – 3x3 matrix containing a homographic transformation for 2D points

  • x (ndarray) – array (1D or 2D) of coordinates

  • y (ndarray) – array (1D or 2D) of coordinates

Returns:

transformed (x, y) points

Return type:

ndarray, ndarray

prysm.coordinates.solve_for_planar_homography(src, dst)#

Find the planar homography that transforms src -> dst.

Parameters:

  • src (ndarray) – (N, 2) shaped array

  • dst (ndarray) – (N, 2) shaped ndarray

Returns:

3x3 array containing the planar homography such that H * src = dst

Return type:

ndarray

prysm.coordinates.warp(img, xnew, ynew)#

Warp an image, via “pull” and not “push”.

Parameters:

  • img (ndarray) – 2D ndarray

  • xnew (ndarray) – 2D array containing x or column coordinates to look up in img

  • ynew (ndarray) – 2D array containing y or row coordinates to look up in img

Returns:

“pulled” warped image

Return type:

ndarray

Notes

The meaning of pull is that the indices of the output array indices are the output image coordinates, in other words xnew/ynew specify the coordinates in img, at which each output pixel is looked up

this is a dst->src mapping, aka “pull” in common image processing vernacular

prysm.coordinates.distort_annular_grid(r, eps)#

Distort an annular grid, such that an annulus becomes the unit circle.

This function is used to distort the grid before computing annular Zernike or other polynomials

r and eps should be in the range [0,1]

Parameters:

  • r (ndarray) – Undistorted grid of normalized radial coordinates

  • eps (float) – linear obscuration fraction, radius, not diameter; e.g. for a telescope with 20% diameter linear obscuration, eps=0.1

Returns:

distorted r, to be passed to a polynomial function

Return type:

ndarray

prysm.coordinates.chebygauss_quadrature_xy(rings, radius=1, spokes=-1, center=(0, 0))#

Use Chebyshev-Gauss quadrature to sample a polar coordinate grid.

Parameters:

  • rings (int) – number of rings to use; degree of radial sampling

  • radius (float) – radius of the grid, process units

  • spokes (int, optional) – number of spokes if -1, use rings*2 + 1

  • center (tuple) – (x,y) center point of the grid

Returns:

Chebyshev-Gauss-Lobatto points (x,y)

Return type:

ndarray