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).
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:
Then the finding of tracks can be done.
Example code:
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:
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:
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)