Sometimes, you might want to compare the orientations of grains between two collections, to make sure that they are the same, for instance.

A typical case when you perform this operation is during training. If you generated a synthetic dataset and indexed this data, you will want to make sure that the grains you indexed actually existed at start.

This operation is performed using the timelessGrainComparison script, which is part of the TIMEleSS tools.

Here is the output of the help command

timelessGrainComparison --help
usage: timelessGrainComparison [options] file1 file2

Compare grains between 2 files This is part of the TIMEleSS project
http://timeless.texture.rocks

positional arguments:
  file1                 first grain file, used as a reference (gff or
                        GrainSpotter output file, based on extension)
  file2                 second grain file, matched against the previous file
                        (gff or GrainSpotter output file, based on extension)

optional arguments:
  -h, --help            show this help message and exit
  -c {1,2,3,4,5,6,7}, --crystal_system {1,2,3,4,5,6,7}
                        Crystal system. Can be one of the following 1:
                        Triclinic 2: Monoclinic 3: Orthorhombic 4: Tetragonal
                        5: Trigonal 6: Hexagonal 7: Cubic
  -o OUTPUT_STEM, --output_stem OUTPUT_STEM
                        Stem for output files. Default is comp
  -m MISORIENTATION, --misorientation MISORIENTATION
                        Misorientation below which two grains are considered
                        identical, in degrees. Default is 2.0

As an illustration, will will work with synthetic data on stishovite. The following file, simu_stishovite_10grain2.gff , is the result of a PolyXSim simulation for stishovite. It includes the orientations of 10 stishovite grains, randomly oriented.

The author ran a GrainSpotter indexing and generated a GrainSpotter log file: stishovite_10grain2.log.

We want to make sure that the grains indexed by GrainSpotter are the same than those we had in the simulation. In other words, we want to test that our indexing makes sense.

The grain comparison is run as follow

timelessGrainComparison -c 4 -o test-stish simu_stishovite_10grain2.gff stishovite_10grain2.log

We use a tetragonal symmetry (c is set to 4), output files will start with test-stish, the reference grains are found in simu_stishovite_10grain2.gff and we are checking whether the grains in stishovite_10grain2.log are correct.

timelessGrainComparison can read gff or GrainSpotter log files. What matters is the order in which you provide the files. The first file is the reference, the second file will be checked.

You should get the following output in your terminal. In this case, the user did an excellent job. He indexed the 10 grains, with no erroneous grains. All grains are indexed with an orientation error of 0.01° or less. This is not always true! Your should be careful and train yourself with complex examples…

3 output files will be generated: 
- test-stish-log.dat,
- test-stish-matching-grains.dat,
- test-stish-erroneous-grains.dat

Parsed simu_stishovite_10grain2.gff, found 10 grains
Parsed stishovite_10grain2.log, found 10 grains

Misorientation below which the two grains are considered identical, in degrees: 2.0

Check for doubles in simu_stishovite_10grain2.gff
Found 0 grains indexed twice
New number of grains: 10

Check for doubles in stishovite_10grain2.log
Found 0 grains indexed twice
New number of grains: 10

Trying to match grains between the 2 collections...
- Grain Grain-1 of simu_stishovite_10grain2.gff matches Grain-1 of stishovite_10grain2.log with a misorientation of 0.00°
- Grain Grain-9 of simu_stishovite_10grain2.gff matches Grain-2 of stishovite_10grain2.log with a misorientation of 0.01°
- Grain Grain-6 of simu_stishovite_10grain2.gff matches Grain-3 of stishovite_10grain2.log with a misorientation of 0.01°
- Grain Grain-7 of simu_stishovite_10grain2.gff matches Grain-4 of stishovite_10grain2.log with a misorientation of 0.00°
- Grain Grain-10 of simu_stishovite_10grain2.gff matches Grain-5 of stishovite_10grain2.log with a misorientation of 0.00°
- Grain Grain-4 of simu_stishovite_10grain2.gff matches Grain-6 of stishovite_10grain2.log with a misorientation of 0.00°
- Grain Grain-8 of simu_stishovite_10grain2.gff matches Grain-7 of stishovite_10grain2.log with a misorientation of 0.01°
- Grain Grain-2 of simu_stishovite_10grain2.gff matches Grain-8 of stishovite_10grain2.log with a misorientation of 0.00°
- Grain Grain-5 of simu_stishovite_10grain2.gff matches Grain-9 of stishovite_10grain2.log with a misorientation of 0.00°
- Grain Grain-3 of simu_stishovite_10grain2.gff matches Grain-1 of stishovite_10grain2.log with a misorientation of 0.01°
End of run

N. of grains in simu_stishovite_10grain2.gff: 10
N. of unique grains in simu_stishovite_10grain2.gff: 10
N. of grains in stishovite_10grain2.log: 10
N. of unique grains in stishovite_10grain2.log: 10
N. of unique grains found in both simu_stishovite_10grain2.gff and stishovite_10grain2.log: 10
N. of unique grains found only in stishovite_10grain2.log: 0
N. of unique grains found in simu_stishovite_10grain2.gff but not in stishovite_10grain2.log: 0

Indexing capability
- 100.0 pc of simu_stishovite_10grain2.gff grains indexed
- 0.0 pc of simu_stishovite_10grain2.gff grains not indexed
- 0.0 pc of erroneous grains in stishovite_10grain2.log

There are 3 text files that can be used for further processing. From the previous examples, the output files are

• test-stish-log.dat: a summary of the run,
• test-stish-matching-grains.dat: information on matching grains (grains that were in the original list and were indexed, actually,
• test-stish-erroneous-grains.dat : information on erroneous grains (grains that were indexed but should not have been there).