documentation (with Oleksandr)

include/PinkIndexer.h

@@ -49,12 +49,15 @@ namespace pinkIndexer
         PinkIndexer(const ExperimentSettings& experimentSettings, ConsideredPeaksCount consideredPeaksCount, AngleResolution angleResolution,
                     RefinementType refinementType, float maxResolutionForIndexing_1_per_A);
 
+		// main function
         int indexPattern(Lattice& indexedLattice, Eigen::Vector2f& centerShift, Eigen::Array<bool, Eigen::Dynamic, 1>& fittedPeaks,
                          Eigen::RowVectorXf& intensities, const Eigen::Matrix2Xf& detectorPeaks_m, int threadCount);
-        int indexPattern(Lattice& indexedLattice, Eigen::Vector2f& centerShift, Eigen::Array<bool, Eigen::Dynamic, 1>& fittedPeaks,
+        // for crystfel
+		int indexPattern(Lattice& indexedLattice, Eigen::Vector2f& centerShift, Eigen::Array<bool, Eigen::Dynamic, 1>& fittedPeaks,
                          Eigen::RowVectorXf& intensities, const Eigen::Matrix3Xf& meanReciprocalPeaks_1_per_A, int threadCount);
 
       private:
+		// reduces number of peaks according to parameter "ConsideredPeaksCount"
         void reducePeakCount(Eigen::Matrix3Xf& ucsDirections, Eigen::Array2Xf& ucsBorderNorms, Eigen::RowVectorXf& intensities,
                              const Eigen::Matrix2Xf& detectorPeaks_m);
         void refine(Lattice& indexedLattice, Eigen::Vector2f& centerShift, const Eigen::Matrix3Xf& ucsDirections, const Eigen::Array2Xf& ucsBorderNorms,
@@ -73,6 +76,6 @@ namespace pinkIndexer
         AngleResolution angleResolution;
         RefinementType refinementType;
         float maxResolutionForIndexing_1_per_A;
-        float finalRefinementTolerance;
+        float finalRefinementTolerance;  //from command line in crystfel
     };
 } // namespace pinkIndexer
\ No newline at end of file

src/PinkIndexer.cpp

@@ -48,15 +48,15 @@ namespace pinkIndexer
         if (detectorPeaks_m.cols() < 2)
             return 0;
 
-        Matrix3Xf ucsDirections;
-        Array2Xf ucsBorderNorms;
+        Matrix3Xf ucsDirections; // Unit vector of ULS
+        Array2Xf ucsBorderNorms; // 2 borders between intersection with the 2 Ewald spheres
         backprojection.backProject(detectorPeaks_m, ucsDirections, ucsBorderNorms);
 
         Matrix3Xf ucsDirections_reduced = ucsDirections;
         Array2Xf ucsBorderNorms_reduced = ucsBorderNorms;
         reducePeakCount(ucsDirections_reduced, ucsBorderNorms_reduced, intensities, detectorPeaks_m);
 
-        if (threadCount == 1)
+        if (threadCount == 1) //threads from crystfel (--pinkIndexer_thread_count)
         {
             sinogram.computeSinogram(ucsDirections_reduced, ucsBorderNorms_reduced);
         }
@@ -79,8 +79,9 @@ namespace pinkIndexer
         refine(indexedLattice, centerShift, ucsDirections, ucsBorderNorms, detectorPeaks_m, threadCount);
 
         indexedLattice.minimize();
-        indexedLattice.reorder(sampleLattice);
+        indexedLattice.reorder(sampleLattice);  //reorder lattice vectors to match sample lattice (from crystfel)
 
+		// return how many peaks have been fitted correctly (according to tolerance)
         return refinement.getFittedPeaks(indexedLattice, fittedPeaks, ucsDirections, ucsBorderNorms);
 
         // sinogram.saveToFile("C:\\DesyFiles\\workspaces\\VisualStudio_workspace\\pinkIndexer\\workfolder\\sinogram");
@@ -327,6 +328,7 @@ namespace pinkIndexer
 
     float PinkIndexer::getAngleResolution()
     {
+		// angluar step in sinogram (in degree)
         switch (angleResolution)
         {
             case AngleResolution::extremelyLoose:

src/Sinogram.cpp

@@ -74,15 +74,15 @@ namespace pinkIndexer
     {
         sinogram.setZero();
 
-        EigenSTL::vector_Matrix3Xf candidateReflectionsDirections;
-        reflectionsInRangeFinder.getReflectionsInRanges(candidateReflectionsDirections, ucsBorderNorms);
+        EigenSTL::vector_Matrix3Xf candidateReflectionsDirections;	//unit vectors to all candidate reflections
+        reflectionsInRangeFinder.getReflectionsInRanges(candidateReflectionsDirections, ucsBorderNorms);	//get candidate reflections
 
-        Matrix3Xf n(3, anglesCount);
-        Array<float, 1, Eigen::Dynamic> gammah(anglesCount); // gamma half
-        Matrix<uint32_t, 3, Eigen::Dynamic> validSinogramPoints_matrix(3, anglesCount);
-        Matrix<uint32_t, 1, Eigen::Dynamic> validSinogramPoints_matrix_lin(1, anglesCount);
+        Matrix3Xf n(3, anglesCount);	//resulting rotation axes
+        Array<float, 1, Eigen::Dynamic> gammah(anglesCount); // gamma half - resulting rotation angle (around n)
+        Matrix<uint32_t, 3, Eigen::Dynamic> validSinogramPoints_matrix(3, anglesCount);		// coordinates (3D) of sampled curve in sinogram
+        Matrix<uint32_t, 1, Eigen::Dynamic> validSinogramPoints_matrix_lin(1, anglesCount);	//linear indices (1D) of validSinogramPoints_matrix
 
-        Matrix<uint32_t, 28, 1> validSinogramPoints_matrix_lin_dilated;
+        Matrix<uint32_t, 28, 1> validSinogramPoints_matrix_lin_dilated;  //all voxels neigboring one single voxel (in sinogram)
 
         int measuredPeaksCount = ucsDirections.cols();
         cout << "peak count used for indexing: " << measuredPeaksCount << endl;
@@ -99,9 +99,9 @@ namespace pinkIndexer
             if (candidateReflectionDirections.cols() == 0)
                 continue;
 
-            sinogram_oneMeasuredPeak.setZero();
+            sinogram_oneMeasuredPeak.setZero();	//sinogram for one Bragg spot (from detector)
             int candidatePeaksCount = candidateReflectionDirections.cols();
-            for (int candidatePeakNumber = 0; candidatePeakNumber < candidatePeaksCount; candidatePeakNumber++)
+            for (int candidatePeakNumber = 0; candidatePeakNumber < candidatePeaksCount; candidatePeakNumber++)	//calculation of curves for each candidate peak
             {
                 const auto& candidateReflectionDirection = candidateReflectionDirections.col(candidatePeakNumber);
 
@@ -116,6 +116,7 @@ namespace pinkIndexer
                 validSinogramPoints_matrix = ((validSinogramPoints * realToMatrixScaling).array() + realToMatrixOffset).matrix().cast<uint32_t>();
                 validSinogramPoints_matrix_lin = validSinogramPoints_matrix.row(0) + strides * validSinogramPoints_matrix.bottomRows(2);
 
+				// for each point from the curve, dilate it and insert into sinogram
                 for (uint32_t *linIdx = validSinogramPoints_matrix_lin.data(),
                               *end = validSinogramPoints_matrix_lin.data() + validSinogramPoints_matrix_lin.size();
                      linIdx < end; linIdx++)
@@ -287,6 +288,7 @@ namespace pinkIndexer
         maxElementSub(1) = maxElementIdx / strides(0);
         maxElementSub(0) = maxElementIdx - maxElementSub(1) * strides(0);
 
+		// TODO: might be improved by proper search of centor of mass
         Vector3f centerOfMassSub_f;
         Matrix<uint32_t, 3, 1> centerOfMassSub, oldCenterOfMassSub = maxElementSub;
         int maxIterationCount = 5;
@@ -299,6 +301,7 @@ namespace pinkIndexer
             oldCenterOfMassSub = centerOfMassSub;
         }
 
+		// calculation from siogram coordinates to vector coordinates
         Vector3f bestRotationVector = centerOfMassSub_f - Vector3f(sinogramCenter, sinogramCenter, sinogramCenter);
         Vector3f bestAxis = bestRotationVector.normalized();
         float bestAngle = tan(bestRotationVector.norm() * sinogramScale * atan(M_PI / 4)) * 4;