ROOT provides powerful graphics capabilities for displaying and interacting with graphical object like plots, histograms, 2D and 3D graphical objects, etc. Here the basic functions and principles are presented, which can be applied to graphs (→ see Graphs) and histograms (→ see Histograms).
The basic whiteboard on which an object is drawn is called in ROOT a canvas
TCanvas). A canvas is an area mapped to a window directly
under the control of the display manager.
A canvas contains one or more independent graphical areas: the pads
TPad). A pad is graphical entity that contains graphical
objects. A pad can contain other pads (unlimited pad hierarchy). A pad is a linked list of
primitives of any type (graphs, histograms, shapes, tracks, etc.).
Adding an element to a pad is done by the
Draw() method of each class.
Painting a pad is done by the automatic call to
Paint() method of each object in the list of primitives.
ROOT provides numerous graphic classes, of which the following are among the most used:
Working with graphics
ROOT offers many possibilities to work with graphics, for example:
- drawing objects
- drawing objects with special characters in its name
- using the context menu for manipulating objects
- using the Graphics Editor for objects
Most of the ROOT classes have a
Draw() method by which they can be “drawn” on a canvas
TCanvas class) that contain one or more pads
TPad class). When an object is drawn, you can interact with it.
- Use the
Draw()method to draw an object.
A one-dimensional sine function shall be drawn.
TF1 class to create an object that is a one-dimensional
function defined between a lower and upper limit.
The function is displayed in a canvas.
Figure: Canvas (point to the bottom left light blue square or right-click on the image to interact with the object).
Using the context menu for manipulating objects
Right-click on the function to display the context menu.
Figure: Context menu for manipulating objects.
Here you can change many properties of the object like title, name, range, line and fill attributes etc. For example, you can change the range by clicking
Figure: SetRange dialog window.
Select a range, for example 5, 25.
Figure: Range 5, 25 for sin(x).
Using the Graphics Editor for objects
You can edit an existing object in a canvas by right-clicking the object or by using the Graphics Editor.
- Click View and then select Editor.
Figure: Editor for setting attributes interactively.
You can draw and edit basic primitives starting from an empty canvas or on top of a picture. There is a toolbar that you can use to draw objects.
- Click View and then select Toolbar.
Figure: Toolbar providing more options.
This section lists some of the graphical objects that ROOT provides. Usually,
one defines these graphical objects with their constructor and draws them with their
- Lines: Use
TLineto create a line.
- Arrows: Use
TArrowto create an arrow.
- Polylines: Use
TPolyLineto create a polyline.
- Ellipses: Use
TEllipseto create an ellipse.
- Rectangles: Use
TWBoxto create a rectangle.
- Markers: Use
TMarkerto create a marker.
- Curly lines and arcs: Use
TCurlyArcto create curly lines and arcs for Feynman diagrams.
- Text and Latex: Use
TTextto draw simple text.
TLatexfor complex text like mathematical formulas. Text can be embedded in a box using
- and more …
Colors and color palettes
Colors are managed by the class
TColor. A color is defined by its
RGB or HLS components. It can be accessed via an
by name for the predefined colors.
Colors can be grouped in palettes. More
than 60 High quality palettes are predefined.
Color can also be transparent.
Graphical objects attributes and styles
There are the following classes for changing the attributes of graphical objects:
TAttFill : Used for filling an area with color and a style.
TAttLine : Used for setting the color, width and style of a line.
TAttMarker : Used for setting the color, size and style for a marker.
TAttText : Used for setting text attributes like alignment, angle, color, size and font.
Creating and modifying a style
When objects are created, their default attributes (taken from
are taken from the current style. The current style is
an object of the
TStyle class and can be referenced via the global
gStyle (→ see ROOT classes, data types and global variables).
ROOT provides several predefined styles.
Modern (used when ROOT starts).
Setting the current style
- Use the
SetStyle()method, to set the current style.
You can get a pointer to an existing style with:
When an object is created, its attributes are taken from the current style. For example, you may have created an histogram in a previous session and saved it in a ROOT file. Meanwhile, if you have changed the style, the histogram will be drawn with the old attributes. You can force the current style attributes to be set when you read an object from a file by:
Creating additional styles
- Use the
TStyleconstructor to create additional styles.
Getting the attributes of the current style
You can force objects (in a canvas or pad) to get the attributes of the current style.
Axis are automatically built in by various high level objects such as histograms or graphs.
TAxis manages the axis and is referenced by
To make a graphical representation of an histogram axis,
- Use the
GetZaxis()methods to get the axis for an histogram or graph.
Setting the axis title
- Use the
SetTitle()method to set the title of an axis.
If the axis is embedded into a histogram or a graph, you first have to extract the axis object.
Setting axis attributes
The axis graphical attributes are managed via the class
Setting the number of divisions
- Use the
SetNdivisionsmethod to set the number of divisions for an axis.
Several axis’ attributes can be changed. For instance the size, the distance to the axis, the alignment etc …
SetMaxDigits() set the maximum number of digits permitted for the axis labels above which the notation with $10^N$ is used.
Labels can also be tuning individually thanks to ChangeLabel().
Setting the axis range
- Use TAxis::SetRange() or TAxis::SetRangeUser() to zoom the axis.
SetRange() method parameters are bin numbers. For example if a histogram plots the
values from 0 to 500 and has 100 bins,
SetRange(0,10) will cover the values 0 to 50.
SetRangeUser() method parameters are user coordinates. If the start or end is in the
middle of a bin the resulting range is approximation. It finds the low edge bin for the
start and the high edge bin for the high.
For a general description see the “How to set ranges on axis” FAQ.
Setting time units for axis
Axis can be labeled with time and date. Such axis are called “Time axis”. A detailed description is given in the TGaxis reference page.
Basically three methods allow to manage such axis:
SetTimeDisplay()to set an axis as a time axis.
SetTimeFormat()to define the format used for time plotting.
SetTimeOffset()to change the time offset.
Figure: A simple time axis with day and hour.
Drawing an axis independently of a graph or a histogram
- Use the
TGaxisclass to draw an axis independently of a graph or a histogram.
This may be useful if you want to draw a supplementary axis for a plot.
A legend is almost always present on a plot. ROOT provides an easy to use tool allowing a direct link between the legend drawn and the legended objects. Therefore, when one of the object attributes is changed, the legend is automatically changed also.
- Use the
TLegendclass to add a legend to graph.
TLegend is a panel with several entries (
The method BuildLegend
automatically build a
TLegend with all the objects present
Canvas and pad
A canvas (
TCanvas) is a graphical entity that contains graphical objects that are called
TPad). A pad is a graphical container that contains other graphical objects like histograms and arrows. It also can contain other pads, called sub-pads. When an object is drawn, it is always in the so-called active pad.
Accessing the active pad
- Use the global variable
gPadto access the active pad.
For more information on global variables, → see ROOT classes, data types and global variables.
If you want to change the fill color of the active pad to blue, but you do not know the name of the active pad, you can use
Accessing an object in an active pad
- Use the TPad::GetPrimitive(const char* name) method to access an object in an active pad.
A pointer to the object
myobjectname is returned and put into the
The type of the returned pointer is a
TObject* that has a name.
Hiding an object in a pad
You can hide an object in a pad by removing it from the list of objects owned by that pad.
Use the TPad::GetListOfPrimitives() method to list is accessible objects of a pad.
Remove()method to remove the object from the list.
First, a pointer to the object is needed.
Second, a pointer to the list of objects owned by the pad is needed.
Then you can remove the object from the list, i.e. pad.
The object disappears as soon as the pad is updated.
Updating a pad
For performance reasons, a pad is not updated with every change. Instead, the pad has a “bit-modified” that triggers a redraw.
The “bit-modified” is automatically set by:
touching the pad with the mouse, for example by resizing it with the mouse,
finishing the execution of a script,
adding or modifying primitives, for example the name and title of an object.
You can set the “bit-modified” by using the
A subsequent call to TCanvas::Update() scans the list of sub-pads and repaints the pads.
Dividing a pad into sub-pads
To draw multiple objects on a
TCanvas), you can it into sub-pads (
There are two ways to divide a pad into sub-pads:
automatically divide a pad into horizontal and vertical sub-pads.
Creating a single sub-pad
To build sub-pads in a pad, you must indicate the size and the position of the sub-pads.
A sub-pad is to be built into the active pad (pointed by
gPad). First, the sub-pad is
build using the
The NDC (normalized coordinate system) coordinates are specified for the lower left point
(0.1, 0.1) and for the upper right point
Then the sub-pad is drawn.
For building more sub-pads, repeat this procedure as many times as necessary.
Dividing a pad into sub-pads
- Use the TPad::Divide() method to divide a pad into sub-pads.
Coordinate systems of a pad
TPad the following coordinate systems are available:
You can convert from one system of coordinates to another.
User coordinate system
Most methods of
user coordinates are set to a range from 0 to 1 starting at the lower left corner.
- Use the TPad::range(float x1,float y1,float x2,float y2) method to set the user coordinate system.
x2define the new range in the x direction, and
y2define the new range in the y direction.
Both coordinates go from -100 to 100, with the center of the pad at (0,0).
Normalized coordinate system (NDC)
Normalized coordinates are independent of the window size and of the user system. The coordinates range from 0 to 1 and (0, 0) correspond to the bottom-left corner of the pad.
Pixel coordinate system
The pixel coordinate system is used by functions such as
ExecuteEvent(). Its primary use is for cursor position, which is always given in pixel coordinates. If (
py) is the
py=0 corresponds to the top-left corner of the pad, which is the standard convention in windowing systems.
Converting between coordinate systems
TPad provides some methods to convert from one system of coordinates to another.
In the following table, a point is defined by:
(px,py)in pixel coordinates,
(ux,uy)in user coordinates,
(ndcx,ndcy)in normalized coordinates,
(apx, apy)in absolute pixel coordinates.
|Conversion||Methods (from TPad)||Returns|
|NDC to pixel||UtoPixel(ndcx)||Int_t|
|Pixel to user||PixeltoX(px)||Double_t|
|User to pixel||XtoPixel(ux)||Int_t|
|User to absolute pixel||XtoAbsPixel(ux)||Int_t|
|Absolute pixel to user||AbsPixeltoX(apx)||Double_t|
All the pixel conversion functions along the Y axis consider that
py=0is at the top of the pad except
PixeltoY(), which assumes that the position
py=0is at the bottom of the pad. To make
PixeltoY()converting the same way as the other conversion functions, it should be used the following way (
pis a pointer to a
Setting the Log Scale
Setting the scale to logarithmic or linear is a pad’s attribute because you may want to draw the same histogram in linear scale in one pad and in log scale in another pad. Setting log scale does not propagate to sub-pads.
TPad defines log scale
for the three directions
Copying a canvas
- Use the TCanvas::DrawClonePad method to make a copy of the canvas.
You can also use the TObject:DrawClone() method, to draw a clone of this object in the current selected pad.
Printing a canvas
Once a canvas is created and shows plots ready to be included in a publication as a
Drawing objects with special characters in its name
In general, avoid using objects that containing special character like
# etc. in the objects names. Also object names starting with a number might be not accessible from the ROOT command line.
/ is the separator for the directory level in a ROOT file therefore an object having a
/ in its name cannot be accessed from the command line.
Nevertheless, some objects may be named in this way and saved in a ROOT file. The following macro shows how to access such an object in a ROOT file.
3D graphics tools for “Event Display”, “Basic 3D” and OPen GL rendering are provided.→ Geometry tutorials
→ OpenGL tutorials