1. Symmetrizer module (symmetrize.sym)

@author: R. Patrick Xian

symmetrize.sym.applyWarping(imgstack, axis, warptype='matrix', hgmat=None, dfield=None, **kwds)

Apply warping transform to a stack of images along the specified axis.

Parameters:

imgstack : 3D array

Image stack before warping correction.

axis : int

Axis to iterate over to apply the transform.

warptype : str | ‘matrix’

Type of warping (‘matrix’ or ‘deform_field’).

hgmat : 2D array | None

3 x 3 homography (hg) matrix.

dfield : list | None

Deformation fields for the x and y image coordinates.

**kwds : keyword arguments

outshape:tuple/list Shape of the output image. order:int Interpolation order. others:See cv2.warpPerspective() and scipy.ndimage.map_coordinates().

Return:

imstack_transformed : 3D array

Stack of images after correction for warping.

symmetrize.sym.compose_deform_field(coordmat, mat_transform, stackaxis, ret='deformation', ret_indexing='rc')

Compose the deformation/displacement field from coordinate and transform matrices.

Parameters:

coordmat : 3D array

Matrix of all pixel coordinates.

mat_transform : 2D array

Transformation matrix.

stackaxis : int

Axis of the stacking direction in the coordmat (0 or -1).

ret : str | ‘deformation’

Option to return ‘deformation’ or ‘displacement’ fields.

ret_indexing : str | ‘xy’

Indexing of return matrices, ‘rc’ (row deformation, column deformation) or ‘xy’ (x deformation, y deformation). Same for displacements.

Returns:

Deformations fields of x and y coordinates.

symmetrize.sym.coordinate_matrix_2D(image, coordtype='homogeneous', stackaxis=0)

Generate pixel coordinate matrix for a 2D image.

Parameters:

image : 2D array

2D image matrix.

coordtype : str | ‘homogeneous’

Type of generated coordinates (‘homogeneous’ or ‘cartesian’).

stackaxis : int | 0

The stacking axis for the coordinate matrix, e.g. a stackaxis of 0 means that the coordinates are stacked along the first dimension, while -1 means stacking along the last dimension.

Return:

coordmat : 3D array

Coordinate matrix stacked along the specified axis.

symmetrize.sym.deform_field_merge(operation, *fields)

Combine multiple deformation fields.

Parameters:

operation : func/str

Function for merging the deformation fields.

fields : list/tuple

Collections of deformaiton fields.

Return:

Combined deformation field.

symmetrize.sym.foldcost(image, center, axis=1)

Cost function for folding over an image along an image axis crossing the image center.

Parameters:

image : 2d array

Image to fold over.

center : tuple/list

Pixel coordinates of the image center (row, column).

axis : int | 1

Axis along which to fold over the image (1 = column-wise, 0 = row-wise).

Return:

Cost in the form of root-mean-squared (RMS) difference between folded and the unfolded part of the image matrix.

symmetrize.sym.imgWarping(img, hgmat=None, landmarks=None, targs=None, rotangle=None, **kwds)

Perform image warping based on a generic affine transform (homography).

Parameters:

img : 2D array

Input image (distorted).

hgmat : 2D array

Homography matrix.

landmarks : list/array

Pixel coordinates of reference landmarks (distorted).

targs : list/array

Pixel coordinates of target landmarks (undistorted).

rotangle : float

Rotation angle (in degrees).

**kwds : keyword argument

center:

tuple/list/1D array

Coordinates of the center of rotation.

outshape:

tuple/list

Shape of the output image.

Other arguments see cv2.warpPerspective().

Returns:

imgaw : 2D array

Image after affine warping.

hgmat : 2D array

(Composite) Homography matrix for the tranform.

symmetrize.sym.pointsetTransform(points, hgmat)

Apply transform to the positions of a point set.

Parameters:

points : 2D array

Cartesian pixel coordinates of the points.

hgmat : 2D array

Transformation matrix (homography).

Return:

points_transformed : 2D array

Transformed Cartesian pixel coordinates.

symmetrize.sym.rotVertexGenerator(center, fixedvertex=None, cvd=None, arot=None, nside=None, direction=-1, scale=1, diagdir=None, ret='all', rettype='float32')

Generation of the vertices of symmetric polygons.

Parameters:

center : (int, int)

Pixel positions of the symmetry center (row pixel, column pixel).

fixedvertex : (int, int) | None

Pixel position of the fixed vertex (row pixel, column pixel).

cvd : numeric | None

Center-vertex distance.

arot : float | None

Spacing in angle of rotation.

nside : int | None

The total number of sides for the polygon (to be implemented).

direction : int | -1

Direction of angular rotation (1 = counterclockwise, -1 = clockwise).

scale : float | 1

Radial scaling factor.

diagdir : str | None

Diagonal direction of the polygon (‘x’ or ‘y’).

ret : str | ‘all’

Return type. Specify 'all' returns all vertices, specify 'generated' returns only the generated ones (without the fixedvertex in the argument).

Return:

vertices : 2D array

Collection of generated vertices.

symmetrize.sym.rotation2D(angle, center=(0, 0), to_rad=True)

Rotation matrix in 2D in homogeneous coordinates.

Parameters:

angle : numeric

Rotation angle in image coordinates.

center : list/tuple/1D array | (0, 0)

Coordinate of the image center in (row, column) form.

to_rad : bool | True

Option to convert the angle into units of radian.

symmetrize.sym.rotationDF(coordmat, stackaxis=0, angle=0, center=(0, 0), to_rad=True, **kwds)

Deformation field of 2D rotation in image coordinates.

Parameters:See symmetrize.sym.rotation2D().

symmetrize.sym.scaledRotation2D(center, angle, scale)

Scaled rotation matrix in 2D in homogeneous coordinates.

Parameters:

center : list/tuple

Coordinates of the center point of rotation.

angle : numeric

Angle of rotation (in degrees).

scale : numeric

Radial scaling factor.

symmetrize.sym.scaling2D(xscale, yscale)

Biaxial scaling matrix in 2D in homogeneous coordinates.

Parameters:

xscale, yscale : numeric, numeric

Scaling factors along x and y directions.

A scaling factor in the range (1, +inf) amounts to zooming in.

A scaling factor in the range [0, 1) amounts to zomming out.

symmetrize.sym.scalingDF(coordmat, stackaxis=0, xscale=1, yscale=1, **kwds)

Deformation field of 2D scaling in image coordinates.

Parameters:See symmetrize.sym.scaling2D().

symmetrize.sym.shearing2D(xshear, yshear)

Biaxial shearing matrix in 2D in homogeneous coordinates.

Parameters:

xshear, yshear : numeric, numeric

Shearing parameters for the x and y axes.

symmetrize.sym.shearingDF(coordmat, stackaxis=0, xshear=0, yshear=0, **kwds)

Deformation field of 2D shearing in image coordinates.

Parameters:See symmetrize.sym.shearing2D().

symmetrize.sym.sym_pose_estimate(image, center, axis=1, angle_range=None, angle_start=-90, angle_stop=90, angle_step=0.1)

Estimate the best presenting angle using rotation-mirroring grid search such that the image is symmetric about an image axis (row or column). The algorithm calculates the intensity difference mirrored from the center of the image at a range of rotation angles and pick the angle that minimizes this difference.

Parameters:

image : 2d array

Input image for optimal presenting angle estimation.

center : tuple/list

The pixel coordinates of the image center.

axis : int | 1

The axis of reflection (0 = row, 1 = column).

angle_range : list/array | None

The range of angles to be tested.

angle_start, angle_stop, angle_step : float, float, float | -90, 90, 0.1

The bounds and step to generate.

Returns:

aopt : float

The optimal rotation needed for posing image symmetric about an image axis.

imrot : 2d array

Image rotated to the optimal presenting angle.

symmetrize.sym.target_set_optimize(init, targpts, center, mcd, med, direction=-1, rotsym=6, weights=(1, 1, 1), optfunc='minimize', optmethod='Nelder-Mead', include_center=False, ret='lean', **kwds)

Optimization of the target point set for image symmetrization.

Parameters:

init : list/tuple

Initial conditions.

targpts : 2D array

Pixel coordinates of the target point set.

center : list/tuple/array

Image center position.

mcd : numeric

Mean center-vertex distance.

med : numeric

Mean edge distance.

niter : int | 200

Number of iterations.

direction : int | -1

Direction of the target generator.

rotsym : int | 6

Order of rotational symmetry.

weights : tuple/list/array | (1, 1, 1)

Weights assigned to the objective function.

optfunc : str/function | ‘minimize’

Name of the optimizer function.

'basinhopping' Use the scipy.optimize.basinhopping() function.

'minimize' Use the scipy.optimize.minimize() function.

others Use other user-specified optimization function optfunc.

optmethod : string | ‘Nelder-Mead’

Name of the optimization method.

include_center : bool | False

Option to include center.

**kwds : keyword arguments

Keyword arguments passed to the specified optimizer function.

Returns:

ptsw : 2D array

Collection of landmarks (pts = points) after warping (w).

H : 2D array

Coordinate transform matrix.

res : dictionary

Full optimization outcome given by the optimizer (when ret='all' is set).

symmetrize.sym.translation2D(xtrans, ytrans)

Translation matrix in 2D in homogeneous coordinates.

Parameters:

xtrans, ytrans : numeric, numeric

Translations along the x and y image axes.

symmetrize.sym.translationDF(coordmat, stackaxis=0, xtrans=0, ytrans=0, **kwds)

Deformation field of 2D translation in image coordinates.

Parameters:See symmetrize.sym.translation2D().