pyvista.DataSetFilters.align_xyz#
- DataSetFilters.align_xyz(
- *,
- centered: bool = True,
- axis_0_direction: VectorLike[float] | str | None = None,
- axis_1_direction: VectorLike[float] | str | None = None,
- axis_2_direction: VectorLike[float] | str | None = None,
- return_matrix: bool = False,
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 (e.g. 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_direction
VectorLike
[float
] |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 (e.g.
'x'
or'-x'
, etc.).- axis_1_direction
VectorLike
[float
] |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 (e.g.
'x'
or'-x'
, etc.).- axis_2_direction
VectorLike
[float
] |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 (e.g.
'x'
or'-x'
, etc.).- return_matrixbool, default:
False
Return the transform matrix as well as the aligned mesh.
- centeredbool, default:
- 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
isTrue
.
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).
Examples
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()
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()
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()
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()
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 algned 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()