DataSetFilters.align_xyz

DataSetFilters.align_xyz(

*,

centered: bool = True,

axis_0_direction: VectorLikeFloat | str | None = None,

axis_1_direction: VectorLikeFloat | str | None = None,

axis_2_direction: VectorLikeFloat | str | None = None,

cell_centers: bool = False,

merge_points: bool = False,

return_matrix: bool = False,

) → _DataSetType | tuple[_DataSetType, NDArray[np.float64]]

Align a dataset to the x-y-z axes.

This filter aligns a mesh’s principal_axes() to the world x-y-z axes. The principal axes are effectively used as a rotation matrix to rotate the dataset for the alignment. The transformation matrix used for the alignment can optionally be returned.

Note that the transformation is not unique, since the signs of the principal axes are arbitrary. Consequently, applying this filter to similar meshes may result in dissimilar alignment (for example, one axis may point up instead of down). To address this, the sign of one or two axes may optionally be “seeded” with a vector which approximates the axis or axes of the input. This can be useful for cases where the orientation of the input has a clear physical meaning.

Added in version 0.45.

Parameters:

centeredbool, default: True

Center the mesh at the origin. If False, the aligned dataset has the same center as the input.

axis_0_directionVectorLikeFloat | str, optional

Approximate direction vector of this mesh’s primary axis prior to alignment. If set, this axis is flipped such that it best aligns with the specified vector. Can be a vector or string specifying the axis by name (for example, 'x' or '-x', etc.).

axis_1_directionVectorLikeFloat | str, optional

Approximate direction vector of this mesh’s secondary axis prior to alignment. If set, this axis is flipped such that it best aligns with the specified vector. Can be a vector or string specifying the axis by name (for example, 'x' or '-x', etc.).

axis_2_directionVectorLikeFloat | str, optional

Approximate direction vector of this mesh’s third axis prior to alignment. If set, this axis is flipped such that it best aligns with the specified vector. Can be a vector or string specifying the axis by name (for example, 'x' or '-x', etc.).

cell_centersbool, default: False

Use the mesh’s cell_centers() when computing the principal_axes(). Points not associated with cells are treated as vertex cells. By default, the mesh’s points are used directly.

Added in version 0.48.

merge_pointsbool, default: False

Merge coincident points with merge_points() before computing the principal_axes(). Duplicate points can bias the principal axes, so enabling this can improve the alignment. By default the mesh’s points are used as-is.

Note

Points are only merged for the alignment. The points of the returned mesh are not merged.

Added in version 0.48.

return_matrixbool, default: False

Return the transform matrix as well as the aligned mesh.

Returns:

pyvista.DataSet

The dataset aligned to the x-y-z axes.

numpy.ndarray

Transform matrix to transform the input dataset to the x-y-z axes if return_matrix is True.

Examples

Download Python source code | Download Jupyter notebook

Create a dataset and align it to the x-y-z axes.

>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.download_oblique_cone()
>>> aligned = mesh.align_xyz()

Plot the aligned mesh along with the original. Show axes at the origin for context.

>>> axes = pv.AxesAssembly(scale=aligned.length)
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(aligned)
>>> _ = pl.add_mesh(mesh, style='wireframe', color='black', line_width=3)
>>> _ = pl.add_actor(axes)
>>> pl.show()

Static Scene

Interactive Scene

Align the mesh but don’t center it.

>>> aligned = mesh.align_xyz(centered=False)

Plot the result again. The aligned mesh has the same position as the input.

>>> axes = pv.AxesAssembly(position=mesh.center, scale=aligned.length)
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(aligned)
>>> _ = pl.add_mesh(mesh, style='wireframe', color='black', line_width=3)
>>> _ = pl.add_actor(axes)
>>> pl.show()

Static Scene

Interactive Scene

Note how the tip of the cone is pointing along the z-axis. This indicates that the cone’s axis is the third principal axis. It is also pointing in the negative z-direction. To control the alignment so that the cone points upward, we can seed an approximate direction specifying what “up” means for the original mesh in world coordinates prior to the alignment.

We can see that the cone is originally pointing downward, somewhat in the negative z-direction. Therefore, we can specify the '-z' vector as the “up” direction of the mesh’s third axis prior to alignment.

>>> aligned = mesh.align_xyz(axis_2_direction='-z')

Plot the mesh. The cone is now pointing upward in the desired direction.

>>> axes = pv.AxesAssembly(scale=aligned.length)
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(aligned)
>>> _ = pl.add_actor(axes)
>>> pl.show()

Static Scene

Interactive Scene

The specified direction only needs to be approximate. For example, we get the same result by specifying the 'y' direction as the mesh’s original “up” direction.

>>> aligned, matrix = mesh.align_xyz(axis_2_direction='y', return_matrix=True)
>>> axes = pv.AxesAssembly(scale=aligned.length)
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(aligned)
>>> _ = pl.add_actor(axes)
>>> pl.show()

Static Scene

Interactive Scene

We can optionally return the transformation matrix.

>>> aligned, matrix = mesh.align_xyz(axis_2_direction='y', return_matrix=True)

The matrix can be inverted, for example, to transform objects from the world axes back to the original mesh’s local coordinate system.

>>> inverse = pv.Transform(matrix).inverse_matrix

Use the inverse to label the object’s axes prior to alignment. For actors, we set the user_matrix as the inverse.

>>> axes_local = pv.AxesAssembly(
...     scale=aligned.length,
...     user_matrix=inverse,
...     labels=["X'", "Y'", "Z'"],
... )

Plot the original mesh with its local axes, along with the aligned mesh and its axes.

>>> axes_aligned = pv.AxesAssembly(scale=aligned.length)
>>> pl = pv.Plotter()
>>> # Add aligned mesh with axes
>>> _ = pl.add_mesh(aligned)
>>> _ = pl.add_actor(axes_aligned)
>>> # Add original mesh with axes
>>> _ = pl.add_mesh(mesh, style='wireframe', color='black', line_width=3)
>>> _ = pl.add_actor(axes_local)
>>> pl.show()

Static Scene

Interactive Scene

See Also

pyvista.principal_axes

Best-fit axes used by this filter for the alignment.

align

Align a source mesh to a target mesh using iterative closest point (ICP).