added plotting to the user manual

Readme.md

@@ -1,10 +1,7 @@
-November 23, 2023
-<<<<<<< HEAD
+October 04, 2024
+
+Version: 1.0.3
 
-Version: 1.0.0
-=======
-Version: 1.0.2
->>>>>>> added stuff to user manual and upgraded to 1.0.2
 
 <img src="./user_manual/figs/logo.png" style="zoom:20%;" />
 

myptv/makePlots/plot_trajectories.py

@@ -13,25 +13,6 @@
 
 
 
-
-
-# ===========  Your Input goes here ================= #
-
-# insert here the name of the trajectory file:
-fname = '/home/ron/Desktop/Research/jetArrayTank/20240821/Rec2/trajectories'
-
-
-# insert here the IDs of the trajectories you wish to plot. 
-# if no number is given, then we plot all the trajectories in the file:
-min_length = 20
-
-# =================================================== #
-
-
-
-
-
-
 def plot_trajectories(fname, min_length, write_trajID=False, t0=0, te=-1):
     '''
     This function plots trajectories from a given file in 3D.

user_manual/bib_myPTV.bib

@@ -85,4 +85,15 @@ @Article{Xu2008
   publisher = {IOP Publishing},
 }
 
+@Article{Shnapp2023,
+  author    = {Shnapp, R. and Brizzolara, S. and Neamtu Halic, M. M. and Gambino, A. and Holzner, M.},
+  journal   = {Nature Communications},
+  title     = {Universal alignment in turbulent pair dispersion},
+  year      = {2023},
+  number    = {1},
+  volume    = {14},
+  doi       = {10.1038/s41467-023-39903-6},
+  publisher = {Springer Science and Business Media {LLC}},
+}
+
 @Comment{jabref-meta: databaseType:bibtex;}

user_manual/user_manual.bbl

@@ -11,16 +11,6 @@ H.~G. Maas, D.~Gruen, and D.~Papantoniou.
   Photogrammetric} determination of particle coordinates.
 \newblock {\em Experiments in Fluid}, 15:133--146, 1993.
 
-\bibitem{Luthi2005}
-B.~L{\"u}thi, A.~Tsinober, and W.~Kinzelbach.
-\newblock Lagrangian measurement of vorticity dynamics in turbulent flow.
-\newblock {\em Journal of Fluid mechanics}, 528:87--118, 2005.
-
-\bibitem{Xu2008}
-H.~Xu.
-\newblock Tracking {Lagrangian} trajectories in position--velocity space.
-\newblock {\em Measurement Science and Technology}, 19(7):075105, 2008.
-
 \bibitem{Bourgoin2020}
 M.~Bourgoin and S.~G. Huisman.
 \newblock Using ray-traversal for {3D} particle matching in the context of
@@ -33,6 +23,21 @@ N.~T. Ouellette, H.~Xu, and E.~Bodenschatz.
   tracking algorithms.
 \newblock {\em Experiments in Fluids}, 40(2):301--313, 2006.
 
+\bibitem{Luthi2005}
+B.~L{\"u}thi, A.~Tsinober, and W.~Kinzelbach.
+\newblock Lagrangian measurement of vorticity dynamics in turbulent flow.
+\newblock {\em Journal of Fluid mechanics}, 528:87--118, 2005.
+
+\bibitem{Xu2008}
+H.~Xu.
+\newblock Tracking {Lagrangian} trajectories in position--velocity space.
+\newblock {\em Measurement Science and Technology}, 19(7):075105, 2008.
+
+\bibitem{Shnapp2023}
+R.~Shnapp, S.~Brizzolara, M.~M. Neamtu~Halic, A.~Gambino, and M.~Holzner.
+\newblock Universal alignment in turbulent pair dispersion.
+\newblock {\em Nature Communications}, 14(1), 2023.
+
 \bibitem{Shnapp2019}
 R.~Shnapp, E.~Shapira, D.~Peri, Y.~Bohbot-Raviv, E.~Fattal, and A.~Liberzon.
 \newblock Extended {3D-PTV} for direct measurements of {Lagrangian} statistics

user_manual/user_manual.log

@@ -1,4 +1,4 @@
-This is pdfTeX, Version 3.14159265-2.6-1.40.18 (TeX Live 2017/Debian) (preloaded format=pdflatex 2023.7.13)  3 OCT 2024 13:12
+This is pdfTeX, Version 3.14159265-2.6-1.40.18 (TeX Live 2017/Debian) (preloaded format=pdflatex 2023.7.13)  3 OCT 2024 22:23
 entering extended mode
  restricted \write18 enabled.
  %&-line parsing enabled.
@@ -764,78 +764,88 @@ Overfull \hbox (17.3725pt too wide) in paragraph at lines 1215--1233
  [][] 
  []
 
-[19] [20] [21] [22] [23]
+<./figs/trajectory_plot.pdf, id=657, 459.96844pt x 392.96812pt>
+File: ./figs/trajectory_plot.pdf Graphic file (type pdf)
+<use ./figs/trajectory_plot.pdf>
+Package pdftex.def Info: ./figs/trajectory_plot.pdf  used on input line 1249.
+(pdftex.def)             Requested size: 227.62204pt x 194.46884pt.
+
+Overfull \hbox (1.62634pt too wide) in paragraph at lines 1258--1273
+ [][] 
+ []
+
+[19 <./figs/trajectory_plot.pdf>] [20] [21] [22] [23] [24]
 LaTeX Font Info:    Font shape `T1/cmtt/bx/n' in size <14.4> not available
-(Font)              Font shape `T1/cmtt/m/n' tried instead on input line 1269.
+(Font)              Font shape `T1/cmtt/m/n' tried instead on input line 1294.
 LaTeX Font Info:    Font shape `T1/cmtt/bx/n' in size <12> not available
-(Font)              Font shape `T1/cmtt/m/n' tried instead on input line 1276.
-<./figs/camera_files.pdf, id=691, 508.10204pt x 141.02348pt>
+(Font)              Font shape `T1/cmtt/m/n' tried instead on input line 1301.
+<./figs/camera_files.pdf, id=707, 508.10204pt x 141.02348pt>
 File: ./figs/camera_files.pdf Graphic file (type pdf)
 <use ./figs/camera_files.pdf>
-Package pdftex.def Info: ./figs/camera_files.pdf  used on input line 1306.
+Package pdftex.def Info: ./figs/camera_files.pdf  used on input line 1331.
 (pdftex.def)             Requested size: 426.79135pt x 118.45676pt.
- [24
+ [25
 
  <./figs/camera_files.pdf>]
-Overfull \hbox (1.44354pt too wide) in paragraph at lines 1376--1377
+Overfull \hbox (1.44354pt too wide) in paragraph at lines 1401--1402
 []\T1/cmtt/m/n/10 fineCalibration(maxiter=500) \T1/cmr/m/n/10 - This func-tion 
 will solve for the co-ef-fi-cients of the quadratic
  []
 
-[25] [26]
-<./figs/blob_file.pdf, id=762, 223.10614pt x 155.32921pt>
+[26] [27]
+<./figs/blob_file.pdf, id=778, 223.10614pt x 155.32921pt>
 File: ./figs/blob_file.pdf Graphic file (type pdf)
 <use ./figs/blob_file.pdf>
-Package pdftex.def Info: ./figs/blob_file.pdf  used on input line 1505.
+Package pdftex.def Info: ./figs/blob_file.pdf  used on input line 1530.
 (pdftex.def)             Requested size: 284.52756pt x 198.10016pt.
- [27] [28 <./figs/blob_file.pdf>]
-<./figs/particle_file.pdf, id=803, 390.14703pt x 291.52518pt>
+ [28] [29 <./figs/blob_file.pdf>]
+<./figs/particle_file.pdf, id=820, 390.14703pt x 291.52518pt>
 File: ./figs/particle_file.pdf Graphic file (type pdf)
 <use ./figs/particle_file.pdf>
-Package pdftex.def Info: ./figs/particle_file.pdf  used on input line 1582.
+Package pdftex.def Info: ./figs/particle_file.pdf  used on input line 1607.
 (pdftex.def)             Requested size: 341.43306pt x 255.13727pt.
 
-Overfull \hbox (18.38263pt too wide) in paragraph at lines 1591--1592
+Overfull \hbox (18.38263pt too wide) in paragraph at lines 1616--1617
 \T1/cmr/m/n/10 we run the rel-e-vant func-tions: \T1/cmtt/m/n/10 get_voxel_dict
 ionary() $\OMS/cmsy/m/n/10 !$ \T1/cmtt/m/n/10 list_candidates() $\OMS/cmsy/m/n/
 10 !$ \T1/cmtt/m/n/10 get_particles()\T1/cmr/m/n/10 ,
  []
 
-[29] [30 <./figs/particle_file.pdf>]
-<./figs/trajectory_files.pdf, id=840, 470.98941pt x 297.17282pt>
+[30] [31 <./figs/particle_file.pdf>]
+<./figs/trajectory_files.pdf, id=856, 470.98941pt x 297.17282pt>
 File: ./figs/trajectory_files.pdf Graphic file (type pdf)
 <use ./figs/trajectory_files.pdf>
-Package pdftex.def Info: ./figs/trajectory_files.pdf  used on input line 1653.
+Package pdftex.def Info: ./figs/trajectory_files.pdf  used on input line 1678.
 (pdftex.def)             Requested size: 284.52756pt x 179.52937pt.
- [31 <./figs/trajectory_files.pdf>]
-<./figs/smoothed_trajfile.pdf, id=864, 514.2885pt x 471.065pt>
+ [32 <./figs/trajectory_files.pdf>]
+<./figs/smoothed_trajfile.pdf, id=880, 514.2885pt x 471.065pt>
 File: ./figs/smoothed_trajfile.pdf Graphic file (type pdf)
 <use ./figs/smoothed_trajfile.pdf>
-Package pdftex.def Info: ./figs/smoothed_trajfile.pdf  used on input line 1699.
+Package pdftex.def Info: ./figs/smoothed_trajfile.pdf  used on input line 1724.
 
 (pdftex.def)             Requested size: 341.43306pt x 312.73677pt.
 
-[32 <./figs/smoothed_trajfile.pdf>] (./user_manual.bbl)
-Package atveryend Info: Empty hook `BeforeClearDocument' on input line 1751.
- [33]
-Package atveryend Info: Empty hook `AfterLastShipout' on input line 1751.
+[33 <./figs/smoothed_trajfile.pdf>] (./user_manual.bbl)
+Package atveryend Info: Empty hook `BeforeClearDocument' on input line 1776.
+ [34]
+Package atveryend Info: Empty hook `AfterLastShipout' on input line 1776.
  (./user_manual.aux)
-Package atveryend Info: Executing hook `AtVeryEndDocument' on input line 1751.
-Package atveryend Info: Executing hook `AtEndAfterFileList' on input line 1751.
+Package atveryend Info: Executing hook `AtVeryEndDocument' on input line 1776.
+Package atveryend Info: Executing hook `AtEndAfterFileList' on input line 1776.
 
 Package rerunfilecheck Info: File `user_manual.out' has not changed.
 (rerunfilecheck)             Checksum: 6B1FC7423BCD656429F1554E9D5FD6BE;4619.
 
 
 LaTeX Font Warning: Some font shapes were not available, defaults substituted.
 
-Package atveryend Info: Empty hook `AtVeryVeryEnd' on input line 1751.
+Package atveryend Info: Empty hook `AtVeryVeryEnd' on input line 1776.
  ) 
 Here is how much of TeX's memory you used:
- 10222 strings out of 493756
- 149042 string characters out of 6152244
- 283327 words of memory out of 5000000
- 13307 multiletter control sequences out of 15000+600000
+ 10236 strings out of 493756
+ 149362 string characters out of 6152244
+ 285708 words of memory out of 5000000
+ 13316 multiletter control sequences out of 15000+600000
  25774 words of font info for 69 fonts, out of 8000000 for 9000
  645 hyphenation exceptions out of 8191
  36i,14n,49p,1169b,458s stack positions out of 5000i,500n,10000p,200000b,80000s
@@ -858,10 +868,10 @@ sr/share/texmf/fonts/type1/public/cm-super/sfsx2488.pfb></usr/share/texmf/fonts
 er/sftt0900.pfb></usr/share/texmf/fonts/type1/public/cm-super/sftt1000.pfb></us
 r/share/texmf/fonts/type1/public/cm-super/sftt1200.pfb></usr/share/texmf/fonts/
 type1/public/cm-super/sftt1440.pfb>
-Output written on user_manual.pdf (36 pages, 4316897 bytes).
+Output written on user_manual.pdf (37 pages, 4446892 bytes).
 PDF statistics:
- 1019 PDF objects out of 1200 (max. 8388607)
- 876 compressed objects within 9 object streams
- 235 named destinations out of 1000 (max. 500000)
- 572 words of extra memory for PDF output out of 10000 (max. 10000000)
+ 1038 PDF objects out of 1200 (max. 8388607)
+ 891 compressed objects within 9 object streams
+ 239 named destinations out of 1000 (max. 500000)
+ 577 words of extra memory for PDF output out of 10000 (max. 10000000)
 

user_manual/user_manual.tex

@@ -1060,7 +1060,7 @@ \subsection{Stitching}\label{sec:workflow_stitch}
 
 \begin{table}[!ht]
 	\centering
-	\caption{The \texttt{params\_file.yml} parameters for the smoothing step. All paths to files are relative to the \texttt{workflow.py} script.}
+	\caption{The \texttt{params\_file.yml} parameters for the \texttt{smoothing} command. All paths to files are relative to the \texttt{workflow.py} script.}
 	\begin{tabular}{l m{12cm}}
 		\hline
 		Parameter & Description\\
@@ -1121,21 +1121,21 @@ \subsection{2D tracking guide} \label{sec:2D_tracking}
 %
 \begin{table}[!ht]
 	\centering
-	\caption{The \texttt{params\_file.yml} parameters for the 2D tracking step. All paths to files are relative to the \texttt{workflow.py} script. \label{tab:2d_tracking}}
+	\caption{The \texttt{params\_file.yml} parameters for 2D tracking. All paths to files are relative to the \texttt{workflow.py} script. \label{tab:2d_tracking}}
 	\begin{tabular}{l m{12cm}}
 		\hline
-		Parameter & Description\\
+		Parameter & Description\\[.2cm]
 		\hline
 
-		\texttt{blob\_file} & The name of the file that contains the segmentation results \\
-		\texttt{frame\_start} & The number of the first frame from which we want to perform 2D tracking \\
-		\texttt{N\_frames} & The number of frames to be analyzed; If \texttt{None}, then all the frames will be analyzed \\
-		\texttt{camera\_name} & the name of the camera from which the images were taken (must be a calibrated camera) \\
-		\texttt{camera\_resolution} & A tuple representing the camera resolution, for example, (1280, 1024) \\
-		\texttt{z\_particles} & The value of the z coordinate of the plane on which the particles are found, e.g. 0.0 \\
-		\texttt{d\_max} &  The maximum allowable particle translation between frame in lab-coordinates\\
-		\texttt{dv\_max} & The maximum allowable change of velocity for the particles in lab-space coordinates per frame (e.g. mm/frame) \\
-		\texttt{save\_name} & The name of the file used to save the results \\
+		\texttt{blob\_file} & The name of the file that contains the segmentation results \\[.2cm]
+		\texttt{frame\_start} & The number of the first frame from which we want to perform 2D tracking \\[.2cm]
+		\texttt{N\_frames} & The number of frames to be analyzed; If \texttt{None}, then all the frames will be analyzed \\[.2cm]
+		\texttt{camera\_name} & the name of the camera from which the images were taken (must be a calibrated camera) \\[.2cm]
+		\texttt{camera\_resolution} & A tuple representing the camera resolution, for example, (1280, 1024) \\[.2cm]
+		\texttt{z\_particles} & The value of the z coordinate of the plane on which the particles are found, e.g. 0.0 \\[.2cm]
+		\texttt{d\_max} &  The maximum allowable particle translation between frame in lab-coordinates\\[.2cm]
+		\texttt{dv\_max} & The maximum allowable change of velocity for the particles in lab-space coordinates per frame (e.g. mm/frame) \\[.2cm]
+		\texttt{save\_name} & The name of the file used to save the results \\[.2cm]
 
 		\hline
 	\end{tabular}
@@ -1164,12 +1164,12 @@ \subsection{Manual Matching GUI} \label{sec:man_match}
 	\caption{The \texttt{params\_file.yml} parameters for the manual matching operation. All paths to files are relative to the \texttt{workflow.py} script. \label{tab:man_match}}
 	\begin{tabular}{l m{12cm}}
 		\hline
-		Parameter & Description\\[.3em]
+		Parameter & Description\\[.2cm]
 		\hline
 		%
-		\texttt{cameras} & a list that holds the names of the cameras used; for example [cam1, cam2, cam3]. Note that the camera files need to be in the same folder where we are running the workflow script\\[.3em]
+		\texttt{cameras} & a list that holds the names of the cameras used; for example [cam1, cam2, cam3]. Note that the camera files need to be in the same folder where we are running the workflow script\\[.2cm]
 		%
-		\texttt{images} & the paths of the images from which matching should be performed. \\[.3em]
+		\texttt{images} & the paths of the images from which matching should be performed. \\[.2cm]
 		\hline
 	\end{tabular}
 \end{table}
@@ -1214,20 +1214,20 @@ \subsection{Fiber tracking} \label{sec:fibers}
 	\caption{The \texttt{params\_file.yml} parameters for the \texttt{fiber\_orientations} operation. All paths to files are relative to the \texttt{workflow.py} script. \label{tab:fibers}}
 	\begin{tabular}{l m{12cm}}
 		\hline
-		Parameter & Description\\
+		Parameter & Description\\[.2cm]
 		\hline
 		%
-		\texttt{camera\_names} & a list of the camera names, e.g. [cam1, cam2, cam3]. Note that the camera files need to be in the same folder where we are running the workflow script\\[.3em]
+		\texttt{camera\_names} & a list of the camera names, e.g. [cam1, cam2, cam3]. Note that the camera files need to be in the same folder where we are running the workflow script\\[.2cm]
 		%
-		\texttt{cam\_resolution} & A tuple for the number of pixels in each axis. \\[.3em]
+		\texttt{cam\_resolution} & A tuple for the number of pixels in each axis. \\[.2cm]
 		%
-		\texttt{blob\_files} & The name of the files that hold the results of the \textbf{blob orientations}. \\[.3em]
+		\texttt{blob\_files} & The name of the files that hold the results of the \textbf{blob orientations}. \\[.2cm]
 		%
-		\texttt{fibers\_file} & The file name with the results of the matching stage. \\[.3em]
+		\texttt{fibers\_file} & The file name with the results of the matching stage. \\[.2cm]
 		%
-		\texttt{trajectory\_file} & The file name with the results of the tracking stage. \\[.3em]
+		\texttt{trajectory\_file} & The file name with the results of the tracking stage. \\[.2cm]
 		%
-		\texttt{save\_name} & The file name that should be used to save the results of the orientation measurements. \\[.3em]
+		\texttt{save\_name} & The file name that should be used to save the results of the orientation measurements. \\[.2cm]
 		\hline
 	\end{tabular}
 \end{table}
@@ -1240,12 +1240,37 @@ \subsection{Fiber tracking} \label{sec:fibers}
 
 \subsection{Plotting the results} \label{sec:plot_trajectories}
 
-Once the post processing is finished, you might want to plot the results. 
-A basic 3D rendering pf the trajectories obtained can be established with
-the workflow command \texttt{plot\_trajectories}.
+Once the post processing is finished, we might want to plot trajectories in order to visualize the results. A basic 3D rendering of measured trajectories can be established with the workflow command \texttt{plot\_trajectories}. As example is shown in Fig.~\ref{fig:trajectory_plot}. The parameters for the plotting function are explained in Tab.~\ref{tab:plotting_parameter}.
 
 
 
+\begin{figure}
+	\centering
+	\includegraphics[width=8cm]{trajectory_plot.pdf}
+	\caption{Trajectory segments plotted using the workflow \texttt{plot\_trajectories} command. A 30 frames long segment is shown from a turbulent flow dataset taken from Ref.~\cite{Shnapp2023}. \label{fig:trajectory_plot}}
+\end{figure}
+
+
+%
+\begin{table}[!ht]
+	\centering
+	\caption{The \texttt{params\_file.yml} parameters for the \texttt{plot\_trajectories} operation. All paths to files are relative to the \texttt{workflow.py} script. \label{tab:plotting_parameter}}
+	\begin{tabular}{l m{12cm}}
+		\hline
+		Parameter & Description\\[.2cm]
+		\hline
+		%
+		\texttt{file\_name} & the path to the file that contains the trajectories; the file can be either in trajectories format or in smoothed trajectories format. \\[.2cm]
+		%
+		\texttt{min\_lenth} & only trajectories that have more samples than this number will be plotted.\\[.2cm]
+		%
+		\texttt{write\_trajID} & If True this will desplay the trajectory ID on top of them.\\[.2cm]
+		%
+		\texttt{t0} and \texttt{te} & Used to delineate the time range for which we plot the data. We only plot the samples in the time range starting at frame \texttt{t0} and ending at frame \texttt{te}. Set \texttt{t0=0} and \texttt{te=-1} to plot trajectories at all times available. \\[.2cm]
+		%
+		\hline
+	\end{tabular}
+\end{table}