21 CatalogRead(), (
int)(values.minMag * 100), values.maxStars,
DegToRad(values.minSeparation));
22 std::cerr <<
"Narrowed catalog has " << narrowedCatalog.size() <<
" stars." << std::endl;
32 std::cerr <<
"Generated database with " << ser.buffer.size() <<
" bytes" << std::endl;
33 std::cerr <<
"Database flagged with " << std::bitset<8 * sizeof(dbFlags)>(dbFlags) << std::endl;
36 pos.Stream().write((
char*)ser.buffer.data(), ser.buffer.size());
42 std::vector<PipelineOutput> outputs = pipeline.Go(input);
54static CLI::Option* AddOutputPathOption(CLI::App* cmd,
55 const std::string& name,
56 std::string& variable,
57 const std::string& description) {
58 return cmd->add_option(name, variable, description)
61 ->option_text(
"[PATH] (no value: stdout)");
68static void AddCatalogNarrowingOptions(CLI::App* cmd,
DatabaseOptions& opts) {
69 const std::string group =
"CATALOG NARROWING OPTIONS";
70 cmd->add_option(
"--min-mag",
72 "Narrows catalog to stars with magnitude less than minimum-magnitude (brighter "
73 "stars have lower magnitudes).")
75 cmd->add_option(
"--max-stars",
77 "Limits catalog to the num-stars brightest stars in the catalog.")
78 ->check(CLI::PositiveNumber)
80 cmd->add_option(
"--min-separation",
82 "Removes stars from the catalog that are within minimum-separation degrees of "
83 "another catalog star. The default option is probably good enough for you.")
84 ->check(CLI::NonNegativeNumber)
89 const std::string group =
"PAIR-DISTANCE KVECTOR DATABASE OPTIONS";
91 CLI::Option* kvector = cmd->add_flag(
"--kvector", opts.kvector,
"Generate a KVector database")
92 ->disable_flag_override()
94 cmd->add_option(
"--kvector-min-distance",
95 opts.kvectorMinDistance,
96 "Sets the minimum distance bin in the kvector building method to min "
97 "(degrees). Defaults to 0.5 if option is not selected.")
98 ->check(CLI::NonNegativeNumber)
101 cmd->add_option(
"--kvector-max-distance",
102 opts.kvectorMaxDistance,
103 "Sets the maximum distance max (degrees). Defaults to 15 if option is not "
104 "selected. Should be set to no larger than your camera's FOV, otherwise you're "
105 "just wasting time and space.")
106 ->check(CLI::PositiveNumber)
109 cmd->add_option(
"--kvector-distance-bins",
110 opts.kvectorNumDistanceBins,
111 "Sets the number of distance bins in the kvector building method to num-bins. "
112 "Defaults to 10000 if option is not selected, which is pretty reasonable for "
114 ->check(CLI::PositiveNumber)
119static void AddTetraDatabaseOptions(CLI::App* cmd,
DatabaseOptions& opts) {
120 const std::string group =
"TETRA DATABASE OPTIONS";
122 CLI::Option* tetra = cmd->add_flag(
"--tetra", opts.tetra,
"Generate a Tetra database.")
123 ->disable_flag_override()
125 cmd->add_option(
"--tetra-max-fov",
127 "Sets the maximum field of view for Tetra patterns to fov degrees. All stars "
128 "in a pattern must be within this angle of each other. Should be at least as "
129 "large as the camera's FOV. Defaults to 12.")
130 ->check(CLI::PositiveNumber)
133 cmd->add_option(
"--tetra-edge-ratio-bins",
134 opts.tetraEdgeRatioBins,
135 "Number of bins used to discretize edge ratios when hashing patterns. Higher "
136 "values give finer discretization and fewer hash collisions. Defaults to 50.")
137 ->check(CLI::PositiveNumber)
140 cmd->add_option(
"--tetra-pattern-stars-per-fov",
141 opts.tetraPatternStarsPerFov,
142 "Maximum number of pattern stars allowed within half the FOV of any other "
143 "given pattern star during catalog preprocessing. Be careful adjusting this "
144 "value. Increasing it can cause large growth in database size while lowering "
145 "it risks gaps in sky coverage. Defaults to 10.")
146 ->check(CLI::PositiveNumber)
151static void AddOtherDatabaseOptions(CLI::App* cmd,
DatabaseOptions& opts) {
152 const std::string group =
"OTHER DATABASE OPTIONS";
153 cmd->add_flag(
"--swap-integer-endianness",
154 opts.swapIntegerEndianness,
155 "If true, generate databases with all integer values having opposite endianness "
157 "generating machine. It will not be possible to use the generated databases on "
159 "they were generated on.")
162 "--swap-decimal-endianness",
163 opts.swapDecimalEndianness,
164 "If true, generate databases with all floating point values having opposite endianness "
165 "than the generating machine. It will not be possible to use the generated databases on "
166 "the system they were generated on.")
169 "--output", opts.outputPath,
"The file to output the database to. Defaults to stdout.")
174 AddCatalogNarrowingOptions(cmd, opts);
175 AddKVectorOptions(cmd, opts);
176 AddTetraDatabaseOptions(cmd, opts);
177 AddOtherDatabaseOptions(cmd, opts);
184static CLI::Option* AddCameraOptions(CLI::App* cmd,
PipelineOptions& opts) {
185 const std::string group =
"CAMERA OPTIONS";
187 cmd->add_option(
"--png",
189 "Identify the png image at the given filepath. Can be given several "
190 "times, or with several filepaths, to identify the images in that order.")
192 cmd->add_option(
"--image-dir",
194 "Identify every .png image in the given directory, in order of file name, as "
195 "consecutive frames of one sequence (so zero-pad frame numbers).")
198 cmd->add_option(
"--focal-length",
200 "The focal length of the camera that took the picture (in mm).")
201 ->check(CLI::PositiveNumber)
203 cmd->add_option(
"--pixel-size",
205 "The pixel size of the camera that took the picture (in micrometers).")
206 ->check(CLI::PositiveNumber)
208 cmd->add_option(
"--fov",
210 "The field of view of the camera that took the picture (in degrees). Defaults "
211 "to 20 deg if option is not selected.")
212 ->check(CLI::PositiveNumber)
218 const std::string group =
"CENTROID OPTIONS";
219 CLI::Option* centroidAlgo =
220 cmd->add_option(
"--centroid-algo",
222 "Runs the algo centroiding algorithm. Recognized options are: dummy "
224 "algorithm), cog (center of gravity), and iwcog (iterative weighted center "
226 "If not selected, the centroiding stage is skipped.")
227 ->check(CLI::IsMember({
"dummy",
"cog",
"iwcog"}))
229 cmd->add_option(
"--centroid-dummy-stars",
230 opts.centroidDummyNumStars,
231 "Runs the dummy centroiding algorithm (random centroid algorithm) with "
232 "num-stars stars centroided. Defaults to 5 if option is not selected.")
233 ->check(CLI::NonNegativeNumber)
237 cmd->add_option(
"--centroid-mag-filter",
238 opts.centroidMagFilter,
239 "Will not consider centroids with magnitude below min-mag.")
240 ->needs(centroidAlgo)
243 "--centroid-filter-brightest",
244 opts.centroidFilterBrightest,
245 "Remove all but the brightest num-stars many stars from the list of centroids before "
246 "sending to star-id. Often a better choice than --centroid-mag-filter, because you can "
247 "ensure that you keep enough stars to do star-id. If both this option and "
248 "--centroid-mag-filter are provided, then all stars satisfying both criteria are kept "
250 ->needs(centroidAlgo)
255 const std::string group =
"STAR IDENTIFICATION OPTIONS";
256 cmd->add_option(
"--database",
258 "Chooses filename as the database to use during star identification.")
263 "Runs the algo star identification algorithm. Current options are \"dummy\", \"gv\", "
264 "\"tetra\", and \"py\" (pyramid). If not selected, the star identification stage is "
266 ->check(CLI::IsMember({
"dummy",
"gv",
"py",
"tetra"}))
268 cmd->add_option(
"--angular-tolerance",
269 opts.angularTolerance,
270 "Sets the estimated angular centroiding error tolerance, used in some star id "
271 "algorithms, to tolerance degrees. Defaults to 0.04 degrees.")
272 ->check(CLI::PositiveNumber)
274 cmd->add_option(
"--false-stars-estimate,--false-stars",
275 opts.estimatedNumFalseStars,
276 "num is the estimated number of false stars in the whole sphere for the "
277 "pyramid scheme star identification algorithm. Defaults to 500 if option is "
279 ->check(CLI::NonNegativeNumber)
281 cmd->add_option(
"--max-mismatch-probability,--max-mismatch-prob",
282 opts.maxMismatchProb,
283 "probability is the maximum allowable probability of an incorrect star "
284 "identification, for star id algorithms which support it. Defaults to 0.001.")
285 ->check(CLI::Range(0.0, 1.0))
287 cmd->add_option(
"--tetra-pairing",
288 opts.tetraPairingMode,
289 "Sets the method used to pair observed centroids with catalog stars after a "
290 "Tetra pattern match. Options are \"triad\" (try all 24 permutations, pick the "
291 "one with lowest TRIAD attitude residual) and \"centroid-radius\" (sort by "
292 "distance from pattern centroid, faster but less robust for symmetric "
293 "patterns). Defaults to \"triad\".")
294 ->check(CLI::IsMember({
"triad",
"centroid-radius"}))
296 cmd->add_option(
"--tetra-pattern-search-range",
297 opts.tetraPatternSearchRange,
298 "How far from the observed edge ratios to search when looking up patterns in "
299 "the database. A larger value is more tolerant of centroiding error but slower "
300 "and more likely to produce false matches. Defaults to 0.001.")
301 ->check(CLI::NonNegativeNumber)
303 cmd->add_option(
"--tetra-pattern-match-tolerance",
304 opts.tetraPatternMatchTolerance,
305 "Maximum allowable difference between observed and catalog edge ratios when "
306 "verifying a candidate match from the hash table. Defaults to 0.001.")
307 ->check(CLI::NonNegativeNumber)
315 "Runs the algo algorithm for the attitude stage of the pipeline. Current options are "
316 "\"dqm\" (Davenport Q), \"triad\", and \"quest\". Defaults to dqm.")
317 ->check(CLI::IsMember({
"dqm",
"triad",
"quest"}))
318 ->group(
"ATTITUDE DETERMINATION OPTIONS");
321static void AddImageGenerationOptions(CLI::App* cmd,
PipelineOptions& opts, CLI::Option* png) {
322 const std::string group =
"IMAGE GENERATION OPTIONS";
323 cmd->add_option(
"--generate",
325 "Generates num-images many images. Mutually exclusive with --png and "
327 ->check(CLI::NonNegativeNumber)
329 ->excludes(cmd->get_option(
"--image-dir"))
331 cmd->add_option(
"--generate-x-resolution",
333 "Sets the horizontal resolution of the generated image(s) to pixels. Defaults "
335 ->check(CLI::PositiveNumber)
337 cmd->add_option(
"--generate-y-resolution",
339 "Sets the vertical resolution of the generated image(s) to pixels. Defaults to "
341 ->check(CLI::PositiveNumber)
344 "--generate-zero-mag-photons",
345 opts.generateZeroMagPhotons,
346 "A star with magnitude 0 will cause num-photoelectrons many photoelectrons to "
347 "be received by the sensor per time unit. A default value of 20,000 is chosen. "
348 "See Liebe's, \"tutorial on star tracker accuracy\" for theoretical information "
349 "on how to calculate this.")
350 ->check(CLI::NonNegativeNumber)
352 cmd->add_option(
"--generate-saturation-photons",
353 opts.generateSaturationPhotons,
354 "When a pixel receives at least this many photoelectrons, it will appear "
355 "completely white (at least before other noise is applied). Note that, because "
356 "of noise, a pixel may still appear completely white if it receives less than "
357 "saturation-photoelectrons many photoelectrons.")
358 ->check(CLI::PositiveNumber)
360 cmd->add_option(
"--generate-spread-stddev",
361 opts.generateSpreadStdDev,
362 "Sets the standard deviation of the Gaussian distribution we use to "
363 "approximate the distribution of photons received from each star. Defaults to "
365 ->check(CLI::NonNegativeNumber)
367 cmd->add_option(
"--generate-shot-noise",
368 opts.generateShotNoise,
369 "Enables or disables shot noise simulation in generated images. Defaults to "
372 cmd->add_option(
"--generate-dark-current",
373 opts.generateDarkCurrent,
374 "Set observed brightness of dark current in the image, from 0 (no dark noise) "
375 "to 1 (whole image pure white). Defaults to 0.1. cf --generate-sensitivity to "
376 "control shot noise intensity.")
377 ->check(CLI::Range(0.0, 1.0))
379 cmd->add_option(
"--generate-read-noise-stddev",
380 opts.generateReadNoiseStdDev,
381 "Sets the standard deviation of Gaussian noise in the generated image(s) to "
382 "stddev. Noise is measured in observed brightness, where 1 is the difference "
383 "between pure white and pure black. Defaults to 0.05.")
384 ->check(CLI::NonNegativeNumber)
386 cmd->add_flag(
"--generate-centroids-only",
387 opts.generateCentroidsOnly,
388 "If set (argument is not needed, but can be a bool), will not actually generate "
390 "data -- only centroid positions. Much faster if only evaluating a star-id "
392 "sky coverage testing).")
395 const std::string attitudeDesc =
396 "Set the right ascension, declination, and roll of the generated image.";
397 cmd->add_option(
"--generate-ra", opts.generateRa, attitudeDesc)->group(group);
398 cmd->add_option(
"--generate-de", opts.generateDe, attitudeDesc)->group(group);
399 cmd->add_option(
"--generate-roll", opts.generateRoll, attitudeDesc)->group(group);
400 cmd->add_flag(
"--generate-random-attitudes",
401 opts.generateRandomAttitudes,
402 "Generate a random attitude for each generated image. Ignores specified "
403 "ra, de, and roll if set.")
406 cmd->add_option(
"--generate-exposure",
407 opts.generateExposure,
408 "Controls the exposure time of generated images. Default is 0.2. "
409 "Affects both motion blur and number of photons received per star.")
410 ->check(CLI::NonNegativeNumber)
413 const std::string blurDesc =
414 "Set the motion blur direction. By default, there is no motion blur (i.e., all of these "
416 cmd->add_option(
"--generate-blur-ra", opts.generateBlurRa, blurDesc)->group(group);
417 cmd->add_option(
"--generate-blur-de", opts.generateBlurDe, blurDesc)->group(group);
418 cmd->add_option(
"--generate-blur-roll", opts.generateBlurRoll, blurDesc)->group(group);
421 "--generate-readout-time",
422 opts.generateReadoutTime,
423 "Rolling shutter readout time for generated images. This is the time it takes from "
424 "starting to capture the first row until finishing capturing the last row. Defaults to "
426 "(rolling shutter simulation disabled).")
427 ->check(CLI::NonNegativeNumber)
429 cmd->add_option(
"--generate-false-stars",
430 opts.generateNumFalseStars,
431 "The number of false stars generated. All are placed uniformly randomly "
432 "around the celestial sphere. Defaults to 0 (no false stars generated)")
433 ->check(CLI::NonNegativeNumber)
435 cmd->add_option(
"--generate-false-min-mag",
436 opts.generateFalseMinMag,
437 "The minimum (weakest) magnitude that generated false stars should have. "
440 cmd->add_option(
"--generate-false-max-mag",
441 opts.generateFalseMaxMag,
442 "The maximum (strongest) magnitude that generated false stars should have. "
445 cmd->add_option(
"--generate-perturb-centroids",
446 opts.generatePerturbationStddev,
447 "Introduce artificial centroiding error. If provided, all the input and "
448 "expected centroids "
449 "will be shifted randomly according to a 2D Gaussian distribution with the "
451 "deviation (defaults to 0.2 pixel stddev). For evaluating star-id performance "
454 ->check(CLI::NonNegativeNumber)
457 "--generate-cutoff-mag",
458 opts.generateCutoffMag,
459 "When evaluating star-id algos on generated images, we don't want every single catalog "
460 "star in the FOV to be fed into the star-id algorithm. This option lets you control "
461 "that! Every catalog star has some probability of being turned into an input centroid, "
462 "and this specifies the magnitude that will have a 50% probability of being included in "
463 "the input centroid list. An overly complicated mathematical function determines how "
464 "that probability changes as you increase and decrease the magnitude from there, but it "
465 "falls to 0 or 1 pretty quickly at either side.\n"
466 "Set to a value of 100 or greater to disable cutoff and include all centroids.")
468 cmd->add_option(
"--generate-oversampling",
469 opts.generateOversampling,
470 "Perform num-samples many samples per pixel when generating images. "
471 "Effectively performs antialiasing. num-samples must be a perfect square. "
474 cmd->add_option(
"--generate-seed",
476 "An integer seed to pass to the random number generator used during image "
479 cmd->add_flag(
"--generate-time-based-seed",
481 "If set, uses the current timestamp as a random seed. "
482 "--generate-seed is ignored if time based seed is set.")
486static void AddComparatorOptions(CLI::App* cmd,
PipelineOptions& opts) {
487 const std::string group =
"COMPARATOR OPTIONS";
488 auto addOutput = [&](
const std::string& name, std::string& variable,
const std::string& desc) {
489 AddOutputPathOption(cmd, name, variable, desc)->group(group);
492 addOutput(
"--plot-raw-input",
494 "Argument is optional. Plots raw BW input image to PNG. Prints to path. Defaults to "
496 addOutput(
"--plot-input",
498 "Argument is optional. Plots annotated input image to PNG. Prints to path. Defaults "
500 addOutput(
"--plot-expected",
502 "Argument is optional. Plots annotated \"expected\" image to PNG. The difference "
503 "between \"expected\" and \"input\" is that \"input\" is what's passed to the actual "
504 "algorithms, while \"expected\" is compared against the actual output of the "
505 "algorithms for evaluation purposes.");
506 addOutput(
"--plot-output",
508 "Argument is optional. Plot output to PNG. Prints to path. Defaults to stdout.");
509 addOutput(
"--plot-centroid-indices",
510 opts.plotCentroidIndices,
511 "Mainly for debugging. Argument is optional. Plot output to PNG, but instead of "
512 "labeling the stars with the catalog star they were identified as, labels them with "
513 "their centroid index.\n"
514 "If a centroid algo was provided, prints those indices. Otherwise, prints the "
515 "\"input centroid\" indices, which is whatever would be passed to the star-id algo "
516 "(so for generated images, after perturbations and magnitude cutoff is applied).");
517 addOutput(
"--print-actual-centroids",
518 opts.printActualCentroids,
519 "Argument is optional. Print list of centroids in the pipeline output to path. If "
520 "star identification was also performed, print which catalog star each centroid was "
521 "identified as. If input is from a generated image, also print the expected id for "
522 "each centroid (note that there can sometimes be multiple acceptable star-ids for a "
523 "star, if it's within the centroid comparison threshold of multiple catalog stars. "
524 "Usually setting --min-separation sufficiently high prevents this). Defaults to "
526 addOutput(
"--print-input-centroids",
527 opts.printInputCentroids,
528 "Argument is optional. Print list of centroids in the pipeline input to path. This "
529 "only works for generated images. Prints whatever centroids would normally be sent "
530 "to the star-id algorithm if provided in the pipeline. Also prints star-ids, but "
531 "don't rely on them, because if the input centroids were perturbed the generated "
532 "star-id may not actually be the closest catalog star anymore! Defaults to stdout.");
533 addOutput(
"--print-expected-centroids",
534 opts.printExpectedCentroids,
535 "Argument is optional. Print list of \"expected\" centroids from the pipeline input "
536 "to path. The \"expected\" centroids are all centroids used to generate the real "
537 "image, including false stars and stars below the cutoff magnitude. Also prints out "
538 "expected star identifications for those stars. This only works for generated "
539 "images. Generally you should use --print-actual-centroids instead, and use "
540 "--compare-centroids if you need to compare actual and expected centroids.");
541 addOutput(
"--print-attitude",
543 "Argument is optional. Print the determined right ascension, declination, and roll "
544 "to path. TODO: Option to print as quaternion. Defaults to stdout.");
545 addOutput(
"--print-expected-attitude",
546 opts.printExpectedAttitude,
547 "Argument is optional. Print the expected right ascension, declination, and roll to "
548 "path. Only works for generated images. Defaults to stdout.");
549 addOutput(
"--print-speed",
551 "Print the average, min, max, and upper 95th percentile of how long each stage of "
552 "the pipeline took to run.");
554 "--compare-centroids",
555 opts.compareCentroids,
556 "Argument is optional. Compare expected to actual centroids. Prints to path. Defaults "
558 addOutput(
"--compare-star-ids",
560 "Argument is optional. Compare expected to actual star identifiers. Prints to path. "
561 "Defaults to stdout. In the output, starid_num_correct, starid_num_incorrect, and "
562 "starid_num_total count the number of individual stars identified in an image. The "
563 "starid_num_images_correct and starid_num_images_incorrect outputs are more "
564 "aggregated: starid_num_images_correct records the number of images where at least "
565 "two stars were correctly id'd and no stars were incorrectly id'd, while "
566 "starid_num_images_incorrect records the number of images with at least one "
567 "incorrectly id'd star (used when generating more than 1 image at a time, eg for "
569 addOutput(
"--compare-attitudes",
570 opts.compareAttitudes,
571 "Argument is optional. Compare expected to actual attitude. Prints to path. Defaults "
574 cmd->add_option(
"--centroid-compare-threshold",
575 opts.centroidCompareThreshold,
576 "Sets the threshold (in pixels) to consider two centroids equal (cf "
577 "--compare-centroids).")
578 ->check(CLI::NonNegativeNumber)
580 cmd->add_option(
"--attitude-compare-threshold",
581 opts.attitudeCompareThreshold,
582 "Sets the threshold (in degrees) to consider two attitudes equal (cf "
583 "--compare-attitudes).")
584 ->check(CLI::NonNegativeNumber)
589 CLI::Option* png = AddCameraOptions(cmd, opts);
590 AddCentroidOptions(cmd, opts);
591 AddStarIdOptions(cmd, opts);
592 AddAttitudeOptions(cmd, opts);
593 AddImageGenerationOptions(cmd, opts, png);
594 AddComparatorOptions(cmd, opts);
597static int LostMain(
int argc,
char** argv) {
598 CLI::App app{
"LOST: Open-source Star Tracker"};
599 argv = app.ensure_utf8(argv);
600 app.require_subcommand(0, 1);
601 app.option_defaults()->always_capture_default();
604 CLI::App* dbCmd = app.add_subcommand(
"database",
"Build a star database");
605 AddDatabaseOptions(dbCmd, dbOptions);
608 CLI::App* pipelineCmd = app.add_subcommand(
"pipeline",
"Run a star-tracking pipeline");
609 AddPipelineOptions(pipelineCmd, pipelineOptions);
611 CLI11_PARSE(app, argc, argv);
613 if (app.got_subcommand(pipelineCmd)) {
614 PipelineRun(pipelineOptions);
615 }
else if (app.got_subcommand(dbCmd)) {
616 DatabaseBuild(dbOptions);
618 std::cout << app.help() << std::endl;
626int main(
int argc,
char** argv) {
627 return lost::LostMain(argc, argv);
Command line options when using the database command.
The command line options passed when running a pipeline.
A set of algorithms that describes all or part of the star-tracking "pipeline".
An output stream which might be a file or stdout.
#define MULTI_DB_FLOAT_FLAG
Stores "inner angles" between star triples.
int main(int argc, char **argv)
const Catalog & CatalogRead()
Read and parse the full catalog from disk. If called multiple times, will re-use the first result.
decimal DegToRad(decimal deg)
std::vector< MultiDatabaseEntry > MultiDatabaseDescriptor
Catalog NarrowCatalog(const Catalog &catalog, int maxMagnitude, int maxStars, decimal minSeparation)
Remove unwanted stars from an unfiltered catalog.
MultiDatabaseDescriptor GenerateDatabases(const Catalog &catalog, const DatabaseOptions &values)
Appropriately create descriptors for all requested databases according to command-line options.
SerializeContext serFromDbValues(const DatabaseOptions &values)
std::vector< std::unique_ptr< PipelineInput > > PipelineInputList
PipelineInputList GetPipelineInput(const PipelineOptions &values)
Come up with a list of pipeline inputs based on command line options.
void SerializeMultiDatabase(SerializeContext *ser, const MultiDatabaseDescriptor &dbs, uint32_t flags)
void PipelineComparison(const PipelineInputList &expected, const std::vector< PipelineOutput > &actual, const PipelineOptions &values)
Print or otherwise analyze the results of (perhaps multiple) runs of a star tracking pipeline.
Pipeline SetPipeline(const PipelineOptions &values)
Create a pipeline from command line options.
std::vector< CatalogStar > Catalog