add_ruler#

Plotter.add_ruler(pointa, pointb, flip_range=False, number_labels=5, show_labels=True, font_size_factor=0.6, label_size_factor=1.0, label_format=None, title='Distance', number_minor_ticks=0, tick_length=5, minor_tick_length=3, show_ticks=True, tick_label_offset=2)#

Add ruler.

The ruler is a 2D object that is not occluded by 3D objects. To avoid issues with perspective, it is recommended to use parallel projection, i.e. Plotter.enable_parallel_projection(), and place the ruler orthogonal to the viewing direction.

The title and labels are placed to the right of ruler moving from pointa to pointb. Use flip_range to flip the 0 location, if needed.

Since the ruler is placed in an overlay on the viewing scene, the camera does not automatically reset to include the ruler in the view.

Parameters
pointaSequence

Starting point for ruler.

pointbSequence

Ending point for ruler.

flip_rangebool

If True, the distance range goes from pointb to pointa.

number_labelsint

Number of labels to place on ruler.

show_labelsbool, optional

Whether to show labels.

font_size_factorfloat

Factor to scale font size overall.

label_size_factorfloat

Factor to scale label size relative to title size.

label_formatstr, optional

A printf style format for labels, e.g. ā€˜%Eā€™.

titlestr, optional

The title to display.

number_minor_ticksint, optional

Number of minor ticks between major ticks.

tick_lengthint

Length of ticks in pixels.

minor_tick_lengthint

Length of minor ticks in pixels.

show_ticksbool, optional

Whether to show the ticks.

tick_label_offsetint

Offset between tick and label in pixels.

Returns
vtk.vtkActor

VTK actor of the ruler.

Examples

>>> import pyvista
>>> cone = pyvista.Cone(height=2.0, radius=0.5)
>>> plotter = pyvista.Plotter()
>>> _ = plotter.add_mesh(cone)

Measure x direction of cone and place ruler slightly below.

>>> _ = plotter.add_ruler(
...     pointa=[cone.bounds[0], cone.bounds[2] - 0.1, 0.0],
...     pointb=[cone.bounds[1], cone.bounds[2] - 0.1, 0.0],
...     title="X Distance"
... )

Measure y direction of cone and place ruler slightly to left. The title and labels are placed to the right of the ruler when traveling from pointa to pointb.

>>> _ = plotter.add_ruler(
...     pointa=[cone.bounds[0] - 0.1, cone.bounds[3], 0.0],
...     pointb=[cone.bounds[0] - 0.1, cone.bounds[2], 0.0],
...     flip_range=True,
...     title="Y Distance"
... )
>>> plotter.enable_parallel_projection()
>>> plotter.view_xy()
>>> plotter.show()
../../../_images/pyvista-Plotter-add_ruler-1_00_00.png