% Created 2025-08-21 Thu 14:02
% Intended LaTeX compiler: pdflatex
\documentclass[usenames,dvipsnames,colorlinks,aspectratio=169]{beamer}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{graphicx}
\usepackage{longtable}
\usepackage{wrapfig}
\usepackage{rotating}
\usepackage[normalem]{ulem}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{capt-of}
\usepackage{hyperref}
\usepackage{color}
\usepackage{listings}
\usepackage{pdfpages}
\usepackage{xcolor}
\usepackage{graphicx}
\usepackage{xspace}
\usepackage{siunitx}
\usepackage{libertine}
\usepackage{fontawesome}
\mode<beamer>{\usetheme{Boadilla}}
\setbeamertemplate{navigation symbols}{}
\setbeamerfont{alerted text}{series=\bfseries}
\setbeamercolor{alerted text}{fg=blue}
\usecolortheme{default}
\usefonttheme{serif}
\usefonttheme{professionalfonts}
\lstloadlanguages{[ISO]C++}
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.50,0,0.82}
\definecolor{codeorange}{rgb}{0.95,0.3,0.1}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}
\lstdefinestyle{mystyle}{
commentstyle=\color{codegreen},
keywordstyle=\color{codeorange},
numberstyle=\tiny\color{codegray},
stringstyle=\color{codepurple},
basicstyle=\footnotesize,
breakatwhitespace=false,
breaklines=true,
captionpos=b,
keepspaces=true,
numbers=left,
numbersep=5pt,
showspaces=false,
showstringspaces=false,
showtabs=false,
tabsize=2
}
\lstset{style=mystyle}
\usetheme{default}
\author{Brett Viren}
\date{\today}
\title{Pattern Recognition Porting Preparation}
\hypersetup{
 pdfauthor={Brett Viren},
 pdftitle={Pattern Recognition Porting Preparation},
 pdfkeywords={},
 pdfsubject={},
 pdfcreator={Emacs 28.2 (Org mode 9.5.5)}, 
 pdflang={English}}
\begin{document}

\maketitle

\begin{frame}[label={sec:org7109b13},fragile]{Overview}
 WCT \texttt{clus/} updates for prepare pattern recognition (PR) related porting.

\begin{itemize}
\item Starts July 22nd after ``steiner'' and ``UbooneClusterSource to remake all live slices''
\item Removed \texttt{patrec/} sub-package, some docs now in \texttt{clus/docs/porting/}
\item Add skeleton for \texttt{ToyFiducial} porting
\item Initiate \texttt{WireCell::Clus::PR} namespace
\begin{itemize}
\item Define ``trajectory graph'' of \texttt{PR::Vertex} node property and \texttt{PR::Segment} edge property
\item \texttt{Tranjectory} and \texttt{TranjectoryView} graph ``wrapper'' classes
\end{itemize}
\item Linear interpolation, KS-like test metric

\item Along the way: Doxygen cleanups, compiler warnings/errors, add support for \texttt{clangd} for Eglot.
\end{itemize}
\end{frame}

\begin{frame}[label={sec:org1e04efc},fragile]{}
 \begin{center}
\Huge New in \texttt{util/}
\end{center}
\end{frame}




\begin{frame}[label={sec:orgaa99d27},fragile,shrink=10]{\texttt{util:} new \texttt{Flagged} base class give object up to \alert{64 boolean ``flags''}}
 \begin{block}{Define set of flags in an \alert{enum class} for each subclass of \texttt{Flagged}}
\scriptsize
\begin{verbatim}
enum class SegmentFlags {
    kUndefined = 0, kShowerTrajectory = 1<<1,
    kShowerTopology = 1<<2, kAvoidMuonCheck = 1<<3, kFit = 1<<4,
};
\end{verbatim}
\end{block}

\begin{block}{\texttt{Flagged} is a \alert{mixin base class} used by \texttt{PR::Segment} and \texttt{PR::Vertex} (so far)}
\scriptsize 
\begin{verbatim}
class Segment : public Flagged<SegmentFlags> { ... };
class Vertex : public Flagged<VertexFlags> { ... };

// Example usage:
vtx.set_flag(VertexFlags::kNeutrinoVertex);
if (! seg.flags_any(SegmentFlags::kAvoidMuonCheck)) { do_muon_check(seg); }
\end{verbatim}
\end{block}
\begin{block}{Flags are a \alert{bit index} and we may use \alert{bit-wise} operators.}
\scriptsize
\begin{verbatim}
seg.set_flag(SegmentFlags::kFit); // kFit is 1<<4, so bit index is 4
assert(seg.flag_at(4))

auto either = SegmentFlags::kShowerTrajectory | SegmentFlags::kShowerTopology;
if (seg.flags_any(either)) { do_either_shower_thing(seg); }
\end{verbatim}
\end{block}
\end{frame}



\begin{frame}[label={sec:orgd9f2288},fragile]{}
 \begin{center}
\Huge New in \texttt{clus/}
\end{center}
\end{frame}


\begin{frame}[label={sec:org7650b02},fragile]{File overview of the new \texttt{WireCell::Clus::PR} namespace}
 All \alert{file names} are like \texttt{PR*.\{h,cxx\}}:

\begin{columns}
\begin{column}{0.4\columnwidth}
\begin{itemize}
\item \texttt{PRCommon}
\item \texttt{PRGraphType}
\item \texttt{PRVertex}
\item \texttt{PRSegment}
\item \texttt{PRGraph}
\item \texttt{PRTrajectoryView}
\item \texttt{PRTrajectory}
\item \texttt{PRShower}
\item \texttt{PR*Functions}
\end{itemize}
\end{column}

\begin{column}{0.6\columnwidth}
The \texttt{PRXxx} files either define a class of same name \texttt{PR::Xxx} or they hold
conceptually connected set of functions or classes, organized by type
dependencies.

\vspace{1cm}

I'll next go through the list of files to describe contents and concepts.
\end{column}
\end{columns}
\end{frame}

\begin{frame}[label={sec:orga7c4c25},fragile]{PRCommon}
 \begin{block}{Mixins: \texttt{HasCluster} and \texttt{HasDPCs}}
Base mixin classes for a class to hold a \texttt{Cluster} or a named map of \texttt{DynamicPointCloud}.
\end{block}

\begin{block}{\texttt{WCPoint} struct and vector}
A 3D \texttt{Point} and 3 wire indices, similar to WCP struct of same name.
\end{block}

\begin{block}{\texttt{Fit} struct and vector}
A 3D \texttt{Point} and fit parameters (\texttt{dQ}, \texttt{dx}, etc).
\end{block}

\begin{block}{Point-related functions}
\begin{itemize}
\item \texttt{to\_point()} eg, convert \texttt{vector<WCPoint>} to \texttt{vector<Point>}
\item \texttt{closest\_point()} find point in collection closest to given test point.
\item \texttt{walk\_length()} length to step between points in a collection
\end{itemize}
\end{block}
\end{frame}

\begin{frame}[label={sec:orgfe28988},fragile]{PRGraphType defines \texttt{PR::Graph} a ``trajectory graph''}
 \begin{block}{Graph type}
A \texttt{setS/setS} graph, robust descriptors but unordered iterations.
\begin{itemize}
\item The graph maintains an \alert{index} in node/edge properties which can provide order.
\item \texttt{ordered\_nodes(g)} gives ordered vector of node descriptors
\end{itemize}
\end{block}
\begin{block}{Nodes and edges}
\begin{itemize}
\item Node property has \texttt{shared\_ptr<PR::Vertex> vertex;}
\item Edge property has \texttt{shared\_ptr<PR::Segment> segment;}
\end{itemize}
\end{block}
\begin{block}{Usage}
Do not use ``bare'' \texttt{boost::} graph functions to build or use this graph.
\begin{itemize}
\item Need care to keep \texttt{shared\_ptr} and \alert{index} consistent.
\item \texttt{PRGraph.h} provides bookkeeping equivalents to \texttt{boost::} graph functions.
\end{itemize}
\end{block}
\end{frame}


\begin{frame}[label={sec:org8b9ba8a},fragile]{PRVertex gives \texttt{PR::Vertex} and \texttt{PR::VertexFlags}}
 Analog to WCP's \texttt{ProtoVertex}

\begin{block}{\texttt{PR::Vertex} \alert{IsA} \texttt{Flagged} and \alert{IsA} \texttt{HasCluster} and holds:}
\begin{itemize}
\item A \texttt{WCPoint} giving ``initial point''
\item A \texttt{Fit} for fit point and parameters
\end{itemize}
\end{block}

\begin{block}{Implements ``chainable setters''.}
\begin{verbatim}
WCPoint p;
Cluster* c = ...;
vtx.wcpt(p).cluster(c);
\end{verbatim}
\end{block}

\begin{block}{Has ``getters'' named same as setter, but no args.}
\begin{verbatim}
WCPoint p = vtx.wcpt();
\end{verbatim}
\end{block}
\end{frame}

\begin{frame}[label={sec:orgcaccfed},fragile]{PRSegment gives \texttt{PR::Segment} and \texttt{PR::SegmentFlags}}
 Analog to WCP's \texttt{ProtoSegment}

\begin{block}{\texttt{PR::Segment} \alert{IsA} \texttt{Flagged}, \texttt{HasCluster}, and \texttt{HasDPCs} and holds:}
\begin{itemize}
\item vector of \texttt{WCPoint}
\item vector of \texttt{Fit}
\end{itemize}
\end{block}

\begin{block}{\texttt{HasDPCs} gives string map to \texttt{DynamicPointCloud}}
\begin{verbatim}
auto dpc_steiner = seg.dpcloud("steiner"); // get
seg.dpcloud("default", dpc_default);       // put
\end{verbatim}
\end{block}
\end{frame}

\begin{frame}[label={sec:org9fd1ecd},fragile,shrink=10]{PRGraph gives main API for using ``trajectory graphs''}
 \begin{columns}
\begin{column}{0.4\columnwidth}
\begin{itemize}
\item \texttt{PRGraph.h} provides functions in terms of the graph and \texttt{PR::Vertex} and \texttt{PR::Segment} types.

\item These \texttt{PR::} types are always held in \texttt{shared\_ptr}.
\end{itemize}
\end{column}

\begin{column}{0.65\columnwidth}
\begin{itemize}
\item \texttt{make\_vertex(graph)} returns a new vertex added to the graph.
\item \texttt{add\_vertex(graph, vtx)} add existing vertex.
\item \texttt{remove\_vertex(graph, vtx)} remove vertex from graph.
\item \texttt{make\_segment()} make a segment not (yet) in a graph.
\item \texttt{make\_segment(graph, vtx1, vtx2)} make a segment as an edge between two vertices.
\item \texttt{add\_segment(graph, seg, vtx1, vtx2)} add a segment as an edge between two vertices.
\item \texttt{remove\_segment(graph, seg)} remove segment's edge from graph.
\item \texttt{find\_enpoints(graph, seg)} return pair of vertices that are endpoints of segment's edge.
\end{itemize}
\end{column}
\end{columns}
\end{frame}

\begin{frame}[label={sec:orgaae7e2e},fragile]{\texttt{PR::Graph} bookkeeping}
 \begin{block}{The \texttt{Graphed} base class gives vertex/segment a graph descriptor}
\begin{verbatim}
auto edge = seg->get_descriptor();
if (vtx->descriptor_valid()) {
    cout << "Vertex is in the graph!\n";
}
\end{verbatim}
\end{block}

\begin{block}{Guidance}
Always use \texttt{PRGraph.h} functions to assure the bookkeeping is correct.
\begin{itemize}
\item \texttt{PR::add\_vertex(graph,vtx)} is \alert{good!}
\end{itemize}

Never use ``bare'' \texttt{boost::} functions on ``trajectory graphs''.
\begin{itemize}
\item \sout{\texttt{boost::add\_vertex()}} is \alert{bad!}
\end{itemize}
\end{block}
\end{frame}


\begin{frame}[label={sec:orgaff3122},fragile]{PRTrajectoryView provides \texttt{PR::TrajectoryView} class}
 \begin{block}{Wrapper around a trajectory graph providing \alert{filtered graph}}
\begin{verbatim}
PR::Graph graph; // user keeps alive
TrajectoryView tv(graph);
// Add objects already in the graph to the filter
tv.add_vertex(vtx);
tv.add_segment(seg);
\end{verbatim}
\end{block}

\begin{block}{Using \texttt{PR::TrajectoryView}}
\begin{itemize}
\item Can create them as needed but \texttt{PR::Trajectory} gives convenient ``collection of views''.

\item A \texttt{PR::TrajectoryView} is a useful base class, eg \texttt{PR::Shower} uses it.
\end{itemize}
\end{block}
\end{frame}

\begin{frame}[label={sec:org5ed13e8},fragile]{PRTrajectory provides \texttt{PR::Trajectory} class}
 \begin{block}{Wrapper around trajectory graph which can make views}
\begin{verbatim}
PR::Graph graph; // user keeps alive
Trajectory t(graph);

auto tv = t.make_view<TrajectoryView>();
auto shwr = t.make_view<Shower>();

cout << "has " << t.size() << " views (2)\n";
for (auto view : t.views()) {
    cout << "has node? " << view->has_node(vtx->get_descriptor()) << "\n";
}
\end{verbatim}
\end{block}

\begin{block}{Details}
\begin{itemize}
\item Views are created in shared pointers.
\item User must keep the graph alive while using the \texttt{Trajectory} (and any views).
\end{itemize}
\end{block}
\end{frame}

\begin{frame}[label={sec:org3e3c3c6},fragile]{PRShower provides \texttt{PR::Shower}}
 Analog of WCP's \texttt{WCShower}

\begin{block}{\alert{IsA} \texttt{TrajectoryView} with extra:}
\begin{itemize}
\item start vertex and segment
\end{itemize}
\end{block}

\begin{block}{More needed.}
This class may need more data.
\end{block}
\end{frame}

\begin{frame}[label={sec:org201ea0c},fragile]{\texttt{PRSegmentFunction.\{h,cxx\}}}
 \begin{block}{Intention is to hold function versions of WCP \texttt{ProtoSegment} methods}
WCT implementations can be \alert{much} simpler due to use of graph, holding segment fit as \texttt{vector<Fit>} and dedicated functions factoring common algorithm primitives.
\end{block}

\begin{block}{Implemented but none are tested yet}
\begin{itemize}
\item \texttt{break\_segment(graph, seg, point)}
\item \texttt{segment\_track\_length(seg)}
\item \texttt{segment\_median\_dQ\_dx(seg)}
\item \texttt{segment\_track\_length\_threshold(seg, thresh)}
\item \texttt{segment\_geometric\_length(seg)}
\end{itemize}
\end{block}
\end{frame}

\begin{frame}[label={sec:org4fe6098},fragile]{\texttt{PRShowerFunctions.\{h,cxx\}}}
 \begin{block}{Intention is to hold function versions of WCP \texttt{WCShower} methods.}
\end{block}

\begin{block}{None are yet implemented, just place-holder declarations}
\begin{itemize}
\item \texttt{shower\_kinematics(shower)}
\item \texttt{update\_particle\_type(shower)}
\item \texttt{longmuon\_kinematics(shower)}
\end{itemize}
\end{block}
\end{frame}
\end{document}