User manual MuhRec
Table of contents
\section{Spatio-temporal tomography} When the sample change shape or composition during the acquisition, the reconstructed data will suffer from motion artefacts. The impact of these artefacts can be reduced by using an alternative acqiusition scheme based on the angles computed using the Golden ratio. MuhRec supports projection data acquired using this scheme. You can tell the reconstructor that the projections are acquired using this scheme by selecting mode (Sequential/Golden ratio) in the Geometry field. With the Golden ratio it also possible to select number of projections after the acquisition. This an advantage when you don't know how fast the observed process is\cite{kaestner2011_golden}.
\section{Tilt correction} When the turn table and detector are not aligned there will be an error in the reconstructed data. For small deviations this error can be corrected by adjusting the center of rotation for each slice. In MuhRec you have two parameters for the tilt correction. The first is the axis tilt angle and the other set the pivot point relative to the image.
The pivot is used for long samples where the turn table is located far away from the detector. For a single data set this parameter is less important than when you have several scans that you want to merge after the completed reconstruction. It is not possible to correct for both detector and pivot tilt simultaneously in the current version. Figure \ref{fig_axistilt} shows the two different detector rotations.
\begin{figure}[ht!] \centering \includegraphics{figures/axis_tilt.pdf} \caption{Possible acquisition axis tilts.}\label{fig_axistilt} \end{figure}
\section{Reconstructing from the command line}\label{sec_cmdline} In addition to the GUI you can also start MuhRec from the command line. This can done by typing \begin{verbatim} muhrec3 -f parameters.xml \end{verbatim} The file parameters.xml contains all settings needed for the reconstruction. This is also the same type of files written by GUI. In appendix \ref{sec_fileformat} an example of the parameter file is given.
The command line option is useful for batch reconstructions. The parameter files for all reconstruction jobs can be prepared with the GUI. In some cases there are only a few parameters that change between the data sets. In this case you can add these parameters on the command line using the format: \begin{verbatim} muhrec3 -f parameters.xml block1:parameter1=value1 block2:parameter2=value2 \end{verbatim} The \verb+block+ is the xml block in the parameter file (userinformation, system, projections, matrix) and \verb+parameter+ is the parameter you want to modify with \verb+value+. Please note that each parameter argument must be a single string each space will be interpreted as delimiter for a new argument. Therefore if you want to change an array parameter you have to use "\ldots" to enclose the argument. Eg. \begin{verbatim} muhrec3 -f parameters.xml "projections:roi=10 10 100 100" \end{verbatim} Muhrec use less memory when it is operated in CLI mode.
\subsubsection{Invoking Muhrec from a script} Sometimes it is convenient to use a script to run muhrec. Here is an example using python. The example uses the CLI interface, which may not be the best way but at least it solves the problem. \begin{verbatim} #!/usr/bin/env python
print("Processing some frames.")
projpath="/Volumes/DataDisk/P20140142" destpath=projpath+"/04_evaluation/20141126" muhrec="/Users/kaestner/Applications/muhrec3.app/Contents/MacOS/muhrec3" cfgpath=projpath+"/04_evaluation/20141126/recon_roots.xml"
from subprocess import call from math import fmod firstproj=1; firstframe=0 lastframe=3 for i in range(firstframe,lastframe) : # select projection sub set firstindex="projections:firstindex="+str(firstproj+i*180) lastindex="projections:lastindex="+str(firstproj+(i+1)*180) # set file mask for the slices matrixname="matrix:matrixname=frame_"+("%04d" % i)+"-slice_####.tif" # adjust the reconstruction angles to alternating between 0-180 and 180-360 angle=fmod(i,2)*180 scanarc="projections:scanarc="+str(angle)+" "+str(angle+180) # call the reconstruction call([muhrec, "-f", cfgpath, firstindex, lastindex, matrixname, scanarc]) \end{verbatim}
This script assumes that you have a well configured Recon.xml file and that the data is acquired as a long sequence, e.g. a time series of CTs.
\chapter{Continued development} MuhRec is continuously developing to adapt to new challenges at the neutron imaging beamlines at Paul Scherrer Institut. Unfortunately, it is not only new development but also bug fixing. To fix bug the input from users is important, so I kindly ask you to report problems when the software misbehaves.
For the continued development it also important with feedback regarding improvements of existing and new features. So, if you have any comments that you would like to share I appreciate if you send them to me. I cannot promise that I will implement everything but I will at least consider it.
\bibliographystyle{plain} \bibliography{../../../../doc/references} \appendix \chapter{License} Definitions: The software refers to any revision of MuhRec. The author Anders Kaestner is referred to as the author. Any person who installed and intends to use or uses the software is referred to as the user. \begin{itemize} \item The user is allowed to install and use the software free of charge. \item The software is delivered as is. The author gratefully receives bug reports and feature requests but can not promise any updates. In case of updates the user will be notified. \item The author takes no responsibility for the use of the software and the accuracy of the results. \item The user is \emph{strongly discouraged} from using the software for medical applications. \item If you use the results in a publication. The following publication should cited: Anders P. Kaestner, \emph{MuhRec -- A new tomography reconstructor}, Nuclear Instruments and Methods in Physics Research Section A: Accelerators, Spectrometers, Detectors and Associated Equipment Volume 651, Issue 1, 21 September 2011, Pages 156-160, doi:10.1016/j.nima.2011.01.129
\end{itemize} \chapter{Parameter file format}\label{sec_fileformat} The parameter file is formatted with xml and is divided into subsections. Here the default parameter file is shown: \begin{verbatim} Anders Kaestner ICON P11048 Curse tablet No comment
<system>
<memory>6000</memory>
<loglevel>message</loglevel>
</system>
<projections>
<dims>2048 2048</dims>
<resolution>0.0135 0.0135</resolution>
<firstindex>1</firstindex>
<lastindex>625</lastindex>
<projectionstep>1</projectionstep>
<repeatline>false</repeatline>
<scantype>sequential</scantype>
<imagetype>projections</imagetype>
<center>568</center>
<translation>false</translation>
<tiltangle>0</tiltangle>
<tiltpivot>0</tiltpivot>
<correcttilt>false</correcttilt>
<filemask>tablet_####.fits</filemask>
<path>/home/data/P11048_tablet/tomo/</path>
<referencepath>/home/data/P11048_tablet/tomo/</referencepath>
<obfilemask>ob_####.fits</obfilemask>
<obfirstindex>1</obfirstindex>
<obcount>5</obcount>
<dcfilemask>dc_####.fits</dcfilemask>
<dcfirstindex>1</dcfirstindex>
<dccount>5</dccount>
<roi>600 400 1700 432</roi>
<doseroi>300 600 350 800</doseroi>
<scanarc>0 360</scanarc>
</projections>
<matrix>
<dims>1100 1100 32</dims>
<rotation>0</rotation>
<serialize>false</serialize>
<path>/home/kaestner/work/svn/</path>
<matrixname>tablet_####.tif</matrixname>
<filetype>TIFF16bits</filetype>
<firstindex>0</firstindex>
<grayinterval>-1 0.728486</grayinterval>
</matrix>
<processchain>
<preprocessing>
<module>
<modulename>FullLogNorm</modulename>
<sharedobject>libStdPreprocModules.so</sharedobject>
<active>true</active>
<parameters>
<uselut>false</uselut>
<usenormregion>true</usenormregion>
</parameters>
</module>
<module>
<modulename>SpotClean2</modulename>
<sharedobject>libStdPreprocModules.so</sharedobject>
<active>true</active>
<parameters>
<gamma>0.03</gamma>
<iterations>1</iterations>
<maxlevel>12</maxlevel>
<minlevel>0.0</minlevel>
<sigma>0.005</sigma>
</parameters>
</module>
<module>
<modulename>MedianMixRingClean</modulename>
<sharedobject>libStdPreprocModules.so</sharedobject>
<active>true</active>
<parameters>
<threshold>0.01</threshold>
<width>0.001</width>
</parameters>
</module>
<module>
<modulename>ProjectionFilterSingle</modulename>
<sharedobject>libStdPreprocModules.so</sharedobject>
<active>true</active>
<parameters>
<cutoff>0.5</cutoff>
<filtertype>hamming</filtertype>
<order>0</order>
<usebias>true</usebias>
</parameters>
</module>
</preprocessing>
<backprojector>
<module>
<modulename>MultiProjBP</modulename>
<sharedobject>libStdBackProjectors.so</sharedobject>
<active>true</active>
<parameters>
<ProjectionBufferSize>16</ProjectionBufferSize>
<SliceBlock>64</SliceBlock>
<SubVolume>1</SubVolume>
</parameters>
</module>
</backprojector>
</processchain>
\chapter{Intended new features} \begin{enumerate} \item Flip, and 90$^{\circ}$ rotations. \item True rotation of the projections. \item Center estimation by reconstruction. \item Add a module for QNI for the projections. QNI is a method to reduce the impact of scattering on the data. It often makes it possible to quantify the water content in a sample. \item Your suggestions. \end{enumerate}
\chapter{Known bugs and limitations\ldots} \section{Limitations} \begin{enumerate} \item Center of rotation can not be found for translated projection data. \end{enumerate} \section{Known bugs} \begin{itemize} \item The reconstructor may crash when the number of slices is not a factor of 4. \item The translated center reconstruction does not reconstruct correctly near the center of rotation. This is especially noticeable when tilt correction is activated \item Muhrec may crash, if you use the projection slider too much or rapidly. \item Reconstruction progress dialog does not work on windows (hence deactivated). \item The module selection list in add module is not cleared when a new object file is opened. \item Zooming and panning in the viewer is incomplete. \end{itemize} \end{document}
%%%%%%%%% This text will reappear after
\subsection{RobustLogNorm}
This modules implements the normalization of projection data to reference images, including open beam, dark current and images with black bodies (BB). The full normalization operation is computed using:
\begin{equation}
p=-\log\left(\frac{D_0}{D}\cdot\frac{I-I_{DC}-I_{BG}^{sample}}{I_{OB}-I_{DC}-I_{BG}^{OB}}\right)
\end{equation}
where background images (BG) are computed from BB images (background image computed from open beam images with BBs:
\item \textit{tau}: mean transmission pattern. It is a parameter which contributes in the computation of background images and can be changed in order to obtain more flat profiles and empty regions closed to zero by lowering its value. Default value = 0.99;
\end{itemize}
Object file: libStdPreprocModules.so
