/// <summary>
        ///
        /// </summary>
        /// <param name="timepoints"></param>
        /// <param name="protractor"></param>
        /// <returns></returns>
        public NBestList Recognize(List <TimePointF> timepoints, bool protractor)       // candidate points
        {
            double        I       = GeotrigEx.PathLength(timepoints) / (NumPoints - 1); // interval distance between points
            List <PointF> points  = TimePointF.ConvertList(SeriesEx.ResampleInSpace(timepoints, I));
            double        radians = GeotrigEx.Angle(GeotrigEx.Centroid(points), points[0], false);

            points = GeotrigEx.RotatePoints(points, -radians);
            points = GeotrigEx.ScaleTo(points, SquareSize);
            points = GeotrigEx.TranslateTo(points, Origin, true);
            List <double> vector = Unistroke.Vectorize(points); // candidate's vector representation

            NBestList nbest = new NBestList();

            foreach (Unistroke u in _gestures.Values)
            {
                if (protractor) // Protractor extension by Yang Li (CHI 2010)
                {
                    double[] best  = OptimalCosineDistance(u.Vector, vector);
                    double   score = 1.0 / best[0];
                    nbest.AddResult(u.Name, score, best[0], best[1]); // name, score, distance, angle
                }
                else // original $1 angular invariance search -- Golden Section Search (GSS)
                {
                    double[] best = GoldenSectionSearch(
                        points,                                 // to rotate
                        u.Points,                               // to match
                        GeotrigEx.Degrees2Radians(-45.0),       // lbound
                        GeotrigEx.Degrees2Radians(+45.0),       // ubound
                        GeotrigEx.Degrees2Radians(2.0)          // threshold
                        );

                    double score = 1.0 - best[0] / HalfDiagonal;
                    nbest.AddResult(u.Name, score, best[0], best[1]); // name, score, distance, angle
                }
            }
            nbest.SortDescending(); // sort descending by score so that nbest[0] is best result
            return(nbest);
        }
        /// <summary>
        /// Tests an entire batch of files. See comments atop MainForm.TestBatch_Click().
        /// </summary>
        /// <param name="subject">Subject identification.</param>
        /// <param name="speed">"fast", "medium", or "slow"</param>
        /// <param name="categories">A list of gesture categories that each contain lists of prototypes (examples) within that gesture category.</param>
        /// <param name="dir">The directory into which to write the output files.</param>
        /// <param name="protractor">If true, uses Protractor instead of Golden Section Search.</param>
        /// <returns>The two filenames of the output file if successful; null otherwise. The main results are in string[0],
        /// while the detailed recognition results are in string[1].</returns>
        public string[] TestBatch(string subject, string speed, List <Category> categories, string dir, bool protractor)
        {
            StreamWriter mw = null; // main results writer
            StreamWriter dw = null; // detailed results writer

            string[] filenames = new string[2];
            try
            {
                // set up a main results file and detailed results file
                int start = Environment.TickCount;
                filenames[0] = String.Format("{0}\\$1({1})_main_{2}.txt", dir, protractor ? "protractor" : "gss", start);  // main results (small file)
                filenames[1] = String.Format("{0}\\$1({1})_nbest_{2}.txt", dir, protractor ? "protractor" : "gss", start); // recognition details (large file)

                mw = new StreamWriter(filenames[0], false, Encoding.UTF8);
                mw.WriteLine("Subject = {0}, Recognizer = $1, Search = {1}, Speed = {2}, StartTime(ms) = {3}", subject, protractor ? "protractor" : "gss", speed, start);
                mw.WriteLine("Subject Recognizer Search Speed NumTraining GestureType RecognitionRate\n");

                dw = new StreamWriter(filenames[1], false, Encoding.UTF8);
                dw.WriteLine("Subject = {0}, Recognizer = $1, Search = {1}, Speed = {2}, StartTime(ms) = {3}", subject, protractor ? "protractor" : "gss", speed, start);
                dw.WriteLine("Correct? NumTrain Tested 1stCorrect Pts Ms Angle : (NBestNames) [NBestScores]\n");

                // determine the number of gesture categories and the number of examples in each one
                int    numCategories = categories.Count;
                int    numExamples   = categories[0].NumExamples;
                double totalTests    = (numExamples - 1) * NumRandomTests;

                // outermost loop: trains on N=1..9, tests on 10-N (for e.g., numExamples = 10)
                for (int n = 1; n <= numExamples - 1; n++)
                {
                    // storage for the final avg results for each category for this N
                    double[] results = new double[numCategories];

                    // run a number of tests at this particular N number of training examples
                    for (int r = 0; r < NumRandomTests; r++)
                    {
                        _gestures.Clear(); // clear any (old) loaded prototypes

                        // load (train on) N randomly selected gestures in each category
                        for (int i = 0; i < numCategories; i++)
                        {
                            int[] chosen = RandomEx.Array(0, numExamples - 1, n, true); // select N unique indices
                            for (int j = 0; j < chosen.Length; j++)
                            {
                                Unistroke p = categories[i][chosen[j]]; // get the prototype from this category at chosen[j]
                                _gestures.Add(p.Name, p);               // load the randomly selected test gestures into the recognizer
                            }
                        }

                        // testing loop on all unloaded gestures in each category. creates a recognition
                        // rate (%) by averaging the binary outcomes (correct, incorrect) for each test.
                        for (int i = 0; i < numCategories; i++)
                        {
                            // pick a random unloaded gesture in this category for testing.
                            // instead of dumbly picking, first find out what indices aren't
                            // loaded, and then randomly pick from those.
                            int[] notLoaded = new int[numExamples - n];
                            for (int j = 0, k = 0; j < numExamples; j++)
                            {
                                Unistroke g = categories[i][j];
                                if (!_gestures.ContainsKey(g.Name))
                                {
                                    notLoaded[k++] = j; // jth gesture in categories[i] is not loaded
                                }
                            }
                            int       chosen = RandomEx.Integer(0, notLoaded.Length - 1); // index
                            Unistroke p      = categories[i][notLoaded[chosen]];          // gesture to test
                            Debug.Assert(!_gestures.ContainsKey(p.Name));

                            // do the recognition!
                            List <PointF> testPts = GeotrigEx.RotatePoints( // spin gesture randomly
                                TimePointF.ConvertList(p.RawPoints),
                                GeotrigEx.Degrees2Radians(RandomEx.Integer(0, 359))
                                );
                            NBestList result   = this.Recognize(TimePointF.ConvertList(testPts), protractor);
                            string    category = Category.ParseName(result.Name);
                            int       correct  = (category == categories[i].Name) ? 1 : 0;

                            dw.WriteLine("{0} {1} {2} {3} {4} {5} {6:F1}{7} : ({8}) [{9}]",
                                         correct,                                // Correct?
                                         n,                                      // NumTrain
                                         p.Name,                                 // Tested
                                         FirstCorrect(p.Name, result.Names),     // 1stCorrect
                                         p.RawPoints.Count,                      // Pts
                                         p.Duration,                             // Ms
                                         Math.Round(result.Angle, 1), (char)176, // Angle tweaking :
                                         result.NamesString,                     // (NBestNames)
                                         result.ScoresString);                   // [NBestScores]

                            results[i] += correct;
                        }

                        // provide feedback as to how many tests have been performed thus far.
                        //double testsSoFar = ((n - 1) * NumRandomTests) + r;
                        //ProgressChangedEvent(this, new ProgressEventArgs(testsSoFar / totalTests)); // callback
                    }

                    //
                    // now create the final results for this N and write them to a file
                    //
                    for (int i = 0; i < numCategories; i++)
                    {
                        results[i] /= (double)NumRandomTests; // normalize by the number of tests at this N
                        Category c = (Category)categories[i];
                        // Subject Recognizer Search Speed NumTraining GestureType RecognitionRate
                        mw.WriteLine("{0} $1 {1} {2} {3} {4} {5:F3}",
                                     subject,
                                     protractor ? "protractor" : "gss",
                                     speed,
                                     n,
                                     c.Name,
                                     Math.Round(results[i], 3)
                                     );
                    }
                }

                // time-stamp the end of the processing
                int end = Environment.TickCount;
                mw.WriteLine("\nEndTime(ms) = {0}, Minutes = {1:F2}", end, Math.Round((end - start) / 60000.0, 2));
                dw.WriteLine("\nEndTime(ms) = {0}, Minutes = {1:F2}", end, Math.Round((end - start) / 60000.0, 2));
            }
            catch (Exception ex)
            {
                Console.WriteLine(ex.Message);
                filenames = null;
            }
            finally
            {
                if (mw != null)
                {
                    mw.Close();
                }
                if (dw != null)
                {
                    dw.Close();
                }
            }
            return(filenames);
        }