• PATHFINDER

PATHFINDER

General Information

• PAckage for Tracking with a Hough trafo FINDER

PATHFINDER is a package which provides a track finding algorithm using a Hough Transformation as well as a very simple track generator. As input it needs hits (points in 3D space) and steering parameter. The positons of the hits must be given in cartesian coordinates. For more details see below. The search is done, depending on the track model, in two or three steps.

• Straight lines: Search is split into two steps. xy-projection (find a straight line) and sz-projection (find a straight line)
• Helices: Search is split into three steps. In the xy-projection (find a circle) the search is split into two steps. In the first step the center of the circle is found and in the second step the radius of the circle is found. The third step is the search in the sz-projection (find a straight line)

Limits/ Features of the Algorithm

• Tracks which are parallel to the z-axis cannot be found. The reason is that the first step of the search is done in the plane perpendicular to the z-axis. In this plane a track parallel to the z-axis is a point.
• It is possible that more than one hit per row is assigned to the track.

Plans for the next release

• Conformal Mapping for circles.
• Add option to set verbosity level.

( means it is already in the head version of the trunk or was at least implemented in a branch.)

Usage

How to get PATHFINDER

• PATHFINDER can be installed via ilcinstall from ilcsoft version v01-13-02 on. There is a processor in MarlinTPC which uses PATHFINDER. It can be found in (PathFinderInterfaceProcessor).

• SVN repository

Getting Started

Have a look at the examples coming along with PATHFINDER.

Track Finding

PATHFINDER has a class called FinderParameter. In order to use PATHFINDER these parameters need to be set by the user.

• _isStraightLine: has to be true straight lines should be found

• _isHelix: has to be true if helix segments should be found

• _findCurler: has to be true if curler should be found, has only effect if _isHelix = true

• _VertexPosition: position of the vertex, if not set no vertex constraint is used

• _minimumHitNumber: minimum number of hits which should be found on the track

• _maxXYDistance: maximum allowed distance of hits to track in the xy-plane

• _maxSZDistance: maximum allowed distance of hits to track in the sz-plane

• _maxXYDistanceFit: maximum allowed distance of hits to track in the xy-plane after fit

• _maxSZDistanceFit: maximum allowed distance of hits to track in the sz-plane after fit

• _saveRootFile: option to save Hough Space as root file (for debugging use only)

• _searchNeighborhood: option to not only search the point of intersection in the Hough Space but also look in the neighborhood of a possible point of intersection

• _numberXYDzeroBins: binning of Hough Space

• _numberXYThetaBins: binning of Hough Space

• _numberXYOmegaBins: binning of Hough Space, only needed for helices

• _numberSZDzeroBins: binning of Hough Space

• _numberSZThetaBins: binning of Hough Space

• _maxDxy:

  • For straight lines: the maximum possible distance of closest approach in the xy plane.
  • For circles: the maximum possible distance of the center of the circle (xy plane) to the origin of the coordinate system so that a circle still looks like a circle and not like a straight line.

• _maxDsz: the maximum possible distance of closest approach in the sz plane.

Example code:

   1 //FinderParameter* myFinderParameter= new FinderParameter(true, false) //straight line
   2 FinderParameter* myFinderParameter= new FinderParameter(false, true) //helix
   3 myFinderParameter -> setVertex(0.,0.);
   4 myFinderParameter -> setFindCurler(false);
   5 myFinderParameter -> setMaxXYDistance(5.);
   6 myFinderParameter -> setMaxSZDistance(5.);
   7 myFinderParameter -> setMaxXYDistanceFit(3.);
   8 myFinderParameter -> setMaxSZDistanceFit(3.);
   9 myFinderParameter -> setMinimumHitNumber(5);
  10 myFinderParameter -> setNumberXYThetaBins(200);
  11 myFinderParameter -> setNumberXYDzeroBins(200);
  12 myFinderParameter -> setNumberXYOmegaBins(200);
  13 myFinderParameter -> setNumberSZThetaBins(200);
  14 myFinderParameter -> setNumberSZDzeroBins(200);
  15 myFinderParameter -> setMaxDxy(10.);//for helix
  16 //myFinderParameter -> setMaxDxy(3200.);//for straight line
  17 myFinderParameter -> setMaxDsz(3200.);
  18 myFinderParameter -> setSearchNeighborhood(false);
  19 myFinderParameter -> setSaveRootFile(false);

Attention: The number of bins cannot be larger than 1000 bins!

Attention: The value for _maxDxy has very different values for straight lines and helices. For more details see Additional notes on track finding

Apart from that PATHFINDER also needs hits as input. The class for hits in PATHFINDER is called basicHit. The constructor takes three doubles as parameters which are the x,y,z position of the hit ( cartesian coordinates! ). To use PATHFINDER a vector of basicHits needs to be created.

Example code:

   1 basicHit myHit(xpos, ypos, zpos);
   2 myBasicHitVector.push_back(myHit);

Then the finding of tracks can be done.

Example code:

   1 HoughTrafoTrackFinder myTrackFinder;
   2 myTrackFinder.setFinderParameter(*myFinderParameter);
   3 myTrackFinder.setInitialHits(myBasicHitVector);
   4 bool track_found = myTrackFinder.find();

PATHFINDER then gives back a vector of TrackFinderTrack, which contains the track parameters and the hits on the track.

Example code:

   1 vector<TrackFinderTrack> foundTracks = myTrackFinder.getTracks();
   2 //get track parameters of first track in vector
   3 TrackParameterFull recoTrackParam = foundTracks[0].getTrackParameter();
   4 
   5 double d0 = recoTrackParam.getDZero();
   6 double phi = recoTrackParam.getPhi();
   7 double omega = recoTrackParam.getOmega();
   8 double z0 = recoTrackParam.getZZero();
   9 double tanl = recoTrackParam.getTanLambda();
  10 
  11 double d0Error = recoTrackParam.getDZeroError();
  12 double phiError = recoTrackParam.getPhiError();
  13 double omegaError = recoTrackParam.getOmegaError();
  14 double z0Error = recoTrackParam.getZZeroError();
  15 double tanlError = recoTrackParam.getTanLambdaError();
  16 
  17 //get hits on track
  18 vector<basicHit> hitsOnTrack = foundTracks[0].getHitsOnTrack();

Additional notes on track finding (Read this in case you have trouble finding tracks!)

• PATHFINDER does not care about units. However, it is important that the positions of the hits and the distances specified in the FinderParameters have the same unit. The track parameter d0 and z0 coming out of the track finding have the same unit as the hit positions and distances.

• The hit positions must be given in cartesian coordiantes.
• The user has to determine which value for _maxDxy and _maxDsz needs to be chosen. This depends on where the origin of the coordinate system is and how the readout structure looks like. In general the range where to look for tracks should be limited as much as possible.
• _maxDxy has different values for straight lines and helices. For straight lines the distance of closest approach is used while for helices the inverse distance of the center of the circle in the xy-plane is used.
• The number of bins should neither be to large nor to small. In both cases tracks cannot be found properly anymore. The value for these parameters depends on how many hits there are on the track. The binning can be smaller when there are many hits on the track because the more hits there are on a track the better the point of intersection of the functions is defined.
• If all the hits are rather far away from the point of reference (origin) it might happen, that no tracks are found or the track parameters do not seem to describe the track very well. In such a case try shifting the hits closer to the origin and run the track finding again. When doing this do NOT use the vertex constraint!

• If _saveRootFile is set to true (debugging only!), two root files are written during reconstruction, one for the xy-projection, one for the sz-projection. These root files contain a root tree of the Hough spaces calculated during track finding. In the file for the xy-projection all hits were used for the calculation, for the sz-projection only those hits were used, which were found to be on the track in the xy-projection. In the directory scripts a script can be found which makes nice 2D plots from these root trees. The filenames might need to be adapted!

Track Generation

To use the track generation implemented in PATHFINDER three steering classes are needed.

• TGEventType: contains all parameters describing how the events should look like.

  • nhits: number of hits per track

  • ntracks: number of tracks per event

  • nnoise: number of noise hits per event

  • smearing: Hits are shifted away from the track. The variable is the width of the gaussian used for this.

  • nevents: number of events ( The track generator uses this variable only as a seed for the random number generator. The loop over the number of events needs to be provided by an external program! ) Example Code:

       1   unsigned int nhitsontrack = 50;
       2   unsigned int nevents = 10;
       3   unsigned int ntracks = 1;
       4   unsigned int nnoise = 0;
       5   double smearing = 0.;
       6   TGEventType EventType(nhitsontrack,
       7                         ntracks,
       8                         nnoise,
       9                         smearing,
      10                         nevents);
    

• TGDeterctorType: contains parameters which describe the detector in which tracks are to be generated. Only rectangular geometries are implemented.

  • padplaneXmin, padplaneXmax: range in x of pad plane

  • padplaneYmin, padplaneYmax: range in y of pad plane

  • padplaneZmin, padplaneZmax: range in z of pad plane

  • padsizeY: size of a pad in y-direction Example Code:

       1   double padplanexmin = -1000.;
       2   double padplanexmax = 1000.;
       3   double padplaneymin = -1400.;
       4   double padplaneymax = 1400.;
       5   double padplanezmin = -1000.;
       6   double padplanezmax = 1000.;
       7   double padsizey = 7.;
       8   TGDetectorType DetectorType(padplanexmin, padplanexmax,
       9                               padplaneymin, padplaneymax,
      10                               padplanezmin, padplanezmax,
      11                               padsizey);
    

• TGParameterLimits: limits on the track parameters are given.

  • minphi, maxphi: minimum and maximum of phi

  • mind0, maxd0: minimum and maximum of d0

  • minr, maxr: minimum and maxiumum of radius

  • mintanl, maxtanl: minimum and maximum of tan(lambda)

  • minz0, maxz0: minimum and maximum of z0 Example Code:

       1   double phimin = -3.14159;
       2   double phimax = 3.14159;
       3   double d0min = 0.;
       4   double d0max = 1000.;
       5   double rmin = -1000.;
       6   double rmax = 1000.;
       7   double tanlmin = -1.;
       8   double tanlmax = 1.;
       9   double z0min = 0.;
      10   double z0max = 1000.;
      11   TGTrackParameterLimits TrackParameterLimits(phimin, phimax,
      12                                               d0min, d0max,
      13                                               rmin, rmax,
      14                                               tanlmin, tanlmax,
      15                                               z0min, z0max);
    

To fix a track parameter, upper and lower limit have to be set to the same value. In all other cases the minimum value for a parameter always needs to be smaller than the maximum value.

In addition to these steering classes the track type needs to be defined. This is done via an integer. It is 0 for straight lines, 1 for helix segments and 2 for curler

Example Code:

   1 unsigned int track_type = 2;//0 = straight line, 1 = helix segment, 2 = curler
   2 

The actual generation of tracks is done with a class called TrackGenerator. This class can only create one event at a time, so the loop over several events has to be provided by an external program. TrackGenerator gives back a vector with the simulated tracks (track parameters + hits on track), a vector containing all noise hits and a vector containing all hits in the event (hits on track + noise hits)

Example Code:

   1 TrackGenerator newTrackGen(track_type, TrackParameterLimits, EventType, Detectortrype);
   2 
   3 for(unsigned int event = 0; event<nevents; event++)
   4 {
   5  newTrackgen.generateTracks(event);
   6  vector<TrackFinderTrack*> simtracks = newTrackGen.getGeneratorTracks();
   7  vector<basicHit> allhits = newTrackGen.getHits();
   8  vector<basicHit> noisehits = newTrackGen.getNoiseHits();
   9  for(unsigned int i = 0; i<simtracks.size(); i++)
  10  {
  11   TrackParameterFull currentTrackParameters = simtracks[i]->getTrackParameter();
  12   vector<basicHit> currentTrackHits = simtracks[i]->getHitsOnTrack();
  13   double d0 = currentTrackParameters.getDZero();
  14   double phi = currentTrackParameters.getPhi();
  15   double omega = currentTrackParameters.getOmega();
  16   double tanl = currentTrackParameters.getTanLambda();
  17   double z0 = currentTrackParameters.getZZero();
  18   for(unsigned int j =0; j<currentTrackHits.size(); j++)
  19   {
  20    double pos[3];
  21    pos[0] = currentTrackHits[j].getX();
  22    pos[1] = currentTrackHits[j].getY();
  23    pos[2] = currentTrackHits[j].getZ();
  24   }
  25  }
  26 }

Note: For event numbers larger than about 2500 the random number for phi is not uniformly distributed.

PATHFINDER Class Diagrams

Track Finding

Track Generation

RootFileWriter

(for debugging use only)

CategoryTpc