$Id$

///\file "field/BlineTracer/.README.txt"
///\brief Example BlineTracer README page

/*! \page ExampleBlineTracer Example BlineTracer

\author Laurent Desorgher (desorgher@phim.unibe.ch) - 04/10/2003

The BlineTracer module allows to trace and visualise magnetic field 
lines in a Geant4 application where particle are tracked through the
magnetic field (in future, these functionalities may be integrated in
the Geant4 kernel).

To use the tracer, the user should copy the classes provided here in
his/her own application/example and create somewhere in his/her code
an instance of a G4BlineTracer object.
It can be anywhere (for example in the main code or in the user class
defining the magnetic field):

\verbatim
#include "G4BlineTracer.hh"
G4BlineTracer* theBlineTool = new G4BlineTracer();
\endverbatim

\section ExampleBlineTracer_s1 Design principles

The core of the tool is the method G4BlineTracer::ComputeBlines() of G4BlineTracer class.
In this method a bline is computed by tracking a ChargedGeantino in the user
defined magnetic field and by using a Bline equation of motion (class
G4BlineEquation, motion along the field) instead of a Lorentz equation.   

During the execution of this method :
 	
 - The user defined  equations of motion associated to the different
  global  and local fields are replaced by instances of G4BlineEquation 
  associated to the same fields.
  The G4BlineEquation class defines the differential equation of a 
  magnetic field line. 

 - User defined ChordFinders are replaced by new ChordFinders 
  associated to the G4BlineEquation object.

 - The user primary generator action, run action, event action and
  stepping action are replaced by instances of the classes
  G4BlinePrimaryGeneratorAction, G4BlineTracer, G4BlineEventAction
  and G4BlineSteppingAction respectively. Other actions are set to
  a NULL pointer.

After the execution of the method, the original user defined actions, equation
of motions and chord-finders are restored.	 
	 
In other words, the deafult run-action is temporarly replaced by a
G4BlineTracer run-action using the same Geometry, physics and magnetic fields
but with a different equation of motion and user actions.

The  G4BlinePrimaryGeneratorAction::GeneratePrimaries() method of the G4BlinePrimaryGeneratorAction class
call the GeneratePrimaries() method of the user defined PrimaryGeneratorAction 
for defining the start position and start time of tracking. 
Start position for user application and for Bline tracking are therefore
controlled by the same UI commands. 
The type of particles to be tracked when tracing Blines is always set 
to Charged-Geantino. This allows to switch off the effect of electromagnetic
and hadronics physics when tracing field lines. 


The G4BlineEventAction class is responsible to store computed magnetic field
lines as a vector of Polylines and Polymarkers for later visualisation.
These vectors can be drawn and reset at any time.

The stepping action does nothing in this implementation but it can be used 
in future versions to limit field line tracing to physical volumes defined
by the user. For this purpose a G4BlineStackingAction could also be
implemented. 

\section ExampleBlineTracer_s2 User Manual
  
\subsection ExampleBlineTracer_subs21  General description

The BlineTracer is controlled by the UI commands contained in the directory
/vis/blineTracer. By calling the command 'computeBline', several magnetic field
lines passing through user defined start positions are computed.
Start positions are generated by the user primary generator action.
By doing so, the definition of start positions is the same for usual particles
tracking and magnetic field line tracking. 

A magnetic field line is computed as a track of a charged geantino that moves 
along the field line. The user can define the maximum length of a tracking step
(only valid for Bline tracing purposes) by the use of the 'setMaxStepLength'
command.

By using small enough maximum step length, smooth magnetic field lines are 
obtained. By using the command 'stockLines' and 'stockPoints' the user 
can decide to store the series of tracking step positions defining  
a magnetic field line as a Polyline object and/or a PolyMarker object
(circles) respectively.

These objects are stored in vectors of PolyLines and PolyMarkers.
By using the command 'draw', these vectors are added to the scene
of the visualisation manager, provided that a scene handler and 
visualisation driver have been properly created.

The scene is visualised by invoking the vis command '/vis/show'.
Polyline objects are visualised as line segments joining the different 
step positions defining a line, while for a Polymarker object markers
(here circles), are  drawn at each step positions.

By using the 'setColour' the user defines the visualisation colour 
that will be associated to the next computed magnetic field lines. 
By calling 'setPointSize' the user defines the size of visualisation markers
that will be  associated to the next computed magnetic field lines. 
The user can remove the vector of Polymarker and Polyline from the memory 
by invoking 'resetMaterialToBeDrawn'.

When using small max step size and polymarkers for visualisation purposes, the
thickness of a smooth magnetic field line is obtained. It is controlled by the
Marker size parameter ('setPointSize')  

\subsection ExampleBlineTracer_subs22 Command description
 
\verbatim
/vis/blineTracer/computeBline  nb_of_lines  
\endverbatim
    - Parameters: integer nb_of_lines      
    - Description: Compute nb_of_lines different magnetic field lines
	
\verbatim
/vis/blineTracer/setMaxStepLength max_step_length 
\endverbatim
    - Parameters: double max_step_length 
    - Description: Set the maximum tracking step length for computing 
		   magnetic field lines
			     
\verbatim
/vis/blineTracer/setColour  red green blue
\endverbatim
    - Parameters: double red, green, blue
    - Description: Define  the colour for visualisation of the 
		   next computed magnetic field lines. The color is
		   defined by a  RGB code (red,green,blue)  with all
		   parameters smaller than 1.
			    
\verbatim
 /vis/blineTracer/stockLines aBool
\endverbatim
    - Parameters: boolean aBool
    - Description: If true the next computed field lines are stored
		   as Polylines for further visualisation

\verbatim
/vis/blineTracer/stockLines aBool
\endverbatim
    - Parameters: boolean aBool
    - Description: If true the next computed field lines are stored
	           as Polymarkers for further visualisation

\verbatim
/vis/blineTracer/setPointSize point_size
\endverbatim
    - Parameters: double point_size
    - Description: set the size of the visualisation  markers
		   that will be associated with the next computed
		   magnetic field lines
   
\verbatim
/vis/blineTracer/resetMaterialToBeDrawn
\endverbatim
    - Parameters: none
    - Description: The vector of Polyline and Polymarker representing 
		   magnetic field lines to be visualised are removed
		   from memory
	
\verbatim
/tracking/storeTrajectory 1
\endverbatim
    - If the storeTrajectory parameter is not set no field lines are
      stored.		     
			     
\section ExampleBlineTracer_s3 Current limitations & known problems

 The tool is working properly only for detectors parts where magnetic
 field are defined. It is planned in the future to stop the tracking of
 field lines in regions where no fields are existing.

*/
