FlowContourMatch

Notes on FlowContourMatch

Purpose

Goal is to define 3D space points for every pixel or hit on the Y-plane. (We can later extend for U and V plane pixels/hits -- but code does not prepare for this at all right now.)

Intended Output of Algorithm

The primary output of the algorithm is a vector<FlowMatchHit3D>. It inherits from vector and is intended to have 3 elements: (x,y,z).

  class FlowMatchHit3D: public std::vector<float>  {
    // class stores 3d location, but also provides us information                                                                                                                                           
    // on the source and target contours it belongs to.                                                                                                                                                     
    // produced by FlowContourMatch::                                                                                                                                                                       

  public:

    FlowMatchHit3D() {
      targetwire.resize(2,-1);
    };
    ~FlowMatchHit3D() {};

    typedef enum { kQandCmatch=0, kCmatch, kClosestC, kNoMatch } MatchQuality_t; // quality of match                                                                                                        
    typedef enum { kIn5mm=0, kIn10mm, kIn50mm, kOut50mm, kNoValue } Consistency_t; // quality of match                                                                                                      

    int tick;        // row                                                                                                                                                                                 
    int srcwire;     // column in source image                                                                                                                                                              
    std::vector<int> targetwire;  // column in target image                                                                                                                                                 
    int idxhit;      // index in eventhit vector                                                                                                                                                            
    MatchQuality_t matchquality; // quality of plane-correspondence match                                                                                                                                   
    Consistency_t consistency;
    float center_y_dist;  // distance to center of y-image used for flow prediction                                                                                                                         

  };

Other information is stored for use by the downstream clustering algorithms. The intention is to primarily keep only useful info for downstream algos. Information to help study performance or decision is intended to be minimal. The algorithm that form these hits will make a ROOT TTree to store development variables.

Inputs

• ADC image from event -- broken apart into subimages by UBSplitDet in larcv/app/UBImageMod.
• Flow predictions for these subimages. Intended for both Y2U and Y2V, but has options to use only one flow direction
• Endpoint/Track/Shower labels for each subregion from the endpoint ssnet.
• Infill predictions for each subregion from the infill CNN
• vectorlarlite::hit: can come from hit-finder's like larsoft's gaushit. Can also make fake hits that represent above threshold pixels. Use larflow::FlowContourMatch::makeHitsFromWholeImagePixels to make this vector of pixel-based hits.

Algorithm Description

Intended Use

Main function to call is larflow::FlowContourMatch::fillPlaneHitFlow. The intention is to call this function repeatedly, once for each subimage. Note when I name functions below, I mean to call the function for an instance of the FlowContourMatch class. I do not mean to call some static version, though I've confusingly written it this way just to emphasize that all the functions are in the class larflow::FlowContourMatch

After every event the intention is to use the stored information from all the subimages to make the final list of 3D spacepoints. Get these points by calling

std::vector< FlowMatchHit3D > larflow::FlowContourMatch::get3Dhits_2pl( bool makehits_for_nonmatches=true, bool require_3Dconsistency=false );

Before every new event, we need to clear the data members in FlowContourMatch that stores information. Do this by calling:

void larflow::FlowContourMatch::clear();

How it works

For each subimage, we call fillPlaneHitFlow. This code then collates information about the flow from the source to target plane, i.e. Y(source)-to-U(target) or Y(source)-to-V(target). We then use this information to make the 3D space points.

Chain of intermediate data products

We describe the algorithm by going through the intended data product at each step. The data is stored as member variables of the algorithm class. The list is

• std::map< SrcTarPair_t, FlowMatchData_t > m_flowdata: Map between the key -- which is a pair of source and target contours -- and value, which is a struct containing information about the pixels within the source and target contours, mostly about how many source pixels inside the source contour are paired to the pixels in the target contours, using the larflow predictions

• double* m_score_matrix.: 2D matrix that stores "matching score" between source and target contours. This score is basically determined by the fraction of source pixels, relative to all pixels in a source contour, that get mapped to the target contour. We use the above information to build this matrix.

• PlaneHitFlowData_t m_plhit2flowdata: this stores for each flow direction (Y2U and Y2V), the flow from source plane hits to the pixels in the target -- after using the contour matching to help adjust raw larflow predictions. This is done to help mitigate bad raw larflow predictions. This data is what is used to make the final output product, the 3D spacepoints

Chain of algorithms that produces the chain of intermediate data

A brief outline of the chain of functions are as follows. We execute them in the order listed below:

• within the primary function, fillPlaneHitFlow, the match function is called, once for each flow direction (Y2U, Y2V):

   void match( FlowDirection_t flowdir,
                const larlitecv::ContourCluster& contour_data,
                const larcv::Image2D& src_adc,
                const larcv::Image2D& tar_adc,
                const larcv::Image2D& flow_img,
                const larlite::event_hit& hit_v,
                const float threshold );

• within match, _createMatchData fills std::map< SrcTarPair_t, FlowMatchData_t > m_flowdata
• within match, _scoreMatches fills double* m_score_matrix
• within match, _greedyMatch() takes scoreMatches matrix and assigns matches between 1 source contour and X target contours
• within match, _make3Dhits uses source-target contour matches to modify flow from source hit/pixel to target hit/pixel
• within fillPlaneHitFlow, _fill_consistency3d. Calculate 3D consistancy between the two flow direction predictions. Measured by distance between predicted 3D spacepoint as determined by contour-corrected flow

Again, this chain is run for each subimage. After all subimages for an event are run, the user should call get3Dhits_2pl to get vector of 3D spacepoints and their metadata

Notes/ToDos

• check if greedymatch is still being used
• move match to an internal function
• function that takes in MC information (mctrack/mcshower vector) and stores in a ROOT Tree (to be written out at the end) the intermediate values that get us to the final 3D spacepoints
• change _make3Dhits with more accurate name, e.g. makeHitFlowData
• use suffice for all functions to be called per subimage
• make it more clear from name and signature, that the main algo, fillPlaneHitFlow, is the one to call.