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.


Starting point for ruler.


Ending point for ruler.


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


Number of labels to place on ruler.

show_labelsbool, optional

Whether to show labels.


Factor to scale font size overall.


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.


Length of ticks in pixels.


Length of minor ticks in pixels.

show_ticksbool, optional

Whether to show the ticks.


Offset between tick and label in pixels.


VTK actor of the ruler.


>>> 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()