<!-- TGaxis.md --- 
;; 
;; Description: 
;; Author: Hongyi Wu(吴鸿毅)
;; Email: wuhongyi@qq.com 
;; Created: 二 11月  1 16:41:34 2016 (+0800)
;; Last-Updated: 三 9月 16 12:47:24 2020 (+0800)
;;           By: Hongyi Wu(吴鸿毅)
;;     Update #: 4
;; URL: http://wuhongyi.cn -->

# TGaxis*

继承 TLine, TAttText

Service class for the graphical representation of axis.


Instances of this class are generated by the histograms and graphs painting
classes when TAxis are drawn. TGaxis is the "painter class"of
TAxis. Therefore it is mainly used via TAxis` even if is some
occasion  it can be used directly to draw an axis which is not part of a graph
or an instance. For instance to draw an extra scale on a plot.

- Basic definition
- Definition with a function
- Logarithmic axis
- Blank axis
- Tick marks' orientation
- Tick marks' size
- Labels' positionning
- Labels' orientation
- Labels' position on tick marks
- Labels' format
- Alphanumeric labels
- Number of divisions optimisation
- Maximum Number of Digits for the axis labels
- Optional grid
- Time axis

### Logarithmic axis

By default axis are linear. To define a TGaxis as logarithmic, it is
enough to create it with the option "G".

When plotting an histogram or a graph the logarithmic scale can be set using:

  - gPad->SetLogx(1); set the logarithmic scale on the X axis
  - gPad->SetLogy(1); set the logarithmic scale on the Y axis

When the SetMoreLogLabels() method is called more labels are drawn
when in logarithmic scale and there is a small number of decades  (less than 3).

### Tick marks' orientation

By default tick marks are drawn on the positive side of the axis, except for
vertical axis for which the default is negative. The chop parameter
allows to control the tick marks orientation:

  - chopt = "+":  tick marks are drawn on Positive side. (default)
  - chopt ="-":   tick mark are drawn on the negative side.
  - chopt = "+-": tick marks are drawn on both sides of the axis.
  - chopt = "U":  Unlabelled axis, default is labeled.


### Tick marks' size

By default, tick marks have a length equal to 3 per cent of the axis length.
When the option "S" is specified, the length of the tick marks is equal to
fTickSize*axis_length, where fTickSize may be set via TGaxis::SetTickSize.

When plotting an histogram **h** the tick marks size can be changed using:

  - h->GetXaxis()->SetTickLength(0.02); set the tick length for the X axis
  - gStyle->SetTickLength(0.02,"x"); set the tick length for the X axis
     of all histograms drawn after this instruction.

A good way to remove tick marks on an axis is to set the tick length to 0:
h->GetXaxis()->SetTickLength(0.);


### Labels' positionning

Labels are normally drawn on side opposite to tick marks. However the option
"=" allows to draw them on the same side.

### Labels' orientation

By default axis labels are drawn parallel to the axis. However if the axis is vertical
then are drawn perpendicular to the axis.

### Labels' position on tick marks

By default axis labels are centered on tick marks. However, for vertical axis,
they are right adjusted. The chop parameter allows to control the labels'
position on tick marks:

  - chopt = "R": labels are Right adjusted on tick mark.(default is centered)
  - chopt = "L": labels are Left adjusted on tick mark.
  - chopt = "C": labels are Centered on tick mark.
  - chopt = "M": In the Middle of the divisions.

### Labels' format

Blank characters are stripped, and then the label is correctly aligned. the dot,
if last character of the string, is also stripped, unless the option "."
(a dot, or period) is specified. if SetDecimals(kTRUE) has been called
all labels have the same number of decimals after the "."
The same is true if gStyle->SetStripDecimals(kFALSE) has been called.

In the following, we have some parameters, like tick marks length and characters
height (in percentage of the length of the axis (user's coordinates))
The default values are as follows:

  - Primary tick marks: 3.0 %
  - Secondary tick marks: 1.5 %
  - Third order tick marks: .75 %
  - Characters height for labels: 4%
  - Labels offset: 1.0 %

By default, an exponent of the form 10^N is used when the label values are either
all very small or very large. One can disable the exponent by calling
axis.SetNoExponent(kTRUE).

TGaxis::SetExponentOffset(Float\_t xoff, Float\_t yoff, Option\_t *axis) is
static function to set X and Y offset of the axis 10^n notation. It is in % of
the pad size. It can be negative. **axis** specifies which axis
("x" or/and "y"), default is "x" if axis = "xz"
set the two axes


### Alphanumeric labels

Axis labels can be any alphanumeric character strings. Such axis can be produced
only with histograms because the labels'definition is stored in TAxis.

Because the alphanumeric labels are usually longer that the numeric labels, their
size is by default equal to "0.66666 * the\_numeric\_labels\_size".


### Number of divisions optimisation

By default the number of divisions on axis is optimised to show a coherent
labelling of the main tick marks. The number of division (ndiv) is a
composite integer given by:
```
 ndiv = N1 + 100*N2 + 10000*N3
```
  - N1 = number of 1st divisions.
  - N2 = number of 2nd divisions.
  - N3 = number of 3rd divisions.

by default the value of N1, N2 and N3 are maximum
values. After optimisation the real number of divisions will be smaller or
equal to these value. If one wants to bypass the optimisation, the option "N"
should be given when the TGaxis is created. The option  "I"
also act on the number of division as it will force an integer labelling of
the axis.

On an histogram pointer **h** the number of divisions can be set in different ways:.

- Directly on the histogram. The following will set the number of division
  to 510 on the X axis of **h**. To avoid optimization the number of divisions
  should be negative (ie: -510);
```cpp
    h->SetNdivisions(510, "X");
```
- On the axis itself:
```cpp
    h->GetXaxis()->SetNdivisions(510, kTRUE);
```

The first parameter is the number of division. If it is negative of if the
second parameter is kFALSE then the number of divisions is not optimised.
And other signature is also allowed:
```cpp
    h->GetXaxis()->SetNdivisions(10, 5, 0, kTRUE);
```


### Maximum Number of Digits for the axis labels

The static function TGaxis::SetMaxDigits sets the maximum number of
digits permitted for the axis labels above which the notation with 10^N is used.
For example, to accept 6 digits number like 900000 on an axis call
TGaxis::SetMaxDigits(6). The default value is 5.
fgMaxDigits must be greater than 0.


### Optional grid

The option "W" allows to draw a grid on the primary tick marks. In case
of a log axis, the grid is only drawn for the primary tick marks if the number
of secondary and tertiary divisions is 0. SetGridLength() allows to define
the length of the grid.

When plotting an histogram or a graph the grid can be set ON or OFF using:

  - gPad->SetGridy(1); set the grid on the X axis
  - gPad->SetGridx(1); set the grid on the Y axis
  - gPad->SetGrid(1,1); set the grid on both axis.


### Time axis

Axis labels may be considered as times, plotted in a defined time format.
The format is set with SetTimeFormat().
The TGaxis minimum (wmin) and maximum (wmax) values
are considered as two time values in seconds.
The time axis will be spread around the time offset value (set with
SetTimeOffset()). Actually it will go from "TimeOffset+wmin" to
"TimeOffset+wmax"

Usually time axis are created automatically via histograms, but one may also
want to draw a time axis outside an "histogram context". This can be done
thanks to the option "T" of TGaxis.


## class

```cpp
   TGaxis();
   TGaxis(Double_t xmin,Double_t ymin,Double_t xmax,Double_t ymax,
          Double_t wmin,Double_t wmax,Int_t ndiv=510, Option_t *chopt="",
          Double_t gridlength = 0);
// Where:
// - xmin : X origin coordinate in user's coordinates space.
// - xmax : X end axis coordinate in user's coordinates space.
// - ymin : Y origin coordinate in user's coordinates space.
// - ymax : Y end axis coordinate in user's coordinates space.
// - wmin : Lowest value for the tick mark labels written on the axis.
// - wmax : Highest value for the tick mark labels written on the axis.
// - ndiv : Number of divisions.
//    - ndiv=N1 + 100*N2 + 10000*N3
//    - N1=number of 1st divisions.
//    - N2=number of 2nd divisions.
//    - N3=number of 3rd divisions. e.g.:
//       - ndiv=0 --> no tick marks.
//       - ndiv=2 --> 2 divisions, one tick mark in the middle of the axis.
// - chopt : Drawing options (see below).
// - gridlength: grid length on main tick marks.

   TGaxis(Double_t xmin,Double_t ymin,Double_t xmax,Double_t ymax,
          const char *funcname, Int_t ndiv=510, Option_t *chopt="",
          Double_t gridlength = 0);
   virtual ~TGaxis();

   virtual void        AdjustBinSize(Double_t A1,  Double_t A2,  Int_t nold
                                    ,Double_t &BinLow, Double_t &BinHigh, Int_t &nbins, Double_t &BinWidth);
/// Internal method for axis labels optimisation. This method adjusts the bining
/// of the axis in order to have integer values for the labels.
/// \param[in]  A1,A2            Old WMIN,WMAX
/// \param[out] binLow,binHigh   New WMIN,WMAX
/// \param[in]  nold             Old NDIV (primary divisions)
/// \param[out] nbins            New NDIV
/// \param[out] binWidth         Bin width

   virtual void        CenterLabels(Bool_t center=kTRUE);
/// If center = kTRUE axis labels are centered in the center of the bin.
/// The default is to center on the primary tick marks.
/// This option does not make sense if there are more bins than tick marks.

   virtual void        CenterTitle(Bool_t center=kTRUE);/// If center = kTRUE axis title will be centered. The default is right adjusted.
   virtual void        DrawAxis(Double_t xmin,Double_t ymin,Double_t xmax,Double_t ymax,
                                Double_t wmin,Double_t wmax,Int_t ndiv=510, Option_t *chopt="",
                                Double_t gridlength = 0);/// Draw this axis with new attributes.
   Float_t             GetGridLength() const   {return fGridLength;}
   TF1                *GetFunction() const     {return fFunction;}
   Int_t               GetLabelColor() const   {return fLabelColor;}
   Int_t               GetLabelFont() const    {return fLabelFont;}
   Float_t             GetLabelOffset() const  {return fLabelOffset;}
   Float_t             GetLabelSize() const    {return fLabelSize;}
   Float_t             GetTitleOffset() const  {return fTitleOffset;}
   Float_t             GetTitleSize() const    {return fTitleSize;}
   virtual const char *GetName() const  {return fName.Data();}
   virtual const char *GetOption() const {return fChopt.Data();}
   virtual const char *GetTitle() const {return fTitle.Data();}
   static Int_t        GetMaxDigits();/// Static function returning fgMaxDigits (See SetMaxDigits).
   Int_t               GetNdiv() const         {return fNdiv;}
   Double_t            GetWmin() const         {return fWmin;}
   Double_t            GetWmax()  const        {return fWmax;}
   Float_t             GetTickSize() const     {return fTickSize;}
   virtual void        ImportAxisAttributes(TAxis *axis);/// Internal method to import TAxis attributes to this TGaxis.
   void                LabelsLimits(const char *label, Int_t &first, Int_t &last);/// Internal method to find first and last character of a label.
   virtual void        Paint(Option_t *chopt="");/// Draw this axis with its current attributes.
   virtual void        PaintAxis(Double_t xmin,Double_t ymin,Double_t xmax,Double_t ymax,
                                 Double_t &wmin,Double_t &wmax,Int_t &ndiv, Option_t *chopt="",
                                 Double_t gridlength = 0, Bool_t drawGridOnly = kFALSE);/// Control function to draw an axis.
   virtual void        Rotate(Double_t X,  Double_t Y,  Double_t CFI, Double_t SFI
                             ,Double_t XT, Double_t YT, Double_t &U,   Double_t &V);///    Internal method to rotate axis coordinates.
   virtual void        SavePrimitive(std::ostream &out, Option_t *option = "");/// Save primitive as a C++ statement(s) on output stream out
   void                SetFunction(const char *funcname="");/// Specify a function to map the axis values.
   void                SetOption(Option_t *option="");/// To set axis options.
   void                SetLabelColor(Int_t labelcolor) {fLabelColor = labelcolor;} // *MENU*
   void                SetLabelFont(Int_t labelfont) {fLabelFont = labelfont;} // *MENU*
   void                SetLabelOffset(Float_t labeloffset) {fLabelOffset = labeloffset;} // *MENU*
   void                SetLabelSize(Float_t labelsize) {fLabelSize = labelsize;} // *MENU*
   static void         SetMaxDigits(Int_t maxd=5);
/// Static function to set `fgMaxDigits` for axis.`fgMaxDigits` is
/// the maximum number of digits permitted for the axis labels above which the
/// notation with 10^N is used.For example, to accept 6 digits number like 900000
/// on an axis call `TGaxis::SetMaxDigits(6)`. The default value is 5.
/// `fgMaxDigits` must be greater than 0.

   virtual void        SetName(const char *name); // *MENU* /// Change the name of the axis.
   virtual void        SetNdivisions(Int_t ndiv) {fNdiv = ndiv;} // *MENU*
   virtual void        SetMoreLogLabels(Bool_t more=kTRUE);  // *MENU*
/// Set the kMoreLogLabels bit flag. When this option is selected more labels are
/// drawn when in logarithmic scale and there is a small number of decades (less than 3).
/// Note that this option is automatically inherited from TAxis

   virtual void        SetNoExponent(Bool_t noExponent=kTRUE);  // *MENU*
/// Set the NoExponent flag. By default, an exponent of the form 10^N is used
/// when the label values are either all very small or very large. One can disable
/// the exponent by calling axis.SetNoExponent(kTRUE).

   virtual void        SetDecimals(Bool_t dot=kTRUE);  // *MENU*
/// Set the decimals flag. By default, blank characters are stripped, and then the
/// label is correctly aligned. The dot, if last character of the string, is also
/// stripped, unless this option is specified. One can disable the option by
/// calling `axis.SetDecimals(kTRUE)`.
/// Note the bit is set in fBits (as opposed to fBits2 in TAxis!)

   void                SetTickSize(Float_t ticksize) {fTickSize = ticksize;} // *MENU*
   void                SetTickLength(Float_t ticklength) {SetTickSize(ticklength);}
   void                SetGridLength(Float_t gridlength) {fGridLength = gridlength;}
   void                SetTimeFormat(const char *tformat);
/// Change the format used for time plotting.
/// The format string for date and time use the same options as the one used
/// in the standard strftime C function, i.e. :
/// for date :
///  - `%a` abbreviated weekday name
///  - `%b` abbreviated month name
///  - `%d` day of the month (01-31)
///  - `%m` month (01-12)
///  - `%y` year without century
/// for time :
///  - `%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)
///  - `%%` %

   void                SetTimeOffset(Double_t toffset, Option_t *option="local");
   virtual void        SetTitle(const char *title=""); // *MENU* /// Change the title of the axis.
   void                SetTitleOffset(Float_t titleoffset=1) {fTitleOffset = titleoffset;} // *MENU*
/// Change the time offset. If option = "gmt", set display mode to GMT.

   void                SetTitleSize(Float_t titlesize) {fTitleSize = titlesize;} // *MENU*
   void                SetTitleFont(Int_t titlefont) {SetTextFont(titlefont);} // *MENU*
   void                SetTitleColor(Int_t titlecolor) {SetTextColor(titlecolor);} // *MENU*
   void                SetWmin(Double_t wmin) {fWmin = wmin;}
   void                SetWmax(Double_t wmax) {fWmax = wmax;}
   static void         SetExponentOffset(Float_t xoff=0., Float_t yoff=0., Option_t *axis="xy");
/// Static function to set X and Y offset of the axis 10^n notation.
/// It is in % of the pad size. It can be negative.
/// axis specifies which axis ("x","y"), default = "x"
/// if axis="xz" set the two axes   
```


## code

```cpp
// Instead of the wmin,wmax arguments of the normal definition, the
// name of a TF1 function can be specified. This function will be used to
// map the user coordinates to the axis values and ticks.

   TCanvas *c2 = new TCanvas("c2","c2",10,10,700,500);

   gStyle->SetOptStat(0);

   TH2F *h2 = new TH2F("h","Axes",100,0,10,100,-2,2);
   h2->Draw();

   TF1 *f1=new TF1("f1","-x",-10,10);
   TGaxis *A1 = new TGaxis(0,2,10,2,"f1",510,"-");
   A1->SetTitle("axis with decreasing values");
   A1->Draw();

   TF1 *f2=new TF1("f2","exp(x)",0,2);
   TGaxis *A2 = new TGaxis(1,1,9,1,"f2");
   A2->SetTitle("exponential axis");
   A2->SetLabelSize(0.03);
   A2->SetTitleSize(0.03);
   A2->SetTitleOffset(1.2);
   A2->Draw();

   TF1 *f3=new TF1("f3","log10(x)",1,1000);
   TGaxis *A3 = new TGaxis(2,-2,2,0,"f3",505,"G");
   A3->SetTitle("logarithmic axis");
   A3->SetLabelSize(0.03);
   A3->SetTitleSize(0.03);
   A3->SetTitleOffset(1.2);
   A3->Draw();
   return c2;
```

```cpp
   c1 = new TCanvas("c1","Examples of TGaxis",10,10,700,100);
   c1->Range(-10,-1,10,1);

   TGaxis *axis = new TGaxis(-8,0.,8,0.,-100000,150000,2405,"tS");
   axis->SetLabelSize(0.3);
   axis->SetTickSize(0.2);

   TDatime da(2003,02,28,12,00,00);
   axis->SetTimeOffset(da.Convert());
   axis->SetTimeFormat("%d-%m-%Y");
   axis->Draw();
   return c1;
```


# example

```cpp
// The example below generates various kind of axis.

   TCanvas *c1 = new TCanvas("c1","Examples of TGaxis",10,10,700,500);

   c1->Range(-10,-1,10,1);

   TGaxis *axis1 = new TGaxis(-4.5,-0.2,5.5,-0.2,-6,8,510,"");
   axis1->SetName("axis1");
   axis1->Draw();

   TGaxis *axis2 = new TGaxis(-4.5,0.2,5.5,0.2,0.001,10000,510,"G");
   axis2->SetName("axis2");
   axis2->Draw();

   TGaxis *axis3 = new TGaxis(-9,-0.8,-9,0.8,-8,8,50510,"");
   axis3->SetName("axis3");
   axis3->Draw();

   TGaxis *axis4 = new TGaxis(-7,-0.8,-7,0.8,1,10000,50510,"G");
   axis4->SetName("axis4");
   axis4->Draw();

   TGaxis *axis5 = new TGaxis(-4.5,-0.6,5.5,-0.6,1.2,1.32,80506,"-+");
   axis5->SetName("axis5");
   axis5->SetLabelSize(0.03);
   axis5->SetTextFont(72);
   axis5->SetLabelOffset(0.025);

   axis5->Draw();

   TGaxis *axis6 = new TGaxis(-4.5,0.6,5.5,0.6,100,900,50510,"-");
   axis6->SetName("axis6");
   axis6->Draw();

   TGaxis *axis7 = new TGaxis(8,-0.8,8,0.8,0,9000,50510,"+L");
   axis7->SetName("axis7");
   axis7->SetLabelOffset(0.01);
   axis7->Draw();

   //one can make axis going top->bottom. However because of a long standing
   //problem, the two x values should not be equal
   TGaxis *axis8 = new TGaxis(6.5,0.8,6.499,-0.8,0,90,50510,"-");
   axis8->SetName("axis8");
   axis8->Draw();
   return c1;
```


<!-- TGaxis.md ends here -->