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
). 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 (class 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
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
class has the virtual method
Draw() by which objects can be “drawn”.
The object is “drawn” on a canvas (TCanvas
class) that contain
one or more pads (TPad
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.
Use the 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).
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.
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.
You can create the following graphical objects:
- Arc of circle
- PaveText or PavesText
- Text string
The following sections introduce some of the graphical objects that ROOT provides. Usually, one defines these
graphical objects with their constructor and draws them with their
The following graphical objects are presented:
- Use the TLine constructor to create a line.
y2 are the coordinates of the first and the second point.
- Use the TArrow constructor to create an arrow.
The arrow is defined between points
option defines the direction of the arrow like
Figure: Examples of various arrow formats.
A polyline is a set of joint segments. It is defined by a set of N points in a 2D-space.
- Use the TPolyLine constructor to create a polyline.
n is the number of points, and
y are arrays of
n elements with the coordinates of the points.
Figure: Example for a polyline.
- Use the TEllipse constructor to create an ellipse.
You can truncate and rotate an ellipse. An ellipse is defined by its center (
y1) and two radii
r2. A minimum and
maximum angle may be specified (
phimax). The ellipse may be rotated with an angle
theta (all in degrees).
Figure: Examples for a ellipses.
- Use the TBox constructor to create a rectangle/box.
- Use the TMarker constructor to create a marker.
y are the marker coordinates and
marker is the marker type.
- Use the TPolyMarker to create an array on N points in a 2D space.
At each point
y[i] a marker is drawn.
- Use the TAttMarker class to change the attributes color, style and size of a marker.
- Use the
TAttMarker::SetMarkerSize(size)method to set the
sizeof a marker.
Curly lines and arcs
Curly lines and the curly arcs are special kinds of lines that are used to draw Feynman diagrams.
- Use the TCurlyLine and the TCurlyArc constructors to create curly lines and arcs for Feynman diagrams.
Both classes directly inherit from TPolyLine .
Refer to the
$ROOTSYS/tutorials/graphics/feynman.C tutorial for creating a Feynman diagram.
Figure: Feynman diagram.
Text and Latex
Figure: Latex in a pad.
Graphical objects attributes and styles
There are the following classes for changing the attributes of graphical objects:
- Used for filling an area with color and a style.
- Used for setting the color, width and style of a line.
- Used for setting the styles for a marker.
- Used for setting text attributes like alignment, color, size, font etc.
Creating and modifying a style
When objects are created, their default attributes (taken from TAttFill
are taken from the current style. The current style is an object of the
class and can be referenced via the global variable
(→ see ROOT classes, data types and global variables).
ROOT provides two styles:
Default style is created by:
Plain style is useful if you, for example, are working on a monochrome display.
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 TStyle constructor 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 TH1 and TGraph . To make a graphical representation of an histogram axis, TAxis references the TGaxis class.
- Use the
GetZaxis()methods to get the axis for an histogram or graph.
Setting the axis title
- Use the
SetTitle()method to set the tile of an axis.
If the axis is embedded into a histogram or a graph, you first have to extract the axis object.
Setting axis options and characteristics
The available axis options are listed in the following example.
Setting the number of divisions
- Use the
TAxis::SetNdivisions(ndiv,optim)method to set the number of divisions for an axis.
optim are defined as follows:
ndiv = N1 + 100*N2 + 10000*N3, with:
N1= number of first division,
N2= number of secondary divisions,
N3= number of tertiary divisions.
kTRUE (default): The divisions’ number will be optimized around the specified value.
kFALSE, or n < 0: The axis will be forced to use exactly n divisions.
ndiv = 0: no tick marks.
ndiv = 2: 2 divisions, one tick mark in the middle of the axis.
ndiv = 510: 10 primary divisions, 5 secondary divisions.
ndiv = -10: exactly 10 primary divisions.
Zooming 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.
Setting time units for axis
- Use the
SetTimeDisplay()method to set an axis as a time axis.
For a histogram
histo, the x-axis is set as time axis.
For a time axis, you can set the
The time format defines the format of the labels along the time axis. It can be changed using the
TAxis::SetTimeFormat() method. The time format used if from the C function
It is a string containing the following formatting characters,
%a: abbreviated weekday name
%b: abbreviated month name
%d: day of the month (01-31)
%m: month (01-12)
%y: year without century
%Y: year with century
%H: hour (24-hour clock)
%I: hour (12-hour clock)
%p: local equivalent of AM or PM
%M: minute (00-59)
%S: seconds (00-61)
The other characters are output as is. For example to have a format like
The time is a time in seconds in the UNIX standard UTC format (this is an universal time, not the local time), defining the starting date of an histogram axis. This date should be greater than 01/01/95 and is given in seconds.
There are the three ways to define the time offset:
- Setting the global default time offset.
Notice the usage of
TDateTime to translate an explicit date into the time in seconds required by
If no time offset is defined for a particular axis, the default time offset will be used.
- Setting a time offset to a particular axis.
SetTimeFormattogether with the time format
The time offset can be specified using the control character
%F after the normal time format.
%F is followed by the date in the format: yyyy-mm-dd hh:mm:ss.
Notice that this date format is the same used by the
TDateString function AsSQLString. If needed, this function can be used to translate a time in seconds into a character string which can be appended after
%F. If the time format is not specified (before
%F), the automatic one will be used.
If a time axis has no specified time offset, the global time offset will be stored in the axis data structure.
Figure: Time axis.
Drawing an axis independently of a graph/histogram
- Use the TGaxis class 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 graph.
- Use the TLegend class to add a legend to graph.
A legend is defined with default coordinates, border size and option. The legend coordinates (NDC) in the current pad are
y2. The default text attributes for the legend are:
- Alignment = 12 left adjusted and vertically centered
- Angle = 0 (degrees)
- Color = 1 (black)
- Size = calculate when number of entries is known
- Font = helvetica-medium-r-normal scalable font = 42, and bold = 62 for title
The title is a regular entry and supports TLatex . The default is no title (header = 0).
- Use the AddEntry() method to a add a new entry to a legend.
The parameters are:
*objisa pointer to an object having a marker, a line, or a fill attributes (a histogram, or a graph).
labelis the label to be associated to the object.
The following legend contains a histogram, a function and a graph. The histogram is put in the legend using its reference pointer whereas the graph and the function are added using their names. Because TGraph
constructors do not have the TGraph
name as parameter, the graph name should be specified using the
Figure: Legend containing a histogram, a function and a graph.
Canvas and pad
A canvas (TCanvas ) is a graphical entity that contains graphical objects that are called pads (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 point 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 pas 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
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 the TPad
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
For a TPad the following coordinate systems are available:
You can convert from one system of coordinates to another.
User coordinate system
- 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 TPad ):
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.